Repositorio GitHub
CódigoCódigo fuente (src/milo), datos, scripts, pruebas, README y manual completo del proyecto.

Agente RAG con Gemini, ChromaDB, LangGraph, herramientas Python y memoria persistente
Proyecto final del módulo de IA Generativa del máster: un agente de cocina y nutrición que responde con su propia base de conocimiento (RAG), calcula calorías y macros con datos reales de USDA mediante herramientas de Python y recuerda cada conversación.
Tres documentos (guía AESAN 2022, recetario y guía de técnicas) se dividen en 83 fragmentos, se convierten en vectores de 3072 dimensiones con gemini-embedding-001 y se guardan en ChromaDB. Un grafo LangGraph recupera contexto en cada turno, deja que Gemini elija entre 8 herramientas deterministas (recetas, escalado, sustituciones, menú semanal, lista de la compra, perfil) y guarda el estado en SQLite. Se usa desde un notebook, la terminal y una web Streamlit desplegada, con 98 pruebas automáticas.
El enunciado pedía un asistente experto con Gemini, RAG y agentes. Elegí cocina y nutrición porque mucha gente no sabe qué cocinar con lo que tiene en la nevera, cómo ajustar una receta a unas calorías o cómo organizar las comidas de la semana.
Es un dominio que exige dos capacidades distintas: conocimiento (qué recomienda una guía oficial, cómo se prepara una receta, cómo sustituir un ingrediente), que resuelve el RAG, y cálculos exactos (calorías, macros, cantidades, totales de un menú), que resuelve Python con valores USDA. El modelo de lenguaje nunca inventa una cifra.
Documentos RAG
3
Guía AESAN 2022 (PDF), recetario propio y guía de técnicas y sustituciones.
Fragmentos
83
≈ 9.900 palabras indexadas en ChromaDB.
Dimensiones
3072
Vector por fragmento con gemini-embedding-001.
Alimentos USDA
121
Valores por 100 g de FoodData Central, con su FDC ID.
Recetas
36
Ingredientes en gramos, validadas por script.
Herramientas
8
Funciones Python que el agente puede ejecutar.
Hay una sola implementación en src/milo/: el notebook, el chat por terminal (scripts/chat.py) y la web Streamlit (app.py) importan el mismo agente mediante agent.ask(pregunta, thread_id).
Cada mensaje entra en el grafo de LangGraph, que siempre empieza recuperando contexto de ChromaDB. Después Gemini decide si responde o si necesita una herramienta de Python; tras cada paso, el estado se guarda en SQLite.
PDF y Markdown alimentan el RAG. Los cálculos usan foods.csv (121 alimentos USDA: 81 Foundation Foods abril 2026, 4 de la edición de octubre 2026 y 36 SR Legacy) y recipes.json (36 recetas). Cada fuente está registrada en sources.json con URL, versión y hash SHA-256: si un documento cambia sin registrarse, la ingesta se detiene.
Guía AESAN 2022
35
Fragmentos. PDF oficial de 19 páginas del Ministerio de Consumo: raciones, frecuencias, sal, agua, actividad física.
Recetario de MILO
37
Fragmentos. Markdown generado desde recipes.json: una receta por fragmento más la introducción.
Técnicas y sustituciones
11
Fragmentos. Markdown propio: pesado, cocción, higiene, temperaturas seguras y sustituciones.
gemini-embedding-001 convierte cada fragmento en 3072 números que representan su significado, en lotes de 16. ChromaDB guarda en local (storage/chroma) el identificador estable, el texto, el vector y los metadatos de procedencia, con distancia coseno.
La colección se llama milo_ + una huella del modelo y de los fragmentos: si cambia un documento se crea otra colección y nunca se mezclan vectores antiguos. Solo se generan los embeddings que faltan, y el índice se construye solo si no existe (por ejemplo, en Streamlit Cloud).
Ejemplo real para "¿Cuántos huevos puedo comer a la semana?". Gemini recibe el system prompt y los fragmentos numerados y responde que la AESAN recomienda un máximo de 4 huevos medianos a la semana [1]. Si una respuesta del RAG no cita nada, se le pide una vez que la reescriba citando. En la web los fragmentos citados se resaltan en naranja.
[1] AESAN · página 9
0,22
Distancia. "Máximo de 4 huevos medianos a la semana".
[2] AESAN · página 18
0,32
Distancia. Resumen de raciones "De un vistazo".
[3] AESAN · página 10
0,32
Distancia. "Leche y lácteos con moderación".
El estado (MiloState) contiene messages, profile y fragments. recuperar busca 4 fragmentos en ChromaDB en cada turno; si la pregunta tiene menos de 6 palabras, le añade la anterior. milo envía a Gemini el system prompt, el perfil, los fragmentos y los últimos 8 turnos, con las herramientas enlazadas mediante bind_tools.
tools_condition decide: si Gemini pide una herramienta, ToolNode la ejecuta y vuelve a milo; si no, termina. Si una herramienta falla, el error vuelve a Gemini para que lo corrija. Un recursion_limit de 16 pasos evita bucles infinitos.
El perfil y el historial no los rellena Gemini: LangGraph los inyecta (InjectedState) y validate_recipe() descarta en Python las recetas incompatibles antes de que Gemini las vea. Con alergias registradas, MILO tampoco recomienda productos comerciales cuya composición depende de la marca.
Para cada ingrediente: aporte = valor por 100 g × gramos ÷ 100. Para escalar a unas kcal, todos los gramos se multiplican por el mismo factor. Python comprueba además que el estado sea coherente (crudo, seco, cocinado) y que un dato ausente nunca se convierta en cero.
Bowl de pollo y arroz
586 kcal
Por ración: 160 g pechuga cruda, 80 g arroz seco, 120 g tomate, 10 g aceite. 42,5 g de proteína.
Escalado a 800 kcal
×1,37
218 g · 109 g · 164 g · 14 g.
Resultado
58,0 g
De proteína a 800 kcal, con valores USDA FoodData Central.
El checkpointer SqliteSaver de LangGraph guarda el estado tras cada paso en storage/memoria.sqlite: mensajes, resultados de herramientas, perfil y fragmentos del último turno. Así "la lista de la compra de ese menú" encuentra el menú en el historial.
Cada conversación tiene su thread_id (en la web va en la URL ?c=…; en la terminal, --hilo). La memoria sobrevive a reiniciar Python: el notebook lo demuestra con un agente nuevo que recuerda "soy vegetariano". A Gemini solo se le envían los últimos 8 turnos; el resto sigue guardado, y un hilo puede borrarse sin tocar los demás.
Vive en src/milo/prompts/system.md. Lo ajusté tras observar fallos: Gemini citaba un fragmento de salmón en una receta de huevos calculada por Python, y copiaba literalmente una frase de ejemplo del tono, que eliminé.
El agente se crea una sola vez con @st.cache_resource. Al recargar la página, la conversación se reconstruye desde la memoria SQLite. Tema con tipografías Nunito y DM Sans, iconos Material Symbols y Lucide, y un chat centrado de 820 px que se adapta al móvil.

