{"repo": "cayetano108/inversia", "files": {"README.md": {"bbb19ded9fd0b141015c1c38e108f218859367a5": {"t": 1785747269.412579, "n": 5583, "h": "71acbf1ddd01ae63", "c": "\n# 📈 inversIA – Asistente de Educación Financiera basado en RAG\n\n> **Nota:** este repositorio recoge el código del proyecto con fines de consulta y documentación del trabajo realizado. No es funcional de forma autónoma: requiere el corpus documental y el índice vectorial FAISS, que no se incluyen aquí. La versión desplegada está disponible en HuggingFace Spaces.\n\nAsistente conversacional de educación financiera para particulares, desarrollado como Trabajo de Fin de Máster del **Máster Universitario en Ciencia de Datos** de la **Universitat de València** (curso 2025–2026).\n\n> **Autor:** Cayetano Fernando Romero Monteagudo  \n> **Tutor:** Arturo Sirvent Fresneda  \n> **Título del TFM:** *Diseño y Evaluación de Asistente Financiero basado en Retrieval Augmented Generation (RAG)*\n\n---\n\n## ¿Qué es inversIA?\n\ninversIA es un asistente conversacional que combina un grafo de estados construido con **LangGraph** y un pipeline **RAG** (Retrieval-Augmented Generation) para responder preguntas de educación financiera en español. A diferencia de un LLM de propósito general, el sistema fundamenta sus respuestas en un corpus curado y verificado, filtra los fragmentos recuperados mediante un juez de relevancia y valida la respuesta generada antes de devolverla al usuario.\n\nEl sistema está pensado para cubrir conceptos como fondos indexados, ETFs, planes de pensiones, interés compuesto, diversificación, fiscalidad básica española (IRPF) y errores comunes del inversor particular.\n\n> ⚠️ **inversIA tiene fines exclusivamente educativos.** Las respuestas no constituyen asesoramiento financiero personalizado en el sentido del artículo 4 de la Directiva MiFID II. Para decisiones de inversión reales, consulta a un profesional autorizado por la CNMV.\n\n---\n\n## Arquitectura\n\nEl pipeline se implementa como un grafo de estados de 8 nodos sobre LangGraph:\n\n```\nPregunta → Expansión → Enrutador ──► Recuperación FAISS\n                          │                 │\n                          │           Juez de relevancia\n                          │                 │\n                          │           Enriquecimiento (yfinance)\n                          │                 │\n                          │           Generación\n                          │                 │\n                          └──► Redirección  Validación doble\n                                            │\n                                        Respuesta\n```\n\n| Nodo | Función |\n|------|---------|\n| `augment` | Enriquece la pregunta con contexto financiero y el historial reciente |\n| `route_question` | Clasifica la pregunta como dentro/fuera del dominio |\n| `retrieve` | Recupera los *k=6* fragmentos más relevantes del índice FAISS |\n| `grade_documents` | Filtra los fragmentos no relevantes para la pregunta |\n| `enrich` | Incorpora datos de mercado en tiempo real vía yfinance (*tool calling*) |\n| `generate` | Genera la respuesta usando el contexto recuperado |\n| `check` | Verifica ausencia de alucinaciones y adecuación de la respuesta |\n| `redirect` | Redirige preguntas fuera del dominio con una respuesta alternativa |\n\n---\n\n## Corpus y vectorstore\n\nEl corpus está compuesto por libros de referencia sobre inversión a largo plazo y gestión pasiva (Bogle, Bernstein, Graham, Housel, Paramés, Larimore et al.) junto con 17 guías divulgativas de la CNMV sobre fondos, ETFs, fiscalidad, protección del inversor y fraudes financieros.\n\nLos documentos se segmentan en fragmentos de 500 tokens (solapamiento 50) y se vectorizan con `text-embedding-3-large` de OpenAI, produciendo un índice FAISS de **2.496 vectores**. Cada fragmento incluye un resumen generado con DeepSeek en el campo de metadatos para mejorar la precisión del retrieval.\n\n---\n\n## Stack tecnológico\n\n| Componente | Librería |\n|-----------|----------|\n| Grafo de estados | `langgraph ≥ 0.4` |\n| Integración LLM | `langchain ≥ 0.3`, `langchain-deepseek`, `langchain-openai` |\n| Vectorstore | `faiss-cpu ≥ 1.7.4` |\n| Embeddings | `text-embedding-3-large` (OpenAI) |\n| Modelo generador principal | `deepseek-chat` (DeepSeek) |\n| Datos de mercado | `yfinance ≥ 0.2.40` |\n| Interfaz conversacional | `chainlit ≥ 2.0` |\n\n---\n\n## Evaluación\n\nEl sistema fue evaluado con métricas RAGAS sobre 28 preguntas estratificadas (simples, multiconcepto, comparativas, adversariales y fuera de alcance), comparando 9 configuraciones: 3 variantes del pipeline (RAG-FULL, RAG-LITE, NO-RAG) × 3 modelos generadores (GPT-3.5-turbo, DeepSeek Chat, GPT-4o).\n\n**Resultados destacados (configuraciones RAG-FULL):**\n\n| Modelo | Faithfulness | Answer Relevancy | Coste/consulta |\n|--------|-------------|-----------------|----------------|\n| GPT-3.5-turbo | 0,803 | 0,693 | $0,001773 |\n| DeepSeek Chat | 0,893 | 0,741 | $0,000960 |\n| GPT-4o | 0,905 | 0,794 | $0,010021 |\n\nDeepSeek ofrece una fidelidad prácticamente equivalente a GPT-4o a menos de una décima parte del coste, posicionándose como la opción más equilibrada para un despliegue productivo. El nodo de evaluación de documentos concentra cerca del 50% de la latencia total en todas las configuraciones RAG-FULL.\n\n---\n\n## Variables de entorno requeridas\n\nEl sistema utiliza las siguientes claves API, configuradas como *secrets* en HuggingFace:\n\n- `DEEPSEEK_API_KEY` — modelos Deepseek\n- `OPENAI_API_KEY_EMBEDDING` — para modelos de openAI y embedding (`text-embedding-3-large`)\n\n---\n\n## Privacidad\n\nEl historial de conversación se mantiene únicamente en memoria durante la sesión activa y se descarta al cerrarla. No se almacenan datos personales entre sesiones, simplificando el cumplimiento del RGPD.\n\n"}, "dc943cc478facc92702f011a5111130574c35b1e": {"t": 1785772036.257836, "n": 5673, "h": "0feb2527751438e2", "c": "---\ntitle: InversIA\nemoji: 📈\ncolorFrom: green\ncolorTo: blue\nsdk: docker\npinned: false\n---\n\n# 📈 inversIA – Asistente de Educación Financiera basado en RAG\n\n> **Nota:** este repositorio recoge el código del proyecto con fines de consulta y documentación del trabajo realizado. No es funcional de forma autónoma: requiere el corpus documental y el índice vectorial FAISS, que no se incluyen aquí. La versión desplegada está disponible en HuggingFace Spaces.\n\nAsistente conversacional de educación financiera para particulares, desarrollado como Trabajo de Fin de Máster del **Máster Universitario en Ciencia de Datos** de la **Universitat de València** (curso 2025–2026).\n\n> **Autor:** Cayetano Fernando Romero Monteagudo  \n> **Tutor:** Arturo Sirvent Fresneda  \n> **Título del TFM:** *Diseño y Evaluación de Asistente Financiero basado en Retrieval Augmented Generation (RAG)*\n\n---\n\n## ¿Qué es inversIA?\n\ninversIA es un asistente conversacional que combina un grafo de estados construido con **LangGraph** y un pipeline **RAG** (Retrieval-Augmented Generation) para responder preguntas de educación financiera en español. A diferencia de un LLM de propósito general, el sistema fundamenta sus respuestas en un corpus curado y verificado, filtra los fragmentos recuperados mediante un juez de relevancia y valida la respuesta generada antes de devolverla al usuario.\n\nEl sistema está pensado para cubrir conceptos como fondos indexados, ETFs, planes de pensiones, interés compuesto, diversificación, fiscalidad básica española (IRPF) y errores comunes del inversor particular.\n\n> ⚠️ **inversIA tiene fines exclusivamente educativos.** Las respuestas no constituyen asesoramiento financiero personalizado en el sentido del artículo 4 de la Directiva MiFID II. Para decisiones de inversión reales, consulta a un profesional autorizado por la CNMV.\n\n---\n\n## Arquitectura\n\nEl pipeline se implementa como un grafo de estados de 8 nodos sobre LangGraph:\n\n```\nPregunta → Expansión → Enrutador ──► Recuperación FAISS\n                          │                 │\n                          │           Juez de relevancia\n                          │                 │\n                          │           Enriquecimiento (yfinance)\n                          │                 │\n                          │           Generación\n                          │                 │\n                          └──► Redirección  Validación doble\n                                            │\n                                        Respuesta\n```\n\n| Nodo | Función |\n|------|---------|\n| `augment` | Enriquece la pregunta con contexto financiero y el historial reciente |\n| `route_question` | Clasifica la pregunta como dentro/fuera del dominio |\n| `retrieve` | Recupera los *k=6* fragmentos más relevantes del índice FAISS |\n| `grade_documents` | Filtra los fragmentos no relevantes para la pregunta |\n| `enrich` | Incorpora datos de mercado en tiempo real vía yfinance (*tool calling*) |\n| `generate` | Genera la respuesta usando el contexto recuperado |\n| `check` | Verifica ausencia de alucinaciones y adecuación de la respuesta |\n| `redirect` | Redirige preguntas fuera del dominio con una respuesta alternativa |\n\n---\n\n## Corpus y vectorstore\n\nEl corpus está compuesto por libros de referencia sobre inversión a largo plazo y gestión pasiva (Bogle, Bernstein, Graham, Housel, Paramés, Larimore et al.) junto con 17 guías divulgativas de la CNMV sobre fondos, ETFs, fiscalidad, protección del inversor y fraudes financieros.\n\nLos documentos se segmentan en fragmentos de 500 tokens (solapamiento 50) y se vectorizan con `text-embedding-3-large` de OpenAI, produciendo un índice FAISS de **2.496 vectores**. Cada fragmento incluye un resumen generado con DeepSeek en el campo de metadatos para mejorar la precisión del retrieval.\n\n---\n\n## Stack tecnológico\n\n| Componente | Librería |\n|-----------|----------|\n| Grafo de estados | `langgraph ≥ 0.4` |\n| Integración LLM | `langchain ≥ 0.3`, `langchain-deepseek`, `langchain-openai` |\n| Vectorstore | `faiss-cpu ≥ 1.7.4` |\n| Embeddings | `text-embedding-3-large` (OpenAI) |\n| Modelo generador principal | `deepseek-chat` (DeepSeek) |\n| Datos de mercado | `yfinance ≥ 0.2.40` |\n| Interfaz conversacional | `chainlit ≥ 2.0` |\n\n---\n\n## Evaluación\n\nEl sistema fue evaluado con métricas RAGAS sobre 28 preguntas estratificadas (simples, multiconcepto, comparativas, adversariales y fuera de alcance), comparando 9 configuraciones: 3 variantes del pipeline (RAG-FULL, RAG-LITE, NO-RAG) × 3 modelos generadores (GPT-3.5-turbo, DeepSeek Chat, GPT-4o).\n\n**Resultados destacados (configuraciones RAG-FULL):**\n\n| Modelo | Faithfulness | Answer Relevancy | Coste/consulta |\n|--------|-------------|-----------------|----------------|\n| GPT-3.5-turbo | 0,803 | 0,693 | $0,001773 |\n| DeepSeek Chat | 0,893 | 0,741 | $0,000960 |\n| GPT-4o | 0,905 | 0,794 | $0,010021 |\n\nDeepSeek ofrece una fidelidad prácticamente equivalente a GPT-4o a menos de una décima parte del coste, posicionándose como la opción más equilibrada para un despliegue productivo. El nodo de evaluación de documentos concentra cerca del 50% de la latencia total en todas las configuraciones RAG-FULL.\n\n---\n\n## Variables de entorno requeridas\n\nEl sistema utiliza las siguientes claves API, configuradas como *secrets* en HuggingFace:\n\n- `DEEPSEEK_API_KEY` — modelos Deepseek\n- `OPENAI_API_KEY_EMBEDDING` — para modelos de openAI y embedding (`text-embedding-3-large`)\n\n---\n\n## Privacidad\n\nEl historial de conversación se mantiene únicamente en memoria durante la sesión activa y se descarta al cerrarla. No se almacenan datos personales entre sesiones, simplificando el cumplimiento del RGPD.\n\n"}, "47ae277f9cc3a876110d5079f6278369979ea668": {"t": 1785772039.0983953, "n": 30, "h": "b445ac0429ed9092", "c": "# inversIA\nTFM - inversIA app\n"}}}}