354 lines
12 KiB
Markdown
354 lines
12 KiB
Markdown
# 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`
|