mirror of
https://github.com/marcogll/talia_bot.git
synced 2026-01-13 21:35:19 +00:00
4750ddf43d
This commit introduces a modular, JSON-driven conversational flow engine. Key changes: - Adds `talia_bot/modules/flow_engine.py` to manage loading and processing conversational flows from external files. - Separates all conversational logic into individual JSON files within `talia_bot/data/flows/`, organized by user role (admin, crew, client). - Updates `talia_bot/main.py` to use the new flow engine, replacing the previous hardcoded logic with a dynamic dispatcher. - Corrects the `.gitignore` file to properly track the new JSON flow files while ensuring sensitive credentials like `google_key.json` remain ignored. - Updates the `README.md` to reflect the new architecture, providing clear documentation for the modular flow system. This new architecture makes the bot more maintainable and scalable by decoupling the conversation logic from the core application code.
171 lines
7.0 KiB
Markdown
171 lines
7.0 KiB
Markdown
# 🤖 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.
|
|
|
|
---
|
|
|
|
## 🚀 Concepto Central: 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. |
|
|
|
|
---
|
|
|
|
## 🛠️ 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 Modulares (Features)
|
|
|
|
El comportamiento del bot se define a través de **flujos de conversación modulares** gestionados por un motor central (`flow_engine.py`). Cada flujo es un archivo `.json` independiente ubicado en `talia_bot/data/flows/`, lo que permite modificar o crear nuevas conversaciones sin alterar el código principal.
|
|
|
|
### 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.
|
|
|
|
---
|
|
|
|
## ⚙️ Instalación y Configuración
|
|
|
|
### Prerrequisitos
|
|
|
|
* Python 3.10+
|
|
* 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
|
|
|
|
```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:
|
|
|
|
```env
|
|
# --- TELEGRAM & SECURITY ---
|
|
TELEGRAM_BOT_TOKEN=tu_token_telegram
|
|
ADMIN_ID=tu_telegram_id
|
|
|
|
# --- AI CORE ---
|
|
OPENAI_API_KEY=sk-...
|
|
|
|
# --- INTEGRACIONES ---
|
|
VIKUNJA_API_URL=https://tuservidor.com/api/v1
|
|
VIKUNJA_TOKEN=tu_token_vikunja
|
|
GOOGLE_CREDENTIALS_PATH=./data/credentials.json
|
|
|
|
# --- 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
|
|
```
|
|
|
|
### 3. Estructura de Datos
|
|
|
|
Asegúrate de tener los archivos y directorios 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 que almacena los roles de los usuarios.
|
|
* `flows/`: Directorio que contiene las definiciones de los flujos de conversación en formato JSON. Cada archivo representa una conversación completa para un rol específico.
|
|
|
|
---
|
|
|
|
## 📂 Estructura del Proyecto
|
|
|
|
```text
|
|
talia_bot_mg/
|
|
├── talia_bot/
|
|
│ ├── main.py # Entry Point y dispatcher principal
|
|
│ ├── db.py # Gestión de la base de datos SQLite
|
|
│ ├── config.py # Carga de variables de entorno
|
|
│ ├── modules/
|
|
│ │ ├── flow_engine.py # Motor de flujos de conversación (lee los JSON)
|
|
│ │ ├── 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
|
|
│ └── data/
|
|
│ ├── flows/ # Directorio con los flujos de conversación en JSON
|
|
│ ├── servicios.json # Base de conocimiento para ventas
|
|
│ ├── credentials.json # Credenciales de Google
|
|
│ └── users.db # Base de datos de usuarios
|
|
├── .env.example # Plantilla de variables de entorno
|
|
├── requirements.txt # Dependencias
|
|
├── Dockerfile # Configuración del contenedor
|
|
└── docker-compose.yml # Orquestador de Docker
|
|
```
|
|
|
|
---
|
|
|
|
## 🗓️ Roadmap
|
|
|
|
- [ ] Implementar Wizard de creación de Tags NFC (Base64).
|
|
- [ ] Conectar Loop de Impresión (SMTP/IMAP).
|
|
- [ ] Migrar de OpenAI a Google Gemini 1.5 Pro.
|
|
- [ ] Implementar soporte para fotos en impresión.
|
|
|
|
---
|
|
|
|
Desarrollado por: Marco G.
|
|
Asistente Personalizado v1.0
|