Captura de la demo grabada: 800 kcal, 58 g de proteína, 93,9 g de hidratos y 19,7 g de grasa.
"Tengo pollo, arroz, aguacate y huevos. Quiero una cena de unas 800 kcal y bastante proteína." El turno usa 1 embedding, 1 búsqueda en ChromaDB, 3 llamadas a Gemini y 2 herramientas de Python: buscar_recetas con los ingredientes y ver_receta(r001, objetivo_kcal=800), que escala el bowl a 800 kcal con 58 g de proteína.

La ficha muestra que las cantidades se multiplican por el mismo factor y que los valores son USDA por 100 g, sin pérdidas de cocción.
python -m pytest ejecuta 92 pruebas sin API ("92 passed, 6 skipped"); python -m pytest --live ejecuta las 98. El notebook se ejecuta de principio a fin con scripts/run_notebook.py y comprueba automáticamente tres consultas de recuperación. No hay una métrica cuantitativa de calidad del RAG sobre un conjunto de referencia: queda como mejora.
Calculadora
33
Sumas, raciones, datos ausentes, crudo ≠ cocinado, unidades inválidas.
Restricciones
18
Alergias, dietas, alimentos que no gustan, búsqueda y escalado.
Datos USDA
15
121 alimentos comparados con los archivos oficiales, importador y hashes.
RAG y agente
17
Chunking, PDF, citas, reescritura y grafo con un Gemini simulado.
Herramientas
9
Nevera, perfil, sustituciones, menú y lista de la compra con datos reales.
Live (--live)
6
Recuperación esperada, citas y memoria con Gemini y ChromaDB reales.
Documentación, notebooks, entregables y archivos organizados como dossier consultable.
Código fuente (src/milo), datos, scripts, pruebas, README y manual completo del proyecto.
Despliegue público con Chat, Mi nevera, Plan semanal y Mi perfil. El chat depende de la disponibilidad de la API de Gemini.
Presentación original de 24 diapositivas en HTML: arquitectura, RAG paso a paso, agente, memoria y demo.
Entregable principal: el RAG fase a fase con salidas reales, el agente LangGraph, la memoria y 6 ejemplos documentados.
Manual para principiantes: datos, scripts, RAG, LangGraph, herramientas, memoria, API, Streamlit y pruebas.
Recorrido por las diapositivas (enunciado, arquitectura, RAG, agente, herramientas, memoria, API de Gemini, Streamlit, pruebas y limitaciones) seguido de una demo en vivo de la web.

Sugerencias de inicio, secciones de la barra lateral y resumen del perfil. Captura del vídeo de la demo.

Gemini redacta la respuesta; todas las cifras salen de las herramientas de Python.

Ingredientes en gramos, pasos y el desplegable "Fragmentos recuperados de ChromaDB".

Sección determinista (sin Gemini): menú, gráfico de kcal por día y lista de la compra descargable.
Fuentes: README, MANUAL_DEL_PROYECTO.md, presentación y requirements.txt del repositorio, más el vídeo de presentación y demo. Las cifras son las documentadas en el proyecto; no se han recalculado para este portfolio.
Las capturas proceden del vídeo grabado y muestran la interfaz en español. La guía AESAN es un documento público del Ministerio de Consumo; los valores nutricionales proceden de USDA FoodData Central.