talia_bot/README.md

🤖 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 (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