rckrdmrd f570727617 feat: Documentation and orchestration updates

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-07 05:35:40 -06:00

6.3 KiB

Raw Blame History

id	title	type	epic	priority	status	project	created_date	updated_date
RF-ML-001	AVM - Valuacion Automatica de Propiedades	Functional Requirement	IAI-008	Alta	Draft	inmobiliaria-analytics	2026-01-04	2026-01-04

RF-IA-008-001: AVM - Valuacion Automatica de Propiedades

Descripcion

El sistema debe proporcionar un modelo de valuacion automatica (Automated Valuation Model - AVM) que estime el valor de mercado de propiedades inmobiliarias basandose en caracteristicas fisicas, ubicacion y condiciones de mercado.

Justificacion

La valuacion automatica es el servicio core de la plataforma. Permite a agentes generar valuaciones instantaneas, a inversores evaluar oportunidades, y es la base para otros servicios como deteccion de propiedades subvaluadas.

Requisitos Funcionales

RF-001.1: Prediccion de Precio

ID	Requisito	Prioridad
RF-001.1.1	El sistema debe predecir precio de venta de propiedades	Alta
RF-001.1.2	El sistema debe predecir precio de renta de propiedades	Alta
RF-001.1.3	El sistema debe proporcionar intervalo de confianza	Alta
RF-001.1.4	El sistema debe retornar score de confianza (0-1)	Alta
RF-001.1.5	El sistema debe calcular precio por m2	Alta

RF-001.2: Features del Modelo

ID	Requisito	Prioridad
RF-001.2.1	El modelo debe usar caracteristicas intrinsecas (m2, recamaras, etc)	Alta
RF-001.2.2	El modelo debe usar caracteristicas de ubicacion (lat/lon, zona)	Alta
RF-001.2.3	El modelo debe usar indicadores de mercado (precio promedio zona)	Alta
RF-001.2.4	El modelo debe usar features derivadas (precio m2 comparables)	Media
RF-001.2.5	El modelo debe manejar features faltantes gracefully	Alta

RF-001.3: Explicabilidad

ID	Requisito	Prioridad
RF-001.3.1	El sistema debe explicar factores que influyen en la valuacion	Alta
RF-001.3.2	El sistema debe usar SHAP values para explicaciones	Media
RF-001.3.3	El sistema debe mostrar comparables usados en la estimacion	Alta
RF-001.3.4	El sistema debe indicar features con mayor impacto	Media

RF-001.4: Comparables

ID	Requisito	Prioridad
RF-001.4.1	El sistema debe encontrar propiedades comparables	Alta
RF-001.4.2	El sistema debe calcular similitud entre propiedades	Alta
RF-001.4.3	El sistema debe ponderar comparables por fecha de venta	Media
RF-001.4.4	El sistema debe filtrar comparables por radio geografico	Alta

Features del Modelo

Intrinsecas

Feature	Tipo	Importancia
superficie_construida_m2	float	Alta
superficie_terreno_m2	float	Alta
num_recamaras	int	Media
num_banos	float	Media
num_estacionamientos	int	Media
antiguedad_anos	int	Alta
tipo_propiedad	categorical	Alta
estado_conservacion	ordinal	Media
amenidades_count	int	Media

Ubicacion

Feature	Tipo	Importancia
latitud	float	Alta
longitud	float	Alta
codigo_postal	categorical	Alta
distancia_centro_m	float	Media
distancia_metro_m	float	Media
indice_seguridad_zona	float	Alta
nivel_socioeconomico	ordinal	Alta

Mercado

Feature	Tipo	Importancia
precio_promedio_m2_zona	float	Alta
tendencia_precios_12m	float	Alta
oferta_activa_zona	int	Media
absorcion_promedio_zona	float	Alta

Arquitectura del Modelo

modelo:
  tipo: Ensemble
  componentes:
    - modelo: XGBoost
      peso: 0.5
      hiperparametros:
        n_estimators: 500
        max_depth: 7
        learning_rate: 0.05

    - modelo: LightGBM
      peso: 0.3
      hiperparametros:
        num_leaves: 50
        learning_rate: 0.05

    - modelo: ElasticNet
      peso: 0.2
      hiperparametros:
        alpha: 0.5
        l1_ratio: 0.5

  preprocessing:
    - log_transform: [precio]
    - standard_scaler: [superficie_*, distancia_*]
    - one_hot: [tipo_propiedad]
    - target_encoding: [codigo_postal]

  target: log(precio)
  inverse_transform: exp(prediction)

API Endpoints

POST /api/v1/ml/valuation/predict:
  description: Valuacion de propiedad individual
  request:
    property:
      type: string
      transaction_type: string
      bedrooms: integer
      bathrooms: number
      construction_m2: number
      land_m2: number
      age_years: integer
      latitude: number
      longitude: number
      postal_code: string
      amenities: string[]
  response:
    estimated_price: number
    price_range:
      min: number
      max: number
    confidence_score: number
    price_per_m2: number
    comparables: array
    explanation:
      top_factors: array
      shap_values: object

POST /api/v1/ml/valuation/batch:
  description: Valuacion de multiples propiedades
  request:
    properties: array
  response:
    results: array

POST /api/v1/ml/valuation/explain:
  description: Valuacion con explicacion detallada
  response:
    # Incluye SHAP waterfall plot data

Metricas de Calidad

metricas:
  objetivo:
    MAPE: "< 10%"
    R2: ">= 0.85"
    RMSE: "< 15% del precio medio"

  monitoreo:
    - mape_por_tipo_propiedad
    - mape_por_rango_precio
    - mape_por_zona
    - drift_score

  reentrenamiento:
    trigger: "MAPE > 12% en ultimos 7 dias"
    frecuencia_minima: "mensual"

Criterios de Aceptacion

MAPE < 10% en test set holdout
R2 >= 0.85 en cross-validation
Latencia < 200ms para prediccion individual
Latencia < 2s para batch de 100 propiedades
Explicaciones SHAP disponibles para cada prediccion
Comparables relevantes incluidos en respuesta
Modelo versionado en MLflow
Tests de regresion pasan

Dependencias

IA-007 (Webscraper): Datos de propiedades
IA-002 (Propiedades): Modelo de datos normalizado
XGBoost, LightGBM, scikit-learn
SHAP para explicabilidad
MLflow para versionamiento

Historias de Usuario Relacionadas

US-ML-001: Valuacion automatica basica
US-ML-002: Explicabilidad de valuacion

Autor: ML Lead Fecha: 2026-01-04

6.3 KiB Raw Blame History