EVEMISSTechnology

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 LICENSE file 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, runs and scripts.
  • 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.py and scripts/infer_bench.py: the guard only calls main().
  • 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.py and tests/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.py as a starting point, while the repository summary names nanochat/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