docs: add per-model runtime docs; benchmark Qwen3-32B, evaluate Qwen3.6-27B

Add docs/<model>.md per runtime model:
- qwen3-32b-nvfp4.md: live test on DGX Spark (GB10) with the nv26.04 vLLM
  image — ~9.7 tok/s decode (batch=1), ~2,800 tok/s prefill, ~72 GB reserved
  at gpu-memory-utilization=0.6, correctness verified.
- qwen3.6-27b-nvfp4.md: candidate mmangkad/Qwen3.6-27B-NVFP4. Its
  Qwen3_5ForConditionalGeneration arch is registered in the current vLLM
  image, so the same compose can serve it; live load-test tracked by #6.

Fix the docker-compose --reasoning-parser comment: on the nv26.04 build the
<think> trace returns in the `reasoning` field, not `reasoning_content`.

Link both docs from README; bump version to 0.3.0.

Refs #6

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: OriNachum

CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-05-27
+
+### Added
+
+- `docs/qwen3-32b-nvfp4.md`: per-model doc for the current runtime model, with a
+  live test on DGX Spark (GB10) — `nvcr.io/nvidia/vllm:26.04-py3` (engine
+  `0.19.0+...nv26.04`), ~9.7 tok/s decode (batch=1), ~2,800 tok/s prefill, ~72 GB
+  reserved at `gpu-memory-utilization=0.6`, correctness verified.
+- `docs/qwen3.6-27b-nvfp4.md`: per-model doc for candidate
+  `mmangkad/Qwen3.6-27B-NVFP4`. Its `Qwen3_5ForConditionalGeneration` arch is
+  registered in the current vLLM image (so the same compose can serve it); live
+  load-test/benchmark tracked by issue #6.
+- README "Per-model notes" linking both docs.
+
+### Fixed
+
+- `docker-compose.yml`: corrected the `--reasoning-parser=qwen3` comment — on the
+  nv26.04 build the `<think>` trace is returned in the `reasoning` field, not
+  `reasoning_content`.
+
 ## [0.2.0] - 2026-05-27
 
 ### Added

README.md

@@ -63,3 +63,14 @@ in-container alongside `HF_TOKEN` and the mounted cache. Add it back only for a
 model whose repo ships custom modeling code. If vLLM rejects the `nvidia/`
 ModelOpt checkpoint, set `VLLM_MODEL` to the vLLM-native `RedHatAI/Qwen3-32B-NVFP4`
 and drop `--quantization` from the compose `command`.
+
+### Per-model notes
+
+Each runtime model has a doc under `docs/` recording how to run it, live test
+results, and caveats:
+
+- [`docs/qwen3-32b-nvfp4.md`](docs/qwen3-32b-nvfp4.md) — the **current** runtime
+  model (`nvidia/Qwen3-32B-NVFP4`), benchmarked on DGX Spark.
+- [`docs/qwen3.6-27b-nvfp4.md`](docs/qwen3.6-27b-nvfp4.md) — a **candidate**
+  (`mmangkad/Qwen3.6-27B-NVFP4`); architecture is supported by the current vLLM
+  image, live load-test pending.

docker-compose.yml

@@ -52,7 +52,7 @@ services:
       - --kv-cache-dtype=fp8
       - --max-model-len=${VLLM_MAX_MODEL_LEN:-32768}
       - --gpu-memory-utilization=${VLLM_GPU_MEM_UTIL:-0.6}
-      - --reasoning-parser=qwen3           # expose the <think> trace as reasoning_content (drop on older vLLM)
+      - --reasoning-parser=qwen3           # expose the <think> trace (field is `reasoning` on the nv26.04 build, `reasoning_content` on older vLLM; drop the flag on builds without the parser)
       - --enable-prefix-caching
       # NOTE: --trust-remote-code is intentionally omitted. Qwen3-32B-NVFP4 loads
       # without it; add it back only for a model whose repo ships custom modeling

docs/qwen3-32b-nvfp4.md

