# 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 ```text 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: ```json { "event": "request_activity", "from": "team", "duration_hours": 4, "description": "Grabación de proyecto" } ``` --- ## 🔐 Variables de Entorno ```env 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 ```yaml 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.