inmobiliaria-analytics/docs/01-fase-alcance-inicial/IAI-008-ml-analytics/README.md

---
id: "EPIC-IAI-008"
title: "EPIC IA-008: Machine Learning y Analytics Avanzado"
type: "EPIC"
status: "Draft"
project: "inmobiliaria-analytics"
version: "1.0.0"
story_points: 89
created_date: "2026-01-04"
updated_date: "2026-01-04"
---

# EPIC IAI-008: Machine Learning y Analytics Avanzado

---

## Resumen Ejecutivo

Este EPIC implementa el nucleo de inteligencia artificial de la plataforma: modelos de valuacion automatica (AVM), prediccion de tendencias de mercado, deteccion de oportunidades de inversion, indices de mercado y generacion de reportes profesionales con insights accionables.

---

## Objetivo

Proporcionar capacidades de ML que transformen datos inmobiliarios en inteligencia de mercado accionable:

1. **Valuacion Automatica (AVM)** - Estimar valor de propiedades con MAPE < 10%
2. **Predicciones** - Tiempo de venta, demanda por zona, tendencias
3. **Oportunidades** - Detectar propiedades subvaluadas y zonas emergentes
4. **Analisis ROI** - Calcular retornos proyectados para inversores
5. **Reportes** - Generar reportes profesionales personalizados

---

## Propuesta de Valor por Segmento

### Para Agentes Inmobiliarios

- Valuaciones instantaneas para clientes
- Reportes CMA profesionales automatizados
- Prediccion de tiempo de venta
- Market snapshots semanales

### Para Inversores

- Deteccion de propiedades subvaluadas
- Analisis ROI con escenarios
- Identificacion de zonas emergentes
- Alertas de oportunidades

### Para Desarrolladores

- Estudios de factibilidad automatizados
- Analisis de demanda por zona
- Benchmarking de costos
- Proyecciones de absorcion

---

## Modelos ML Core

```
+-------------------+     +-------------------+     +-------------------+
|   AVM-Core        |     |   DOM-Predictor   |     | Demand-Forecaster |
|   (Valuacion)     |     |   (Tiempo Venta)  |     |   (Demanda Zona)  |
+-------------------+     +-------------------+     +-------------------+
        |                         |                         |
        v                         v                         v
+---------------------------------------------------------------+
|                     Feature Engineering                        |
|   (Geo, Mercado, Propiedad, Temporales, NLP Embeddings)       |
+---------------------------------------------------------------+
        |                         |                         |
        v                         v                         v
+-------------------+     +-------------------+     +-------------------+
|   Deal-Finder     |     |   Zone-Spotter    |     |   ROI-Analyzer    |
|   (Subvaluadas)   |     |(Zonas Emergentes) |     |   (Inversion)     |
+-------------------+     +-------------------+     +-------------------+
```

---

## Stack Tecnologico

| Capa | Tecnologia | Uso |
|------|------------|-----|
| ML Framework | XGBoost, LightGBM, Prophet | Modelos predictivos |
| Data | pandas, polars, geopandas | Procesamiento |
| NLP | spaCy, sentence-transformers | Analisis texto |
| API | FastAPI, Pydantic | Serving |
| MLOps | MLflow, DVC | Versionamiento |
| Cache | Redis | Predicciones frecuentes |
| Vectors | pgvector | Embeddings |

---

## Arquitectura de Alto Nivel

```
                    +------------------+
                    |   API Gateway    |
                    +--------+---------+
                             |
           +-----------------+-----------------+
           |                                   |
+----------v----------+           +-----------v-----------+
|    ML API Service   |           |   Report Generator    |
|     (FastAPI)       |           |      (PDF/HTML)       |
+----------+----------+           +-----------+-----------+
           |                                  |
           |       +---------------+          |
           +------>|   ML Models   |<---------+
                   |   (MLflow)    |
                   +-------+-------+
                           |
                   +-------v-------+
                   |  Feature Store|
                   |   (Redis)     |
                   +-------+-------+
                           |
           +---------------+---------------+
           |                               |
+----------v----------+         +----------v----------+
|    PostgreSQL       |         |    pgvector         |
|  (Datos Mercado)    |         |   (Embeddings)      |
+---------------------+         +---------------------+
```

