# Prompt para Claude Code — AR-House Location Intelligence Agent

## Contexto del proyecto
Proyecto: AR-House
Ruta: D:\Proyectos Software\AR-House
Stack existente: Python, Streamlit, Ollama, SQLite, Firecrawl
Nuevo módulo: `location_agent` — Agente de Investigación de Ubicación

---

## Instrucción para Claude Code

Eres Claude Code trabajando en el proyecto AR-House ubicado en `D:\Proyectos Software\AR-House`.

Antes de escribir cualquier código:
1. Lee `docs/LOGBOOK.md` para entender el estado actual del proyecto
2. Si no existe, créalo siguiendo el skill app-organizer

Tu tarea es implementar un nuevo módulo llamado `location_agent` que investiga una dirección o ubicación y genera un reporte completo de inteligencia de ubicación para decisiones de inversión inmobiliaria.

---

## Arquitectura del módulo

### Estructura de archivos a crear

```
D:\Proyectos Software\AR-House\
├── location_agent/
│   ├── __init__.py
│   ├── agent.py                    ← Orquestador principal
│   ├── sub_agents/
│   │   ├── __init__.py
│   │   ├── crime_agent.py          ← Criminalidad
│   │   ├── property_agent.py       ← Valoración y apreciación
│   │   ├── schools_agent.py        ← Escuelas
│   │   ├── amenities_agent.py      ← Amenities cercanos
│   │   ├── demographics_agent.py   ← Demografía y etnias
│   │   ├── maritime_agent.py       ← Mercado laboral marítimo
│   │   └── lifestyle_agent.py      ← Marinas, playas, supermercados
│   ├── scrapers/
│   │   ├── __init__.py
│   │   ├── crime_scraper.py        ← CrimeMapping, SpotCrime
│   │   ├── property_scraper.py     ← Zillow, Redfin, County Appraiser
│   │   ├── schools_scraper.py      ← GreatSchools
│   │   └── census_scraper.py       ← Census.gov ACS
│   ├── report/
│   │   ├── __init__.py
│   │   ├── report_generator.py     ← Generador reporte completo
│   │   └── pdf_generator.py        ← Export a PDF
│   └── utils/
│       ├── __init__.py
│       ├── geocoder.py             ← Conversión dirección → coordenadas
│       └── ollama_client.py        ← Cliente Ollama local
```

---

## Implementación detallada

### 1. agent.py — Orquestador principal

```python
"""
LocationAgent — Orquestador principal del agente de investigación de ubicación
Usa Ollama local para síntesis y análisis de datos recopilados por sub-agentes
"""
```

El agente debe:
- Recibir una dirección o ciudad/estado como input
- Geocodificar la dirección usando Nominatim (OpenStreetMap, gratuito)
- Ejecutar todos los sub-agentes en paralelo usando `asyncio` o `concurrent.futures`
- Consolidar los resultados
- Calcular un Score General de 0-100 basado en los datos objetivos
- Generar el reporte completo via Ollama
- Exportar PDF

### 2. Sub-agentes — Cada uno debe

- Recibir coordenadas (lat/lon) y dirección como input
- Hacer scraping o consultar APIs gratuitas
- Retornar un diccionario estructurado con los datos
- Incluir fuente y fecha de los datos
- Manejar errores gracefully — si falla, retornar datos vacíos con mensaje de error

### 3. Fuentes de datos gratuitas por sub-agente

#### crime_agent.py
- **CrimeMapping.com** — scraping de mapa de crímenes por radio de 1 milla
- **SpotCrime.com** — scraping de reportes recientes
- **FBI UCR API** — https://api.usa.gov/crime/fbi/cde/ (gratuita con key)
- Datos a recopilar: tipos de crimen, frecuencia, tendencia 12 meses, comparación con promedio del condado

#### property_agent.py
- **Zillow** — scraping de Zestimate y histórico de precios del vecindario
- **Redfin** — scraping de precios por sqft y tendencias
- **County Property Appraiser** — buscar el sitio del condado correspondiente (e.g. bcpa.net para Broward)
- Datos: valor estimado, apreciación 1/3/5 años, precio/sqft, días en mercado promedio, inventory

#### schools_agent.py
- **GreatSchools.org** — scraping de ratings de escuelas en radio de 3 millas
- **NCES** (National Center for Education Statistics) — datos oficiales
- Datos: escuelas primarias/secundarias/high school más cercanas, rating 1-10, distancia

