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:

Input: Telegram (Texto o Audio).
STT: Whisper (Conversión de Audio a Texto).
Router: Verificación de ID contra la base de datos de usuarios.
Cerebro (LLM): OpenAI (Fase 1) / Google Gemini (Fase 2).
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.

⚙️ 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

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:

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

📂 Estructura del Proyecto

talia_bot_mg/
├── 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

🗓️ 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

README.md

🤖 Talia Bot: Asistente Personal & Orquestador de Negocio