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
213
README.md
Normal file
213
README.md
Normal file
@@ -0,0 +1,213 @@
|
||||
# CXInsights
|
||||
|
||||
Pipeline automatizado para análisis de conversaciones de contact center en español. Identifica causas raíz de ventas perdidas y mala experiencia de cliente (CX) mediante análisis de transcripciones de llamadas.
|
||||
|
||||
## Propuesta de Valor
|
||||
|
||||
CXInsights identifica, de forma automatizada y basada en evidencia:
|
||||
|
||||
- **Por qué se pierden oportunidades de venta** durante las llamadas
|
||||
- **Por qué los clientes reciben una mala experiencia**
|
||||
- **Cuáles son las causas más frecuentes** y prioritarias
|
||||
|
||||
### Responde a preguntas clave:
|
||||
|
||||
- ¿En qué punto del flujo se pierde la venta?
|
||||
- ¿Qué comportamientos o procesos generan frustración?
|
||||
- ¿Cuáles son las causas raíz de mala CX o churn potencial?
|
||||
|
||||
## Instalación
|
||||
|
||||
### Requisitos previos
|
||||
|
||||
- Python 3.11+
|
||||
- ffmpeg (opcional, para validación de audio)
|
||||
- Cuentas en AssemblyAI y OpenAI
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
# 1. Clonar repositorio
|
||||
git clone https://github.com/tu-org/cxinsights.git
|
||||
cd cxinsights
|
||||
|
||||
# 2. Crear entorno virtual
|
||||
python -m venv .venv
|
||||
|
||||
# Windows
|
||||
.venv\Scripts\activate
|
||||
|
||||
# Linux/Mac
|
||||
source .venv/bin/activate
|
||||
|
||||
# 3. Instalar dependencias
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 4. (Opcional) Instalar soporte PII
|
||||
pip install -r requirements-pii.txt
|
||||
python -m spacy download es_core_news_md
|
||||
|
||||
# 5. (Opcional) Instalar dependencias de desarrollo
|
||||
pip install -r requirements-dev.txt
|
||||
```
|
||||
|
||||
## Configuración
|
||||
|
||||
### 1. Variables de entorno
|
||||
|
||||
```bash
|
||||
# Copiar template
|
||||
cp .env.example .env
|
||||
|
||||
# Editar con tus API keys
|
||||
# Windows: notepad .env
|
||||
# Linux/Mac: nano .env
|
||||
```
|
||||
|
||||
Variables requeridas:
|
||||
|
||||
| Variable | Descripción |
|
||||
|----------|-------------|
|
||||
| `ASSEMBLYAI_API_KEY` | API key de AssemblyAI para transcripción |
|
||||
| `OPENAI_API_KEY` | API key de OpenAI para análisis LLM |
|
||||
|
||||
### 2. Configuración de throttling
|
||||
|
||||
Ajusta según tu tier en las APIs:
|
||||
|
||||
```bash
|
||||
# .env
|
||||
MAX_CONCURRENT_TRANSCRIPTIONS=30 # AssemblyAI
|
||||
LLM_REQUESTS_PER_MINUTE=200 # OpenAI (Tier 1: 200, Tier 2: 2000)
|
||||
```
|
||||
|
||||
## Flujo de Ejecución
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ PIPELINE CXInsights │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. VALIDACIÓN Usuario carga audios → Validación + estimación coste │
|
||||
│ ↓ │
|
||||
│ 2. TRANSCRIPCIÓN Audio → Transcript (AssemblyAI) │
|
||||
│ ↓ │
|
||||
│ 3. FEATURES Transcript → Eventos + Métricas (determinístico) │
|
||||
│ ↓ │
|
||||
│ 4. COMPRESIÓN Transcript → CompressedTranscript (reducción >60%) │
|
||||
│ ↓ │
|
||||
│ 5. INFERENCE CompressedTranscript → Labels (LLM) │
|
||||
│ ↓ │
|
||||
│ 6. VALIDACIÓN Labels → Quality Gate (evidence requerido) │
|
||||
│ ↓ │
|
||||
│ 7. AGREGACIÓN Labels → RCA Trees (estadístico) │
|
||||
│ ↓ │
|
||||
│ 8. OUTPUTS RCA Trees → PDF + Excel + JSON │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Uso
|
||||
|
||||
### Estimación de costes
|
||||
|
||||
```bash
|
||||
python -m cxinsights.pipeline.cli estimate --input ./data/raw/audio/mi_batch
|
||||
```
|
||||
|
||||
### Ejecutar pipeline completo
|
||||
|
||||
```bash
|
||||
python -m cxinsights.pipeline.cli run \
|
||||
--input ./data/raw/audio/mi_batch \
|
||||
--batch-id mi_batch
|
||||
```
|
||||
|
||||
### Ejecutar por stages
|
||||
|
||||
```bash
|
||||
# Solo transcripción
|
||||
python -m cxinsights.pipeline.cli run --batch-id mi_batch --stages transcription
|
||||
|
||||
# Solo inferencia (requiere transcripts existentes)
|
||||
python -m cxinsights.pipeline.cli run --batch-id mi_batch --stages inference
|
||||
```
|
||||
|
||||
### Resumir desde checkpoint
|
||||
|
||||
```bash
|
||||
python -m cxinsights.pipeline.cli resume --batch-id mi_batch
|
||||
```
|
||||
|
||||
## Inputs Esperados
|
||||
|
||||
### Formato de audio
|
||||
|
||||
- MP3, WAV, M4A
|
||||
- Duración típica: 6-8 minutos (AHT)
|
||||
|
||||
### Naming convention
|
||||
|
||||
```
|
||||
{call_id}_{YYYYMMDD}_{queue}.mp3
|
||||
```
|
||||
|
||||
Ejemplo: `CALL001_20240115_ventas-movil.mp3`
|
||||
|
||||
### Metadata opcional (CSV)
|
||||
|
||||
```csv
|
||||
call_id,date,queue,duration
|
||||
CALL001,2024-01-15,ventas-movil,420
|
||||
```
|
||||
|
||||
## Outputs
|
||||
|
||||
| Archivo | Descripción |
|
||||
|---------|-------------|
|
||||
| `transcripts.json` | Transcripciones con diarización |
|
||||
| `call_labels.json` | Etiquetas RCA por llamada con evidencias |
|
||||
| `rca_trees.json` | Árboles de causas raíz |
|
||||
| `executive_summary.pdf` | Reporte ejecutivo (2-3 páginas) |
|
||||
| `raw_analytics.xlsx` | Dataset completo para exploración |
|
||||
|
||||
## Estructura del Proyecto
|
||||
|
||||
```
|
||||
cxinsights/
|
||||
├── src/
|
||||
│ ├── transcription/ # STT (AssemblyAI)
|
||||
│ ├── features/ # Extracción determinística
|
||||
│ ├── inference/ # Análisis LLM
|
||||
│ ├── validation/ # Quality gate
|
||||
│ ├── aggregation/ # RCA trees
|
||||
│ ├── visualization/ # Exports
|
||||
│ └── pipeline/ # Orquestación
|
||||
├── config/
|
||||
│ ├── rca_taxonomy.yaml # Taxonomía frozen
|
||||
│ └── settings.yaml # Configuración
|
||||
├── data/ # Datos (gitignored)
|
||||
├── tests/ # Tests
|
||||
└── notebooks/ # Validación
|
||||
```
|
||||
|
||||
## Documentación
|
||||
|
||||
- [PRODUCT_SPEC.md](./PRODUCT_SPEC.md) - Especificación del producto
|
||||
- [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) - Arquitectura del pipeline
|
||||
- [docs/TECH_STACK.md](./docs/TECH_STACK.md) - Stack tecnológico
|
||||
- [docs/PROJECT_STRUCTURE.md](./docs/PROJECT_STRUCTURE.md) - Estructura detallada
|
||||
- [docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md) - Guía de deployment
|
||||
|
||||
## KPIs de Calidad
|
||||
|
||||
| KPI | Target |
|
||||
|-----|--------|
|
||||
| Transcripciones utilizables | 90% |
|
||||
| Confianza media RCA | ≥ 0.70 |
|
||||
| Tiempo (5K llamadas) | < 24h |
|
||||
| Coste por llamada | < €0.50 |
|
||||
|
||||
## Licencia
|
||||
|
||||
Propietario - BeyondCX.ai
|
||||
Reference in New Issue
Block a user