mirror of
https://github.com/marcogll/talia_bot.git
synced 2026-01-13 13:25:19 +00:00
238baa7211
This commit fixes a critical `ImportError` that prevented the bot from starting. The error was caused by the `agenda.py` module attempting to import calendar ID variables that were not being loaded into the application's configuration. The fix involves: - Updating `talia_bot/config.py` to correctly load the `WORK_GOOGLE_CALENDAR_ID` and `PERSONAL_GOOGLE_CALENDAR_ID` from the environment. - Removing the obsolete `CALENDAR_ID` variable from the configuration. - Updating `talia_bot/modules/calendar.py` to import and use the new, more specific `WORK_GOOGLE_CALENDAR_ID` as its default, ensuring consistency with the rest of the application.
159 lines
6.7 KiB
Markdown
159 lines
6.7 KiB
Markdown
# 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í.
|