| # StoryCode — Handoff for the executing agent (Codex) |
|
|
| Full design rationale: `~/.claude/plans/so-uh-this-is-modular-curry.md`. |
| This file is the **do-this-next checklist**. Deadline: **2026-06-15**. |
|
|
| Read `AGENTS.md` first — it has the rules you must not break. |
|
|
| ## What's already built & verified ✅ |
|
|
| The whole app is written, and the **deterministic core is tested green** |
| (`python tests/test_analyzer.py` → 10/10, no GPU). The Gradio UI builds and every |
| panel renders. The only thing not yet exercised is the live model — because it |
| needs the Modal endpoint. |
|
|
| | File | State | |
| |---|---| |
| | `config.py`, `schema.py`, `ingest.py` (+ secret scan) | ✅ done & tested | |
| | `analyzer/` (`python_ast`, `js_treesitter`, `generic`, `graph`, `deps`, `__init__`) | ✅ done & tested — **the source of truth** | |
| | `diagram.py`, `story.py`, `narrate.py`, `db.py` | ✅ done; narration verified via the model-free fallback | |
| | `llm.py` | ✅ written; needs the live Modal endpoint to exercise the real path | |
| | `ui/theme.py`, `ui/styles.css`, `app.py` | ✅ written; UI builds. Needs a live `python app.py` run | |
| | `modal_app.py` (vLLM serving MiniCPM4.1-8B) | ✅ written; **you must deploy + version-pin it** | |
| | `zerogpu_backend.py` | ✅ break-glass fallback | |
| | `scripts/sample_project/`, `tests/test_analyzer.py` | ✅ done; tests pass | |
| | `README.md` (HF frontmatter+tags), `.env.example`, `requirements.txt` | ✅ done | |
|
|
| ## Do these in order |
|
|
| 1. **Deploy the GPU backend.** |
| - In `modal_app.py`: confirm `VLLM_VERSION` against the **MiniCPM4.1-8B model |
| card** (it uses custom code → `--trust-remote-code`). Set a real shared secret: |
| `modal secret create storycode-api MODAL_API_KEY=<secret>`, then |
| `modal token new` and `modal deploy modal_app.py`. |
| - Smoke-test the endpoint: |
| `curl -H "Authorization: Bearer <secret>" <url>/v1/chat/completions -d '{"model":"openbmb/MiniCPM4.1-8B","messages":[{"role":"user","content":"Reply with JSON {\"ok\":true}"}]}'` |
| - **Risk:** MiniCPM4.1 is a *hybrid-reasoning* model. If it emits long `<think>` |
| chains or ignores `guided_json`, (a) check the model card for the flag that |
| disables thinking and add it to the vLLM args, and (b) confirm the installed |
| vLLM version supports `xgrammar` guided decoding. The contract `llm.py` |
| expects is a plain OpenAI `/v1/chat/completions` that honours |
| `extra_body={"guided_json": ...}`. |
| |
| 2. **Wire secrets.** Copy `.env.example` → `.env` locally; on the Space set |
| `MODAL_ENDPOINT_URL` (= `<url>/v1`) and `MODAL_API_KEY` (same shared secret). |
|
|
| 3. **Run locally.** `pip install -r requirements.txt && python app.py`. |
| Click **"Try the sample project"** → you should get a Story + Plain-English |
| panel + a rendered Architecture Map + the Safe-to-Edit list + Dependencies. |
| Switch styles/difficulty → the Story re-narrates (no re-analysis). |
|
|
| 4. **Tune the narration prompts** in `story.py` (and only `story.py`) until the |
| output is accurate AND in-voice for each of the 5 styles × 3 difficulties. |
| This is the main creative loop and your clearest Codex-attributed work. Keep |
| the grounding rule intact (the model narrates facts; it never invents files). |
| Re-run `python tests/test_analyzer.py` after — it must stay 10/10. |
|
|
| 5. **Real-user proof (Backyard AI requirement).** Run the friend's actual |
| Claude-generated app through StoryCode. Capture: a quote from them, before/after |
| screenshots, and the story it produced. Put these in the README. |
|
|
| 6. **Deploy + submission assets.** |
| - Create a Gradio Space under `build-small-hackathon`; push this repo; set the |
| two secrets. Verify it reaches Modal (check Modal logs). **Test on mobile.** |
| - Record a 60–90s demo video (upload → Story → Map → Safe-to-Edit); link in README. |
| - Push to a public GitHub repo with **Codex-attributed commits**; link it in |
| the README (OpenAI Codex prize requirement). |
| - Post once on social; link it. Confirm README frontmatter tags are present. |
| |
| ## Post-MVP queue — only after steps 1–6 are deployed. One at a time. |
|
|
| In priority order (each is a clean, bounded task; details in the plan file): |
| 1. **Grounded chat Q&A** — "Ask anything about your code", answered from the |
| ProjectModel + summaries already in `gr.State` (no new analysis). |
| 2. **"How do I change X?"** assistant → "file X, line Y, change Z to W." |
| 3. **Error detective** — paste an error + file → detective-story fix. |
| 4. **Dependency panel polish** — surface `analyzer/deps.py` risk flags more loudly. |
| 5. **Save / revisit + Share** (wire `db.py` into the UI). |
| 6. **Export story as PDF / Markdown.** |
| 7. **GitHub URL ingestion** (add a `from_github` path to `ingest.py`). |
| 8. **Before/after edit preview.** |
|
|
| ## Gotchas |
| - **Don't** add `torch`/`vllm`/`transformers` to `requirements.txt` — the GPU is on |
| Modal; the Space is a CPU container. (Those belong only in `modal_app.py`, or in |
| the Space *only* if you switch to the ZeroGPU fallback.) |
| - Keep the UI custom (`ui/styles.css`) — Off-Brand badge + explicit requirement. |
| - **Don't claim Tiny Titan** — MiniCPM4.1-8B is ~8B, not ≤4B. |
| - The static analysis is the source of truth. Never let the model override the |
| Architecture Map or the Safe-to-Edit verdicts. If you change `analyzer/`, update |
| `tests/test_analyzer.py` to match and keep it green. |
|
|
