rckrdmrd/workspace-v1
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
workspace-v1/shared/knowledge-base/projects/inmobiliaria-analytics/ML-SERVICES-SPEC.yml
rckrdmrd cb4c0681d3 feat(workspace): Add new projects and update architecture 
New projects created:
- michangarrito (marketplace mobile)
- template-saas (SaaS template)
- clinica-dental (dental ERP)
- clinica-veterinaria (veterinary ERP)

Architecture updates:
- Move catalog from core/ to shared/
- Add MCP servers structure and templates
- Add git management scripts
- Update SUBREPOSITORIOS.md with 15 new repos
- Update .gitignore for new projects

Repository infrastructure:
- 4 main repositories
- 11 subrepositorios
- Gitea remotes configured

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-07 04:43:28 -06:00

1468 lines
44 KiB
YAML
Raw Permalink Blame History

# ============================================================================
# ESPECIFICACION: Servicios ML para Analytics Inmobiliario SaaS
# ============================================================================
# Fecha: 2026-01-04
# Version: 1.0.0
# Autor: ML-Specialist-Agent
# Dominio: Real Estate Analytics / Proptech
# Tipo: Documento de Especificacion Tecnica
# ============================================================================
metadata:
proyecto: inmobiliaria-analytics-saas
version: "1.0.0"
fecha_creacion: "2026-01-04"
autor: "ML-Specialist-Agent"
estado: "draft"
categoria: "ML/AI Services"
referencias:
- "PERFIL-ML-SPECIALIST.md"
- "SIMCO-ML.md"
- "trading-platform/apps/ml-engine (patron de referencia)"
# ============================================================================
# 1. MODELOS DE PREDICCION
# ============================================================================
modelos_prediccion:
# --------------------------------------------------------------------------
# 1.1 Prediccion de Precios de Propiedades (AVM - Automated Valuation Model)
# --------------------------------------------------------------------------
prediccion_precios:
nombre: "PropertyPricePredictor"
alias: "AVM-Core"
tipo: "regression"
descripcion: |
Modelo de valuacion automatica de propiedades basado en caracteristicas
fisicas, ubicacion, mercado y comparables cercanos.
features:
intrinsecas:
- nombre: "superficie_construida_m2"
tipo: float
importancia: "alta"
- nombre: "superficie_terreno_m2"
tipo: float
importancia: "alta"
- nombre: "num_recamaras"
tipo: int
importancia: "media"
- nombre: "num_banos"
tipo: float # Permite 1.5, 2.5 banos
importancia: "media"
- nombre: "num_estacionamientos"
tipo: int
importancia: "media"
- nombre: "antiguedad_anos"
tipo: int
importancia: "alta"
- nombre: "tipo_propiedad"
tipo: categorical # casa, depto, terreno, local, bodega
importancia: "alta"
- nombre: "estado_conservacion"
tipo: ordinal # 1-5 (malo a excelente)
importancia: "media"
- nombre: "tiene_alberca"
tipo: boolean
importancia: "baja"
- nombre: "tiene_jardin"
tipo: boolean
importancia: "baja"
- nombre: "nivel_piso"
tipo: int # Para departamentos
importancia: "media"
- nombre: "amenidades_count"
tipo: int
importancia: "media"
ubicacion:
- nombre: "latitud"
tipo: float
importancia: "alta"
- nombre: "longitud"
tipo: float
importancia: "alta"
- nombre: "codigo_postal"
tipo: categorical
importancia: "alta"
- nombre: "colonia_cluster_id"
tipo: int
importancia: "alta"
- nombre: "distancia_centro_m"
tipo: float
importancia: "media"
- nombre: "distancia_metro_m"
tipo: float
importancia: "media"
- nombre: "distancia_hospital_m"
tipo: float
importancia: "baja"
- nombre: "distancia_escuela_m"
tipo: float
importancia: "media"
- nombre: "indice_seguridad_zona"
tipo: float # 0-100
importancia: "alta"
- nombre: "nivel_socioeconomico_zona"
tipo: ordinal # A, B, C+, C, D+, D, E
importancia: "alta"
mercado:
- nombre: "precio_promedio_m2_zona"
tipo: float
importancia: "alta"
- nombre: "tendencia_precios_12m"
tipo: float # % cambio
importancia: "alta"
- nombre: "oferta_activa_zona"
tipo: int
importancia: "media"
- nombre: "absorcion_promedio_zona"
tipo: float # meses
importancia: "alta"
- nombre: "tasa_ocupacion_zona"
tipo: float
importancia: "media"
derivadas:
- nombre: "precio_m2_comparables"
tipo: float
derivacion: "Promedio ponderado de 5 propiedades similares cercanas"
- nombre: "desviacion_comparables"
tipo: float
derivacion: "Std dev de precios de comparables"
- nombre: "premium_ubicacion"
tipo: float
derivacion: "Factor de ajuste por ubicacion premium"
algoritmos_candidatos:
- nombre: "XGBoost"
pros: ["Mejor performance general", "Feature importance nativa", "Manejo de missing values"]
contras: ["Requiere tuning", "No extrapola bien"]
recomendado: true
- nombre: "LightGBM"
pros: ["Rapido entrenamiento", "Bajo uso memoria", "Bueno con categoricas"]
contras: ["Sensible a overfitting con pocos datos"]
recomendado: true
- nombre: "CatBoost"
pros: ["Excelente con categoricas", "Menos overfitting"]
contras: ["Mas lento que LightGBM"]
recomendado: false
- nombre: "Neural Network"
pros: ["Puede capturar patrones complejos"]
contras: ["Requiere mucho dato", "Caja negra", "Overengineering para este caso"]
recomendado: false
metricas_objetivo:
mape: "< 10%" # Mean Absolute Percentage Error
r2_score: ">= 0.85"
rmse: "< 15% del precio medio"
arquitectura:
ensemble: true
modelos:
- modelo_base: "XGBoost"
peso: 0.5
- modelo_base: "LightGBM"
peso: 0.3
- modelo_base: "ElasticNet" # Para regularizacion
peso: 0.2
api_endpoints:
- path: "/api/v1/valuation/predict"
method: "POST"
descripcion: "Valuacion de propiedad individual"
request_schema: "PropertyValuationRequest"
response_schema: "PropertyValuationResponse"
- path: "/api/v1/valuation/batch"
method: "POST"
descripcion: "Valuacion de multiples propiedades"
- path: "/api/v1/valuation/explain"
method: "POST"
descripcion: "Valuacion con explicabilidad (SHAP)"
# --------------------------------------------------------------------------
# 1.2 Prediccion de Tiempo de Venta (Days on Market)
# --------------------------------------------------------------------------
prediccion_tiempo_venta:
nombre: "TimeToSellPredictor"
alias: "DOM-Predictor"
tipo: "regression"
descripcion: |
Predice cuantos dias tardara una propiedad en venderse basado en
caracteristicas, precio y condiciones de mercado.
features:
propiedad:
- nombre: "precio_lista"
tipo: float
importancia: "alta"
- nombre: "precio_vs_mercado_ratio"
tipo: float
importancia: "critica"
descripcion: "Precio lista / Precio promedio zona"
- nombre: "tipo_propiedad"
tipo: categorical
importancia: "alta"
- nombre: "superficie_m2"
tipo: float
importancia: "media"
- nombre: "antiguedad_anos"
tipo: int
importancia: "media"
- nombre: "calidad_fotos"
tipo: ordinal # ML scoring de imagenes
importancia: "alta"
- nombre: "tiene_tour_virtual"
tipo: boolean
importancia: "media"
- nombre: "descripcion_calidad_score"
tipo: float # NLP score
importancia: "media"
mercado:
- nombre: "inventario_activo_zona"
tipo: int
importancia: "alta"
- nombre: "absorcion_mensual_zona"
tipo: float
importancia: "alta"
- nombre: "estacionalidad_mes"
tipo: int # 1-12
importancia: "media"
- nombre: "tendencia_demanda_zona"
tipo: float
importancia: "alta"
- nombre: "competencia_precio_similar"
tipo: int
importancia: "alta"
agente:
- nombre: "experiencia_agente_anos"
tipo: int
importancia: "media"
- nombre: "ventas_previas_agente"
tipo: int
importancia: "media"
- nombre: "calificacion_agente"
tipo: float
importancia: "media"
algoritmos_candidatos:
- nombre: "Survival Analysis (Cox PH)"
pros: ["Modela censura correctamente", "Interpretable"]
contras: ["Asume proporcionalidad"]
recomendado: true
- nombre: "Random Survival Forest"
pros: ["No asume proporcionalidad", "Captura no-linealidades"]
contras: ["Menos interpretable"]
recomendado: true
- nombre: "XGBoost Regressor"
pros: ["Simple", "Buen performance"]
contras: ["No maneja censura nativamente"]
recomendado: false
metricas_objetivo:
c_index: ">= 0.75" # Concordance Index
mape: "< 25%" # Dias predichos vs reales
output:
- dias_estimados: int
- intervalo_confianza: "[min_dias, max_dias]"
- probabilidad_venta_30_dias: float
- probabilidad_venta_60_dias: float
- probabilidad_venta_90_dias: float
# --------------------------------------------------------------------------
# 1.3 Prediccion de Demanda por Zona
# --------------------------------------------------------------------------
prediccion_demanda:
nombre: "ZoneDemandPredictor"
alias: "Demand-Forecaster"
tipo: "time_series_forecasting"
descripcion: |
Pronostico de demanda inmobiliaria por zona geografica
usando series temporales y factores externos.
features:
historicas:
- nombre: "busquedas_zona_30d"
tipo: int
importancia: "alta"
- nombre: "visitas_propiedades_30d"
tipo: int
importancia: "alta"
- nombre: "contactos_agentes_30d"
tipo: int
importancia: "alta"
- nombre: "ventas_cerradas_30d"
tipo: int
importancia: "critica"
- nombre: "precio_promedio_30d"
tipo: float
importancia: "alta"
externas:
- nombre: "tasa_interes_hipotecaria"
tipo: float
importancia: "alta"
- nombre: "indice_confianza_consumidor"
tipo: float
importancia: "media"
- nombre: "crecimiento_empleo_zona"
tipo: float
importancia: "media"
- nombre: "proyectos_infraestructura_cerca"
tipo: int
importancia: "alta"
- nombre: "indice_google_trends_zona"
tipo: float
importancia: "media"
estacionales:
- nombre: "mes_ano"
tipo: int
importancia: "alta"
- nombre: "trimestre"
tipo: int
importancia: "alta"
- nombre: "es_temporada_alta"
tipo: boolean
importancia: "media"
algoritmos_candidatos:
- nombre: "Prophet (Facebook)"
pros: ["Facil de usar", "Maneja estacionalidad", "Robusto a outliers"]
contras: ["No captura dependencias complejas"]
recomendado: true
- nombre: "LSTM"
pros: ["Captura patrones complejos", "Bueno con secuencias largas"]
contras: ["Requiere mucho dato", "Dificil de tunar"]
recomendado: false
- nombre: "XGBoost + Features temporales"
pros: ["Simple", "Permite features externas facilmente"]
contras: ["No modela dependencia temporal nativamente"]
recomendado: true
- nombre: "ARIMA/SARIMA"
pros: ["Clasico", "Interpretable"]
contras: ["No maneja features externas bien"]
recomendado: false
metricas_objetivo:
mape: "< 15%"
directional_accuracy: ">= 70%"
horizontes_prediccion:
- 7_dias
- 30_dias
- 90_dias
- 180_dias
# ============================================================================
# 2. ANALISIS DE OPORTUNIDADES
# ============================================================================
analisis_oportunidades:
# --------------------------------------------------------------------------
# 2.1 Deteccion de Propiedades Subvaluadas
# --------------------------------------------------------------------------
deteccion_subvaluadas:
nombre: "UndervaluedPropertyDetector"
alias: "Deal-Finder"
tipo: "anomaly_detection"
descripcion: |
Identifica propiedades cuyo precio de lista esta significativamente
por debajo del valor de mercado estimado.
metodologia:
paso_1: "Calcular valor de mercado con AVM"
paso_2: "Comparar precio_lista vs valor_mercado"
paso_3: "Calcular z-score de la diferencia"
paso_4: "Filtrar donde (valor_mercado - precio_lista) / valor_mercado > umbral"
paso_5: "Validar con comparables recientes"
umbrales:
oportunidad_moderada: ">= 10%" # Descuento sobre valor mercado
oportunidad_alta: ">= 15%"
oportunidad_excepcional: ">= 20%"
filtros_calidad:
- "Propiedad activa (no vendida)"
- "Antigedad publicacion < 30 dias"
- "Confianza AVM > 0.75"
- "No es foreclosure o venta forzada"
output_schema:
propiedad_id: string
precio_lista: float
valor_mercado_estimado: float
descuento_pct: float
nivel_oportunidad: "moderada | alta | excepcional"
confianza_estimacion: float
factores_descuento:
- factor: string
impacto: float
comparables_cercanos: list
alertas:
- tipo: "nueva_oportunidad"
trigger: "Nueva propiedad con descuento >= 15%"
canales: ["email", "push", "dashboard"]
- tipo: "cambio_precio"
trigger: "Propiedad existente baja precio >10%"
canales: ["email", "push"]
# --------------------------------------------------------------------------
# 2.2 Identificacion de Zonas Emergentes
# --------------------------------------------------------------------------
zonas_emergentes:
nombre: "EmergingZoneIdentifier"
alias: "Zone-Spotter"
tipo: "clustering + trend_analysis"
descripcion: |
Identifica zonas geograficas con potencial de apreciacion
basado en senales tempranas de desarrollo y demanda.
senales_tempranas:
infraestructura:
- "Nuevas lineas de metro/transporte"
- "Nuevos centros comerciales"
- "Nuevos hospitales/escuelas"
- "Mejoras viales"
peso: 0.25
desarrollo:
- "Permisos de construccion nuevos"
- "Proyectos residenciales anunciados"
- "Inversion inmobiliaria en zona"
peso: 0.20
demanda:
- "Incremento en busquedas >20% YoY"
- "Reduccion tiempo en mercado"
- "Incremento en precio m2 >10% YoY"
peso: 0.30
demograficos:
- "Crecimiento poblacional"
- "Mejora en nivel socioeconomico"
- "Reduccion tasa criminalidad"
peso: 0.15
sociales:
- "Nuevos restaurantes/cafes"
- "Apertura coworkings"
- "Eventos culturales"
peso: 0.10
algoritmo:
nombre: "Composite Score + Clustering"
pasos:
1: "Calcular score de cada senal normalizado 0-100"
2: "Weighted average de todas las senales"
3: "K-Means clustering de zonas por score"
4: "Identificar cluster con mejor momentum"
5: "Ranking dentro del cluster"
output:
zona_id: string
nombre_zona: string
score_emergente: float # 0-100
clasificacion: "early_stage | growing | maturing | saturated"
apreciacion_proyectada_12m: float # %
confianza: float
senales_activas: list
mapa_calor: geojson
# --------------------------------------------------------------------------
# 2.3 Analisis de ROI Potencial
# --------------------------------------------------------------------------
analisis_roi:
nombre: "ROIAnalyzer"
alias: "Investment-Analyzer"
tipo: "financial_modeling + ml"
descripcion: |
Calcula el retorno de inversion proyectado para propiedades
considerando diferentes estrategias (renta, flip, desarrollo).
estrategias:
buy_and_hold:
descripcion: "Comprar y rentar a largo plazo"
metricas:
- cap_rate
- cash_on_cash_return
- noi
- dscr
flip:
descripcion: "Comprar, remodelar y vender"
metricas:
- roi_bruto
- roi_neto
- marge_ganancia
- tiempo_proyecto
desarrollo:
descripcion: "Comprar terreno y construir"
metricas:
- irr
- npv
- payback_period
- profit_margin
inputs_requeridos:
propiedad:
- precio_compra
- superficie_m2
- estado_actual
- ubicacion
financiamiento:
- enganche_pct
- tasa_interes
- plazo_anos
operacion:
- renta_estimada_mensual # ML prediction
- gastos_mantenimiento_pct
- tasa_vacancia
- impuestos_anuales
mercado:
- apreciacion_proyectada_anual
- inflacion_proyectada
ml_components:
prediccion_renta:
modelo: "RentPredictor"
tipo: "regression"
features: ["tipo", "ubicacion", "superficie", "amenidades"]
metricas_objetivo:
mape: "< 12%"
prediccion_apreciacion:
modelo: "AppreciationForecaster"
tipo: "time_series"
features: ["zona", "historico_precios", "factores_externos"]
metricas_objetivo:
mape: "< 15%"
prediccion_vacancia:
modelo: "VacancyPredictor"
tipo: "classification"
features: ["tipo", "ubicacion", "precio_renta", "competencia"]
metricas_objetivo:
accuracy: ">= 0.80"
output:
estrategia: string
roi_proyectado_1y: float
roi_proyectado_3y: float
roi_proyectado_5y: float
cash_flow_mensual: float
punto_equilibrio_meses: int
riesgo_nivel: "bajo | medio | alto"
sensibilidad_analisis:
- escenario: "optimista"
roi: float
- escenario: "base"
roi: float
- escenario: "pesimista"
roi: float
# ============================================================================
# 3. ANALISIS DE MERCADO
# ============================================================================
analisis_mercado:
# --------------------------------------------------------------------------
# 3.1 Tendencias de Precios por Zona/Colonia
# --------------------------------------------------------------------------
tendencias_precios:
nombre: "PriceTrendAnalyzer"
alias: "Market-Pulse"
tipo: "time_series_analysis"
descripcion: |
Analiza y visualiza tendencias de precios historicas y proyectadas
por zona geografica, tipo de propiedad y segmento.
agregaciones:
temporal:
- diario
- semanal
- mensual
- trimestral
- anual
geografica:
- pais
- estado
- ciudad
- zona
- colonia
- codigo_postal
propiedad:
- tipo_propiedad
- rango_precio
- superficie_rango
- antiguedad_rango
metricas_calculadas:
- precio_promedio_m2
- precio_mediana_m2
- precio_percentil_25
- precio_percentil_75
- variacion_mensual_pct
- variacion_anual_pct
- volatilidad_30d
- tendencia: "alcista | bajista | lateral"
- fuerza_tendencia: float # 0-100
visualizaciones:
- tipo: "line_chart"
uso: "Evolucion temporal de precios"
- tipo: "heatmap"
uso: "Comparativa geografica"
- tipo: "box_plot"
uso: "Distribucion de precios"
- tipo: "scatter_geo"
uso: "Mapa de precios por ubicacion"
# --------------------------------------------------------------------------
# 3.2 Analisis Comparativo de Propiedades (Comps)
# --------------------------------------------------------------------------
analisis_comparativo:
nombre: "PropertyComparator"
alias: "Comp-Analyzer"
tipo: "similarity_search + statistics"
descripcion: |
Encuentra y analiza propiedades comparables para valuacion
y posicionamiento de mercado.
criterios_similitud:
geograficos:
- radio_km: [0.5, 1, 2, 5]
- misma_colonia: boolean
- mismo_codigo_postal: boolean
fisicos:
- tipo_propiedad: "exacto"
- superficie_m2: "+/- 20%"
- recamaras: "+/- 1"
- banos: "+/- 1"
- antiguedad: "+/- 10 anos"
temporales:
- vendidas_ultimos_meses: [3, 6, 12]
- activas_actualmente: boolean
algoritmo_similitud:
tipo: "weighted_euclidean_distance"
features_numericas:
- superficie_m2
- num_recamaras
- num_banos
- antiguedad
- latitud
- longitud
features_categoricas:
- tipo_propiedad
- estado_conservacion
normalizacion: "min-max"
pesos:
superficie_m2: 0.25
ubicacion: 0.30
tipo: 0.20
caracteristicas: 0.15
antiguedad: 0.10
output:
propiedad_objetivo: object
comparables:
- propiedad: object
similitud_score: float
distancia_km: float
diferencia_precio_pct: float
fecha_venta: date
dias_en_mercado: int
estadisticas:
precio_promedio_comps: float
precio_mediana_comps: float
precio_min: float
precio_max: float
precio_m2_promedio: float
recomendacion_precio:
valor_sugerido: float
rango_min: float
rango_max: float
confianza: float
# --------------------------------------------------------------------------
# 3.3 Indices de Mercado
# --------------------------------------------------------------------------
indices_mercado:
nombre: "MarketIndexCalculator"
alias: "Index-Engine"
tipo: "statistical_aggregation"
descripcion: |
Calcula indices estandarizados para medir salud y dinamica
del mercado inmobiliario.
indices:
indice_precios:
nombre: "IPV (Indice de Precios de Vivienda)"
metodologia: "Case-Shiller repeat-sales"
base: 100
fecha_base: "2020-01-01"
frecuencia: "mensual"
indice_accesibilidad:
nombre: "IAV (Indice de Accesibilidad a Vivienda)"
formula: "(Ingreso_medio_hogar * 12) / Precio_promedio_vivienda"
interpretacion: |
< 3: Muy accesible
3-5: Accesible
5-7: Moderadamente accesible
> 7: Poco accesible
indice_absorcion:
nombre: "Meses de Inventario"
formula: "Inventario_activo / Ventas_mensuales_promedio"
interpretacion: |
< 4: Mercado de vendedores (alta demanda)
4-6: Mercado equilibrado
> 6: Mercado de compradores (baja demanda)
indice_actividad:
nombre: "IAM (Indice de Actividad de Mercado)"
componentes:
- nuevos_listings: peso 0.25
- ventas_cerradas: peso 0.30
- visitas_propiedades: peso 0.20
- dias_en_mercado_inverso: peso 0.25
escala: 0-100
indice_inversion:
nombre: "IRI (Indice de Rendimiento de Inversion)"
componentes:
- cap_rate_promedio: peso 0.35
- apreciacion_anual: peso 0.35
- liquidez_mercado: peso 0.15
- riesgo_inverso: peso 0.15
escala: 0-100
dashboards:
executive_summary:
- indice_precios_trend
- indice_accesibilidad_actual
- indice_absorcion_actual
- mapa_calor_actividad
investor_view:
- indice_inversion_por_zona
- top_zonas_roi
- alertas_oportunidad
agent_view:
- indice_actividad_zona
- tendencia_precios_local
- competencia_analisis
# ============================================================================
# 4. REPORTES PROFESIONALES
# ============================================================================
reportes_profesionales:
# --------------------------------------------------------------------------
# 4.1 Reportes para Agentes Inmobiliarios
# --------------------------------------------------------------------------
reportes_agentes:
tipos:
cma_report:
nombre: "Comparative Market Analysis (CMA)"
descripcion: "Reporte de valuacion para clientes vendedores"
secciones:
- resumen_ejecutivo
- informacion_propiedad
- analisis_comparables
- ajustes_precio
- precio_recomendado
- condiciones_mercado
- estrategia_venta
formato: ["PDF", "HTML", "PowerPoint"]
personalizacion:
- logo_inmobiliaria
- datos_agente
- branding
buyer_presentation:
nombre: "Buyer Property Report"
descripcion: "Reporte de propiedad para compradores"
secciones:
- resumen_propiedad
- analisis_precio
- comparativo_mercado
- proyeccion_apreciacion
- analisis_vecindario
- pros_contras
- recomendacion
market_snapshot:
nombre: "Market Snapshot"
descripcion: "Resumen rapido de mercado local"
secciones:
- indicadores_clave
- tendencia_precios
- inventario_activo
- ventas_recientes
- prediccion_corto_plazo
frecuencia: "semanal"
listing_performance:
nombre: "Listing Performance Report"
descripcion: "Performance de propiedades activas del agente"
secciones:
- listings_activos
- vistas_por_propiedad
- contactos_recibidos
- comparativa_mercado
- recomendaciones_optimizacion
# --------------------------------------------------------------------------
# 4.2 Reportes para Inversores
# --------------------------------------------------------------------------
reportes_inversores:
tipos:
investment_analysis:
nombre: "Investment Analysis Report"
descripcion: "Analisis completo de inversion inmobiliaria"
secciones:
- resumen_ejecutivo
- descripcion_propiedad
- analisis_mercado_local
- proyecciones_financieras:
- flujo_caja_5_anos
- escenarios_sensibilidad
- roi_proyectado
- cap_rate
- cash_on_cash
- analisis_riesgo
- comparativa_alternativas
- recomendacion
portfolio_report:
nombre: "Portfolio Performance Report"
descripcion: "Desempeno de portafolio de propiedades"
secciones:
- resumen_portafolio
- valor_actual_total
- ingresos_por_renta
- gastos_operativos
- roi_por_propiedad
- diversificacion_geografica
- diversificacion_tipo
- benchmark_mercado
- rebalanceo_sugerido
opportunity_alert:
nombre: "Investment Opportunity Alert"
descripcion: "Alerta de oportunidad de inversion"
secciones:
- propiedad_destacada
- por_que_oportunidad
- analisis_rapido
- comparables
- accion_sugerida
- tiempo_limite
market_outlook:
nombre: "Market Outlook Report"
descripcion: "Perspectivas de mercado a futuro"
secciones:
- tendencias_macro
- prediccion_precios
- zonas_emergentes
- riesgos_identificados
- oportunidades
- recomendaciones_estrategicas
frecuencia: "trimestral"
# --------------------------------------------------------------------------
# 4.3 Reportes para Desarrolladores
# --------------------------------------------------------------------------
reportes_desarrolladores:
tipos:
feasibility_study:
nombre: "Feasibility Study Report"
descripcion: "Estudio de factibilidad para desarrollo"
secciones:
- resumen_ejecutivo
- analisis_sitio:
- ubicacion
- uso_suelo
- topografia
- servicios
- analisis_mercado:
- demanda_zona
- competencia
- precios_venta
- absorcion_proyectos_similares
- analisis_financiero:
- costo_terreno
- costo_construccion
- costo_financiero
- precio_venta_proyectado
- utilidad_proyectada
- irr
- payback
- analisis_riesgo
- recomendacion_go_no_go
demand_study:
nombre: "Demand Analysis Report"
descripcion: "Estudio de demanda para nuevo desarrollo"
secciones:
- perfil_demografico_zona
- segmento_objetivo
- tamano_mercado
- competencia_directa
- absorcion_proyectada
- precio_optimo
- product_mix_recomendado
construction_benchmark:
nombre: "Construction Cost Benchmark"
descripcion: "Benchmark de costos de construccion"
secciones:
- costo_m2_por_tipo
- comparativa_zonas
- tendencia_costos
- proveedores_recomendados
- optimizacion_sugerida
project_tracking:
nombre: "Project Tracking Report"
descripcion: "Seguimiento de proyecto de desarrollo"
secciones:
- avance_construccion
- avance_ventas
- flujo_caja_actual
- desviaciones_vs_plan
- proyeccion_cierre
- alertas
# ============================================================================
# 5. TECNICAS ML APLICABLES
# ============================================================================
tecnicas_ml:
# --------------------------------------------------------------------------
# 5.1 Regresion para Valuacion
# --------------------------------------------------------------------------
regresion_valuacion:
descripcion: "Modelos de regresion para predecir valores continuos"
modelos_recomendados:
gradient_boosting:
- nombre: "XGBoost"
uso: "Valuacion de propiedades, prediccion de precios"
hiperparametros:
n_estimators: [100, 500, 1000]
max_depth: [3, 5, 7, 10]
learning_rate: [0.01, 0.05, 0.1]
min_child_weight: [1, 3, 5]
subsample: [0.7, 0.8, 0.9]
colsample_bytree: [0.7, 0.8, 0.9]
pros:
- "Excelente performance en datos tabulares"
- "Feature importance nativa"
- "Maneja missing values"
- "Regularizacion incluida"
contras:
- "Puede overfittear con pocos datos"
- "No extrapola bien"
- nombre: "LightGBM"
uso: "Datasets grandes, entrenamiento rapido"
hiperparametros:
num_leaves: [31, 50, 100]
max_depth: [-1, 10, 20]
learning_rate: [0.01, 0.05, 0.1]
n_estimators: [100, 500, 1000]
min_child_samples: [20, 50, 100]
pros:
- "Muy rapido"
- "Bajo uso de memoria"
- "Excelente con categoricas"
contras:
- "Sensible a overfitting con pocos datos"
linear_models:
- nombre: "ElasticNet"
uso: "Baseline, interpretabilidad, regularizacion"
hiperparametros:
alpha: [0.1, 0.5, 1.0]
l1_ratio: [0.1, 0.5, 0.9]
pros:
- "Muy interpretable"
- "Rapido"
- "Buena regularizacion"
contras:
- "No captura no-linealidades"
feature_engineering:
transformaciones:
- log_transform: "Para precios (distribucion log-normal)"
- sqrt_transform: "Para superficies"
- one_hot_encoding: "Para categoricas con pocas clases"
- target_encoding: "Para categoricas con muchas clases"
- geohash: "Para coordenadas geograficas"
features_derivadas:
- precio_m2: "precio / superficie"
- ratio_banos_recamaras: "banos / recamaras"
- distancia_amenidades: "Distancia ponderada a servicios"
- score_ubicacion: "Composite score de ubicacion"
# --------------------------------------------------------------------------
# 5.2 Clustering para Segmentacion
# --------------------------------------------------------------------------
clustering_segmentacion:
descripcion: "Agrupacion de propiedades, zonas o clientes similares"
aplicaciones:
segmentacion_propiedades:
objetivo: "Agrupar propiedades similares para analisis de mercado"
features:
- precio_m2
- superficie
- tipo
- antiguedad
- ubicacion (lat/lon)
algoritmo_recomendado: "K-Means"
segmentacion_zonas:
objetivo: "Identificar clusters geograficos con caracteristicas similares"
features:
- precio_promedio_m2
- nivel_socioeconomico
- densidad_poblacional
- amenidades_cercanas
- crecimiento_historico
algoritmo_recomendado: "DBSCAN"
segmentacion_compradores:
objetivo: "Perfilar tipos de compradores para targeting"
features:
- presupuesto
- tipo_propiedad_buscada
- zona_preferida
- financiamiento
- urgencia
algoritmo_recomendado: "K-Means + PCA"
algoritmos:
kmeans:
uso: "Clusters esfericos, numero conocido de clusters"
hiperparametros:
n_clusters: "Determinar con Elbow method o Silhouette"
init: "k-means++"
max_iter: 300
evaluacion:
- silhouette_score
- calinski_harabasz_score
- davies_bouldin_score
dbscan:
uso: "Clusters de forma arbitraria, detectar outliers"
hiperparametros:
eps: "Distancia maxima entre puntos"
min_samples: "Minimo puntos para formar cluster"
evaluacion:
- silhouette_score
- noise_ratio
hierarchical:
uso: "Jerarquia de clusters, dendrograma"
hiperparametros:
linkage: ["ward", "complete", "average"]
n_clusters: "O cortar dendrograma"
evaluacion:
- cophenetic_correlation
- silhouette_score
# --------------------------------------------------------------------------
# 5.3 Time Series para Tendencias
# --------------------------------------------------------------------------
time_series_tendencias:
descripcion: "Analisis y prediccion de series temporales de mercado"
aplicaciones:
prediccion_precios:
horizonte: "1-12 meses"
granularidad: "mensual"
prediccion_demanda:
horizonte: "1-6 meses"
granularidad: "semanal o mensual"
deteccion_estacionalidad:
objetivo: "Identificar patrones estacionales en mercado"
periodos: ["semanal", "mensual", "anual"]
algoritmos:
prophet:
uso: "Series con estacionalidad multiple, tendencias no lineales"
pros:
- "Facil de usar"
- "Maneja holidays y eventos"
- "Robusto a datos faltantes"
- "Intervalos de confianza automaticos"
contras:
- "No muy preciso para series muy irregulares"
hiperparametros:
changepoint_prior_scale: [0.001, 0.01, 0.1, 0.5]
seasonality_prior_scale: [0.01, 0.1, 1, 10]
seasonality_mode: ["additive", "multiplicative"]
sarima:
uso: "Series estacionarias con estacionalidad"
pros:
- "Teoricamente solido"
- "Bueno para series cortas"
contras:
- "Asume estacionariedad"
- "Dificil de tunar"
hiperparametros:
p: [0, 1, 2]
d: [0, 1]
q: [0, 1, 2]
P: [0, 1]
D: [0, 1]
Q: [0, 1]
s: 12 # Para mensual
xgboost_temporal:
uso: "Series con features externas importantes"
pros:
- "Incorpora features externas facilmente"
- "Captura no-linealidades"
contras:
- "No modela dependencia temporal nativamente"
features_temporales:
- lag_features: [1, 7, 30, 365]
- rolling_mean: [7, 30, 90]
- rolling_std: [7, 30]
- day_of_week
- month
- quarter
- is_holiday
# --------------------------------------------------------------------------
# 5.4 NLP para Analisis de Descripciones
# --------------------------------------------------------------------------
nlp_descripciones:
descripcion: |
Procesamiento de lenguaje natural para extraer informacion
y features de descripciones de propiedades.
aplicaciones:
extraccion_amenidades:
objetivo: "Identificar amenidades mencionadas en descripcion"
tecnica: "Named Entity Recognition (NER) customizado"
entidades:
- "amenidad_interior": ["alberca", "gimnasio", "salon_eventos"]
- "amenidad_exterior": ["jardin", "terraza", "roof_garden"]
- "caracteristica": ["remodelado", "estrenar", "amueblado"]
- "ubicacion_ref": ["cerca_metro", "zona_exclusiva"]
sentiment_analysis:
objetivo: "Evaluar tono y calidad de descripcion"
metricas:
- positivity_score
- urgency_score
- professionalism_score
quality_scoring:
objetivo: "Puntuar calidad de la descripcion"
features:
- longitud_palabras
- num_amenidades_mencionadas
- estructura_gramatical
- keywords_relevantes
- llamados_accion
output: "quality_score (0-100)"
similarity_search:
objetivo: "Encontrar propiedades con descripciones similares"
tecnica: "Embeddings + Cosine Similarity"
modelos:
embeddings:
- nombre: "text-embedding-3-small"
provider: "OpenAI"
dimensiones: 1536
uso: "Similarity search, semantic search"
costo: "$0.00002 / 1K tokens"
- nombre: "all-MiniLM-L6-v2"
provider: "Sentence Transformers"
dimensiones: 384
uso: "On-premise, bajo costo"
costo: "Gratis (self-hosted)"
ner:
- nombre: "SpaCy + Custom NER"
uso: "Extraccion de entidades inmobiliarias"
training: "Fine-tune con datos anotados"
- nombre: "GPT-4 / Claude"
uso: "Zero-shot extraction"
prompt: |
Extrae las siguientes entidades de esta descripcion de propiedad:
- Amenidades interiores
- Amenidades exteriores
- Caracteristicas especiales
- Referencias de ubicacion
Descripcion: {descripcion}
Responde en JSON.
sentiment:
- nombre: "VADER"
uso: "Sentiment basico, rapido"
- nombre: "RoBERTa fine-tuned"
uso: "Sentiment mas preciso"
# ============================================================================
# 6. ARQUITECTURA TECNICA
# ============================================================================
arquitectura_tecnica:
stack_tecnologico:
ml_framework:
- scikit-learn: "Modelos clasicos, preprocessing"
- xgboost: "Gradient boosting"
- lightgbm: "Gradient boosting alternativo"
- pytorch: "Deep learning (si necesario)"
- prophet: "Time series"
data_processing:
- pandas: "Manipulacion de datos"
- polars: "Procesamiento rapido de grandes datasets"
- numpy: "Operaciones numericas"
- geopandas: "Datos geograficos"
nlp:
- spacy: "NER, preprocessing"
- sentence-transformers: "Embeddings"
- langchain: "LLM integration"
api:
- fastapi: "API REST"
- pydantic: "Validacion de schemas"
- uvicorn: "ASGI server"
mlops:
- mlflow: "Experiment tracking"
- dvc: "Data versioning"
- docker: "Containerization"
database:
- postgresql: "Datos transaccionales"
- pgvector: "Vector embeddings"
- redis: "Cache de predicciones"
estructura_proyecto:
ml_service:
- src/:
- api/:
- main.py
- routes/
- schemas/
- models/:
- property_valuation/
- time_to_sell/
- demand_forecast/
- opportunity_detector/
- pipelines/:
- preprocessing.py
- feature_engineering.py
- training/:
- train.py
- evaluate.py
- hyperparameter_tuning.py
- inference/:
- predictor.py
- batch_predictor.py
- nlp/:
- embeddings.py
- entity_extraction.py
- utils/:
- logging.py
- metrics.py
- geo.py
- notebooks/
- data/:
- raw/
- processed/
- models/
- tests/
- configs/
- mlflow/
- Dockerfile
- requirements.txt
- MODEL_CARDS/
api_design:
base_url: "/api/v1/ml"
endpoints:
valuation:
- "POST /valuation/predict"
- "POST /valuation/batch"
- "POST /valuation/explain"
- "GET /valuation/comparables/{property_id}"
predictions:
- "POST /predictions/time-to-sell"
- "POST /predictions/demand/{zone_id}"
- "GET /predictions/trends/{zone_id}"
opportunities:
- "GET /opportunities/undervalued"
- "GET /opportunities/emerging-zones"
- "POST /opportunities/roi-analysis"
market:
- "GET /market/indices"
- "GET /market/trends/{zone_id}"
- "GET /market/comparables/{property_id}"
reports:
- "POST /reports/cma"
- "POST /reports/investment-analysis"
- "POST /reports/market-snapshot"
monitoring:
metricas:
modelo:
- prediction_latency_ms
- prediction_count
- error_rate
- drift_score
negocio:
- accuracy_vs_actual: "Prediccion vs precio real de venta"
- user_adoption: "% de usuarios que usan predicciones"
- report_generation_count
alertas:
- "Drift detectado > umbral"
- "Latencia > 500ms"
- "Error rate > 5%"
- "Modelo accuracy < 80%"
# ============================================================================
# 7. ROADMAP DE IMPLEMENTACION
# ============================================================================
roadmap:
fase_1_mvp:
duracion: "4-6 semanas"
entregables:
- "AVM basico (XGBoost)"
- "API de valuacion"
- "Dashboard simple de tendencias"
- "Reporte CMA basico"
prioridad: "CRITICA"
fase_2_predicciones:
duracion: "4-6 semanas"
entregables:
- "Prediccion tiempo de venta"
- "Prediccion demanda por zona"
- "Detector propiedades subvaluadas"
- "Alertas de oportunidades"
prioridad: "ALTA"
fase_3_analisis_avanzado:
duracion: "4-6 semanas"
entregables:
- "Indices de mercado"
- "Analisis ROI"
- "Zonas emergentes"
- "Reportes para inversores"
prioridad: "MEDIA"
fase_4_nlp_optimization:
duracion: "4-6 semanas"
entregables:
- "Analisis NLP descripciones"
- "Scoring calidad listings"
- "Recomendaciones personalizadas"
- "A/B testing de modelos"
prioridad: "MEDIA"
fase_5_enterprise:
duracion: "4-8 semanas"
entregables:
- "Multi-tenant isolation"
- "Custom models por cliente"
- "API avanzada (batch, webhooks)"
- "Reportes white-label"
prioridad: "BAJA"
# ============================================================================
# 8. METRICAS DE EXITO
# ============================================================================
metricas_exito:
modelo:
avm_accuracy:
metrica: "MAPE"
objetivo: "< 10%"
medicion: "Prediccion vs precio de venta real"
time_to_sell_accuracy:
metrica: "MAPE"
objetivo: "< 25%"
medicion: "Dias predichos vs dias reales"
demand_forecast:
metrica: "Directional Accuracy"
objetivo: ">= 70%"
medicion: "Prediccion correcta de subida/bajada"
negocio:
user_adoption:
objetivo: "70% de usuarios activos usan ML features"
medicion: "MAU ML / MAU total"
report_generation:
objetivo: ">100 reportes/mes por cliente enterprise"
opportunity_conversion:
objetivo: "30% de oportunidades alertadas son investigadas"
nps_ml_features:
objetivo: ">= 40"
medicion: "NPS especifico de features ML"
tecnico:
api_latency:
objetivo: "p95 < 500ms para valuacion individual"
availability:
objetivo: "99.5% uptime"
model_freshness:
objetivo: "Re-entrenamiento mensual"
Reference in New Issue View Git Blame Copy Permalink