@@ -0,0 +1,79 @@
+# Runtime model: `nvidia/Qwen3-32B-NVFP4`
+
+lepenseur's **current runtime model**, served by local vLLM over the `acp`
+backend. Declared in `culture.yaml` as `vllm-local/nvidia/Qwen3-32B-NVFP4` and
+stood up by `docker-compose.yml`.
+
+## What it is
+
+- 32B **dense** reasoning model, quantized to **NVFP4** (NVIDIA ModelOpt FP4).
+- Native **32K** context (`max_model_len 32768`), extendable to ~131K via YaRN
+  rope scaling.
+- **Thinking mode:** emits a `<think>` reasoning trace before its answer — which
+  is why it suits a deep thinker.
+- Repo is **public** (no `HF_TOKEN` needed). ~20 GB on disk.
+
+## How to run
+
+```bash
+cp .env.example .env          # optional; set HF_TOKEN only for gated repos
+docker login nvcr.io          # NGC API key, to pull the vLLM image
+docker compose up -d
+docker compose logs -f vllm   # first run downloads ~20 GB of weights
+```
+
+Verify:
+
+```bash
+curl -fsS http://localhost:8000/health
+curl -s http://localhost:8000/v1/models   # lists nvidia/Qwen3-32B-NVFP4
+```
+
+Relevant compose flags: `--quantization=modelopt_fp4`, `--kv-cache-dtype=fp8`,
+`--reasoning-parser=qwen3`, `--enable-prefix-caching`,
+`--gpu-memory-utilization=0.6`. Tunables in `.env` (`VLLM_GPU_MEM_UTIL`,
+`VLLM_MAX_MODEL_LEN`, `HF_CACHE`, …).
+
+## Reading the reasoning trace
+
+> **Field name caveat.** On the `nvcr.io/nvidia/vllm:26.04-py3` build (engine
+> `0.19.0+...nv26.04`), `--reasoning-parser=qwen3` returns the `<think>` trace in
+> the message field **`reasoning`**, *not* `reasoning_content`. Clients (and any
+> acp `vllm-local` wiring) should read `message.reasoning`. Older vLLM builds use
+> `reasoning_content` — check the field name against your image.
+
+A reasoning model spends most of its tokens thinking, so give it room: a tight
+`max_tokens` can be consumed entirely inside the trace, leaving `content` empty
+with `finish_reason: length`.
+
+## Live test — 2026-05-27, DGX Spark (GB10)
+
+Verified end-to-end on the GB10 (121 GB unified memory). Served on port `8001`
+during the test (compose default is `8000`) to avoid a co-resident service.
+
+| Property | Value |
+|---|---|
+| Image / engine | `nvcr.io/nvidia/vllm:26.04-py3` / vLLM `0.19.0+...nv26.04` |
+| Weights on disk | ~20 GB |
+| GPU memory reserved | ~72 GB (`gpu-memory-utilization=0.6`; 74,136 MiB observed) |
+| Health / models | `/health` 200; `/v1/models` lists the model, `max_model_len 32768` |
+| Correctness | "14:45→17:10 = 145 min" ✅; "17 × 23 = 391" ✅, both with full reasoning trace |
+| **Decode throughput** | **~9.7 tok/s** (batch=1, greedy, 512 tokens forced; identical across 2 runs) |
+| **Prefill** | ~2,014 prompt tokens in ~0.7 s (~2,800 tok/s); 2.37 s incl. 16 decode tokens |
+
+Decode at ~10 tok/s reflects a 32B dense model on the GB10's low-power unified
+memory — adequate for a deliberate, write-by-thinking agent, not for
+high-throughput serving.
+
+### Known noise
+
+`env_file: .env` passes the compose-interpolation vars (`VLLM_MODEL`,
+`VLLM_PORT`, …) into the container, so vLLM logs harmless
+`Unknown vLLM environment variable detected: VLLM_*` warnings at startup. They do
+not affect serving.
+
+## Fallback
+
+If a vLLM build rejects the `nvidia/` ModelOpt checkpoint, set
+`VLLM_MODEL=RedHatAI/Qwen3-32B-NVFP4` and drop `--quantization` from the compose
+`command` (the RedHatAI checkpoint is vLLM-native).

docs/qwen3.6-27b-nvfp4.md

