diff --git a/backlog/transcript-sprint-backlog.md b/backlog/transcript-sprint-backlog.md new file mode 100644 index 0000000..fc30722 --- /dev/null +++ b/backlog/transcript-sprint-backlog.md @@ -0,0 +1,265 @@ +# Transcript Forensics · Sprint backlog + +**Producto**: Transcript Forensics (audio counterpart to Blocao). +**Stack**: misma plataforma que Blocao (router + Cell + hub + GitOps + Mosquitto). Lo distinto es el contenedor de procesamiento (Whisper + pyannote) y el panel forense del audio. + +Las stories `WDM-T-XX.Y` corresponden 1:1 con la épica numerada. Muchas son **trivialmente reutilizables** desde el backlog Blocao — esas se identifican abajo y se delegan a `shared-stories.md`. + +--- + +## Cómo se relaciona con Blocao + +La gran mayoría de la infraestructura es la misma: monorepo, CI, image builder, balena fleet, MQTT contract, GitOps reconciler, hub, auth, network sovereignty, design tokens, console framework. Las épicas 0, 1, 2, 5, 6, 7 son **prácticamente idénticas** — solo cambia qué corre dentro del Cell y qué panel muestra la consola. + +Las épicas que **sí son específicas** del transcript product: + +- **Épica 3 — Audio onboarding** (en lugar de camera onboarding). +- **Épica 4 — Transcript operator plane** (en lugar de video operator plane). + +Esto significa que ~70% del trabajo de Transcript Forensics ya está hecho cuando Blocao MVP esté en producción. + +--- + +## ÉPICAS y mapping a Blocao + +| Sprint | Épica | Mapping a Blocao | +|---|---|---| +| 0 | Foundation | Idéntico a Blocao Épica 0. Stories `SHARED-00.X`. | +| 1 | First boot | Idéntico a Blocao Épica 1. Stories `SHARED-01.X`. | +| 2 | Engineering plane | Idéntico a Blocao Épica 2. Stories `SHARED-02.X`. | +| 3 | **Audio onboarding** | NUEVO. Stories `WDM-T-03.X`. | +| 4 | **Transcript operator plane** | NUEVO. Stories `WDM-T-04.X`. | +| 5 | Health & ops | Idéntico a Blocao Épica 5 + algunos checks específicos de STT. Stories `SHARED-05.X` + `WDM-T-05.X`. | +| 6 | Hub & fleet | Idéntico a Blocao Épica 6. Stories `SHARED-06.X`. | +| 7 | Hardening | Idéntico a Blocao Épica 7 + manifest schema con campos audio-specific. Stories `SHARED-07.X` + `WDM-T-07.X`. | + +--- + +# ÉPICA 3 — AUDIO ONBOARDING + +Equivalente a la épica de camera onboarding pero para audio sources. + +### `[WDM-T-03.1]` Audio source discovery — *M* + +**Como** installer, **veo** las fuentes de audio disponibles: USB mic conectado, line-in, SIP gateway, file watcher, archivos subidos manualmente. + +Backend en Cell: enumera devices ALSA/PulseAudio, comprueba SIP gateway si configurado, escanea carpetas watched. +**Tests de aceptación**: enchufar un USB mic se detecta en <5s; añadir un fichero a watched folder se detecta en <30s. +**Estimación**: M (3d). +**Depende de**: SHARED-02.1 (hai.uc base). + +### `[WDM-T-03.2]` Audio source authentication — *S* + +**Como** installer, para SIP gateways o cuentas de servicio, **introduzco** credenciales y se verifican. + +Backend: SIP register-test, IMAP/POP3 test si fuente es email-attached audio. +**Estimación**: S (1d). +**Depende de**: WDM-T-03.1. + +### `[WDM-T-03.3]` Test stream + transcripción de prueba — *M* + +**Como** installer, **graban** 30s de audio y veo la transcripción aparecer. + +Backend: el Cell recibe orden de capturar 30s, los pasa a Whisper, devuelve resultado al router. +**Tests de aceptación**: la transcripción aparece en <60s; speaker labels (SP-A, SP-B) aparecen si hay 2+ speakers. +**Estimación**: M (3d). +**Depende de**: WDM-T-03.2, WDM-T-04.1 (whisper container). + +### `[WDM-T-03.4]` Configure form — name, language, retention, speakers expected — *S* + +**Como** installer, **introduzco** datos: nombre del source, idioma esperado, retention (hereda regional), speakers esperados (lista o "auto"). + +UI: form similar al de cameras. +**Estimación**: S (1d). +**Depende de**: WDM-T-03.3. + +### `[WDM-T-03.5]` Save — generate Whisper config + GitOps commit — *L* + +**Como** installer, **al guardar**, se genera la config de Whisper para el source, se comitea, se reinicia el container, primer ciclo de prueba end-to-end. + +Backend: +1. Generar la sección `sources:` del whisper.yml. +2. Commit local al repo. +3. Push si configurado. +4. Trigger reconcile. +5. Esperar primer transcript end-to-end. + +**Tests de aceptación**: tras "FINISH", primer evento `aud//transcript` llega al MQTT en <60s. +**Estimación**: L (5d). +**Depende de**: WDM-T-03.4, SHARED-02.8 (gitops). + +### `[WDM-T-03.6]` Speaker library — initial enrollment — *M* + +**Como** installer, **enrollo** voiceprints conocidos: subo audio o grabo en directo, etiqueto con nombre. + +Backend: pyannote produce el embedding, se guarda en Qdrant collection `speakers/`. +**Tests de aceptación**: 5 speakers enrolados; en sesiones nuevas, esos speakers son identificados automáticamente con score >0.7. +**Estimación**: M (3d). +**Depende de**: WDM-T-03.5. + +--- + +# ÉPICA 4 — TRANSCRIPT OPERATOR PLANE + +El panel forense del audio. Equivalente al panel forense de video pero adaptado. + +### `[WDM-T-04.1]` Whisper + pyannote container — *L* + +**Como** team, **necesito** un contenedor Balena que corra Whisper + pyannote en el Cell, expuesto como API. + +Stack: +- Whisper.cpp con quantized model (large-v3-q5). +- Pyannote para diarization. +- Wrapper FastAPI que orquesta: audio in → diarization → transcripción por segmento → match contra speaker library. + +**Tests de aceptación**: 60min de audio se procesan en <15min en RK3588 con NPU; 95% accuracy en idioma claro (Spanish/English). +**Estimación**: L (1 sem). +**Depende de**: SHARED-00.4 (balena fleet provisioning). + +### `[WDM-T-04.2]` Transcript chat UI con autocomplete — *M* + +**Como** investigator, **escribo** consultas naturales sobre transcripts: "qué se dijo del contrato Acme y quién insistió más". + +Reuso del componente chat del Blocao operator plane. Vocabulario adaptado: speakers conocidos, topics, time ranges. +**Tests de aceptación**: query en español devuelve hits relevantes; ghost text sugiere desde corpus de transcripts existente. +**Estimación**: M (3d). +**Depende de**: WDM-T-04.1, BL-04.5 (chat UI base — shared). + +### `[WDM-T-04.3]` Transcript timeline con speaker bands — *L* + +**Como** investigator, **veo** un waveform con bands coloreadas por speaker (uno por color), markers en hits, playhead. + +UI: similar al timeline de video pero con waveform en vez de frames; swimlanes son speakers en lugar de cameras. +Backend: API devuelve segments `{start, end, speaker_id, confidence, text}`. +**Tests de aceptación**: 1h de transcript con 4 speakers se renderiza en <500ms; click en marker reproduce desde ese punto. +**Estimación**: L (5d). +**Depende de**: WDM-T-04.1. + +### `[WDM-T-04.4]` Audio player con live caption — *M* + +**Como** investigator, **reproduzco** el audio y **veo** la transcripción avanzar sincronizada con el playhead. + +UI: player shell shared con video; visualización es waveform en lugar de frame. +Backend: streaming HTTP con range requests; transcript events sincronizados. +**Tests de aceptación**: scrubbing fluido; caption salta correctamente al cambiar speaker. +**Estimación**: M (3d). +**Depende de**: WDM-T-04.3. + +### `[WDM-T-04.5]` Topic detection panel — *L* + +**Como** investigator, **veo** los topics detectados en una sesión, ordenados por tiempo de discusión, click → hits relacionados. + +Backend: NER (Named Entity Recognition) + clustering de spans; topics aparecen como entities (personas, organizaciones, fechas, lugares, montos económicos). +**Tests de aceptación**: en transcript de 1h con 5 topics distintos, se detectan al menos 4 con precisión. +**Estimación**: L (5d). +**Depende de**: WDM-T-04.1. + +### `[WDM-T-04.6]` Speaker breakdown — quién habla cuánto — *M* + +**Como** investigator, **veo** estadísticas por speaker: tiempo total, número de turnos, palabras, ratio de interrupción. + +UI: panel lateral en transcript view. +Backend: estadísticas calculadas del array de segments. +**Estimación**: M (2d). +**Depende de**: WDM-T-04.3. + +### `[WDM-T-04.7]` Insistence ranking por topic — *L* + +**Como** investigator, **veo** quién insiste más en cada topic detectado: número de intervenciones, repetición de keywords, evolución temporal. + +Backend: heurística sobre los segments + topic mapping. Score por (speaker, topic). +**Tests de aceptación**: en transcript con discusión clara de 2 partes sobre un topic, la heurística identifica correctamente quién insistió más. +**Estimación**: L (5d). +**Depende de**: WDM-T-04.5, WDM-T-04.6. + +### `[WDM-T-04.8]` Pin to case (transcript) — *M* + +**Como** investigator, **pino** un segmento o un transcript completo a un caso. + +Backend: extiende el modelo de cases existente con tipo `transcript_segment`. +**Estimación**: M (2d). +**Depende de**: BL-04.8 (case model — shared). + +### `[WDM-T-04.9]` Transcript export — bundle ZIP — *M* + +**Como** investigator, **exporto** un caso con transcripts, audio, manifests. + +Backend: extiende el exporter con tipos audio. +**Estimación**: M (3d). +**Depende de**: BL-04.10 (export base — shared). + +--- + +# ÉPICA 5 — HEALTH & OPS (transcript-specific additions) + +### `[WDM-T-05.1]` Selftest checks específicos de STT — *S* + +**Como** ops, **el selftest** verifica que Whisper container está sano, que el audio device es accesible, que el speaker library responde. + +Backend: tests adicionales en healthd. +**Estimación**: S (1d). +**Depende de**: BL-05.1 (selftest base). + +### `[WDM-T-05.2]` Transcripción throughput metrics — *S* + +**Como** ops, **veo** cuántos minutos de audio se procesan por hora, latencia desde grabación a transcript disponible. + +Backend: métricas publicadas a TimescaleDB. +**Estimación**: S (1d). +**Depende de**: WDM-T-04.1. + +--- + +# ÉPICA 7 — HARDENING (transcript-specific) + +### `[WDM-T-07.1]` Manifest schema audio-specific — *S* + +**Como** investigator, **el manifest** de cada transcript incluye: sha256_audio, sha256_transcript, ts_start, ts_end, model_sha, source_id, speaker_ids_present. + +Backend: extiende el manifest schema base con campos audio. +**Estimación**: S (1d). +**Depende de**: BL-07.1 (manifest base). + +### `[WDM-T-07.2]` Audio evidence verifier — *S* + +**Como** investigator, **`blocao verify`** acepta también audio + transcript + manifest. + +Backend: la CLI extiende su matching. +**Estimación**: S (1d). +**Depende de**: BL-07.2. + +--- + +# Cross-references a stories shared + +Para evitar duplicar trabajo, las stories de épicas 0, 1, 2, 5, 6, 7 que son comunes con Blocao están en [`shared-stories.md`](shared-stories.md): + +- `SHARED-00.1` ↔ `BL-00.1` (monorepo) +- `SHARED-00.2` ↔ `BL-00.2` (CI/CD) +- `SHARED-00.3` ↔ `BL-00.3` (image builder) +- `SHARED-00.4` ↔ `BL-00.4` (balena fleet — extiende con whisper container) +- `SHARED-00.5` ↔ `BL-00.5` (MQTT schemas — extiende con namespace `aud/`) +- ... (sprints 1, 2, 5, 6, 7) + +El equipo de transcript no escribe su propia versión de estas stories; trabaja sobre las shared y solo añade adaptaciones documentadas. + +--- + +# Riesgos específicos del transcript product + +1. **Whisper en RK3588** puede ser limitante si el audio tiene mucho ruido o múltiples lenguajes mezclados. Mitigación: ofrecer opción de fallback a Cell con Jetson para customers con audio difícil. +2. **Speaker library cross-session matching** depende de calidad de voiceprint enrollment. Mitigación: enrollment guidado en wizard, calidad mínima validada antes de aceptar. +3. **Privacy del audio** es aún más sensible que video — un whisper de transcripción puede capturar conversaciones íntimas. Mitigación: documentación clara de qué se graba y cuándo, signage equivalente a cámaras. +4. **Latencia transcripción → disponible para query**: en sitios con poca compute, puede ser >2x real-time. Mitigación: priorización por flag "investigation pending". + +--- + +# Notas para sprint planning + +El equipo transcript puede empezar **en el Sprint 4 de Blocao**, una vez que SHARED-00.X y SHARED-02.X estén estables. Antes, no hay sustrato sobre el que construir. + +Demo viable de transcript: ~Sprint 4 desde el inicio del transcript track. Asumiendo que Blocao MVP cierra en su Sprint 4, el transcript MVP es Sprint 8 desde el inicio del proyecto global. + +--- + +*Documento sujeto a revisión cuando el equipo transcript entre en planning.*