ARCHITECTURE.md

# EYEWITNESS — cómo funciona (mapa del sistema)

## El principio de diseño

**Author the ground truth, don't detect it.** El motor compone cada cara desde un
vocabulario cerrado de 12 atributos (`game/face.py: VOCAB`), así que siempre sabe la
verdad exacta. Los modelos solo *traducen* — nunca tienen que reconocer nada.

## Flujo de una partida

```
intro ──ROLL──▶ glimpse (3s, CSS animation-delay oculta la cara)
      ──I SAW HIM──▶ testimony (texto libre EN/ES)
      ──SEND──▶ [PARSER] testimonio → JSON de atributos
                   ├── Tier B: MiniCPM5-1B fine-tuneado (ZeroGPU, frases sucias)
                   └── Tier A: matcher de sinónimos (backstop literal, siempre gana donde matchea)
              ──▶ sketch (dibuja SOLO lo que dijiste) + lineup (gr.Gallery PNG)
                   └── lineup.py: distractores desde TUS errores
                       · lo que dijiste MAL → plantado en distractores
                       · lo que NO mencionaste → ejes de confusión
                       · lo que acertaste → poda la rueda (p=0.72, afinado por simulación)
      ──click──▶ verdict: sello + cita con voz (VoxCPM2 pre-render, en memoria) +
                 tabla transparente dijiste/verdad + póster SE BUSCA (PIL) ──▶ next case
```

Rangos: ROOKIE (3s, rueda 4) → DETECTIVE (2s, 6) → INSPECTOR (1.5s, 6 + disfraz) → CHIEF (1s, 8 + disfraz).
"Disfraz" = el culpable cambia UN atributo saliente entre el crimen y la rueda.

## Ficheros

| Fichero | Qué hace |
|---|---|
| `app.py` | UI Gradio: una sola etapa `@gr.render` dirigida por `gr.State` dict (screen=intro/glimpse/testimony/lineup/verdict) |
| `game/face.py` | VOCAB + FaceSpec + renderer SVG paramétrico (estilo retrato robot) |
| `game/render.py` | SVG→PIL compartido (Gallery y póster) |
| `game/casegen.py` | Casos: crimen + culpable + parámetros por rango; carga banco Modal si existe |
| `game/parser.py` | Tier A: sinónimos EN+ES, matching longest-first |
| `game/model.py` | Tier B: MiniCPM5-1B slot-filling (gated: solo ZeroGPU/CUDA/env), merge con prioridad Tier A |
| `game/lineup.py` | Distractores derivados de errores (la mecánica firma) |
| `game/scoring.py` | Nota ponderada por saliencia + rating con humor |
| `game/poster.py` | Póster SE BUSCA compartible (PIL) |
| `modal_factory.py` | Build-time en Modal: banco de casos (llama.cpp+GGUF) + banco de voces (VoxCPM2, anchor a 48kHz) |
| `train/gen_dataset.py` | Dataset sintético: spec→testimonio ruidoso bilingüe (verdad por construcción) |
| `train/train_modal.py` | LoRA en Modal → publica `Fcabla/MiniCPM5-1B-eyewitness` |
| `tests/test_engine.py` | QA: testimonios límite, equidad por simulación (400 partidas), bounds |
| `deploy.sh` | Sube el Space a la org (idempotente) |

## Modelos en runtime (~5.7B total)

- `Fcabla/MiniCPM5-1B-eyewitness` (1.08B, LoRA) — parser de testimonios (SOLO sabe slot-filling:
  olvido catastrófico verificado — balbucea dataset en prompts abiertos). OJO: en inferencia
  exige el formato EXACTO de entrenamiento (SYSTEM corto + `Witness testimony: "..."`); con el
  prompt few-shot del base parrotea los valores del ejemplo (fedora fantasma, 12 jun).
- `openbmb/MiniCPM5-1B` base (1.08B) — escribe la COLETILLA personalizada del veredicto desde el
  diff dijiste/verdad (`culprit_taunt`); solo entra si pasa validación + actitud. El chiste
  principal del veredicto es AUTORADO por crimen (`CRIME_TAUNTS` en casegen.py — el lab demostró
  ~3% de acierto en comedia libre del 1B). `enable_thinking=False` obligatorio (modelo razonador).
- `CohereLabs/cohere-transcribe-03-2026` (2B) — ASR del testimonio hablado, EN EXCLUSIVA (sponsor).
  `language` es obligatorio: se transcribe con `en` Y `es` y gana el de mayor log-prob medio.
- VoxCPM2 (2.29B) — voz del veredicto EN VIVO clonando un anchor (`game/voice.py`); banco
  pre-renderizado como fallback. Audio siempre en memoria (48000, int16) — gr.Audio con rutas
  fuera de allowed dirs revienta el render.

**Veredicto**: punchline autorado del crimen + coletilla de memoria (1B vivo si pasa el listón,
autorada si no) → voz viva → banco enlatado → solo texto. Cada `except` loguea su causa
(`[taunt]`/`[voice]`/`[asr]` en logs del Space).

**Patrón ZeroGPU**: en el arranque se precargan a CPU el parser+pulla (model.py), la voz
(voice.py) y el ASR (asr.py) — así el primer testimonio hablado no paga la carga del 2B de
Cohere. Las funciones `@spaces.GPU` (20s parser/pulla/ASR, 30s voz) solo transfieren y generan.
La cuota ZeroGPU admite por duración SOLICITADA — pedir de más = llamadas rechazadas.

## Infra

- **Space**: `build-small-hackathon/eyewitness`, ZeroGPU (H200 slice), gating por env.
- **GitHub**: `fcabla/eyewitness` (público).
- **Dataset**: `build-small-hackathon/eyewitness-testimonies`.
- **Modal**: apps `eyewitness-factory` (casos+voces) y `eyewitness-train` (LoRA, A10G).

## Limitaciones conocidas (candidatas a iteración)

1. La pulla del veredicto es chiste sobre el CRIMEN (banco autorado de 64 líneas + 1B base
   improvisando por encima cuando pasa validación). Riesgo: cuando entra el modelo, la
   calidad es variable (legible pero no siempre tan buena como el banco curado).
2. El glimpse es vulnerable a inspeccionar el DOM (la cara sigue en el HTML borroso).
3. El parser puede alucinar atributos no mencionados (mitigado: Tier A manda donde habló).
4. Crash SIGSEGV espontáneo visto 1 vez en local (C-level, en el writer de stdout durante
   render de voz concurrente) — no reproducido en el Space; observar tras deploy.