# 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.