fromscratch-pyllm 0.5.0__tar.gz

fromscratch_pyllm-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,14 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    uses: robcox2910/robcox2910.github.io/.github/workflows/python-ci.yml@v1

fromscratch_pyllm-0.5.0/.github/workflows/docs.yml

@@ -0,0 +1,16 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch: {}
+
+jobs:
+  docs:
+    uses: robcox2910/robcox2910.github.io/.github/workflows/docs.yml@v1
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    with:
+      coverage-report: false

fromscratch_pyllm-0.5.0/.github/workflows/release.yml

@@ -0,0 +1,58 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+      - name: Upload to GitHub Release
+        uses: softprops/action-gh-release@v3
+        with:
+          files: dist/*
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/fromscratch-pyllm/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

fromscratch_pyllm-0.5.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+src/pyllm/_version.py
+.coverage
+.hypothesis/

fromscratch_pyllm-0.5.0/.pre-commit-config.yaml

@@ -0,0 +1,56 @@
+default_language_version:
+  python: python3.14
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      # Pages paste real pytest output, trailing spaces included.
+      - id: trailing-whitespace
+        exclude: ^docs/property-testing\.md$
+      - id: end-of-file-fixer
+        exclude: ^docs/property-testing\.md$
+      - id: check-yaml
+        args: ['--unsafe']
+      - id: check-added-large-files
+      - id: check-json
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.4
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: https://github.com/RobertCraigie/pyright-python
+    rev: v1.1.408
+    hooks:
+      - id: pyright
+
+  - repo: local
+    hooks:
+      - id: pip-audit
+        name: pip-audit
+        language: system
+        pass_filenames: false
+        files: ^(pyproject\.toml|uv\.lock)$
+        entry: >-
+          bash -c 'f=$(mktemp) &&
+          uv export --frozen --no-emit-project --all-extras --no-hashes -o "$f" >/dev/null &&
+          uvx pip-audit==2.10.0 -r "$f" --disable-pip --no-deps;
+          status=$?; rm -f "$f"; exit $status'
+
+  - repo: https://github.com/rhysd/actionlint
+    rev: v1.7.7
+    hooks:
+      - id: actionlint
+
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.13.8
+    hooks:
+      - id: commitizen
+        stages: [commit-msg]
+        additional_dependencies: [typing_extensions]

fromscratch_pyllm-0.5.0/CLAUDE.md

@@ -0,0 +1,72 @@
+# PyLLM
+
+<!-- standard:start -->
+## Code Style
+
+- All public functions, methods, classes, and modules **must** have a docstring
+- Use imperative mood: "Return the result." not "Returns the result."
+- One-line docstrings for simple functions; multi-line with summary + details for complex ones
+- Follow the Google docstring convention (D211, D212 selected via ruff)
+
+## Linting
+
+- Ruff enforces a comprehensive rule set -- run `uv run ruff check .` before committing
+- Pyright runs in strict mode -- run `uv run pyright src tests` before committing
+- All violations must be fixed, not ignored. Exceptions are the repo-owned `ignore` and `per-file-ignores` lists in `pyproject.toml`, which belong to this repo; the series sync never edits them
+
+## Testing
+
+- TDD workflow: Red-Green-Refactor
+- Coverage is enforced by pytest-cov; the floor in `pyproject.toml` is repo-owned
+- Test classes and methods also require docstrings
+- Use named constants instead of magic values (PLR2004)
+- Run `uv run pytest` before committing
+- Property-based tests (Hypothesis) live in `tests/test_properties.py` and `tests/test_model.py`; the shared profiles are in the root `conftest.py` (owned by `series sync`). Run `uv run pytest --hypothesis-profile=thorough` before a release.
+
+## Commits
+
+- Use conventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `ci:`, `chore:`
+- All changes go via PR from a feature branch (main is protected); merge when CI is green
+
+## Dependencies
+
+- Package manager: uv
+- Run `uv sync --all-extras` after modifying dependencies
+- `uv.lock` is committed; CI and pre-commit audit it with pip-audit through `uvx`, so pip-audit is not a project dependency
+- Sibling projects, where used, are pinned release tags in `[tool.uv.sources]` (git + tag); never use `path` sources
+
+## Releasing
+
+- A release is a `vX.Y.Z` tag on main after the PR is merged
+- Docs-only and tooling-only changes do not get a release tag
+- Docs are built with `mkdocs build --strict` and deployed to GitHub Pages by the docs workflow
+<!-- standard:end -->
+
+## Project notes
+
+- **Numpy autograd.** There is no torch: `src/pyllm/autograd` is a small reverse-mode
+  autodiff engine on numpy arrays (`Tensor`). Layers live in `src/pyllm/nn`, models in
+  `src/pyllm/models`, and `pyllm._types` holds the shared `Array` alias. Each op stores a
+  backward recipe via `Tensor.set_backward`; check new ops with
+  `pyllm.autograd.gradcheck.numerical_grad`.
+- **Bundled checkpoints.** `src/pyllm/data/pokemon.npz` and `src/pyllm/data/pebble.npz` are
+  trained models committed to the repo (and force-included in the wheel). Regenerate them with
+  `uv run python scripts/train_pokemon.py` and `uv run python scripts/train_pebble.py`. Both
+  use fixed seeds, but training changes whenever the model code changes, so rerun them and
+  commit the new `.npz` files if you touch the models, optimizers or training loop.
+- **The Pebble referee.** `src/pyllm/pebble/referee.py` is a hand-written, character-by-character
+  checker for the canonical slice of Pebble the corpus uses (4-space indents, single spaces
+  around operators). `viable(text)` means "could still become valid" and `complete(text)` means
+  "valid right now". It must stay a strict subset of real Pebble so anything it accepts, Pebble's
+  own parser accepts too (tests check this against `pebble-lang`). `generate(..., referee=...)`
+  uses it to veto illegal characters.
+- **Regenerating the Pebble corpus.** `src/pyllm/data/pebble_corpus.txt` is generated, not
+  hand-written: `uv run python scripts/build_pebble_corpus.py` grows random valid programs
+  (`pebble/generator.py`), mixes in snippets harvested from a sibling `../pebble-lang/docs`
+  checkout (kept only if they parse) and canonicalises everything with Pebble's formatter. Use
+  `--pebble-docs PATH` to harvest from elsewhere; if the docs folder is missing the script stops
+  with an error (it never silently drops the snippets) unless you pass `--no-harvest`. The
+  bundled corpus is built *with* the snippets, so only use `--no-harvest` for experiments. A
+  similar recipe is available as `pyllm gen-corpus --harvest PATH --canonical` (which also fails
+  on a missing `--harvest` folder). It needs the optional `pebble` extra
+  (`uv sync --all-extras`). Retrain `pebble.npz` afterwards.

fromscratch_pyllm-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rob Cox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fromscratch_pyllm-0.5.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.5
+Name: fromscratch-pyllm
+Version: 0.5.0
+Summary: An educational large language model built from scratch in Python
+Project-URL: Homepage, https://github.com/robcox2910/pyllm
+Project-URL: Repository, https://github.com/robcox2910/pyllm
+Project-URL: Issues, https://github.com/robcox2910/pyllm/issues
+Project-URL: Documentation, https://robcox2910.github.io/pyllm/
+Author: Rob Cox
+License: MIT
+License-File: LICENSE
+Keywords: autograd,education,gpt,learning,llm,transformer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Education
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: numpy>=2.1
+Provides-Extra: dev
+Requires-Dist: commitizen>=4.4.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.170; extra == 'dev'
+Requires-Dist: pip-audit>=2.10.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.0.1; extra == 'dev'
+Requires-Dist: pyright>=1.1.400; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.4; extra == 'dev'
+Requires-Dist: ruff>=0.9.3; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Provides-Extra: pebble
+Requires-Dist: fromscratch-pebble>=0.3.0; extra == 'pebble'
+Description-Content-Type: text/markdown
+
+# PyLLM
+
+An educational large language model built from scratch in Python.
+
+Part of the "from scratch in Python" series. Built incrementally with TDD,
+every concept explained with analogies a 12-year-old can follow. The only
+dependency is numpy (for fast array math) — the autograd engine, neural-net
+layers, attention, the Transformer, the tokenizer, the optimizer, the training
+loop, and sampling are all ours.
+
+## Quick Start
+
+```bash
+uv sync --all-extras
+uv run pytest
+```
+
+## Dream up new Pokémon (generates instantly)
+
+PyLLM ships with a tiny pre-trained GPT, so it invents Pokémon-ish names the
+moment you launch it — no training wait:
+
+```console
+$ uv run pyllm --seed 0 --max-new-tokens 40
+machop
+machoke
+machamp
+bellsprout
+weepin
+```
+
+Turn the boldness dial with `--temperature` (0 = safe/greedy, higher = wilder)
+and add a `--top-k` guardrail. Start from a prompt with `--prompt "pi"`.
+
+## Train your own model
+
+Pick a rung on the teaching ladder (`bigram`, `mlp`, or `gpt`) and point it at
+any text file (defaults to the bundled Pokémon corpus):
+
+```console
+$ uv run pyllm train --model gpt --steps 2000 --out mine.npz
+step 0: loss 3.31
+...
+final loss 0.42; saved checkpoint to mine.npz
+
+$ uv run pyllm --checkpoint mine.npz --max-new-tokens 60
+```
+
+## The flagship: teach PyLLM to write Pebble
+
+There's no corpus of [Pebble](https://github.com/robcox2910/pebble-lang) code in
+the wild — so we *grow our own*. A generator emits **random-but-provably-valid**
+Pebble ASTs (100% parse under Pebble's own parser), a harvester scrapes real
+snippets from Pebble's docs, and — because we own the language toolchain — we
+**grade** the trained model by running its output back through Pebble's real
+parser and reporting what percentage parses:
+
+```console
+$ uv run pyllm pebble --seed 7 --temperature 0.5 --score
+let result = 62
+    }
+    if count < 47 {
+        let c = 51 + (83 + 32)
+...
+parse rate: 0.0% of 1 programs
+```
+
+The bundled checkpoint is *tiny* (a few-minute char-level GPT), so it writes
+Pebble-*flavoured* code and only some of it parses — and that's the whole point:
+the parser is an honest, objective judge, so you can watch the score go up as you
+train longer or bigger. Almost no LLM project can grade its own output like this.
+
+### Call in the referee: always-valid Pebble
+
+Add `--constrained` and a from-scratch grammar **referee** vetoes every character
+that would break Pebble's rules, so the model rolls again until it picks a legal
+one. Same tiny brain — but now every program it returns parses:
+
+```console
+$ uv run pyllm pebble --seed 7 --constrained --score
+let total = n * (63 - 99)
+
+let result = c
+fount = 55 + (n - b) % (6 - b)
+
+parse rate: 100.0% of 2 programs
+```
+
+From Python: `generate_pebble(constrained=True)`. See
+[`docs/concepts/the-referee.md`](docs/concepts/the-referee.md).
+
+Grow a fresh synthetic corpus with `uv run pyllm gen-corpus`. Live scoring needs
+the optional `fromscratch-pebble` dependency (`uv sync --all-extras`); generation and
+training work without it. See [`docs/concepts/grow-your-own-data.md`](docs/concepts/grow-your-own-data.md).
+
+## See how text becomes tokens
+
+```console
+$ uv run pyllm tokenize --text "pika"
+'p' -> 16
+'i' -> 9
+'k' -> 11
+'a' -> 1
+```
+
+## The teaching ladder
+
+Each rung is a real, trainable language model that fixes a weakness of the one
+below it, so you feel *why* each idea exists:
+
+1. **Bigram** — "what character usually comes next?" A lookup table.
+2. **MLP** — a small neural net over the last few characters (embeddings + a
+   hidden layer).
+3. **GPT** — stacked Transformer blocks (multi-head attention + feed-forward +
+   LayerNorm + residuals) with positional information. The real thing.
+
+## Learn the ideas
+
+Kid-friendly explanations live in [`docs/concepts/`](docs/concepts/README.md):
+the breadcrumb trail (autograd), tokens, embeddings, attention, how a Transformer
+is built, how a model learns, sampling, and — the flagship lesson — growing your
+own data.
+
+## Developing alongside a sibling
+
+PyLLM uses a released version of [Pebble](https://github.com/robcox2910/pebble-lang)
+from PyPI (`fromscratch-pebble`, the optional `pebble` extra). To try an
+unreleased Pebble change, install your local checkout over the released one:
+
+```bash
+uv pip install -e ../pebble-lang
+uv run --no-sync pytest
+```
+
+Use `uv run --no-sync` while you do this: a plain `uv run` (like `uv sync`)
+puts the pinned release back, which is how you undo the override.
+
+## Releasing
+
+1. Merge the change to `main`.
+2. Tag it: `git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z`.
+   A change to the public API bumps the minor version (`v0.1.0` → `v0.2.0`);
+   anything else bumps the patch (`v0.1.0` → `v0.1.1`).
+3. Projects that use PyLLM (like [PyStack](https://github.com/robcox2910/pystack))
+   upgrade by editing the tag in their `[tool.uv.sources]` and running
+   `uv lock --upgrade-package pyllm`, in a pull request so CI checks the pair.
+
+## PyLLM inside PyStack
+
+PyLLM is **the brain** of a family of educational projects, each building a real
+system from scratch to teach how it works. They're tied together by
+**[PyStack](https://github.com/robcox2910/pystack)**, where a Pebble program can
+even `import "llm"` and ask PyLLM to write more code.
+
+Once PyLLM is installed as a PyStack plugin, any Pebble program can call it:
+
+```pebble
+import "llm"
+let code = llm_generate("a function that adds two numbers")
+print(code)
+```
+
+<!-- series:start -->
+## Related Projects
+
+This project is one of a series that builds real systems "from scratch in Python" to teach how they work. See the [series home](https://robcox2910.github.io/) for the full story.
+
+| Project | What it teaches | Repository | Docs |
+| --- | --- | --- | --- |
+| PyOS | Operating systems | [py-os](https://github.com/robcox2910/py-os) | [Docs](https://robcox2910.github.io/py-os/) |
+| Pebble | Compilers and programming languages | [pebble-lang](https://github.com/robcox2910/pebble-lang) | [Docs](https://robcox2910.github.io/pebble-lang/) |
+| PyDB | Relational databases | [pydb](https://github.com/robcox2910/pydb) | [Docs](https://robcox2910.github.io/pydb/) |
+| PyKV | Key-value stores | [pykv](https://github.com/robcox2910/pykv) | [Docs](https://robcox2910.github.io/pykv/) |
+| PyDocDB | Document databases | [pydoc-db](https://github.com/robcox2910/pydoc-db) | [Docs](https://robcox2910.github.io/pydoc-db/) |
+| PyGraphDB | Graph databases | [pygraphdb](https://github.com/robcox2910/pygraphdb) | [Docs](https://robcox2910.github.io/pygraphdb/) |
+| PyTSDB | Time-series databases | [pytsdb](https://github.com/robcox2910/pytsdb) | [Docs](https://robcox2910.github.io/pytsdb/) |
+| PyVecDB | Vector databases | [pyvecdb](https://github.com/robcox2910/pyvecdb) | [Docs](https://robcox2910.github.io/pyvecdb/) |
+| PyColDB | Column-family databases | [pycoldb](https://github.com/robcox2910/pycoldb) | [Docs](https://robcox2910.github.io/pycoldb/) |
+| PyCrypt | Cryptography | [pycrypt](https://github.com/robcox2910/pycrypt) | [Docs](https://robcox2910.github.io/pycrypt/) |
+| PyNet | Computer networking | [pynet](https://github.com/robcox2910/pynet) | [Docs](https://robcox2910.github.io/pynet/) |
+| PyWeb | HTTP web servers | [pyweb](https://github.com/robcox2910/pyweb) | [Docs](https://robcox2910.github.io/pyweb/) |
+| PyGit | Version control | [pygit](https://github.com/robcox2910/pygit) | [Docs](https://robcox2910.github.io/pygit/) |
+| PySearch | Search engines | [pysearch](https://github.com/robcox2910/pysearch) | [Docs](https://robcox2910.github.io/pysearch/) |
+| PyMQ | Message queues | [pymq](https://github.com/robcox2910/pymq) | [Docs](https://robcox2910.github.io/pymq/) |
+| **PyLLM** | **Language models (the brain)** | [pyllm](https://github.com/robcox2910/pyllm) | [Docs](https://robcox2910.github.io/pyllm/) |
+| PyScheduler | Job scheduling | [pyscheduler](https://github.com/robcox2910/pyscheduler) | [Docs](https://robcox2910.github.io/pyscheduler/) |
+| PyStack | Full-stack integration | [pystack](https://github.com/robcox2910/pystack) | [Docs](https://robcox2910.github.io/pystack/) |
+<!-- series:end -->
+
+<!-- docs:start -->
+## Documentation
+
+Full docs (with kid-friendly explanations of every idea): https://robcox2910.github.io/pyllm/
+<!-- docs:end -->

fromscratch_pyllm-0.5.0/README.md

@@ -0,0 +1,194 @@
+# PyLLM
+
+An educational large language model built from scratch in Python.
+
+Part of the "from scratch in Python" series. Built incrementally with TDD,
+every concept explained with analogies a 12-year-old can follow. The only
+dependency is numpy (for fast array math) — the autograd engine, neural-net
+layers, attention, the Transformer, the tokenizer, the optimizer, the training
+loop, and sampling are all ours.
+
+## Quick Start
+
+```bash
+uv sync --all-extras
+uv run pytest
+```
+
+## Dream up new Pokémon (generates instantly)
+
+PyLLM ships with a tiny pre-trained GPT, so it invents Pokémon-ish names the
+moment you launch it — no training wait:
+
+```console
+$ uv run pyllm --seed 0 --max-new-tokens 40
+machop
+machoke
+machamp
+bellsprout
+weepin
+```
+
+Turn the boldness dial with `--temperature` (0 = safe/greedy, higher = wilder)
+and add a `--top-k` guardrail. Start from a prompt with `--prompt "pi"`.
+
+## Train your own model
+
+Pick a rung on the teaching ladder (`bigram`, `mlp`, or `gpt`) and point it at
+any text file (defaults to the bundled Pokémon corpus):
+
+```console
+$ uv run pyllm train --model gpt --steps 2000 --out mine.npz
+step 0: loss 3.31
+...
+final loss 0.42; saved checkpoint to mine.npz
+
+$ uv run pyllm --checkpoint mine.npz --max-new-tokens 60
+```
+
+## The flagship: teach PyLLM to write Pebble
+
+There's no corpus of [Pebble](https://github.com/robcox2910/pebble-lang) code in
+the wild — so we *grow our own*. A generator emits **random-but-provably-valid**
+Pebble ASTs (100% parse under Pebble's own parser), a harvester scrapes real
+snippets from Pebble's docs, and — because we own the language toolchain — we
+**grade** the trained model by running its output back through Pebble's real
+parser and reporting what percentage parses:
+
+```console
+$ uv run pyllm pebble --seed 7 --temperature 0.5 --score
+let result = 62
+    }
+    if count < 47 {
+        let c = 51 + (83 + 32)
+...
+parse rate: 0.0% of 1 programs
+```
+
+The bundled checkpoint is *tiny* (a few-minute char-level GPT), so it writes
+Pebble-*flavoured* code and only some of it parses — and that's the whole point:
+the parser is an honest, objective judge, so you can watch the score go up as you
+train longer or bigger. Almost no LLM project can grade its own output like this.
+
+### Call in the referee: always-valid Pebble
+
+Add `--constrained` and a from-scratch grammar **referee** vetoes every character
+that would break Pebble's rules, so the model rolls again until it picks a legal
+one. Same tiny brain — but now every program it returns parses:
+
+```console
+$ uv run pyllm pebble --seed 7 --constrained --score
+let total = n * (63 - 99)
+
+let result = c
+fount = 55 + (n - b) % (6 - b)
+
+parse rate: 100.0% of 2 programs
+```
+
+From Python: `generate_pebble(constrained=True)`. See
+[`docs/concepts/the-referee.md`](docs/concepts/the-referee.md).
+
+Grow a fresh synthetic corpus with `uv run pyllm gen-corpus`. Live scoring needs
+the optional `fromscratch-pebble` dependency (`uv sync --all-extras`); generation and
+training work without it. See [`docs/concepts/grow-your-own-data.md`](docs/concepts/grow-your-own-data.md).
+
+## See how text becomes tokens
+
+```console
+$ uv run pyllm tokenize --text "pika"
+'p' -> 16
+'i' -> 9
+'k' -> 11
+'a' -> 1
+```
+
+## The teaching ladder
+
+Each rung is a real, trainable language model that fixes a weakness of the one
+below it, so you feel *why* each idea exists:
+
+1. **Bigram** — "what character usually comes next?" A lookup table.
+2. **MLP** — a small neural net over the last few characters (embeddings + a
+   hidden layer).
+3. **GPT** — stacked Transformer blocks (multi-head attention + feed-forward +
+   LayerNorm + residuals) with positional information. The real thing.
+
+## Learn the ideas
+
+Kid-friendly explanations live in [`docs/concepts/`](docs/concepts/README.md):
+the breadcrumb trail (autograd), tokens, embeddings, attention, how a Transformer
+is built, how a model learns, sampling, and — the flagship lesson — growing your
+own data.
+
+## Developing alongside a sibling
+
+PyLLM uses a released version of [Pebble](https://github.com/robcox2910/pebble-lang)
+from PyPI (`fromscratch-pebble`, the optional `pebble` extra). To try an
+unreleased Pebble change, install your local checkout over the released one:
+
+```bash
+uv pip install -e ../pebble-lang
+uv run --no-sync pytest
+```
+
+Use `uv run --no-sync` while you do this: a plain `uv run` (like `uv sync`)
+puts the pinned release back, which is how you undo the override.
+
+## Releasing
+
+1. Merge the change to `main`.
+2. Tag it: `git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z`.
+   A change to the public API bumps the minor version (`v0.1.0` → `v0.2.0`);
+   anything else bumps the patch (`v0.1.0` → `v0.1.1`).
+3. Projects that use PyLLM (like [PyStack](https://github.com/robcox2910/pystack))
+   upgrade by editing the tag in their `[tool.uv.sources]` and running
+   `uv lock --upgrade-package pyllm`, in a pull request so CI checks the pair.
+
+## PyLLM inside PyStack
+
+PyLLM is **the brain** of a family of educational projects, each building a real
+system from scratch to teach how it works. They're tied together by
+**[PyStack](https://github.com/robcox2910/pystack)**, where a Pebble program can
+even `import "llm"` and ask PyLLM to write more code.
+
+Once PyLLM is installed as a PyStack plugin, any Pebble program can call it:
+
+```pebble
+import "llm"
+let code = llm_generate("a function that adds two numbers")
+print(code)
+```
+
+<!-- series:start -->
+## Related Projects
+
+This project is one of a series that builds real systems "from scratch in Python" to teach how they work. See the [series home](https://robcox2910.github.io/) for the full story.
+
+| Project | What it teaches | Repository | Docs |
+| --- | --- | --- | --- |
+| PyOS | Operating systems | [py-os](https://github.com/robcox2910/py-os) | [Docs](https://robcox2910.github.io/py-os/) |
+| Pebble | Compilers and programming languages | [pebble-lang](https://github.com/robcox2910/pebble-lang) | [Docs](https://robcox2910.github.io/pebble-lang/) |
+| PyDB | Relational databases | [pydb](https://github.com/robcox2910/pydb) | [Docs](https://robcox2910.github.io/pydb/) |
+| PyKV | Key-value stores | [pykv](https://github.com/robcox2910/pykv) | [Docs](https://robcox2910.github.io/pykv/) |
+| PyDocDB | Document databases | [pydoc-db](https://github.com/robcox2910/pydoc-db) | [Docs](https://robcox2910.github.io/pydoc-db/) |
+| PyGraphDB | Graph databases | [pygraphdb](https://github.com/robcox2910/pygraphdb) | [Docs](https://robcox2910.github.io/pygraphdb/) |
+| PyTSDB | Time-series databases | [pytsdb](https://github.com/robcox2910/pytsdb) | [Docs](https://robcox2910.github.io/pytsdb/) |
+| PyVecDB | Vector databases | [pyvecdb](https://github.com/robcox2910/pyvecdb) | [Docs](https://robcox2910.github.io/pyvecdb/) |
+| PyColDB | Column-family databases | [pycoldb](https://github.com/robcox2910/pycoldb) | [Docs](https://robcox2910.github.io/pycoldb/) |
+| PyCrypt | Cryptography | [pycrypt](https://github.com/robcox2910/pycrypt) | [Docs](https://robcox2910.github.io/pycrypt/) |
+| PyNet | Computer networking | [pynet](https://github.com/robcox2910/pynet) | [Docs](https://robcox2910.github.io/pynet/) |
+| PyWeb | HTTP web servers | [pyweb](https://github.com/robcox2910/pyweb) | [Docs](https://robcox2910.github.io/pyweb/) |
+| PyGit | Version control | [pygit](https://github.com/robcox2910/pygit) | [Docs](https://robcox2910.github.io/pygit/) |
+| PySearch | Search engines | [pysearch](https://github.com/robcox2910/pysearch) | [Docs](https://robcox2910.github.io/pysearch/) |
+| PyMQ | Message queues | [pymq](https://github.com/robcox2910/pymq) | [Docs](https://robcox2910.github.io/pymq/) |
+| **PyLLM** | **Language models (the brain)** | [pyllm](https://github.com/robcox2910/pyllm) | [Docs](https://robcox2910.github.io/pyllm/) |
+| PyScheduler | Job scheduling | [pyscheduler](https://github.com/robcox2910/pyscheduler) | [Docs](https://robcox2910.github.io/pyscheduler/) |
+| PyStack | Full-stack integration | [pystack](https://github.com/robcox2910/pystack) | [Docs](https://robcox2910.github.io/pystack/) |
+<!-- series:end -->
+
+<!-- docs:start -->
+## Documentation
+
+Full docs (with kid-friendly explanations of every idea): https://robcox2910.github.io/pyllm/
+<!-- docs:end -->