@@ -0,0 +1,87 @@
+# Candidate model: `mmangkad/Qwen3.6-27B-NVFP4`
+
+A candidate alternative runtime model. **Architecturally supported** by the
+vLLM image lepenseur already runs, but **not yet load-tested live** — see the
+benchmark plan below. Tracked by [issue #6](https://github.com/agentculture/lepenseur/issues/6).
+
+Source: <https://huggingface.co/mmangkad/Qwen3.6-27B-NVFP4> — public, Apache-2.0.
+
+## What it is
+
+- NVFP4 (NVIDIA ModelOpt) quantization of **`Qwen/Qwen3.6-27B`**.
+- `config.json`: `architectures: ["Qwen3_5ForConditionalGeneration"]`,
+  `model_type: qwen3_5`, 64 layers, `hidden_size 5120`,
+  `max_position_embeddings 262144` (**256K** context), multimodal RoPE
+  (`mrope_interleaved`, `mrope_section`).
+- ~20B effective params after compression; ~20 GB on disk (BF16 / F8_E4M3 / U8
+  tensors). ModelOpt producer `0.42.0rc1.dev107` (a dev/rc build).
+
+## Is it supported here? — Yes (architecture), pending live load
+
+The deciding check: query the **running** vLLM engine's model registry rather
+than guess.
+
+```text
+$ docker exec lepenseur-vllm python3 -c \
+  "from vllm.model_executor.models.registry import ModelRegistry; \
+   print('Qwen3_5ForConditionalGeneration' in ModelRegistry.get_supported_archs())"
+True
+```
+
+The `nvcr.io/nvidia/vllm:26.04-py3` image (engine `0.19.0+...nv26.04`) registers
+`Qwen3_5ForConditionalGeneration` (plus `Qwen3_5MoeForConditionalGeneration` and
+`Qwen3_5MTP`) — the exact architecture this checkpoint declares. The quant flag
+(`--quantization=modelopt_fp4`) and `--reasoning-parser=qwen3` are the same ones
+already working for the 32B. So the same compose can serve it.
+
+"Registered" means vLLM can instantiate the model class; it does not prove the
+weights load and serve cleanly. That requires the live load-test below.
+
+## How to run (same compose, model override)
+
+```bash
+# in .env
+VLLM_MODEL=mmangkad/Qwen3.6-27B-NVFP4
+VLLM_SERVED_NAME=mmangkad/Qwen3.6-27B-NVFP4   # must match culture.yaml's vllm-local/<name>
+# keep --quantization=modelopt_fp4 and --reasoning-parser=qwen3 (already in compose)
+docker compose up -d
+```
+
+Memory note: at 256K context the KV cache is large. Keep
+`VLLM_MAX_MODEL_LEN=32768` (or similar) for a first load; only raise it with
+headroom to spare. The GB10 has 121 GB unified memory total.
+
+## Caveats to validate during the load-test
+
+1. **SGLang is the blessed runtime.** The model card recommends `sglang serve`
+   (with `--tool-call-parser qwen3_coder`), not vLLM. vLLM support is present in
+   the registry but is not the card's documented path.
+2. **`ForConditionalGeneration` + multimodal RoPE.** The arch and `mrope` config
+   suggest a vision/multimodal lineage; text-only chat should still serve, but
+   confirm vLLM does not demand an image/processor path at load.
+3. **ModelOpt dev/rc producer** (`0.42.0rc1.dev107`) — verify the quant config
+   parses under this vLLM build.
+
+## Benchmark plan (to be filled when load-tested)
+
+Run the same methodology used for the 32B (see
+[`qwen3-32b-nvfp4.md`](qwen3-32b-nvfp4.md)) so the two are comparable:
+
+- Health + `/v1/models` reachable.
+- Correctness on the same two probes (train-times, `17 × 23`), confirming the
+  `reasoning` field populates.
+- Decode throughput: 512 tokens forced (`ignore_eos`), batch=1, greedy.
+- Prefill: ~2K-token prompt, 16-token gen.
+- Record image/engine version, weights-on-disk, and GPU memory reserved.
+
+| Property | Value |
+|---|---|
+| Decode throughput | _TBD_ |
+| Prefill | _TBD_ |
+| GPU memory reserved | _TBD_ |
+| Correctness | _TBD_ |
+
+### For comparison — 32B baseline (2026-05-27, GB10)
+
+~9.7 tok/s decode (batch=1), ~2,800 tok/s prefill, ~72 GB reserved at
+`gpu-memory-utilization=0.6`.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lepenseur"
-version = "0.2.0"
+version = "0.3.0"
 description = "lepenseur — the local thinking agent of the Culture mesh."
 readme = "README.md"
 license = "MIT"