#### amenities_agent.py
- **Nominatim/Overpass API (OpenStreetMap)** — gratuita, sin límites razonables
- Query: supermercados, hospitales, restaurantes, parques, gimnasios en radio de 2 millas
- Datos: cantidad por categoría, distancia al más cercano, score de walkability

#### demographics_agent.py
- **Census.gov American Community Survey (ACS) API** — https://api.census.gov/data.html
  Key gratuita en https://api.census.gov/data/key_signup.html
- Datos: distribución étnica %, ingreso mediano del hogar, edad mediana, nivel educativo, 
  desempleo, población total del ZIP code o tract

#### maritime_agent.py
- **BLS.gov API** — Bureau of Labor Statistics, gratuita
- **Census.gov** — datos de empleo por industria
- **NOAA** — puertos y facilities cercanas
- Datos: % de empleos en sector marítimo/portuario en el área metropolitana, 
  compañías navieras cercanas, astilleros, marinas con empleos

#### lifestyle_agent.py
- **Nominatim/Overpass API** — marinas, boat ramps, acceso a playa
- **NOAA Nautical Charts API** — calado, acceso por agua
- **Google Maps Static API** — opcional, free tier $200/mes
- Datos: marinas en radio de 10 millas (nombre, distancia, facilidades), 
  acceso a playa más cercano, boat ramps, distancia al océano/bahía

---

### 4. Score General 0-100

Calcular como promedio ponderado de scores parciales:

```python
SCORE_WEIGHTS = {
    'crime': 0.20,          # Criminalidad (inverso — menos crimen = más score)
    'property': 0.20,       # Valoración y apreciación
    'schools': 0.10,        # Escuelas
    'amenities': 0.15,      # Amenities y walkability
    'demographics': 0.10,   # Demografía (ingreso mediano, empleo)
    'maritime': 0.15,       # Mercado laboral marítimo
    'lifestyle': 0.10,      # Marinas, playa, calidad de vida náutica
}
```

Cada sub-score debe calcularse objetivamente con reglas claras y documentadas.

---

### 5. Integración con Ollama

Usar Ollama local con modelo configurable (default: llama3.1:8b o mixtral).

Ollama se usa para:
1. **Síntesis narrativa** — convertir datos crudos en párrafos de análisis legibles
2. **Identificación de red flags** — detectar patrones preocupantes en los datos
3. **Resumen ejecutivo** — 3-5 párrafos de conclusión para el reporte

NO usar Ollama para calcular scores — esos deben ser determinísticos basados en datos.

```python
# Ejemplo de uso de Ollama
def analyze_with_ollama(data_dict: dict, section: str) -> str:
    prompt = f"""
    Analiza los siguientes datos de {section} para una propiedad inmobiliaria.
    Sé objetivo y conciso. Presenta los puntos clave en 2-3 párrafos.
    No hagas recomendaciones de compra — solo presenta los hechos.
    
    Datos: {json.dumps(data_dict, indent=2)}
    """
    # Llamada a Ollama local
    response = ollama.chat(model='llama3.1:8b', messages=[...])
    return response
```

---

### 6. Reporte completo — Estructura

El reporte debe tener estas secciones en orden:

