🏃 Runbook

This runbook answers how to install StoryMatrix, generate a production, resume it, and keep provider costs controlled.

🔹 📦 Install profiles

The optional-dependency profiles come from pyproject.toml; minimal = [] adds nothing because all core dependencies already belong to the main dependency set.

Profile	Adds	Use
minimal	Nothing	Quick setup and CI dependency resolution; optional local SFX features are deferred until their extra is installed.
cloud	elevenlabs, freesound-python	Cloud TTS and Freesound integrations without the heavy local ML stack.
local	torch, transformers, chromadb, librosa, optimum[onnxruntime], sentence-transformers, TTS, numba, aubio, nltk, rapidfuzz, tinytag, unidecode	Privacy-focused, air-gapped, local AI and audio processing.
full	Cloud profile plus the complete local ML stack	Development with every provider family installed.
dev	Pytest, async test tooling, mocks, coverage, xdist, Hypothesis, Ruff, mypy, pre-commit, and MkDocs packages	Development and quality checks.
test	Pytest, async test tooling, mocks, coverage, snapshot testing, and HTTPX	Running the test profile and API tests.
docs	mkdocs, mkdocs-material, mkdocstrings[python]	Legacy documentation tooling; it is vestigial because this Quartz wiki is the documentation surface.
deploy	gunicorn, sentry-sdk[fastapi]	Deployment process and error reporting.

Install a profile from the repository root:

# repository root
uv sync --extra local

🔹 🧰 First run

The minimal startup contract is repaired; use the default profile for import-safe startup and install local only when exercising optional local SFX features (src/storymatrix/infrastructure/adapters/sfx/local.py).

# repository root
uv sync --extra local
source .venv/bin/activate
storymatrix config show

Set the local-only gate before any exploratory run:

# repository root
export APP__DEV_LOCAL_ONLY=true
storymatrix config show

🔹 🎬 Generate a story

The CLI entry point is storymatrix; the generate command accepts the story request and writes production artifacts under the configured output root (src/storymatrix/cli/main.py, src/storymatrix/config/models.py:AppSettings.output_dir).

# repository root
storymatrix generate --prompt "A short mystery in a lighthouse"

The prompt is required unless the loaded configuration supplies one; alternatively provide a StoryMatrix markdown input with --story-md <path-to-STORY.md> (src/storymatrix/cli/main.py).

For a named configuration file, pass the CLI option supported by the installed command surface:

# repository root
storymatrix generate --config storymatrix_config.yaml --prompt "A short mystery in a lighthouse"

The --prompt input remains required for this path unless the configuration file supplies a prompt.

🔹 📂 Output layout

The code contract uses out/, selected by AppSettings.output_dir; storymatrix_config.yaml also sets output_dir: out (src/storymatrix/config/models.py, storymatrix_config.yaml). Finalization places the distribution MP3 at the output root and organizes generated assets as follows (src/storymatrix/application/production/stages/finalize_production.py):

Path	Contents
out/<Title>.mp3	Final distribution MP3 at the output root.
out/artifacts/audio/tts/	TTS source audio.
out/artifacts/audio/sfx/	SFX source audio.
out/artifacts/audio/music/	Music source audio.
out/artifacts/audio/stems/	_tts.wav, _music.wav, _impact_sfx.wav, and _ambient_sfx.wav exports.
out/artifacts/audio/<Title>.wav	Master WAV.
out/artifacts/visual/images/	Scene and visual assets.
out/artifacts/text/	Text and JSON artifacts, including montage_details.json.

Finalization patches montage_details.json with final_output_path after it establishes the master output (src/storymatrix/application/production/stages/finalize_production.py). This layout is the code’s contract, not an observed run: out/ is empty in this checkout and no pipeline run completes here.

🔹 🔁 Resume a failed run

Pipeline checkpoints live at artifacts_path/checkpoint.json; the production use case reads the checkpoint and resumes from the recorded stage (src/storymatrix/application/use_cases/generate_story.py). Re-run with the CLI resume option after preserving the artifact directory:

# repository root
storymatrix generate --resume --prompt "A short mystery in a lighthouse"

Resume still passes through the same prompt/Story markdown input guard; alternatively use --story-md <path-to-STORY.md> or a configuration that supplies a prompt (src/storymatrix/cli/main.py).

🔹 🌐 Run API and web UI

The API console script starts the FastAPI service; its defaults are 0.0.0.0:8000 (src/storymatrix/config/models.py:APISettings, pyproject.toml).

# repository root
storymatrix-api

The NiceGUI web console resolves typed host, port, title, dark mode, and reload settings through WebSettings; focused startup evidence closes B13 at that boundary. Full browser workflow remains separately scoped (src/storymatrix/config/models.py, src/storymatrix/interfaces/web/main.py).

uv run storymatrix-web

The API exposes /health and /metrics, and its authentication/rate-limit dependencies use config.services.api; focused dispatch closes B14. Status polling uses only job_id and returns the declared response model, closing B17 at its named boundary (src/storymatrix/interfaces/api/main.py).

🔹 🛡️ Cost-control checklist

• Set APP__DEV_LOCAL_ONLY=true; the container selects mock or local adapters instead of paid providers (src/storymatrix/config/models.py, src/storymatrix/infrastructure/container.py).
• Select local strategies for TTS, SFX, music, and image generation in the strategy settings (src/storymatrix/config/models.py).
• Do not export cloud credential values; keep credential-bearing environment variable names unset for local runs (src/storymatrix/config/models.py).
• Use uv sync --extra local, not cloud or full, when the goal is an air-gapped install (pyproject.toml).
• Keep API and web services pointed at local development infrastructure and verify the effective configuration with storymatrix config show (src/storymatrix/cli/main.py).