docs(nanochat): add end-to-end setup guide

Document the full Nanochat setup flow, including submodule init, maturin installation, rustbpe build, tokenizer preparation, CPU smoke-test commands, and CORE evaluation prerequisites.

Author: baochunli

docs/docs/configurations/evaluation.md

@@ -40,7 +40,7 @@ If `[evaluation]` is omitted, Plato only records the trainer's normal scalar met
 | Evaluator | Install path | Primary output style | Typical use |
 | --- | --- | --- | --- |
 | `lighteval` | `uv sync --extra llm_eval` | Named benchmark metrics such as `ifeval_avg` and `arc_avg` | Server-side LLM evaluation |
-| `nanochat_core` | `uv sync --extra nanochat` | `core_metric` | Nanochat benchmark runs — requires `trainer.type = "nanochat"` |
+| `nanochat_core` | `uv sync --extra nanochat` | `core_metric` | Nanochat benchmark runs — requires `trainer.type = "nanochat"` and a trained Nanochat tokenizer under `~/.cache/nanochat/tokenizer/` |
 
 ## Lighteval
 
@@ -165,6 +165,17 @@ These columns are added to the CSV automatically the first time they appear.
 
 Nanochat's CORE benchmark is also available through `[evaluation]`.
 
+!!! note "Tokenizer required"
+    `nanochat_core` does not just need the `nanochat` Python dependencies. It also
+    requires a trained Nanochat tokenizer under `~/.cache/nanochat/tokenizer/`
+    (notably `tokenizer.pkl` and `token_bytes.pt`).
+
+    Plato can download the CORE evaluation bundle automatically, but it does **not**
+    create the tokenizer automatically.
+
+    See [Nanochat in Plato](examples/case-studies/5. Nanochat in Plato.md) for the
+    full setup sequence, including tokenizer training.
+
 ### Supported options
 
 !!! example "bundle_dir"

docs/docs/examples/case-studies/5. Nanochat in Plato.md

