mirror of
https://github.com/marcogll/talia_bot.git
synced 2026-01-13 21:35:19 +00:00
docs: Update README.md to reflect current architecture
This commit provides a comprehensive update to the README.md file. The previous version was outdated and did not accurately represent the project's structure or architecture after the implementation of the JSON-based flow engine. Key changes: - Rewrites the "Arquitectura Técnica" section to be simpler and more accurate. - Updates the "Estructura del Proyecto" diagram to be a perfect representation of the current file and module structure. - Corrects the `git clone` URL in the installation instructions. - Harmonizes file names (e.g., `google_key.json`) across the documentation and configuration to avoid confusion. - Simplifies and clarifies the setup and execution instructions.
This commit is contained in:
google-labs-jules[bot]
186
README.md
186
README.md
@@ -1,73 +1,34 @@
|
||||
# 🤖 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 es un **Middleware de Inteligencia Artificial** diseñado para orquestar operaciones de negocio a través de Telegram. Funciona como un asistente personal que responde a roles de usuario específicos, conectando servicios externos como **Vikunja (Gestión de Proyectos)** y **Google Calendar** en una única interfaz conversacional.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Concepto Central: Enrutamiento por Identidad
|
||||
## 🚀 Concepto Central: Arquitectura Modular y Roles de Usuario
|
||||
|
||||
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:
|
||||
La funcionalidad del bot se basa en dos pilares:
|
||||
|
||||
| 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. |
|
||||
1. **Enrutamiento por Identidad**: El bot identifica a cada usuario por su Telegram ID y le asigna un rol (`admin`, `crew`, `client`). Cada rol tiene acceso a un conjunto diferente de funcionalidades y menús, definidos en una base de datos SQLite.
|
||||
2. **Motor de Flujos de Conversación**: En lugar de código rígido, las conversaciones se definen como "flujos" en archivos **JSON** (`talia_bot/data/flows/`). Un motor central (`flow_engine.py`) interpreta estos archivos para guiar al usuario a través de una serie de preguntas y respuestas, haciendo que el sistema sea altamente escalable y fácil de mantener.
|
||||
|
||||
| Rol | Icono | Descripción | Permisos Clave |
|
||||
| :------ | :---: | :------------------ | :-------------------------------------------------------------------------- |
|
||||
| **Admin** | 👑 | Dueño / Gerente | Control total: gestión de proyectos, agenda, y configuración del sistema. |
|
||||
| **Crew** | 👷 | Equipo Operativo | Funciones limitadas: solicitud de agenda, impresión de documentos. |
|
||||
| **Cliente** | 👤 | Usuario Externo | Embudo de ventas: captación de datos y presentación de servicios. |
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Arquitectura Técnica
|
||||
## 🛠️ Arquitectura Técnica Simplificada
|
||||
|
||||
El sistema sigue un flujo modular:
|
||||
El sistema opera con el siguiente flujo:
|
||||
|
||||
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. **Recepción de Mensajes**: `main.py` recibe todos los inputs (texto, botones, comandos) desde Telegram.
|
||||
2. **Identificación de Usuario**: Se consulta la base de datos (`users.db`) para obtener el rol del usuario.
|
||||
3. **Dispatching de Acciones**:
|
||||
* Si el usuario no está en una conversación, se le muestra un menú de botones basado en los flujos JSON disponibles para su rol.
|
||||
* Si el usuario ya está en una conversación, el `flow_engine.py` gestiona la respuesta.
|
||||
4. **Ejecución de Módulos**: El motor de flujos invoca módulos específicos (`vikunja.py`, `calendar.py`, etc.) para interactuar con APIs externas según sea necesario.
|
||||
|
||||
---
|
||||
|
||||
@@ -75,79 +36,96 @@ El sistema sigue un flujo modular:
|
||||
|
||||
### Prerrequisitos
|
||||
|
||||
* Python 3.10+
|
||||
* Python 3.9+
|
||||
* Docker y Docker Compose
|
||||
* Cuenta de Telegram Bot (@BotFather)
|
||||
* Instancia de Vikunja (Self-hosted)
|
||||
* Cuenta de Servicio Google Cloud (Calendar API)
|
||||
* Servidor de Correo (SMTP/IMAP)
|
||||
* Credenciales de Cuenta de Servicio de Google Cloud (para Calendar API)
|
||||
|
||||
### 1. Clonar y Entorno Virtual
|
||||
### 1. Clonar y Configurar el 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
|
||||
# Clona el repositorio oficial
|
||||
git clone https://github.com/marcogll/talia_bot.git
|
||||
cd talia_bot
|
||||
|
||||
# Copia el archivo de ejemplo para las variables de entorno
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
### 2. Variables de Entorno (`.env`)
|
||||
|
||||
Crea un archivo `.env` en la raíz con la siguiente estructura:
|
||||
Abre el archivo `.env` y rellena las siguientes variables. **No subas este archivo a Git.**
|
||||
|
||||
```env
|
||||
# --- TELEGRAM & SECURITY ---
|
||||
TELEGRAM_BOT_TOKEN=tu_token_telegram
|
||||
# Token de tu bot de Telegram
|
||||
TELEGRAM_TOKEN=tu_token_telegram
|
||||
|
||||
# Tu Telegram ID numérico para permisos de administrador
|
||||
ADMIN_ID=tu_telegram_id
|
||||
|
||||
# --- AI CORE ---
|
||||
# Clave de API de OpenAI (si se usa)
|
||||
OPENAI_API_KEY=sk-...
|
||||
|
||||
# --- INTEGRACIONES ---
|
||||
VIKUNJA_API_URL=https://tuservidor.com/api/v1
|
||||
# URL y Token de tu instancia de Vikunja
|
||||
VIKUNJA_API_URL=https://tu_vikunja.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
|
||||
# ID del Calendario de Google a gestionar
|
||||
CALENDAR_ID=tu_id_de_calendario@group.calendar.google.com
|
||||
|
||||
# Ruta al archivo de credenciales de Google Cloud.
|
||||
# Este archivo debe estar en el directorio raíz y se llama 'google_key.json' por defecto.
|
||||
GOOGLE_SERVICE_ACCOUNT_FILE=./google_key.json
|
||||
```
|
||||
|
||||
### 3. Estructura de Datos
|
||||
### 3. Estructura de Datos y Credenciales
|
||||
|
||||
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.
|
||||
* **Base de Datos**: La base de datos `users.db` se creará automáticamente si no existe. Para asignar roles, debes agregar manualmente los Telegram IDs en la tabla `users`.
|
||||
* **Credenciales de Google**: Coloca tu archivo de credenciales de la cuenta de servicio de Google Cloud en el directorio raíz del proyecto y renómbralo a `google_key.json`. **El archivo `.gitignore` ya está configurado para ignorar este archivo y proteger tus claves.**
|
||||
* **Flujos de Conversación**: Para modificar o añadir flujos, edita los archivos JSON en `talia_bot/data/flows/`.
|
||||
|
||||
### 4. Ejecución con Docker
|
||||
|
||||
La forma más sencilla de levantar el bot es usando Docker Compose:
|
||||
|
||||
```bash
|
||||
docker-compose up --build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📂 Estructura del Proyecto
|
||||
|
||||
```text
|
||||
talia_bot_mg/
|
||||
talia_bot/
|
||||
├── .env # (Local) Variables de entorno y secretos
|
||||
├── .env.example # Plantilla de variables de entorno
|
||||
├── .gitignore # Archivos ignorados por Git
|
||||
├── Dockerfile # Define el contenedor de la aplicación
|
||||
├── docker-compose.yml # Orquesta el servicio del bot
|
||||
├── google_key.json # (Local) Credenciales de Google Cloud
|
||||
├── requirements.txt # Dependencias de Python
|
||||
├── talia_bot/
|
||||
│ ├── main.py # Entry Point y Router de Identidad
|
||||
│ ├── db.py # Gestión de la base de datos
|
||||
│ ├── 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
|
||||
│ └── data/
|
||||
│ ├── servicios.json # Base de conocimiento
|
||||
│ ├── 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
|
||||
│ ├── __init__.py
|
||||
│ ├── main.py # Entry point, dispatcher y handlers de Telegram
|
||||
│ ├── db.py # Lógica de la base de datos SQLite
|
||||
│ ├── config.py # Carga y validación de variables de entorno
|
||||
│ ├── scheduler.py # (Futuro) Tareas programadas
|
||||
│ ├── webhook_client.py # (Futuro) Cliente para webhooks externos
|
||||
│ ├── data/
|
||||
│ │ ├── flows/ # Directorio con flujos de conversación en JSON
|
||||
│ │ ├── services.json # Base de conocimiento para ventas
|
||||
│ │ └── users.db # Base de datos de usuarios
|
||||
│ └── modules/
|
||||
│ ├── __init__.py
|
||||
│ ├── flow_engine.py # Motor que interpreta los flujos JSON
|
||||
│ ├── calendar.py # Integración con Google Calendar API
|
||||
│ ├── vikunja.py # Integración con Vikunja API
|
||||
│ ├── onboarding.py # Lógica para el alta de nuevos usuarios
|
||||
│ ├── llm_engine.py # (Opcional) Cliente para OpenAI/Gemini
|
||||
│ └── ... (otros módulos)
|
||||
└── ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user