BeyondCX_Insights/docs/CHANGELOG.md

# CHANGELOG

> Registro de cambios del proyecto CXInsights

---

## [2.1.0] - 2026-01-19 - Streamlit Dashboard + Blueprint Compliance

### Added

#### Streamlit Dashboard (`dashboard/`)
- **Main Application** (`app.py`)
  - 8 navigation sections: Overview, Outcomes, Poor CX, FCR, Churn, Agent, Call Explorer, Export
  - Automatic batch detection and selection
  - Beyond brand header with logo and metadata

- **Brand Configuration** (`config.py`)
  - Beyond Brand Identity colors: Black #000000, Blue #6D84E3, Grey #B1B1B0
  - Custom CSS with Outfit font (Google Fonts)
  - McKinsey-style chart formatting

- **Data Loading** (`data_loader.py`)
  - `load_batch_data()` - Load summary and individual analyses
  - `calculate_kpis()` - Dashboard KPI calculations
  - `aggregate_drivers()` - Cross-analysis driver aggregation

- **Visualization Components** (`components.py`)
  - `render_kpi_cards()` - Metric cards with deltas
  - `render_outcome_chart()` - Horizontal bar chart
  - `render_driver_analysis()` - Driver frequency bars
  - `render_fcr_analysis()` - FCR 4-category view per blueprint
  - `render_churn_risk_analysis()` - Binary churn risk view per blueprint
  - `render_agent_performance()` - Talento Para Replicar / Oportunidades de Mejora
  - `render_rca_sankey()` - RCA flow: Driver → Outcome → Churn Risk
  - `render_driver_correlation_heatmap()` - Jaccard similarity co-occurrence
  - `render_driver_outcome_heatmap()` - Driver distribution by outcome
  - `render_outcome_deep_dive()` - Root causes, correlation, duration analysis
  - `render_call_explorer()` - Filterable call detail table

- **Export Functionality** (`exports.py`)
  - `create_excel_export()` - 8-sheet workbook with all analysis data
  - `create_executive_summary_html()` - Branded HTML report
  - `create_json_export()` - Raw JSON data package

- **Theme Configuration** (`.streamlit/config.toml`)
  - Light theme base
  - Brand primary color
  - Port 8510 configuration

### Changed

#### Blueprint Terminology Compliance
- **FCR Analysis**: Updated from simple distribution to 4 categories
  - Primera Llamada Sin Riesgo de Fuga
  - Primera Llamada Con Riesgo de Fuga
  - Rellamada Sin Riesgo de Fuga
  - Rellamada Con Riesgo de Fuga

- **Churn Risk Analysis**: Updated to binary categories
  - Sin Riesgo de Fuga (LOW, MEDIUM)
  - En Riesgo de Fuga (AT_RISK, HIGH)

- **Agent Performance**: Updated labels to blueprint terminology
  - Talento Para Replicar (positive skills)
  - Oportunidades de Mejora (improvement areas)

#### FCR Rate Calculation Fix
- **Before**: `FIRST_CALL + RESOLVED` counted as success
- **After**: Only `FIRST_CALL` counts as FCR success (per blueprint)
- Updated in `data_loader.py` and `exports.py`

### Fixed
- Plotly colorbar `titlefont` deprecated property → `title.font`
- Streamlit dark theme issue → Light theme in config.toml
- Port conflicts → Using port 8510

---

## [2.0.0] - 2026-01-19 - Blueprint Alignment

### Added

#### New Analysis Dimensions (High Priority Gaps)
- **FCR Detection Module**
  - `FCRStatus` enum: `FIRST_CALL`, `REPEAT_CALL`, `UNKNOWN`
  - `fcr_status` field in `CallAnalysis`
  - `fcr_failure_drivers` field for tracking repeat call causes

- **Churn Risk Classification**
  - `ChurnRisk` enum: `NO_RISK`, `AT_RISK`, `UNKNOWN`
  - `churn_risk` field in `CallAnalysis`
  - `churn_risk_drivers` field for churn indicators

- **Agent Skill Assessment**
  - `AgentClassification` enum: `GOOD_PERFORMER`, `NEEDS_IMPROVEMENT`, `MIXED`, `UNKNOWN`
  - `AgentSkillIndicator` model with skill_code, skill_type, evidence, coaching recommendations
  - `agent_positive_skills` and `agent_improvement_areas` fields in `CallAnalysis`

