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.