feat: Add Streamlit dashboard with Blueprint compliance (v2.1.0)
Dashboard Features: - 8 navigation sections: Overview, Outcomes, Poor CX, FCR, Churn, Agent, Call Explorer, Export - Beyond Brand Identity styling (colors #6D84E3, Outfit font) - RCA Sankey diagram (Driver → Outcome → Churn Risk flow) - Correlation heatmaps (driver co-occurrence, driver-outcome) - Outcome Deep Dive (root causes, correlation, duration analysis) - Export functionality (Excel, HTML, JSON) Blueprint Compliance: - FCR: 4 categories (Primera Llamada/Rellamada × Sin/Con Riesgo de Fuga) - Churn: Binary view (Sin Riesgo de Fuga / En Riesgo de Fuga) - Agent: Talento Para Replicar / Oportunidades de Mejora - Fixed FCR rate calculation (only FIRST_CALL counts as success) Technical: - Streamlit + Plotly for interactive visualizations - Light theme configuration (.streamlit/config.toml) - Fixed Plotly colorbar titlefont deprecation Documentation: - Updated PROJECT_CONTEXT.md, TODO.md, CHANGELOG.md - Added 4 new technical decisions (TD-014 to TD-017) - Created TROUBLESHOOTING.md with 10 common issues Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
sujucu70
256
docs/TECHNICAL_DECISIONS.md
Normal file
256
docs/TECHNICAL_DECISIONS.md
Normal file
@@ -0,0 +1,256 @@
|
||||
# TECHNICAL_DECISIONS.md
|
||||
|
||||
> Registro de decisiones técnicas con rationale
|
||||
|
||||
---
|
||||
|
||||
## TD-001: STT Provider
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **Fecha** | 2026-01-19 |
|
||||
| **Contexto** | Necesitamos transcribir 5k-20k llamadas en español con diarización |
|
||||
| **Opciones evaluadas** | AssemblyAI, Whisper (local), Google Speech-to-Text, AWS Transcribe |
|
||||
| **Decisión** | AssemblyAI |
|
||||
| **Rationale** | Mejor diarización español, API simple, coste competitivo (~$0.04/call) |
|
||||
| **Trade-offs** | Dependencia de servicio externo, costes recurrentes |
|
||||
| **Reversibilidad** | Alta - interface abstracta permite cambiar provider |
|
||||
|
||||
---
|
||||
|
||||
## TD-002: LLM for Inference
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **Fecha** | 2026-01-19 |
|
||||
| **Contexto** | Necesitamos extraer RCA labels con evidence de transcripts |
|
||||
| **Opciones evaluadas** | GPT-4o, GPT-4o-mini, Claude 3.5 Sonnet |
|
||||
| **Decisión** | GPT-4o-mini (default), configurable |
|
||||
| **Rationale** | Cost-effective, JSON strict mode, buen español, configurable via CLI |
|
||||
| **Trade-offs** | Menor capacidad que GPT-4o, posible menor precisión |
|
||||
| **Reversibilidad** | Alta - `--model` flag permite cambiar |
|
||||
|
||||
---
|
||||
|
||||
## TD-003: Data Storage
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **Fecha** | 2026-01-19 |
|
||||
| **Contexto** | Almacenar transcripts, analyses, manifests |
|
||||
| **Opciones evaluadas** | Filesystem JSON, SQLite, DuckDB, PostgreSQL |
|
||||
| **Decisión** | Filesystem JSON |
|
||||
| **Rationale** | Simplicidad, debuggability, checkpoint/resume fácil, sin dependencias |
|
||||
| **Trade-offs** | No óptimo para queries complejos en >50k llamadas |
|
||||
| **Reversibilidad** | Media - migrar a DB requiere refactor |
|
||||
|
||||
---
|
||||
|
||||
## TD-004: OBSERVED vs INFERRED Separation
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **Fecha** | 2026-01-19 |
|
||||
| **Contexto** | Outputs deben ser auditables y defendibles |
|
||||
| **Opciones evaluadas** | Mezclar todo, separar en campos, separar en objetos |
|
||||
| **Decisión** | Separar en `ObservedFeatures` y campos inferred |
|
||||
| **Rationale** | Auditoría clara, stakeholders ven qué es hecho vs opinión |
|
||||
| **Trade-offs** | Estructura más compleja |
|
||||
| **Reversibilidad** | Baja - cambiar rompe contratos downstream |
|
||||
|
||||
---
|
||||
|
||||
## TD-005: Evidence Mandatory
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **Fecha** | 2026-01-19 |
|
||||
| **Contexto** | RCA labels deben ser verificables |
|
||||
| **Opciones evaluadas** | Evidence opcional, evidence recomendado, evidence obligatorio |
|
||||
| **Decisión** | Evidence obligatorio (`evidence_spans[]` min 1) |
|
||||
| **Rationale** | Sin evidence = alucinación, indefendible ante cliente |
|
||||
| **Trade-offs** | LLM puede fallar si no encuentra evidence |
|
||||
| **Reversibilidad** | Baja - relajar validation afecta confianza en outputs |
|
||||
|
||||
---
|
||||
|
||||
## TD-006: Closed Taxonomy + OTHER_EMERGENT
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **Fecha** | 2026-01-19 |
|
||||
| **Contexto** | Balance entre estructura y flexibilidad |
|
||||
| **Opciones evaluadas** | Taxonomía abierta, taxonomía cerrada, híbrido |
|
||||
| **Decisión** | Taxonomía cerrada + `OTHER_EMERGENT` para captura |
|
||||
| **Rationale** | Consistencia en aggregation + captura de nuevos patrones |
|
||||
| **Trade-offs** | Requiere revisión manual de emergent para promover |
|
||||
| **Reversibilidad** | Alta - añadir códigos no rompe existentes |
|
||||
|
||||
---
|
||||
|
||||
## TD-007: Transcript Compression
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **Fecha** | 2026-01-19 |
|
||||
| **Contexto** | Reducir costes de LLM (tokens) |
|
||||
| **Opciones evaluadas** | No comprimir, extractive summary, rule-based extraction |
|
||||
| **Decisión** | Rule-based extraction (>60% reducción) |
|
||||
| **Rationale** | Predecible, sin pérdida de información clave, sin coste adicional |
|
||||
| **Trade-offs** | Puede perder contexto sutil |
|
||||
| **Reversibilidad** | Alta - `--no-compression` flag disponible |
|
||||
|
||||
---
|
||||
|
||||
## TD-008: Severity Scoring Formula
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **Fecha** | 2026-01-19 |
|
||||
| **Contexto** | Priorizar drivers en RCA tree |
|
||||
| **Opciones evaluadas** | Solo frecuencia, solo confidence, fórmula ponderada |
|
||||
| **Decisión** | Fórmula ponderada: base*0.4 + freq*0.3 + conf*0.2 + co-occur*0.1 |
|
||||
| **Rationale** | Balance múltiples factores, configurable |
|
||||
| **Trade-offs** | Pesos arbitrarios, pueden necesitar ajuste |
|
||||
| **Reversibilidad** | Alta - pesos en config |
|
||||
|
||||
---
|
||||
|
||||
## TD-009: Pipeline Checkpointing
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **Fecha** | 2026-01-19 |
|
||||
| **Contexto** | Batches grandes (20k) pueden fallar a mitad |
|
||||
| **Opciones evaluadas** | Sin checkpoint, checkpoint por archivo, checkpoint por stage |
|
||||
| **Decisión** | Checkpoint por stage con manifest JSON |
|
||||
| **Rationale** | Resume granular, debuggable, sin estado complejo |
|
||||
| **Trade-offs** | Más archivos en filesystem |
|
||||
| **Reversibilidad** | Alta |
|
||||
|
||||
---
|
||||
|
||||
## TD-010: Export Formats
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **Fecha** | 2026-01-19 |
|
||||
| **Contexto** | Outputs para diferentes stakeholders |
|
||||
| **Opciones evaluadas** | Solo JSON, JSON+Excel, JSON+Excel+PDF+Dashboard |
|
||||
| **Decisión** | JSON + Excel + PDF/HTML |
|
||||
| **Rationale** | JSON para devs, Excel para analysts, PDF para executives |
|
||||
| **Trade-offs** | Más código de export, dependencias (openpyxl) |
|
||||
| **Reversibilidad** | Alta - formats seleccionables |
|
||||
|
||||
---
|
||||
|
||||
## TD-011: Prompt Versioning Strategy (v2.0)
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **Fecha** | 2026-01-19 |
|
||||
| **Contexto** | Blueprint alignment requires significant prompt changes |
|
||||
| **Opciones evaluadas** | Modify v1.0 in-place, create v2.0 with deprecation, feature flags |
|
||||
| **Decisión** | Create v2.0 with v1.0 deprecated but preserved |
|
||||
| **Rationale** | Backward compatibility, traceability, easy rollback |
|
||||
| **Trade-offs** | More prompt files to maintain |
|
||||
| **Reversibilidad** | Alta - `--prompt-version v1.0` flag can be added |
|
||||
|
||||
---
|
||||
|
||||
## TD-012: Blueprint Alignment Scope
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **Fecha** | 2026-01-19 |
|
||||
| **Contexto** | Gap analysis identified ~20 gaps vs BeyondCX blueprints |
|
||||
| **Opciones evaluadas** | Implement all, implement high priority only, defer all |
|
||||
| **Decisión** | Implement HIGH priority gaps (FCR, Churn, Agent, RCALabel) |
|
||||
| **Rationale** | Core functionality gaps, medium priority can wait for Phase 2 |
|
||||
| **Trade-offs** | Medium/low priority gaps remain (campaign tracking, customer value) |
|
||||
| **Reversibilidad** | Media - additional gaps can be added incrementally |
|
||||
|
||||
---
|
||||
|
||||
## TD-013: DriverOrigin Attribution
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **Fecha** | 2026-01-19 |
|
||||
| **Contexto** | Blueprints require responsibility attribution for each driver |
|
||||
| **Opciones evaluadas** | 3 origins (agent/customer/company), 4 origins (+process), 5 origins (+unknown) |
|
||||
| **Decisión** | 5 origins: AGENT, CUSTOMER, COMPANY, PROCESS, UNKNOWN |
|
||||
| **Rationale** | PROCESS separates systemic issues from company decisions, UNKNOWN for ambiguous cases |
|
||||
| **Trade-offs** | More categories for LLM to distinguish |
|
||||
| **Reversibilidad** | Alta - can collapse categories if needed |
|
||||
|
||||
---
|
||||
|
||||
## TD-014: Dashboard Technology
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **Fecha** | 2026-01-19 |
|
||||
| **Contexto** | Necesitamos visualizar resultados de análisis para clientes |
|
||||
| **Opciones evaluadas** | Solo exports (Excel/PDF), Streamlit, Dash, React custom |
|
||||
| **Decisión** | Streamlit + Plotly |
|
||||
| **Rationale** | Desarrollo rápido, interactividad, Python nativo, fácil de mantener |
|
||||
| **Trade-offs** | Menos customizable que React, limitado para muy alto tráfico |
|
||||
| **Reversibilidad** | Media - componentes Plotly reutilizables |
|
||||
|
||||
---
|
||||
|
||||
## TD-015: Blueprint Terminology Compliance
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **Fecha** | 2026-01-19 |
|
||||
| **Contexto** | Dashboard debe usar terminología exacta de blueprints BeyondCX |
|
||||
| **Opciones evaluadas** | Usar inglés técnico, usar español parcial, compliance total |
|
||||
| **Decisión** | Compliance total con terminología de blueprints |
|
||||
| **Rationale** | Consistencia con documentos cliente, menos confusión |
|
||||
| **Trade-offs** | Labels más largos en algunos casos |
|
||||
| **Reversibilidad** | Alta - solo cambios de texto |
|
||||
|
||||
---
|
||||
|
||||
## TD-016: FCR Rate Calculation
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **Fecha** | 2026-01-19 |
|
||||
| **Contexto** | Blueprint FCR define "Primera Llamada" como éxito |
|
||||
| **Opciones evaluadas** | FIRST_CALL+RESOLVED, solo FIRST_CALL, custom logic |
|
||||
| **Decisión** | Solo FIRST_CALL cuenta como FCR success |
|
||||
| **Rationale** | Blueprint es explícito: "primer contacto por ese motivo" |
|
||||
| **Trade-offs** | Puede diferir de métricas legacy del cliente |
|
||||
| **Reversibilidad** | Alta - fórmula configurable |
|
||||
|
||||
---
|
||||
|
||||
## TD-017: RCA Sankey Visualization
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **Fecha** | 2026-01-19 |
|
||||
| **Contexto** | Visualizar causalidad Driver → Outcome → Churn |
|
||||
| **Opciones evaluadas** | Tree diagram, Sunburst, Sankey, Chord |
|
||||
| **Decisión** | Sankey diagram |
|
||||
| **Rationale** | Muestra flujo causal, ancho proporcional, muy visual para executives |
|
||||
| **Trade-offs** | Puede ser confuso con muchos nodos |
|
||||
| **Reversibilidad** | Alta - componente independiente |
|
||||
|
||||
---
|
||||
|
||||
## Decisiones Pendientes
|
||||
|
||||
| ID | Tema | Status |
|
||||
|----|------|--------|
|
||||
| TD-018 | DuckDB para analytics grandes | Pendiente |
|
||||
| TD-019 | Multi-idioma strategy | Pendiente (Fase 2) |
|
||||
| TD-020 | Campaign tracking implementation | Pendiente (Fase 2) |
|
||||
| TD-021 | Customer value analysis | Pendiente (Fase 2) |
|
||||
|
||||
---
|
||||
|
||||
**Última actualización**: 2026-01-19 (v2.1 Dashboard + Blueprint Compliance)
|
||||
Reference in New Issue
Block a user