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

id	title	type	status	project	version	story_points	created_date	updated_date
EPIC-IAI-008	EPIC IA-008: Machine Learning y Analytics Avanzado	EPIC	Draft	inmobiliaria-analytics	1.0.0	89	2026-01-04	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 - Definicion del modulo
• ML-SERVICES-SPEC.yml - Especificacion completa
• PERFIL-ML-SPECIALIST.md - Perfil de agente

---

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