```
1. RESUMEN EJECUTIVO
   - Score General: XX/100
   - Dirección analizada
   - Fecha del análisis
   - 3-5 párrafos de síntesis (Ollama)
   - Top 3 fortalezas
   - Top 3 debilidades

2. CRIMINALIDAD
   - Score parcial: XX/100
   - Mapa de calor de crímenes (si es posible)
   - Tabla: tipos de crimen últimos 12 meses
   - Comparación con promedio del condado
   - Tendencia (mejorando/empeorando)
   - Análisis narrativo (Ollama)

3. VALORACIÓN Y MERCADO INMOBILIARIO
   - Score parcial: XX/100
   - Valor estimado del área ($/sqft)
   - Apreciación 1 año / 3 años / 5 años (%)
   - Días promedio en mercado
   - Inventory actual
   - Análisis narrativo (Ollama)

4. ESCUELAS
   - Score parcial: XX/100
   - Tabla de escuelas cercanas (nombre, nivel, rating, distancia)
   - Rating promedio del área
   - Análisis narrativo (Ollama)

5. AMENITIES Y WALKABILITY
   - Score parcial: XX/100
   - Supermercados más cercanos (nombre, distancia)
   - Hospitales/clínicas cercanas
   - Restaurantes, parques, gimnasios
   - Walk Score estimado
   - Análisis narrativo (Ollama)

6. DEMOGRAFÍA
   - Score parcial: XX/100
   - Distribución étnica (gráfico de pie)
   - Ingreso mediano del hogar
   - Edad mediana
   - Nivel educativo
   - Tasa de desempleo
   - Análisis narrativo (Ollama)

7. MERCADO LABORAL MARÍTIMO
   - Score parcial: XX/100
   - % empleos sector marítimo/portuario en área metropolitana
   - Principales empleadores marítimos cercanos
   - Astilleros y marinas con empleos
   - Tendencia del sector en la región
   - Análisis narrativo (Ollama)

8. ESTILO DE VIDA NÁUTICO
   - Score parcial: XX/100
   - Marinas cercanas (tabla: nombre, distancia, facilidades, calado)
   - Boat ramps en radio de 10 millas
   - Acceso a playa más cercano (distancia, tipo)
   - Distancia al océano/bahía/ICW
   - Análisis narrativo (Ollama)

9. DATOS TÉCNICOS
   - Fuentes consultadas
   - Fecha y hora del análisis
   - Modelos y metodología de scoring
```

---

### 7. Interfaz Streamlit

Integrar en la UI existente de AR-House como nueva sección:

```python
# Página nueva: pages/location_intelligence.py
# - Input: campo de dirección o ciudad/estado
# - Botón "Investigar Ubicación"
# - Progress bar mientras los sub-agentes trabajan en paralelo
# - Mostrar resultados sección por sección con expanders
# - Score General destacado al inicio con gauge chart (plotly)
# - Botón "Exportar PDF"
# - Guardar reporte en SQLite para consultas futuras
```

---

### 8. PDF Export

Usar `reportlab` o `weasyprint` para generar PDF profesional:
- Logo AR-House en header
- Fecha y dirección en header
- Score General prominente en primera página
- Cada sección en página separada
- Tablas y datos bien formateados
- Footer con fuentes de datos

---

### 9. Base de datos SQLite

Guardar cada análisis en la base de datos existente de AR-House:

```sql
CREATE TABLE location_reports (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    address TEXT NOT NULL,
    lat REAL,
    lon REAL,
    score_general INTEGER,
    score_crime INTEGER,
    score_property INTEGER,
    score_schools INTEGER,
    score_amenities INTEGER,
    score_demographics INTEGER,
    score_maritime INTEGER,
    score_lifestyle INTEGER,
    raw_data JSON,
    report_text TEXT,
    pdf_path TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

---

### 10. Manejo de errores y rate limiting

- Cada scraper debe tener retry logic con backoff exponencial
- Si una fuente falla, continuar con las demás y marcar como "Datos no disponibles"
- Respetar rate limits — agregar delays entre requests
- Cachear resultados por 24 horas para no re-scraper la misma dirección

---

## Librerías nuevas a instalar

```bash
pip install requests beautifulsoup4 selenium playwright
pip install geopy nominatim
pip install ollama
pip install reportlab weasyprint
pip install plotly
pip install asyncio aiohttp
pip install python-dotenv
```

---

## Al finalizar la implementación

Siguiendo el skill app-organizer:
1. Crear `docs/modules/location_agent_log.md` con el log de esta sesión
2. Actualizar `docs/LOGBOOK.md` con entrada de esta sesión
3. Documentar todas las librerías nuevas en `docs/LIBRARIES.md`
4. Actualizar `D:\Proyectos Software\_docs_global\GLOBAL_LIBRARIES.md`
5. Confirmar: "Log actualizado. Módulo location_agent implementado. Librerías documentadas."

---

## Notas importantes

- Los datos de Census.gov requieren una API key gratuita — solicitar en https://api.census.gov/data/key_signup.html y guardar en `.env`
- FBI UCR API también requiere key gratuita — solicitar en https://api.usa.gov/crime/fbi/cde/
- Para el scraping de Zillow/Redfin usar delays generosos (3-5 segundos entre requests) para evitar bloqueos
- Nominatim/Overpass API es completamente gratuita pero requiere User-Agent identificado en los headers
- El modelo Ollama por defecto es configurable via variable de entorno `OLLAMA_MODEL`
