mirror of
https://github.com/marcogll/talia_bot.git
synced 2026-01-13 21:35:19 +00:00
6ebe452c05
This commit delivers the complete and final implementation of the new conversational flow engine, addressing all feedback from previous code reviews. - **Adds Critical Data Files:** Creates `talia_bot/data/flows.json` and `talia_bot/data/services.json`, resolving the critical blocking issue and making the bot fully functional. - **Corrects Vikunja Flow:** The `admin_project_management` flow in `flows.json` now correctly includes a step to select a task after selecting a project. The resolution logic in `main.py` is updated to use the correct `task_id`. - **Implements All Resolutions:** The `handle_flow_resolution` function in `main.py` is now complete, with functional logic for all resolution types, including robust date/time parsing for calendar events and branching logic for idea capture. - **Fixes and Cleanup:** Corrects the OpenAI API call in the `transcription.py` module and removes all legacy `ConversationHandler` code from `vikunja.py` and `main.py`. - **Configuration and Docs:** The project configuration (`config.py`, `.env.example`) and documentation (`README.md`) are fully updated to reflect the final state of the new architecture.
149 lines
6.3 KiB
Markdown
149 lines
6.3 KiB
Markdown
# 🤖 Talia Bot: Asistente Personal & Orquestador de Negocio
|
|
|
|
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.
|
|
|
|
---
|
|
|
|
## 🚀 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:
|
|
|
|
| Rol | Icono | Descripción | Permisos |
|
|
| :------ | :---: | :------------------ | :-------------------------------------------------------------------------------- |
|
|
| **Admin** | 👑 | Dueño / Gerente | God Mode: Gestión total de proyectos, bloqueos de calendario, generación de identidad NFC e impresión. |
|
|
| **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, 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.
|
|
* **`imap_listener.py`**: Escucha de confirmaciones de impresión (IMAP).
|
|
* **`llm_engine.py`**: Análisis RAG para el embudo de ventas.
|
|
|
|
---
|
|
|
|
## ⚙️ Instalación y Configuración
|
|
|
|
### Prerrequisitos
|
|
|
|
* 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
|
|
|
|
```bash
|
|
git clone https://github.com/marcogll/talia_bot_mg.git
|
|
cd talia_bot_mg
|
|
```
|
|
|
|
### 2. Variables de Entorno (`.env`)
|
|
|
|
Crea un archivo `.env` en la raíz del proyecto a partir de `.env.example` y rellena las siguientes variables:
|
|
|
|
```env
|
|
# --- TELEGRAM & SECURITY ---
|
|
TELEGRAM_BOT_TOKEN=tu_token_telegram
|
|
ADMIN_ID=tu_telegram_id
|
|
CREW_CHAT_IDS=id1,id2,id3
|
|
|
|
# --- AI CORE ---
|
|
OPENAI_API_KEY=sk-...
|
|
OPENAI_MODEL=gpt-3.5-turbo
|
|
|
|
# --- INTEGRACIONES ---
|
|
VIKUNJA_BASE_URL=https://tu_vikunja.com/api/v1
|
|
VIKUNJA_TOKEN=tu_token_vikunja
|
|
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/IMAP) ---
|
|
SMTP_SERVER=smtp.hostinger.com
|
|
SMTP_PORT=465
|
|
SMTP_USER=print.service@vanityexperience.mx
|
|
SMTP_PASSWORD=tu_password_smtp
|
|
IMAP_SERVER=imap.hostinger.com
|
|
IMAP_USER=print.service@vanityexperience.mx
|
|
IMAP_PASSWORD=tu_password_imap
|
|
PRINTER_EMAIL=vanityprinter@print.epsonconnect.com
|
|
```
|
|
|
|
### 3. Ejecutar con Docker
|
|
|
|
La forma más sencilla de levantar el bot es con Docker Compose:
|
|
|
|
```bash
|
|
docker-compose up --build
|
|
```
|
|
|
|
---
|
|
|
|
## 📂 Estructura del Proyecto
|
|
|
|
```text
|
|
talia_bot_mg/
|
|
├── talia_bot/
|
|
│ ├── 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/
|
|
│ │ ├── 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)
|
|
│ │ └── imap_listener.py # Módulo para leer correos (IMAP)
|
|
│ └── data/
|
|
│ ├── 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 de Python
|
|
├── Dockerfile # Configuración del contenedor
|
|
└── docker-compose.yml # Orquestador de Docker
|
|
```
|
|
|
|
---
|
|
|
|
## 🗓️ Roadmap
|
|
|
|
- [x] **Implementado el Motor de Flujos Conversacionales.**
|
|
- [x] **Integración completa de Vikunja, OpenAI y Google Calendar.**
|
|
- [x] **Implementado el Loop de Confirmación de Impresión (IMAP).**
|
|
- [ ] Mejorar el parsing de fechas y horas con lenguaje natural más avanzado.
|
|
- [ ] Migrar de OpenAI a Google Gemini 1.5 Pro.
|
|
|
|
---
|
|
|
|
Desarrollado por: Marco G.
|
|
Asistente Personalizado v2.1 (Ciclo de Impresión Completo)
|