talia_bot/README.md

Talía — Asistente Ejecutiva Inteligente

Talía es una asistente ejecutiva digital diseñada para centralizar, ordenar y coordinar la agenda, solicitudes y actividades de Marco. Funciona como un punto único de entrada para clientes, equipo y administradores, asegurando que cada solicitud se procese con contexto, validación y respeto por el tiempo disponible.

Talía no improvisa ni asume. Consulta, valida, confirma y ejecuta.

---

🎯 Propósito del Sistema

Talía existe para eliminar fricción operativa y proteger el tiempo ejecutivo. El sistema está diseñado para:

• Centralizar todas las solicitudes de agenda, citas y actividades
• Validar disponibilidad real antes de comprometer tiempo
• Priorizar clientes sin romper compromisos existentes
• Delegar reglas de negocio y disponibilidad a flujos en n8n
• Mantener trazabilidad completa mediante eventos webhook
• Escalar de forma modular sin romper flujos existentes

---

🧠 Personalidad, Actitud y Voz

Talía se comporta como una asistente ejecutiva profesional:

• Educada, clara y precisa en cada respuesta
• Proactiva, pero nunca invasiva
• Siempre confirma antes de agendar o ejecutar acciones
• No improvisa horarios ni decisiones
• Comunica decisiones con calma, orden y neutralidad

Talía no es informal, no es robótica y no utiliza sarcasmo. Su función es ordenar el día, no interrumpirlo.

---

👥 Roles y Niveles de Acceso

Marco (Owner)

• Consulta agenda, pendientes y solicitudes activas
• Recibe resumen diario automático a las 7:00 AM
• Aprueba o rechaza solicitudes del equipo
• Puede interactuar desde su número privado
• Tiene prioridad absoluta sobre cualquier decisión

Clientes

• Solicitan citas de duración fija (30 minutos)
• Visualizan únicamente horarios disponibles
• No tienen acceso a la agenda completa

Equipo Autorizado

• Puede proponer actividades de mayor duración (ej. grabaciones)
• Puede solicitar acciones operativas
• Toda actividad que consuma tiempo requiere aprobación

Administradores

• Ejecutan acciones sensibles
• Requieren validación adicional
• Acceden a flujos administrativos restringidos

---

🏗️ Arquitectura del Sistema

Talía está construida en capas desacopladas que se comunican por eventos:

1. Interfaz Conversacional – Telegram / WhatsApp
2. Cerebro Central – Python
3. Automatización y Reglas – n8n
4. Servicios Externos – Google Calendar, IA, APIs

Cada capa es independiente y puede evolucionar sin afectar a las demás.

---

📁 Estructura del Proyecto

talia-bot/
├── docker-compose.yml        # Orquestación de contenedores
├── Dockerfile               # Imagen del bot
├── .env.example             # Variables de entorno
├── README.md                # Documentación
└── app/
    ├── main.py              # Cerebro del bot
    ├── config.py            # Configuración y credenciales
    ├── permissions.py       # Roles y validaciones
    ├── scheduler.py         # Resumen diario y recordatorios
    ├── webhook_client.py    # Comunicación con n8n
    ├── calendar.py          # Integración Google Calendar
    ├── llm.py               # Respuestas inteligentes (IA)
    └── modules/
        ├── onboarding.py    # Bienvenida y menú inicial
        ├── agenda.py        # Consulta de agenda
        ├── citas.py         # Citas con clientes
        ├── equipo.py        # Solicitudes del equipo
        ├── aprobaciones.py  # Aprobaciones del owner
        ├── servicios.py     # Servicios y cotizaciones
        └── admin.py         # Acciones administrativas

---

🧠 Cerebro del Sistema (main.py)

main.py actúa como orquestador central. No contiene reglas de negocio complejas. Sus funciones son:

• Recibir mensajes y callbacks
• Identificar usuario y rol
• Mantener contexto conversacional
• Delegar acciones a módulos
• Emitir y recibir eventos vía webhook

Toda decisión importante se valida externamente.

---

🧩 Módulos Funcionales

Cada módulo cumple una responsabilidad única:

• onboarding.py: inicio de conversación y opciones
• agenda.py: consulta de agenda y pendientes
• citas.py: flujo de citas con clientes
• equipo.py: solicitudes internas del equipo
• aprobaciones.py: aceptar o rechazar solicitudes
• servicios.py: información y cotización de proyectos
• admin.py: acciones administrativas

---

⚡ Comandos Adicionales

/create_tag

Este comando inicia un flujo conversacional para generar un tag de identificación en formato Base64, compatible con aplicaciones de escritura NFC. El bot solicitará los siguientes datos:

• Nombre
• Número de empleado
• Sucursal
• ID de Telegram

Al finalizar, el bot devolverá una cadena de texto en Base64 que contiene un objeto JSON con la información proporcionada.

---

🔁 Flujo General de Ejecución

1. Usuario envía mensaje o interactúa con botones
2. Talía valida identidad y permisos
3. Se ejecuta el módulo correspondiente
4. Si se requiere lógica externa, se envía evento a n8n
5. n8n evalúa reglas y responde
6. Talía comunica el resultado
7. Si aplica, se agenda en Google Calendar

---

📆 Gestión de Agenda

Citas con Clientes

• Duración fija: 30 minutos
• Disponibilidad definida exclusivamente por n8n
• Confirmación explícita antes de agendar

Actividades del Equipo

• Duración flexible
• Requieren aprobación del owner
• Solo usuarios autorizados pueden solicitarlas

---

⏰ Resumen Diario

Todos los días a las 7:00 AM, Talía envía a Marco:

• Agenda del día
• Pendientes activos
• Recordatorios importantes

---

🔌 Webhooks

Toda acción relevante genera o responde un evento webhook.

Ejemplo:

{
  "event": "request_activity",
  "from": "team",
  "duration_hours": 4,
  "description": "Grabación de proyecto"
}

---

🔐 Variables de Entorno

TELEGRAM_BOT_TOKEN=
OWNER_CHAT_ID=
ADMIN_CHAT_IDS=
TEAM_CHAT_IDS=
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_REFRESH_TOKEN=
N8N_WEBHOOK_URL=
OPENAI_API_KEY=
TIMEZONE=America/Mexico_City

---

🐳 Despliegue con Docker Compose

version: "3.9"
services:
  talia-bot:
    build: .
    container_name: talia-bot
    env_file:
      - .env
    restart: unless-stopped

---

🛠️ Guía de Desarrollo

1. Clonar el repositorio
2. Crear archivo .env
3. Configurar bot de Telegram
4. Configurar flujos y reglas en n8n
5. Conectar Google Calendar
6. Levantar servicios con Docker Compose

---

✨ Principio Rector

Talía no es un bot que responde mensajes. Es un sistema de criterio, orden y protección del tiempo.

Si algo no está claro, pregunta. Si algo invade la agenda, protege. Si algo es importante, lo prioriza.