| # SPI Architecture — Phase 1 (Foundation) |
|
|
| ## Status legend used throughout SPI docs |
|
|
| `WORKS` = executed with evidence · `STUB` = interface exists, deterministic placeholder logic · `PLANNED` = not built. |
|
|
| ## Component map (Phase 1) |
|
|
| | Component | Module | Status (Phase 1) | Notes | |
| |---|---|---|---| |
| | ProjectState | `spi/schemas/project_state.py` | WORKS | Pydantic v2, versioned, mutation log, transactional deltas | |
| | Evidence schema | `spi/schemas/evidence.py` | WORKS | PASS/REPAIR/REGENERATE/REPLAN/REJECT/UNRESOLVED/BLOCKED; every metric carries evidence | |
| | ProductionGraph | `spi/compiler/production_graph.py` | WORKS | DAG: project→act→sequence→scene→shot→generation job; topological sort; cycle rejection | |
| | Scheduler | `spi/scheduler/scheduler.py` | WORKS (mock lane) | Priority, dependencies, retries, recorded timing | |
| | Renderer interfaces | `spi/renderers/base.py` | WORKS | VideoRenderer/ImageRenderer/AudioRenderer protocols + capabilities() | |
| | Mock renderers | `spi/renderers/mock.py` | WORKS | Deterministic artifact metadata; GenerationCache keyed on request hash | |
| | ModelRouter | `spi/renderers/registry.py` | STUB | Routes by capability/cost/VRAM; real adapters arrive in Phase 2 | |
| | Level-1 verification | `spi/evaluation/level1.py` | WORKS | Deterministic checks (frame count, resolution, duration, entity presence) | |
| | EvidenceFusion | `spi/evaluation/evidence_fusion.py` | WORKS | Fuses MetricResults, flags disagreements | |
| | MasterArbiter | `spi/evaluation/arbiter.py` | WORKS | Evidence-based PASS/REPAIR/REPLAN/UNRESOLVED | |
| | IntentEngine | `spi/intelligence/intent.py` | STUB | Prompt→Goal; preserves explicit constraints vs AI additions | |
| | IdeaEngine / ConceptEngine | `spi/intelligence/ideas.py`, `concept.py` | STUB | Adaptive idea budget, no LLM in mock mode | |
| | WorldEngine / StoryGraph / CausalGraph | — | PLANNED | Phase 5 | |
| | Evidyne API | `spi/api/server.py` | WORKS | Tool layer with the §32 response contract; FastAPI optional | |
| | RepairEngine | — | PLANNED | Phase 7 | |
| | Real video backend | — | PLANNED | Phase 2: Wan 2.2 (see research_report.md) | |
| |
| ## Data flow (Phase 1, mock lane) |
| |
| ``` |
| prompt |
| → IntentEngine (constraints separated from creative additions) |
| → ProjectState (v1) |
| → MovieCompiler → ProductionGraph (DAG of shots/jobs) |
| → Scheduler → MockVideoRenderer (cached, deterministic artifacts) |
| → Level1 verification (deterministic checks → MetricResult with evidence) |
| → EvidenceFusion → MasterArbiter → PASS | REPAIR |
| → OutputCompiler summary → response contract |
| ``` |
| |
| ## Design rules honored in code |
| |
| - Agents exchange structured state and **deltas**, not prompt strings. `ProjectState.apply_delta()` is transactional and bumps `state_version`; every mutation is appended to a log. |
| - Evidence over assertion: `MetricResult` cannot be constructed without a status; scores without evidence are flagged by the arbiter as `UNRESOLVED`. |
| - Cheap-first verification: Level 1 (deterministic) runs before any Level-2 evaluator; `select_evaluators()` routes by artifact properties. |
| - Generation cache: requests are hashed (model+prompt+seed+params+refs); identical requests reuse artifacts. |
| - `SPI_MODE` = mock | small | production is threaded through the registry; mock needs no GPU. |
