inmobiliaria-analytics/docs/01-fase-alcance-inicial/IAI-008-ml-analytics/requerimientos/RF-ML-001.md

---
id: "RF-ML-001"
title: "AVM - Valuacion Automatica de Propiedades"
type: "Functional Requirement"
epic: "IAI-008"
priority: "Alta"
status: "Draft"
project: "inmobiliaria-analytics"
created_date: "2026-01-04"
updated_date: "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

```yaml
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

```yaml
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

```yaml
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