- **Enhanced RCALabel Structure**
  - `DriverOrigin` enum: `AGENT`, `CUSTOMER`, `COMPANY`, `PROCESS`, `UNKNOWN`
  - `origin` field in `RCALabel` for responsibility attribution
  - `corrective_action` field for actionable recommendations
  - `replicable_practice` field for positive behaviors to replicate

#### New Taxonomy Categories
- `churn_risk` drivers: PRICE_DISSATISFACTION, SERVICE_QUALITY_ISSUES, REPEATED_PROBLEMS, COMPETITOR_MENTION, CONTRACT_ISSUES, BILLING_PROBLEMS
- `fcr_failure` drivers: INCOMPLETE_RESOLUTION, PENDING_ACTION_REQUIRED, MISSING_INFORMATION, UNCLEAR_NEXT_STEPS, SYSTEM_LIMITATIONS, PROMISED_CALLBACK
- `agent_skills.positive`: EFFECTIVE_CLOSING, GOOD_RAPPORT, OBJECTION_MASTERY, PRODUCT_KNOWLEDGE, ACTIVE_LISTENING, EMPATHY_SHOWN, SOLUTION_ORIENTED, CLEAR_COMMUNICATION
- `agent_skills.improvement_needed`: POOR_CLOSING, MISSED_OPPORTUNITIES, OBJECTION_FAILURES, KNOWLEDGE_GAPS, PASSIVE_LISTENING, LOW_EMPATHY, PROBLEM_FOCUSED, UNCLEAR_COMMUNICATION

#### New Files
- `config/prompts/call_analysis/v2.0/system.txt` - System prompt for v2.0
- `config/prompts/call_analysis/v2.0/user.txt` - User prompt with all taxonomy sections
- `config/prompts/call_analysis/v2.0/schema.json` - JSON schema for v2.0 response
- `docs/GAP_ANALYSIS.md` - Comprehensive gap analysis vs BeyondCX blueprints

### Changed

#### Models (`src/models/call_analysis.py`)
- Added 4 new enums: `FCRStatus`, `ChurnRisk`, `AgentClassification`, `DriverOrigin`
- Extended `RCALabel` with `origin`, `corrective_action`, `replicable_practice` fields
- Added `AgentSkillIndicator` model
- Extended `CallAnalysis` with 7 new fields

#### Inference (`src/inference/`)
- `prompt_manager.py`: Added `TaxonomyTexts` dataclass, updated `load_taxonomy_for_prompt()` to return all sections
- `analyzer.py`: Updated to parse all v2.0 fields, added `_parse_agent_skills()` method
- Default `prompt_version` changed from `v1.0` to `v2.0`

#### Aggregation (`src/aggregation/`)
- `models.py`: Added `DriverCategory` type, extended `RCATree` and `BatchAggregation` with v2.0 fields
- `statistics.py`: Updated `calculate_frequencies()` to return dict with 6 categories, added FCR/churn/agent metrics to `calculate_outcome_rates()`

#### Configuration
- `config/prompts/versions.yaml`: Changed active version from v1.0 to v2.0
- `config/rca_taxonomy.yaml`: Added 3 new top-level sections

### Tests Updated
- `tests/unit/test_inference.py`: Updated active version assertion to v2.0
- `tests/unit/test_aggregation.py`: Updated sample_analyses fixture with v2.0 fields, updated frequency tests

### Documentation
- Updated `docs/PROJECT_CONTEXT.md` with v2.0 status
- Updated `docs/TODO.md` with completed and new tasks
- Created `docs/CHANGELOG.md` (this file)

---

## [1.0.0] - 2026-01-19 - MVP Complete

### Added
- Complete pipeline: transcription → features → inference → aggregation → exports
- CP1-CP8 checkpoints completed
- AssemblyAI transcription with diarization
- GPT-4o-mini inference with JSON strict mode
- Transcript compression (>60% token reduction)
- RCA tree building with severity scoring
- Export formats: JSON, Excel, PDF/HTML
- CLI interface with resume support
- Comprehensive test suite

### Features
- `CallAnalysis` model with observed vs inferred separation
- `RCALabel` with mandatory `evidence_spans[]`
- Versioned prompts system
- Checkpoint/resume mechanism
- Batch processing with rate limiting

---

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