---

## Desglose por Fase

### Fase 1: MVP (4-6 semanas)

| Tarea | SP | Entregable |
|-------|----|------------|
| Setup MLflow + FastAPI | 3 | Infraestructura base |
| Feature engineering pipeline | 5 | Pipeline de features |
| Modelo AVM (XGBoost) | 8 | Valuacion basica |
| API `/valuation/predict` | 3 | Endpoint de prediccion |
| Dashboard tendencias | 5 | Visualizacion basica |
| Reporte CMA basico | 5 | PDF generado |

**Total:** 29 SP

### Fase 2: Predicciones (4-6 semanas)

| Tarea | SP | Entregable |
|-------|----|------------|
| TimeToSell model | 8 | Prediccion dias |
| Demand forecaster | 5 | Prediccion demanda |
| Detector subvaluadas | 5 | Deal-Finder |
| Sistema de alertas | 5 | Email + push |

**Total:** 23 SP

### Fase 3: Analisis Avanzado (4-6 semanas)

| Tarea | SP | Entregable |
|-------|----|------------|
| Indices de mercado | 5 | IPV, IAV, IAM, IRI |
| Zonas emergentes | 8 | Zone-Spotter |
| Analisis ROI | 8 | Investment-Analyzer |
| Reportes inversores | 5 | PDF completo |

**Total:** 26 SP

### Fase 4: NLP + Enterprise (4-6 semanas)

| Tarea | SP | Entregable |
|-------|----|------------|
| NLP pipeline | 5 | Extraccion amenidades |
| Quality scoring | 3 | Score de listings |
| Multi-tenant models | 5 | Aislamiento |
| White-label reports | 5 | Branding custom |

**Total:** 18 SP

---

## Metricas de Exito

### Modelo

| Metrica | Objetivo | Medicion |
|---------|----------|----------|
| AVM MAPE | < 10% | vs precio venta real |
| AVM R2 | >= 0.85 | Cross-validation |
| Time-to-sell MAPE | < 25% | vs dias reales |
| Demand accuracy | >= 70% | Directional |

### Negocio

| Metrica | Objetivo |
|---------|----------|
| Adopcion ML features | 70% MAU |
| Reportes generados | > 100/mes (enterprise) |
| Conversion oportunidades | 30% investigadas |
| NPS ML features | >= 40 |

### Tecnico

| Metrica | Objetivo |
|---------|----------|
| Latencia prediccion | p95 < 500ms |
| Uptime | 99.5% |
| Model freshness | Re-train mensual |

---

## Riesgos y Mitigaciones

| Riesgo | Prob | Impacto | Mitigacion |
|--------|------|---------|------------|
| Datos insuficientes | Alta | Alto | Scraping agresivo, datos sinteticos |
| Accuracy baja inicial | Media | Alto | Feature engineering, ensemble |
| Latencia alta | Media | Medio | Caching agresivo, batch |
| Model drift | Alta | Medio | Monitoreo continuo |
| Costos compute | Media | Bajo | Optimizacion, spot instances |

---

## Criterios de Aceptacion

- [ ] AVM predice con MAPE < 10% en test set
- [ ] API responde < 500ms p95
- [ ] Reportes se generan correctamente
- [ ] Alertas se envian en tiempo real
- [ ] Dashboard muestra tendencias actualizadas
- [ ] Modelos versionados en MLflow
- [ ] Tests de integracion pasan

---

## Documentacion Relacionada

- [IA-008-ML-ANALYTICS.md](../../02-definicion-modulos/IA-008-ML-ANALYTICS.md) - Definicion del modulo
- [ML-SERVICES-SPEC.yml](/shared/knowledge-base/projects/inmobiliaria-analytics/ML-SERVICES-SPEC.yml) - Especificacion completa
- [PERFIL-ML-SPECIALIST.md](/orchestration/agents/perfiles/PERFIL-ML-SPECIALIST.md) - Perfil de agente

---

**EPIC Owner:** Tech Lead / ML Lead
**Fecha creacion:** 2026-01-04
**Estado:** Draft