feat: AR-House initial commit

2026-07-03 12:24:58 -04:00
commit 047c05287a
216 changed files with 127552 additions and 0 deletions
@@ -0,0 +1,238 @@
+# AR-House
+
+Sistema multi-agente local para análisis de inversión en bienes raíces, especializado en Florida. Clon estilo Tranchi.ai corriendo 100% local con Ollama + estrategia híbrida de scraping (Playwright gratis + Firecrawl pago).
+
+## 1. ¿Qué es esto?
+
+Pipeline de 6 agentes Ollama coordinados que analizan un deal de bienes raíces y entregan un veredicto accionable:
+
+- **AR-House** — coordinador, veredicto final con score 1-10
+- **DealAnalyzer** — calcula DSCR, NOI, Cash Flow para 4 escenarios (Buy & Hold, BRRRR, Wholesale, Section 8)
+- **PhotoInspector** — estima rehab desde fotos del listing
+- **FloridaResearcher** — research del barrio + riesgos específicos FL (flood, huracanes, insurance)
+- **LenderMatcher** — recomienda lenders (DSCR, hard money, foreign national) según perfil del comprador
+- **EmailComposer** — genera emails para lenders/sellers que no suenan a IA
+
+Más adelante: módulo **DealFinder** (auto-scraping de listings desde HUD, Craigslist, county tax deeds, Zillow, Realtor) y módulo **BuyerFinder** (lista de cash buyers activos en tus mercados).
+
+## 2. Requisitos
+
+- **Sistema operativo:** Windows 10/11 (64-bit). VBScript launchers no funcionan en Linux/macOS.
+- **Python:** 3.13 (recomendado) o 3.14
+- **Ollama:** instalado y en el PATH ([ollama.com/download](https://ollama.com/download))
+- **Hardware:**
+  - 12 GB+ VRAM recomendado (probado en 12 GB con partial offload del modelo de 32B)
+  - 32 GB+ RAM
+  - ~60 GB libres en disco (los 6 modelos Ollama)
+- **Cuentas externas:**
+  - Firecrawl free tier (1000 créditos/mes) — solo necesario para scrapers de Zillow/Realtor en Phase 3B
+
+## 3. Setup inicial
+
+### 3.1 Clonar/copiar el proyecto
+
+```
+D:\Proyectos Software\AR-House\
+```
+
+### 3.2 Configurar variables de entorno
+
+Crear `.env` en la raíz del proyecto con:
+
+```
+FIRECRAWL_API_KEY=fc-tu_key_real_aqui
+```
+
+(Si todavía no usás Firecrawl, dejá el archivo vacío o sin esa línea — el sistema lo maneja gracefully.)
+
+### 3.3 Crear virtualenv e instalar dependencias
+
+```powershell
+cd D:\Proyectos Software\AR-House
+py -3.13 -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install -r requirements.txt
+playwright install chromium
+```
+
+### 3.4 Verificar los 6 modelos Ollama
+
+```powershell
+ollama list
+```
+
+Deben aparecer: `AR-House`, `PhotoInspector`, `DealAnalyzer`, `FloridaResearcher`, `LenderMatcher`, `EmailComposer`.
+
+Si falta alguno, recrearlo desde los modelfiles:
+
+```powershell
+ollama create AR-House -f modelfiles\AR-House.modelfile
+ollama create PhotoInspector -f modelfiles\PhotoInspector.modelfile
+ollama create DealAnalyzer -f modelfiles\DealAnalyzer.modelfile
+ollama create FloridaResearcher -f modelfiles\FloridaResearcher.modelfile
+ollama create LenderMatcher -f modelfiles\LenderMatcher.modelfile
+ollama create EmailComposer -f modelfiles\EmailComposer.modelfile
+```
+
+## 4. Cómo arrancar
+
+**Iniciar todo** (Ollama + Streamlit + abre el navegador):
+
+> Doble-click en **`AR-House-Start.vbs`**
+
+**Detener todo** (Ollama + Streamlit):
+
+> Doble-click en **`AR-House-Stop.vbs`**
+
+Para crear un acceso directo en el escritorio:
+1. Click derecho en `AR-House-Start.vbs` → Enviar a → Escritorio (crear acceso directo)
+2. (Opcional) cambiar el icono al del navegador o uno personalizado
+
+## 5. Programar el DealFinder diario (Task Scheduler)
+
+Esto es opcional. Solo aplica una vez tengas Phase 3D implementada.
+
+1. Abrir **Programador de tareas** (Task Scheduler) en Windows
+2. **Crear tarea básica**:
+   - **Nombre:** `AR-House DealFinder`
+   - **Desencadenador:** Diariamente a las **6:00 AM** (o el horario que prefieras)
+   - **Acción:** Iniciar un programa
+     - **Programa o script:** `wscript.exe`
+     - **Argumentos:** `"D:\Proyectos Software\AR-House\AR-House-DealFinder.vbs"`
+3. En las propiedades de la tarea, **General → Configurar para → Windows 10/11**, marcar:
+   - **Ejecutar tanto si el usuario inició sesión como si no**
+   - **Ejecutar con los privilegios más altos** (si el scraping necesita acceso a red sin restricciones)
+4. Guardar
+
+El scraper escribe a `logs\dealfinder.log`. Revisá ese archivo si algo falla.
+
+## 6. Estructura del proyecto
+
+```
+AR-House/
+├── modelfiles/                       # 6 modelfiles de Ollama
+│   ├── AR-House.modelfile
+│   ├── PhotoInspector.modelfile
+│   ├── DealAnalyzer.modelfile
+│   ├── FloridaResearcher.modelfile
+│   ├── LenderMatcher.modelfile
+│   └── EmailComposer.modelfile
+├── scripts/
+│   └── stop-streamlit.ps1            # Helper PowerShell para matar Streamlit limpio
+├── .claude/
+│   └── skills/firecrawl/             # SKILL.md de Firecrawl (pendiente)
+├── analyses/                         # JSON de cada análisis (auto-generado)
+├── logs/                             # Logs del DealFinder (auto-generado)
+├── .venv/                            # Virtualenv Python (NO versionar)
+├── .env                              # Secrets (NO versionar)
+├── markets_database.json             # 50 mercados precargados + 9 presets
+├── user_active_markets.json          # Selección actual del usuario (UI)
+├── config.py                         # Constantes globales
+├── orchestrator.py                   # Coordina los 5 agentes secuencialmente
+├── prompt_templates.py               # Templates de prompts por agente
+├── requirements.txt                  # Dependencias Python
+├── app.py                            # UI Streamlit (Phase 2C, pendiente)
+├── AR-House-Start.vbs            # Launcher: arranca Ollama + Streamlit
+├── AR-House-Stop.vbs             # Stopper: mata Ollama + Streamlit
+├── AR-House-DealFinder.vbs       # Scheduled: scraping diario (Phase 3D)
+└── README.md                         # Este archivo
+```
+
+## 7. Modelos Ollama
+
+| Agente | Modelo base | Tamaño | Función |
+|---|---|---|---|
+| AR-House | qwen2.5:32b | 19 GB | Coordinador, veredicto final |
+| LenderMatcher | qwen2.5:14b | 9 GB | Financiamiento + perfiles A-D |
+| DealAnalyzer | qwen2.5:14b | 9 GB | 4 escenarios financieros |
+| EmailComposer | qwen2.5:14b | 9 GB | Emails on-demand sin frases-IA |
+| PhotoInspector | llama3.2-vision | 7.8 GB | Estima rehab desde fotos |
+| FloridaResearcher | llama3.1:8b | 4.9 GB | Investigación barrio + riesgos FL |
+
+Total en disco: ~59 GB.
+
+**Modo de recursos por defecto:** `low_power` (en `config.py`). Los modelos se cargan uno a la vez (`keep_alive=0`) y se descargan después de responder. Esto evita OOM en GPUs de 12 GB.
+
+Tiempo total estimado por análisis: **~225 segundos** (~3:45 min).
+
+## 8. Mercados monitoreados
+
+El sistema viene precargado con **50 mercados** de USA organizados en 8 regiones (ver `markets_database.json`):
+
+- Florida Primary (6)
+- Florida Treasure Coast (3)
+- Florida Central (3)
+- Florida Secondary (9)
+- Mercados Tranchi cash flow alto (8)
+- Texas (5)
+- Sun Belt (6)
+- Midwest / Otros (10)
+
+Plus **9 presets** para configuración rápida: "Sur de Florida", "Treasure Coast", "Florida Costa Este", "Orlando metro", "Tampa metro", etc.
+
+Para elegir cuáles monitorear:
+1. Abrir la app (`AR-House-Start.vbs`)
+2. Ir a **Mercados** en el sidebar
+3. Seleccionar con checkbox o usar un preset
+4. **Guardar configuración**
+
+El DealFinder solo busca en los mercados activos. Por defecto la lista está vacía (todo desactivado).
+
+## 9. Troubleshooting
+
+### Los VBS no arrancan
+
+- **Windows SmartScreen los bloquea la primera vez:**
+  Click derecho en el `.vbs` → Propiedades → tildar **"Desbloquear"** → Aceptar.
+
+- **El antivirus los marca como sospechoso:**
+  Normal para scripts caseros. Agregar exclusión para `D:\Proyectos Software\AR-House\`.
+
+- **wscript.exe no responde:**
+  Verificar que Windows Script Host (WSH) esté habilitado:
+  ```
+  reg query "HKLM\SOFTWARE\Microsoft\Windows Script Host\Settings" /v Enabled
+  ```
+  Debe devolver `Enabled = 1`.
+
+### Limitación conocida: VBScript deprecated
+
+Microsoft anunció en septiembre 2024 que VBScript será removido de Windows en una versión futura (sin fecha confirmada todavía). Mientras tanto sigue funcionando en Windows 11 actual y al menos hasta 2026-2027. Si en algún momento Microsoft lo desactiva, hay que migrar los launchers a PowerShell + accesos directos `.lnk` configurados como hidden window.
+
+### Ollama no responde
+
+- Verificá que `ollama serve` esté corriendo (lo lanza el VBS automáticamente, pero podés verificar manualmente con `curl http://localhost:11434/api/tags`)
+- Si los modelos no aparecen en `ollama list`, re-crearlos desde los modelfiles (ver sección 3.4)
+- Si Ollama crashea por OOM, bajá `num_ctx` en los modelfiles más pesados (AR-House primero)
+
+### Errores de Python al arrancar
+
+- Verificar virtualenv activo y completo:
+  ```powershell
+  .\.venv\Scripts\Activate.ps1
+  pip list
+  ```
+- Si falta algún paquete: `pip install -r requirements.txt`
+- Si Playwright se queja: `playwright install chromium`
+
+### Streamlit no abre el navegador automáticamente
+
+Abrirlo manualmente: [http://localhost:8501](http://localhost:8501)
+
+### Firecrawl rate limit / créditos agotados
+
+El plan free es 1000 créditos/mes. El sistema usa `FIRECRAWL_CREDIT_BUDGET=500` como margen seguro. Si llegás al límite, el `runner.py` pausa los scrapers de Firecrawl (Zillow/Realtor) pero los gratis (HUD/Craigslist/County) siguen activos.
+
+Para verificar saldo actual:
+```powershell
+curl -H "Authorization: Bearer $env:FIRECRAWL_API_KEY" https://api.firecrawl.dev/v1/team/credit-usage
+```
+
+---
+
+**Versión actual:** 0.1 (Phase 2A completa, Phase 2C/3/4 en roadmap)
+
+**Roadmap:**
+- Phase 2C: UI Streamlit con análisis manual
+- Phase 3: DealFinder (auto-scraping de listings)
+- Phase 4: BuyerFinder (lista de cash buyers + matching)