README.md

---
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

```bash
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: _<link>_ · Social post: _<link>_ · Codex repo: _<link>_