mirror of
https://github.com/marcogll/talia_bot.git
synced 2026-01-13 21:35: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.
142 lines
7.2 KiB
Markdown
142 lines
7.2 KiB
Markdown
# Agent_skills.md
|
|
|
|
Este documento detalla las capacidades técnicas, reglas de negocio y límites de cada agente definido en `AGENTS.md`.
|
|
|
|
---
|
|
|
|
### 1. Agente Recepcionista (`main.py`)
|
|
|
|
- **Capacidades Técnicas**:
|
|
- **Framework**: `python-telegram-bot`.
|
|
- **Manejo de Eventos**: Utiliza `CommandHandler`, `CallbackQueryHandler`, `MessageHandler` para registrar y procesar diferentes tipos de actualizaciones de Telegram.
|
|
- **Inyección de Dependencias**: Almacena instancias compartidas (como `FlowEngine`) en el `bot_data` del contexto de la aplicación para que estén disponibles globalmente.
|
|
|
|
- **Reglas de Negocio**:
|
|
- El comando `/start` siempre debe borrar cualquier estado de conversación previo del usuario para asegurar un inicio limpio.
|
|
- Los documentos (`filters.Document.ALL`) se enrutan exclusivamente al manejador de impresión.
|
|
- Los mensajes de texto y voz se enrutan al `text_and_voice_handler`, que a su vez los delega al motor de flujos.
|
|
|
|
- **Límites Claros**:
|
|
- No implementa lógica de reintentos para comandos fallidos.
|
|
- No contiene estado. El estado se gestiona en la base de datos a través de otros agentes.
|
|
|
|
---
|
|
|
|
### 2. Agente de Identidad (`identity.py`, `db.py`)
|
|
|
|
- **Capacidades Técnicas**:
|
|
- **Base de Datos**: `SQLite`.
|
|
- **Conexión**: Utiliza `sqlite3` para conectarse a la base de datos `users.db`.
|
|
- **Modelo de Datos**: La tabla `users` contiene `chat_id` (INTEGER, PRIMARY KEY) y `role` (TEXT).
|
|
|
|
- **Reglas de Negocio**:
|
|
- Un `chat_id` solo puede tener un rol.
|
|
- Si un usuario no se encuentra en la base de datos, se le asigna el rol de `client` por defecto.
|
|
- Los roles válidos son `admin`, `crew`, y `client`. Cualquier otro valor se trata como `client`.
|
|
|
|
- **Límites Claros**:
|
|
- No gestiona la adición o eliminación de usuarios. Esto debe hacerse manualmente en la base de datos por ahora.
|
|
- No ofrece permisos granulares, solo los tres roles definidos.
|
|
|
|
---
|
|
|
|
### 3. Agente de Motor de Flujos (`flow_engine.py`)
|
|
|
|
- **Capacidades Técnicas**:
|
|
- **Serialización**: Lee y parsea archivos `.json` para definir la estructura de las conversaciones.
|
|
- **Persistencia de Estado**: Utiliza `SQLite` para almacenar y recuperar el estado de la conversación de cada usuario en la tabla `conversations`.
|
|
- **Arquitectura**: Máquina de estados finitos donde cada paso de la conversación es un estado.
|
|
|
|
- **Reglas de Negocio**:
|
|
- Cada flujo debe tener un `id` único y una clave `role` que restringe su acceso.
|
|
- Los pasos se ejecutan en orden secuencial según su `step_id`.
|
|
- Al final de un flujo, se puede invocar una función de "finalización" (ej. `generate_sales_pitch`) para procesar los datos recopilados.
|
|
|
|
- **Límites Claros**:
|
|
- No soporta bifurcaciones complejas (condicionales) en los flujos. La lógica es estrictamente lineal.
|
|
- No tiene un mecanismo de "timeout". Las conversaciones pueden permanecer activas indefinidamente hasta que el usuario las complete o las reinicie.
|
|
|
|
---
|
|
|
|
### 4. Agente de Onboarding y Menús (`onboarding.py`)
|
|
|
|
- **Capacidades Técnicas**:
|
|
- **Framework**: `python-telegram-bot`.
|
|
- **UI**: Construye menús utilizando `InlineKeyboardMarkup` y `InlineKeyboardButton`.
|
|
|
|
- **Reglas de Negocio**:
|
|
- Debe mostrar un menú específico para cada uno de los tres roles (`admin`, `crew`, `client`).
|
|
- **Fallo Actual**: Los menús son estáticos y no se generan a partir de los flujos disponibles, lo que impide el acceso a flujos que sí existen.
|
|
|
|
- **Límites Claros**:
|
|
- No puede mostrar menús que dependan del estado del usuario (ej. un botón diferente si el usuario ya ha completado una tarea).
|
|
|
|
---
|
|
|
|
### 5. Agente de Agenda (`calendar.py`, `agenda.py`, `aprobaciones.py`)
|
|
|
|
- **Capacidades Técnicas**:
|
|
- **Integraciones**: API de Google Calendar (`googleapiclient`).
|
|
- **Autenticación**: Utiliza una cuenta de servicio de Google Cloud con un archivo `google_key.json`.
|
|
- **Manejo de Fechas**: Utiliza la librería `datetime` para manejar zonas horarias y rangos de tiempo.
|
|
|
|
- **Reglas de Negocio**:
|
|
- El tiempo personal (del `PERSONAL_GOOGLE_CALENDAR_ID`) es prioritario y se considera "ocupado" e inamovible.
|
|
- Los eventos propuestos por el `crew` solo deben enviarse a Google Calendar después de ser aprobados por un `admin`.
|
|
- Una vez que una actividad es rechazada, su estado debe persistir y no debe volver a mostrarse como "pendiente".
|
|
- **Fallo Actual**: El código ignora los diferentes IDs de calendario y solo usa uno genérico, rompiendo la separación entre personal y trabajo.
|
|
|
|
- **Límites Claros**:
|
|
- No puede modificar eventos existentes, solo crearlos.
|
|
- La lógica de aprobación es binaria (aprobar/rechazar) y no permite re-programación o negociación.
|
|
|
|
---
|
|
|
|
### 6. Agente de Impresión (`printer.py`)
|
|
|
|
- **Capacidades Técnicas**:
|
|
- **Protocolos de Red**: `SMTP` para enviar correos y `IMAP` para leerlos.
|
|
- **Librerías**: `smtplib` y `imaplib` de la biblioteca estándar de Python.
|
|
- **Manejo de Archivos**: Descarga temporalmente los archivos de Telegram al disco antes de enviarlos.
|
|
|
|
- **Reglas de Negocio**:
|
|
- Solo los usuarios con rol `admin` pueden usar esta función (verificación de permisos).
|
|
- El estado se determina buscando palabras clave (ej. "completed", "failed") en los asuntos de los correos no leídos.
|
|
|
|
- **Límites Claros**:
|
|
- No maneja la impresión de imágenes, solo documentos.
|
|
- No tiene un sistema de cola. Las solicitudes se procesan de forma síncrona.
|
|
|
|
---
|
|
|
|
### 7. Agente de RAG y Ventas (`sales_rag.py`, `llm_engine.py`)
|
|
|
|
- **Capacidades Técnicas**:
|
|
- **Integraciones**: API de OpenAI.
|
|
- **Procesamiento de Lenguaje Natural (PLN)**: Realiza una búsqueda simple de palabras clave en `services.json` para encontrar contexto relevante.
|
|
- **Generación de Prompts**: Construye un prompt detallado para el LLM a partir de una plantilla y los datos recopilados del usuario.
|
|
|
|
- **Reglas de Negocio**:
|
|
- La regla "sin contexto, no hay respuesta" es obligatoria. Si la búsqueda en `services.json` no arroja resultados, el agente debe detenerse.
|
|
- **Fallo Actual**: Esta regla no se está aplicando, lo que resulta in respuestas genéricas.
|
|
|
|
- **Límites Claros**:
|
|
- El mecanismo de "retrieval" (recuperación) es una búsqueda de palabras clave, no un sistema de embeddings vectoriales. Su precisión es limitada.
|
|
- No mantiene memoria de interacciones pasadas con el cliente.
|
|
|
|
---
|
|
|
|
### 8. Agente de Transcripción (Whisper)
|
|
|
|
- **Capacidades Técnicas**:
|
|
- **Integraciones Futuras**: API de OpenAI (Whisper).
|
|
- **Manejo de Medios**: Deberá poder descargar archivos de audio de Telegram y enviarlos como una solicitud `multipart/form-data`.
|
|
|
|
- **Reglas de Negocio**:
|
|
- Debe ser capaz de manejar diferentes formatos de audio si Telegram los proporciona.
|
|
- Debe tener un manejo de errores para cuando la transcripción falle.
|
|
|
|
- **Límites Claros**:
|
|
- **Estado Actual**: No implementado. El `text_and_voice_handler` contiene una respuesta placeholder.
|
|
- No está diseñado para la traducción, solo para la transcripción del idioma hablado.
|