saga

S.A.G.A. (Story Analysis, Generation, and Archives) is described as canon-aware narrative intelligence for analysis, retrieval, timelines, and story generation. Rather than a single monolithic application, the project is organized as a contract-driven collection of reusable runtimes. What it does The README states that S.A.G.A. analyzes source books into evidence-backed canon, generates grounded stories and visual assets, synthesizes audited audiobooks, and packages release artifacts. The production orchestration path is documented as a sequence: source ingestion and analysis foundation; Modal XCore LitBank identity resolution; canon extraction; character and world modeling; generation planning; narrative generation and semantic support; visual generation and image QA; audiobook synthesis and transcription QA; and finally EPUB, manifest, lineage, and qualification reporting. Architecture The active source tree has four primary surfaces: - packages/ — independent runtime packages covering agents, reasoning, retrieval, persistence, execution, identity, media generation, observability, lineage, qualification, and deployment. - integrations/ — provider implementations for ComfyUI, Kokoro TTS, and XCore LitBank on Modal. - apps/dashboard_api/ — a stateless FastAPI control and query surface. - apps/dashboard_pro/ — a React operator dashboard. Supabase Postgres, pgvector, and object storage act as persistence providers behind packages/persistence_runtime. LangGraph execution is owned by packages/agent_runtime. Provider credentials stay in persistence or deployment secret stores and are injected into runtimes rather than committed to source control. A notable design decision is that an earlier implementation is kept as inert reference material under backup/reference/. Active code is prohibited from importing it, and this boundary is enforced by an automated architecture-boundary test. Additional documentation files cover the storage architecture and an architecture hardening audit. Development workflow Python dependencies are locked with uv, and the documented commands are: uv sync --frozen --extra dev uv run pytest -q Dashboard development is handled with npm ci, npm test -- --run, and npm run build inside apps/dashboard_pro. The API is started with uv run saga-runtime-api after configuring the Supabase environment. Production and operations Production topology and operations live under deploy/production/ and are documented in docs/deployment_operations.md. The deployment is split into separate processes for API, workers, scheduler, observability, frontend, migrations, and a telemetry collector. A docker compose workflow is provided for configuration validation and startup. Container base images and the OpenTelemetry collector are pinned by digest. CI publishes runtime and dashboard images from the main branch, refuses existing version tags, creates provenance attestations, and stores a release manifest containing the commit and image digests. Production promotion is described as failing closed unless the deployment manifest has clean committed source provenance. Documentation index The README points to docs/system_agent_roadmap.md and docs/production_qualification.md for implementation and qualification status, plus operational references on deployment (build, rollout, rollback, backup, recovery), runtime secret ownership, storage contracts and provider boundaries, end-to-end orchestration, accepted real-book qualification evidence, and the architecture integrity audit. Assessment The repository is best understood as infrastructure for grounded, canon-aware story production: it combines retrieval and identity resolution over source books with generation stages for text, images, and audio, and finishes with release packaging and provenance-oriented CI. The README is heavy on architecture and operational contract detail and does not publish benchmark or quality claims; capability statements should be read against the qualification documentation it references.