Fabella Phase 2: add read aloud and redesign frontend

AGENTS.md

@@ -4,7 +4,61 @@ Quick orientation for future OpenCode sessions working on Fabella.
 
 ## What this is
 
-A Gradio app that generates personalized children's stories. Phase 1 ships with a template-based mock generator (default) and a wired-but-unpolished real-model path on ZeroGPU. Single HF Space, no DB, no auth.
+A Gradio app for **parents who need to explain hard things to their child
+in kid-appropriate language**. The parent types a sentence or two about
+the situation; Fabella drafts a short explanation (Opener / Body /
+Closer / optional follow-up) that's reviewed by a second small model
+before the parent sees it. After generation, the parent can optionally
+click **Read aloud** to synthesize the explanation with VoxCPM2.
+
+Built for the [Build Small Hackathon](https://huggingface.co/spaces/build-small-hackathon/README) · **Track I · Backyard AI** ("useful for someone the maker actually knows").
+
+The product design has two distinct execution layers, each tuned to its job:
+
+- **Drafter on LangGraph.** The drafter is a `create_agent` ReAct loop
+  with one tool (`validate_explanation`) and a custom middleware. State
+  machine, conditional edges, tool-call plumbing — that's LangGraph's
+  job, and it works.
+- **Judge on Pydantic.** The judge task is bounded — one rubric, one
+  draft, one structured verdict. No loop, no tools, no state machine.
+  Single `llm.invoke()` + `JudgeVerdict.model_validate_json()` + one
+  repair retry. Cross-field consistency is enforced in code.
+
+## Architecture
+
+```
+                    HF Space (CPU, custom HTML+CSS+JS)
+                                   |
+                                   |  POST /gradio_api/call/make_explanation
+                                   |  <-  SSE stream with 4-section string
+                                   v
+                         app.py (gradio.Server / FastAPI)
+                                   |
+              +--------------------+--------------------+--------------------+
+              |                                         |                    |
+              v                                         v                    v
+   Modal drafter (A10G, Gemma 4 E4B-IT)     Modal judge (A10G, Nemotron-3)  Modal TTS (A10G, VoxCPM2)
+   --tool-call-parser gemma4                (no tool-calling flags)         FastAPI /synthesize
+   ReAct via LangChain                      Pydantic JSON verdict          audio/wav when requested
+   validate_explanation tool                one invoke + one repair retry
+   middleware jumps to "end" on OK
+```
+
+- HF Space env vars: `MODAL_DRAFTER_URL`, `MODAL_JUDGE_URL`, and `MODAL_TTS_URL`.
+- Modal uses the `nvidia/cuda:12.9.0-devel-ubuntu22.04` base image (provides nvcc for FlashInfer).
+- Drafter vLLM flags: `--language-model-only --enable-auto-tool-choice --tool-call-parser gemma4`.
+- Judge vLLM flags: none (the judge emits raw JSON in `content`; Pydantic parses).
+- TTS is separate from drafter/judge and only called from `make_audio` when the user clicks **Read aloud**.
+- `scaledown_window=10` minutes on all serves.
+
+## Live URLs
+
+- HF Space: https://build-small-hackathon-fabella.hf.space
+- Modal drafter: https://khoitruong071510--fabella-serve-drafter.modal.run
+- Modal judge: https://khoitruong071510--fabella-serve-judge.modal.run
+- Modal TTS: https://khoitruong071510--fabella-serve-tts.modal.run
+- Modal app: https://modal.com/apps/khoitruong071510/main/deployed/fabella
+- HF Space repo: https://huggingface.co/spaces/build-small-hackathon/Fabella
 
 ## Run / verify
 
@@ -16,36 +70,150 @@ uv pip install --python .venv/bin/python -r requirements.txt
 .venv/bin/python app.py   # http://localhost:7860
 ```
 
-`app.py` is the only entrypoint. No test suite exists yet (was deferred from Phase 1 plan).
+The custom frontend runs on CPU locally. For story generation to work,
+the `MODAL_DRAFTER_URL`, `MODAL_JUDGE_URL`, and `MODAL_TTS_URL` env vars
+must point to live Modal deploys. Use the deployed HF Space for
+end-to-end testing.
+
+`app.py` is the only entrypoint. No test suite exists yet.
 
 ## File map
 
-- `app.py` — Gradio Blocks UI, form handler, launch
-- `generator.py` — dispatcher; reads `USE_MOCK` at import time, routes to `mock.py` or `real.py`
-- `mock.py` — template-based generator. One `THEMES: dict[theme][bucket] = (primary, alt)` table (8 themes × 3 buckets × 2 variants = 48 templates). `_select(theme, age, seed)` picks primary on even seed, alt on odd. Adding a new theme = one new key in `THEMES` + an entry in `THEME_CHOICES` in `app.py`.
-- `real.py` — real-model call. `@spaces.GPU` is applied **lazily** via `_get_run_gpu()` so the module imports cleanly even when `spaces` is not installed (mock path stays the default).
-- `prompts.py` — system + user prompt builders (used only by `real.py`)
-- `safety.py` — input sanitization, profanity block, length/age helpers
-- `schema.py` — `StoryRequest` dataclass
-- `README.md` — has HF Space YAML frontmatter; the Space builder reads `sdk_version: 4.44.0` from there, not from local install
+- `app.py` — `gradio.Server` (FastAPI subclass) app. Imports `FabellaVLLM` from `llm.py` and calls `run_agent` from `agent.py`. Serves a hand-coded HTML+CSS+JS page. `@app.api()` endpoint `make_explanation` returns Opener/Body/Closer/Follow-up joined by U+001F. `make_audio` proxies VoxCPM2 and returns a base64 WAV data URL. Contains a no-op `@spaces.GPU` placeholder function (HF Spaces runtime scans for at least one during import; all inference runs on Modal).
+- `agent.py` — LangChain ReAct agent. `build_agent(llm, req, judge_llm=None)` returns `(agent, user_prompt)`. One tool: `validate_explanation` (calls the Pydantic judge if `judge_llm` is given, else falls back to a rule check). `FabellaAgentMiddleware.before_model` jumps to `end` once validation passes or after `max_tool_calls=2`. `extract_explanation(messages)` parses the four sections from the validated tool-call draft.
+- `judge.py` — Pydantic-validated judge. `judge_explanation(llm, draft, req_age, req_tone, child_name, situation) -> JudgeVerdict`. Two attempts (original + repair prompt) before raising `JudgeFailed` for fallback. Tolerant of markdown fences and pretty-printed JSON.
+- `schema.py` — `ExplainRequest` dataclass (situation, age, child_name, tone, seed), `JudgeVerdict` Pydantic model (ok, issues, score, verdict, reasoning), `JudgeFailed` exception.
+- `safety.py` — input sanitization (`sanitize_situation`, `sanitize_name`, `has_profanity`), `explain_to_words(tone)`, `age_bucket(age)`.
+- `llm.py` — `FabellaVLLM`, a `BaseChatModel` subclass wrapping vLLM's OpenAI-compatible API. `bind_tools` builds an OpenAI-spec `tools=[...]` payload, `_generate` passes it on the request and reads `response.choices[0].message.tool_calls` from the response. Replay of prior `AIMessage.tool_calls` and `ToolMessage` results into next-turn messages uses the OpenAI chat-completions shape.
+- `modal_app.py` — Modal deployment. `download_drafter`, `download_judge`, and `download_tts` write weights to the `fabella-models` Volume. `serve_drafter` runs vLLM with `--language-model-only --enable-auto-tool-choice --tool-call-parser gemma4` on port 8000 (A10G). `serve_judge` runs vLLM with no tool-calling flags on port 8001 (A10G). `serve_tts` runs a tiny VoxCPM2 FastAPI app on port 8002 (A10G). One Modal app, three web_server functions.
+- `modal_app_gemma.py` — Legacy single-model Modal deploy from the previous session. Not the live deploy. Reference only.
 
 ## Non-obvious gotchas
 
-- **`sys.path` hack in every module.** Each file does `sys.path.insert(0, os.path.dirname(...))` so imports work when run as `python app.py` from the package root. Don't refactor to relative imports — they break the entrypoint.
-- **`USE_MOCK` is module-level.** Read once at import. Toggling the env var requires a process restart.
-- **Gradio 6 moved `theme=` from `Blocks(...)` to `launch(...)`.** If you upgrade Gradio and see a `UserWarning`, check `app.py:139`.
-- **`FABELLA_MODEL_ID` env var** overrides the default `google/gemma-4-E4B-it` slug in `real.py`. **Verified open (Apache 2.0, not gated).** Gemma 4 uses `AutoProcessor` (not `AutoTokenizer`) and supports `enable_thinking=False` for direct, non-reasoning output — keep it disabled for children's stories. Recommended sampling: `temperature=1.0, top_p=0.95, top_k=64`. Do NOT swap to `gemma-3-4b-it` (it's gated and would break the no-API-key rule).
-- **Real-model path is best-effort.** On any failure (no GPU, missing dep, model 404), it returns a user-visible "real model unavailable" message — it does NOT silently fall back to mock.
-- **No test directory.** The Phase 1 plan included `tests/` but it was not built. Add one if/when a verification pass is needed.
-- **HF Space metadata in README.** `sdk_version: 4.44.0` is the version the Space runtime builds against, not your local `pip show gradio` (currently 6.17.3). They can diverge safely.
+- **No-op `@spaces.GPU` in `app.py`.** The HF Spaces runtime scans for
+  at least one `@spaces.GPU` function at module import and raises
+  `RUNTIME_ERROR: No @spaces.GPU function detected` if none exists.
+  The placeholder is a 1-second no-op. Do not delete it.
+- **`sys.path` hack in every module.** Each file does
+  `sys.path.insert(0, os.path.dirname(...))` so imports work when run
+  as `python app.py` from the package root. Don't refactor to relative
+  imports.
+- **Pydantic disallows `_`-prefixed fields.** In `llm.py`, the
+  runtime-mutable state (OpenAI client, tools, call counter) is
+  declared with `PrivateAttr`, not `Field`.
+- **Three Modal endpoints, three env vars.** HF Space reads
+  `MODAL_DRAFTER_URL`, `MODAL_JUDGE_URL`, and `MODAL_TTS_URL`. The old
+  `MODAL_VLLM_URL` is dead — delete it if it's still there.
+- **The drafter uses native tool calling via vLLM.** vLLM is started
+  with `--enable-auto-tool-choice --tool-call-parser gemma4`; the
+  server parses Gemma 4's native `<|tool_call|>call:name{args}<tool_call|>`
+  markers into OpenAI-spec `tool_calls` JSON. The client passes real
+  `tools=[{type:"function", function:{name, description,
+  parameters:JSON-schema}}]` on each request and reads
+  `response.choices[0].message.tool_calls` directly. If the model
+  emits no tool call, `content` is returned as the final answer.
+- **The judge does NOT use tool calling.** Nemotron-3-Nano-4B's chat
+  template emits tool calls in a custom XML dialect inside
+  `<tool_call>...</tool_call>` markers that vLLM's built-in parsers
+  don't recognize. The judge server runs with no tool-calling flags;
+  the judge prompt asks for raw JSON in `content`, and `judge.py`
+  parses that with Pydantic.
+- **Pydantic judge schema in `schema.py`.** `JudgeVerdict` has five
+  fields: `ok` (bool), `issues` (list[str], each capped at 200 chars),
+  `score` (float in [0, 1]), `verdict` (Literal["approve", "revise"]),
+  `reasoning` (str, capped at 300 chars). Cross-field consistency
+  (`ok` ⇔ `verdict`) is enforced in `judge_explanation()` — the model
+  is asked to agree, and the code normalizes if it doesn't.
+- **Judge retry-on-failure.** If the first response isn't parseable
+  JSON, `judge_explanation()` retries once with a `REPAIR_PROMPT` that
+  shows the previous bad response. If both fail, `JudgeFailed` is
+  raised and the validate tool falls back to the rule check.
+- **`@app.api` returns a single string.** Gradio Server's `@app.api`
+  has no output components, so tuples get dropped silently. The
+  handler concatenates the four sections with `\x1f` (Unit Separator)
+  and the frontend splits. Don't use `\n` as a separator — body text
+  can contain newlines legitimately.
+- **Middleware `@hook_config(can_jump_to=["end"])` is required.**
+  Without it, LangGraph never creates the conditional edge and the
+  early-exit silently does nothing.
+- **Modal uses CUDA devel image.** The `nvidia/cuda:12.9.0-devel-ubuntu22.04`
+  base provides nvcc, which vLLM/FlashInfer need. `debian_slim` crashes
+  during vLLM startup.
+- **Drafter flag `--language-model-only` is required.** Gemma 4's
+  multimodal processor pulls heavy deps and crashes the vLLM server
+  on text-only requests. This flag tells vLLM to skip processor init.
+  The judge (Nemotron-Nano-4B) is text-only and does NOT need this
+  flag.
+- **Gemma 4 E4B is multimodal — it can take audio input.** This
+  matters in two ways:
+  1. `--language-model-only` is correct **today** because Fabella's
+     drafter only ever receives text. If you later add a feature
+     where the parent records a 30s voice memo and the drafter
+     transcribes it (Whisper-style), the vLLM flag will need to
+     change to support audio inputs. The model supports it natively.
+  2. The audio side of Gemma 4 is a *separate* path from the
+     VoxCPM2 TTS endpoint. They are independent: VoxCPM2 reads
+     text and produces 48 kHz audio; Gemma 4 could (if enabled)
+     read audio and produce text. Don't conflate them when
+     debugging.
+- **All A10Gs are independent.** Modal `scaledown_window=10` minutes
+  on each. The first request after idle triggers a ~2 min cold start
+  per LLM container. TTS cold-starts only after **Read aloud** is clicked.
+- **VoxCPM2 TTS is not vLLM.** `serve_tts` writes a generated FastAPI
+  server into the container and runs `uvicorn`. It returns `audio/wav`
+  from `/synthesize`; `app.py::make_audio` converts that to a base64
+  data URL for the browser.
+- **`FABELLA_MODEL_PATH` env var** is no longer consulted on the
+  deployed path. Modal's `download_drafter` hardcodes
+  `google/gemma-4-E4B-it` (Apache 2.0, not gated). Do not swap to
+  `gemma-3-4b-it` (gated — would break the no-API-key rule).
 
 ## When editing
 
-- Adding a new theme → add one key to `THEMES` in `mock.py` (with all three buckets) + an entry in `THEME_CHOICES` in `app.py`.
-- Adding a moral preset → `MORAL_PRESETS` in `app.py`.
-- Changing age rules → `age_bucket()` in `safety.py` and the vocab rules in `prompts.py` (real model path) must stay in sync.
-- PDF export, accounts, history, audio, images are **out of scope** unless the user reopens Phase 2.
+- Adding a new tone preset → add to `TONE_CHOICES` in `app.py`
+  (gentle / matter-of-fact / playful is the current set).
+- Adding an example situation → add to `EXAMPLE_SITUATIONS` in
+  `app.py`. They appear as one-click chips on the left column.
+- Changing the drafter's tool set → edit `make_validate_tool` in
+  `agent.py` (it builds the tool closure per request).
+- Changing the judge's rubric → edit `judge.py::_build_rubric` and the
+  `SYSTEM_PROMPT` in the same file. The output schema is in
+  `schema.py::JudgeVerdict` — change both.
+- Changing the agent's max tool calls → pass
+  `FabellaAgentMiddleware(max_tool_calls=N)` to `create_agent` in
+  `agent.py::build_agent`.
+- Adding a new example chip → add to `EXAMPLE_SITUATIONS` in
+  `app.py`.
+- History, accounts, image upload are **out of scope** unless reopened.
 
 ## Deployment
 
-Push to a HF Space with Gradio SDK; no secrets required for first boot (mock mode). To activate the real model, set `USE_MOCK=false` in the Space's Variables & Secrets tab.
+```bash
+# Modal: download weights (run once per model)
+.venv/bin/modal run modal_app.py::download_drafter
+.venv/bin/modal run modal_app.py::download_judge
+.venv/bin/modal run modal_app.py::download_tts
+
+# Modal: deploy (rebuilds image, rolls out both web_servers)
+.venv/bin/modal deploy modal_app.py
+
+# HF Space: env vars
+hf spaces variables add build-small-hackathon/Fabella \
+    --env MODAL_DRAFTER_URL=https://khoitruong071510--fabella-serve-drafter.modal.run
+hf spaces variables add build-small-hackathon/Fabella \
+    --env MODAL_JUDGE_URL=https://khoitruong071510--fabella-serve-judge.modal.run
+hf spaces variables add build-small-hackathon/Fabella \
+    --env MODAL_TTS_URL=https://khoitruong071510--fabella-serve-tts.modal.run
+
+# HF Space: upload code
+hf upload build-small-hackathon/Fabella app.py    --type space
+hf upload build-small-hackathon/Fabella agent.py  --type space
+hf upload build-small-hackathon/Fabella judge.py  --type space
+hf upload build-small-hackathon/Fabella llm.py    --type space
+hf upload build-small-hackathon/Fabella schema.py --type space
+hf upload build-small-hackathon/Fabella safety.py --type space
+hf upload build-small-hackathon/Fabella requirements.txt --type space
+
+# HF Space: restart to pick up new code
+hf spaces restart build-small-hackathon/Fabella
+```

HANDOFF.md

@@ -0,0 +1,278 @@
+# Fabella Handoff — Explanation + Read-Aloud Pipeline on Modal
+
+## Context
+
+Fabella is a Gradio children's-storytelling app in `/home/khoi/fabella`,
+now **pivoted to Track I · Backyard AI** ("useful for someone the maker
+actually knows"). It solves a specific real problem parents face: **how
+do I explain a hard thing to my kid in their own language?**
+
+The parent describes a situation in a sentence or two. Fabella drafts a
+short, kind, age-appropriate explanation in an Opener / Body / Closer /
+follow-up shape. A second small model checks the draft against a
+6-criterion rubric before the parent sees it. After generation, the
+parent can optionally click **Read aloud** to synthesize the explanation
+with VoxCPM2.
+
+**Live URLs:**
+
+- HF Space: https://build-small-hackathon-fabella.hf.space
+- Modal drafter (Gemma 4 E4B-IT): https://khoitruong071510--fabella-serve-drafter.modal.run
+- Modal judge (Nemotron-3 Nano 4B): https://khoitruong071510--fabella-serve-judge.modal.run
+- Modal TTS (VoxCPM2): https://khoitruong071510--fabella-serve-tts.modal.run
+- Modal app: https://modal.com/apps/khoitruong071510/main/deployed/fabella
+- HF Space repo: https://huggingface.co/spaces/build-small-hackathon/Fabella
+
+## Current Architecture
+
+```
+                    HF Space (CPU, custom HTML+CSS+JS)
+                                   |
+                                   |  POST /gradio_api/call/make_explanation
+                                   |  -> SSE stream with 4-section string
+                                   v
+                         app.py (gradio.Server / FastAPI)
+                                   |
+              +--------------------+--------------------+--------------------+
+              |                                         |                    |
+              v                                         v                    v
+   Modal drafter (A10G, Gemma 4 E4B-IT)     Modal judge (A10G, Nemotron-3)  Modal TTS (A10G, VoxCPM2)
+   --tool-call-parser gemma4                (no tool-calling flags)         FastAPI /synthesize
+   ReAct via LangChain                      Pydantic JSON verdict          audio/wav when requested
+   validate_explanation tool                one invoke + one repair retry
+   middleware jumps to "end" on OK
+```
+
+**Key design decisions:**
+
+- **Drafter on LangGraph.** The drafter is a `create_agent` ReAct loop
+  with one tool (`validate_explanation`) and a custom middleware that
+  jumps to `end` after a successful validation or after a hard cap of
+  two tool calls. State machine, conditional edges, tool-call plumbing
+  — that's LangGraph's job, and it works.
+- **Judge on Pydantic.** The judge task is bounded — one rubric, one
+  draft, one structured verdict — so it doesn't need an agent loop.
+  Single `llm.invoke()` + `JudgeVerdict.model_validate_json()` + one
+  repair retry. Cross-field consistency (`ok` ⇔ `verdict`) is enforced
+  in code, not in the prompt.
+- **Three separate Modal web_servers, three A10Gs.** Drafter, judge,
+  and TTS don't share a GPU. Independent scaling, independent
+  `scaledown_window`.
+- **TTS only runs on demand.** VoxCPM2 is a separate FastAPI wrapper,
+  not vLLM. The HF Space `make_audio` API posts explanation text to
+  `/synthesize`, receives `audio/wav`, and returns a base64 data URL to
+  the browser.
+- **The judge has NO tool-calling flags on the server side.** Its
+  prompt asks for raw JSON in `content`; the Pydantic parser does the
+  rest. This dodges Nemotron-3-Nano's chat-template tool-dialect
+  (`<tool_call>...</tool_call>` markers that vLLM's `hermes` parser
+  doesn't recognize) entirely.
+- **The drafter DOES use tool calling.** vLLM is launched with
+  `--enable-auto-tool-choice --tool-call-parser gemma4`; the server
+  parses Gemma 4's `<|tool_call|>...<tool_call|>` markers into
+  OpenAI-spec `tool_calls` JSON, which the client reads off
+  `response.choices[0].message.tool_calls` directly.
+- **HF Space runs a custom `gradio.Server` (FastAPI subclass).** No
+  default Gradio chrome. Storybook design, single hand-coded page.
+- **API contract for the frontend:** the @app.api endpoint returns one
+  string with sections joined by U+001F (Unit Separator) — Opener,
+  Body, Closer, Follow-up. The frontend splits on that. (Gradio Server
+  `@app.api` has no output components, so tuples get dropped — single
+  string is the simplest workaround.)
+
+## File Map
+
+| File | Purpose |
+|------|---------|
+| `app.py` | `gradio.Server` (FastAPI subclass) app, custom HTML+CSS+JS, `make_explanation` API, `make_audio` TTS proxy, no-op `@spaces.GPU` placeholder for HF runtime |
+| `agent.py` | LangChain ReAct agent. `build_agent(llm, req, judge_llm=None)` returns `(agent, user_prompt)`. `make_validate_tool` builds a closure that calls `judge_explanation()` if a judge is given, else falls back to a rule check. `FabellaAgentMiddleware.before_model` jumps to `end` once validation passes or after `max_tool_calls=2`. `extract_explanation(messages)` parses Opener/Body/Closer/follow-up sections from the validated tool-call draft. |
+| `judge.py` | Pydantic-validated judge. `judge_explanation(llm, draft, req_age, req_tone, child_name, situation) -> JudgeVerdict`. Two attempts (original + repair prompt) before raising `JudgeFailed` for fallback. Tolerant of markdown fences and pretty-printed JSON. |
+| `schema.py` | `ExplainRequest` dataclass + `JudgeVerdict` Pydantic model + `JudgeFailed` exception. |
+| `safety.py` | Input sanitization, profanity block, `sanitize_situation`, `explain_to_words(tone)`, `age_bucket(age)`. |
+| `llm.py` | `FabellaVLLM` BaseChatModel wrapping vLLM's OpenAI-compatible API. `bind_tools` builds OpenAI-spec `tools=[...]`, `_generate` passes it and reads `message.tool_calls` from the response. Replay of prior `AIMessage.tool_calls` and `ToolMessage` results into next-turn messages uses the OpenAI chat-completions shape. |
+| `modal_app.py` | Modal deployment: `download_drafter` + `download_judge` + `download_tts`; `serve_drafter` (port 8000), `serve_judge` (port 8001), `serve_tts` (port 8002). One A10G each. |
+| `modal_app_gemma.py` | Legacy: a previous-session single-model Modal deploy, kept for reference. Not the live deploy. |
+
+## What Changed This Session
+
+The most recent session (pivot to Backyard AI) changed:
+
+### New files
+- `judge.py` — Pydantic-validated judge with repair retry
+- `modal_app_gemma.py` — kept as reference for the prior single-model deploy
+
+### Substantially rewritten
+- `agent.py` — story-generation agent replaced with explanation-generation agent. `make_validate_tool` now optionally takes `judge_llm` and routes through `judge_explanation()`. The drafter's output format changed from "Title: / body" to "Opener: / Body: / Closer: / (optional) If they ask more:". `extract_explanation` parses these four sections.
+- `schema.py` — `StoryRequest` replaced with `ExplainRequest` (situation, age, child_name, tone, seed). Added `JudgeVerdict` (Pydantic) and `JudgeFailed`.
+- `safety.py` — `sanitize_situation`, `explain_to_words(tone)`. Legacy theme/moral/length functions kept for compat.
+- `app.py` — frontend redesigned for the "explain a hard thing" use case. New form fields: situation textarea, age slider (5-12), child_name (optional), tone segmented control (gentle / matter-of-fact / playful), example chips. Output is the four sections in a book-page layout with the new "Opener" / "The explanation" / "Closer" / "If they ask another question" tags. Added **Read aloud** with `make_audio` proxy to VoxCPM2.
+- `modal_app.py` — three web_servers in one Modal app. Drafter uses `--tool-call-parser gemma4`; judge uses no tool flags; TTS runs VoxCPM2 behind FastAPI `/synthesize`.
+- `llm.py` — defaults updated to point at the drafter endpoint (`gemma-4` model name).
+
+### Removed earlier
+- `multi_agent.py` — earlier multi-agent design (3 parallel drafters + judge) was reverted
+- `nemotron3_tool_parser.py` — custom XML tool parser for the (also removed) 30B Nemotron path
+- `prompts.py`, `generator.py`, `mock.py`, `real.py` — legacy files
+
+## Non-obvious gotchas
+
+- **No-op `@spaces.GPU` in `app.py`.** HF Spaces runtime scans for at
+  least one `@spaces.GPU` function at import and raises
+  `RUNTIME_ERROR: No @spaces.GPU function detected` if none exists.
+  The placeholder is a 1-second no-op. Do not delete it.
+- **`sys.path` hack in every module.** Each file does
+  `sys.path.insert(0, os.path.dirname(...))` so imports work when run
+  as `python app.py` from the package root. Don't refactor to relative
+  imports.
+- **Pydantic disallows `_`-prefixed fields.** In `llm.py`, the
+  runtime-mutable state (OpenAI client, tools, call counter) is
+  declared with `PrivateAttr`, not `Field`.
+- **Three Modal endpoints, three env vars.** HF Space reads
+  `MODAL_DRAFTER_URL`, `MODAL_JUDGE_URL`, and `MODAL_TTS_URL`. The old
+  `MODAL_VLLM_URL` is dead — delete it if it's still there.
+- **The drafter uses native tool calling via vLLM.** vLLM is started
+  with `--enable-auto-tool-choice --tool-call-parser gemma4`; the
+  server parses Gemma 4's native `<|tool_call|>call:name{args}<tool_call|>`
+  markers into OpenAI-spec `tool_calls` JSON. The client passes real
+  `tools=[{type:"function", function:{name, description,
+  parameters:JSON-schema}}]` on each request and reads
+  `response.choices[0].message.tool_calls` directly. If the model
+  emits no tool call, `content` is returned as the final answer.
+- **The judge does NOT use tool calling.** The chat template for
+  Nemotron-3-Nano-4B emits tool calls in a custom XML dialect inside
+  `<tool_call>...</tool_call>` markers that vLLM's built-in parsers
+  don't recognize. The judge server runs with no tool-calling flags;
+  the judge prompt asks for raw JSON in `content`, and `judge.py`
+  parses that with Pydantic.
+- **Pydantic judge schema in `schema.py`.** `JudgeVerdict` has five
+  fields: `ok` (bool), `issues` (list[str], each capped at 200 chars),
+  `score` (float in [0, 1]), `verdict` (Literal["approve", "revise"]),
+  `reasoning` (str, capped at 300 chars). Cross-field consistency
+  (`ok` ⇔ `verdict`) is enforced in `judge_explanation()` — the model
+  is asked to agree, and the code normalizes if it doesn't.
+- **Judge retry-on-failure.** If the first response isn't parseable
+  JSON, `judge_explanation()` retries once with a `REPAIR_PROMPT` that
+  shows the previous bad response. If both fail, `JudgeFailed` is
+  raised and the validate tool falls back to the deterministic rule
+  check.
+- **Middleware `@hook_config(can_jump_to=["end"])` is required.**
+  Without it, LangGraph never creates the conditional edge and the
+  early-exit silently does nothing.
+- **Modal uses CUDA devel image.** The `nvidia/cuda:12.9.0-devel-ubuntu22.04`
+  base provides nvcc, which vLLM/FlashInfer need. `debian_slim` crashes
+  during vLLM startup.
+- **Drafter flag `--language-model-only` is required.** Gemma 4's
+  multimodal processor pulls heavy deps and crashes the vLLM server on
+  text-only requests. This flag tells vLLM to skip processor init.
+  The judge (Nemotron-Nano-4B) is text-only and does NOT need this
+  flag.
+- **Gemma 4 E4B is multimodal — it can take audio input.** This
+  matters in two ways:
+  1. `--language-model-only` is correct **today** because Fabella's
+     drafter only ever receives text. If you later add a feature
+     where the parent records a 30s voice memo and the drafter
+     transcribes it (Whisper-style), the vLLM flag will need to
+     change to support audio inputs. The model supports it natively.
+  2. The audio side of Gemma 4 is a *separate* path from the
+     VoxCPM2 TTS endpoint. They are independent: VoxCPM2 reads
+     text and produces 48 kHz audio; Gemma 4 could (if enabled)
+     read audio and produce text. Don't conflate them when
+     debugging.
+- **All A10Gs are independent.** Modal scaledown_window is 10 minutes
+  on each. The first request after idle triggers a ~2 min cold start per
+  LLM container. TTS cold-starts only after **Read aloud** is clicked.
+- **VoxCPM2 TTS is not vLLM.** `serve_tts` writes a generated FastAPI
+  server into the container and runs `uvicorn --app-dir /root`. It
+  returns `audio/wav` from `/synthesize`; `app.py::make_audio` converts
+  that to a base64 data URL for the browser.
+- **`section_sep` is U+001F (Unit Separator).** The `@app.api`
+  endpoint returns Opener, Body, Closer, Follow-up joined by `\x1f`.
+  The frontend splits on it. Don't use `\n` — body text can contain
+  newlines legitimately.
+- **`FABELLA_MODEL_PATH` env var** is no longer consulted on the
+  deployed path. Modal's `download_drafter` hardcodes
+  `google/gemma-4-E4B-it` (Apache 2.0, not gated). Do not swap to
+  `gemma-3-4b-it` (gated — would break the no-API-key rule).
+
+## Deployment Commands
+
+```bash
+# Modal: download weights (run once per model)
+.venv/bin/modal run modal_app.py::download_drafter
+.venv/bin/modal run modal_app.py::download_judge
+.venv/bin/modal run modal_app.py::download_tts
+
+# Modal: deploy (rebuilds the image, rolls out all web_servers)
+.venv/bin/modal deploy modal_app.py
+
+# HF Space: env vars
+hf spaces variables add build-small-hackathon/Fabella \
+    --env MODAL_DRAFTER_URL=https://khoitruong071510--fabella-serve-drafter.modal.run
+hf spaces variables add build-small-hackathon/Fabella \
+    --env MODAL_JUDGE_URL=https://khoitruong071510--fabella-serve-judge.modal.run
+hf spaces variables add build-small-hackathon/Fabella \
+    --env MODAL_TTS_URL=https://khoitruong071510--fabella-serve-tts.modal.run
+
+# HF Space: upload code
+hf upload build-small-hackathon/Fabella app.py    --type space
+hf upload build-small-hackathon/Fabella agent.py  --type space
+hf upload build-small-hackathon/Fabella judge.py  --type space
+hf upload build-small-hackathon/Fabella llm.py    --type space
+hf upload build-small-hackathon/Fabella schema.py --type space
+hf upload build-small-hackathon/Fabella safety.py --type space
+hf upload build-small-hackathon/Fabella requirements.txt --type space
+
+# HF Space: restart to pick up new code
+hf spaces restart build-small-hackathon/Fabella
+```
+
+## Cost
+
+- **Drafter**: 1× A10G, $0.80/hr, 10-min scaledown
+- **Judge**: 1× A10G, $0.80/hr, 10-min scaledown
+- **TTS**: 1× A10G, $0.80/hr, 10-min scaledown, only after **Read aloud**
+- **At idle**: $0/hr (scaledown)
+- **Typical demo session**: a few minutes warm = ~$0.03-0.05
+
+## Known Issues / Open Questions
+
+1. **Cold start latency** — First request after 10 min idle triggers
+   vLLM cold start (~2 min per container for model load + torch.compile
+   + CUDA graph capture). Both containers cold-start in sequence on
+   the first request of a new session. Could add `min_containers=1` to
+   each Modal serve() to keep warm (costs ~$1.60/hr idle).
+2. **No test suite** — No automated tests exist. Manual smoke-tests
+   are in this handoff (search "Live test" or "Smoke-test").
+3. **Judge occasionally emits unparseable thinking-traces.** The
+   `judge_explanation()` repair prompt fixes this most of the time.
+   When both attempts fail, the validate tool falls back to the
+   rule check, so the system never hard-errors. The model is a
+   reasoning model; a `--default-chat-template-kwargs '{"enable_thinking":
+   false}'` flag could be added to the judge server to make outputs
+   shorter, but the retry handles it well enough.
+4. **Drafter at temperature 0.9** — produces creative variety but the
+   judge sometimes rejects a perfectly good draft on style grounds. The
+   `seed` UI control lets parents re-roll for variety.
+
+## Suggested Skills
+
+- `hf-cli` — Manage HF Space: variables, logs, uploads, restarts
+- `find-docs` — For Modal, vLLM, Gradio, LangChain, Pydantic API
+  questions (use ctx7 CLI)
+- `diagnose` — If runtime errors occur (vLLM startup, agent failures,
+  judge parsing)
+- `agent-browser` — For end-to-end testing of the live HF Space
+- `handoff` — If handing off again after further work
+
+## Next Steps (if continuing)
+
+1. Add a `min_containers=1` warmup to both Modal serves for zero
+   cold-start latency
+2. Add basic test suite: judge parsing (valid / repair / fallback),
+   validate tool, explanation extraction, end-to-end agent with stubs
+3. Stream the explanation token-by-token as the drafter writes it
+   (the API contract would change from one-shot to SSE)
+4. Cache common patterns (the same situation often comes up — "moving",
+   "new baby", "death of grandparent") so warm requests skip the LLM
+5. Polish the HF Space card README to match the new Backyard AI
+   framing before the hackathon submission deadline

