EVEMISSTechnology

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: module nanochat/dataset.py; file-level container, library code (confidence 0.76).
  • nanochat/engine.py:1-352: module nanochat/engine.py; file-level container, library code (0.76).
  • tasks/common.py:1-222: module tasks/common.py; file-level container, library code (0.76).
  • scripts/base_eval.py:1-243: module scripts/base_eval.py; file-level container, script (0.9).
  • scripts/chat_eval.py:1-240: module scripts/chat_eval.py; file-level container, script (0.76).
  • scripts/infer_bench.py:1-246: module scripts/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: module nanochat/dataset.py; the file-level container for this file (0.76).
  • nanochat/common.py:71-80: function get_base_dir, signature def 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: function muon_step_fused; encapsulates an operation with 42 downstream call or import relations (0.76).
  • nanochat/core_eval.py:168-241: function evaluate_example; operation with 34 relations (0.76).
  • nanochat/loss_eval.py:9-65: function evaluate_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: function get_peak_flops; operation with 5 downstream relations.
  • nanochat/common.py:281-328: function get_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: class Engine; groups related behavior under one class boundary (0.97).
  • nanochat/engine.py:176-275: function Engine.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: function build_model; operation with 19 downstream relations.
  • nanochat/checkpoint_manager.py:173-193: function load_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: class Task; groups related behavior under one class boundary (0.99).
  • tasks/common.py:45-82: function load_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: function print0; operation with 3 downstream call or import relations (0.76).
  • nanochat/common.py:119-119: straight_line region inside print0; adjacent sequential statements grouped as one bounded region.
  • nanochat/common.py:120-121: if block inside print0; selects between control-flow paths by a condition in this region.
  • nanochat/engine.py:176-275: function Engine.generate; operation with 43 downstream relations.
  • scripts/infer_bench.py:97-243: function main; operation with 80 downstream relations, script code.
  • scripts/base_eval.py:128-239: function main; 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