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
206
PRODUCT_SPEC.md
Normal file
206
PRODUCT_SPEC.md
Normal file
@@ -0,0 +1,206 @@
|
||||
# PRODUCT_SPEC.md — CXInsights
|
||||
|
||||
## 1. Propuesta de Valor
|
||||
|
||||
### ¿Qué problema resuelve?
|
||||
|
||||
CXInsights identifica, de forma automatizada y basada en evidencia, **por qué se pierden oportunidades de venta** durante las llamadas y **por qué los clientes reciben una mala experiencia**, analizando conversaciones reales de contact center en español.
|
||||
|
||||
El producto responde a preguntas clave como:
|
||||
|
||||
- ¿En qué punto del flujo se pierde la venta?
|
||||
- ¿Qué comportamientos o procesos generan frustración en el cliente?
|
||||
- ¿Cuáles son las causas más frecuentes y prioritarias de mala CX o churn potencial?
|
||||
|
||||
### ¿Para quién?
|
||||
|
||||
- **Uso interno de BeyondCX.ai** como herramienta analítica estándar.
|
||||
- **Clientes finales** (p. ej. Entelgy) como servicio de análisis batch de conversaciones.
|
||||
|
||||
### ¿Cómo se usa?
|
||||
|
||||
- **Interfaz principal**: CLI (línea de comandos).
|
||||
- **Outputs**: artefactos estáticos (PDF, Excel, JSON).
|
||||
- **Dashboard interactivo**: fuera de alcance en Fase 1.
|
||||
|
||||
---
|
||||
|
||||
## 2. User Journey (Fase 1 – MVP)
|
||||
|
||||
```
|
||||
Usuario carga archivos de audio →
|
||||
Validación + estimación de coste (10–15 min) →
|
||||
Transcripción batch (≈ 1 día para 5,000 llamadas) →
|
||||
Inference analytics (≈ 1 día para 5,000 llamadas) →
|
||||
Entrega de outputs (PDF + Excel + JSON)
|
||||
```
|
||||
|
||||
### Condiciones del SLA (<24h para 5,000 llamadas)
|
||||
|
||||
- Duración media de llamada: 6–8 minutos.
|
||||
- Concurrencia STT configurada correctamente.
|
||||
- Uso de transcripciones comprimidas para inferencia (no transcript completo).
|
||||
- Ratio de reintentos < 2%.
|
||||
- Sin reprocesamientos humanos durante el batch.
|
||||
|
||||
---
|
||||
|
||||
## 3. Inputs Esperados
|
||||
|
||||
### Formato de audio soportado
|
||||
|
||||
| Formato | Extensión |
|
||||
|---------|-----------|
|
||||
| MP3 | `.mp3` |
|
||||
| WAV | `.wav` |
|
||||
| M4A | `.m4a` |
|
||||
|
||||
### Naming Convention de archivos
|
||||
|
||||
```
|
||||
{call_id}_{YYYYMMDD}_{queue}.mp3
|
||||
```
|
||||
|
||||
**Reglas:**
|
||||
|
||||
- `call_id`: identificador único global.
|
||||
- `YYYYMMDD`: fecha de la llamada.
|
||||
- `queue`: sin underscores (`_`). Usar `-` si es necesario.
|
||||
|
||||
Si el naming no cumple este formato, se debe proporcionar archivo CSV de metadata.
|
||||
|
||||
### Metadata opcional (CSV)
|
||||
|
||||
Campos esperados:
|
||||
|
||||
| Campo | Requerido |
|
||||
|-------|-----------|
|
||||
| `call_id` | Sí |
|
||||
| `date` | Sí |
|
||||
| `queue` | Sí |
|
||||
| `duration` | No |
|
||||
|
||||
El CSV prevalece sobre el nombre del archivo en caso de conflicto.
|
||||
|
||||
---
|
||||
|
||||
## 4. Outputs Garantizados
|
||||
|
||||
Para cada batch procesado, CXInsights entrega:
|
||||
|
||||
### Artefactos principales
|
||||
|
||||
| Archivo | Descripción |
|
||||
|---------|-------------|
|
||||
| `transcripts.json` | Transcripciones completas con speaker diarization y timestamps. |
|
||||
| `call_labels.json` | Etiquetas analíticas por llamada (RCA + CX) con: evidencias (fragmentos + timestamps), nivel de confianza, estado de procesamiento. |
|
||||
| `rca_trees.json` | Árboles jerárquicos de causas raíz (Lost Sales y Poor CX), construidos a partir de agregación estadística. |
|
||||
| `executive_summary.pdf` | Informe ejecutivo (2–3 páginas) con: principales causas, impacto relativo, oportunidades de mejora. |
|
||||
| `raw_analytics.xlsx` | Dataset completo para exploración y análisis adicional. |
|
||||
|
||||
### Estado por llamada
|
||||
|
||||
Cada llamada incluye un campo `status`:
|
||||
|
||||
| Status | Descripción |
|
||||
|--------|-------------|
|
||||
| `success` | Procesamiento completo |
|
||||
| `partial` | Procesamiento incompleto (algunas etiquetas faltantes) |
|
||||
| `failed` | Procesamiento fallido |
|
||||
|
||||
En caso de `partial` o `failed`, se incluye motivo (`LOW_AUDIO_QUALITY`, `LLM_PARSE_ERROR`, etc.).
|
||||
|
||||
---
|
||||
|
||||
## 5. Configuración de Usuario
|
||||
|
||||
### Archivo `.env` (mínimo requerido)
|
||||
|
||||
```bash
|
||||
ASSEMBLYAI_API_KEY=
|
||||
OPENAI_API_KEY=
|
||||
INPUT_FOLDER=
|
||||
OUTPUT_FOLDER=
|
||||
```
|
||||
|
||||
### Controles de coste y ejecución
|
||||
|
||||
| Variable | Descripción |
|
||||
|----------|-------------|
|
||||
| `BATCH_SIZE` | Número máximo de llamadas por ejecución. |
|
||||
| `MAX_AUDIO_MINUTES_PER_RUN` | Límite total de minutos de audio procesados por batch. |
|
||||
| `LLM_MAX_TOKENS_PER_CALL` | Límite de tokens usados por llamada en inferencia. |
|
||||
| `MAX_LLM_RETRIES` | Número máximo de reintentos por llamada. |
|
||||
|
||||
---
|
||||
|
||||
## 6. Taxonomía RCA (Frozen – Round 1)
|
||||
|
||||
La taxonomía de causas raíz está **congelada** para la Fase 1 y se aplica de forma consistente a todos los batches.
|
||||
|
||||
### Lost Sales
|
||||
|
||||
| Código | Descripción |
|
||||
|--------|-------------|
|
||||
| `NO_SAVE_OFFER` | No se ofreció retención al cliente |
|
||||
| `OBJECTION_NOT_HANDLED` | Objeción no manejada adecuadamente |
|
||||
| `PRICE_TOO_HIGH` | Cliente considera precio demasiado alto |
|
||||
| `NO_NEED` | Cliente no tiene necesidad del producto |
|
||||
| *(ver lista completa en documento de taxonomía)* | |
|
||||
|
||||
### Poor Customer Experience
|
||||
|
||||
| Código | Descripción |
|
||||
|--------|-------------|
|
||||
| `LONG_HOLD` | Tiempo de espera prolongado |
|
||||
| `MULTI_TRANSFER` | Múltiples transferencias |
|
||||
| `LOW_EMPATHY` | Falta de empatía del agente |
|
||||
| `ISSUE_NOT_RESOLVED` | Problema no resuelto |
|
||||
| *(ver lista completa en documento de taxonomía)* | |
|
||||
|
||||
### Canal controlado de emergentes
|
||||
|
||||
Se permite el uso de `OTHER_EMERGENT` con:
|
||||
|
||||
- etiqueta propuesta,
|
||||
- evidencia asociada.
|
||||
|
||||
Estas causas **no afectan** al árbol RCA principal en Fase 1 y se reportan por separado.
|
||||
|
||||
---
|
||||
|
||||
## 7. KPIs de Calidad del Producto
|
||||
|
||||
### KPIs principales
|
||||
|
||||
| KPI | Target | Medición |
|
||||
|-----|--------|----------|
|
||||
| **Calidad de transcripción** | 90% de transcripciones utilizables en español | Muestreo QA (manual o semi-automático) |
|
||||
| **Confianza media de RCA** | ≥ 0.70 | Confidence score auto-reportado por el modelo |
|
||||
| **Tiempo de procesamiento** | < 24h para 5,000 llamadas | Medición end-to-end |
|
||||
| **Coste por llamada** | < €0.50 | STT + inferencia (excluye costes humanos) |
|
||||
|
||||
---
|
||||
|
||||
## 8. MVP Scope (Fase 1)
|
||||
|
||||
### Incluido
|
||||
|
||||
- [x] Transcripción batch (AssemblyAI).
|
||||
- [x] Inference analytics con taxonomía fija.
|
||||
- [x] Construcción de RCA trees en JSON.
|
||||
- [x] Exportación a Excel y PDF.
|
||||
- [x] Ejecución vía CLI.
|
||||
|
||||
### Fuera de alcance
|
||||
|
||||
- [ ] Dashboard interactivo (Fase 1.5).
|
||||
- [ ] API REST (Fase 2).
|
||||
- [ ] Multi-idioma (Fase 2).
|
||||
- [ ] Análisis en tiempo real.
|
||||
|
||||
---
|
||||
|
||||
> **Nota:**
|
||||
> Este documento define el alcance funcional y las promesas del producto CXInsights para su Fase 1.
|
||||
> No se debe diseñar ni implementar código fuera de este alcance sin una revisión explícita del Product Spec.
|
||||
Reference in New Issue
Block a user