File size: 2,906 Bytes
71d239c | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 | # AGENTS.md — rules for any agent (Codex) working in this repo
StoryCode explains a non-coder's project to them as a story. Read `HANDOFF.md` for
the task list and `~/.claude/plans/so-uh-this-is-modular-curry.md` for the why.
## The one rule that defines this app
**Static analysis is the source of truth; the model only narrates it.**
`analyzer/` computes the real files, import edges, fan-in/out, roles, entry points,
and safe-to-edit verdicts. The language model (via `narrate.py` / `story.py`) writes
plain-English *about* those facts. Never let the model invent files, edges, or
safety verdicts, and never let model text override what `analyzer/` produced. The
Architecture Map (`diagram.py`) and Safe-to-Edit panel are built directly from the
ProjectModel — keep them that way.
## Architecture (where things live)
- `ingest.py` — zip/file → clean `SourceFile`s; **redacts secrets** before anything
leaves it. All code text must pass through here first.
- `analyzer/` — the deterministic engine. `graph.py` owns edges, fan-in/out, roles,
and the safe-to-edit logic. Touch with care; it's covered by tests.
- `narrate.py` — map (per-file) + reduce (project), with caching and a model-free
fallback. `story.py` — the prompts. `llm.py` — the Modal/vLLM client.
- `app.py` + `ui/` — the Gradio UI. `modal_app.py` — the GPU backend.
## Hard constraints — do not violate
1. **No `torch` / `vllm` / `transformers` in `requirements.txt`.** The Space is a
CPU container; the GPU lives on Modal (`modal_app.py`). The only exception is the
ZeroGPU break-glass path, and only if you deliberately switch to it.
2. **Model ≤ 32B and it must be a MiniCPM** (OpenBMB prize). Default is
`openbmb/MiniCPM4.1-8B`. Don't swap in a non-OpenBMB model as the core brain.
3. **Don't claim the Tiny Titan badge** (that needs all models ≤4B; ours is ~8B).
4. **Keep the custom UI** (`ui/styles.css`) — it's the Off-Brand badge and a user
requirement. Don't fall back to the default Gradio theme.
5. **Secrets:** never display or send code without `ingest.redact_secrets` having
run. Don't weaken the secret patterns.
6. **Tests stay green.** If you change `analyzer/`, update `tests/test_analyzer.py`
and keep `python tests/test_analyzer.py` at 10/10 (or higher).
## Style conventions (match the existing code)
- `from __future__ import annotations`; PEP 604 unions (`str | None`); module
docstrings that explain *why*, not just *what*.
- Keep functions small and pure where you can; parsing/analysis code never calls
the network or the model.
- Prefer extending the curated map in `analyzer/deps.py` over adding a model call.
## What to work on
Only the next unchecked item in `HANDOFF.md`. Don't start post-MVP features until
steps 1–6 there are deployed. One feature per commit; write Codex-attributed
commit messages (the OpenAI Codex prize depends on them).
|