BeyondCX_Insights/WORKFLOW.md

CXInsights - Development Workflow

Checkpoints Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                         DEVELOPMENT WORKFLOW                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  CP1 → CP2 → CP3 → CP4 → CP5 → CP6 → CP7 → CP8 → [CP9]                    │
│   │     │     │     │     │     │     │     │      │                       │
│   │     │     │     │     │     │     │     │      └─ Optimization         │
│   │     │     │     │     │     │     │     └─ E2E Pipeline                │
│   │     │     │     │     │     │     └─ RCA Aggregation                   │
│   │     │     │     │     │     └─ Compression                             │
│   │     │     │     │     └─ Inference Engine                              │
│   │     │     │     └─ Feature Extraction                                  │
│   │     │     └─ RCA Schemas                                               │
│   │     └─ Transcription Module                                            │
│   └─ Project Setup & Contracts                                             │
│                                                                             │
│  Cada checkpoint tiene criterios STOP/GO explícitos.                       │
│  NO avanzar sin aprobación del checkpoint anterior.                        │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

---

CHECKPOINT 1 — Project Setup & Contracts

Objetivo: Fijar estructura, contratos y versionado antes de escribir lógica.

Tareas

• Crear estructura de carpetas según ARCHITECTURE.md
• Inicializar repo Git con .gitignore (datos, .env, outputs)
• Crear requirements.txt con versiones pinned
• Crear .env.example con todas las variables necesarias
• Crear README.md con:
  • descripción del producto
  • instalación (virtualenv)
  • configuración (.env)
  • flujo de ejecución (alto nivel)
• Crear config/rca_taxonomy.yaml (Round 1 frozen)
• Crear config/settings.yaml (batch_size, limits, retries)
• Crear config/schemas/:
  • call_analysis_v1.py (Pydantic)
  • incluir: schema_version, prompt_version, model_id

Reglas

• ❌ No implementar lógica funcional
• ❌ No llamar APIs externas

Entregable

• Output de tree -L 3
• Revisión de contratos y estructura

STOP/GO Criteria

• Estructura completa y coherente con ARCHITECTURE.md
• Contratos Pydantic compilables
• .gitignore protege datos sensibles

---

CHECKPOINT 2 — Transcription Module (Isolated & Auditable)

Objetivo: STT fiable, comparable y con métricas reales.

Tareas

• Implementar src/transcription/base.py
  • interfaz Transcriber
• Implementar AssemblyAITranscriber
  • batch async
  • retries + backoff
  • captura de provider, job_id
• Implementar modelos:
  • Transcript
  • SpeakerTurn
  • incluir: audio_duration_sec, language, provider, created_at
• Implementar extracción básica de audio metadata (ffprobe)
• Tests:
  • 1 audio corto (mock o real)
  • validar estructura + diarización mínima
• Notebook 01_transcription_validation.ipynb:
  • 5–10 audios reales
  • medir: latencia, coste real/min, diarization quality

STOP/GO Criteria

• Calidad aceptable
• Coste real conocido
• Decisión proveedor STT

---

CHECKPOINT 3 — RCA Schemas & Data Contracts (NO LLM)

Objetivo: Definir qué significa una llamada analizada.

Tareas

• Implementar src/models/call_analysis.py:
  • CallAnalysis
  • RCALabel
  • EvidenceSpan
  • Event
• Reglas obligatorias:
  • separar observed vs inferred
  • events[] estructurado (HOLD, TRANSFER, ESCALATION…)
  • status por llamada (success/partial/failed)
  • trazabilidad: schema_version, prompt_version, model_id
• Crear data/examples/:
  • lost sale
  • poor CX
  • mixed
  • con evidence y events reales

STOP/GO Criteria

• ¿El schema captura TODO lo necesario?
• ¿Es auditable sin leer texto libre?

---

CHECKPOINT 4 — Feature & Event Extraction (Deterministic)

Objetivo: Sacar del LLM lo que no debe inferir.

Tareas

• Implementar src/features/event_detector.py:
  • HOLD_START / HOLD_END
  • TRANSFER
  • SILENCE
• Implementar src/features/turn_metrics.py:
  • talk ratio
  • interruptions
• Enriquecer Transcript → TranscriptWithEvents

STOP/GO Criteria

• Eventos coherentes
• Base causal estable para inference

---

CHECKPOINT 5 — Inference Engine (MAP Stage, Single Pass)

Objetivo: Inferencia consistente, explicable y controlada.

Tareas

• Crear un único prompt MAP:
  • sales + CX + RCA + reasoning
  • forzar JSON completo
• Implementar LLMClient:
  • JSON strict
  • retries + repair
  • logging de tokens
• Implementar BatchInference:
  • batch_size configurable
  • guardado incremental
  • resume seguro
• Tests:
  • evidence obligatorio
  • confidence < 0.6 si evidence débil
• Notebook 02_inference_validation.ipynb:
  • 10 llamadas reales
  • revisar evidence manualmente
  • coste por llamada

STOP/GO Criteria

• ¿El LLM no alucina?
• ¿La evidence es defendible?

---

CHECKPOINT 6 — Transcript Compression (Baseline, not optional)

Objetivo: Control de coste y latencia desde diseño.

Tareas

• Implementar CompressedTranscript:
  • customer intent
  • agent offers
  • objections
  • resolution statements
• Validar reducción tokens (>60%)
• Forzar uso de compressed transcript en inference

STOP/GO Criteria

• Coste predecible
• Latencia estable en 20k

---

CHECKPOINT 7 — Aggregation & RCA Trees (Deterministic Core)

Objetivo: Pasar de llamadas a causas.

Tareas

• Implementar estadísticas:
  • frecuencia
  • conditional probabilities
• Definir severity_score con reglas explícitas
• Implementar RCATreeBuilder (determinístico)
• (Opcional) LLM solo para narrativa
• Notebook 04_aggregation_validation.ipynb:
  • 100 llamadas
  • números cuadran
  • RCA prioriza bien

STOP/GO Criteria

• ¿El árbol es accionable?
• ¿Refleja impacto real?

---

CHECKPOINT 8 — End-to-End Pipeline & Delivery

Objetivo: Operación real sin intervención humana.

Tareas

• Implementar CXInsightsPipeline
  • manifests por stage
  • resume total/parcial
• Implementar exports:
  • Excel
  • PDF
  • JSON
• CLI principal
• Notebook 05_full_pipeline_test.ipynb:
  • 50 llamadas
  • medir tiempo total
  • medir coste total

STOP/GO Criteria

• Pipeline estable
• Outputs reproducibles

---

CHECKPOINT 9 — Optimization & Benchmarking (Optional)

Objetivo: Maximizar ROI.

Tareas

• Caching por hash
• Batch size benchmarks
• Comparar STT providers

---

Progress Tracking

Checkpoint	Status	Date Started	Date Completed	Notes
CP1	✅ Completed	2026-01-19	2026-01-19	Approved
CP2	✅ Completed	2026-01-19	2026-01-19	Approved
CP3	✅ Completed	2026-01-19	2026-01-19	Approved
CP4	✅ Completed	2026-01-19	2026-01-19	Approved
CP5	✅ Completed	2026-01-19	2026-01-19	Approved
CP6	✅ Completed	2026-01-19	2026-01-19	Approved
CP7	✅ Completed	2026-01-19	2026-01-19	Approved
CP8	✅ Completed	2026-01-19	2026-01-19	Approved
CP9	⏳ Optional	-	-	-