Repository guide · getting started · v1
karpathy / nanochat · Getting started
This repository is a Python, MIT-licensed project that its author describes as a low-cost ChatGPT-style system. Its pyproject.toml lists runtime dependencies, including torch pinned exactly at 2.9.1. Seven files carry a __main__ guard. This analysis does not verify installation or run commands.
- Original repository
- karpathy/nanochat
- License
- MIT · open-source license
- Analyzed revision · last verified
- 92d63d4e8bb4df75c3b71618f31ddde2378b2bcd ·
Getting started with karpathy/nanochat: manifests and entrypoints
Terms used on this page
- Entrypoint record
- A file the analyzer marks as a place where execution can start. When it carries a __main__ guard excerpt, the file contains an if __name__ == "__main__": block and the excerpt shows what that block calls; without an excerpt, the file was flagged by its name only.
- Bounded static execution path
- A call chain reconstructed from the source code without running it, stopped after a fixed number of steps. It shows how far the code can be followed on paper, not what happens at run time.
- Unresolved boundary
- Where a static path stops because the next call goes into an external library or cannot be resolved without running the code. It marks the edge of this analysis, not a defect in the repository.
- Static relations
- Calls and imports found in the source. "External or unresolved" relations point outside the analyzed files.
- Module role
- The analyzer's label for a file, inferred from how many calls go in and out (for example core, entry/orchestration, leaf). It describes a position in the call graph, not the authors' design.
- Test-like files
- Files whose names or locations look like tests. This analysis counts them; it does not run them.
- Observed · inferred · author-claimed · unresolved
- How each statement is supported: read directly from the analyzed files; derived by the analyzer from them; stated by the repository's authors (metadata, README); or not established by this analysis.
- Verified
- Two uses on these pages. In an analyzer record ("verified provenance", "a verified entrypoint") it means the record was read directly from the analyzed files, which these guides call observed; for an entrypoint, the __main__ guard text is present. Since the analyzer fix of 2026-10-04, a file that only has an entrypoint-like name such as cli.py or main.py is recorded as inferred; guides analyzed before that still call such a file verified, and it is still only a guess about how the file is used. It does not mean the code was run or tested. "Last verified" is the date the guide last passed the lab's checks against the analysis record of the stated revision; it is not a review of the repository itself.
What you are looking at
The repository's platform description presents it as a ChatGPT-style system that fits a budget of about $100. That is the author's own framing, and this analysis does not check it. The homepage field is empty, and no topics are set.
- Language: Python is the primary language. GitHub reports roughly 355 kB of Python, 88 kB of Jupyter Notebook and 15 kB of Shell.
- License: MIT, reported both by the GitHub API and from a
LICENSEfile in the repository. - Releases: none published.
- Size signals: the analyzer counted 53 files and 2803 static relation edges. It inferred a Python project organized around
dev,nanochat,runsandscripts. - Attention: 60,579 stargazers at the time of the metadata snapshot.
What it needs
All 16 dependency records come from pyproject.toml. The analyzer summary counts this as the single manifest.
- Runtime: filelock >=3.19.0, kernels >=0.11.7, numpy >=1.26.0, psutil >=7.1.0, pyarrow >=21.0.0, rustbpe >=0.1.0, tiktoken >=0.11.0, torch ==2.9.1 (an exact pin) and wandb >=0.21.3.
- Optional: setuptools >=65.0.0, plus two more torch ==2.9.1 records. Both point at the same line as the runtime torch entry.
- Dev: ipykernel >=7.1.0, matplotlib >=3.10.8, pytest >=8.0.0 and python-dotenv >=1.2.1.
Version constraints are recorded as written. Manifests such as setup.py, setup.cfg, Pipfile and lock files are not parsed, so anything they declare is missing from this list. The packet does not name the optional dependency groups. No citable packet record establishes required hardware or a Python version.
How it starts
There are seven entrypoint records, and each is a file with a __main__ guard: nanochat/dataset.py, nanochat/engine.py, scripts/base_eval.py, scripts/chat_eval.py, scripts/infer_bench.py, tasks/common.py and tests/test_attention_fallback.py.
scripts/base_eval.pyandscripts/infer_bench.py: the guard only callsmain().nanochat/dataset.py: the guard builds an argument parser described as downloading pretraining dataset shards. It has options for the number of files and parallel workers.scripts/chat_eval.py: the guard parses a required model source (sft or rl) and an optional task name.nanochat/engine.py,tasks/common.pyandtests/test_attention_fallback.py: the guards hold quick self-checks. They compare two generate functions, load an MMLU subset, and print PyTorch and CUDA details.
The analyzer marks the dataset, engine and three script files as likely entrypoints. It reports 81 bounded execution paths; 5 are listed. All five start in nanochat/dataset.py, reach get_base_dir in nanochat/common.py, and stop at unresolved standard-library calls. Runtime behaviour beyond these records is not established.
Where to look first
The analyzer flags README.md, pyproject.toml and LICENSE as project-level important files.
Its learning-path suggestion has three steps:
- start with the manifests and important symbols;
- trace the bounded execution path;
- inspect unresolved boundaries before changing code.
Its modify guide names tasks/common.py as the place to begin modification analysis. Downstream effects are to be checked by hand.
Top-level layout by file count: nanochat 14, scripts 9, dev 7, tasks 6, tests 6, runs 4, the root 6 and .claude 1.
Tests exist. The analyzer counts 6 test-like files, and pytest appears among the dev dependencies.
What this analysis cannot tell you
- Commands: install, run and build inference is partial, and installation commands are not verified. None are given here.
- Manifests: only requirements files, package.json and pyproject.toml formats are read. setup.py, setup.cfg, Pipfile and lock files are not parsed.
- README: claim extraction is line-based and skips code blocks, tables and similar content. Anything from the README stays author-claimed at most.
- Static only: reflection, dynamic imports, monkey-patching, dynamic dispatch and runtime framework wiring are not resolved. Files over 400 kB, minified bundles and vendored directories are inventoried but not parsed.
- Inconsistencies: one teaching claim says no bounded execution path is available, yet the analyzer reports 81 and lists 5. The overview teaching claim names
tasks/common.pyas a starting point, while the repository summary namesnanochat/dataset.py.
What this analysis could not establish
The writing model's own notes on the analysis record. Identifiers such as lim_3, exec_* or claim_… name records of that analysis; the claims table cites the same records.
- A uv.lock file appears in the inventory, but lock files are not parsed, so its pinned versions are unknown.
- The analyzer reports 2223 static relations that remain external or unresolved.
- Torch is recorded three times at the same manifest line under runtime and optional scopes; the optional group names are not in the packet.
- Shell appears in the language bytes, but no shell entrypoint records exist, so the role and location of shell code are not established.
- The contents and purpose of the .claude and dev directories are not described by any packet record.
- The platform description uses superlative marketing wording; it has been paraphrased and is not treated as fact.
Claims and evidence — 33 claims, 33 supported by an independent verifier
Every substantive statement above is a claim bound to grounding IDs of the analyzed revision. Global grounding IDs are namespaced by the analysis run.
| Claim | Epistemic status | Verifier | Grounding (global IDs) |
|---|---|---|---|
| c1 The platform description presents the project as a ChatGPT-style system that fits a budget of about $100; this is the author's framing and is not checked by this analysis. | author_claimed | supported | analysis_50dfee49d6903e32:meta_description |
| c2 The repository's homepage metadata field is empty. | author_claimed | supported | analysis_50dfee49d6903e32:meta_homepage |
| c3 No topics are set in the repository's platform metadata. | observed | supported | analysis_50dfee49d6903e32:meta_topics |
| c4 Python is the primary language; GitHub reports about 355 kB of Python, 88 kB of Jupyter Notebook and 15 kB of Shell. | observed | supported | analysis_50dfee49d6903e32:meta_primary_language, analysis_50dfee49d6903e32:meta_language_bytes |
| c5 The license is MIT, reported by the GitHub API and a repository file, and LICENSE is a project-level important file. | observed | supported | analysis_50dfee49d6903e32:meta_license, analysis_50dfee49d6903e32:important_3 |
| c6 No release has been published. | observed | supported | analysis_50dfee49d6903e32:meta_latest_release |
| c7 The analyzer counted 53 files and 2803 static relation edges and inferred a Python project organized around dev, nanochat, runs and scripts. | inferred | supported | analysis_50dfee49d6903e32:summary_repository |
| c8 The repository had 60,579 stargazers at the time of the metadata snapshot. | observed | supported | analysis_50dfee49d6903e32:meta_stars |
| c9 All 16 dependency records come from pyproject.toml, which the analyzer summary counts as the single manifest. | inferred | supported | analysis_50dfee49d6903e32:dep_1, analysis_50dfee49d6903e32:dep_2, analysis_50dfee49d6903e32:dep_3, analysis_50dfee49d6903e32:dep_4, analysis_50dfee49d6903e32:dep_5, analysis_50dfee49d6903e32:dep_6, analysis_50dfee49d6903e32:dep_7, analysis_50dfee49d6903e32:dep_8, analysis_50dfee49d6903e32:dep_9, analysis_50dfee49d6903e32:dep_10, analysis_50dfee49d6903e32:dep_11, analysis_50dfee49d6903e32:dep_12, analysis_50dfee49d6903e32:dep_13, analysis_50dfee49d6903e32:dep_14, analysis_50dfee49d6903e32:dep_15, analysis_50dfee49d6903e32:dep_16, analysis_50dfee49d6903e32:summary_repository |
| c10 Runtime dependencies: filelock >=3.19.0, kernels >=0.11.7, numpy >=1.26.0, psutil >=7.1.0, pyarrow >=21.0.0, rustbpe >=0.1.0, tiktoken >=0.11.0, torch ==2.9.1 and wandb >=0.21.3. | observed | supported | analysis_50dfee49d6903e32:dep_1, analysis_50dfee49d6903e32:dep_2, analysis_50dfee49d6903e32:dep_3, analysis_50dfee49d6903e32:dep_4, analysis_50dfee49d6903e32:dep_5, analysis_50dfee49d6903e32:dep_6, analysis_50dfee49d6903e32:dep_7, analysis_50dfee49d6903e32:dep_8, analysis_50dfee49d6903e32:dep_9 |
| c11 Optional-scope records are setuptools >=65.0.0 and two torch ==2.9.1 records at line 15, the same line as the runtime torch record. | observed | supported | analysis_50dfee49d6903e32:dep_10, analysis_50dfee49d6903e32:dep_11, analysis_50dfee49d6903e32:dep_12, analysis_50dfee49d6903e32:dep_8 |
| c12 Dev-scope dependencies are ipykernel >=7.1.0, matplotlib >=3.10.8, pytest >=8.0.0 and python-dotenv >=1.2.1. | observed | supported | analysis_50dfee49d6903e32:dep_13, analysis_50dfee49d6903e32:dep_14, analysis_50dfee49d6903e32:dep_15, analysis_50dfee49d6903e32:dep_16 |
| c13 Version constraints are recorded as written; setup.py, setup.cfg, Pipfile and lock files are not parsed. | observed | supported | analysis_50dfee49d6903e32:lim_3a |
| c14 The packet does not name the optional dependency groups. No citable packet record establishes required hardware or a Python version. | unresolved | supported | analysis_50dfee49d6903e32:dep_10, analysis_50dfee49d6903e32:dep_11, analysis_50dfee49d6903e32:dep_12 |
| c15 Seven entrypoint records exist, each a file with a __main__ guard: nanochat/dataset.py, nanochat/engine.py, scripts/base_eval.py, scripts/chat_eval.py, scripts/infer_bench.py, tasks/common.py and tests/test_attention_fallback.py. | observed | supported | analysis_50dfee49d6903e32:py_entry_6f78b0b1883f, analysis_50dfee49d6903e32:py_entry_d1f565fa3410, analysis_50dfee49d6903e32:py_entry_4e39b6126807, analysis_50dfee49d6903e32:py_entry_269c07384799, analysis_50dfee49d6903e32:py_entry_405999f52cfe, analysis_50dfee49d6903e32:py_entry_21a180b9528c, analysis_50dfee49d6903e32:py_entry_9395ac6dfb21 |
| c16 The __main__ guards of scripts/base_eval.py and scripts/infer_bench.py only call main(). | observed | supported | analysis_50dfee49d6903e32:py_entry_4e39b6126807, analysis_50dfee49d6903e32:py_entry_405999f52cfe |
| c17 The nanochat/dataset.py guard builds an argument parser described as downloading pretraining dataset shards, with options for number of files and parallel workers. | observed | supported | analysis_50dfee49d6903e32:py_entry_6f78b0b1883f |
| c18 The scripts/chat_eval.py guard parses a required model source (sft or rl) and an optional task name. | observed | supported | analysis_50dfee49d6903e32:py_entry_269c07384799 |
| c19 The guards in nanochat/engine.py, tasks/common.py and tests/test_attention_fallback.py hold quick checks: comparing two generate functions, loading an MMLU subset, and printing PyTorch and CUDA details. | observed | supported | analysis_50dfee49d6903e32:py_entry_d1f565fa3410, analysis_50dfee49d6903e32:py_entry_21a180b9528c, analysis_50dfee49d6903e32:py_entry_9395ac6dfb21 |
| c20 The analyzer marks nanochat/dataset.py, nanochat/engine.py, scripts/base_eval.py, scripts/chat_eval.py and scripts/infer_bench.py as important because they are likely entrypoints. | observed | supported | analysis_50dfee49d6903e32:important_4, analysis_50dfee49d6903e32:important_5, analysis_50dfee49d6903e32:important_6, analysis_50dfee49d6903e32:important_7, analysis_50dfee49d6903e32:important_8 |
| c21 The analyzer reports 81 bounded execution paths; 5 are listed, all from nanochat/dataset.py, reaching get_base_dir in nanochat/common.py and stopping at unresolved os.environ.get, os.path.expanduser or os.path.join calls. | inferred | supported | analysis_50dfee49d6903e32:exec_de60eb0f815c, analysis_50dfee49d6903e32:exec_270399b88681, analysis_50dfee49d6903e32:exec_bebf565646e1, analysis_50dfee49d6903e32:exec_9b057297bbd5, analysis_50dfee49d6903e32:exec_6fe58885bff5, analysis_50dfee49d6903e32:summary_repository |
| c22 Runtime behaviour beyond these records is not established, because analysis is static only and run inference is partial. | observed | supported | analysis_50dfee49d6903e32:lim_1, analysis_50dfee49d6903e32:lim_2 |
| c23 README.md, pyproject.toml and LICENSE are flagged as project-level important files. | observed | supported | analysis_50dfee49d6903e32:important_1, analysis_50dfee49d6903e32:important_2, analysis_50dfee49d6903e32:important_3 |
| c24 The analyzer's learning path suggests starting with manifests and important symbols, then tracing the bounded execution path and inspecting unresolved boundaries before changing code. | inferred | supported | analysis_50dfee49d6903e32:claim_e56db45165bf |
| c25 The analyzer's modify guide points to tasks/common.py as the place to begin modification analysis, with downstream effects to be verified manually. | inferred | supported | analysis_50dfee49d6903e32:claim_0fee32387cf9 |
| c26 Top-level file counts: nanochat 14, scripts 9, dev 7, tasks 6, tests 6, runs 4, root 6 and .claude 1. | inferred | supported | analysis_50dfee49d6903e32:summary_repository |
| c27 The analyzer counts 6 test-like files, and pytest is listed as a dev dependency. | inferred | supported | analysis_50dfee49d6903e32:summary_repository, analysis_50dfee49d6903e32:dep_15 |
| c28 Install, run and build inference is partial, and installation commands are not verified. | observed | supported | analysis_50dfee49d6903e32:lim_2 |
| c29 Dependency records come only from requirements files, package.json and pyproject.toml; setup.py, setup.cfg, Pipfile and lock files are not parsed. | observed | supported | analysis_50dfee49d6903e32:lim_3a |
| c30 README claim extraction is line-based, skips fenced code, tables and similar, and README claims remain author-claimed at best. | observed | supported | analysis_50dfee49d6903e32:lim_4a |
| c31 Reflection, dynamic imports, monkey-patching, dynamic dispatch and runtime framework wiring are not resolved; files over 400 kB, minified bundles and vendored directories are inventoried but not parsed. | observed | supported | analysis_50dfee49d6903e32:lim_1, analysis_50dfee49d6903e32:lim_6 |
| c32 One teaching claim says no bounded execution path is available, which conflicts with the analyzer's report of 81 paths and the listed path records. | inferred | supported | analysis_50dfee49d6903e32:claim_4d30ade3e21e, analysis_50dfee49d6903e32:summary_repository, analysis_50dfee49d6903e32:exec_de60eb0f815c |
| c33 The overview teaching claim names tasks/common.py as a starting point, while the repository summary names nanochat/dataset.py. | inferred | supported | analysis_50dfee49d6903e32:claim_39fa81e523b3, analysis_50dfee49d6903e32:summary_repository |
Sources, rights and disclosure · attribution-license-templates/v0.1
Rights notice. Original repository hosted on GitHub. Repository source code, documentation, names, media, and related project materials remain subject to the rights of their respective authors, contributors, and other rights holders and to applicable repository license terms.
Platform notice. GitHub is the source hosting platform for the linked repository. GitHub and related marks are trademarks of GitHub, Inc. EVEMISS Technology is not affiliated with or endorsed by GitHub unless explicitly stated otherwise.
How this page is produced. This page was produced using revision-aware repository analysis and AI-assisted editorial tooling. Technical claims are tied to the analyzed repository revision and may be revalidated when the source repository changes.
AI-assisted analysis. Reviewed by EVEMISS Technology through human–AI collaborative review. · Report a rights concern · Back to the overview