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