🎬 StoryMatrix SSOT
StoryMatrix turns a one-line prompt into a finished multimedia story — planned and written by a crew of LLM agents, then produced into mixed stereo audio with narration, dialogue, sound effects and music, plus generated images and a timeline.
🧭 Start here
| I want to… | Go to |
|---|---|
| Install it and generate my first story | 🏃 Runbook — but read the warning below first |
| Understand how a prompt becomes audio | 🎞️ Production Pipeline |
| Configure a provider or change a default | ⚙️ Configuration and 🔑 Environment Variables |
| Look up a command or a flag | ⌨️ CLI Reference |
| Fix an error I just hit | 🚑 Troubleshooting |
| Know what is broken and what is next | 🗺️ Roadmap |
🚨 Read this before you install
The minimal startup contract is repaired. The local SFX adapter now defers optional imports, and focused evidence demonstrates import-safe startup while keeping the SFX path enabled. Full generation remains evidence-blocked.
No pipeline run has ever completed on this checkout. The output directory is empty. Everything this wiki documents about output layout is read from the code that would write it, and every page that describes run artifacts says so explicitly.
The repaired B1 contract and the remaining evidence boundary are tracked on 🗺️ Roadmap.
🗂️ Sections
| Section | What it covers |
|---|---|
| 🏗️ Architecture | Layering and dependency rules, the nine-stage pipeline, the agent crews, the audio chain, and the decisions behind them |
| 📚 Reference | CLI, HTTP API, configuration tree, environment variables, provider integrations, domain model |
| 🛠️ Development | Setup, conventions, and how the test suite is organized and currently doing |
| 🚀 Operations | Running it, observing it, and recovering when it breaks |
| 🗺️ Roadmap | Blockers, open work, what is proven done, what cannot be proven yet |
| 📜 History | Dated decisions, real incidents, and where the pre-migration documents went |
⚡ What it is, technically
| Aspect | Detail |
|---|---|
| Language | Python 3.11+, CPU-only by design — no GPU dependency in the required install |
| Architecture | Hexagonal / clean architecture; the domain layer depends on nothing |
| Pipeline | Nine ordered stages with checkpoint-based resume |
| Agents | Four CrewAI crews; the story crew runs six agents across five tasks |
| Providers | 21 concrete adapters across seven categories; the wired subset is selectable by config, the rest exist but are unreachable |
| Interfaces | A Typer CLI, a focused FastAPI service with repaired API/status contracts, and a NiceGUI web UI whose typed startup settings now resolve; full workflows remain separately scoped |
| Persistence | SQLite for content, plus filesystem-backed media assets |
| Observability | 19 Prometheus metric families and OpenTelemetry stage tracing |
| Cost control | APP__DEV_LOCAL_ONLY=true forces local and mock adapters so paid providers are never called |
📌 Status
| Lifecycle | Active. Development runs through 2026-02 with open work tracked in-repo |
| Health | Not healthy. B2–B12, the flaky suite, structural work, and evidence-blocked runs remain open |
| Test suite | 12 errors and 18 skipped of 458 non-skipped; passing count varies 391–393 across identical runs |
| Written against | master at 9d810e1 |
| Reviewed | 2026-08-02 |
Active and healthy are different claims. This project is under development and its documentation is current; its headline command does not work on a default install. Both things are true and this wiki says both.
⚠️ Open questions & known gaps
Everything below was found by reading source, not by reading documentation. It is published here rather than quietly fixed, because the repository is not this wiki’s to change.
🔴 Blockers
Six demonstrated source defects (B1, B13–B17) are closed at their named contract boundaries; B2–B12, the flaky suite, structural work, and evidence-blocked runs remain open. Full evidence and remediation notes are on 🗺️ Roadmap; symptom-first lookup is on 🚑 Troubleshooting.
| ID | Sev | Symptom |
|---|---|---|
| B1 | P0 | Minimal startup and optional local-SFX import boundary repaired; full generation remains unverified |
| B2 | P0 | The legacy story-crew fallback raises NameError on entry |
| B3 | P0 | The agentic timeline path never runs, and a fallback hides the error |
| B4 | P0 | The mock image service is abstract and cannot be constructed |
| B5 | P0 | Mock mode always fails the image-prompt crew at the LLM boundary |
| B6 | P1 | An async repository conversion never reached its callers |
| B7 | P1 | The golden-path fixture no longer satisfies its schema |
| B8 | P1 | A wiring fixture passes a string where a path is required |
| B9 | P1 | A repository annotates a type it never imports (latent) |
| B10 | P1 | Eighteen undefined names in src/ |
| B11 | P2 | Untracked debris at the repository root |
| B12 | P2 | AGENTS.md names the wrong output directory |
| B13 | P1 | Web startup settings contract repaired; full browser workflow remains separately scoped |
| B14 | P0 | API dependency boundary and monitoring routes repaired |
| B15 | P0 | Typed CLI precedence and offline/low-resource safety contract repaired |
| B16 | P2 | Config-loader stdout debug noise removed |
| B17 | P1 | Status handler now matches the declared job-id response contract |
📛 Documentation that contradicts the code
In every row the code is authoritative and this wiki follows it.
| Topic | What the code does | What the document says | Where |
|---|---|---|---|
| Output root | Defaults to out/, and the shipped YAML sets it too | outputs/ is the active target and out/ is legacy | AGENTS.md — the wrong party; README.md agrees with the code |
| Completeness | Eleven open blockers (B2–B12); B1 and B13–B17 are closed only at named focused boundaries | ”Phoenix Protocol 100% Complete”, “production-grade” | README.md |
| Metrics coverage | Tracing reaches seven of nine major stages | ”100% metrics coverage (14/14 stages)“ | README.md |
| Install profiles | The minimal profile is an empty list — it adds nothing, because every core dependency is already required | Four profiles offered as meaningful choices | README.md |
| Config precedence | Defaults/environment, YAML, then explicit typed CLI overrides; one resolved object reaches consumers | A simple four-tier override chain | README.md, AGENTS.md — stale about implementation details |
| Style guide | The file does not exist; docs/ is empty after the migration | ”Follow docs/STYLE_GUIDE.md” | CONTRIBUTING.md |
| Task tracker sources | Both referenced files were deleted in the migration | Cites a flaws document and a project-state YAML | CHECKLIST.md |
🧟 Code that exists but is never reached
Not bugs exactly — but each is a claim the codebase makes and does not keep.
| Thing | State |
|---|---|
config/yaml_precedence_validator.py | Never called by the config loader |
api_cache.py’s @cached(ttl, namespace) | Defined, with an example; no adapter imports or calls it |
crew/timeline_crew.yaml at the crew root | Dead — the live file is the one under crew/configs/ |
crew/prompts/planner.md, reviewer.md, writer.md | Unreachable. The file: include mechanism exists in the crew factory, but every configured backstory is inline, so the loader never fires |
crew/prompts/personas/*_author_template.md | Unreachable for the same reason; persona text is inline in the crew config |
| Crew tool registry | Registered and populated, but every tool returns a constant — and the factory never passes tools into constructed agents, so they are not wired either |
InteractiveStoryBuilder in cli/interactive.py | No CLI flag or command invokes it |
generate --story-md | Accepts a path and uses it only to bypass the missing-prompt guard; the file is never read |
generate --min-similarity-score | Accepted by the parser and then ignored; the global similarity option is the effective one |
The docs install extra | Pulls a documentation generator that is vestigial now that documentation lives in this wiki |
🔧 Interface defects worth knowing
| Issue | Detail |
|---|---|
| Status route | The handler now accepts job_id only and returns the declared response shape; focused pending/ready coverage closes B17 |
| Duplicate health route | One explicit /health handler remains; focused API dispatch covers the liveness contract |
| Web UI startup | Typed WebSettings now supplies title, dark mode, and reload; focused startup closes B13, while full browser workflow remains separately scoped |
🌍 Non-portable and orphaned configuration
| Issue | Detail |
|---|---|
| Host-specific defaults | Two provider defaults — the Midjourney API URL and the Ollama base URL — point at a specific machine. Treat them as placeholders and override them |
| Environment template drift | .env.example lists names no code consumes, including ElevenLabs and DALL·E variables under the wrong prefixes, several Chroma and web keys with no matching fields, a media-repository path, and a commented provider key. It also carries a stale host-specific value |
| Unprefixed config | Some nested settings groups have no environment prefix, so they are YAML-only. They are documented as such rather than given invented variable names |
❓ Genuinely open questions
Not answerable from code, and deliberately not guessed:
- No performance baseline exists. There is no reproducible measurement of generation latency, throughput or resource use, so the known image-generation bottleneck cannot be quantified beyond “over ten minutes for two scenes”.
- Which historical fixes actually reached verified production behaviour is unknown. Many items are ticked in the repository’s tracker with no evidence beyond the tick, and no run completes here to check them. They are separated on the roadmap into proven, open, and evidence-blocked rather than being collapsed into one list.
Both are recorded in the 🧾 Claim Registry as unsourced rather than asserted either way.
🧾 How this wiki is kept honest
Every factual claim cites the code path it came from. Claims that can be machine-checked live in the 🧾 Claim Registry with a lifecycle state and, where one exists, the test that proves them — and a claim whose named test does not actually assert it stays marked disputed rather than being quietly promoted. Five claims are in exactly that state today.
Provenance for every page, and the fate of the 498 migrated documents, is on 🧾 Evidence & Provenance.