docs/architecture.md

# The Séance — Architecture

## Pipeline

```
User Input (strange concept)
        │
        ▼
┌─────────────────┐
│  The Scientist  │  nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16
│  (Nemotron-4B)  │  Cold, clinical field-note voice
└────────┬────────┘
         │ scientist_text
         ▼
┌─────────────────┐
│ The Mythologist │  openbmb/MiniCPM3-4B  (40K downloads, Apache 2.0)
│  (MiniCPM3-4B)  │  Ancient, folkloric, feeling-forward voice
└────────┬────────┘
         │ mythologist_text
         ▼
┌─────────────────┐
│ FLUX Constructor│  prompts/flux_constructor.py
│ (prompt chain)  │  Synthesises both text outputs → FLUX prompt
└────────┬────────┘
         │ flux_params
         ▼
┌─────────────────┐
│   The Dreamer   │  black-forest-labs/FLUX.1-schnell
│  (FLUX-schnell) │  301K downloads, Apache 2.0, ~12B params
└────────┬────────┘
         │ image_path
         ▼
   Artifact Card
  (3 panels + image)
```

## Model Loading Strategy

**Lazy sequential loading** — never load all models simultaneously.

```
Load Nemotron → run → unload → (VRAM free)
Load MiniCPM3 → run → unload → (VRAM free)
Load FLUX     → run → unload → (VRAM free)
```

Combined peak VRAM usage: ~8GB (single model at a time in bfloat16).
ZeroGPU limit: 40GB — well within budget.

## FLUX Prompt Chaining

The image prompt is NOT written independently. It is constructed from:
1. Key noun phrases extracted from Scientist output
2. Dominant creature/image from Mythologist output
3. Fixed style suffix: `dreamlike atmospheric surreal dark watercolor cinematic lighting no text`

This ensures the image feels like a visual synthesis of both voices.

## ZeroGPU Notes

- Each model load/unload cycle takes ~10-20 seconds cold, ~2-5 seconds warm
- FLUX.1-schnell inference: ~5-10 seconds at 4 steps on H200
- Total expected latency: 30-60 seconds per summoning
- Use `@spaces.GPU` decorator on the summon function for ZeroGPU allocation