mirror of
https://github.com/marcogll/talia_bot.git
synced 2026-01-13 13:25:19 +00:00
81efa4babd
This commit addresses critical issues in the Talia Bot system, including fixing missing admin flows, correcting agenda privacy logic, implementing voice message transcription, and enforcing RAG guardrails. Key changes include: - Modified the onboarding module to dynamically generate admin menus from available JSON flows, making all admin functions accessible. - Updated the agenda module to correctly use separate work and personal Google Calendar IDs, ensuring privacy and accurate availability. - Implemented audio transcription using the OpenAI Whisper API, replacing placeholder logic and enabling multimodal interaction. - Reworked the sales RAG module to prevent it from generating generic responses when it lacks sufficient context. Additionally, this commit introduces comprehensive documentation as requested: - `AGENTS.md`: Defines the roles and responsibilities of each system agent. - `Agent_skills.md`: Details the technical capabilities and business rules for each agent. - `plan_de_pruebas.md`: Provides a step-by-step test plan to verify the fixes. - `reparacion_vs_refactor.md`: Outlines the immediate repairs performed and proposes a strategic, incremental plan for long-term architectural improvements.
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í.
|