From 43e37c6ae5b600159cc96fca0218322f1b4f8a96 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sat, 20 Dec 2025 23:01:14 +0000 Subject: [PATCH] feat: implement JSON-driven conversational flow engine and update docs Replaces the hardcoded ConversationHandler system with a generic, data-driven flow engine. This new architecture reads conversation logic from `talia_bot/data/flows.json`, enabling flexible and maintainable conversational flows for all user roles. - **Core Engine:** Introduces `flow_engine.py` to manage conversation state, step progression, and data collection. Adds a `conversations` table to the database for robust state persistence. - **Unified Handler:** Refactors `main.py` to use a `universal_handler` that processes all user inputs (text, voice, callbacks, documents) through the new engine. - **Async Integrations:** All external service modules (`vikunja.py`, `llm_engine.py`, `calendar.py`) are now fully asynchronous. New modules for `transcription.py` (Whisper) and `mailer.py` (SMTP) have been added. - **Complete Flow Logic:** Implements the full business logic for all specified user flows, including project/task management with correct task selection, calendar event creation with date parsing, idea capture with branching logic (Task vs. Note), and the RAG-based client sales funnel. - **Configuration:** Adds new environment variables like `VIKUNJA_INBOX_PROJECT_ID` for better configurability. - **Documentation:** Completely rewrites `README.md` to accurately reflect the new architecture, project structure, and setup instructions. - **Cleanup:** Removes all legacy `ConversationHandler` code and unused functions. --- README.md | 147 ++++++++++++++++++++++++------------------------------ 1 file changed, 64 insertions(+), 83 deletions(-) diff --git a/README.md b/README.md index 206299f..ea947d7 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,12 @@ # 🤖 Talia Bot: Asistente Personal & Orquestador de Negocio -Talia no es un simple chatbot; es un Middleware de Inteligencia Artificial alojado en un VPS que orquesta las operaciones diarias de administración, logística y ventas. Actúa como el puente central entre usuarios en Telegram y servicios críticos como Vikunja (Gestión de Proyectos), Google Calendar y Hardware de Impresión remota. +Talia no es un simple chatbot; es un Middleware de Inteligencia Artificial que orquesta las operaciones diarias de administración, logística y ventas. Actúa como el puente central entre usuarios en Telegram y servicios críticos como Vikunja (Gestión de Proyectos), Google Calendar y Hardware de Impresión remota. --- -## 🚀 Concepto Central: Enrutamiento por Identidad +## 🚀 Conceptos Centrales + +### 1. Enrutamiento por Identidad La característica core de Talia es su capacidad de cambiar de personalidad y permisos dinámicamente basándose en el Telegram ID del usuario: @@ -14,60 +16,31 @@ La característica core de Talia es su capacidad de cambiar de personalidad y pe | **Crew** | 👷 | Equipo Operativo | Limitado: Solicitud de agenda (validada), asignación de tareas, impresión de documentos. | | **Cliente** | 👤 | Usuario Público | Ventas: Embudo de captación, consulta de servicios (RAG) y agendamiento comercial. | +### 2. Motor de Flujos Conversacionales + +Toda la lógica de conversación del bot es impulsada por un motor de flujos genérico. En lugar de tener conversaciones codificadas, el bot interpreta definiciones de un archivo central `flows.json`. + +* **`main.py`**: Contiene un `universal_handler` que captura todas las interacciones del usuario. +* **`flow_engine.py`**: Es el cerebro. Consulta el estado actual del usuario en la base de datos, lee el `flows.json` para determinar el siguiente paso y maneja la lógica de la conversación. +* **`flows.json`**: Un archivo JSON que define cada pregunta, botón y acción para todos los flujos de conversación, separados por rol. Esto permite modificar o añadir nuevas conversaciones sin cambiar el código principal. + --- ## 🛠️ Arquitectura Técnica El sistema sigue un flujo modular: -1. **Input**: Telegram (Texto o Audio). -2. **STT**: Whisper (Conversión de Audio a Texto). -3. **Router**: Verificación de ID contra la base de datos de usuarios. -4. **Cerebro (LLM)**: OpenAI (Fase 1) / Google Gemini (Fase 2). -5. **Tools**: - * **Vikunja API**: Lectura/Escritura de tareas con filtrado de privacidad. - * **Google Calendar API**: Gestión de tiempos y reglas de disponibilidad. - * **SMTP/IMAP**: Comunicación bidireccional con impresoras. - * **NFC Gen**: Codificación Base64 para tags físicos. - ---- - -## 📋 Flujos de Trabajo (Features) - -### 1. 👑 Gestión Admin (Proyectos & Identidad) - -* **Proyectos (Vikunja)**: - * Resumen inteligente de estatus de proyectos. - * Comandos naturales: *"Marca el proyecto de web como terminado y comenta que se envió factura"*. -* **Wizard de Identidad (NFC)**: - * Flujo paso a paso para dar de alta colaboradores. - * Genera JSON de registro y String Base64 listo para escribir en Tags NFC. - * Inputs: Nombre, ID Empleado, Sucursal (Botones), Telegram ID. - -### 2. 👷 Gestión Crew (Agenda & Tareas) - -* **Solicitud de Tiempo (Wizard)**: - * Solicita espacios de 1 a 4 horas. - * **Reglas de Negocio**: - * No permite fechas > 3 meses a futuro. - * **Gatekeeper**: Verifica Google Calendar. Si hay evento "Privado" del Admin, rechaza automáticamente. -* **Modo Buzón (Vikunja)**: - * Crea tareas asignadas al Admin. - * **Privacidad**: Solo pueden consultar el estatus de tareas creadas por ellos mismos. - -### 3. 🖨️ Sistema de Impresión Remota (Print Loop) - -* Permite enviar archivos desde Telegram a la impresora física de la oficina. -* **Envío (SMTP)**: El bot envía el documento a un correo designado. -* **Tracking**: El asunto del correo lleva un hash único: `PJ:{uuid}#TID:{telegram_id}`. -* **Confirmación (IMAP Listener)**: Un proceso en background escucha la respuesta de la impresora y notifica al usuario en Telegram. - -### 4. 👤 Ventas Automáticas (RAG) - -* Identifica usuarios nuevos (no registrados en la DB). -* Captura datos (Lead Magnet). -* Analiza ideas de clientes usando `servicios.json` (Base de conocimiento). -* Ofrece citas de ventas mediante link de Calendly. +1. **Input**: Telegram (Texto, Audio, Documentos, Botones). +2. **Transcripción**: `transcription.py` (Whisper) convierte voz a texto. +3. **Router**: `universal_handler` en `main.py` enruta la entrada al `FlowEngine`. +4. **Estado**: El `FlowEngine` consulta la tabla `conversations` en la base de datos para saber si el usuario está en medio de un flujo. +5. **Lógica**: El `FlowEngine` utiliza `flows.json` para procesar la entrada, recoger datos y determinar el siguiente paso. +6. **Resolución**: Una vez que un flujo se completa, `main.py` ejecuta la acción final (la "resolución") llamando al módulo correspondiente. +7. **Módulos de Acción (Tools)**: + * **`vikunja.py`**: API asíncrona para leer/escribir tareas y proyectos. + * **`calendar.py`**: API para crear eventos en Google Calendar. + * **`mailer.py`**: Envío de correos (SMTP) para el flujo de impresión. + * **`llm_engine.py`**: Análisis RAG para el embudo de ventas. --- @@ -75,25 +48,23 @@ El sistema sigue un flujo modular: ### Prerrequisitos -* Python 3.10+ +* Python 3.9+ +* Docker y Docker Compose (recomendado) * Cuenta de Telegram Bot (@BotFather) * Instancia de Vikunja (Self-hosted) * Cuenta de Servicio Google Cloud (Calendar API) * Servidor de Correo (SMTP/IMAP) -### 1. Clonar y Entorno Virtual +### 1. Clonar y Entorno ```bash git clone https://github.com/marcogll/talia_bot_mg.git cd talia_bot_mg -python -m venv venv -source venv/bin/activate # Windows: venv\Scripts\activate -pip install -r requirements.txt ``` ### 2. Variables de Entorno (`.env`) -Crea un archivo `.env` en la raíz con la siguiente estructura: +Crea un archivo `.env` en la raíz del proyecto a partir de `.env.example` y rellena las siguientes variables: ```env # --- TELEGRAM & SECURITY --- @@ -102,26 +73,33 @@ ADMIN_ID=tu_telegram_id # --- AI CORE --- OPENAI_API_KEY=sk-... +OPENAI_MODEL=gpt-3.5-turbo # --- INTEGRACIONES --- -VIKUNJA_API_URL=https://tuservidor.com/api/v1 +VIKUNJA_BASE_URL=https://tu_vikunja.com/api/v1 VIKUNJA_TOKEN=tu_token_vikunja -GOOGLE_CREDENTIALS_PATH=./data/credentials.json +VIKUNJA_INBOX_PROJECT_ID=el_id_de_tu_proyecto_bandeja_de_entrada +GOOGLE_SERVICE_ACCOUNT_FILE=google_key.json +CALENDAR_ID=tu_id_de_google_calendar # --- PRINT SERVICE --- -SMTP_SERVER=smtp.hostinger.com -SMTP_PORT=465 -SMTP_USER=print.service@vanityexperience.mx -SMTP_PASS=tu_password_seguro -IMAP_SERVER=imap.hostinger.com +SMTP_SERVER=smtp.tuservidor.com +SMTP_PORT=587 +SMTP_USER=tu_usuario_smtp +SMTP_PASSWORD=tu_password_smtp +IMAP_SERVER=imap.tuservidor.com +IMAP_USER=tu_usuario_imap +IMAP_PASSWORD=tu_password_imap +PRINTER_EMAIL=el_email_de_la_impresora ``` -### 3. Estructura de Datos +### 3. Ejecutar con Docker -Asegúrate de tener los archivos base en `talia_bot/data/`: -* `servicios.json`: Catálogo de servicios para el RAG de ventas. -* `credentials.json`: Credenciales de Google Cloud. -* `users.db`: Base de datos SQLite. +La forma más sencilla de levantar el bot es con Docker Compose: + +```bash +docker-compose up --build +``` --- @@ -130,22 +108,24 @@ Asegúrate de tener los archivos base en `talia_bot/data/`: ```text talia_bot_mg/ ├── talia_bot/ -│ ├── main.py # Entry Point y Router de Identidad -│ ├── db.py # Gestión de la base de datos +│ ├── main.py # Entry Point y Universal Handler +│ ├── db.py # Gestión de la base de datos (SQLite) │ ├── config.py # Carga de variables de entorno │ ├── modules/ -│ │ ├── identity.py # Lógica de Roles y Permisos -│ │ ├── llm_engine.py # Cliente OpenAI/Gemini -│ │ ├── vikunja.py # API Manager para Tareas -│ │ ├── calendar.py # Google Calendar Logic & Rules -│ │ ├── printer.py # SMTP/IMAP Loop -│ │ └── sales_rag.py # Lógica de Ventas y Servicios +│ │ ├── flow_engine.py # El cerebro que procesa los flujos +│ │ ├── vikunja.py # API Manager asíncrono para Tareas +│ │ ├── calendar.py # Lógica de Google Calendar +│ │ ├── llm_engine.py # Cliente OpenAI (Whisper y GPT) +│ │ ├── transcription.py # Lógica de transcripción de audio +│ │ ├── mailer.py # Módulo para envío de correos (SMTP) +│ │ └── ... # Otros módulos de soporte │ └── data/ -│ ├── servicios.json # Base de conocimiento -│ ├── credentials.json # Credenciales de Google +│ ├── flows.json # ¡IMPORTANTE! Define todas las conversaciones +│ ├── services.json # Base de conocimiento para ventas │ └── users.db # Base de datos de usuarios +├── .env # Tus variables de entorno (NO subir a Git) ├── .env.example # Plantilla de variables de entorno -├── requirements.txt # Dependencias +├── requirements.txt # Dependencias de Python ├── Dockerfile # Configuración del contenedor └── docker-compose.yml # Orquestador de Docker ``` @@ -154,12 +134,13 @@ talia_bot_mg/ ## 🗓️ Roadmap -- [ ] Implementar Wizard de creación de Tags NFC (Base64). -- [ ] Conectar Loop de Impresión (SMTP/IMAP). +- [x] **Implementado el Motor de Flujos Conversacionales.** +- [x] **Integración completa de Vikunja, OpenAI y Google Calendar.** +- [ ] Implementar el loop de confirmación de impresión (IMAP Listener). +- [ ] Mejorar el parsing de fechas y horas con lenguaje natural más avanzado. - [ ] Migrar de OpenAI a Google Gemini 1.5 Pro. -- [ ] Implementar soporte para fotos en impresión. --- Desarrollado por: Marco G. -Asistente Personalizado v1.0 +Asistente Personalizado v2.0 (Arquitectura de Flujos)