---
id: "US-ML-001"
title: "Valuacion automatica de propiedad"
type: "User Story"
epic: "IAI-008"
status: "Draft"
story_points: 13
priority: "Alta"
sprint: "-"
project: "inmobiliaria-analytics"
created_date: "2026-01-04"
updated_date: "2026-01-04"
---

# US-ML-001: Valuacion automatica de propiedad

---

## User Story

**Como** agente inmobiliario
**Quiero** obtener una valuacion automatica de una propiedad
**Para** proporcionar a mis clientes una estimacion de precio basada en datos

---

## Descripcion

Implementar el modelo AVM (Automated Valuation Model) que estime el valor de mercado de propiedades basandose en caracteristicas, ubicacion y condiciones de mercado. El modelo debe ser preciso (MAPE < 10%) y proporcionar explicaciones de los factores que influyen en la valuacion.

---

## Criterios de Aceptacion

### Funcionales

- [ ] Usuario ingresa caracteristicas de propiedad
- [ ] Sistema retorna valor estimado con rango
- [ ] Sistema muestra score de confianza
- [ ] Sistema muestra precio por m2
- [ ] Sistema lista propiedades comparables

### Tecnicos

- [ ] MAPE < 10% en test set
- [ ] Latencia < 500ms
- [ ] Modelo versionado en MLflow
- [ ] API disponible en `/api/v1/ml/valuation/predict`

---

## Mockup de Interfaz

```
+------------------------------------------+
|  VALUACION AUTOMATICA                    |
+------------------------------------------+
|                                          |
|  Tipo: [Casa v]  Transaccion: [Venta v]  |
|                                          |
|  Recamaras: [3]   Banos: [2.5]           |
|  Superficie construida: [180] m2         |
|  Superficie terreno: [250] m2            |
|  Antiguedad: [5] anos                    |
|                                          |
|  Direccion: [Av. Americas 1234_______]   |
|  Colonia: [Providencia]                  |
|  Ciudad: [Guadalajara]                   |
|                                          |
|  [        CALCULAR VALUACION        ]    |
|                                          |
+------------------------------------------+
|  RESULTADO                               |
+------------------------------------------+
|                                          |
|  Valor Estimado: $4,850,000 MXN          |
|  Rango: $4,600,000 - $5,100,000          |
|  Precio/m2: $26,944                      |
|  Confianza: 87%                          |
|                                          |
|  Factores principales:                   |
|  + Ubicacion premium (+12%)              |
|  + Superficie generosa (+8%)             |
|  - Antiguedad moderada (-3%)             |
|                                          |
|  Comparables cercanos:                   |
|  | Direccion | Precio | m2 | $/m2 |     |
|  |-----------|--------|-----|------|     |
|  | Americas  | 4.9M   | 190 | 25.8K|     |
|  | Lopez M.  | 4.7M   | 175 | 26.9K|     |
|                                          |
+------------------------------------------+
```

---

## Tareas Tecnicas

| # | Tarea | Estimacion |
|---|-------|------------|
| 1 | Feature engineering pipeline | 8h |
| 2 | Entrenar modelo XGBoost | 4h |
| 3 | Entrenar modelo LightGBM | 4h |
| 4 | Implementar ensemble | 4h |
| 5 | API endpoint FastAPI | 4h |
| 6 | Integracion frontend | 8h |
| 7 | Tests unitarios y de integracion | 6h |
| 8 | Documentacion y model card | 4h |

**Total estimado:** 42h (~5 dias)

---

## Datos de Entrada

```yaml
input:
  required:
    - property_type: string
    - transaction_type: string
    - construction_m2: number
    - latitude: number
    - longitude: number

  optional:
    - land_m2: number
    - bedrooms: integer
    - bathrooms: number
    - parking_spaces: integer
    - age_years: integer
    - postal_code: string
    - amenities: string[]
```

---

## Datos de Salida

```yaml
output:
  estimated_price: number
  price_range:
    min: number
    max: number
  price_per_m2: number
  confidence_score: number  # 0-1
  factors:
    - name: string
      impact: string  # "positive" | "negative"
      magnitude: number  # %
  comparables:
    - id: string
      address: string
      price: number
      surface_m2: number
      price_per_m2: number
      similarity_score: number
```

---

## Definition of Done

- [ ] MAPE < 10% validado
- [ ] API responde en < 500ms
- [ ] UI implementada y funcional
- [ ] Comparables se muestran correctamente
- [ ] Tests pasan (unit + integration)
- [ ] Model card documentado
- [ ] Deployed a staging

---

## Dependencias

- IA-007 completado (datos de propiedades)
- Modelo de datos de propiedades
- Infraestructura ML (FastAPI, MLflow)

---

**Asignado a:** -
**Sprint:** -