inmobiliaria-analytics/docs/01-fase-alcance-inicial/IAI-008-ml-analytics/historias-usuario/US-ML-001.md

id	title	type	epic	status	story_points	priority	sprint	project	created_date	updated_date
US-ML-001	Valuacion automatica de propiedad	User Story	IAI-008	Draft	13	Alta	-	inmobiliaria-analytics	2026-01-04	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

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

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: -