README.md

metadata

title: StoryCode
emoji: 📖
colorFrom: indigo
colorTo: gray
sdk: gradio
sdk_version: 5.50.0
app_file: app.py
pinned: false
license: mit
tags:
  - backyard-ai
  - jetbrains
  - openbmb
  - minicpm
  - modal
  - off-brand

StoryCode — you built it, now understand it

You made an app with Claude, Cursor, or ChatGPT. It runs… but you have no idea what each file does, how they connect, or what you can change without breaking everything. StoryCode reads your whole project and tells you the true story of it — in plain language — plus a map of how the pieces fit and a traffic-light of what's safe to edit.

Upload a .zip (or paste one file) → get the Story, the Architecture Map, and Safe to Edit.

The person I built it for

A friend who shipped a RAG app entirely through Claude — five Python files, LangChain, a vector database — and froze the first time it crashed, because they didn't know which file the error came from or whether touching it would break the rest. They didn't need a senior engineer; they needed someone who'd read the whole thing and could explain it without jargon. That's StoryCode.

Why it's different (the part that matters)

Every other code explainer feeds raw code → an AI → hope. On a small model that hallucinates structure. StoryCode computes the truth first with deterministic static analysis (Python ast, tree-sitter for JS/TS, real dependency parsing), then the model only narrates the extracted facts. So:

• the Architecture Map is drawn from your real import edges, not a guess;
• the Safe-to-Edit verdict is computed from how many files depend on each file (its fan-in) — a fact, not a vibe;
• an 8B model stays reliable, because it never has to infer the wiring.

How it works

your .zip ─▶ ingest (filter + hide secrets)
          ─▶ static analysis  (ast · tree-sitter · deps)  ─▶ ProjectModel
                                                              (files, real edges,
                                                               fan-in/out, roles)
          ─▶ MAP   : summarise each file        (MiniCPM4.1-8B, guided JSON)
          ─▶ REDUCE: write the project's story   (your style + difficulty)
          ─▶ Mermaid map + Safe-to-Edit panel    (straight from ProjectModel)

• Brain: openbmb/MiniCPM4.1-8B, served on Modal with vLLM and guided_json so every summary and story is schema-valid by construction.
• Story styles: Simple Walkthrough (default) · Kids Book · Thriller · News Report · Recipe. Difficulty: explain-like-I'm-5 · teenager · adult. A literal Plain English panel always sits beside the creative version.
• Safety: a secret scanner hides API keys / passwords before anything is shown or sent to the model.

Models (all ≤ 32B)

Model	Size	Role
openbmb/MiniCPM4.1-8B	~8B	Per-file summaries + the project story

Run it locally

pip install -r requirements.txt
cp .env.example .env          # fill MODAL_ENDPOINT_URL + MODAL_API_KEY
modal deploy modal_app.py     # serves MiniCPM4.1-8B on a GPU; prints the endpoint
python app.py                 # open the Space, click "Try the sample project"

The deterministic analysis runs with no GPU: python tests/test_analyzer.py.

Scope (honest)

Deeply understands Python and JavaScript/TypeScript, plus HTML/CSS/JSON/YAML. Upload a .zip (GitHub-URL import is on the roadmap). Without a model endpoint the app still works — it falls back to a truthful, model-free story.

Tech & sponsors

Backyard AI · OpenBMB (MiniCPM4.1-8B core) · Modal (serverless GPU runtime) · JetBrains (a code-understanding companion for non-coders) · built with OpenAI Codex · custom UI (Off Brand).

• Demo video: · Social post: · Codex repo: