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