BeyondCX_Insights/PRODUCT_SPEC.md

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)

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

• Transcripción batch (AssemblyAI).
• Inference analytics con taxonomía fija.
• Construcción de RCA trees en JSON.
• Exportación a Excel y PDF.
• 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.