CODEX_PROMPT.md

# Codex kickoff prompt — paste this into Codex

You are working in the **StoryCode** repository (a Gradio app for the Build Small
hackathon). The architecture and all the hard, deterministic code are already
written and tested. Your job is to **deploy the model on Modal, wire it up, test
the whole app end-to-end, tune the narration, and ship it** — without breaking the
rules. Work through the steps in order. Do not skip ahead.

## 0. Read first (do not skip)
- `HANDOFF.md` — the authoritative do-this-next checklist.
- `AGENTS.md` — the hard rules. The most important one: **static analysis is the
  source of truth; the model only narrates it.** Never let the model invent files,
  edges, or safe-to-edit verdicts, and never override `analyzer/` output.
- `README.md` — what the app is and how it's meant to work.

Then confirm the baseline works with **no GPU**:
```
python -m pip install -r requirements.txt
python tests/test_analyzer.py        # must print "10/10 passed"
python app.py                        # open it, click "Try the sample project"
```
With no model endpoint set, the app uses a truthful model-free fallback story —
the Story/Map/Safe-to-Edit/Dependencies tabs must all render. If anything errors,
fix that before touching Modal.

## 1. Deploy MiniCPM4.1-8B on Modal (this is the "download + use the model" step)
The model is **downloaded and baked into the Modal image automatically** by
`modal_app.py` (it calls `huggingface_hub.snapshot_download("openbmb/MiniCPM4.1-8B")`
at image-build time, so there is no per-request download). You do NOT download the
model onto this machine — it lives on Modal's GPU.

Do this:
```
python -m pip install modal
modal token new                                   # one-time auth
modal secret create storycode-api MODAL_API_KEY=<pick-a-long-random-secret>
modal deploy modal_app.py                          # builds image (downloads weights), deploys
```
`modal deploy` prints a public URL. The OpenAI base_url is **that URL + `/v1`**.

Before deploying, open `modal_app.py` and:
- Confirm `VLLM_VERSION` matches what the **MiniCPM4.1-8B Hugging Face model card**
  lists as the supported vLLM version (the model uses custom code → it serves with
  `--trust-remote-code`, already set).
- **Hybrid-reasoning caveat:** MiniCPM4.1-8B can run in a deep "thinking" mode. We
  want fast, grounded narration, NOT long chain-of-thought. Check the model card
  for how to disable thinking (often a chat-template flag or a system-prompt
  convention) and apply it. If `guided_json` is ignored, verify the installed vLLM
  supports the `xgrammar` guided-decoding backend.

Smoke-test the live endpoint (replace URL + secret):
```
curl -s -H "Authorization: Bearer <secret>" \
  <printed-url>/v1/chat/completions \
  -d '{"model":"openbmb/MiniCPM4.1-8B",
       "messages":[{"role":"user","content":"Reply with JSON only: {\"ok\": true}"}],
       "max_tokens":50}'
```
You should get a JSON chat completion back. If the container is slow to start the
first time, that is the GPU cold-start — retry after ~1–2 minutes.

## 2. Wire the secrets
Locally:
```
cp .env.example .env
# set MODAL_ENDPOINT_URL=<printed-url>/v1   and   MODAL_API_KEY=<secret>
```
The app reads these via `config.py` → `llm.py`. (On the HF Space later, set the same
two values as Space secrets.)

## 3. Run the real (model-backed) app and verify every tab
```
python app.py
```
Click **"Try the sample project"** and confirm, with the live model:
- **📖 The Story** renders, and the **Plain English** panel beside it is filled.
- Switching **Story style** (Simple Walkthrough / Kids Book / Thriller / News /
  Recipe) and **difficulty** re-narrates the Story **without re-analysing** (it
  should be fast — it reuses the cached per-file summaries).
- **🗺️ Architecture Map** draws a Mermaid diagram (boxes grouped by job, arrows).
- **🚦 Safe to Edit** shows `config.py` and `app.py` as 🔴, the rest 🟠/🟢.
- **📦 Dependencies** explains openai / chromadb / gradio in plain English.
- Upload a `.zip` with a fake API key in it → the 🔒 "we hid N secrets" banner shows.

If the model returns malformed or empty output, the app falls back to the
deterministic story — that's expected resilience, but your goal is for the live
model path to work.

## 4. Tune the narration (your main creative work — commit these)
Edit **only `story.py`** (the prompts). Iterate until each of the 5 styles × 3
difficulty levels is **accurate AND in-voice** and never invents anything not in the
facts. Keep the grounding system message intact. After any change:
```
python tests/test_analyzer.py        # must STILL be 10/10
```
Make small, frequent, **Codex-attributed commits** with clear messages (the OpenAI
Codex prize depends on Codex-attributed commit history).

## 5. Real-user proof (required for the Backyard AI track)
Run a real, non-trivial project a non-coder built (ideally the friend's actual
Claude-generated app) through StoryCode. Capture: a short quote from them,
before/after screenshots, and the produced story. Add these to `README.md` under
"The person I built it for".

## 6. Deploy + submission assets
- Create a Gradio Space under the **`build-small-hackathon`** org, push this repo,
  and set the two Space secrets (`MODAL_ENDPOINT_URL`, `MODAL_API_KEY`). Verify the
  Space reaches Modal (check Modal logs) and **test it on a phone**.
- Record a 60–90s demo video (upload → Story → Map → Safe-to-Edit) and link it in
  the README.
- Push to a **public GitHub repo** with the Codex-attributed commits; link it in
  the README.
- Post once on social and link it. Confirm the README frontmatter tags are present.

## Hard rules — do not violate (see AGENTS.md)
1. Do **not** add `torch` / `vllm` / `transformers` to `requirements.txt`. The GPU is
   on Modal; the Space is a CPU container.
2. Core model must be a **MiniCPM ≤32B** (`openbmb/MiniCPM4.1-8B`). Don't swap in a
   non-OpenBMB model.
3. Do **not** claim the Tiny Titan badge (our model is ~8B, not ≤4B).
4. Keep the custom UI (`ui/styles.css`). Don't revert to the default Gradio theme.
5. Never display or send code that hasn't passed `ingest.redact_secrets`.
6. If you change anything under `analyzer/`, update `tests/test_analyzer.py` and keep
   it green. The Architecture Map and Safe-to-Edit must stay computed from the
   ProjectModel, never from the model's text.

## When you're done, report back
List, explicitly: the live Modal endpoint URL (without the secret), the result of
the curl smoke test, whether each of the 4 tabs worked with the live model, which
prompts in `story.py` you changed and why, the Space URL, and anything you could
NOT get working. Do not claim a step passed unless you actually ran it.

## Do NOT build these yet (post-MVP queue — only after steps 1–6 ship)
Grounded chat Q&A → "How do I change X?" → error detective → dependency-risk polish
→ save/share → PDF export → GitHub-URL ingestion → before/after edit preview. One
feature per commit, in that order, and only once the MVP above is deployed.
```