@@ -0,0 +1,275 @@
+# Nanochat in Plato
+
+Plato includes a Nanochat integration for federated training plus optional CORE evaluation.
+This guide documents the **working end-to-end setup** for the current repository state.
+
+Reference files:
+
+- `configs/Nanochat/synthetic_micro.toml`
+- `configs/Nanochat/parquet_micro.toml`
+- `examples/nanochat/README.md`
+- `external/nanochat/`
+
+## What you need to know first
+
+There are two separate pieces of setup:
+
+1. **Running Nanochat training inside Plato**
+2. **Running Nanochat CORE evaluation**
+
+The current `synthetic_micro.toml` configuration already enables:
+
+```toml
+[evaluation]
+type = "nanochat_core"
+```
+
+So if you run that config as-is, you need **both**:
+
+- the Nanochat Rust tokenizer extension (`rustbpe`)
+- a trained tokenizer under `~/.cache/nanochat/tokenizer/`
+
+The CORE evaluation bundle itself is downloaded automatically on first use, but the tokenizer is **not**.
+
+## Step 1: Clone Plato and initialize submodules
+
+From a fresh checkout:
+
+```bash
+git clone git@github.com:TL-System/plato.git
+cd plato
+git submodule update --init --recursive
+```
+
+The Nanochat code lives in the submodule:
+
+- `external/nanochat`
+
+If this step is skipped, Nanochat imports and build steps will fail.
+
+## Step 2: Install Plato with the Nanochat extra
+
+From the repository root:
+
+```bash
+uv sync --extra nanochat
+```
+
+This installs the Python dependencies needed by Plato's Nanochat integration.
+
+## Step 3: Install `maturin`
+
+The Rust tokenizer build step uses `maturin`. Install it once if it is not already available on your machine:
+
+```bash
+uv tool install maturin
+```
+
+If you already have `maturin`, you can skip this step.
+
+## Step 4: Build the Nanochat Rust tokenizer extension for Plato's environment
+
+From the repository root:
+
+```bash
+uv run --extra nanochat maturin develop --release --manifest-path external/nanochat/rustbpe/Cargo.toml
+```
+
+This builds and installs the `rustbpe` extension into the environment used by `uv run` in the Plato repository.
+
+### Troubleshooting: `Both VIRTUAL_ENV and CONDA_PREFIX are set`
+
+If `maturin` fails with a message like this:
+
+```text
+Both VIRTUAL_ENV and CONDA_PREFIX are set. Please unset one of them
+```
+
+run:
+
+```bash
+unset CONDA_PREFIX
+uv run --extra nanochat maturin develop --release --manifest-path external/nanochat/rustbpe/Cargo.toml
+```
+
+## Step 5A: Run the training-only synthetic smoke test
+
+If you only want to verify that Nanochat training works and do **not** need CORE evaluation yet, first make a local copy of the config and disable the evaluation block there:
+
+```bash
+cp configs/Nanochat/synthetic_micro.toml /tmp/nanochat_synthetic_train_only.toml
+```
+
+Edit `/tmp/nanochat_synthetic_train_only.toml` and comment out:
+
+```toml
+# [evaluation]
+# type = "nanochat_core"
+# max_per_task = 16
+```
+
+Then run:
+
+```bash
+uv run --extra nanochat python plato.py --config /tmp/nanochat_synthetic_train_only.toml --cpu
+```
+
+This launches a 1-round synthetic training smoke test on CPU without requiring tokenizer setup for CORE evaluation.
+
+## Step 5B: Prepare the tokenizer required by CORE evaluation
+
+If you want to run `configs/Nanochat/synthetic_micro.toml` **without editing it**, you must prepare a tokenizer first.
+
+### Why this extra step is needed
+
+Nanochat's CORE evaluator expects these tokenizer artifacts under:
+
+- `~/.cache/nanochat/tokenizer/tokenizer.pkl`
+- `~/.cache/nanochat/tokenizer/token_bytes.pt`
+
+Plato can auto-download the CORE evaluation bundle, but it does **not** auto-create the tokenizer.
+
+### 5B.1 Download Nanochat base data shards
+
+Run this from the Plato repository root:
+
+```bash
+PYTHONPATH=external/nanochat:$PYTHONPATH \
+uv run --extra nanochat python external/nanochat/nanochat/dataset.py -n 2
+```
+
+This downloads data into:
+
+- `~/.cache/nanochat/base_data/`
+
+!!! warning "Download at least 2 shards"
+    Do not download just one shard.
+
+    Nanochat's tokenizer training script uses all but the last shard for the training split and reserves the last shard for validation. With only one shard, the training split is empty and tokenizer training produces an unusable tokenizer.
+
+### 5B.2 Train the tokenizer
+
+For the micro config, use a small vocabulary size matching the smoke-test setup:
+
+```bash
+PYTHONPATH=external/nanochat:$PYTHONPATH \
+uv run --extra nanochat python external/nanochat/scripts/tok_train.py --max_chars 1000000 --vocab_size 512
+```
+
+This should create:
+
+- `~/.cache/nanochat/tokenizer/tokenizer.pkl`
+- `~/.cache/nanochat/tokenizer/token_bytes.pt`
+
+## Step 6: Run the synthetic Nanochat config with CORE evaluation
+
+Once the tokenizer exists, run:
+
+```bash
+uv run --extra nanochat python plato.py --config configs/Nanochat/synthetic_micro.toml --cpu
+```
+
+What to expect:
+
+- training runs on CPU
+- one client participates in one round
+- the CORE evaluation bundle is downloaded automatically on the first run if missing
+- some CORE examples may be skipped when they exceed the tiny micro model's `sequence_len`
+
+That last point is expected for this micro configuration.
+
+## Step 7: Run the Parquet micro config
+
+The repository also includes:
+
+- `configs/Nanochat/parquet_micro.toml`
+
+Run it with:
+
+```bash
+uv run --extra nanochat python plato.py --config configs/Nanochat/parquet_micro.toml
+```
+
+Notes:
+
+- this config is set up for `mode = "parquet"`
+- it reuses Nanochat's cached base data under `~/.cache/nanochat/base_data/`
+- it also requires the tokenizer prepared in [Step 5B](#step-5b-prepare-the-tokenizer-required-by-core-evaluation), because Parquet tokenization and CORE evaluation both depend on it
+- by default it will reuse the tokenizer trained in Step 5B; if you train a different tokenizer or vocabulary, keep the tokenizer, cached data flow, and model settings aligned
+- it defaults to `device = "cuda"`
+- it performs many more rounds than the synthetic smoke test
+- it is intended for a more realistic run than the CPU micro smoke test
+
+You may need to adjust device, batch counts, rounds, and data volume for your hardware.
+
+## Common failure modes
+
+### `ModuleNotFoundError: No module named 'nanochat'`
+
+This usually happens when running upstream Nanochat scripts directly.
+
+Use the commands in this guide from the **Plato repository root** and include:
+
+```bash
+PYTHONPATH=external/nanochat:$PYTHONPATH
+```
+
+when calling upstream scripts such as:
+
+- `external/nanochat/nanochat/dataset.py`
+- `external/nanochat/scripts/tok_train.py`
+
+You do **not** need this extra `PYTHONPATH` prefix when running `plato.py`, because Plato's Nanochat integration adds the submodule path internally.
+
+### `AttributeError: module 'rustbpe' has no attribute 'Tokenizer'`
+
+The Rust extension was not built for Plato's active Python environment.
+
+Re-run:
+
+```bash
+uv run --extra nanochat maturin develop --release --manifest-path external/nanochat/rustbpe/Cargo.toml
+```
+
+### `FileNotFoundError: ... ~/.cache/nanochat/tokenizer/tokenizer.pkl`
+
+The tokenizer has not been trained yet.
+
+Follow the steps in:
+
+- [Step 5B: Prepare the tokenizer required by CORE evaluation](#step-5b-prepare-the-tokenizer-required-by-core-evaluation)
+
+### CORE evaluation crashes on long prompts
+
+The `synthetic_micro.toml` model uses a very small sequence length.
+Some CORE prompts can exceed that limit.
+
+Plato now skips examples that do not fit into the model context window during Nanochat CORE evaluation, instead of aborting the entire run.
+
+## Recommended command summary
+
+### Minimal training-only smoke test
+
+1. `git submodule update --init --recursive`
+2. `uv sync --extra nanochat`
+3. `uv tool install maturin`
+4. `uv run --extra nanochat maturin develop --release --manifest-path external/nanochat/rustbpe/Cargo.toml`
+5. `cp configs/Nanochat/synthetic_micro.toml /tmp/nanochat_synthetic_train_only.toml`
+6. comment out `[evaluation]` in `/tmp/nanochat_synthetic_train_only.toml`
+7. `uv run --extra nanochat python plato.py --config /tmp/nanochat_synthetic_train_only.toml --cpu`
+
+### Full synthetic run with CORE evaluation
+
+1. `git submodule update --init --recursive`
+2. `uv sync --extra nanochat`
+3. `uv tool install maturin`
+4. `uv run --extra nanochat maturin develop --release --manifest-path external/nanochat/rustbpe/Cargo.toml`
+5. `PYTHONPATH=external/nanochat:$PYTHONPATH uv run --extra nanochat python external/nanochat/nanochat/dataset.py -n 2`
+6. `PYTHONPATH=external/nanochat:$PYTHONPATH uv run --extra nanochat python external/nanochat/scripts/tok_train.py --max_chars 1000000 --vocab_size 512`
+7. `uv run --extra nanochat python plato.py --config configs/Nanochat/synthetic_micro.toml --cpu`
+
+## Related documentation
+
+- [Installation](../../install.md)
+- [Quick Start](../../quickstart.md)
+- [Evaluation configuration](../../configurations/evaluation.md)

docs/docs/index.md

@@ -36,8 +36,9 @@ Welcome to *Plato*, a software framework to facilitate scalable, reproducible, a
     ### Case Studies
     - **[Federated LoRA Fine-Tuning](examples/case-studies/1. LoRA.md)**
     - **[Composable Trainer API](examples/case-studies/2. Composable Trainer.md)**
-    - **[Server-side Lighteval for SmolLM2](examples/case-studies/4. Server-side Lighteval for SmolLM2.md)**
     - **[SmolVLA Trainer with LeRobot](examples/case-studies/3. SmolVLA Trainer with LeRobot.md)**
+    - **[Server-side Lighteval for SmolLM2](examples/case-studies/4. Server-side Lighteval for SmolLM2.md)**
+    - **[Nanochat in Plato](examples/case-studies/5. Nanochat in Plato.md)**
 
 ## Configuration Settings
 

docs/docs/install.md

@@ -95,6 +95,15 @@ To use Nanochat workloads or the `nanochat_core` evaluator, install:
 uv sync --extra nanochat
 ```
 
+Nanochat also requires the `external/nanochat` git submodule, and the Rust tokenizer extension must be built before running the Nanochat configs successfully.
+
+See [Nanochat in Plato](examples/case-studies/5. Nanochat in Plato.md) for the full step-by-step setup, including:
+
+- `git submodule update --init --recursive`
+- installing `maturin` and building `rustbpe`
+- preparing the tokenizer required by CORE evaluation
+- running `configs/Nanochat/synthetic_micro.toml` and `configs/Nanochat/parquet_micro.toml`
+
 ### Optional: SmolVLA + LeRobot Robotics Stack
 
 The LeRobot / SmolVLA path is intentionally kept separate from the default Plato install so the root environment stays lean.

docs/docs/quickstart.md

@@ -53,6 +53,17 @@ This configuration performs Hugging Face training locally while the server evalu
 
 See [Evaluation](configurations/evaluation.md) for the available evaluator options and [Server-side Lighteval for SmolLM2](examples/case-studies/4. Server-side Lighteval for SmolLM2.md) for the full example.
 
+## Running Nanochat in Plato
+
+Nanochat requires additional setup beyond `uv sync --extra nanochat`:
+
+- initialize the `external/nanochat` submodule
+- install `maturin` and build the `rustbpe` extension
+- prepare a tokenizer if you want to run CORE evaluation
+- use `--cpu` for the synthetic smoke-test path if you want the run to stay on CPU
+
+See [Nanochat in Plato](examples/case-studies/5. Nanochat in Plato.md) for the full step-by-step instructions.
+
 ## Using MLX as a Backend
 
 Plato supports MLX as an alternative backend to PyTorch for Apple Silicon devices. To use MLX, first install the optional dependencies:

docs/docs/references/evaluators.md

@@ -81,6 +81,14 @@ def evaluate(self, request: EvaluationInput) -> EvaluationResult:
     or `composable`) produces no evaluation output and no error — the runner silently
     skips it.
 
+!!! note "nanochat_core tokenizer prerequisite"
+    In addition to `uv sync --extra nanochat`, this evaluator requires a trained
+    Nanochat tokenizer under `~/.cache/nanochat/tokenizer/`. Plato can auto-download
+    the CORE bundle, but it does **not** auto-create the tokenizer.
+
+    See [Nanochat in Plato](examples/case-studies/5. Nanochat in Plato.md) for the
+    end-to-end setup.
+
 ## Evaluator registry
 
 `plato.evaluators.registry` provides the registration surface:

docs/mkdocs.yml

@@ -69,8 +69,9 @@ nav:
       - Case Studies:
           - Federated LoRA Fine-Tuning: examples/case-studies/1. LoRA.md
           - Composable Trainer API: examples/case-studies/2. Composable Trainer.md
-          - Server-side Lighteval for SmolLM2: examples/case-studies/4. Server-side Lighteval for SmolLM2.md
           - SmolVLA Trainer with LeRobot: examples/case-studies/3. SmolVLA Trainer with LeRobot.md
+          - Server-side Lighteval for SmolLM2: examples/case-studies/4. Server-side Lighteval for SmolLM2.md
+          - Nanochat in Plato: examples/case-studies/5. Nanochat in Plato.md
   - Configuration Settings:
       - Overview: configurations/overview.md
       - General: configurations/general.md