🤖 Talia Bot: Asistente Personal & Orquestador de Negocio

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: Arquitectura de Agente Autónomo

El bot opera como un agente que sigue un ciclo de Recepción -> Identificación -> Enrutamiento -> Ejecución.

1. Recepción de Mensajes: bot/main.py actúa como el punto de entrada que recibe todos los inputs (texto, botones, comandos, documentos) desde Telegram.
2. Identificación de Usuario: Al recibir un mensaje, el módulo identity.py consulta la base de datos (users.db) para obtener el rol del usuario (admin, crew, client).
3. Enrutamiento de Acciones:
   • Si el usuario está en una conversación activa, el flow_engine.py toma el control y procesa la respuesta según la definición del flujo JSON correspondiente.
   • Si el usuario no está en una conversación, el sistema le muestra un menú de botones. Estos menús se generan dinámicamente a partir de los archivos de flujo en bot/data/flows/ que tienen una clave "trigger_button".
4. Ejecución de Módulos: Dependiendo de la acción, se invocan módulos específicos para interactuar con APIs externas:
   • sales_rag.py para generar respuestas de ventas con IA.
   • printer.py para enviar correos de impresión.
   • vikunja.py para gestionar tareas.
   • calendar.py para consultar la agenda.

Rol	Icono	Descripción	Permisos Clave
Admin	👑	Dueño / Gerente	Control total: gestión de proyectos, agenda, impresión y configuración del sistema.
Crew	👷	Equipo Operativo	Funciones limitadas: solicitud de agenda y consulta de tareas.
Cliente	👤	Usuario Externo	Embudo de ventas: captación de datos y generación de propuestas con IA.

---

📋 Flujos de Trabajo y Funcionalidades Clave

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 que define una conversación paso a paso, permitiendo una fácil personalización.

1. 🤖 Flujo de Ventas RAG (Retrieval-Augmented Generation)

Este es el embudo de ventas principal para nuevos clientes. El bot inicia una conversación para entender las necesidades del prospecto y luego utiliza un modelo de IA para generar una propuesta personalizada.

• Recopilación de Datos: El flujo (client_sales_funnel.json) guía al usuario a través de una serie de preguntas para recopilar su nombre, industria y la descripción de su proyecto.
• Recuperación de Conocimiento (Retrieval): El sistema consulta una base de datos de servicios (servicios.json) para encontrar las soluciones más relevantes basadas en las palabras clave del cliente.
• Generación Aumentada (Augmented Generation): Con la información del cliente y los servicios relevantes, el bot construye un prompt detallado y lo envía al llm_engine (conectado a OpenAI). El modelo de lenguaje genera una respuesta que conecta las necesidades del cliente con los servicios y ejemplos de trabajo concretos.
• Llamada a la Acción: La respuesta siempre termina sugiriendo el siguiente paso, como agendar una llamada.

2. 🖨️ Servicio de Impresión Remota

Permite a los usuarios autorizados (admin) enviar documentos a una impresora física directamente desde Telegram.

• Envío (SMTP): Al recibir un archivo, el bot lo adjunta a un correo electrónico y lo envía a la dirección de la impresora preconfigurada usando credenciales SMTP.
• Monitoreo de Estado (IMAP): Un comando /check_print_status permite al administrador consultar la bandeja de entrada de la impresora. El bot se conecta vía IMAP, busca correos no leídos y reporta el estado de los trabajos de impresión basándose en palabras clave en el asunto (ej. "completed", "failed").

3. 📅 Gestión de Agenda y Tareas

• Consulta de Agenda: Se integra con Google Calendar para mostrar los eventos del día.
• Gestión de Tareas: Se conecta a Vikunja para permitir la creación y seguimiento de tareas desde Telegram.

4. 🛂 Sistema de Roles y Permisos

• El acceso a las funcionalidades está restringido por roles (admin, crew, client), los cuales se gestionan en una base de datos SQLite.
• Los menús y opciones se muestran dinámicamente según el rol del usuario, asegurando que cada quien solo vea las herramientas que le corresponden.

