Repository guide · source walkthrough · v1
karpathy / nanochat · Source walkthrough
A reading order for this Python repository at the analyzed revision. Start with file-level blocks, then follow the dataset.py guard into get_base_dir. Next, read the most connected library modules. Finish with the coupling points around print0, Engine.generate and two script main functions. Every block description is a static inference.
- Original repository
- karpathy/nanochat
- License
- MIT · open-source license
- Analyzed revision · last verified
- 92d63d4e8bb4df75c3b71618f31ddde2378b2bcd ·
karpathy/nanochat source walkthrough: a static reading order
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.
How to use this walkthrough
This walkthrough has four stops that follow the analyzer's own lessons: orientation, execution story, core code and change guide. It ends with a note on what it cannot show. Every line range below is a block's own lines value and refers to the files of the analyzed revision, so open that revision when reading. A block is the analyzer's line-addressable unit: a whole module, a function, a class, a direct-execution guard or a smaller control-flow region. Each block description here is the analyzer's inference and carries a confidence score. The analysis counts 908 blocks, and only a small selection appears below.
Stop 1: Orientation
Start with the six file-level blocks of the orientation lesson. The analyzer describes each one only generically, as the file-level container for the analyzed code in that file, so these blocks show where to look rather than what the code does. Each of the six files also has a detected __main__ entrypoint guard.
nanochat/dataset.py:1-160: modulenanochat/dataset.py; file-level container, library code (confidence 0.76).nanochat/engine.py:1-352: modulenanochat/engine.py; file-level container, library code (0.76).tasks/common.py:1-222: moduletasks/common.py; file-level container, library code (0.76).scripts/base_eval.py:1-243: modulescripts/base_eval.py; file-level container, script (0.9).scripts/chat_eval.py:1-240: modulescripts/chat_eval.py; file-level container, script (0.76).scripts/infer_bench.py:1-246: modulescripts/infer_bench.py; file-level container, script (0.9).
Stop 2: Execution story
The execution story starts at the direct-execution guard of nanochat/dataset.py and goes one step into nanochat/common.py. The analyzer recorded 81 bounded paths. The five shown to this walkthrough all go from that entrypoint to get_base_dir and end at an unresolved boundary in os.environ.get, os.path.expanduser or os.path.join. One analyzer teaching claim says no bounded static execution path is available. That conflicts with the listed paths, and the packet does not establish which statement holds.
nanochat/dataset.py:136-160: main_guard__main__; gates code that runs when the file is executed directly rather than imported (confidence 0.99).nanochat/dataset.py:1-160: modulenanochat/dataset.py; the file-level container for this file (0.76).nanochat/common.py:71-80: functionget_base_dir, signaturedef get_base_dir():; the analyzer reads it as encapsulating an operation with 6 downstream call or import relations (0.76).
Stop 3: Core code
All eight blocks of the analyzer's core-code lesson lie in library code. Five of them appear in other stops or in the reading set below. The remaining three are:
nanochat/optim.py:112-180: functionmuon_step_fused; encapsulates an operation with 42 downstream call or import relations (0.76).nanochat/core_eval.py:168-241: functionevaluate_example; operation with 34 relations (0.76).nanochat/loss_eval.py:9-65: functionevaluate_bpb; operation with 28 relations (0.76).
The library reading set below is the AI Frontier lab's selection by static call degree, not an analyzer lesson. It covers the four most connected library modules, each with its two longest class or function blocks.
nanochat/common.py: leaf/data-boundary candidate, with 143 incoming and 0 outgoing calls.
nanochat/common.py:228-279: functionget_peak_flops; operation with 5 downstream relations.nanochat/common.py:281-328: functionget_peak_bandwidth; operation with 4 downstream relations.
nanochat/engine.py: entry/orchestration candidate, with 17 incoming and 3 outgoing calls.
nanochat/engine.py:169-299: classEngine; groups related behavior under one class boundary (0.97).nanochat/engine.py:176-275: functionEngine.generate; operation with 43 downstream relations.
nanochat/checkpoint_manager.py: service/core candidate, with 12 incoming and 6 outgoing calls.
nanochat/checkpoint_manager.py:76-114: functionbuild_model; operation with 19 downstream relations.nanochat/checkpoint_manager.py:173-193: functionload_optimizer_state; operation with 10 downstream relations.
tasks/common.py: entry/orchestration candidate, with 16 incoming calls and 1 outgoing call.
tasks/common.py:85-126: classTask; groups related behavior under one class boundary (0.99).tasks/common.py:45-82: functionload_hub_dataset; operation with 27 downstream relations.
Stop 4: Where changes ripple
The change-guide lesson lists six blocks where the static graph shows stronger coupling. Four lie in library code. Three of those are in and around print0 in nanochat/common.py, a module the analyzer counts 143 incoming calls into. The two blocks with the largest relation counts are main functions in scripts, so that part of the coupling signal comes from tooling code rather than the library.
nanochat/common.py:118-121: functionprint0; operation with 3 downstream call or import relations (0.76).nanochat/common.py:119-119: straight_line region insideprint0; adjacent sequential statements grouped as one bounded region.nanochat/common.py:120-121: if block insideprint0; selects between control-flow paths by a condition in this region.nanochat/engine.py:176-275: functionEngine.generate; operation with 43 downstream relations.scripts/infer_bench.py:97-243: functionmain; operation with 80 downstream relations, script code.scripts/base_eval.py:128-239: functionmain; operation with 61 downstream relations, script code.
What this walkthrough cannot show
This walkthrough inherits the analyzer's limits. The analysis is static only, so it does not resolve reflection, runtime dependency injection, dynamic imports, monkey-patching, generated code, framework runtime wiring or dynamic dispatch. Every listed execution path ends at an external or unresolved call, so runtime behavior past that point is not shown. Install, run and build inference is partial and installation commands are not verified, so no commands are given here. Files over 400 kB, minified bundles and vendored directories are inventoried but not parsed, and relation extraction is capped per file and per repository. Block descriptions are inferences; the blocks named here carry confidence scores from 0.76 to 0.99. The analyzer's uncertainties lesson lists no blocks. Its teaching note says static analysis cannot establish all dynamic dispatch, reflection, generated-code or runtime framework behavior.
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.
- The teaching claim stating that no bounded static execution path is available contradicts the 81 bounded paths reported elsewhere in the packet; which statement holds is not established.
- The analyzer reports 2223 static relations that remain external or unresolved; the downstream relation counts per block do not say how many of those relations resolve locally.
- One teaching claim names tasks/common.py as a detected starting point, while the analyzer's purpose summary names nanochat/dataset.py; the packet does not rank them.
- The symbol records for evaluate_example and evaluate_bpb have no signature, so their parameters are not shown here.
- Only 23 of 908 blocks appear in the lessons, so large parts of the code, for example the scripts/base_train.py orchestration candidate, have no block-level guidance in this walkthrough.
Claims and evidence — 31 claims, 31 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 walkthrough's four stops follow the analyzer's lessons for orientation, execution story, core code and change guide, followed by a note on limits. | inferred | supported | analysis_50dfee49d6903e32:block_df3165c373085a, analysis_50dfee49d6903e32:block_3b159c33fe914a, analysis_50dfee49d6903e32:block_c8196da74438a6, analysis_50dfee49d6903e32:block_a1abd4609abe14 |
| c2 Each stated line range is the block's own lines value in the analyzed revision's files; a block is the analyzer's line-addressable unit, such as a module, function, class, guard or smaller control-flow region. | inferred | supported | analysis_50dfee49d6903e32:block_df3165c373085a, analysis_50dfee49d6903e32:block_c7448be3e775ff, analysis_50dfee49d6903e32:block_8edeafce1e8c31, analysis_50dfee49d6903e32:block_3b159c33fe914a, analysis_50dfee49d6903e32:block_df1b86af2cd9c6 |
| c3 Block descriptions are the analyzer's inferences and each carries a confidence score. | inferred | supported | analysis_50dfee49d6903e32:block_c7448be3e775ff, analysis_50dfee49d6903e32:block_3b159c33fe914a |
| c4 The analysis reports 908 line-addressable semantic code blocks; this walkthrough names only a small selection of them. | inferred | supported | analysis_50dfee49d6903e32:summary_repository |
| c5 The orientation lesson consists of six file-level module blocks, which the analyzer describes generically as the file-level container for each analyzed source file. | inferred | supported | analysis_50dfee49d6903e32:block_df3165c373085a, analysis_50dfee49d6903e32:block_6ece4b993038d1, analysis_50dfee49d6903e32:block_625c1c9334b2fd, analysis_50dfee49d6903e32:block_9ca9430ebe5293, analysis_50dfee49d6903e32:block_f5d08a9df2b10b, analysis_50dfee49d6903e32:block_17abd485dd7278 |
| c6 Three orientation blocks lie in library code: nanochat/dataset.py:1-160, nanochat/engine.py:1-352 and tasks/common.py:1-222, each at confidence 0.76. | inferred | supported | analysis_50dfee49d6903e32:block_df3165c373085a, analysis_50dfee49d6903e32:block_6ece4b993038d1, analysis_50dfee49d6903e32:block_17abd485dd7278 |
| c7 Three orientation blocks lie in scripts: scripts/base_eval.py:1-243 and scripts/infer_bench.py:1-246 at confidence 0.9, and scripts/chat_eval.py:1-240 at 0.76. | inferred | supported | analysis_50dfee49d6903e32:block_625c1c9334b2fd, analysis_50dfee49d6903e32:block_f5d08a9df2b10b, analysis_50dfee49d6903e32:block_9ca9430ebe5293 |
| c8 Each of these six files contains a detected __main__ entrypoint guard. | 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 |
| c9 The execution-story lesson has three blocks: the guard at nanochat/dataset.py:136-160 (confidence 0.99), the module block nanochat/dataset.py:1-160, and the get_base_dir block nanochat/common.py:71-80. | inferred | supported | analysis_50dfee49d6903e32:block_3b159c33fe914a, analysis_50dfee49d6903e32:block_df3165c373085a, analysis_50dfee49d6903e32:block_c7448be3e775ff |
| c10 The analyzer says the guard gates code that runs when nanochat/dataset.py is executed directly rather than imported, and that get_base_dir encapsulates an operation with 6 downstream call or import relations. | inferred | supported | analysis_50dfee49d6903e32:block_3b159c33fe914a, analysis_50dfee49d6903e32:block_c7448be3e775ff |
| c11 A __main__ guard in nanochat/dataset.py and a function get_base_dir with signature def get_base_dir(): in nanochat/common.py are parsed symbols. | observed | supported | analysis_50dfee49d6903e32:py_entry_6f78b0b1883f, analysis_50dfee49d6903e32:py_func_8dd5e10657c8 |
| c12 Five of the analyzer's 81 bounded paths are listed. All start at the nanochat/dataset.py entrypoint, call get_base_dir, and stop at an unresolved boundary in os.environ.get, os.path.expanduser or os.path.join. | 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 |
| c13 One analyzer teaching claim states that no bounded static execution path is available. This conflicts with the listed paths, and the packet does not establish which statement holds. | unresolved | supported | analysis_50dfee49d6903e32:claim_4d30ade3e21e, analysis_50dfee49d6903e32:exec_de60eb0f815c |
| c14 All eight blocks of the analyzer's core-code lesson lie in library code. | inferred | supported | analysis_50dfee49d6903e32:block_3b159c33fe914a, analysis_50dfee49d6903e32:block_c7448be3e775ff, analysis_50dfee49d6903e32:block_a1abd4609abe14, analysis_50dfee49d6903e32:block_c8196da74438a6, analysis_50dfee49d6903e32:block_b1620ddb25cd2e, analysis_50dfee49d6903e32:block_9d9920ef9b288e, analysis_50dfee49d6903e32:block_c9f453c630bdd4, analysis_50dfee49d6903e32:block_87084d3257e7b3 |
| c15 Five core-code blocks appear elsewhere here. The other three, each described as encapsulating an operation, are muon_step_fused at nanochat/optim.py:112-180 (42 relations), evaluate_example at nanochat/core_eval.py:168-241 (34) and evaluate_bpb at nanochat/loss_eval.py:9-65 (28). | inferred | supported | analysis_50dfee49d6903e32:block_b1620ddb25cd2e, analysis_50dfee49d6903e32:block_9d9920ef9b288e, analysis_50dfee49d6903e32:block_87084d3257e7b3 |
| c16 The library reading set is the AI Frontier lab's selection of the four most connected library modules by static call degree, each with its two longest class or function blocks; it is not an analyzer lesson. | inferred | supported | analysis_50dfee49d6903e32:role_2, analysis_50dfee49d6903e32:role_6, analysis_50dfee49d6903e32:role_1, analysis_50dfee49d6903e32:role_23 |
| c17 nanochat/common.py is a leaf/data-boundary candidate with 143 incoming and 0 outgoing calls. Its get_peak_flops (nanochat/common.py:228-279) and get_peak_bandwidth (nanochat/common.py:281-328) connect to 5 and 4 downstream relations. | inferred | supported | analysis_50dfee49d6903e32:role_2, analysis_50dfee49d6903e32:block_d61c1c7a78d0e3, analysis_50dfee49d6903e32:block_f5d270ee395db6 |
| c18 nanochat/engine.py is an entry/orchestration candidate with 17 incoming and 3 outgoing calls. The class Engine (nanochat/engine.py:169-299) groups related behavior, and Engine.generate (nanochat/engine.py:176-275) connects to 43 downstream relations. | inferred | supported | analysis_50dfee49d6903e32:role_6, analysis_50dfee49d6903e32:block_8edeafce1e8c31, analysis_50dfee49d6903e32:block_c8196da74438a6 |
| c19 nanochat/checkpoint_manager.py is a service/core candidate with 12 incoming and 6 outgoing calls. build_model (nanochat/checkpoint_manager.py:76-114) and load_optimizer_state (nanochat/checkpoint_manager.py:173-193) connect to 19 and 10 downstream relations. | inferred | supported | analysis_50dfee49d6903e32:role_1, analysis_50dfee49d6903e32:block_5cf0cac763550a, analysis_50dfee49d6903e32:block_2cd518b16b36ba |
| c20 tasks/common.py is an entry/orchestration candidate with 16 incoming calls and 1 outgoing call. The class Task (tasks/common.py:85-126) groups related behavior, and load_hub_dataset (tasks/common.py:45-82) connects to 27 downstream relations. | inferred | supported | analysis_50dfee49d6903e32:role_23, analysis_50dfee49d6903e32:block_e6cdd090912853, analysis_50dfee49d6903e32:block_c9f453c630bdd4 |
| c21 The change-guide lesson lists six blocks where the static graph shows stronger coupling; four lie in library code and two in scripts. | inferred | supported | analysis_50dfee49d6903e32:block_a1abd4609abe14, analysis_50dfee49d6903e32:block_4bd4f7da666897, analysis_50dfee49d6903e32:block_df1b86af2cd9c6, analysis_50dfee49d6903e32:block_feceb45c048682, analysis_50dfee49d6903e32:block_34744734d1322a, analysis_50dfee49d6903e32:block_c8196da74438a6 |
| c22 Three listed blocks concern print0: the function at nanochat/common.py:118-121 with 3 downstream relations, a straight_line region at nanochat/common.py:119-119, and an if block at nanochat/common.py:120-121 that selects between control-flow paths. | inferred | supported | analysis_50dfee49d6903e32:block_a1abd4609abe14, analysis_50dfee49d6903e32:block_4bd4f7da666897, analysis_50dfee49d6903e32:block_df1b86af2cd9c6 |
| c23 The analyzer counts 143 incoming calls into nanochat/common.py, the module that contains print0. | inferred | supported | analysis_50dfee49d6903e32:role_2, analysis_50dfee49d6903e32:block_a1abd4609abe14 |
| c24 The two script main functions, scripts/infer_bench.py:97-243 and scripts/base_eval.py:128-239, connect to 80 and 61 downstream relations, so that part of the coupling signal comes from script code. | inferred | supported | analysis_50dfee49d6903e32:block_feceb45c048682, analysis_50dfee49d6903e32:block_34744734d1322a |
| c25 Engine.generate at nanochat/engine.py:176-275 is described as encapsulating an operation with 43 downstream relations. | inferred | supported | analysis_50dfee49d6903e32:block_c8196da74438a6 |
| c26 The analysis is static only and does not resolve reflection, runtime dependency injection, dynamic imports, monkey-patching, generated code, framework runtime wiring or dynamic dispatch. | observed | supported | analysis_50dfee49d6903e32:lim_1 |
| c27 Every listed execution path ends at an external or unresolved call, so runtime behavior past that point is not shown. | inferred | supported | analysis_50dfee49d6903e32:exec_de60eb0f815c, analysis_50dfee49d6903e32:exec_270399b88681, analysis_50dfee49d6903e32:exec_bebf565646e1, analysis_50dfee49d6903e32:exec_9b057297bbd5, analysis_50dfee49d6903e32:exec_6fe58885bff5 |
| c28 Install, run and build inference is partial and installation commands are not verified. | observed | supported | analysis_50dfee49d6903e32:lim_2 |
| c29 Files over 400 kB, minified bundles and vendored directories are inventoried but not parsed, and relation extraction is capped at 2500 per file and 150000 per repository. | observed | supported | analysis_50dfee49d6903e32:lim_6 |
| c30 Block descriptions are the analyzer's inferences; the blocks named in this walkthrough carry confidence scores from 0.76 to 0.99. | inferred | supported | analysis_50dfee49d6903e32:block_c7448be3e775ff, analysis_50dfee49d6903e32:block_3b159c33fe914a, analysis_50dfee49d6903e32:block_625c1c9334b2fd, analysis_50dfee49d6903e32:block_8edeafce1e8c31 |
| c31 The analyzer's uncertainties lesson lists no blocks. Its teaching note says static analysis cannot establish all dynamic dispatch, reflection, generated-code or runtime framework behavior. | inferred | supported | analysis_50dfee49d6903e32:claim_7c9925f9c8f4 |
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