Add YAML and Jinja2 support to agents; refactor agent method names

- Updated `requirements.txt` to include `pyyaml` and `jinja2`.
- Refactored `AgentNode` class in `base.py` to change method name from `handle` to `__call__`.
- Enhanced `FAQAgent` and `WizardAgent` to load configurations from YAML files and utilize Jinja2 for prompt rendering.
- Improved prompt generation in `supervisor.py` and `faq.py` for better context handling and response generation.

Author: EmiLabarthe

app/agents/base.py

@@ -17,13 +17,13 @@ class AgentNode(ABC):
         name        – short identifier used as the graph node key (e.g. "faq").
         description – natural-language purpose used by the supervisor to route
                       user messages to the right agent.
-        handle()    – async entry point that LangGraph invokes.
+        __call__()  – async entry point that LangGraph invokes.
     """
 
     name: str
     description: str
 
     @abstractmethod
-    async def handle(self, state: ConversationState) -> ConversationState:
+    async def __call__(self, state: ConversationState) -> ConversationState:
         """Process the current conversation state and return the updated state."""
         ...

app/agents/config/faq.yaml

@@ -0,0 +1,17 @@
+name: faq
+description: >-
+  Responde preguntas sobre Ithaka: programas (Fellows, minor),
+  cursos, costos, campus, convocatorias, requisitos, actividades,
+  información general y preguntas frecuentes. Incluye cualquier
+  consulta informativa como '¿qué es...?', '¿cómo funciona...?',
+  '¿cuándo es...?', '¿dónde queda...?', contacto, etc.
+
+model:
+  temperature_contextual: 0.0
+  temperature_no_results: 0.0
+  max_tokens_contextual: 400
+  max_tokens_no_results: 200
+
+system_prompts:
+  contextual: "Eres el asistente virtual oficial de Ithaka, centro de emprendimiento de la UCU. Respondes consultas de manera amigable y precisa."
+  no_results: "Eres el asistente de Ithaka. Ayuda al usuario incluso cuando no tienes información específica."

app/agents/config/supervisor.yaml

@@ -0,0 +1,3 @@
+model:
+  temperature: 0.0
+  max_tokens: 10

app/agents/config/wizard.yaml

@@ -0,0 +1,6 @@
+name: wizard
+description: >-
+  Guía al usuario a través del proceso de postulación/aplicación:
+  postular una idea o proyecto, inscripción, formulario de
+  postulación, emprendimiento, incubadora, startup. También maneja
+  comandos de navegación del formulario como 'volver' o 'cancelar'.

app/agents/faq.py

@@ -4,9 +4,12 @@
 
 import logging
 import os
+from pathlib import Path
 from typing import Any
 
 import numpy as np
+import yaml
+from jinja2 import Environment, FileSystemLoader
 from langchain_core.messages import AIMessage
 from openai import AsyncOpenAI
 
@@ -17,6 +20,10 @@
 
 logger = logging.getLogger(__name__)
 
+_AGENTS_DIR = Path(__file__).parent
+_config = yaml.safe_load((_AGENTS_DIR / "config" / "faq.yaml").read_text())
+_prompts = Environment(loader=FileSystemLoader(str(_AGENTS_DIR / "prompts")), keep_trailing_newline=True)
+
 
 def to_serializable(obj):
     if isinstance(obj, np.floating):
@@ -31,14 +38,8 @@ def to_serializable(obj):
 class FAQAgent(AgentNode):
     """Agente para responder preguntas frecuentes usando base vectorial"""
 
-    name = "faq"
-    description = (
-        "Responde preguntas sobre Ithaka: programas (Fellows, minor), "
-        "cursos, costos, campus, convocatorias, requisitos, actividades, "
-        "información general y preguntas frecuentes. Incluye cualquier "
-        "consulta informativa como '¿qué es...?', '¿cómo funciona...?', "
-        "'¿cuándo es...?', '¿dónde queda...?', contacto, etc."
-    )
+    name: str = _config["name"]
+    description: str = _config["description"]
 
     def __init__(self):
         api_key = os.getenv("OPENAI_API_KEY")
@@ -51,7 +52,7 @@ def __init__(self):
         self.similarity_threshold = float(
             os.getenv("SIMILARITY_THRESHOLD", "0.4"))
 
-    async def handle(self, state: ConversationState) -> ConversationState:
+    async def __call__(self, state: ConversationState) -> ConversationState:
         """Procesa una consulta FAQ del usuario"""
 
         user_message = [m.content for m in state["messages"] if m.type == "human"][-1]
@@ -138,132 +139,77 @@ async def _generate_contextual_response(
         """Genera una respuesta contextualizada basada en FAQs similares"""
 
         try:
-            # Preparar contexto de FAQs
             faq_context = ""
             for i, faq in enumerate(similar_faqs, 1):
-                faq_context += f"""
-FAQ {i} (similitud: {faq['similarity']:.2f}):
-Pregunta: {faq['question']}
-Respuesta: {faq['answer']}
-"""
+                faq_context += (
+                    f"\nFAQ {i} (similitud: {faq['similarity']:.2f}):\n"
+                    f"Pregunta: {faq['question']}\n"
+                    f"Respuesta: {faq['answer']}\n"
+                )
 
-            prompt = f"""
-Eres el asistente virtual inteligente de Ithaka (centro de emprendimiento UCU). Tu misión es ayudar de la manera más útil posible.
-
-CONSULTA DEL USUARIO:
-"{user_query}"
-
-INFORMACIÓN RELEVANTE ENCONTRADA:
-{faq_context}
-
-INSTRUCCIONES INTELIGENTES:
-1. **Flexibilidad**: Interpreta la intención aunque haya errores de tipeo ("corsos" = "cursos", "ithaka" mal escrito, etc.)
-2. **Contextualidad**: Si preguntan sobre temas relacionados a emprendimiento/universidad, conecta con lo que ofrece Ithaka
-3. **Inteligencia**: Aunque la pregunta no sea exacta, infiere qué información necesita (ej: "qué hacen" → explica programas y servicios)
-4. **Completitud**: Da información útil incluso si no hay coincidencia perfecta
-5. **Natural**: Responde conversacionalmente, como si fueras un consejero experto
-6. **Proactivo**: Sugiere recursos adicionales y próximos pasos
-7. **Amigable**: Termina invitando a hacer más preguntas
-8. **Postulación directa**: Si la intención del usuario es postularse (ej: "quiero postularme", "quiero inscribirme", "quiero postular mi idea"), no preguntes "¿te gustaría saber más sobre eso?". En su lugar, ofrece iniciar la postulación directamente con una frase clara como "Si querés, iniciamos tu postulación ahora mismo."
-
-CONTEXTO ITHAKA:
-- Centro de emprendimiento de la Universidad Católica del Uruguay
-- Ofrece: cursos, minor de emprendimiento, programa Fellows, incubadora
-- Todo gratuito para comunidad UCU
-- Abierto también a emprendedores externos
-- Foco en innovación, emprendimiento e impacto social
-
-RESPUESTA INTELIGENTE:
-"""
+            prompt = _prompts.get_template("faq_contextual.j2").render(
+                user_query=user_query,
+                faq_context=faq_context,
+            )
 
+            model_cfg = _config["model"]
             response = await self.client.chat.completions.create(
                 model=self.model,
                 messages=[
-                    {
-                        "role": "system",
-                        "content": "Eres el asistente virtual oficial de Ithaka, centro de emprendimiento de la UCU. Respondes consultas de manera amigable y precisa."
-                    },
-                    {"role": "user", "content": prompt}
+                    {"role": "system", "content": _config["system_prompts"]["contextual"]},
+                    {"role": "user", "content": prompt},
                 ],
-                temperature=0.3,
-                max_tokens=400
+                temperature=model_cfg["temperature_contextual"],
+                max_tokens=model_cfg["max_tokens_contextual"],
             )
 
             return response.choices[0].message.content
 
         except Exception as e:
             logger.error(f"Error generating contextual response: {e}")
 
-            # Respuesta básica usando la FAQ más similar
             best_faq = similar_faqs[0] if similar_faqs else None
             if best_faq:
-                return f"""
-Basándome en tu consulta, creo que esto te puede ayudar:
-
-**{best_faq['question']}**
-
-{best_faq['answer']}
-
-¿Esto responde a tu pregunta o necesitas información adicional?
-"""
+                return (
+                    f"Basándome en tu consulta, creo que esto te puede ayudar:\n\n"
+                    f"**{best_faq['question']}**\n\n"
+                    f"{best_faq['answer']}\n\n"
+                    f"¿Esto responde a tu pregunta o necesitas información adicional?"
+                )
 
             return "Lo siento, no pude procesar tu consulta correctamente. ¿Podrías reformularla?"
 
     async def _generate_no_results_response(self, user_query: str) -> str:
         """Genera respuesta cuando no se encuentran FAQs relevantes"""
 
         try:
-            prompt = f"""
-El usuario preguntó: "{user_query}"
-
-Aunque no encuentro FAQs específicas que coincidan exactamente, soy el asistente inteligente de Ithaka y puedo ayudar.
-
-CONTEXTO ITHAKA:
-- Centro de emprendimiento de la Universidad Católica del Uruguay
-- Programas: Minor de emprendimiento, Programa Fellows, cursos electivos
-- Servicios: Incubadora de startups, mentorías, capacitaciones
-- Todo gratuito para comunidad UCU, abierto a emprendedores externos
-- Campus: Montevideo, Maldonado, Salto
-- Foco: Innovación, emprendimiento, impacto social
-
-GENERA UNA RESPUESTA INTELIGENTE QUE:
-1. **Interprete la intención**: Aunque la pregunta tenga errores o sea vaga, infiere qué necesita
-2. **Proporcione valor**: Da información útil sobre Ithaka basándose en el contexto
-3. **Sea proactiva**: Sugiere programas/servicios que podrían interesarle
-4. **Mantenga conversación**: Invita a hacer preguntas más específicas
-5. **Corrige sutilmente**: Si hay errores de tipeo, usa las palabras correctas en tu respuesta
-6. **Postulación directa**: Si el usuario quiere postularse, ofrece iniciar la postulación de forma directa y no uses la frase "¿te gustaría saber más sobre eso?".
-
-Respuesta útil e inteligente:
-"""
+            prompt = _prompts.get_template("faq_no_results.j2").render(
+                user_query=user_query,
+            )
 
+            model_cfg = _config["model"]
             response = await self.client.chat.completions.create(
                 model=self.model,
                 messages=[
-                    {
-                        "role": "system",
-                        "content": "Eres el asistente de Ithaka. Ayuda al usuario incluso cuando no tienes información específica."
-                    },
-                    {"role": "user", "content": prompt}
+                    {"role": "system", "content": _config["system_prompts"]["no_results"]},
+                    {"role": "user", "content": prompt},
                 ],
-                temperature=0.5,
-                max_tokens=200
+                temperature=model_cfg["temperature_no_results"],
+                max_tokens=model_cfg["max_tokens_no_results"],
             )
 
             return response.choices[0].message.content
 
         except Exception as e:
             logger.error(f"Error generating no results response: {e}")
-            return """
-No encontré información específica sobre tu consulta en nuestras FAQs.
-
-Te sugiero:
-• Contactar directamente al equipo de Ithaka
-• Revisar nuestro sitio web oficial
-• Seguirnos en redes sociales para estar al día
-
-¿Hay algo más sobre emprendimiento o nuestros programas en lo que pueda ayudarte?
-"""
+            return (
+                "No encontré información específica sobre tu consulta en nuestras FAQs.\n\n"
+                "Te sugiero:\n"
+                "• Contactar directamente al equipo de Ithaka\n"
+                "• Revisar nuestro sitio web oficial\n"
+                "• Seguirnos en redes sociales para estar al día\n\n"
+                "¿Hay algo más sobre emprendimiento o nuestros programas en lo que pueda ayudarte?"
+            )
 
 
 # Instancia global del agente
@@ -272,4 +218,4 @@ async def _generate_no_results_response(self, user_query: str) -> str:
 
 async def handle_faq_query(state: ConversationState) -> ConversationState:
     """Función wrapper para LangGraph"""
-    return await faq_agent.handle(state)
+    return await faq_agent(state)

app/agents/prompts/faq_contextual.j2

@@ -0,0 +1,26 @@
+Eres el asistente virtual inteligente de Ithaka (centro de emprendimiento UCU). Tu misión es ayudar de la manera más útil posible.
+
+CONSULTA DEL USUARIO:
+"{{ user_query }}"
+
+INFORMACIÓN RELEVANTE ENCONTRADA:
+{{ faq_context }}
+
+INSTRUCCIONES INTELIGENTES:
+1. **Flexibilidad**: Interpreta la intención aunque haya errores de tipeo ("corsos" = "cursos", "ithaka" mal escrito, etc.)
+2. **Contextualidad**: Si preguntan sobre temas relacionados a emprendimiento/universidad, conecta con lo que ofrece Ithaka
+3. **Inteligencia**: Aunque la pregunta no sea exacta, infiere qué información necesita (ej: "qué hacen" → explica programas y servicios)
+4. **Completitud**: Da información útil incluso si no hay coincidencia perfecta
+5. **Natural**: Responde conversacionalmente, como si fueras un consejero experto
+6. **Proactivo**: Sugiere recursos adicionales y próximos pasos
+7. **Amigable**: Termina invitando a hacer más preguntas
+8. **Postulación directa**: Si la intención del usuario es postularse (ej: "quiero postularme", "quiero inscribirme", "quiero postular mi idea"), no preguntes "¿te gustaría saber más sobre eso?". En su lugar, ofrece iniciar la postulación directamente con una frase clara como "Si querés, iniciamos tu postulación ahora mismo."
+
+CONTEXTO ITHAKA:
+- Centro de emprendimiento de la Universidad Católica del Uruguay
+- Ofrece: cursos, minor de emprendimiento, programa Fellows, incubadora
+- Todo gratuito para comunidad UCU
+- Abierto también a emprendedores externos
+- Foco en innovación, emprendimiento e impacto social
+
+RESPUESTA INTELIGENTE:

app/agents/prompts/faq_no_results.j2

@@ -0,0 +1,21 @@
+El usuario preguntó: "{{ user_query }}"
+
+Aunque no encuentro FAQs específicas que coincidan exactamente, soy el asistente inteligente de Ithaka y puedo ayudar.
+
+CONTEXTO ITHAKA:
+- Centro de emprendimiento de la Universidad Católica del Uruguay
+- Programas: Minor de emprendimiento, Programa Fellows, cursos electivos
+- Servicios: Incubadora de startups, mentorías, capacitaciones
+- Todo gratuito para comunidad UCU, abierto a emprendedores externos
+- Campus: Montevideo, Maldonado, Salto
+- Foco: Innovación, emprendimiento, impacto social
+
+GENERA UNA RESPUESTA INTELIGENTE QUE:
+1. **Interprete la intención**: Aunque la pregunta tenga errores o sea vaga, infiere qué necesita
+2. **Proporcione valor**: Da información útil sobre Ithaka basándose en el contexto
+3. **Sea proactiva**: Sugiere programas/servicios que podrían interesarle
+4. **Mantenga conversación**: Invita a hacer preguntas más específicas
+5. **Corrige sutilmente**: Si hay errores de tipeo, usa las palabras correctas en tu respuesta
+6. **Postulación directa**: Si el usuario quiere postularse, ofrece iniciar la postulación de forma directa y no uses la frase "¿te gustaría saber más sobre eso?".
+
+Respuesta útil e inteligente:

app/agents/prompts/faq_system_contextual.j2

@@ -0,0 +1 @@
+Eres el asistente virtual oficial de Ithaka, centro de emprendimiento de la Universidad Católica del Uruguay. Respondes consultas de manera amigable y precisa.

app/agents/prompts/supervisor_route.j2

@@ -0,0 +1,20 @@
+Eres un router que analiza la intención del usuario y elige el agente más adecuado.
+
+AGENTES DISPONIBLES:
+{{ agents_block }}
+
+{% if context %}
+CONTEXTO (mensajes recientes de la conversación):
+{{ context }}
+
+{% endif %}
+MENSAJE ACTUAL DEL USUARIO:
+"{{ message }}"
+
+INSTRUCCIONES:
+- Elige el agente cuya descripción mejor coincida con lo que el usuario quiere hacer.
+- Considera el contexto completo de la conversación.
+- No uses heurísticas por palabras clave: interpreta la intención por el contexto.
+- Si el usuario quiere iniciar postulación o responde afirmativamente a una invitación a iniciarla, elige wizard.
+- Responde ÚNICAMENTE con el nombre del agente: {{ valid_names }}.
+- No agregues explicación ni puntuación, solo el nombre.

app/agents/prompts/supervisor_system.j2

@@ -0,0 +1 @@
+Eres un router experto. Respondes únicamente con el nombre del agente elegido, sin explicación.