talia_bot/AGENTS.md

AGENTS.md

Este documento define los agentes que componen el sistema Talia Bot y sus responsabilidades. Un "agente" es un componente de software con un propósito claro y un conjunto de responsabilidades definidas.

---

1. Agente Recepcionista (main.py)

Es el punto de entrada principal del sistema. Actúa como el primer filtro para todas las interacciones del usuario.

• Responsabilidades:

  • Recibir todas las actualizaciones de Telegram (mensajes de texto, comandos, clics en botones, documentos, mensajes de voz).
  • Inicializar y registrar todos los manejadores de comandos y mensajes.
  • Delegar las actualizaciones al agente o manejador correspondiente.
  • Gestionar el ciclo de vida de la aplicación.

• Flujos que Maneja:

  • Comandos (/start, /reset, /check_print_status).
  • Recepción de documentos para el Agente de Impresión.
  • Mensajes de texto y voz para el Agente de Motor de Flujos.
  • Clics en botones para el Despachador de Botones.

• Flujos que NO Debe Manejar:

  • No debe contener lógica de negocio compleja. Su única función es enrutar.
  • No debe gestionar el estado de una conversación.

---

2. Agente de Identidad (identity.py, db.py)

Este agente es responsable de conocer "quién" es el usuario y qué permisos tiene.

• Responsabilidades:

  • Consultar la base de datos users.db para obtener el rol de un usuario (admin, crew, client) a partir de su chat_id.
  • Proporcionar esta información a otros agentes para que puedan tomar decisiones de enrutamiento y acceso.

• Flujos que Maneja:

  • Verificación de rol en el comando /start.
  • Verificación de permisos para acceder a flujos específicos.

• Flujos que NO Debe Manejar:

  • No gestiona la lógica de las conversaciones.
  • No interactúa con APIs externas.

---

3. Agente de Motor de Flujos (flow_engine.py)

Es el cerebro de las conversaciones de múltiples pasos. Orquesta la interacción con el usuario basándose en definiciones declarativas.

• Responsabilidades:

  • Cargar todas las definiciones de flujo desde los archivos .json en el directorio data/flows/.
  • Gestionar el estado de la conversación de cada usuario (qué flujo está activo, en qué paso está y qué datos ha recopilado).
  • Persistir y recuperar el estado de la conversación desde la base de datos.
  • Ejecutar acciones de finalización cuando un flujo se completa (ej. generar un pitch de ventas).

• Flujos que Maneja:

  • Cualquier conversación definida en un archivo .json (ej. client_sales_funnel, admin_create_nfc_tag).

• Flujos que NO Debe Manejar:

  • Acciones simples que no requieren una conversación de varios pasos (ej. view_agenda).
  • La generación del menú inicial de opciones.

---

4. Agente de Onboarding y Menús (onboarding.py)

Este agente es responsable de la primera impresión y de la navegación principal del usuario.

• Responsabilidades:

  • Presentar el mensaje de bienvenida y el menú de opciones principal al usuario cuando ejecuta /start.
  • Generar los menús de botones específicos para cada rol (admin, crew, client).
  • Observación (Fallo Detectado): Actualmente, los menús son estáticos y hardcodeados, contrario a la documentación.

• Flujos que Maneja:

  • La experiencia inicial del usuario.
  • La visualización de las opciones de primer nivel.

• Flujos que NO Debe Manejar:

  • La ejecución de los flujos de conversación. Solo debe proporcionar los botones para iniciarlos.

---

5. Agente de Agenda (calendar.py, agenda.py, aprobaciones.py)

Gestiona toda la lógica relacionada con la programación, consulta y aprobación de eventos.

• Responsabilidades:

  • Interactuar con la API de Google Calendar.
  • Diferenciar entre la agenda de trabajo y la agenda personal. El tiempo personal debe ser tratado como bloqueado e inamovible por defecto.
  • Mostrar al administrador únicamente sus propios eventos.
  • Gestionar el estado de las solicitudes de actividades (pendiente, aprobada, rechazada).
  • Asegurar que las actividades rechazadas no vuelvan a aparecer como pendientes.

• Flujos que Maneja:

  • view_agenda
  • view_pending
  • propose_activity
  • Aprobación y rechazo de eventos.

• Flujos que NO Debe Manejar:

  • Gestión de tareas (esa es responsabilidad del Agente de Tareas).
  • Conversaciones no relacionadas con la agenda.

---

6. Agente de Impresión (printer.py)

Este agente gestiona la funcionalidad de impresión remota.

• Responsabilidades:

  • Recibir un archivo desde Telegram.
  • Enviar el archivo como adjunto por correo electrónico (SMTP) a la dirección de la impresora.
  • Consultar el estado de los trabajos de impresión mediante la revisión de una bandeja de entrada de correo (IMAP).
  • Informar al usuario sobre el estado de la impresión.

• Flujos que Maneja:

  • Recepción de documentos.
  • /check_print_status

• Flujos que NO Debe Manejar:

  • Cualquier interacción que no sea enviar un archivo o consultar el estado.

---

7. Agente de RAG y Ventas (sales_rag.py, llm_engine.py)

Es responsable del embudo de ventas para nuevos clientes, utilizando un modelo de lenguaje para generar respuestas personalizadas.

• Responsabilidades:

  • Ejecutar el flujo de conversación client_sales_funnel.
  • Recuperar información relevante de la base de conocimiento (services.json).
  • Construir un prompt enriquecido con el contexto del cliente y la información de los servicios.
  • Invocar al modelo de lenguaje (OpenAI) para generar una propuesta de ventas.
  • Regla Obligatoria: Si no se encuentra contexto relevante en la base de conocimiento, NO debe generar una respuesta genérica. Debe informar que no puede ayudar.

• Flujos que Maneja:

  • client_sales_funnel

• Flujos que NO Debe Manejar:

  • Conversaciones que no estén relacionadas con el proceso de ventas.

---

8. Agente de Transcripción (Whisper)

Estado: Inexistente. Este agente es requerido pero no está implementado.

• Responsabilidades Futuras:

  • Recibir un archivo de audio (mensaje de voz) de Telegram.
  • Enviar el audio a la API de Whisper para su transcripción.
  • Devolver el texto transcrito al text_and_voice_handler para que sea procesado por el Agente de Motor de Flujos.

• Flujos que Maneja:

  • La conversión de voz a texto dentro de cualquier flujo de conversación.

• Flujos que NO Debe Manejar:

  • La lógica de la conversación en sí.