# 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.