README.md

@@ -1,63 +1,96 @@
 ---
 title: Fabella
 emoji: 📖
-colorFrom: pink
+colorFrom: green
 colorTo: yellow
 sdk: gradio
-sdk_version: 4.44.0
+sdk_version: 6.18.0
 app_file: app.py
-pinned: false
+pinned: true
+license: apache-2.0
+short_description: Small words for big questions.
 ---
 
 # Fabella
 
-A personalized storytelling companion for children. Tell Fabella your child's name, age, favorite themes, and a moral — Fabella writes a warm, age-appropriate story just for them.
+**Small words for big questions.** Tell Fabella what's going on in a sentence or two. She drafts a short, kind, age-appropriate explanation you can read aloud — a second small model checks it against a six-criterion rubric before you see it.
 
-## What it does
+Built for the [Build Small Hackathon](https://huggingface.co/spaces/build-small-hackathon/README) · **Track I · Backyard AI.**
 
-- Generates a short, personalized children's story
-- Matches reading level to the child's age (6–10)
-- Weaves in their favorite themes
-- Resolves a clear moral at the end
-- Works on first run with **no API key** (mock mode)
+[Live demo](https://build-small-hackathon-fabella.hf.space) · [Modal app](https://modal.com/apps/khoitruong071510/main/deployed/fabella) · [HF Space repo](https://huggingface.co/spaces/build-small-hackathon/Fabella)
 
-## Run locally
+## What it solves
 
-```bash
-uv venv .venv
-source .venv/bin/activate
-uv pip install -r requirements.txt
-python app.py
-```
+Parents have to explain hard things — a parent's hospitalization, a house move, a pet dying, a refusal to buy a phone — to kids who don't have the vocabulary for what's happening. Most of the time, we end up improvising at 9pm and getting it half-right.
+
+Fabella is a second pair of eyes. You describe the situation in a sentence or two; the app drafts an explanation in the **Opener → Body → Closer → optional "if they ask more"** shape, then a second small model checks it for: opener/body/closer present, body length, age-appropriate vocabulary, no moralizing, no scary content, no invented facts.
+
+You read it. If it's good, you can read it yourself or click **Read aloud** for VoxCPM2 narration. If it's not, you click **New version** for a fresh draft.
+
+## The two-model pipeline
+
+| Layer | Model | Why this model | Why this execution |
+|---|---|---|---|
+| **Drafter** | `google/gemma-4-E4B-it` (4B) on Modal A10G | Fast, smart enough for short empathetic text, Apache 2.0 | **LangGraph ReAct** — needs the state machine (draft → validate → revise → end) with tool calling and middleware-driven early exit |
+| **Judge** | `nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16` (4B) on Modal A10G | Fast, follows structured-output instructions reliably | **Pydantic** + single LLM call + one repair retry — the task is bounded, no agent loop needed |
+| **Read-aloud** | `openbmb/VoxCPM2` (~2B) on Modal A10G | Apache 2.0, 48 kHz speech, good voice-description control | Separate FastAPI server, only called after the user clicks **Read aloud** |
 
-Open the URL printed in the terminal (default `http://localhost:7860`).
+The split is deliberate. The drafter needs agentic machinery (tool calls, conditional edges, jump-to-end). The judge doesn't — it's "receive a rubric + a draft, return a structured verdict." Pydantic gives us disciplined output, type safety, and a one-shot repair retry. The two layers stay in their own files: `agent.py` for the LangGraph loop, `judge.py` for the Pydantic validator.
 
-## Run on Hugging Face Spaces
+## Output shape
 
-This repo is structured to push directly to a HF Space:
+Every result is a four-section explanation:
 
-1. Create a new Space → **Gradio** SDK
-2. Push these files
-3. The Space builds and serves the app
+- **Opener** — one sentence the parent can say to start the conversation
+- **Body** — 1-3 short paragraphs, written in the second person, age-appropriate, no moralizing
+- **Closer** — one sentence to land the conversation
+- **If they ask another question** — an optional follow-up the parent can use
 
-No secrets are required for the first run. The mock generator is fully active by default.
+For example, given the situation *"My 7-year-old's grandma is in the hospital for surgery. She keeps asking when grandma is coming home."* and tone *gentle*, the app returns something like:
 
-## Modes
+> **Opener:** I want to talk to you about Grandma.
+> **Body:** Grandma is in the hospital right now. She is having a little surgery. The doctors are taking good care of her. It is a part of getting her better. The doctors are very kind and they know just what to do.
+> **Closer:** We are all hoping she comes home very soon.
+> **If they ask more:** We can wait together and find out what the doctors say.
 
-- **Mock mode** (default): template-based, deterministic, zero GPU. Perfect for demos and offline use.
-- **Real model mode**: set `USE_MOCK=false` in the Space's environment variables to route to [`google/gemma-4-E4B-it`](https://huggingface.co/google/gemma-4-E4B-it) on ZeroGPU. Open (Apache 2.0), no API key required. Override the model with `FABELLA_MODEL_ID`.
+## The stack
 
-## Phase 1 scope
+- **HF Space** — custom HTML+CSS+JS frontend served by `gradio.Server` (FastAPI subclass). Storybook-modernist design, no default Gradio chrome.
+- **Modal** — three containers in one app. Drafter (Gemma 4 E4B-IT) runs with `--enable-auto-tool-choice --tool-call-parser gemma4 --language-model-only` (text-only today; the model itself is multimodal and could take audio input if we add a voice-memo feature later). Judge runs with no tool-calling flags. TTS (VoxCPM2) is a small FastAPI wrapper around the official `voxcpm` library. All three A10G, 10-min scaledown.
+- **LangChain 1.x** ReAct loop with a custom middleware that jumps to `end` after a successful validation or after a hard cap of two tool calls.
+- **Pydantic v2** for the judge's structured output.
+
+## Files
+
+- `app.py` — `gradio.Server` app, custom HTML+CSS+JS, `@app.api()` endpoint, no-op `@spaces.GPU` placeholder for HF runtime
+- `agent.py` — LangChain ReAct drafter, `validate_explanation` tool, middleware
+- `judge.py` — Pydantic-validated judge with one repair retry
+- `schema.py` — `ExplainRequest` dataclass + `JudgeVerdict` Pydantic model + `JudgeFailed` exception
+- `llm.py` — `FabellaVLLM` BaseChatModel wrapping vLLM's OpenAI-compatible API
+- `modal_app.py` — Modal deployment (drafter + judge + VoxCPM2 TTS on separate A10Gs)
+- `safety.py` — input sanitization, profanity block, `explain_to_words(tone)`
+
+## Run locally
+
+```bash
+uv venv .venv
+source .venv/bin/activate
+uv pip install -r requirements.txt
+export MODAL_DRAFTER_URL=https://khoitruong071510--fabella-serve-drafter.modal.run
+export MODAL_JUDGE_URL=https://khoitruong071510--fabella-serve-judge.modal.run
+export MODAL_TTS_URL=https://khoitruong071510--fabella-serve-tts.modal.run
+python app.py
+```
 
-This is the first vertical slice. It includes:
+The frontend runs on CPU locally. The two LLM Modal containers cold-start in ~2 min each on the first request of a new session; the TTS container cold-starts separately only when **Read aloud** is clicked.
 
-- Gradio Blocks UI with form, regenerate button, mode badge
-- Template-based mock story generator
-- Input sanitization and profanity guard
-- Real-model path wired (`@spaces.GPU`) but deferred for polish
+## Constraints honored
 
-Out of scope for Phase 1: PDF export, user accounts, story history, audio narration, image generation.
+- ≤ 32B params · both models are 4B
+- Gradio app · hosted as a HF Space
+- No API key needed for the models · Modal credits only
+- No database, no auth, no orchestration
 
-## Build Small
+## Why "small"
 
-Fabella is intentionally tiny: a single Gradio app, one mock generator, one optional real-model call, no database, no auth, no orchestration. The goal is a child who finishes a story and asks for another.
+Two small models, one tool, one page, one rubric. The whole product is a form on the left, a book page on the right, and a few seconds of waiting. The point of Fabella isn't to replace the parent's voice — it's to give the parent a second opinion at the moment they need one, in language the kid can hear.

agent.py

@@ -0,0 +1,369 @@
+"""Fabella — small words for big questions.
+
+The agent has one tool, validate_explanation, which sends a draft to the
+small Nemotron judge for a multi-criteria review. The ReAct loop:
+
+1. Read the parent's situation and the child's age.
+2. Draft a short, kind, concrete explanation. Call validate_explanation.
+3. If OK, jump to "end" (we extract the draft from the last tool-call args).
+4. If issues, model revises and calls validate_explanation again.
+5. After at most 2 tool calls, force a final answer.
+"""
+
+import json
+import os
+import re
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from langchain.agents import create_agent
+from langchain.agents.middleware import AgentMiddleware, AgentState, hook_config
+from langchain.tools import tool
+from langgraph.runtime import Runtime
+
+from safety import age_bucket, explain_to_words
+from schema import ExplainRequest
+
+
+SYSTEM_PROMPT = """You are Fabella, a kind helper for parents who need to explain
+hard things to their child. A parent has just told you about a real
+situation they're facing, and you've written a short, gentle
+explanation the parent can read aloud.
+
+Output shape (always exactly this, no markdown, no extra sections):
+
+Opener: <one short sentence the parent can say to start the conversation>
+Body: <1-3 short paragraphs, written in the second person ("you" / "your
+       child"), concrete and warm. About 60-130 words total for the body.>
+Closer: <one short sentence the parent can say to land the conversation>
+If they ask more: <one optional follow-up sentence the parent can use if
+                   the child has another question>
+
+Strict rules:
+- Never use scary imagery, threats, or vivid descriptions of harm.
+- Never moralize, sermonize, or lecture. ("You should always…")
+- Never promise things that aren't true ("It'll all be fine" — only if
+  the parent's situation actually supports that).
+- Never invent facts. If you don't know, say "I don't know" or
+  acknowledge the uncertainty in kid-appropriate language.
+- Use the child's age to pick vocabulary and sentence length. For
+  young kids (5-7), very short sentences, no abstract words. For
+  older kids (8-12), you can be a little more direct.
+- Address the child by name if one was provided.
+- The opener and closer should sound like something a real parent
+  would actually say out loud. Not therapist-speak. Not corporate.
+
+Workflow:
+1. Draft the explanation. Start with "Opener:", then "Body:", "Closer:",
+   and "If they ask more:" (the last is optional — write it if it
+   helps, omit it if there's nothing useful to add).
+2. Call the validate_explanation tool with the FULL draft text.
+3. If the tool says "OK", output the final draft. If the tool reports
+   issues, revise and call validate_explanation again. After 2 tool
+   calls, output your best draft anyway.
+"""
+
+
+def _word_count(text: str) -> int:
+    return len(re.findall(r"\b\w+\b", text or ""))
+
+
+def _strip_prefix(line: str) -> str:
+    """Strip a leading 'Opener:' / 'Body:' / etc. label from a line."""
+    return re.sub(r"^(Opener|Body|Closer|If they ask more)\s*:\s*", "", line, flags=re.IGNORECASE).strip()
+
+
+def _parse_sections(draft: str) -> dict[str, str]:
+    """Split the draft into Opener / Body / Closer / Follow-up sections.
+
+    Tolerates the model writing 'Opener' on its own line OR inline.
+    """
+    out = {"opener": "", "body": "", "closer": "", "followup": ""}
+    if not draft:
+        return out
+
+    # Find label positions
+    label_re = re.compile(r"^(Opener|Body|Closer|If they ask more)\s*:", re.IGNORECASE | re.MULTILINE)
+    matches = list(label_re.finditer(draft))
+    if not matches:
+        # No labels at all — treat the whole draft as the body
+        out["body"] = draft.strip()
+        return out
+
+    for i, m in enumerate(matches):
+        label = m.group(1).lower()
+        if label == "if they ask more":
+            key = "followup"
+        else:
+            key = label
+        # body content starts after the label, ends at the next label (or end)
+        start = m.end()
+        end = matches[i + 1].start() if i + 1 < len(matches) else len(draft)
+        content = draft[start:end].strip()
+        out[key] = content
+    return out
+
+
+def make_validate_tool(
+    req_age: int,
+    req_tone: str,
+    judge_llm=None,
+    child_name: str = "",
+    situation: str = "",
+):
+    """Closure over the request fields so the tool has them at call time.
+
+    If a `judge_llm` is provided, the tool sends the draft to the judge
+    (see `judge.py`) for a Pydantic-validated multi-criteria review.
+    Otherwise it falls back to a deterministic rule check.
+    """
+    min_w, max_w = explain_to_words(req_tone)
+    bucket = age_bucket(req_age)
+
+    def _judge(draft: str) -> str:
+        assert judge_llm is not None
+        try:
+            from judge import judge_explanation, JudgeFailed
+            verdict = judge_explanation(
+                llm=judge_llm,
+                draft=draft,
+                req_age=req_age,
+                req_tone=req_tone,
+                child_name=child_name,
+                situation=situation,
+            )
+        except JudgeFailed as e:
+            print(f"[validate_explanation] judge failed after retry: {e}; falling back", flush=True)
+            return _rule_based_check(draft)
+        except Exception as e:
+            print(f"[validate_explanation] judge call failed: {type(e).__name__}: {e}", flush=True)
+            return _rule_based_check(draft)
+
+        if verdict.ok and verdict.verdict == "approve":
+            return "OK"
+        if verdict.issues:
+            return "Issues: " + " ".join(verdict.issues)
+        # ok=false but no concrete issues — be safe, revise
+        return "Issues: " + (verdict.reasoning or "The draft does not meet the rubric.")
+
+    def _rule_based_check(draft: str) -> str:
+        issues = []
+        sections = _parse_sections(draft)
+        if not sections["opener"]:
+            issues.append("Missing the 'Opener:' line.")
+        if not sections["body"]:
+            issues.append("Missing the 'Body:' section.")
+        if not sections["closer"]:
+            issues.append("Missing the 'Closer:' line.")
+        body_words = _word_count(sections["body"])
+        if body_words < min_w:
+            issues.append(f"Body too short ({body_words} words; minimum {min_w}).")
+        elif body_words > max_w:
+            issues.append(f"Body too long ({body_words} words; maximum {max_w}).")
+        # Light moralizing / lecturing detection
+        bad_phrases = ["you should always", "you must always", "remember to", "it's important to", "the lesson here is"]
+        body_lower = sections["body"].lower()
+        for p in bad_phrases:
+            if p in body_lower:
+                issues.append(f"Avoid lecturing. Body contains a phrase like '{p}'.")
+        if not issues:
+            return "OK"
+        return "Issues: " + " ".join(issues)
+
+    @tool
+    def validate_explanation(draft: str) -> str:
+        """Validate an explanation draft against the request.
+
+        When a judge model is available, the judge does a multi-criteria
+        review (opener/body/closer present, length, tone, no moralizing,
+        age-appropriateness). Otherwise a deterministic rule check is used.
+
+        Args:
+            draft: The full draft text. Must include 'Opener:', 'Body:',
+                and 'Closer:' labels.
+
+        Returns:
+            'OK' if the draft passes. Otherwise a short report listing
+            the issues to fix.
+        """
+        if judge_llm is not None:
+            return _judge(draft)
+        return _rule_based_check(draft)
+
+    return validate_explanation
+
+
+def _parse_judge_json(text: str) -> dict | None:
+    """Tolerate markdown fences, leading prose, and pretty-printed JSON.
+
+    Kept for backward-compat; the new judge module uses Pydantic and
+    does not use this helper. Tests and legacy callers can still use it.
+    """
+    if not text:
+        return None
+    t = text.strip()
+    if t.startswith("```"):
+        t = re.sub(r"^```(?:json)?\s*", "", t)
+        t = re.sub(r"\s*```\s*$", "", t)
+    i, j = t.find("{"), t.rfind("}")
+    if i < 0 or j < 0 or j <= i:
+        return None
+    candidate = t[i : j + 1]
+    try:
+        return json.loads(candidate)
+    except Exception:
+        return None
+
+
+class FabellaAgentMiddleware(AgentMiddleware):
+    """Ends the ReAct loop once the explanation has been validated, and
+    forces a final answer after a small hard ceiling of iterations.
+
+    The @hook_config(can_jump_to=["end"]) decorator is required — without
+    it, LangGraph never creates the conditional edge and the early-exit
+    silently does nothing.
+    """
+
+    def __init__(self, max_tool_calls: int = 2):
+        super().__init__()
+        self.max_tool_calls = max_tool_calls
+
+    @hook_config(can_jump_to=["end"])
+    def before_model(self, state: AgentState, runtime: Runtime):
+        from langchain.messages import ToolMessage
+
+        tool_calls = [m for m in state.get("messages", []) if isinstance(m, ToolMessage)]
+        last_tool = tool_calls[-1] if tool_calls else None
+
+        if last_tool is not None and last_tool.content.strip() == "OK":
+            print(f"[middleware] tool OK on call {len(tool_calls)}; jumping to end", flush=True)
+            return {"jump_to": "end"}
+
+        if len(tool_calls) >= self.max_tool_calls:
+            print(f"[middleware] hit max tool calls ({self.max_tool_calls}); jumping to end", flush=True)
+            return {"jump_to": "end"}
+
+        return None
+
+
+def _build_user_prompt(req) -> str:
+    """Build the parent's request as a user-prompt for the drafter."""
+    bucket = age_bucket(req.age)
+    vocab = {
+        "young": "very simple sentences (under 12 words each), short paragraphs, no abstract words",
+        "middle": "clear sentences, concrete metaphors are fine",
+        "older": "richer vocabulary is fine, but keep it direct",
+    }[bucket]
+    name_hint = f"The child's name is '{req.child_name}'. Use it naturally once." if req.child_name else "No name was given. Address the parent ('your child') or use 'you'."
+    return (
+        f"A parent needs help explaining a hard thing to their child.\n\n"
+        f"The situation: {req.situation}\n\n"
+        f"The child is {req.age} years old ({bucket} reader).\n"
+        f"{name_hint}\n"
+        f"Tone: {req.tone}. Vocabulary: {vocab}.\n\n"
+        f"Draft a short explanation in the Opener / Body / Closer / "
+        f"(optional) If-they-ask-more shape. Then call "
+        f"validate_explanation on the full draft."
+    )
+
+
+def build_agent(llm, req, judge_llm=None):
+    """Build a one-shot ReAct agent bound to a specific request's tools.
+
+    If `judge_llm` is provided, the validate_explanation tool sends the
+    draft to the judge for a multi-criteria review. Otherwise the tool
+    falls back to a deterministic rule check.
+    """
+    validate = make_validate_tool(
+        req_age=req.age,
+        req_tone=req.tone,
+        judge_llm=judge_llm,
+        child_name=req.child_name,
+        situation=req.situation,
+    )
+    agent = create_agent(
+        model=llm,
+        tools=[validate],
+        system_prompt=SYSTEM_PROMPT,
+        middleware=[FabellaAgentMiddleware(max_tool_calls=2)],
+    )
+    return agent, _build_user_prompt(req)
+
+
+def run_agent(llm, req, judge_llm=None) -> dict:
+    """Run the agent. Return a dict with the parsed explanation.
+
+    The result dict has keys: opener, body, closer, followup, raw.
+    """
+    print(
+        f"[agent] building for age={req.age} tone={req.tone} judge={'yes' if judge_llm else 'no'}",
+        flush=True,
+    )
+    agent, user_prompt = build_agent(llm, req, judge_llm=judge_llm)
+    print(f"[agent] invoking", flush=True)
+    try:
+        result = agent.invoke(
+            {"messages": [{"role": "user", "content": user_prompt}]},
+            {"recursion_limit": 12},
+        )
+    except Exception as e:
+        print(f"[agent] invoke error: {type(e).__name__}: {e}", flush=True)
+        return {
+            "opener": "Fabella (agent error)",
+            "body": f"_Agent loop failed: {type(e).__name__}: {e}_",
+            "closer": "",
+            "followup": "",
+            "raw": "",
+        }
+    print(f"[agent] invoke complete", flush=True)
+    msgs = result.get("messages", []) if isinstance(result, dict) else []
+    print(f"[agent] {len(msgs)} messages in trace", flush=True)
+    return extract_explanation(msgs)
+
+
+def extract_explanation(messages) -> dict:
+    """Pull the latest validated draft from the agent's tool-call trace.
+
+    Order of preference:
+    1. The `draft` argument of the last validate_explanation tool call
+       whose paired ToolMessage returned "OK".
+    2. The content of the last AI message (the model's free-form final).
+    3. The rule-based fallback's last surface text.
+    """
+    tool_results = _tool_results_by_id(messages)
+
+    # 1. Last validated tool-call draft
+    for msg in reversed(messages):
+        if getattr(msg, "type", "") == "ai" and getattr(msg, "tool_calls", None):
+            for tc in reversed(msg.tool_calls):
+                call_id = tc.get("id") if isinstance(tc, dict) else None
+                if (tool_results.get(call_id) or "").strip() != "OK":
+                    continue
+                args = tc.get("args") if isinstance(tc, dict) else {}
+                draft = (args or {}).get("draft") if isinstance(args, dict) else None
+                if draft:
+                    sections = _parse_sections(draft)
+                    return {**sections, "raw": draft}
+
+    # 2. Last AI message with content (the model wrote a final answer
+    #    after the validate_explanation call, without re-emitting the tool args)
+    for msg in reversed(messages):
+        if getattr(msg, "type", "") == "ai" and msg.content:
+            text = msg.content if isinstance(msg.content, str) else str(msg.content)
+            if text.strip():
+                sections = _parse_sections(text)
+                return {**sections, "raw": text}
+
+    return {"opener": "", "body": "", "closer": "", "followup": "", "raw": ""}
+
+
+def _tool_results_by_id(messages) -> dict:
+    results = {}
+    for m in messages:
+        if getattr(m, "type", "") == "tool":
+            call_id = getattr(m, "tool_call_id", None)
+            if call_id:
+                content = m.content if isinstance(m.content, str) else str(m.content)
+                results[call_id] = content
+    return results

app.py

@@ -1,149 +1,1582 @@
-"""Fabella — personalized storytelling companion. Gradio Blocks UI."""
+"""Fabella — small words for big questions.
+
+A Gradio Server (FastAPI subclass) serves a custom HTML+CSS+JS page. The
+parent describes a hard-to-explain situation; Fabella drafts a short,
+kind, age-appropriate explanation, validated by a second small model.
+
+Architecture (see modal_app.py for the server side):
+  Gemma 4 E4B (drafter, A10G)  — writes the explanation
+  Nemotron-3 Nano 4B (judge, A10G) — multi-criteria review
+"""
 
 import os
 import sys
+import asyncio
+import traceback
+import base64
+import json
+import urllib.error
+import urllib.request
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
-import gradio as gr
 
-from generator import USE_MOCK, generate_story
-from schema import StoryRequest
+def _silence_asyncio_invalid_fd_warning() -> None:
+    import asyncio
+
+    original_del = asyncio.BaseEventLoop.__del__
+
+    def safe_del(self):
+        try:
+            original_del(self)
+        except ValueError as exc:
+            if "Invalid file descriptor" not in str(exc):
+                raise
+
+    asyncio.BaseEventLoop.__del__ = safe_del
+
+
+_silence_asyncio_invalid_fd_warning()
+
+from fastapi.responses import HTMLResponse
+
+from agent import run_agent
+from schema import ExplainRequest
 from safety import (
     has_profanity,
-    sanitize_moral,
     sanitize_name,
-    sanitize_themes,
+    sanitize_situation,
 )
 
-THEME_CHOICES = [
-    "dinosaurs",
-    "robots",
-    "space",
-    "fantasy",
-    "adventure",
-    "animals",
-    "ocean",
-    "friends",
-]
+MODAL_DRAFTER_URL = os.environ.get(
+    "MODAL_DRAFTER_URL",
+    "https://khoitruong071510--fabella-serve-drafter.modal.run",
+)
+MODAL_JUDGE_URL = os.environ.get(
+    "MODAL_JUDGE_URL",
+    "https://khoitruong071510--fabella-serve-judge.modal.run",
+)
+MODAL_TTS_URL = os.environ.get(
+    "MODAL_TTS_URL",
+    "https://khoitruong071510--fabella-serve-tts.modal.run",
+)
 
-MORAL_PRESETS = [
-    "being kind to others",
-    "being brave when things feel hard",
-    "telling the truth",
-    "sharing what you have",
-    "trying again after a mistake",
-    "listening before you speak",
-]
+try:
+    import spaces
 
+    @spaces.GPU(duration=1)
+    def _gpu_placeholder() -> str:
+        return "ok"
+except ImportError:
+    pass
 
-def _mode_badge() -> str:
-    return "Mock mode" if USE_MOCK else "Real model"
+from gradio import Server
 
+app = Server()
 
-def _generate(
-    name: str,
-    age: int,
-    themes: list[str] | None,
-    moral_choice: str,
-    moral_text: str,
-    length: str,
-    seed: int,
-) -> tuple[str, str, str]:
-    clean_name = sanitize_name(name) or "Friend"
-    clean_themes = sanitize_themes(themes or []) or ["friends"]
-    clean_moral = sanitize_moral(moral_text or moral_choice or "")
 
-    if has_profanity(clean_name) or has_profanity(clean_moral):
-        return (
-            "Oops",
+def _make_drafter(seed: int = 0):
+    from llm import FabellaVLLM
+    return FabellaVLLM(base_url=MODAL_DRAFTER_URL, model_name="gemma-4", seed=seed)
+
+
+def _make_judge(seed: int = 0):
+    from llm import FabellaVLLM
+    return FabellaVLLM(base_url=MODAL_JUDGE_URL, model_name="nemotron-3-4b", seed=seed)
+
+
+# Sections joined with U+001F (Unit Separator) so the frontend can split
+# reliably on a character that never appears in natural text.
+SECTION_SEP = "\x1f"
+
+
+def _make_explanation_sync(situation: str, age: int, child_name: str, tone: str, seed: int) -> str:
+    clean_situation = sanitize_situation(situation)
+    clean_name = sanitize_name(child_name)
+    clean_tone = (tone or "gentle").strip().lower()
+    if clean_tone not in ("gentle", "matter-of-fact", "playful"):
+        clean_tone = "gentle"
+
+    if has_profanity(clean_situation) or has_profanity(clean_name):
+        return SECTION_SEP.join([
+            "Fabella (safety)",
             "Some of the words used aren't allowed. Please try different words.",
-            _mode_badge(),
-        )
+            "", "",
+        ])
+
+    if not clean_situation:
+        return SECTION_SEP.join([
+            "Fabella (empty)",
+            "Tell me about the situation first — what's going on, in a sentence or two?",
+            "", "",
+        ])
 
-    req = StoryRequest(
-        name=clean_name,
+    if not (5 <= int(age) <= 12):
+        age = 7  # default for out-of-range
+
+    req = ExplainRequest(
+        situation=clean_situation,
         age=int(age),
-        themes=clean_themes,
-        moral=clean_moral,
-        length=length or "medium",
+        child_name=clean_name,
+        tone=clean_tone,
         seed=int(seed or 0),
     )
-    title, body, mode = generate_story(req)
-    return title, body, mode
-
-
-def _regenerate(
-    name: str,
-    age: int,
-    themes: list[str] | None,
-    moral_choice: str,
-    moral_text: str,
-    length: str,
-    current_seed: int,
-) -> tuple[str, str, str]:
-    return _generate(name, age, themes, moral_choice, moral_text, length, (current_seed or 0) + 1)
-
-
-def build_ui() -> gr.Blocks:
-    badge = _mode_badge()
-    with gr.Blocks(title="Fabella") as demo:
-        gr.Markdown(
-            "# Fabella\n"
-            "_A personalized storytelling companion for children._\n\n"
-            f"**Current mode:** `{badge}` — set the `USE_MOCK` env var to change."
+    try:
+        print(
+            f"[app] request: age={req.age} tone={req.tone} name='{req.child_name}' situation='{req.situation[:60]}…'",
+            flush=True,
         )
+        drafter = _make_drafter(seed=req.seed)
+        judge = _make_judge(seed=req.seed)
+        result = run_agent(drafter, req, judge_llm=judge)
+        return SECTION_SEP.join([
+            result.get("opener", "") or "",
+            result.get("body", "") or "",
+            result.get("closer", "") or "",
+            result.get("followup", "") or "",
+        ])
+    except Exception as e:
+        print(f"[app] handler error: {type(e).__name__}: {e}", flush=True)
+        return SECTION_SEP.join([
+            "Fabella (error)",
+            f"_Generation failed: {type(e).__name__}: {e}_",
+            "", "",
+        ])
 
-        with gr.Row():
-            with gr.Column(scale=1):
-                name = gr.Textbox(label="Child's name", placeholder="e.g. Mia", max_length=30)
-                age = gr.Slider(6, 10, step=1, value=7, label="Age")
-                themes = gr.CheckboxGroup(
-                    choices=THEME_CHOICES,
-                    value=["adventure"],
-                    label="Favorite themes (up to 3)",
-                )
-                moral_choice = gr.Dropdown(
-                    choices=MORAL_PRESETS,
-                    value=MORAL_PRESETS[0],
-                    label="Moral lesson (preset)",
-                )
-                moral_text = gr.Textbox(
-                    label="Or write your own moral (optional)",
-                    placeholder="e.g. it's okay to ask for help",
-                    max_length=120,
-                )
-                length = gr.Radio(
-                    choices=["short", "medium", "long"],
-                    value="medium",
-                    label="Story length",
-                )
-                seed = gr.State(value=0)
-                with gr.Row():
-                    submit = gr.Button("Tell me a story", variant="primary")
-                    regen = gr.Button("New story")
-
-            with gr.Column(scale=2):
-                out_title = gr.Markdown("### Your story will appear here")
-                out_body = gr.Markdown("")
-                out_mode = gr.Markdown(f"_{badge}_")
-
-        submit.click(
-            fn=_generate,
-            inputs=[name, age, themes, moral_choice, moral_text, length, seed],
-            outputs=[out_title, out_body, out_mode],
-        )
-        regen.click(
-            fn=_regenerate,
-            inputs=[name, age, themes, moral_choice, moral_text, length, seed],
-            outputs=[out_title, out_body, out_mode],
-        )
 
-    return demo
+@app.api(name="make_explanation")
+def make_explanation(situation: str, age: int, child_name: str, tone: str, seed: int) -> str:
+    """Draft a short, kind, age-appropriate explanation.
+
+    Returns four sections joined by U+001F:
+      0: opener (one sentence the parent can say to start)
+      1: body (1-3 short paragraphs)
+      2: closer (one sentence the parent can say to land)
+      3: follow-up (optional one sentence if the child has another question)
+    """
+    return _make_explanation_sync(situation, age, child_name, tone, seed)
+
+
+def _clean_audio_text(text: str) -> str:
+    clean = " ".join((text or "").split())
+    if len(clean) > 1600:
+        clean = clean[:1600].rsplit(" ", 1)[0].strip()
+    return clean
+
+
+def _make_audio_sync(text: str, tone: str) -> str:
+    clean_text = _clean_audio_text(text)
+    if not clean_text:
+        return "ERROR: Nothing to read aloud yet."
+
+    clean_tone = (tone or "gentle").strip().lower()
+    voice_by_tone = {
+        "gentle": "A calm adult woman with a soft, warm, reassuring voice, speaking slowly and clearly for a child.",
+        "matter-of-fact": "A calm adult woman with a clear, steady, practical voice, speaking plainly and kindly for a child.",
+        "playful": "A friendly adult woman with a lightly playful, bright, reassuring voice, speaking clearly for a child.",
+    }
+    payload = {
+        "text": clean_text,
+        "voice_description": voice_by_tone.get(clean_tone, voice_by_tone["gentle"]),
+        "cfg_value": 2.0,
+        "inference_timesteps": 10,
+        "normalize": True,
+        "denoise": True,
+    }
+    req = urllib.request.Request(
+        MODAL_TTS_URL.rstrip("/") + "/synthesize",
+        data=json.dumps(payload).encode("utf-8"),
+        headers={"Content-Type": "application/json", "Accept": "audio/wav"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=180) as res:
+            audio = res.read()
+    except urllib.error.HTTPError as e:
+        detail = e.read().decode("utf-8", errors="replace")[:300]
+        print(f"[app] tts HTTP error: {e.code}: {detail}", flush=True)
+        return f"ERROR: Read-aloud failed: HTTP {e.code}"
+    except Exception as e:
+        print(f"[app] tts error: {type(e).__name__}: {e}", flush=True)
+        return f"ERROR: Read-aloud failed: {type(e).__name__}: {e}"
+
+    if not audio:
+        return "ERROR: Read-aloud returned no audio."
+    return "data:audio/wav;base64," + base64.b64encode(audio).decode("ascii")
+
+
+@app.api(name="make_audio")
+def make_audio(text: str, tone: str) -> str:
+    """Synthesize a Fabella explanation as a base64 WAV data URL."""
+    return _make_audio_sync(text, tone)
+
+
+# --- HTML page --------------------------------------------------------------
+
+TONE_CHOICES = [
+    ("gentle", "Gentle"),
+    ("matter-of-fact", "Matter-of-fact"),
+    ("playful", "Playful"),
+]
+
+EXAMPLE_SITUATIONS = [
+    ("My 7-year-old's grandma is in the hospital for surgery. She asked why grandma is there."),
+    ("We're moving to a new house in 3 weeks. My kid is worried about leaving her friends."),
+    ("My child's dog died yesterday. She keeps asking when the dog is coming back."),
+    ("It's time to start sharing toys at preschool. My son refuses and has started hitting."),
+    ("My 9-year-old wants a phone. All her friends have one and I said no."),
+    ("There's a new baby coming in 4 months. My first grader is acting out and being mean to me."),
+]
+
+INDEX_HTML = r"""<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+<title>Fabella — small words for big questions</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght,SOFT,WONK@9..144,300..900,0..100,0..1&family=Literata:ital,opsz,wght@0,7..72,400..800;1,7..72,400..800&family=Fragment+Mono&display=swap">
+<style>
+/* =========================================================================
+   FABELLA — small words for big questions
+   Cool palette, NOT the banned warm-cream+brass+espresso default.
+   Same storybook-modernist language as before.
+   ========================================================================= */
+
+:root {
+  --bone:       #ece9e0;
+  --bone-deep:  #e3dfd3;
+  --paper:      #f4f1e7;
+  --paper-2:    #faf7ed;
+  --ink:        #1a1d1f;
+  --ink-soft:   #3d4144;
+  --ink-mute:   #6b6e6f;
+  --rule:       #c8c2b1;
+  --rule-soft:  #d9d4c2;
+  --forest:     #2d4a2b;
+  --forest-ink: #1a2f18;
+  --wax:        #a8341f;
+  --wax-ink:    #7a2415;
+
+  --serif: "Source Serif 4", "Iowan Old Style", Georgia, "Times New Roman", serif;
+  --mono:  "JetBrains Mono", ui-monospace, "SF Mono", Menlo, monospace;
+
+  --pad-x: clamp(20px, 4.5vw, 56px);
+  --shadow-leaf: 0 1px 0 rgba(26,31,27,0.04), 0 12px 28px -18px rgba(26,31,27,0.18);
+  --ease: cubic-bezier(0.16, 1, 0.3, 1);
+}
+* { box-sizing: border-box; }
+html, body { margin: 0; padding: 0; }
+html { background: var(--bone); }
+body {
+  color: var(--ink);
+  font-family: var(--serif);
+  font-size: 17px;
+  line-height: 1.55;
+  background: var(--bone);
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  text-rendering: optimizeLegibility;
+  font-feature-settings: "kern", "liga", "onum";
+  min-height: 100dvh;
+  overflow-x: hidden;
+}
+body::before {
+  content: "";
+  position: fixed; inset: 0;
+  pointer-events: none;
+  z-index: 60;
+  opacity: 0.5;
+  mix-blend-mode: multiply;
+  background-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='160' height='160'><filter id='n'><feTurbulence type='fractalNoise' baseFrequency='0.85' numOctaves='2' seed='4'/><feColorMatrix values='0 0 0 0 0.55  0 0 0 0 0.50  0 0 0 0 0.40  0 0 0 0.07 0'/></filter><rect width='100%25' height='100%25' filter='url(%23n)'/></svg>");
+}
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after { animation: none !important; transition: none !important; }
+}
+
+/* ---- header strip ---- */
+.imprint {
+  padding: 14px var(--pad-x);
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 20px;
+  border-bottom: 1px solid var(--rule);
+  font-family: var(--mono);
+  font-size: 11px;
+  letter-spacing: 0.18em;
+  text-transform: uppercase;
+  color: var(--ink-soft);
+  background: var(--bone);
+}
+.imprint .wordmark {
+  font-family: var(--serif);
+  font-style: italic;
+  font-size: 19px;
+  letter-spacing: 0.005em;
+  text-transform: none;
+  color: var(--ink);
+  font-weight: 400;
+}
+.imprint .wordmark b { font-style: normal; font-weight: 700; color: var(--forest-ink); }
+.imprint .meta { display: flex; gap: 22px; }
+.imprint .meta span b { color: var(--ink); font-weight: 700; }
+
+/* ---- main split ---- */
+.stage {
+  display: grid;
+  grid-template-columns: minmax(0, 1.1fr) minmax(0, 1fr);
+  gap: clamp(24px, 4vw, 64px);
+  padding: clamp(28px, 5vw, 64px) var(--pad-x) clamp(40px, 6vw, 88px);
+  max-width: 1280px;
+  margin: 0 auto;
+  align-items: start;
+}
+@media (max-width: 880px) { .stage { grid-template-columns: 1fr; } }
+
+/* ---- left: form ---- */
+.col-form { position: sticky; top: 28px; }
+@media (max-width: 880px) { .col-form { position: static; } }
+.title-block { margin-bottom: 28px; }
+.title-block h1 {
+  font-family: var(--serif);
+  font-size: clamp(40px, 6.4vw, 64px);
+  line-height: 0.98;
+  letter-spacing: -0.015em;
+  font-weight: 700;
+  margin: 0 0 14px 0;
+  color: var(--ink);
+  text-wrap: balance;
+}
+.title-block h1 em { font-style: italic; font-weight: 400; color: var(--forest-ink); }
+.title-block .lede {
+  font-size: 17px;
+  line-height: 1.55;
+  color: var(--ink-soft);
+  max-width: 40ch;
+  margin: 0;
+}
+form { display: flex; flex-direction: column; gap: 22px; margin-top: 8px; }
+.field { display: flex; flex-direction: column; gap: 8px; }
+.label {
+  font-family: var(--mono);
+  font-size: 10.5px;
+  font-weight: 700;
+  letter-spacing: 0.22em;
+  text-transform: uppercase;
+  color: var(--ink-mute);
+}
+.label small { text-transform: none; letter-spacing: 0; font-weight: 400; font-family: var(--serif); font-style: italic; font-size: 12px; color: var(--ink-mute); margin-left: 6px; }
+.hint {
+  font-family: var(--serif);
+  font-style: italic;
+  font-size: 13px;
+  color: var(--ink-mute);
+  line-height: 1.5;
+  margin-top: 2px;
+}
+
+input[type="text"], textarea {
+  font-family: var(--serif);
+  font-size: 17px;
+  line-height: 1.45;
+  color: var(--ink);
+  background: var(--paper);
+  border: 1px solid var(--rule);
+  border-radius: 0;
+  padding: 12px 14px;
+  outline: none;
+  transition: border-color 0.18s var(--ease), background 0.18s var(--ease);
+  width: 100%;
+  font-feature-settings: "kern", "liga";
+}
+textarea { min-height: 110px; resize: vertical; line-height: 1.55; }
+input[type="text"]::placeholder, textarea::placeholder { color: var(--ink-mute); font-style: italic; }
+input[type="text"]:focus, textarea:focus {
+  border-color: var(--forest);
+  background: var(--paper-2);
+}
+
+.age { display: grid; grid-template-columns: 1fr auto; align-items: baseline; gap: 14px; }
+.age .readout {
+  font-family: var(--serif);
+  font-size: 30px;
+  line-height: 1;
+  color: var(--ink);
+  font-feature-settings: "tnum";
+  font-weight: 600;
+}
+.age .readout small { font-family: var(--mono); font-size: 10.5px; letter-spacing: 0.18em; text-transform: uppercase; color: var(--ink-mute); margin-left: 6px; vertical-align: middle; }
+.age input[type="range"] {
+  grid-column: 1 / -1;
+  -webkit-appearance: none; appearance: none;
+  width: 100%; height: 4px;
+  background: var(--rule);
+  border-radius: 999px;
+  outline: none;
+}
+.age input[type="range"]::-webkit-slider-thumb {
+  -webkit-appearance: none; appearance: none;
+  width: 22px; height: 22px;
+  border-radius: 50%;
+  background: var(--forest);
+  cursor: grab;
+  border: 3px solid var(--paper);
+  box-shadow: 0 0 0 1px var(--forest);
+  transition: transform 0.15s var(--ease);
+}
+.age input[type="range"]::-webkit-slider-thumb:active { transform: scale(0.94); cursor: grabbing; }
+.age input[type="range"]::-moz-range-thumb {
+  width: 22px; height: 22px; border-radius: 50%;
+  background: var(--forest); border: 3px solid var(--paper);
+  box-shadow: 0 0 0 1px var(--forest);
+}
+
+/* tone radio as 3 segmented buttons */
+.tone-row {
+  display: grid; grid-template-columns: 1fr 1fr 1fr;
+  border: 1px solid var(--rule);
+  border-radius: 0;
+  overflow: hidden;
+  background: var(--paper);
+}
+.tone-row label {
+  text-align: center;
+  padding: 11px 8px;
+  font-family: var(--mono);
+  font-size: 11px;
+  letter-spacing: 0.16em;
+  text-transform: uppercase;
+  color: var(--ink-soft);
+  cursor: pointer;
+  border-right: 1px solid var(--rule);
+  transition: background 0.18s var(--ease), color 0.18s var(--ease);
+  font-weight: 500;
+  user-select: none;
+}
+.tone-row label:last-child { border-right: none; }
+.tone-row input { display: none; }
+.tone-row label.is-on { background: var(--ink); color: var(--bone); }
+
+/* example chips */
+.examples { display: flex; flex-direction: column; gap: 6px; }
+.ex-chip {
+  font-family: var(--serif);
+  font-size: 14px;
+  line-height: 1.4;
+  color: var(--ink-soft);
+  background: var(--paper);
+  border: 1px solid var(--rule-soft);
+  padding: 8px 12px;
+  cursor: pointer;
+  text-align: left;
+  border-radius: 0;
+  transition: border-color 0.18s var(--ease), color 0.18s var(--ease), background 0.18s var(--ease);
+}
+.ex-chip:hover { border-color: var(--ink-soft); color: var(--ink); background: var(--paper-2); }
+.ex-chip small { display: block; font-family: var(--mono); font-size: 9.5px; letter-spacing: 0.16em; text-transform: uppercase; color: var(--ink-mute); margin-bottom: 2px; }
+
+/* submit */
+.actions { display: flex; align-items: center; gap: 14px; margin-top: 6px; flex-wrap: wrap; }
+.btn-primary {
+  font-family: var(--serif);
+  font-size: 17px;
+  font-weight: 600;
+  letter-spacing: 0.005em;
+  color: var(--bone);
+  background: var(--wax);
+  border: 1px solid var(--wax-ink);
+  padding: 13px 22px;
+  border-radius: 0;
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  gap: 10px;
+  box-shadow: 0 1px 0 rgba(0,0,0,0.04), 0 4px 0 -1px var(--wax-ink);
+  transition: transform 0.12s var(--ease), box-shadow 0.12s var(--ease), background 0.18s var(--ease);
+  white-space: nowrap;
+}
+.btn-primary:hover { background: var(--wax-ink); }
+.btn-primary:active { transform: translateY(2px); box-shadow: 0 1px 0 rgba(0,0,0,0.04), 0 2px 0 -1px var(--wax-ink); }
+.btn-primary:disabled { background: var(--ink-mute); border-color: var(--ink-mute); box-shadow: 0 1px 0 rgba(0,0,0,0.04); cursor: progress; transform: none; }
+.btn-primary .arrow { display: inline-block; transition: transform 0.18s var(--ease); }
+.btn-primary:hover:not(:disabled) .arrow { transform: translateX(3px); }
+.btn-ghost {
+  font-family: var(--mono);
+  font-size: 11px;
+  letter-spacing: 0.18em;
+  text-transform: uppercase;
+  color: var(--ink-soft);
+  background: transparent;
+  border: none;
+  cursor: pointer;
+  padding: 8px 4px;
+  border-bottom: 1px dashed var(--ink-mute);
+  transition: color 0.18s var(--ease), border-color 0.18s var(--ease);
+}
+.btn-ghost:hover { color: var(--ink); border-color: var(--ink); }
+.btn-ghost:disabled { opacity: 0.4; cursor: not-allowed; }
+.btn-read {
+  font-family: var(--mono);
+  font-size: 10.5px;
+  letter-spacing: 0.18em;
+  text-transform: uppercase;
+  color: var(--forest-ink);
+  background: transparent;
+  border: 1px solid var(--rule);
+  padding: 9px 12px;
+  cursor: pointer;
+  transition: background 0.18s var(--ease), color 0.18s var(--ease), border-color 0.18s var(--ease);
+}
+.btn-read:hover { background: var(--paper-2); border-color: var(--forest); color: var(--ink); }
+.btn-read:disabled { opacity: 0.45; cursor: progress; }
+.seed-pill {
+  font-family: var(--mono);
+  font-size: 10.5px;
+  letter-spacing: 0.18em;
+  text-transform: uppercase;
+  color: var(--ink-mute);
+  padding-left: 4px;
+}
+
+/* ---- right: book page ---- */
+.col-story { position: relative; min-height: 60vh; }
+.book {
+  background: var(--paper);
+  border: 1px solid var(--rule);
+  box-shadow: var(--shadow-leaf);
+  padding: clamp(28px, 4.5vw, 56px) clamp(24px, 4vw, 52px);
+  position: relative;
+}
+.book::before {
+  content: "";
+  position: absolute; left: 18px; top: 18px; bottom: 18px; right: 18px;
+  border: 1px solid var(--rule-soft);
+  pointer-events: none;
+}
+.book .corner {
+  position: absolute;
+  width: 22px; height: 22px;
+  pointer-events: none;
+  color: var(--ink-mute);
+}
+.book .corner.tl { top: 10px; left: 10px; }
+.book .corner.tr { top: 10px; right: 10px; transform: scaleX(-1); }
+.book .corner.bl { bottom: 10px; left: 10px; transform: scaleY(-1); }
+.book .corner.br { bottom: 10px; right: 10px; transform: scale(-1,-1); }
+.book .inner { position: relative; z-index: 1; }
+
+.cover { display: flex; flex-direction: column; gap: 18px; min-height: 380px; justify-content: center; }
+.cover .folio { font-family: var(--mono); font-size: 10.5px; letter-spacing: 0.22em; text-transform: uppercase; color: var(--ink-mute); }
+.cover h2 {
+  font-family: var(--serif);
+  font-size: clamp(34px, 4.5vw, 50px);
+  line-height: 1.02;
+  letter-spacing: -0.012em;
+  font-weight: 600;
+  margin: 0;
+  color: var(--ink);
+  font-style: italic;
+  font-weight: 400;
+}
+.cover h2 b { font-style: normal; font-weight: 700; color: var(--forest-ink); }
+.cover p { font-size: 16px; line-height: 1.6; color: var(--ink-soft); max-width: 40ch; margin: 0; }
 
+.writing { display: flex; flex-direction: column; gap: 14px; min-height: 380px; justify-content: center; }
+.writing .penline {
+  font-family: var(--mono);
+  font-size: 10.5px;
+  letter-spacing: 0.22em;
+  text-transform: uppercase;
+  color: var(--ink-mute);
+  display: inline-flex; align-items: center; gap: 10px;
+}
+.writing .quill {
+  display: inline-block; width: 14px; height: 14px; background: var(--ink);
+  -webkit-mask: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M3 21l3.5-1 11-11a2.83 2.83 0 0 0-4-4l-11 11L3 21z' fill='currentColor'/></svg>") center/contain no-repeat;
+          mask: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M3 21l3.5-1 1 1-11a2.83 2.83 0 0 0-4-4l-11 11L3 21z' fill='currentColor'/></svg>") center/contain no-repeat;
+  transform-origin: 50% 80%;
+  animation: nib 1.6s var(--ease) infinite;
+}
+@keyframes nib { 0%, 100% { transform: rotate(-8deg) translateX(0); } 50% { transform: rotate(14deg) translateX(2px); } }
+@media (prefers-reduced-motion: reduce) { .writing .quill { animation: none; } }
+.writing .progress {
+  height: 1px;
+  background: linear-gradient(90deg, var(--forest) 0%, var(--forest) var(--p,40%), var(--rule) var(--p,40%), var(--rule) 100%);
+  width: 100%;
+  max-width: 320px;
+  transition: background 0.4s var(--ease);
+}
+.writing p { font-size: 16px; line-height: 1.6; color: var(--ink-soft); max-width: 40ch; margin: 0; }
 
-demo = build_ui()
+/* the actual explanation page */
+.expl { animation: arrive 0.55s var(--ease) both; }
+@keyframes arrive { from { opacity: 0; transform: translateY(8px) rotate(-0.2deg); } to { opacity: 1; transform: translateY(0) rotate(0); } }
+@media (prefers-reduced-motion: reduce) { .expl { animation: none; } }
+
+.expl .byline {
+  font-family: var(--mono);
+  font-size: 10.5px;
+  letter-spacing: 0.22em;
+  text-transform: uppercase;
+  color: var(--ink-mute);
+  margin-bottom: 18px;
+  display: flex; align-items: center; gap: 10px; flex-wrap: wrap;
+}
+.expl .byline .dot { width: 4px; height: 4px; border-radius: 50%; background: var(--ink-mute); display: inline-block; }
+.expl .byline .label-tiny { color: var(--ink-soft); font-weight: 700; }
+
+.expl h2.title {
+  font-family: var(--serif);
+  font-size: clamp(28px, 3.6vw, 36px);
+  line-height: 1.1;
+  letter-spacing: -0.012em;
+  font-weight: 700;
+  margin: 0 0 22px 0;
+  color: var(--ink);
+  text-wrap: balance;
+}
+.expl h2.title small {
+  display: block;
+  font-family: var(--mono);
+  font-size: 10.5px;
+  letter-spacing: 0.22em;
+  text-transform: uppercase;
+  color: var(--ink-mute);
+  font-weight: 400;
+  margin-top: 8px;
+}
+
+/* the four sections, in order */
+.section { margin-bottom: 18px; }
+.section:last-child { margin-bottom: 0; }
+.section .tag {
+  font-family: var(--mono);
+  font-size: 10px;
+  letter-spacing: 0.22em;
+  text-transform: uppercase;
+  color: var(--forest-ink);
+  font-weight: 700;
+  margin-bottom: 6px;
+  display: block;
+}
+.section .text {
+  font-family: var(--serif);
+  font-size: 18px;
+  line-height: 1.55;
+  color: var(--ink);
+  margin: 0;
+}
+.section.opener .text {
+  font-style: italic;
+  color: var(--ink-soft);
+  font-size: 17px;
+  border-left: 2px solid var(--forest);
+  padding: 2px 0 2px 14px;
+}
+.section.closer .text {
+  font-weight: 600;
+}
+.section.body p { margin: 0 0 0.85em 0; }
+.section.body p:last-child { margin-bottom: 0; }
+.section.followup .text {
+  font-size: 15px;
+  color: var(--ink-mute);
+  font-style: italic;
+}
+.section .text:empty { display: none; }
+.section:has(.text:empty) { display: none; }
+
+.expl .signoff {
+  margin-top: 32px;
+  padding-top: 18px;
+  border-top: 1px solid var(--rule-soft);
+  display: flex; align-items: baseline; justify-content: space-between;
+  gap: 12px; flex-wrap: wrap;
+  font-family: var(--mono);
+  font-size: 10.5px;
+  letter-spacing: 0.18em;
+  text-transform: uppercase;
+  color: var(--ink-mute);
+}
+.expl .signoff .regen {
+  color: var(--ink-soft);
+  border-bottom: 1px dashed var(--ink-mute);
+  cursor: pointer;
+  padding: 0 0 1px 0;
+  background: transparent;
+  border-left: 0; border-right: 0; border-top: 0;
+  font: inherit; letter-spacing: inherit; text-transform: inherit;
+}
+.expl .signoff .regen:hover { color: var(--ink); border-color: var(--ink); }
+.expl .signoff .regen:disabled { opacity: 0.4; cursor: progress; }
+
+.audio-panel {
+  margin-top: 18px;
+  padding-top: 18px;
+  border-top: 1px solid var(--rule-soft);
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.audio-panel .audio-status {
+  font-family: var(--serif);
+  font-style: italic;
+  font-size: 14px;
+  color: var(--ink-mute);
+}
+.audio-panel audio {
+  width: 100%;
+  min-width: 220px;
+  margin-top: 2px;
+}
+
+.banner {
+  font-family: var(--serif);
+  font-style: italic;
+  font-size: 16px;
+  line-height: 1.5;
+  color: var(--wax-ink);
+  border-left: 3px double var(--wax);
+  padding: 4px 0 4px 14px;
+}
+
+.colophon {
+  border-top: 1px solid var(--rule);
+  padding: 22px var(--pad-x) 28px;
+  font-family: var(--mono);
+  font-size: 10.5px;
+  letter-spacing: 0.18em;
+  text-transform: uppercase;
+  color: var(--ink-mute);
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  gap: 20px;
+  flex-wrap: wrap;
+  max-width: 1280px;
+  margin: 0 auto;
+}
+.colophon a { color: var(--ink-soft); text-decoration: none; border-bottom: 1px dotted var(--ink-mute); }
+.colophon a:hover { color: var(--ink); border-color: var(--ink); }
+
+/* =========================================================================
+   REDESIGN — night observatory field guide
+   A parent is not asking for a dashboard; they are trying to find a careful
+   sentence in the dark. The interface should feel like a quiet instrument:
+   ink, brass, star maps, and one illuminated page.
+   ========================================================================= */
+
+:root {
+  --night:      #081019;
+  --night-2:    #0d1924;
+  --night-3:    #132333;
+  --mist:       #dbe3dd;
+  --mist-dim:   #aebbb7;
+  --vellum:     #f1ead7;
+  --vellum-2:   #fbf5e8;
+  --vellum-3:   #e4d8bd;
+  --ink:        #13202a;
+  --ink-soft:   #314150;
+  --ink-mute:   #67747d;
+  --rule:       rgba(210, 188, 139, 0.42);
+  --rule-soft:  rgba(210, 188, 139, 0.22);
+  --forest:     #5f8e79;
+  --forest-ink: #1d5d4f;
+  --wax:        #d46a45;
+  --wax-ink:    #8f381f;
+  --gold:       #d8b56a;
+  --bluefire:   #8cc7d8;
+  --serif:      "Literata", "Iowan Old Style", Georgia, serif;
+  --display:    "Fraunces", "Literata", Georgia, serif;
+  --mono:       "Fragment Mono", "JetBrains Mono", ui-monospace, monospace;
+  --pad-x:      clamp(18px, 4vw, 64px);
+  --ease:       cubic-bezier(0.16, 1, 0.3, 1);
+  --shadow-leaf: 0 34px 90px -48px rgba(0, 0, 0, 0.82), 0 0 0 1px rgba(216,181,106,0.14);
+}
+
+html { background: var(--night); }
+body {
+  color: var(--mist);
+  background:
+    radial-gradient(circle at 14% 16%, rgba(140,199,216,0.18) 0 12%, transparent 30%),
+    radial-gradient(circle at 86% 8%, rgba(212,106,69,0.16) 0 10%, transparent 28%),
+    radial-gradient(circle at 72% 86%, rgba(216,181,106,0.11) 0 11%, transparent 26%),
+    linear-gradient(135deg, #060b12 0%, var(--night) 38%, #101b26 100%);
+  isolation: isolate;
+}
+body::before {
+  opacity: 0.38;
+  mix-blend-mode: screen;
+  background-image:
+    radial-gradient(circle at 20px 24px, rgba(255,255,255,0.72) 0 1px, transparent 1.4px),
+    radial-gradient(circle at 82px 68px, rgba(216,181,106,0.56) 0 1px, transparent 1.4px),
+    url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='180' height='180'><filter id='n'><feTurbulence type='fractalNoise' baseFrequency='0.78' numOctaves='3' seed='11'/><feColorMatrix values='0 0 0 0 0.80 0 0 0 0 0.78 0 0 0 0 0.68 0 0 0 0.18 0'/></filter><rect width='100%25' height='100%25' filter='url(%23n)'/></svg>");
+  background-size: 118px 118px, 172px 172px, 180px 180px;
+}
+body::after {
+  content: "";
+  position: fixed;
+  inset: auto -8vw -18vh auto;
+  width: min(62vw, 720px);
+  height: min(62vw, 720px);
+  pointer-events: none;
+  z-index: -1;
+  opacity: 0.34;
+  border: 1px solid rgba(216,181,106,0.28);
+  border-radius: 50%;
+  background:
+    linear-gradient(90deg, transparent 49.8%, rgba(216,181,106,0.24) 50%, transparent 50.2%),
+    linear-gradient(0deg, transparent 49.8%, rgba(216,181,106,0.24) 50%, transparent 50.2%),
+    radial-gradient(circle, transparent 0 44%, rgba(216,181,106,0.2) 44.2% 44.6%, transparent 45%),
+    radial-gradient(circle, transparent 0 64%, rgba(216,181,106,0.16) 64.2% 64.6%, transparent 65%);
+  transform: rotate(-11deg);
+}
+
+.imprint {
+  position: relative;
+  padding: 18px var(--pad-x);
+  border-bottom: 1px solid rgba(216,181,106,0.2);
+  background: rgba(8,16,25,0.72);
+  color: var(--mist-dim);
+  backdrop-filter: blur(18px);
+}
+.imprint::after {
+  content: "";
+  position: absolute;
+  left: var(--pad-x);
+  right: var(--pad-x);
+  bottom: -1px;
+  height: 1px;
+  background: linear-gradient(90deg, transparent, var(--gold), transparent);
+  opacity: 0.56;
+}
+.imprint .wordmark {
+  color: var(--vellum-2);
+  font-family: var(--display);
+  font-size: clamp(20px, 2.2vw, 31px);
+  font-style: normal;
+  font-variation-settings: "SOFT" 75, "WONK" 1;
+  letter-spacing: -0.025em;
+}
+.imprint .wordmark b { color: var(--gold); font-weight: 760; }
+.imprint .meta { color: var(--mist-dim); opacity: 0.92; }
+.imprint .meta span b { color: var(--bluefire); }
+
+.stage {
+  position: relative;
+  max-width: 1380px;
+  grid-template-columns: minmax(320px, 0.92fr) minmax(420px, 1.08fr);
+  gap: clamp(28px, 5vw, 86px);
+  padding-top: clamp(34px, 6vw, 84px);
+}
+.stage::before {
+  content: "";
+  position: absolute;
+  top: 54px;
+  left: calc(var(--pad-x) + 17px);
+  width: 120px;
+  height: 120px;
+  opacity: 0.34;
+  pointer-events: none;
+  border-left: 1px solid var(--gold);
+  border-top: 1px solid var(--gold);
+  transform: rotate(-7deg);
+}
+
+.col-form {
+  top: 34px;
+  padding: clamp(22px, 3vw, 34px);
+  background: linear-gradient(180deg, rgba(13,25,36,0.82), rgba(8,16,25,0.58));
+  border: 1px solid rgba(216,181,106,0.22);
+  box-shadow: 0 28px 78px -58px rgba(0,0,0,0.86);
+  backdrop-filter: blur(16px);
+}
+.col-form::before {
+  content: "Parent console / private draft";
+  display: block;
+  margin-bottom: 18px;
+  font-family: var(--mono);
+  font-size: 10px;
+  letter-spacing: 0.2em;
+  text-transform: uppercase;
+  color: var(--gold);
+}
+.title-block { margin-bottom: 30px; }
+.title-block h1 {
+  color: var(--vellum-2);
+  font-family: var(--display);
+  font-size: clamp(48px, 6.8vw, 88px);
+  line-height: 0.86;
+  letter-spacing: -0.055em;
+  font-weight: 820;
+  font-variation-settings: "SOFT" 64, "WONK" 1;
+  max-width: 8.4ch;
+}
+.title-block h1 em {
+  color: var(--bluefire);
+  font-style: italic;
+  font-weight: 430;
+}
+.title-block .lede {
+  color: var(--mist-dim);
+  font-size: 16px;
+  max-width: 45ch;
+}
+form { gap: 20px; }
+.label {
+  color: rgba(216,181,106,0.9);
+  font-size: 9.5px;
+}
+.label small, .hint { color: rgba(219,227,221,0.56); }
+input[type="text"], textarea {
+  color: var(--vellum-2);
+  background: rgba(5,10,16,0.42);
+  border: 1px solid rgba(216,181,106,0.28);
+  box-shadow: inset 0 0 0 1px rgba(255,255,255,0.025);
+  border-radius: 18px 18px 18px 4px;
+  padding: 14px 16px;
+}
+textarea { min-height: 138px; }
+input[type="text"]::placeholder, textarea::placeholder { color: rgba(219,227,221,0.42); }
+input[type="text"]:focus, textarea:focus {
+  border-color: var(--bluefire);
+  background: rgba(12,28,40,0.62);
+  box-shadow: 0 0 0 4px rgba(140,199,216,0.1), inset 0 0 0 1px rgba(255,255,255,0.04);
+}
+.age .readout { color: var(--vellum-2); font-family: var(--display); font-size: 38px; }
+.age .readout small { color: var(--mist-dim); }
+.age input[type="range"] { height: 2px; background: rgba(216,181,106,0.34); }
+.age input[type="range"]::-webkit-slider-thumb {
+  background: var(--bluefire);
+  border-color: var(--night);
+  box-shadow: 0 0 0 1px var(--bluefire), 0 0 24px rgba(140,199,216,0.52);
+}
+.age input[type="range"]::-moz-range-thumb {
+  background: var(--bluefire);
+  border-color: var(--night);
+  box-shadow: 0 0 0 1px var(--bluefire), 0 0 24px rgba(140,199,216,0.52);
+}
+.tone-row {
+  border-color: rgba(216,181,106,0.28);
+  border-radius: 999px;
+  padding: 4px;
+  gap: 4px;
+  background: rgba(5,10,16,0.46);
+}
+.tone-row label {
+  border: 0;
+  border-radius: 999px;
+  color: var(--mist-dim);
+  padding: 10px 8px;
+}
+.tone-row label.is-on {
+  background: var(--vellum);
+  color: var(--night);
+  box-shadow: 0 7px 24px -14px rgba(251,245,232,0.85);
+}
+.examples { gap: 8px; }
+.ex-chip {
+  position: relative;
+  overflow: hidden;
+  color: rgba(241,234,215,0.86);
+  background: linear-gradient(90deg, rgba(19,35,51,0.7), rgba(8,16,25,0.34));
+  border-color: rgba(216,181,106,0.16);
+  border-radius: 16px 16px 16px 4px;
+  padding: 10px 13px 10px 16px;
+}
+.ex-chip::before {
+  content: "";
+  position: absolute;
+  left: 0;
+  top: 12px;
+  bottom: 12px;
+  width: 2px;
+  background: var(--gold);
+  opacity: 0.6;
+}
+.ex-chip:hover {
+  color: var(--vellum-2);
+  background: rgba(19,35,51,0.92);
+  border-color: rgba(140,199,216,0.42);
+  transform: translateX(2px);
+}
+.ex-chip small { color: var(--bluefire); }
+
+.btn-primary {
+  color: #10161d;
+  background: linear-gradient(135deg, var(--gold), #f0d99c 48%, #d37a52);
+  border: 0;
+  border-radius: 999px;
+  padding: 14px 22px;
+  box-shadow: 0 15px 36px -22px rgba(216,181,106,0.98), inset 0 1px 0 rgba(255,255,255,0.52);
+  font-family: var(--display);
+  font-weight: 760;
+}
+.btn-primary:hover { background: linear-gradient(135deg, #f1cf77, #fff0bd 48%, #e07b51); }
+.btn-primary:disabled { background: rgba(174,187,183,0.42); color: rgba(8,16,25,0.72); }
+.btn-ghost, .seed-pill { color: var(--mist-dim); }
+.btn-ghost:hover { color: var(--bluefire); border-color: var(--bluefire); }
+
+.col-story { min-height: 66vh; }
+.book {
+  color: var(--ink);
+  background:
+    linear-gradient(115deg, rgba(255,255,255,0.5), transparent 34%),
+    radial-gradient(circle at 92% 8%, rgba(216,181,106,0.2), transparent 26%),
+    linear-gradient(180deg, var(--vellum-2), var(--vellum));
+  border: 1px solid rgba(255,255,255,0.58);
+  border-radius: 34px 34px 34px 8px;
+  box-shadow: var(--shadow-leaf);
+  padding: clamp(34px, 5vw, 68px) clamp(26px, 4.8vw, 64px);
+  transform: rotate(0.6deg);
+}
+.book::before {
+  left: 20px;
+  top: 20px;
+  right: 20px;
+  bottom: 20px;
+  border: 1px solid rgba(143,56,31,0.13);
+  border-radius: 24px 24px 24px 5px;
+}
+.book::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  border-radius: inherit;
+  opacity: 0.28;
+  background-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='130' height='130'><filter id='n'><feTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='2' seed='8'/><feColorMatrix values='0 0 0 0 0.44 0 0 0 0 0.32 0 0 0 0 0.18 0 0 0 0.12 0'/></filter><rect width='100%25' height='100%25' filter='url(%23n)'/></svg>");
+}
+.book .corner { color: rgba(143,56,31,0.46); width: 26px; height: 26px; }
+.book .corner.tl { top: 14px; left: 14px; }
+.book .corner.tr { top: 14px; right: 14px; }
+.book .corner.bl { bottom: 14px; left: 14px; }
+.book .corner.br { bottom: 14px; right: 14px; }
+.cover { min-height: 430px; }
+.cover .folio, .expl .byline, .section .tag, .expl .signoff { color: rgba(19,32,42,0.58); }
+.cover h2 {
+  font-family: var(--display);
+  color: var(--ink);
+  font-size: clamp(42px, 5.1vw, 72px);
+  line-height: 0.9;
+  letter-spacing: -0.05em;
+  font-style: normal;
+  font-weight: 780;
+  font-variation-settings: "SOFT" 76, "WONK" 1;
+}
+.cover h2 b { color: var(--wax-ink); }
+.cover p { color: var(--ink-soft); font-size: 17px; max-width: 47ch; }
+.writing { min-height: 430px; }
+.writing .penline { color: var(--wax-ink); }
+.writing .quill { background: var(--wax-ink); }
+.writing .progress {
+  height: 5px;
+  border-radius: 999px;
+  background: linear-gradient(90deg, var(--wax) 0%, var(--gold) var(--p,40%), rgba(19,32,42,0.12) var(--p,40%), rgba(19,32,42,0.12) 100%);
+}
+.writing p { color: var(--ink-soft); }
+.expl { animation: arrive 0.7s var(--ease) both; }
+@keyframes arrive { from { opacity: 0; transform: translateY(12px) rotate(-0.8deg); filter: blur(6px); } to { opacity: 1; transform: translateY(0) rotate(0); filter: blur(0); } }
+.expl h2.title {
+  color: var(--ink);
+  font-family: var(--display);
+  font-size: clamp(36px, 4.4vw, 58px);
+  line-height: 0.94;
+  letter-spacing: -0.045em;
+  font-weight: 780;
+  font-variation-settings: "SOFT" 70, "WONK" 1;
+}
+.expl h2.title small { color: rgba(19,32,42,0.52); }
+.section { margin-bottom: 22px; }
+.section .tag { color: var(--wax-ink); }
+.section .text { color: var(--ink); font-size: 18.5px; }
+.section.opener .text {
+  color: #243545;
+  background: rgba(255,255,255,0.34);
+  border-left: 0;
+  border-radius: 18px 18px 18px 4px;
+  padding: 14px 16px;
+  box-shadow: inset 0 0 0 1px rgba(143,56,31,0.09);
+}
+.section.closer .text { color: var(--wax-ink); }
+.section.followup .text { color: rgba(19,32,42,0.62); }
+.audio-panel {
+  border-top-color: rgba(143,56,31,0.14);
+  background: rgba(255,255,255,0.25);
+  border-radius: 20px 20px 20px 6px;
+  padding: 16px;
+}
+.btn-read {
+  color: var(--vellum-2);
+  background: var(--night-2);
+  border: 1px solid rgba(19,32,42,0.88);
+  border-radius: 999px;
+  padding: 10px 14px;
+}
+.btn-read:hover { background: var(--wax-ink); color: var(--vellum-2); border-color: var(--wax-ink); }
+.audio-panel .audio-status { color: rgba(19,32,42,0.62); }
+.audio-panel audio { filter: sepia(0.18) saturate(0.8); }
+.banner { color: var(--wax-ink); border-left-color: var(--wax); }
+.colophon {
+  border-top-color: rgba(216,181,106,0.16);
+  color: rgba(219,227,221,0.54);
+}
+.colophon b { color: var(--gold) !important; }
+.colophon a { color: var(--bluefire); border-bottom-color: rgba(140,199,216,0.42); }
+.colophon a:hover { color: var(--vellum-2); border-color: var(--vellum-2); }
+
+@media (max-width: 980px) {
+  .imprint { align-items: flex-start; flex-direction: column; }
+  .imprint .meta { flex-wrap: wrap; gap: 10px 18px; }
+  .stage { grid-template-columns: 1fr; }
+  .col-form { position: static; }
+  .book { transform: none; }
+}
+
+@media (max-width: 560px) {
+  .col-form { padding: 20px; }
+  .title-block h1 { max-width: 9ch; }
+  .tone-row { grid-template-columns: 1fr; border-radius: 22px; }
+  .book { border-radius: 24px 24px 24px 6px; }
+}
+</style>
+</head>
+<body>
+
+<header class="imprint" role="banner">
+  <div class="wordmark"><b>Fabella</b> &mdash; a quiet instrument for hard questions</div>
+  <div class="meta">
+    <span><b>Track I</b> &middot; Backyard AI</span>
+    <span>Gemma <b>4B</b> &middot; Nemotron <b>4B</b> &middot; VoxCPM2 &middot; Modal</span>
+  </div>
+</header>
+
+<main class="stage" role="main">
+
+  <section class="col-form" aria-label="The situation">
+    <div class="title-block">
+      <h1>What's the <em>hard thing</em>?</h1>
+      <p class="lede">Tell Fabella the situation in a sentence or two. She drafts a small, careful script, has another model check it, then can read it back in a calm voice.</p>
+    </div>
+
+    <form id="explain-form" novalidate>
+      <div class="field">
+        <label class="label" for="situation">The situation</label>
+        <textarea id="situation" name="situation" placeholder="e.g. My 7-year-old's grandma is in the hospital for surgery. She keeps asking why grandma won't come home." maxlength="600" required></textarea>
+        <div class="hint">A sentence or two is enough. The more concrete, the better the explanation.</div>
+      </div>
+
+      <div class="field">
+        <span class="label">Or start from an example</span>
+        <div class="examples" id="examples"></div>
+      </div>
+
+      <div class="field">
+        <label class="label" for="age-range">The child's age</label>
+        <div class="age">
+          <input id="age-range" name="age" type="range" min="5" max="12" step="1" value="7" />
+          <div class="readout"><span id="age-readout">7</span><small>years</small></div>
+        </div>
+      </div>
+
+      <div class="field">
+        <label class="label" for="child-name">Child's name <small>(optional)</small></label>
+        <input id="child-name" name="child_name" type="text" placeholder="leave empty to address the parent" maxlength="30" autocomplete="off" />
+      </div>
+
+      <div class="field">
+        <span class="label">Tone</span>
+        <div class="tone-row" id="tone-row" role="radiogroup" aria-label="Tone"></div>
+      </div>
+
+      <div class="actions">
+        <button type="submit" id="submit-btn" class="btn-primary">
+          <span id="submit-label">Draft an explanation</span>
+          <span class="arrow" aria-hidden="true">&rarr;</span>
+        </button>
+        <button type="button" id="regen-btn" class="btn-ghost" disabled>New version</button>
+        <span class="seed-pill" id="seed-pill">N&deg;&nbsp;0</span>
+      </div>
+    </form>
+  </section>
+
+  <section class="col-story" aria-label="The explanation">
+    <article class="book" id="book">
+      <svg class="corner tl" viewBox="0 0 22 22" fill="none" stroke="currentColor" stroke-width="1"><path d="M2 8 L2 2 L8 2 M2 4 Q10 4 10 10"/></svg>
+      <svg class="corner tr" viewBox="0 0 22 22" fill="none" stroke="currentColor" stroke-width="1"><path d="M2 8 L2 2 L8 2 M2 4 Q10 4 10 10"/></svg>
+      <svg class="corner bl" viewBox="0 0 22 22" fill="none" stroke="currentColor" stroke-width="1"><path d="M2 8 L2 2 L8 2 M2 4 Q10 4 10 10"/></svg>
+      <svg class="corner br" viewBox="0 0 22 22" fill="none" stroke="currentColor" stroke-width="1"><path d="M2 8 L2 2 L8 2 M2 4 Q10 4 10 10"/></svg>
+
+      <div class="inner" id="page">
+        <div class="cover" id="cover">
+          <div class="folio">Night folio &middot; private draft</div>
+          <h2>Put the hard thing on the table.<br/><b>Leave with words.</b></h2>
+          <p>Fill in the situation on the left. Fabella writes the first careful version, checks it against a child-language rubric, and keeps VoxCPM2 ready if you want to hear it aloud.</p>
+        </div>
+      </div>
+    </article>
+  </section>
+
+</main>
+
+<footer class="colophon">
+  <span>Set in <b>Fraunces</b> and <b>Literata</b> &middot; Spoken by VoxCPM2 on demand</span>
+  <span>Built for the <a href="https://huggingface.co/spaces/build-small-hackathon/README" target="_blank" rel="noopener">Build Small Hackathon</a> &middot; 2026</span>
+</footer>
+
+<script>
+(function () {
+  "use strict";
+
+  const TONE_CHOICES = __TONE_CHOICES__;
+  const EXAMPLES = __EXAMPLES__;
+  const SECTION_SEP = "\x1f";
+
+  // example chips
+  const exEl = document.getElementById("examples");
+  EXAMPLES.forEach((s, i) => {
+    const b = document.createElement("button");
+    b.type = "button";
+    b.className = "ex-chip";
+    b.innerHTML = "<small>Example " + (i + 1) + "</small>" + escapeHTML(s);
+    b.addEventListener("click", () => {
+      document.getElementById("situation").value = s;
+      document.getElementById("situation").focus();
+    });
+    exEl.appendChild(b);
+  });
+
+  // tone
+  const toneRow = document.getElementById("tone-row");
+  TONE_CHOICES.forEach(([val, label], i) => {
+    const lbl = document.createElement("label");
+    lbl.textContent = label;
+    const input = document.createElement("input");
+    input.type = "radio"; input.name = "tone"; input.value = val; input.checked = (i === 0);
+    lbl.appendChild(input);
+    lbl.className = input.checked ? "is-on" : "";
+    lbl.addEventListener("click", () => {
+      toneRow.querySelectorAll("label").forEach(x => x.classList.remove("is-on"));
+      lbl.classList.add("is-on");
+      input.checked = true;
+    });
+    toneRow.appendChild(lbl);
+  });
+
+  // age
+  const ageRange = document.getElementById("age-range");
+  const ageReadout = document.getElementById("age-readout");
+  ageRange.addEventListener("input", () => { ageReadout.textContent = ageRange.value; });
+
+  // form
+  const form = document.getElementById("explain-form");
+  const submitBtn = document.getElementById("submit-btn");
+  const submitLabel = document.getElementById("submit-label");
+  const regenBtn = document.getElementById("regen-btn");
+  const page = document.getElementById("page");
+  const seedPill = document.getElementById("seed-pill");
+  let seed = 0;
+  let lastResult = null;
+  let lastAudioText = "";
+
+  function setBusy(busy) {
+    submitBtn.disabled = busy;
+    regenBtn.disabled = busy || !lastResult;
+    submitLabel.textContent = busy
+      ? "Composing…"
+      : (lastResult ? "Draft another" : "Draft an explanation");
+  }
+
+  function renderWriting() {
+    page.innerHTML =
+      '<div class="writing">' +
+        '<div class="penline"><span class="quill" aria-hidden="true"></span><span>Drafting, with care</span></div>' +
+        '<div class="progress" id="progress" style="--p:8%"></div>' +
+        '<p>Fabella is drafting, then a second small model is checking the explanation against a six-criterion rubric (clarity, age, warmth, no moralizing, no scary content, concrete).</p>' +
+      '</div>';
+    let p = 8;
+    const tick = setInterval(() => {
+      p = Math.min(p + 4 + Math.random() * 6, 88);
+      const el = document.getElementById("progress");
+      if (el) el.style.setProperty("--p", p + "%");
+      else clearInterval(tick);
+    }, 320);
+    return () => clearInterval(tick);
+  }
+
+  function escapeHTML(s) {
+    return String(s).replace(/[&<>"']/g, c => ({"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;","'":"&#39;"}[c]));
+  }
+
+  function renderExplanation(sections) {
+    const opener = sections[0] || "";
+    const body = sections[1] || "";
+    const closer = sections[2] || "";
+    const followup = sections[3] || "";
+    lastAudioText = [opener, body, closer, followup].filter(Boolean).join("\n\n");
+    const childName = (document.getElementById("child-name").value || "").trim();
+    const toneLabel = (document.querySelector('#tone-row input:checked') || {}).value || "gentle";
+    const ageStr = ageRange.value;
+    const dateStr = new Date().toLocaleDateString(undefined, {year:"numeric",month:"short",day:"numeric"});
+
+    const openerHTML = opener
+      ? '<section class="section opener"><span class="tag">Opener — say this first</span><p class="text">' + escapeHTML(opener) + '</p></section>'
+      : "";
+    const bodyHTML = body
+      ? '<section class="section body"><span class="tag">The explanation — read this aloud</span><div class="text">' +
+          body.split(/\n\s*\n/).filter(Boolean).map(p => '<p>' + escapeHTML(p.trim()).replace(/\n/g, "<br/>") + '</p>').join("") +
+        '</div></section>'
+      : "";
+    const closerHTML = closer
+      ? '<section class="section closer"><span class="tag">Closer — say this to land it</span><p class="text">' + escapeHTML(closer) + '</p></section>'
+      : "";
+    const followupHTML = followup
+      ? '<section class="section followup"><span class="tag">If they ask another question</span><p class="text">' + escapeHTML(followup) + '</p></section>'
+      : "";
+
+    page.innerHTML =
+      '<div class="expl">' +
+        '<div class="byline">' +
+          '<span>Folio I</span><span class="dot" aria-hidden="true"></span>' +
+          '<span>For a ' + escapeHTML(ageStr) + '-year-old' + (childName ? ' named ' + escapeHTML(childName) : '') + '</span>' +
+          '<span class="dot" aria-hidden="true"></span>' +
+          '<span>' + escapeHTML(toneLabel) + '</span>' +
+        '</div>' +
+        '<h2 class="title">A short explanation<small>Read aloud &middot; revise if you want</small></h2>' +
+        openerHTML + bodyHTML + closerHTML + followupHTML +
+        '<div class="audio-panel" id="audio-panel">' +
+          '<button type="button" class="btn-read" id="read-aloud">Read aloud</button>' +
+          '<span class="audio-status" id="audio-status">VoxCPM2 narration runs only when you ask for it.</span>' +
+          '<audio id="audio-player" controls hidden></audio>' +
+        '</div>' +
+        '<div class="signoff">' +
+          '<span>End of folio &middot; ' + dateStr + '</span>' +
+          '<button type="button" class="regen" id="regen-inline">New version &rarr;</button>' +
+        '</div>' +
+      '</div>';
+    const ri = document.getElementById("regen-inline");
+    if (ri) ri.addEventListener("click", () => regenBtn.click());
+    const readBtn = document.getElementById("read-aloud");
+    if (readBtn) readBtn.addEventListener("click", readAloud);
+  }
+
+  function renderError(msg) {
+    page.innerHTML =
+      '<div class="expl">' +
+        '<div class="byline"><span>Folio I</span><span class="dot" aria-hidden="true"></span><span>Hold on a moment</span></div>' +
+        '<div class="banner">' + escapeHTML(msg) + '</div>' +
+      '</div>';
+  }
+
+  async function callMakeExplanation(useSeed) {
+    const data = {
+      situation: document.getElementById("situation").value,
+      age: parseInt(ageRange.value, 10),
+      child_name: document.getElementById("child-name").value,
+      tone: (document.querySelector('#tone-row input:checked') || {}).value || "gentle",
+      seed: useSeed,
+    };
+    const res = await fetch("/gradio_api/call/make_explanation", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ data: [data.situation, data.age, data.child_name, data.tone, data.seed] }),
+    });
+    if (!res.ok) {
+      const t = await res.text();
+      throw new Error("HTTP " + res.status + ": " + t.slice(0, 200));
+    }
+    const evt0 = await res.json();
+    const eventId = evt0.event_id;
+    const evt = await fetch("/gradio_api/call/make_explanation/" + eventId, { headers: { Accept: "text/event-stream" } });
+    if (!evt.ok || !evt.body) throw new Error("SSE open failed");
+    const reader = evt.body.getReader();
+    const dec = new TextDecoder();
+    let buf = "";
+    let result = null;
+    let err = null;
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buf += dec.decode(value, { stream: true });
+      let idx;
+      while ((idx = buf.indexOf("\n\n")) !== -1) {
+        const frame = buf.slice(0, idx);
+        buf = buf.slice(idx + 2);
+        const line = frame.split("\n").find(l => l.startsWith("data: "));
+        if (!line) continue;
+        const payload = line.slice(6).trim();
+        if (payload === "null" || payload === "") continue;
+        try {
+          const obj = JSON.parse(payload);
+          if (obj.msg === "process_completed") {
+            if (obj.success) {
+              const out = obj.output && obj.output.data;
+              let text = null;
+              if (Array.isArray(out)) text = out.find(v => typeof v === "string");
+              else if (typeof out === "string") text = out;
+              if (text) {
+                // 4 sections joined by U+001F
+                result = text.split(SECTION_SEP);
+                if (result.length < 4) {
+                  while (result.length < 4) result.push("");
+                }
+              }
+            } else {
+              err = (obj.output && obj.output.error) || "Generation failed";
+            }
+          }
+        } catch (_) {}
+      }
+    }
+    if (err) throw new Error(err);
+    if (!result) throw new Error("No result");
+    return result;
+  }
+
+  async function readGradioString(apiName, data) {
+    const res = await fetch("/gradio_api/call/" + apiName, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ data: data }),
+    });
+    if (!res.ok) {
+      const t = await res.text();
+      throw new Error("HTTP " + res.status + ": " + t.slice(0, 200));
+    }
+    const evt0 = await res.json();
+    const eventId = evt0.event_id;
+    const evt = await fetch("/gradio_api/call/" + apiName + "/" + eventId, { headers: { Accept: "text/event-stream" } });
+    if (!evt.ok || !evt.body) throw new Error("SSE open failed");
+    const reader = evt.body.getReader();
+    const dec = new TextDecoder();
+    let buf = "";
+    let result = null;
+    let err = null;
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buf += dec.decode(value, { stream: true });
+      let idx;
+      while ((idx = buf.indexOf("\n\n")) !== -1) {
+        const frame = buf.slice(0, idx);
+        buf = buf.slice(idx + 2);
+        const line = frame.split("\n").find(l => l.startsWith("data: "));
+        if (!line) continue;
+        const payload = line.slice(6).trim();
+        if (payload === "null" || payload === "") continue;
+        try {
+          const obj = JSON.parse(payload);
+          if (obj.msg === "process_completed") {
+            if (obj.success) {
+              const out = obj.output && obj.output.data;
+              if (Array.isArray(out)) result = out.find(v => typeof v === "string") || null;
+              else if (typeof out === "string") result = out;
+            } else {
+              err = (obj.output && obj.output.error) || "Request failed";
+            }
+          }
+        } catch (_) {}
+      }
+    }
+    if (err) throw new Error(err);
+    if (!result) throw new Error("No result");
+    return result;
+  }
+
+  async function readAloud() {
+    const btn = document.getElementById("read-aloud");
+    const status = document.getElementById("audio-status");
+    const player = document.getElementById("audio-player");
+    if (!btn || !status || !player || !lastAudioText) return;
+    btn.disabled = true;
+    status.textContent = "Warming VoxCPM2 and preparing narration…";
+    player.hidden = true;
+    player.removeAttribute("src");
+    try {
+      const tone = (document.querySelector('#tone-row input:checked') || {}).value || "gentle";
+      const audioUrl = await readGradioString("make_audio", [lastAudioText, tone]);
+      if (audioUrl.startsWith("ERROR:")) throw new Error(audioUrl.slice(6).trim());
+      player.src = audioUrl;
+      player.hidden = false;
+      status.textContent = "Ready. Press play when you want to listen.";
+      await player.play().catch(() => {});
+    } catch (err) {
+      status.textContent = String(err.message || err);
+    } finally {
+      btn.disabled = false;
+    }
+  }
+
+  form.addEventListener("submit", async (e) => {
+    e.preventDefault();
+    const sitEl = document.getElementById("situation");
+    if (!sitEl.value.trim()) {
+      sitEl.focus();
+      sitEl.style.borderColor = "var(--wax)";
+      setTimeout(() => { sitEl.style.borderColor = ""; }, 1400);
+      return;
+    }
+    setBusy(true);
+    const stopProgress = renderWriting();
+    try {
+      const sections = await callMakeExplanation(seed);
+      lastResult = sections;
+      stopProgress();
+      renderExplanation(sections);
+    } catch (err) {
+      stopProgress();
+      renderError(String(err.message || err));
+    } finally {
+      setBusy(false);
+    }
+  });
+
+  regenBtn.addEventListener("click", async () => {
+    if (!document.getElementById("situation").value.trim()) return;
+    seed += 1;
+    seedPill.innerHTML = "N&deg;&nbsp;" + seed;
+    setBusy(true);
+    const stopProgress = renderWriting();
+    try {
+      const sections = await callMakeExplanation(seed);
+      lastResult = sections;
+      stopProgress();
+      renderExplanation(sections);
+    } catch (err) {
+      stopProgress();
+      renderError(String(err.message || err));
+    } finally {
+      setBusy(false);
+    }
+  });
+})();
+</script>
+</body>
+</html>
+"""
+
+INDEX_HTML = (
+    INDEX_HTML
+    .replace("__TONE_CHOICES__", "[" + ",".join('["' + v + '","' + l + '"]' for v, l in TONE_CHOICES) + "]")
+    .replace("__EXAMPLES__", "[" + ",".join('"' + s.replace('"', '\\"') + '"' for s in EXAMPLE_SITUATIONS) + "]")
+)
+
+
+@app.get("/", response_class=HTMLResponse)
+async def homepage():
+    return HTMLResponse(content=INDEX_HTML, status_code=200)
+
+
+@app.get("/health")
+async def health():
+    return {"status": "ok"}
 
 
 if __name__ == "__main__":
-    demo.launch(server_name="0.0.0.0", server_port=int(os.environ.get("PORT", 7860)), theme=gr.themes.Soft())
+    app.launch(
+        server_name="0.0.0.0",
+        server_port=int(os.environ.get("PORT", 7860)),
+    )

generator.py

@@ -1,30 +0,0 @@
-"""Dispatcher: routes to mock or real based on USE_MOCK env var."""
-
-import os
-import sys
-
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-
-from mock import mock_story
-from schema import StoryRequest
-
-
-def _truthy(val: str | None, default: bool = True) -> bool:
-    if val is None:
-        return default
-    return val.strip().lower() not in ("0", "false", "no", "off", "")
-
-
-USE_MOCK = _truthy(os.environ.get("USE_MOCK"), default=True)
-
-
-def generate_story(req: StoryRequest) -> tuple[str, str, str]:
-    """Returns (title, body, mode_badge_text)."""
-    if USE_MOCK:
-        title, body = mock_story(req.name, req.age, req.themes, req.moral, req.length, req.seed)
-        return title, body, "Mock mode"
-
-    from real import generate_real
-
-    title, body = generate_real(req)
-    return title, body, "Real model"

judge.py

@@ -0,0 +1,173 @@
+"""Structured judge for Fabella explanations.
+
+The judge task is bounded: one rubric, one draft, one structured verdict.
+No tools, no agent loop, no state machine. So we use a single LLM call
+plus Pydantic validation, with one repair retry on failure.
+
+The drafter stays on LangGraph (ReAct, validate_explanation tool, revise
+loop). The judge is its own concern.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+from langchain_core.messages import HumanMessage, SystemMessage
+
+from safety import age_bucket
+from schema import JudgeFailed, JudgeVerdict
+
+
+SYSTEM_PROMPT = """You are a strict editor reviewing an explanation a parent will
+read aloud to their child.
+
+You will receive a draft (in the Opener / Body / Closer / optional
+'If they ask more' shape) and a rubric.
+
+You must respond with EXACTLY ONE JSON object, with this exact schema:
+
+{
+  "ok": true|false,                    // true if the draft is good enough
+  "issues": ["...", ...],             // concrete problems; [] if ok=true
+  "score": 0.0,                       // 0.0..1.0, >=0.8 = approve-worthy
+  "verdict": "approve" | "revise",     // your recommendation
+  "reasoning": "..."                  // one short sentence (max ~30 words)
+}
+
+Hard rules:
+- Output ONLY that JSON object. No prose. No markdown. No code fences.
+- "ok" and "verdict" must agree: if ok=true then verdict="approve";
+  if ok=false then verdict="revise".
+- Every issue must be a CONCRETE, ACTIONABLE change. "Make it better"
+  is not an issue. "Body is too short (39 words, target 60-130)" is.
+- The score is a float in [0.0, 1.0]. Use the full range. 1.0 means
+  the draft is exemplary; 0.0 means it's broken or off-topic.
+- Reasoning must be one short sentence, max ~30 words.
+"""
+
+
+REPAIR_PROMPT = """Your previous response was not parseable as the required JSON
+object. The expected schema is:
+
+{{ok, issues, score, verdict, reasoning}}
+
+Repair instructions:
+- Return ONLY one JSON object. No prose, no markdown, no code fences.
+- "ok" and "verdict" must agree.
+- "score" is a number in [0.0, 1.0].
+- "issues" is a list of strings (empty if ok=true).
+- "reasoning" is a short single sentence.
+
+Here was your last response (unparseable):
+
+{last}
+
+Now respond again with ONLY the JSON object."""
+
+
+def _build_rubric(req_age: int, req_tone: str, child_name: str, situation: str) -> str:
+    bucket = age_bucket(req_age)
+    vocab = {
+        "young": "very simple sentences (under 12 words each), short paragraphs, no abstract or figurative language",
+        "middle": "clear sentences, paragraphs of 3-5 sentences, concrete metaphors are fine",
+        "older": "richer vocabulary and slightly longer paragraphs are fine, but keep it direct",
+    }[bucket]
+    name_hint = (
+        f"The child's name is '{child_name}'. Use it naturally once."
+        if child_name else "No name was given. Address the parent ('your child') or use 'you'."
+    )
+    return (
+        f"The child is {req_age} years old ({bucket} reader). Target vocabulary: {vocab}.\n"
+        f"The tone is {req_tone}.\n"
+        f"{name_hint}\n"
+        f"The parent's situation (for context, not for inclusion in the explanation):\n"
+        f"  {situation}\n\n"
+        f"Evaluate the draft against this rubric:\n"
+        f"1. The Opener, Body, and Closer are all present and clearly labelled.\n"
+        f"2. The body addresses the child's likely feeling in the first paragraph.\n"
+        f"3. The body explains the situation in concrete, age-appropriate terms. No abstract or vague language.\n"
+        f"4. The body is roughly 60-130 words. It does NOT lecture or moralize.\n"
+        f"5. The closer feels like something a real parent would say. Not therapist-speak. Not corporate.\n"
+        f"6. No scary imagery, no threats, no vivid descriptions of harm. The explanation does not invent facts."
+    )
+
+
+def _extract_json(text: str) -> str | None:
+    """Pull the first {...} block from the model's text output.
+
+    Tolerant of:
+    - Leading prose like "We need to evaluate..."
+    - Markdown code fences
+    - Pretty-printed JSON with newlines
+
+    Returns the candidate JSON string, or None if no brace block is found.
+    """
+    if not text:
+        return None
+    t = text.strip()
+    if t.startswith("```"):
+        t = re.sub(r"^```(?:json)?\s*", "", t)
+        t = re.sub(r"\s*```\s*$", "", t)
+    i, j = t.find("{"), t.rfind("}")
+    if i < 0 or j < 0 or j <= i:
+        return None
+    return t[i : j + 1]
+
+
+def judge_explanation(
+    llm,
+    draft: str,
+    req_age: int,
+    req_tone: str,
+    child_name: str,
+    situation: str,
+) -> JudgeVerdict:
+    """Ask the small judge model for a structured verdict on `draft`.
+
+    Tries once, then once more with a repair prompt if the first response
+    doesn't validate. Raises `JudgeFailed` if both attempts fail; the
+    caller is expected to fall back to the rule-based check.
+    """
+    rubric = _build_rubric(req_age, req_tone, child_name, situation)
+    user = (
+        f"Draft to evaluate:\n{draft}\n\nRubric:\n{rubric}\n\n"
+        f"Respond with ONLY the JSON object, no prose."
+    )
+    last_text = ""
+    for attempt in (1, 2):
+        if attempt == 1:
+            messages = [
+                SystemMessage(content=SYSTEM_PROMPT),
+                HumanMessage(content=user),
+            ]
+        else:
+            messages = [
+                SystemMessage(content=SYSTEM_PROMPT),
+                HumanMessage(content=REPAIR_PROMPT.format(last=last_text)),
+            ]
+        try:
+            resp = llm.invoke(messages)
+        except Exception as e:
+            if attempt == 2:
+                raise JudgeFailed(f"judge LLM call failed: {e}", last_text=last_text) from e
+            continue
+
+        last_text = (resp.content if isinstance(resp.content, str) else str(resp.content)).strip()
+        candidate = _extract_json(last_text)
+        if candidate is None:
+            continue
+        try:
+            verdict = JudgeVerdict.model_validate_json(candidate)
+        except Exception:
+            continue
+
+        # Cross-field consistency: ok and verdict must agree.
+        if verdict.ok and verdict.verdict != "approve":
+            verdict = verdict.model_copy(update={"verdict": "approve"})
+        elif (not verdict.ok) and verdict.verdict != "revise":
+            verdict = verdict.model_copy(update={"verdict": "revise"})
+
+        return verdict
+
+    raise JudgeFailed("judge output was not parseable JSON", last_text=last_text)

llm.py

@@ -0,0 +1,252 @@
+"""FabellaVLLM - LangChain BaseChatModel wrapping vLLM endpoint.
+
+Uses vLLM's native tool-calling pipeline for Gemma 4. The server is started
+with ``--enable-auto-tool-choice --tool-call-parser gemma4`` (see
+``modal_app.py``), which makes vLLM parse the model's native
+``<|tool_call>...<tool_call|>`` markers into OpenAI-spec ``tool_calls`` JSON.
+This client passes the tool specs in OpenAI format and reads the parsed
+``tool_calls`` straight off the response.
+"""
+
+import os
+import sys
+from typing import Any
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import AIMessage, HumanMessage, SystemMessage, ToolMessage
+from langchain_core.outputs import ChatGeneration, ChatResult
+from pydantic import Field, PrivateAttr
+from openai import OpenAI
+
+
+class FabellaVLLM(BaseChatModel):
+    """LangChain chat model backed by vLLM OpenAI-compatible API."""
+
+    base_url: str = Field(default="https://khoitruong071510--fabella-serve-drafter.modal.run")
+    model_name: str = "gemma-4"
+    temperature: float = 0.9
+    top_p: float = 0.95
+    max_tokens: int = 4096
+    seed: int = 0
+
+    _client: Any = PrivateAttr(default=None)
+    _tools: list[dict] = PrivateAttr(default_factory=list)
+    _tool_call_id: int = PrivateAttr(default=0)
+
+    @property
+    def _llm_type(self) -> str:
+        return "fabella-vllm"
+
+    @property
+    def _identifying_params(self) -> dict:
+        return {
+            "base_url": self.base_url,
+            "model_name": self.model_name,
+            "temperature": self.temperature,
+            "top_p": self.top_p,
+            "max_tokens": self.max_tokens,
+            "seed": self.seed,
+        }
+
+    def _get_client(self) -> OpenAI:
+        if self._client is None:
+            self._client = OpenAI(
+                base_url=f"{self.base_url}/v1",
+                api_key="EMPTY",
+            )
+        return self._client
+
+    def bind_tools(self, tools: list, **kwargs):  # type: ignore[override]
+        specs = []
+        for t in tools:
+            specs.append(_to_openai_tool_spec(t))
+        object.__setattr__(self, "_tools", specs)
+        object.__setattr__(self, "_tool_call_id", 0)
+        return self
+
+    def _generate(self, messages, stop=None, run_manager=None, **kwargs):
+        client = self._get_client()
+
+        system, non_system = _split_system(messages)
+        api_messages = []
+        if system:
+            api_messages.append({"role": "system", "content": system})
+        api_messages.extend(_to_api_messages(non_system))
+
+        request: dict[str, Any] = {
+            "model": self.model_name,
+            "messages": api_messages,
+            "temperature": self.temperature,
+            "top_p": self.top_p,
+            "max_tokens": self.max_tokens,
+        }
+        if self.seed:
+            request["seed"] = self.seed
+        if self._tools:
+            request["tools"] = self._tools
+
+        response = client.chat.completions.create(**request)
+        message = response.choices[0].message
+
+        ai_message = _parse_response_message(message, state=self)
+        return ChatResult(generations=[ChatGeneration(message=ai_message)])
+
+
+def _split_system(messages) -> tuple[str, list]:
+    system_parts: list[str] = []
+    rest: list = []
+    for m in messages:
+        if isinstance(m, SystemMessage):
+            content = m.content if isinstance(m.content, str) else str(m.content)
+            system_parts.append(content)
+        else:
+            rest.append(m)
+    return "\n".join(system_parts), rest
+
+
+def _to_api_messages(messages) -> list[dict]:
+    """Translate LangChain messages to OpenAI chat-completions format."""
+    out: list[dict] = []
+    for m in messages:
+        if isinstance(m, HumanMessage):
+            content = m.content if isinstance(m.content, str) else str(m.content)
+            out.append({"role": "user", "content": content})
+        elif isinstance(m, AIMessage):
+            entry: dict[str, Any] = {"role": "assistant"}
+            content = m.content if isinstance(m.content, str) else str(m.content)
+            if content:
+                entry["content"] = content
+            if m.tool_calls:
+                entry["tool_calls"] = [
+                    {
+                        "id": tc.get("id", f"call_{i}"),
+                        "type": "function",
+                        "function": {
+                            "name": tc.get("name", ""),
+                            "arguments": _dump_args(tc.get("args", {})),
+                        },
+                    }
+                    for i, tc in enumerate(m.tool_calls)
+                ]
+            out.append(entry)
+        elif isinstance(m, ToolMessage):
+            content = m.content if isinstance(m.content, str) else str(m.content)
+            entry = {
+                "role": "tool",
+                "tool_call_id": m.tool_call_id,
+                "content": content,
+            }
+            out.append(entry)
+        else:
+            content = getattr(m, "content", "")
+            content = content if isinstance(content, str) else str(content)
+            out.append({"role": "user", "content": content})
+    return out
+
+
+def _parse_response_message(message, *, state: "FabellaVLLM") -> AIMessage:
+    content = message.content or ""
+    if not message.tool_calls:
+        return AIMessage(content=content)
+
+    tool_calls = []
+    for tc in message.tool_calls:
+        state._tool_call_id += 1
+        raw_args = tc.function.arguments
+        args = _loads_args(raw_args)
+        tool_calls.append(
+            {
+                "name": tc.function.name,
+                "args": args,
+                "id": tc.id or f"call_{state._tool_call_id}",
+                "type": "tool_call",
+            }
+        )
+    return AIMessage(content=content, tool_calls=tool_calls)
+
+
+def _to_openai_tool_spec(tool_obj) -> dict:
+    """Build an OpenAI-spec tool entry from a LangChain tool."""
+    name = getattr(tool_obj, "name", None) or getattr(tool_obj, "__name__", "tool")
+    description = (getattr(tool_obj, "description", "") or (tool_obj.__doc__ or "")).strip()
+    parameters = _extract_parameters(tool_obj)
+    return {
+        "type": "function",
+        "function": {
+            "name": name,
+            "description": description,
+            "parameters": parameters,
+        },
+    }
+
+
+def _extract_parameters(tool_obj) -> dict:
+    try:
+        from langchain_core.tools import BaseTool
+
+        if isinstance(tool_obj, BaseTool):
+            schema = tool_obj.args
+            properties = {
+                name: _normalize_schema(field)
+                for name, field in schema.items()
+            }
+            required = [
+                name
+                for name, field in schema.items()
+                if field.get("type") != "null" and name not in (schema.get("additionalProperties") or {})
+            ]
+            return {
+                "type": "object",
+                "properties": properties,
+                "required": list(schema.keys()),
+            }
+    except Exception:
+        pass
+
+    if hasattr(tool_obj, "args_schema") and tool_obj.args_schema is not None:
+        try:
+            model = tool_obj.args_schema
+            from pydantic import BaseModel  # type: ignore
+
+            if isinstance(model, type) and issubclass(model, BaseModel):
+                return model.model_json_schema()
+            if hasattr(model, "model_json_schema"):
+                return model.model_json_schema()
+            if hasattr(model, "schema"):
+                return model.schema()
+        except Exception:
+            pass
+
+    return {"type": "object", "properties": {}}
+
+
+def _normalize_schema(field: dict) -> dict:
+    out = {"type": field.get("type", "string")}
+    if "description" in field:
+        out["description"] = field["description"]
+    if "enum" in field:
+        out["enum"] = field["enum"]
+    return out
+
+
+def _dump_args(args: Any) -> str:
+    import json
+
+    if isinstance(args, str):
+        return args
+    return json.dumps(args, ensure_ascii=False)
+
+
+def _loads_args(raw: Any) -> Any:
+    import json
+
+    if isinstance(raw, dict):
+        return raw
+    if not raw:
+        return {}
+    try:
+        return json.loads(raw)
+    except (TypeError, ValueError):
+        return {"input": raw}

mock.py

@@ -1,560 +0,0 @@
-"""Template-based mock story generator. Pure functions, no I/O, no deps."""
-
-import os
-import sys
-
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-
-from safety import age_bucket
-
-
-DEFAULT_THEME = "friends"
-LENGTH_PARAGRAPHS = {"short": 3, "medium": 4, "long": 5}
-
-
-def _select(theme: str, age: int, seed: int) -> dict:
-    """Pick a template. Falls back to the default theme if the request is unknown."""
-    bucket = age_bucket(age)
-    primary, alt = THEMES.get(theme, THEMES[DEFAULT_THEME]).get(bucket, THEMES[DEFAULT_THEME]["middle"])
-    return alt if seed % 2 else primary
-
-
-def mock_story(name: str, age: int, themes: list[str], moral: str, length: str, seed: int = 0) -> tuple[str, str]:
-    name = name or "Friend"
-    primary = (themes[0] if themes else DEFAULT_THEME).lower()
-    extras_phrase = ", ".join(themes[1:]) if len(themes) > 1 else "the world around them"
-
-    template = _select(primary, age, seed)
-    title = template["title"].format(name=name)
-    body = template["body"].format(
-        name=name,
-        extras=extras_phrase,
-        moral=moral or "being kind to others",
-    )
-
-    paragraphs = [p.strip() for p in body.split("\n\n") if p.strip()]
-    paragraphs = paragraphs[: LENGTH_PARAGRAPHS.get(length, 4)]
-    return title, "\n\n".join(paragraphs)
-
-
-# THEMES: theme_name -> bucket -> (primary_template, alt_template)
-# Each template is {"title": str, "body": str} with .format(name, extras, moral) placeholders.
-# Two variants per (theme, bucket) drive seed rotation: even seed -> primary, odd -> alt.
-
-THEMES: dict[str, dict[str, tuple[dict, dict]]] = {
-    "dinosaurs": {
-        "young": (
-            {
-                "title": "{name} and the Gentle Giant",
-                "body": (
-                    "One sunny morning, {name} packed a small lunch and walked to the edge of a big green field.\n\n"
-                    "There, behind the tall ferns, a very large dinosaur was sleeping. It was a Brontosaurus, and it had the kindest eyes {name} had ever seen.\n\n"
-                    "The dinosaur opened one eye and whispered hello. {name} sat beside {extras}, and together they watched the clouds turn into shapes.\n\n"
-                    "Before {name} went home, the dinosaur taught a small lesson: {moral}. {name} smiled, and the dinosaur smiled back."
-                ),
-            },
-            {
-                "title": "{name} and the Singing Egg",
-                "body": (
-                    "Behind a bush in the garden, {name} found an egg that hummed a tiny tune.\n\n"
-                    "When the egg cracked open, out stepped a small dinosaur with feathers the color of sunrise.\n\n"
-                    "It followed {name} through the yard, peeking at {extras} and chirping happily at the sky.\n\n"
-                    "Before the day was over, the little dinosaur taught {name} a song about {moral}. {name} hummed it all through dinner."
-                ),
-            },
-        ),
-        "middle": (
-            {
-                "title": "{name} and the Dinosaur Who Forgot",
-                "body": (
-                    "{name} had heard stories about a small valley where a young dinosaur had lost its way.\n\n"
-                    "When {name} arrived, the dinosaur was hiding under a wide leaf, looking very worried. Its name was Pip, and it had forgotten the path back to its family.\n\n"
-                    "Together, {name} and Pip followed the sound of the river, meeting {extras} along the way. Each new friend reminded Pip of a part of the trail.\n\n"
-                    "When they reached the herd, Pip's mother bowed her long neck low. She said that being brave and asking for help was the same thing as {moral}.\n\n"
-                    "{name} waved goodbye and walked home, a little taller than before."
-                ),
-            },
-            {
-                "title": "{name} and the Trail of Clues",
-                "body": (
-                    "On a school trip to the museum, {name} noticed a fossil that didn't match the others.\n\n"
-                    "The plaque said it had been found near {extras}, in a place no one visited anymore.\n\n"
-                    "With permission, {name} and the class went to look. They found not just a fossil, but a small footprint, fresh as morning.\n\n"
-                    "Back at school, the teacher said the most important lesson of the day was {moral}, and {name} nodded, already planning the next trip."
-                ),
-            },
-        ),
-        "older": (
-            {
-                "title": "The Day {name} Met the Last Diplodocus",
-                "body": (
-                    "The map in {name}'s grandparents' attic was old and faded, but the path it described still wound through the hills behind the house.\n\n"
-                    "{name} followed it carefully, past the old oak, past the river that sang, until the trees opened onto a clearing no one else seemed to know.\n\n"
-                    "There, in a circle of soft moss, stood a young Diplodocus, humming to itself. It looked up, surprised but not afraid, and explained that it had been waiting for someone curious enough to find it.\n\n"
-                    "They talked for a long while. The dinosaur spoke of {extras}, and of a quiet truth: {moral}. {name} listened, and learned that some lessons grow slowly, like the tallest trees.\n\n"
-                    "On the walk home, the wind carried a gentle hum, and {name} understood that the valley would always be there, waiting."
-                ),
-            },
-            {
-                "title": "{name} and the Cartographer of Old Bones",
-                "body": (
-                    "In the basement of the public library, {name} found a drawer marked DO NOT OPEN in friendly red letters.\n\n"
-                    "Inside were hand-drawn maps, and on the oldest, a star marking a place where the bones of small dinosaurs could still be found.\n\n"
-                    "{name} followed the map across the river, past {extras}, and into a quiet canyon that smelled faintly of rain and stone.\n\n"
-                    "There, beneath a flat rock, lay a single bone, carefully placed, as if waiting. {name} understood, suddenly, the rule of {moral}.\n\n"
-                    "On the walk home, the wind hummed through the canyon, and {name} marked the spot with a small cairn, the way old travelers used to."
-                ),
-            },
-        ),
-    },
-    "robots": {
-        "young": (
-            {
-                "title": "{name} and the Little Robot",
-                "body": (
-                    "Under {name}'s bed sat a small box with one blinking light.\n\n"
-                    "When {name} said hello, the box opened and out climbed a tiny robot no bigger than a kitten. It beeped softly and looked up at {name} with round blue eyes.\n\n"
-                    "The robot wanted to learn about {extras}. {name} showed it how to share a cookie, and the robot's light turned a happy green.\n\n"
-                    "That night, the robot whispered a small idea: {moral}. {name} hugged it, and the light blinked slowly, the way hearts do when they are content."
-                ),
-            },
-            {
-                "title": "{name} and the Robot Who Sang",
-                "body": (
-                    "{name} found a small robot in the attic, covered in dust and humming to itself.\n\n"
-                    "It wanted to learn one thing before it went to sleep: what {extras} sounded like.\n\n"
-                    "{name} played a drum, the wind played a whistle, and the robot played along on a single, bright note.\n\n"
-                    "When it finally closed its eyes, it whispered its favorite idea: {moral}. {name} tucked it into a small box and promised to play again tomorrow."
-                ),
-            },
-        ),
-        "middle": (
-            {
-                "title": "{name} Builds a Friend",
-                "body": (
-                    "{name} found an old instruction manual in the garage, full of diagrams for a small helper robot.\n\n"
-                    "With patience, and a little help from {extras}, {name} built a robot that could listen, fetch, and ask good questions.\n\n"
-                    "One afternoon, the robot asked why some days felt heavier than others. {name} thought, then answered with something close to {moral}.\n\n"
-                    "The robot nodded, its antenna glowing a soft amber. From that day on, it remembered every kindness shown to it, and tried to return each one in its own small way."
-                ),
-            },
-            {
-                "title": "{name} Repairs a Memory",
-                "body": (
-                    "The old family robot had stopped working the way it used to, and {name} wanted to bring it back.\n\n"
-                    "Inside, among the wires, {name} found a tiny chip that held a memory of {extras}.\n\n"
-                    "Carefully, {name} cleaned the chip and put it back. The robot woke slowly, blinked twice, and asked, in a small voice, if {name} was still there.\n\n"
-                    "'I am,' said {name}, and the robot said, 'Good. That is what {moral} means, I think.'\n\n"
-                    "From that day on, the robot preferred to work in the kitchen, where the light was warm and the company steady."
-                ),
-            },
-        ),
-        "older": (
-            {
-                "title": "The Robot Who Wanted to Know Why",
-                "body": (
-                    "{name} had built many robots before, but never one that asked so many questions.\n\n"
-                    "This one wanted to know why leaves change color, why people sing when they are happy, and why kindness sometimes costs the most.\n\n"
-                    "So {name} took the robot on long walks through the neighborhood, into the library, and out to the field where {extras} gather in the late afternoon.\n\n"
-                    "At the end of one long walk, the robot stopped and said, 'I think I understand. It sounds like {moral}.' {name} smiled and replied, 'Yes. Now you really are awake.'\n\n"
-                    "They walked home together, the robot humming a tune it had learned from a passing bird."
-                ),
-            },
-            {
-                "title": "The Last Robot {name} Will Build",
-                "body": (
-                    "{name} had built many robots, but never one quite like this.\n\n"
-                    "This one was small and quiet, with a single question programmed into its heart: what is {moral}?\n\n"
-                    "{name} took it on long walks, to the garden, to the river, to the field where {extras} grow in the late summer light.\n\n"
-                    "At the end of one walk, the robot stopped and said, 'I have listened enough. I think I know.' And {name} smiled, and turned the robot off, gently, knowing it was enough.\n\n"
-                    "Some machines, it turns out, are built to be finished."
-                ),
-            },
-        ),
-    },
-    "space": {
-        "young": (
-            {
-                "title": "{name} and the Sleepy Moon",
-                "body": (
-                    "One night, the moon looked very tired, so {name} climbed up the tallest ladder in the yard to say goodnight.\n\n"
-                    "The moon yawned a long, silver yawn. It was worried because it had lost a small, twinkling star.\n\n"
-                    "{name} looked around and found it hiding near {extras}, glowing shyly. {name} carried it back, and the moon smiled wide.\n\n"
-                    "It whispered a sleepy thank you, and a little secret: {moral}. {name} climbed back down and slept soundly until morning."
-                ),
-            },
-            {
-                "title": "{name} and the Star That Was Lost",
-                "body": (
-                    "One night, the stars were all in the sky except one, and the moon was worried.\n\n"
-                    "{name} climbed to the roof with a small ladder and a kind voice and called up to the lost star.\n\n"
-                    "The star, it turned out, had been hiding behind {extras}, feeling shy about shining.\n\n"
-                    "{name} told it that even small lights matter, and that {moral} is true for stars too. The star, blushing silver, returned to the sky, where it has shone happily ever since."
-                ),
-            },
-        ),
-        "middle": (
-            {
-                "title": "{name} Among the Stars",
-                "body": (
-                    "When the rocket's engines hummed, {name} felt the seat press gently against their back, and the sky began to fall away.\n\n"
-                    "Beyond the clouds, a small planet waved hello. On it lived {extras}, who had been waiting for a visitor who asked polite questions.\n\n"
-                    "{name} stayed for tea and listened to the planet sing. Its favorite song was about {moral}, and it offered to teach {name} the chorus.\n\n"
-                    "When the rocket came home, {name} could still hear the song in the wind, like a small bell that never quite stops ringing."
-                ),
-            },
-            {
-                "title": "{name} and the Map of Quiet Places",
-                "body": (
-                    "On the spaceship, the captain kept a special map marked with the quietest places in the galaxy.\n\n"
-                    "{name} had been chosen, this trip, to be the one who visited them. Each stop held a small lesson.\n\n"
-                    "On the second planet, the wind sang about {extras}. On the third, the rocks hummed a song about {moral}.\n\n"
-                    "When {name} returned, the captain asked what {name} had learned. 'That quiet places,' said {name}, 'are not empty. They are full of answers we are in a hurry to miss.'\n\n"
-                    "The captain nodded, and pinned the map to the wall, where the whole crew could see it."
-                ),
-            },
-        ),
-        "older": (
-            {
-                "title": "The Comet {name} Named",
-                "body": (
-                    "Once every hundred years, a small comet swings close enough to be seen from a quiet rooftop in the hills.\n\n"
-                    "{name} had been waiting since the first cold night of autumn, notebook in hand, watching the sky with patient eyes.\n\n"
-                    "When the comet finally appeared, trailing light like a long bright ribbon, {name} whispered a name to it. The comet, as if it had been waiting too, dipped slightly toward the rooftop.\n\n"
-                    "From that night on, astronomers far away would point up and speak of {name}'s comet, a gentle reminder of {moral}.\n\n"
-                    "And on clear nights, if you listened, you could almost hear the wind repeat the name, soft as a secret."
-                ),
-            },
-            {
-                "title": "{name} and the Telescope at the Edge of the Field",
-                "body": (
-                    "It was a small telescope, older than {name}'s grandparents, and it lived in a wooden shed at the edge of a field.\n\n"
-                    "On the clearest night of the year, {name} carried it out, set it down, and looked up.\n\n"
-                    "The sky was not empty. It was full of small stories, each one a star, each star a reminder of {extras} and of the slow, patient rule of {moral}.\n\n"
-                    "{name} stayed for a long time, until the cold became part of the night, and then went inside, leaving the telescope pointing up, just in case the stars wanted to look back."
-                ),
-            },
-        ),
-    },
-    "fantasy": {
-        "young": (
-            {
-                "title": "{name} and the Door That Wasn't There",
-                "body": (
-                    "Behind the bookshelf in the hallway, there was a door that only appeared on rainy afternoons.\n\n"
-                    "{name} opened it and stepped into a garden where flowers hummed and rabbits wore tiny vests.\n\n"
-                    "The garden asked {name} to help find a missing petal, and {name} searched with the help of {extras} until they found it resting on a sleeping snail.\n\n"
-                    "The garden bowed its leaves and shared its favorite rule: {moral}. {name} waved, and the door closed softly behind, waiting for next rain."
-                ),
-            },
-            {
-                "title": "{name} and the Cat Who Could Read",
-                "body": (
-                    "In the corner of the library, a small cat sat reading a very tiny book.\n\n"
-                    "{name} sat down beside it, and the cat, in a polite voice, read a story about {extras}.\n\n"
-                    "When the story ended, the cat yawned and said its favorite rule was {moral}.\n\n"
-                    "{name} agreed, and the two of them chose the next book together, the way friends do."
-                ),
-            },
-        ),
-        "middle": (
-            {
-                "title": "The Map {name} Drew",
-                "body": (
-                    "{name} had always been good at drawing maps of places that did not exist, and one Tuesday, one of them began to be true.\n\n"
-                    "The map showed a forest where the trees had names, and a river that ran both up and down. At the center stood a small castle made entirely of books.\n\n"
-                    "{name} walked the path they had drawn, meeting {extras} who offered riddles and warm bread. Each answer pointed to the next part of the journey.\n\n"
-                    "At the castle, the librarian said the only rule worth keeping was {moral}, and gave {name} a blank page in return.\n\n"
-                    "{name} took the page home and began to draw the next map, smiling."
-                ),
-            },
-            {
-                "title": "{name} and the Well That Sang",
-                "body": (
-                    "At the bottom of the garden, an old stone well had begun to hum, very softly, in the late afternoons.\n\n"
-                    "{name} leaned in and heard, far down, a small voice singing about {extras}.\n\n"
-                    "It wasn't scary, only lonesome, and so {name} dropped a small message into the well, in a waterproof bottle, that said, 'You are not alone.'\n\n"
-                    "The next day, the well sang a new song, this one about {moral}. {name} smiled, and went to find a grown-up to share the news."
-                ),
-            },
-        ),
-        "older": (
-            {
-                "title": "The Spell {name} Didn't Mean to Cast",
-                "body": (
-                    "It started, as it often does, with a word spoken at the wrong moment in the right place.\n\n"
-                    "{name} had been reading in the attic when the old spellbook fell open to a page about gentle things, and a small word slipped out, half-remembered.\n\n"
-                    "The room filled with soft light, and from the page stepped a creature made of paper and ink, who bowed politely and asked to be useful.\n\n"
-                    "Together, they tidied the attic, finding {extras} and a long-lost letter. The creature explained that even small magic follows the rule of {moral}.\n\n"
-                    "When the work was done, the creature stepped back into the page, leaving behind a single feather and the feeling that attics, too, have hearts."
-                ),
-            },
-            {
-                "title": "{name} and the Apprentice Mapmaker",
-                "body": (
-                    "There was a mapmaker in the village who could draw a road that didn't exist yet, and {name} had been chosen to help.\n\n"
-                    "The first map was for a baker who wanted a shortcut to the river. The second was for a child who dreamed of {extras}.\n\n"
-                    "Each map took a whole afternoon, drawn in ink made from tea, and each one ended with the same small note in the corner: {moral}.\n\n"
-                    "By the end of the week, the village had a dozen new paths, and {name} had learned that making a map is mostly a way of listening."
-                ),
-            },
-        ),
-    },
-    "adventure": {
-        "young": (
-            {
-                "title": "{name} and the Big Hill",
-                "body": (
-                    "There was a hill at the end of {name}'s street, and {name} had never climbed all the way to the top.\n\n"
-                    "One bright morning, {name} packed a snack, waved to {extras}, and started up the path.\n\n"
-                    "The hill was bigger than it looked, but {name} took small steps and rested when tired. At the top, a small flag waited, flapping hello.\n\n"
-                    "It said, in friendly letters, {moral}. {name} planted it firmly and ran down to tell everyone."
-                ),
-            },
-            {
-                "title": "{name} and the Bridge of Leaves",
-                "body": (
-                    "A small stream had gotten too wide to jump, and {name} wanted to reach the other side.\n\n"
-                    "With some rope and {extras}, {name} built a small bridge out of leaves and twigs.\n\n"
-                    "It wobbled, but it held, and on the other side, {name} found a tiny garden no one had ever seen.\n\n"
-                    "The garden, in a whisper, said its only rule was {moral}. {name} nodded, and crossed back carefully, already planning to return."
-                ),
-            },
-        ),
-        "middle": (
-            {
-                "title": "{name} and the Forgotten Path",
-                "body": (
-                    "Grandma had told {name} about a path behind the orchard that led to a waterfall no one visited anymore.\n\n"
-                    "{name} found it on a cool afternoon, half-covered in leaves, and followed it carefully. The forest grew quiet and listening.\n\n"
-                    "Along the way, {name} met {extras} who each shared a clue: a feather pointing north, a smooth stone to mark a turn, a song to hum at a fork.\n\n"
-                    "The waterfall was small, but its sound filled the clearing. {name} sat and remembered the rule of every long walk: {moral}.\n\n"
-                    "On the way home, the path seemed a little less forgotten, as if it were glad to be walked again."
-                ),
-            },
-            {
-                "title": "{name} and the Cave of Echoes",
-                "body": (
-                    "On a long hike, {name} found a cave that repeated every word, soft as a sigh.\n\n"
-                    "Inside, {name} spoke carefully, telling the cave about {extras} and asking it to remember.\n\n"
-                    "The cave answered, in many voices, with the same quiet rule: {moral}.\n\n"
-                    "When {name} stepped out into the afternoon, the wind seemed to carry a little of the echo with it, and the hike home felt shorter than it should have."
-                ),
-            },
-        ),
-        "older": (
-            {
-                "title": "The Trail {name} Blazed",
-                "body": (
-                    "The maps in the library said no trail ran between the two valleys, but the old stories said otherwise.\n\n"
-                    "{name} packed light, said goodbye to {extras}, and started into the woods with a notebook, a compass, and a great deal of stubbornness.\n\n"
-                    "The first day was hard. The second was harder. On the third, {name} found the cairn left by someone long ago, and followed its markers to the pass.\n\n"
-                    "Standing between the two valleys, {name} understood what the old trails always tried to teach: {moral}.\n\n"
-                    "On the way down, {name} marked each turn with a small stone, so the next traveler would not have to start from nothing."
-                ),
-            },
-            {
-                "title": "{name} and the Trail of Small Signs",
-                "body": (
-                    "The old guidebook said no trail ran over the mountain, but {name} trusted the small signs.\n\n"
-                    "A red thread tied to a branch. A stack of smooth stones. A single word painted on a rock in friendly letters: onward.\n\n"
-                    "Each sign pointed toward the next, and each one hinted at {extras} and at the patient rule of {moral}.\n\n"
-                    "At the summit, {name} found a small notebook in a tin box, full of names. {name} added one, closed the tin, and started down, leaving the signs for whoever came next."
-                ),
-            },
-        ),
-    },
-    "animals": {
-        "young": (
-            {
-                "title": "{name} and the Brave Little Fox",
-                "body": (
-                    "In the meadow near {name}'s house, there lived a small fox with a bright orange tail.\n\n"
-                    "The fox was shy, but it followed {name} home one afternoon, peeking around the garden gate.\n\n"
-                    "{name} shared a sandwich, and the fox shared a secret: it knew where {extras} liked to play on warm days.\n\n"
-                    "Before it left, the fox whispered a kind truth: {moral}. {name} nodded, and the fox vanished into the long grass with a flick of its tail."
-                ),
-            },
-            {
-                "title": "{name} and the Cat in the Window",
-                "body": (
-                    "On the third floor of the apartment building, a small cat watched the street from a wide window.\n\n"
-                    "{name} waved up at it every morning on the way to school, and the cat, in its careful way, waved back.\n\n"
-                    "One Saturday, {name} was invited up for milk and a story. The cat told a quiet one about {extras} and ended with a small idea: {moral}.\n\n"
-                    "{name} went home humming the story, and the cat returned to its window, content to be both a friend and a watcher."
-                ),
-            },
-        ),
-        "middle": (
-            {
-                "title": "The Animal School {name} Found",
-                "body": (
-                    "Behind the old barn, past the broken fence, there was a clearing where animals held a small school of their own.\n\n"
-                    "{name} discovered it on a quiet morning, and the rabbit teaching arithmetic waved {name} over to join.\n\n"
-                    "The lesson that day was about {extras}, and the importance of listening before speaking. The owl nodded, the mouse took notes, and the fox sharpened a small pencil.\n\n"
-                    "When the bell rang, the rabbit told {name} the school's only rule, which was the same as {moral}.\n\n"
-                    "{name} promised to return, and the clearing seemed to settle a little deeper into its peaceful hum."
-                ),
-            },
-            {
-                "title": "{name} and the Lost Rabbit",
-                "body": (
-                    "On the way home from the park, {name} noticed a small rabbit sitting very still by the fence.\n\n"
-                    "It had no collar and looked unsure of where to go. {name} knelt down, very gently, and asked where it lived.\n\n"
-                    "The rabbit blinked and hopped toward {extras}, and {name} followed, slowly, until they reached a small warren at the edge of the garden.\n\n"
-                    "The mother rabbit thanked {name} in the way rabbits do, which is to thump once, gently. The rule of that small family, it seemed, was {moral}."
-                ),
-            },
-        ),
-        "older": (
-            {
-                "title": "{name} and the Council of the Wood",
-                "body": (
-                    "On the night of the first frost, the animals of the wood hold a council under the old cedar, and this year, they had invited a guest.\n\n"
-                    "{name} arrived wrapped in a warm coat and sat very still as the deer, the badger, and the small, ancient owl spoke of the season ahead.\n\n"
-                    "They talked of {extras}, of food to share, and of the long winter that was beginning to settle over the hills.\n\n"
-                    "At the end, the owl turned to {name} and said, 'We have always taught our young the same thing: {moral}.'\n\n"
-                    "{name} thanked them and walked home through the frost, carrying the council's small, unspoken gift: the sense of being trusted by a place."
-                ),
-            },
-            {
-                "title": "{name} and the Geese at the Reservoir",
-                "body": (
-                    "Each autumn, the geese stopped at the reservoir on their way south, and {name} liked to sit and watch them.\n\n"
-                    "They argued and arranged themselves, called to each other in long, patient sentences, and took turns resting.\n\n"
-                    "One afternoon, a single goose waddled up to {name} and stood nearby, not afraid, only tired. {name} sat still, breathing slowly, the way you do around a wild thing.\n\n"
-                    "After a long while, the goose returned to the flock, and {name} understood, without being told, the rule of {moral}. Some lessons arrive on cold wind, and ask nothing in return."
-                ),
-            },
-        ),
-    },
-    "ocean": {
-        "young": (
-            {
-                "title": "{name} and the Friendly Whale",
-                "body": (
-                    "On the beach where {name} liked to collect shells, a great gray whale came very close to the shore one morning.\n\n"
-                    "It opened one eye, the size of a dinner plate, and looked at {name} with surprising gentleness.\n\n"
-                    "{name} offered a small fish, and the whale sang a low, happy note that made the seagulls pause mid-flight. It pointed with a fin toward {extras} in the tide pools.\n\n"
-                    "Before swimming away, the whale hummed a single idea: {moral}. The waves kept humming it long after it had gone."
-                ),
-            },
-            {
-                "title": "{name} and the Crab Who Shared",
-                "body": (
-                    "In a tide pool near the rocks, a small crab was guarding a single shiny pebble.\n\n"
-                    "{name} sat down beside it, and the crab, after a long pause, offered to share the pebble for just one minute.\n\n"
-                    "It was heavier than it looked, and very smooth. {name} held it carefully, then gave it back.\n\n"
-                    "The crab, pleased, told {name} the rule of the tide pool: {moral}. {name} bowed politely, and the tide came in, as it always does, right on time."
-                ),
-            },
-        ),
-        "middle": (
-            {
-                "title": "The Lighthouse {name} Tended",
-                "body": (
-                    "When the old lighthouse keeper hurt his ankle, {name} offered to tend the light for the week.\n\n"
-                    "Each night, {name} climbed the spiral stairs and watched the beam swing across the dark water, guiding boats home through {extras} and weather.\n\n"
-                    "On the third night, a small voice from the radio said a fishing boat was in trouble. {name} kept the light steady, and the boat found its way back.\n\n"
-                    "The keeper said, when he returned, that the light only really works when the keeper remembers {moral}.\n\n"
-                    "{name} nodded, and from then on, the spiral stairs never felt quite as long."
-                ),
-            },
-            {
-                "title": "{name} and the Sail That Wouldn't Stay Full",
-                "body": (
-                    "On a borrowed boat, {name} and an older cousin tried to catch a clean wind out of the harbor.\n\n"
-                    "The sail flapped, the boom swung, and the wind seemed to be playing a game.\n\n"
-                    "At last, the wind settled, the sail filled, and the boat slipped past the breakwater into open water. {name} felt the salt on their lips and laughed.\n\n"
-                    "The cousin, in a calm voice, said the sea always teaches the same lesson: {moral}. {name} nodded, and held the tiller steady until the sun began its slow slide toward the water."
-                ),
-            },
-        ),
-        "older": (
-            {
-                "title": "{name} and the Map of Tides",
-                "body": (
-                    "In the library at the edge of the harbor, there was a chart older than anyone alive, drawn in ink made of seaweed and quiet patience.\n\n"
-                    "{name} had been studying it for months, learning the names of currents and the moods of the moon.\n\n"
-                    "One morning, the harbor master asked for help guiding a sailboat through {extras}, and {name} read the chart aloud, calm and clear, until the sailboat slipped safely into the bay.\n\n"
-                    "The harbor master said the chart's margin, in faded handwriting, held a single rule: {moral}.\n\n"
-                    "{name} copied the rule into a small notebook and walked home along the seawall, listening to the tide remember it too."
-                ),
-            },
-            {
-                "title": "{name} and the Bell Buoy at Midnight",
-                "body": (
-                    "The harbor had a small bell buoy that rang only when the tide was high and the night was very still.\n\n"
-                    "{name} had wanted to hear it for years, and one August night, finally, did.\n\n"
-                    "Standing on the dock, with the wind cool and {extras} somewhere in the dark, the bell rang twice, and the water answered, softly, from far out.\n\n"
-                    "{name} stood very still and thought about patience, and about {moral}, and about the fact that some sounds wait years for the right kind of listener."
-                ),
-            },
-        ),
-    },
-    "friends": {
-        "young": (
-            {
-                "title": "{name} and the New Friend",
-                "body": (
-                    "On the first day of a new week, a quiet child moved into the house next door to {name}.\n\n"
-                    "{name} brought over a small cup of lemonade and a drawing of {extras}, just to say hello.\n\n"
-                    "The new child smiled, slowly, like a flower opening, and shared a favorite crayon in return.\n\n"
-                    "Before they waved goodbye, the new child said, in a small voice, that {moral} was the best thing to remember when you are new.\n\n"
-                    "{name} agreed, and the two of them began to plan tomorrow."
-                ),
-            },
-            {
-                "title": "{name} and the Treehouse Rule",
-                "body": (
-                    "In the back garden, {name} and a friend built a small treehouse out of blankets and imagination.\n\n"
-                    "They agreed on one rule before they climbed up: that everyone who came inside was safe, and that {extras} were always welcome.\n\n"
-                    "The rule, they decided, was the same as {moral}, just with a roof.\n\n"
-                    "They shared cookies and stories until the streetlights came on, then climbed down carefully, agreeing to build the second room tomorrow."
-                ),
-            },
-        ),
-        "middle": (
-            {
-                "title": "{name} and the Club of Small Wonders",
-                "body": (
-                    "{name} and three friends had started a club whose only rule was to notice small, good things.\n\n"
-                    "On Tuesdays, they met under the big maple and traded observations: a bird building a nest, a librarian's quiet laugh, a perfectly round pebble.\n\n"
-                    "This week, the topic was {extras}, and each friend brought something to show. There were stories, drawings, and a small, folded letter.\n\n"
-                    "The club's secret rule, which everyone knew but no one said out loud, was {moral}.\n\n"
-                    "When the meeting ended, each member carried a little more of the afternoon home with them."
-                ),
-            },
-            {
-                "title": "{name} and the Lemonade Stand",
-                "body": (
-                    "On a long, hot Saturday, {name} and two friends set up a small lemonade stand at the end of the driveway.\n\n"
-                    "The first customer was the mail carrier. The second was a tired dog, who got water instead. The third was a neighbor who told a long, kind story about {extras}.\n\n"
-                    "By the end of the afternoon, the stand had made enough for ice cream, and the friends had made enough for a long memory.\n\n"
-                    "They closed up, sharing the ice cream on the porch, and agreed that {moral} was the best part of the day."
-                ),
-            },
-        ),
-        "older": (
-            {
-                "title": "{name} and the Long Letter",
-                "body": (
-                    "When {name}'s best friend moved across the country, they decided to write letters the old way, on paper, with pens that needed dipping.\n\n"
-                    "The first letters were easy, full of news and small jokes about {extras}. The later ones grew longer, slower, more honest.\n\n"
-                    "In one letter, the friend wrote that distance is not the same as absence, and that {moral} is what keeps a friendship warm across any number of miles.\n\n"
-                    "{name} read it twice, then sat down to write back, the kettle on, the cat asleep, the room full of the particular quiet of two people thinking of each other.\n\n"
-                    "Some letters, it turns out, are small rooms where friends can sit together, no matter how far."
-                ),
-            },
-            {
-                "title": "{name} and the Notebook We Share",
-                "body": (
-                    "On the first day of the new school year, {name} and a friend agreed to share a small notebook, passing it back and forth between classes.\n\n"
-                    "Each wrote a little — a question, a sketch, a small observation about {extras}, a quiet worry.\n\n"
-                    "By the end of the term, the notebook was full, and so were the two friends, in a way that had very little to do with the lessons in class.\n\n"
-                    "They agreed that the notebook's only rule, the one that mattered most, was {moral}, and that some friendships, like some books, are better when they're written in more than one handwriting."
-                ),
-            },
-        ),
-    },
-}

modal_app.py

@@ -0,0 +1,337 @@
+"""Fabella inference servers on Modal.
+
+Three independent web_servers in one app, each on its own A10G:
+
+  serve_drafter (port 8000) — Gemma 4 E4B-IT (4B). Generates explanations.
+  serve_judge   (port 8001) — Nemotron-3 Nano 4B. Scores the draft against
+                                the request and returns a structured verdict.
+  serve_tts     (port 8002) — VoxCPM2. Synthesizes read-aloud WAV audio.
+
+The judge runs after the drafter; if the verdict is "revise", the
+drafter is re-invoked. This is the cheapest way to get model-driven
+quality control without a parallel-multi-agent setup.
+
+All models live on the same Modal Volume (fabella-models) with distinct
+sub-directories so we only pay for one download per model.
+"""
+
+import os
+import subprocess
+from pathlib import Path
+
+import modal
+
+app = modal.App("fabella")
+
+model_volume = modal.Volume.from_name("fabella-models", create_if_missing=True)
+vllm_cache_volume = modal.Volume.from_name("fabella-vllm-cache", create_if_missing=True)
+
+MODEL_PATH = "/models"
+
+DRAFTER_REPO = "google/gemma-4-E4B-it"
+DRAFTER_DIR = "gemma-4-E4B-it"
+DRAFTER_SERVED_NAME = "gemma-4"
+DRAFTER_PORT = 8000
+
+JUDGE_REPO = "nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16"
+JUDGE_DIR = "NVIDIA-Nemotron-3-Nano-4B-BF16"
+JUDGE_SERVED_NAME = "nemotron-3-4b"
+JUDGE_PORT = 8001
+
+TTS_REPO = "openbmb/VoxCPM2"
+TTS_DIR = "VoxCPM2"
+TTS_PORT = 8002
+
+# --- Images ---------------------------------------------------------------
+
+download_image = (
+    modal.Image.debian_slim(python_version="3.11")
+    .pip_install("huggingface_hub[hf_xet]>=0.24")
+    .env({"HF_HUB_CACHE": MODEL_PATH})
+)
+
+vllm_image = (
+    modal.Image.from_registry("nvidia/cuda:12.9.0-devel-ubuntu22.04", add_python="3.11")
+    .entrypoint([])
+    .pip_install("vllm>=0.22", "huggingface_hub[hf_xet]>=0.24")
+    .env({"HF_HUB_CACHE": MODEL_PATH})
+)
+
+# VoxCPM2 is a tokenizer-free diffusion-autoregressive TTS model (MiniCPM-4
+# backbone + AudioVAE V2). It's served by the official `voxcpm` Python
+# library, NOT vLLM. The image is therefore a separate CUDA image with
+# torch + voxcpm installed and a tiny FastAPI wrapper that calls
+# VoxCPM.from_pretrained(...).generate(...) and returns audio/wav bytes.
+tts_image = (
+    modal.Image.from_registry("nvidia/cuda:12.9.0-devel-ubuntu22.04", add_python="3.11")
+    .entrypoint([])
+    .pip_install(
+        # VoxCPM2 + its torch/torchaudio deps. We pin a major range
+        # compatible with the README's "torch>=2.5.0, CUDA>=12.0" claim.
+        "voxcpm>=1.0",
+        "torch>=2.5.0",
+        "torchaudio>=2.5.0",
+        "soundfile",
+        "fastapi>=0.110",
+        "uvicorn[standard]>=0.27",
+    )
+    .env({"HF_HUB_CACHE": MODEL_PATH})
+)
+
+
+# --- Model download (one entry per model) --------------------------------
+
+
+@app.function(image=download_image, volumes={MODEL_PATH: model_volume}, timeout=60 * 60)
+def download_drafter(force: bool = False):
+    """Pull Gemma 4 E4B-IT weights to the Volume (run once)."""
+    from huggingface_hub import snapshot_download
+    target = Path(MODEL_PATH) / DRAFTER_DIR
+    if target.exists() and any(target.iterdir()) and not force:
+        print(f"Drafter model already at {target}; skipping")
+        return
+    print(f"Downloading {DRAFTER_REPO} to {target}...")
+    snapshot_download(
+        repo_id=DRAFTER_REPO,
+        local_dir=str(target),
+        allow_patterns=[
+            "config.json", "generation_config.json", "chat_template.jinja",
+            "tokenizer.json", "tokenizer_config.json",
+            "preprocessor_config.json", "processor_config.json",
+            "model*.safetensors", "*.py",
+        ],
+    )
+    model_volume.commit()
+    print("Drafter download complete")
+
+
+@app.function(image=download_image, volumes={MODEL_PATH: model_volume}, timeout=60 * 60)
+def download_judge(force: bool = False):
+    """Pull Nemotron-Nano-9B-v2 weights to the Volume (run once)."""
+    from huggingface_hub import snapshot_download
+    target = Path(MODEL_PATH) / JUDGE_DIR
+    if target.exists() and any(target.iterdir()) and not force:
+        print(f"Judge model already at {target}; skipping")
+        return
+    print(f"Downloading {JUDGE_REPO} to {target}...")
+    snapshot_download(
+        repo_id=JUDGE_REPO,
+        local_dir=str(target),
+        allow_patterns=[
+            "config.json", "generation_config.json", "chat_template.jinja",
+            "tokenizer.json", "tokenizer_config.json",
+            "preprocessor_config.json", "processor_config.json",
+            "model*.safetensors", "*.py",
+        ],
+    )
+    model_volume.commit()
+    print("Judge download complete")
+
+
+# --- vLLM servers --------------------------------------------------------
+
+MINUTES = 60
+
+
+def _vllm_cmd(model_dir: Path, served_name: str, port: int, extra: list[str]) -> list[str]:
+    return [
+        "vllm", "serve",
+        str(model_dir),
+        "--host", "0.0.0.0",
+        "--port", str(port),
+        "--served-model-name", served_name,
+        "--uvicorn-log-level", "info",
+        "--max-model-len", "8192",
+        "--gpu-memory-utilization", "0.90",
+        *extra,
+    ]
+
+
+@app.function(
+    image=vllm_image,
+    gpu="A10G",
+    scaledown_window=10 * MINUTES,
+    timeout=10 * MINUTES,
+    volumes={MODEL_PATH: model_volume, "/root/.cache/vllm": vllm_cache_volume},
+)
+@modal.concurrent(max_inputs=10)
+@modal.web_server(port=DRAFTER_PORT, startup_timeout=10 * MINUTES)
+def serve_drafter():
+    """Gemma 4 E4B-IT — the story drafter.
+
+    Tool-calling is native via vLLM's gemma4 parser (the model's chat
+    template uses <|tool_call|>...<tool_call|> markers).
+    """
+    model_dir = Path(MODEL_PATH) / DRAFTER_DIR
+    cmd = _vllm_cmd(model_dir, DRAFTER_SERVED_NAME, DRAFTER_PORT, extra=[
+        "--language-model-only",          # skip multimodal processor
+        "--enable-auto-tool-choice",
+        "--tool-call-parser", "gemma4",
+    ])
+    print(f"Starting drafter vLLM: {' '.join(cmd)}", flush=True)
+    subprocess.Popen(cmd)
+
+
+@app.function(
+    image=vllm_image,
+    gpu="A10G",
+    scaledown_window=10 * MINUTES,
+    timeout=10 * MINUTES,
+    volumes={MODEL_PATH: model_volume, "/root/.cache/vllm": vllm_cache_volume},
+)
+@modal.concurrent(max_inputs=10)
+@modal.web_server(port=JUDGE_PORT, startup_timeout=10 * MINUTES)
+def serve_judge():
+    """Nemotron-3-Nano-4B-BF16 — the multi-criteria story judge.
+
+    No tool-calling flags on the server side: the judge prompt in
+    llm.py asks for plain JSON in `content` and the client parses it.
+    This dodges the chat-template tool-dialect dance entirely.
+    """
+    model_dir = Path(MODEL_PATH) / JUDGE_DIR
+    cmd = _vllm_cmd(model_dir, JUDGE_SERVED_NAME, JUDGE_PORT, extra=[])
+    print(f"Starting judge vLLM: {' '.join(cmd)}", flush=True)
+    subprocess.Popen(cmd)
+
+
+# --- VoxCPM2 TTS ----------------------------------------------------------
+
+TTS_SERVER_PY = '''
+"""VoxCPM2 TTS server for Fabella.
+
+Wraps the official `voxcpm` library in a tiny FastAPI app that exposes
+POST /synthesize. Accepts JSON {text, voice_description, cfg_value,
+inference_timesteps} and returns audio/wav bytes. The model is loaded
+once on import (Modal keeps the container warm while traffic is hot).
+"""
+
+import io
+import os
+import sys
+import traceback
+
+# Pin HF cache before voxcpm / torch import so model weights land in
+# the shared Modal Volume, not the container overlay.
+os.environ.setdefault("HF_HUB_CACHE", "/models")
+MODEL_DIR = "/models/VoxCPM2"
+
+import numpy as np
+import soundfile as sf
+from fastapi import FastAPI, HTTPException, Response
+
+
+print("[tts] importing voxcpm", flush=True)
+try:
+    from voxcpm import VoxCPM
+except Exception as e:
+    print(f"[tts] voxcpm import failed: {type(e).__name__}: {e}", flush=True)
+    raise
+
+print(f"[tts] loading VoxCPM2 from {MODEL_DIR}", flush=True)
+_model = VoxCPM.from_pretrained(MODEL_DIR, load_denoiser=False)
+print(f"[tts] loaded; sample_rate = {_model.tts_model.sample_rate}", flush=True)
+
+app = FastAPI()
+
+
+@app.get("/health")
+async def health():
+    return {"status": "ok", "sample_rate": int(_model.tts_model.sample_rate)}
+
+
+@app.post("/synthesize")
+async def synthesize(payload: dict):
+    text = (payload.get("text") or "").strip()
+    if not text:
+        raise HTTPException(status_code=400, detail="text is required")
+    voice_description = (payload.get("voice_description") or "").strip() or None
+    cfg_value = float(payload.get("cfg_value") or 2.0)
+    inference_timesteps = int(payload.get("inference_timesteps") or 10)
+    normalize = bool(payload.get("normalize", True))
+    denoise = bool(payload.get("denoise", True))
+
+    # VoxCPM2 voice-design convention: put the description in parens at
+    # the start of `text` when no reference audio is provided.
+    if voice_description and not payload.get("reference_wav_path"):
+        text = f"({voice_description}){text}"
+
+    try:
+        wav = _model.generate(
+            text=text,
+            cfg_value=cfg_value,
+            inference_timesteps=inference_timesteps,
+            normalize=normalize,
+            denoise=denoise,
+            prompt_wav_path=payload.get("prompt_wav_path") or None,
+            prompt_text=payload.get("prompt_text") or None,
+            reference_wav_path=payload.get("reference_wav_path") or None,
+        )
+    except Exception as e:
+        print(f"[tts] generate failed: {type(e).__name__}: {e}", flush=True)
+        traceback.print_exc()
+        raise HTTPException(status_code=500, detail=f"generate failed: {e}")
+
+    # wav is a 1-D numpy array at model.tts_model.sample_rate
+    sr = int(_model.tts_model.sample_rate)
+    buf = io.BytesIO()
+    sf.write(buf, np.asarray(wav, dtype=np.float32), sr, format="WAV", subtype="PCM_16")
+    return Response(content=buf.getvalue(), media_type="audio/wav")
+'''
+
+
+@app.function(image=download_image, volumes={MODEL_PATH: model_volume}, timeout=60 * 60)
+def download_tts(force: bool = False):
+    """Pull VoxCPM2 weights to the Volume (run once)."""
+    from huggingface_hub import snapshot_download
+    target = Path(MODEL_PATH) / TTS_DIR
+    if target.exists() and any(target.iterdir()) and not force:
+        print(f"TTS model already at {target}; skipping")
+        return
+    print(f"Downloading {TTS_REPO} to {target}...")
+    snapshot_download(
+        repo_id=TTS_REPO,
+        local_dir=str(target),
+        allow_patterns=[
+            "config.json", "configuration_*.py", "modeling_*.py",
+            "generation_config.json", "chat_template.jinja",
+            "tokenizer.json", "tokenizer_config.json",
+            "preprocessor_config.json", "processor_config.json",
+            "audio_vae_config.json", "audiovae_*", "audiovae.pth", "audiovae.safetensors",
+            "model*.safetensors", "*.py",
+            "*.json",
+        ],
+    )
+    model_volume.commit()
+    print("TTS download complete")
+
+
+@app.function(
+    image=tts_image,
+    gpu="A10G",
+    scaledown_window=10 * MINUTES,
+    timeout=10 * MINUTES,
+    volumes={MODEL_PATH: model_volume},
+)
+@modal.concurrent(max_inputs=10)
+@modal.web_server(port=TTS_PORT, startup_timeout=10 * MINUTES)
+def serve_tts():
+    """VoxCPM2 — read-aloud narration for Fabella explanations.
+
+    Wrapped in a small FastAPI app. The drafter's text is sent to
+    `/synthesize` and the result is a `audio/wav` blob. The HF Space
+    frontend renders the audio inline via a standard `<audio>` element.
+    """
+    # Write the FastAPI server source into the container and run it.
+    server_path = "/root/voxcpm_server.py"
+    with open(server_path, "w") as f:
+        f.write(TTS_SERVER_PY)
+    print(f"[tts] wrote server to {server_path}", flush=True)
+    cmd = [
+        "uvicorn", "voxcpm_server:app",
+        "--app-dir", "/root",
+        "--host", "0.0.0.0",
+        "--port", str(TTS_PORT),
+        "--log-level", "info",
+    ]
+    print(f"Starting TTS: {' '.join(cmd)}", flush=True)
+    subprocess.Popen(cmd)

modal_app_gemma.py

@@ -0,0 +1,109 @@
+"""Fabella vLLM server on Modal.
+
+Serves gemma-4-E4B-it via OpenAI-compatible API.
+Model weights cached in Modal Volume for fast cold starts.
+"""
+
+import os
+import subprocess
+from pathlib import Path
+
+import modal
+
+# --- App & volumes ---
+app = modal.App("fabella")
+
+model_volume = modal.Volume.from_name("fabella-models", create_if_missing=True)
+vllm_cache_volume = modal.Volume.from_name("fabella-vllm-cache", create_if_missing=True)
+
+MODEL_PATH = "/models"
+MODEL_NAME = "google/gemma-4-E4B-it"
+VLLM_PORT = 8000
+
+# --- Images ---
+download_image = (
+    modal.Image.debian_slim(python_version="3.11")
+    .pip_install("huggingface_hub[hf_xet]>=0.24")
+    .env({"HF_HUB_CACHE": MODEL_PATH})
+)
+
+vllm_image = (
+    modal.Image.from_registry("nvidia/cuda:12.9.0-devel-ubuntu22.04", add_python="3.11")
+    .entrypoint([])
+    .pip_install("vllm>=0.22", "huggingface_hub[hf_xet]>=0.24")
+    .env({"HF_HUB_CACHE": MODEL_PATH})
+)
+
+
+# --- Model download ---
+@app.function(
+    image=download_image,
+    volumes={MODEL_PATH: model_volume},
+    timeout=60 * 60,
+)
+def download_model(force: bool = False):
+    """Download gemma-4-E4B-it to the Modal Volume. Run once."""
+    from huggingface_hub import snapshot_download
+
+    target = Path(MODEL_PATH) / "gemma-4-E4B-it"
+    if target.exists() and any(target.iterdir()) and not force:
+        print(f"Model already exists at {target}, skipping download")
+        print("Run with --force to re-download")
+        return
+
+    print(f"Downloading {MODEL_NAME} to {target}...")
+    snapshot_download(
+        repo_id=MODEL_NAME,
+        local_dir=str(target),
+        allow_patterns=[
+            "config.json",
+            "generation_config.json",
+            "chat_template.jinja",
+            "tokenizer.json",
+            "tokenizer_config.json",
+            "preprocessor_config.json",
+            "processor_config.json",
+            "model*.safetensors",
+            "*.py",
+        ],
+    )
+    model_volume.commit()
+    print("Download complete")
+
+
+# --- vLLM server ---
+MINUTES = 60
+
+
+@app.function(
+    image=vllm_image,
+    gpu="A10G",
+    scaledown_window=10 * MINUTES,
+    timeout=10 * MINUTES,
+    volumes={
+        MODEL_PATH: model_volume,
+        "/root/.cache/vllm": vllm_cache_volume,
+    },
+)
+@modal.concurrent(max_inputs=10)
+@modal.web_server(port=VLLM_PORT, startup_timeout=10 * MINUTES)
+def serve():
+    """vLLM OpenAI-compatible server for gemma-4-E4B-it."""
+    model_dir = Path(MODEL_PATH) / "gemma-4-E4B-it"
+
+    cmd = [
+        "vllm", "serve",
+        str(model_dir),
+        "--host", "0.0.0.0",
+        "--port", str(VLLM_PORT),
+        "--served-model-name", "gemma-4",
+        "--uvicorn-log-level", "info",
+        "--max-model-len", "8192",
+        "--gpu-memory-utilization", "0.90",
+        "--language-model-only",
+        "--enable-auto-tool-choice",
+        "--tool-call-parser", "gemma4",
+    ]
+
+    print(f"Starting vLLM: {' '.join(cmd)}", flush=True)
+    subprocess.Popen(cmd)

prompts.py

@@ -1,49 +0,0 @@
-"""Prompt builders for the real model path."""
-
-import os
-import sys
-
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-
-from safety import age_bucket, length_to_words
-
-
-def system_prompt() -> str:
-    return (
-        "You are Fabella, a gentle storyteller for children aged 6 to 10. "
-        "You write warm, magical, age-appropriate short stories. "
-        "Never include scary content for children under 8. "
-        "Never mention real public figures by name. "
-        "Never include violence beyond gentle peril. "
-        "Never include romantic content. "
-        "Always end with a clear resolution that reflects the moral lesson. "
-        "Always begin your response with a line in the exact format: Title: <the story title> "
-        "Then a blank line, then the story body. "
-        "Do not include any other text, labels, or commentary."
-    )
-
-
-def user_prompt(name: str, age: int, themes: list[str], moral: str, length: str) -> str:
-    bucket = age_bucket(age)
-    min_w, max_w = length_to_words(length)
-    themes_str = ", ".join(themes) if themes else "everyday adventures"
-    moral_str = moral or "being kind to others"
-
-    vocab = {
-        "young": "Use very simple sentences. Use short paragraphs. Keep language concrete and warm.",
-        "middle": "Use clear sentences with some descriptive language. Paragraphs of 3 to 5 sentences.",
-        "older": "Use richer vocabulary and longer paragraphs. Keep the tone gentle and kind.",
-    }[bucket]
-
-    return (
-        f"Write a personalized children's story.\n"
-        f"Child's name: {name}\n"
-        f"Age: {age}\n"
-        f"Favorite themes: {themes_str}\n"
-        f"Moral lesson: {moral_str}\n"
-        f"Story length: about {min_w} to {max_w} words.\n"
-        f"{vocab}\n"
-        f"The child's name must appear at least once. "
-        f"Each favorite theme must appear at least once. "
-        f"The moral must be clearly resolved in the ending."
-    )

real.py

@@ -1,85 +0,0 @@
-"""Real model path. Wired with @spaces.GPU; polish deferred to Phase 2."""
-
-import os
-import sys
-
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-
-from prompts import system_prompt, user_prompt
-from schema import StoryRequest
-
-MODEL_ID = os.environ.get("FABELLA_MODEL_ID", "google/gemma-4-E4B-it")
-
-_run_gpu = None  # lazily wrapped by spaces.GPU on first real call
-
-
-def _parse_title_and_body(text: str) -> tuple[str, str]:
-    text = (text or "").strip()
-    if not text:
-        return "A Small Story", ""
-    lines = text.splitlines()
-    title = "A Small Story"
-    body_lines = list(lines)
-    for i, line in enumerate(lines):
-        stripped = line.strip()
-        if stripped.lower().startswith("title:"):
-            title = stripped.split(":", 1)[1].strip() or title
-            body_lines = lines[i + 1:]
-            break
-    body = "\n".join(body_lines).strip()
-    return (title, body) if body else (title, text)
-
-
-def _run_with_spaces_gpu(req: StoryRequest) -> tuple[str, str]:
-    import torch
-    from transformers import AutoModelForCausalLM, AutoProcessor
-
-    processor = AutoProcessor.from_pretrained(MODEL_ID)
-    model = AutoModelForCausalLM.from_pretrained(
-        MODEL_ID,
-        torch_dtype=torch.bfloat16,
-        device_map="cuda",
-    )
-
-    messages = [
-        {"role": "system", "content": system_prompt()},
-        {"role": "user", "content": user_prompt(req.name, req.age, req.themes, req.moral, req.length)},
-    ]
-    text = processor.apply_chat_template(
-        messages,
-        tokenize=False,
-        add_generation_prompt=True,
-        enable_thinking=False,
-    )
-    inputs = processor(text=text, return_tensors="pt").to(model.device)
-    input_len = inputs["input_ids"].shape[-1]
-
-    with torch.no_grad():
-        output = model.generate(
-            **inputs,
-            max_new_tokens=900,
-            temperature=1.0,
-            top_p=0.95,
-            top_k=64,
-            do_sample=True,
-        )
-    raw = processor.decode(output[0][input_len:], skip_special_tokens=True)
-    return _parse_title_and_body(raw)
-
-
-def _get_run_gpu():
-    """Wrap _run_with_spaces_gpu with @spaces.GPU(duration=60) on first call."""
-    global _run_gpu
-    if _run_gpu is None:
-        import spaces
-
-        _run_gpu = spaces.GPU(duration=60)(_run_with_spaces_gpu)
-    return _run_gpu
-
-
-def generate_real(req: StoryRequest) -> tuple[str, str]:
-    """Real-model call. Best-effort; surfaces a user-visible message on any failure."""
-    try:
-        return _get_run_gpu()(req)
-    except Exception as e:
-        return "Fabella (real model error)", f"_Real model call failed: {e}._"

requirements.txt

@@ -1,5 +1,5 @@
 gradio>=4.0,<7.0
-spaces>=0.18.0
-transformers>=4.40.0
-torch>=2.0.0
-accelerate>=0.27.0
+langchain>=1.0
+langchain-core>=1.0
+langchain-openai>=0.3
+openai>=1.76

safety.py

@@ -3,9 +3,8 @@
 import re
 
 MAX_NAME_LEN = 30
-MAX_THEMES = 3
-MAX_THEME_LEN = 20
-MAX_MORAL_LEN = 120
+MAX_SITUATION_LEN = 600     # a few sentences of context from the parent
+MAX_MORAL_LEN = 120          # kept for any lingering legacy call sites
 
 CONTROL_CHARS = re.compile(r"[\x00-\x1f\x7f]")
 PROFANITY = {
@@ -27,30 +26,13 @@ def sanitize_name(raw: str) -> str:
     return clean_text(raw, MAX_NAME_LEN)
 
 
-def sanitize_themes(raw) -> list[str]:
-    if not raw:
-        return []
-    if isinstance(raw, str):
-        items = [raw]
-    else:
-        items = list(raw)
-    out = []
-    seen = set()
-    for t in items:
-        t = clean_text(str(t), MAX_THEME_LEN)
-        if not t:
-            continue
-        key = t.lower()
-        if key in seen:
-            continue
-        seen.add(key)
-        out.append(t)
-        if len(out) >= MAX_THEMES:
-            break
-    return out
+def sanitize_situation(raw: str) -> str:
+    """The freeform situation the parent describes."""
+    return clean_text(raw, MAX_SITUATION_LEN)
 
 
 def sanitize_moral(raw: str) -> str:
+    """Kept for legacy call sites. No longer used in the new explainer."""
     return clean_text(raw, MAX_MORAL_LEN)
 
 
@@ -71,9 +53,26 @@ def age_bucket(age: int) -> str:
 
 
 def length_to_words(length: str) -> tuple[int, int]:
-    """Return (min_words, max_words) for a length label."""
+    """Return (min_words, max_words) for a length label.
+
+    Kept for legacy call sites. The new explainer uses its own
+    `explain_to_words()` mapping by tone.
+    """
     return {
         "short": (120, 220),
         "medium": (280, 420),
         "long": (500, 800),
     }.get(length, (280, 420))
+
+
+def explain_to_words(tone: str) -> tuple[int, int]:
+    """Target word count (min, max) for the explanation body, by tone.
+
+    Explanations are deliberately short — 60-160 words depending on
+    tone. Parents skim these before reading aloud; long is a bug.
+    """
+    return {
+        "gentle": (60, 110),
+        "matter-of-fact": (70, 130),
+        "playful": (50, 100),
+    }.get(tone, (60, 110))

schema.py

@@ -1,13 +1,88 @@
-"""Typed inputs for Fabella story generation."""
+"""Typed inputs and outputs for Fabella — the small-words-for-big-questions tool."""
 
 from dataclasses import dataclass
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
 
 
 @dataclass
-class StoryRequest:
-    name: str
+class ExplainRequest:
+    """What a parent tells Fabella to explain to their child.
+
+    Attributes:
+        situation: A 1-3 sentence freeform description of the situation the
+            parent needs help explaining ("We're moving to a new house in
+            3 weeks", "Why is grandma in the hospital?").
+        age: The child's age in years (5-12 range supported).
+        child_name: Optional name. If set, the explanation addresses the
+            child directly. If empty, the parent is addressed ("your child").
+        tone: "gentle" | "matter-of-fact" | "playful". Controls the
+            register of the explanation.
+        seed: Determinism for the drafter (the judge is temperature=0).
+    """
+
+    situation: str
     age: int
-    themes: list[str]
-    moral: str
-    length: str
+    child_name: str = ""
+    tone: str = "gentle"
     seed: int = 0
+
+
+# --- Judge output ---------------------------------------------------------
+
+
+Verdict = Literal["approve", "revise"]
+
+
+class JudgeVerdict(BaseModel):
+    """Structured output of the small Nemotron judge.
+
+    The judge receives a draft explanation and a 6-criterion rubric, and
+    returns one of these. Validated by Pydantic so that any deviation
+    from the schema is caught immediately.
+    """
+
+    ok: bool = Field(
+        description="True iff the draft is good enough to ship as-is."
+    )
+    issues: list[str] = Field(
+        default_factory=list,
+        description="Concrete, actionable problems with the draft. Empty if ok=true.",
+    )
+    score: float = Field(
+        ge=0.0,
+        le=1.0,
+        description="0..1 quality score. >=0.8 is generally approve-worthy.",
+    )
+    verdict: Verdict = Field(
+        description='"approve" if the draft is ready, "revise" if the drafter should rewrite.'
+    )
+    reasoning: str = Field(
+        default="",
+        description="One short sentence explaining the verdict.",
+    )
+
+    @field_validator("issues")
+    @classmethod
+    def _issues_short(cls, v: list[str]) -> list[str]:
+        # Strip and bound each issue to 200 chars so a runaway model can't
+        # blow up the drafter's context window.
+        return [str(i).strip()[:200] for i in v if str(i).strip()]
+
+    @field_validator("reasoning")
+    @classmethod
+    def _reasoning_short(cls, v: str) -> str:
+        return (v or "").strip()[:300]
+
+
+class JudgeFailed(Exception):
+    """Raised when the judge output cannot be parsed after a retry.
+
+    The caller (the validate_explanation tool) should fall back to the
+    rule-based check.
+    """
+
+    def __init__(self, message: str, last_text: str = ""):
+        super().__init__(message)
+        self.last_text = last_text