BeyondCX_Insights/docs/QUICK_START.md

# QUICK_START.md

> Para que Claude Code (o cualquier dev) empiece rápido

---

## Para entender el proyecto (5 min)

### Paso 1: Lee PROJECT_CONTEXT.md (2 min)
```
docs/PROJECT_CONTEXT.md
```
Contiene: qué es, estado actual, stack, estructura, prohibiciones.

### Paso 2: Lee ARCHITECTURE.md (2 min)
```
docs/ARCHITECTURE.md
```
Contiene: diagrama de pipeline, módulos, flujo de datos.

### Paso 3: Escanea la estructura (1 min)
```
src/
├── transcription/     # Audio → JSON transcripts
├── features/          # Eventos determinísticos
├── compression/       # Reducción de tokens
├── inference/         # LLM → RCA labels
├── aggregation/       # Stats + RCA trees
├── pipeline/          # Orchestration
├── exports/           # JSON/Excel/PDF
└── models/            # CallAnalysis central
```

---

## Para ejecutar el pipeline

### Instalación
```bash
# Crear virtualenv
python -m venv venv
venv\Scripts\activate  # Windows
source venv/bin/activate  # Linux/Mac

# Instalar dependencias
pip install -r requirements.txt

# Configurar variables de entorno
cp .env.example .env
# Editar .env con tus API keys
```

### Ejecutar pipeline
```bash
# Con audio files
python cli.py run my_batch -i data/audio -o data/output

# Ver estado
python cli.py status my_batch

# Con opciones
python cli.py run my_batch --model gpt-4o --formats json,excel,pdf
```

---

## Para implementar un feature

### Paso 1: Identifica el módulo
| Si quieres... | Edita... |
|---------------|----------|
| Cambiar transcripción | `src/transcription/` |
| Detectar nuevos eventos | `src/features/event_detector.py` |
| Modificar compresión | `src/compression/compressor.py` |
| Cambiar prompt LLM | `src/inference/prompts.py` |
| Ajustar severidad | `src/aggregation/severity.py` |
| Añadir nuevo export | `src/exports/` |

### Paso 2: Lee el schema en DATA_CONTRACTS.md
```
docs/DATA_CONTRACTS.md
```

### Paso 3: Implementa siguiendo el patrón existente
```python
# Ejemplo: Añadir nuevo evento
# src/features/event_detector.py

class EventType(str, Enum):
    # ... existentes ...
    NEW_EVENT = "new_event"  # Añadir aquí

def _detect_new_event(self, transcript: Transcript) -> list[Event]:
    # Implementar detección
    pass
```

### Paso 4: Escribe tests
```bash
# Crear test
tests/unit/test_<module>.py

# Ejecutar
pytest tests/unit/test_<module>.py -v
```

### Paso 5: Actualiza documentación
- `CHANGELOG.md` - Log del cambio
- `DATA_CONTRACTS.md` - Si cambias schemas
- `TECHNICAL_DECISIONS.md` - Si tomas decisiones

---

## Para debugging

### Paso 1: Check TROUBLESHOOTING.md
```
docs/TROUBLESHOOTING.md
```

### Paso 2: Ejecutar módulo aislado
```python
# Test transcription solo
from src.transcription import AssemblyAITranscriber

transcriber = AssemblyAITranscriber(api_key="...")
result = transcriber.transcribe(Path("test.mp3"))
print(result)
```

### Paso 3: Logs verbosos
```bash
python cli.py run test_batch -v  # Verbose mode
```

### Paso 4: Si resuelves algo nuevo
Añádelo a `docs/TROUBLESHOOTING.md`

---

## Para validar cambios

### Paso 1: Tests
```bash
pytest tests/ -v
```

### Paso 2: Notebooks de validación
```
notebooks/01_transcription_validation.ipynb
notebooks/02_inference_validation.ipynb
notebooks/03_compression_validation.ipynb
notebooks/04_aggregation_validation.ipynb
notebooks/05_full_pipeline_test.ipynb
```

### Paso 3: Actualizar BENCHMARKS.md
Si afecta performance/cost:
```
docs/BENCHMARKS.md
```

---

## Archivos críticos (NO modificar sin revisión)

| Archivo | Por qué |
|---------|---------|
| `config/rca_taxonomy.yaml` | Define todos los drivers |
| `src/models/call_analysis.py` | Contrato central |
| `src/inference/prompts.py` | Prompt afecta calidad |
| `src/aggregation/severity.py` | Fórmula de priorización |

---

## Comandos útiles

```bash
# Ver estructura del proyecto
tree -L 2 src/

# Buscar en código
grep -r "RCALabel" src/

# Ver tests de un módulo
pytest tests/unit/test_inference.py -v

# Coverage
pytest --cov=src tests/

# Type checking (si hay mypy)
mypy src/
```

---

## Principios clave (siempre recordar)

1. **OBSERVED vs INFERRED** - Todo dato clasificado
2. **Evidence obligatoria** - Sin evidence = driver rechazado
3. **Taxonomía cerrada** - Solo códigos del enum
4. **Traceability** - Versiones en todo output
5. **No over-engineering** - Solo lo que se pide

---

## Preguntas frecuentes

### ¿Cómo añado un nuevo driver RCA?
1. Editar `config/rca_taxonomy.yaml`
2. Actualizar `src/inference/prompts.py`
3. Correr tests
4. Documentar en CHANGELOG.md

### ¿Cómo cambio el LLM?
1. Editar `cli.py run --model <model>`
2. O configurar en `src/inference/analyzer.py`

### ¿Cómo proceso más de 20k llamadas?
1. Dividir en batches
2. Usar resume automático
3. Considerar DuckDB para aggregation

### ¿Dónde están los costes?
`docs/BENCHMARKS.md` (pendiente de datos reales)

---

**Última actualización**: 2026-01-19