5. NFC Tag Wizard

• Un flujo de conversación exclusivo para administradores que permite registrar a un nuevo colaborador.
• El wizard recopila el nombre, ID de empleado, sucursal y Telegram ID a través de una serie de preguntas.
• Al finalizar, genera un string en formato Base64 que contiene los datos en un objeto JSON, listo para ser escrito en una etiqueta NFC.

---

⚙️ Instalación y Configuración

Prerrequisitos

• Python 3.9+
• Docker y Docker Compose
• Cuenta de Telegram Bot (@BotFather)
• Instancia de Vikunja (Self-hosted)
• Credenciales de Cuenta de Servicio de Google Cloud (para Calendar API)

1. Clonar y Configurar el Entorno

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

Abre el archivo .env y rellena las siguientes variables. No subas este archivo a Git.

# 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

# Clave de API de OpenAI (si se usa)
OPENAI_API_KEY=sk-...

# URL y Token de tu instancia de Vikunja
VIKUNJA_API_URL=https://tu_vikunja.com/api/v1
VIKUNJA_TOKEN=tu_token_vikunja

# 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 y Credenciales

• 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 bot/data/flows/.

Asegúrate de tener los archivos y directorios base en 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

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
├── plan_de_pruebas.md         # Casos de prueba documentados
├── README.md                  # Documentación principal
├── requirements.txt           # Dependencias de Python
├── start_bot.sh               # Script para iniciar el bot en desarrollo
└── bot/
    ├── __init__.py            # Inicializador de paquete
    ├── main.py                # Entry point y dispatcher principal
    ├── db.py                  # Gestión de la base de datos SQLite
    ├── config.py              # Carga de variables de entorno
    ├── scheduler.py           # Tareas programadas y resúmenes diarios
    ├── webhook_client.py      # Webhooks externos (n8n, etc.)
    ├── modules/
    │   ├── flow_engine.py     # Motor de flujos de conversación
    │   ├── 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
    │   ├── agenda.py          # Agendas y solicitudes
    │   ├── printer.py         # SMTP/IMAP Loop
    │   ├── sales_rag.py       # Lógica de Ventas y Servicios
    │   ├── debug.py           # Herramientas de diagnóstico
    │   ├── onboarding.py      # Menús y onboarding inicial
    │   ├── citas.py           # Solicitudes de citas
    │   ├── nfc_tag.py         # Wizard NFC
    │   ├── aprobaciones.py    # Aprobaciones y rechazos
    │   └── equipo.py          # Equipo y estado de solicitudes
    └── data/
        ├── flows/             # Directorio con los flujos de conversación JSON
        ├── servicios.json     # Base de conocimiento para ventas
        ├── credentials.json   # Credenciales de Google
        └── users.db           # Base de datos de usuarios

---

🗓️ Roadmap y Funcionalidades Completadas

Funcionalidades Implementadas

• ✅ Motor de Flujos Conversacionales (JSON): Arquitectura central para conversaciones dinámicas.
• ✅ Gestión de Roles y Permisos: Sistema de admin, crew, y client.
• ✅ Integración con Vikunja: Creación y consulta de tareas.
• ✅ Integración con Google Calendar: Consulta de agenda.
• ✅ Servicio de Impresión Remota (SMTP/IMAP): Envío de documentos y monitoreo de estado.
• ✅ Flujo de Ventas RAG: Captura de leads y generación de propuestas personalizadas con IA.
• ✅ Wizard de Creación de Tags NFC: Flujo para registrar nuevos colaboradores y generar un tag Base64.

Próximos Pasos

• Soporte para Fotos en Impresión: Añadir la capacidad de enviar imágenes al servicio de impresión.
• Migración a Google Gemini 1.5 Pro: Evaluar y migrar el motor de IA para optimizar costos y capacidades.

---

Desarrollado por: Marco G. Asistente Personalizado v1.0