Pipeline Robusto Patterns

Pipeline Robusto — Patrones (de helmcode-whisper)

Lecciones transferibles del repo helmcode/helmcode-whisper que aplican a los pipelines de datos de Ntizar. El repo es un grabador/transcriptor de reuniones self-hosted; lo valioso no es lo que hace, sino cómo está pensado: cada decisión reduce el trabajo del paso difícil en lugar de añadirle complejidad.

When to Use

• Diseñar o revisar un pipeline de datos (fetch → normalizar → procesar → salida).
• Cuando un paso de un pipeline es "caro o impreciso" y se busca que lo sea menos resolviendo un problema aguas arriba.
• Al tocar código que consume APIs externas (límites de concurrencia, hosts permitidos).
• Cuando el output debe tener forma estable y el sistema degradar en vez de romperse.
• Escribir/editar prompts que generan salida estructurada de un LLM.

No usar para: documentar este repo concreto; para eso va una nota en notes/.

Los patrones

1. Resolver el problema en la captura, no en el modelo

helmcode-whisper graba micrófono y audio de sistema en DOS pistas separadas: "near vs far" se decide por el archivo, y pyannote solo tiene que desenredar al remoto. Idea clave: particiona el problema en el origen para que el paso difícil se vuelva trivial.

Cómo aplicarlo: si en un pipeline ya conoces la partición por construcción (isócronas por transporte, GTFS por dirección/agencia, series por fuente), sepárala en la fuente de datos en vez de dejar que el modelo lo adivine. Ante un paso caro o impreciso, pregunta primero: ¿se puede conocer esto ANTES, a partir de cómo capturo/particiono los datos?

2. Tests que imponen invariantes de arquitectura

tests/test_no_egress.py rompe el build si aparece cualquier host que no sea el de la API. No es una promesa en un README, es una regla verificada por CI.

Cómo aplicarlo: invariantes de arquitectura ("solo estos endpoints", "estas tablas son read-only") se imponen con un test, no con disciplina. En pipelines que tocan APIs externas: whitelist de hosts permitidos + test que falle el build si algo sale a otro lado.

3. Degradación en escalera con contrato de salida fijo

Nunca falla en duro. Si json_schema falla → baja a modos más laxos. Si pyannote no va → Me, Others. Si no hay audio de sistema → solo micrófono y avisa una vez. La forma del output es fija; la ruta degrada.

Cómo aplicarlo: define el contrato de salida de forma estable; en caso de fallo el pipeline se simplifica (calidad), pero el consumer nunca ve un resultado con forma distinta. Es la regla "no reemplazar funcional por roto": degradar, nunca romper.

4. Prompt como artefacto, modelo intercambiable, salida fijada

templates/notes.md es un fichero del repo (editable, versionado) con placeholders {{VAR}}, usando .replace() (no .format() — coincide con la nota de qwen NaN). El LLM es una variable (HCW_NOTES_MODEL) desacoplada de la forma del output (fijada por un JSON schema).

Cómo aplicarlo: separa el contrato de datos de salida (schema) del modelo que lo produce (config). Los prompts viven como archivos versionados en el repo, con placeholders reemplazables por .replace() — nunca .format().

5. Un solo pool compartido + conocer el límite de la API

4 requests concurrentes a través de un MISMO pool que cubre ambas tracks (un pool por track dejaría al micro esperando al sistema). Y 4, no más: la API permite 5 en paralelo y hace 429 al sexto.

Cómo aplicarlo: conoce el límite de concurrencia del proveedor (NaN = max 5 en paralelo) y deja margen (usa 4). Comparte el pool de conexiones en vez de fragmentarlo por fuente. Si un cron lanza sub-agentes en paralelo, los lanza SECUENCIALMENTE para no sobrepasar el límite.

6. Honestidad radical sobre "testeado vs no testeado"

Marca macOS como "implemented, not yet tested", admite que los números del benchmark vienen de audio SINTETIZADO, y que las instrucciones de BlackHole no se validaron en una máquina.

Cómo aplicarlo: normaliza decir qué se ha probado y qué no, y de dónde salen las cifras. Evita demos alucinados y builds que parecen más sólidos de lo que son.

Pitfalls

• Confundir "degradar" con "fallar silenciosamente": la degradación debe avisar (un WARN) y quedar registrada en meta.json con el mode usado, como hace el repo.
• Fragmentar pools por fuente "por claridad" → un recurso espera a otro. Comparte el pool.
• .format() en prompts con llaves JSON → KeyError. Usar .replace('{var}', ...).
• Poner el tope en el límite exacto de la API (5 de 5) → 429. Dejar margen.
• Chunking: mantener chunks por SILENCIO (VAD), no solo por límite de tamaño; cortar por silencio confina el daño en la detección de idioma por request.

Verification

• El pipeline degrada y lo registra (meta/mode), no revienta.
• El test de invariante pasa (hosts permitidos, etc.).
• Contrato de salida estable, modelo intercambiable.