RoboAdvisor educativo de carteras de ETFs

⚠️ Herramienta educativa y de simulación. NO constituye asesoramiento de inversión regulado. No se ejecutan órdenes contra ningún bróker.

Recomienda una cartera modelo de ETFs UCITS según un perfil de riesgo calculado de forma determinista, calcula métricas con datos de mercado reales (solo lectura) y genera una explicación en español con un LLM local que solo redacta — nunca decide. Detecta deriva de cartera y sugiere movimientos de rebalanceo (informativo).

📺 Acompaña al vídeo

Este repositorio es el código completo del vídeo en el que construyo este roboadvisor paso a paso aplicando Spec-Driven Development con GitHub Spec Kit, en el canal Joki Ruiz:

🎥 Roboadvisor con IA local construido con Spec-Driven Development

Es el segundo capítulo de la serie sobre SDD — si es la primera vez que ves el método, empieza por el primer vídeo donde lo explico desde cero. En la carpeta prompts/ tienes los prompts exactos usados en cada paso del flujo.

Garantías (constitución del proyecto)

• Separación de responsabilidades: la lógica de decisión (src/profiling, src/portfolio, src/market) es Python puro determinista. El LLM (src/explanation) solo redacta a partir de decisiones ya tomadas.
• No es asesoramiento financiero: disclaimer visible en cada respuesta de la API y en cada pantalla de la UI; sin ejecución de órdenes.
• Privacidad local: perfiles, carteras y caché viven en SQLite local; la API se enlaza a 127.0.0.1. La única conexión externa es la descarga de precios en solo lectura, con caché de 24h (nunca commiteada).
• Calidad y testing: la capa de decisión tiene tests de casos límite con cobertura completa; el cliente del LLM se mockea en los tests.
• Explicabilidad: cada recomendación es trazable (respuestas → perfil → cartera → métricas → explicación).

Requisitos

• Python 3.11+ y uv
• Ollama en localhost con un modelo (ollama pull llama3.1:8b). Opcional: sin él, ves cartera y métricas, pero no la explicación.

Instalación y ejecución

uv sync
cp config.example.yaml config.yaml   # ajusta umbrales, modelo LLM, etc.

# Backend (API local; docs OpenAPI en /docs)
uv run uvicorn src.api.main:app --host 127.0.0.1 --port 8000

# Frontend (otra terminal)
uv run streamlit run src/ui/app.py

Tests

uv run pytest                                           # toda la suite
uv run pytest --cov --cov-report=term-missing           # cobertura (capa de decisión)

Estructura

src/profiling/    Cuestionario y cálculo determinista del perfil
src/portfolio/    Carteras modelo, métricas y rebalanceo (determinista)
src/market/       Descarga (solo lectura) y caché de precios
src/explanation/  Capa LLM aislada (Ollama), mockeable
src/api/          Endpoints FastAPI (disclaimer en cada respuesta)
src/ui/           Frontend Streamlit
src/common/       Tipos de dominio, disclaimer, carga de datos semilla
src/persistence/  SQLite local
data/             Universo de ETFs y carteras modelo (seed)
config.yaml       Umbrales, ventana histórica, modelo LLM, TTL de caché

La caché de precios (data/cache/) y cualquier *.db están en .gitignore y no deben commitearse.

---

📚 Sobre el autor

Soy Joaquín "Joki" Ruiz, ingeniero informático con más de 20 años de experiencia, autor y creador de contenido especializado en IA local y privada para desarrolladores. Llevo años divulgando en español sobre cómo construir sistemas de IA que respetan tu privacidad y que tú controlas de verdad.

Mis libros sobre Inteligencia Artificial

Tengo tres libros publicados en Amazon que te ayudan a entender la IA desde sus cimientos y a programar con ella sin cajas negras. Disponibles en Kindle y tapa blanda:

• 🆕 El Motor de la Inteligencia Artificial — el más reciente, donde desgrano cómo funcionan por dentro los modelos que usas a diario. Ver en Amazon
• 📖 Todos mis libros en mi página de autor en Amazon

Si este proyecto te ha resultado útil, los libros son la mejor forma de profundizar en el "cómo" y el "por qué" de todo lo que ocurre debajo de la capa de explicación que ves aquí.

Sígueme

• 🎥 YouTube: @jokioki — IA local, agentes, Spec-Driven Development, OpenCode, MCP, Ollama y más, todo en español.
• 🌐 Web: jokiruiz.com

Si te ha gustado el repo

• ⭐ Dale una estrella en GitHub — ayuda muchísimo a que llegue a más gente.
• 🔔 Suscríbete al canal de YouTube para los próximos capítulos de la serie SDD.
• 💬 Abre una Discussion en el repo si quieres comentar el diseño, proponer mejoras o que cubra algún tema en un próximo vídeo.

---

¡Que la IA te acompañe!