mirror of
https://github.com/marcogll/talia_bot.git
synced 2026-01-13 13:25:19 +00:00
Revise README for Talía assistant details
Updated README to reflect new branding and detailed functionality of the Talía assistant.
This commit is contained in:
Marco Gallegos
242
README.md
242
README.md
@@ -1,2 +1,240 @@
|
||||
# Talia_bot_mg
|
||||
Asistente personal de Marco Gallegos
|
||||
# 🤍 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. Actúa como un punto único de entrada para clientes, equipo y administradores, cuidando el tiempo, validando contexto y ejecutando automatizaciones mediante integraciones externas.
|
||||
|
||||
Talía no toma decisiones arbitrarias: consulta, valida, confirma y ejecuta.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Objetivo del Sistema
|
||||
|
||||
Talía existe para reducir fricción operativa y proteger el tiempo ejecutivo. Sus objetivos principales son:
|
||||
|
||||
* Centralizar todas las solicitudes de agenda y trabajo
|
||||
* Validar disponibilidad real antes de comprometer tiempo
|
||||
* Priorizar clientes sin romper compromisos existentes
|
||||
* Delegar lógica compleja de negocio a n8n
|
||||
* Mantener trazabilidad total mediante webhooks
|
||||
* Permitir crecimiento modular y escalable
|
||||
|
||||
---
|
||||
|
||||
## 🧠 Personalidad y Actitud
|
||||
|
||||
Talía se comporta como una asistente ejecutiva profesional:
|
||||
|
||||
* Educada, clara y precisa
|
||||
* Proactiva, pero nunca invasiva
|
||||
* Siempre confirma antes de agendar
|
||||
* No improvisa ni asume disponibilidad
|
||||
* Comunica decisiones con calma y orden
|
||||
|
||||
No es informal, no es robótica y no es sassy. Su rol es ordenar el día, no interrumpirlo.
|
||||
|
||||
---
|
||||
|
||||
## 👥 Roles y Permisos
|
||||
|
||||
### Marco (Owner)
|
||||
|
||||
* Consulta agenda y pendientes
|
||||
* 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 en decisiones
|
||||
|
||||
### Clientes
|
||||
|
||||
* Solicitan citas de 30 minutos
|
||||
* Solo ven horarios disponibles
|
||||
* No acceden a la agenda completa
|
||||
|
||||
### Equipo Autorizado
|
||||
|
||||
* Puede proponer actividades de mayor duración
|
||||
* Puede solicitar acciones operativas
|
||||
* Requiere aprobación para agendar tiempo
|
||||
|
||||
### Administradores
|
||||
|
||||
* Ejecutan acciones sensibles
|
||||
* Requieren doble validación
|
||||
* Acceso a datos internos
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Arquitectura General
|
||||
|
||||
Talía está construida en capas claramente definidas:
|
||||
|
||||
1. Interfaz conversacional (Telegram / WhatsApp)
|
||||
2. Cerebro central en Python
|
||||
3. Automatización y reglas de negocio en n8n
|
||||
4. Servicios externos (Google Calendar, APIs, IA)
|
||||
|
||||
Cada capa es desacoplada y se comunica mediante eventos y webhooks.
|
||||
|
||||
---
|
||||
|
||||
## 📁 Estructura del Proyecto
|
||||
|
||||
```text
|
||||
talia-bot/
|
||||
├── docker-compose.yml
|
||||
├── Dockerfile
|
||||
├── .env.example
|
||||
├── README.md
|
||||
└── app/
|
||||
├── main.py # Cerebro del bot
|
||||
├── config.py # Configuración global
|
||||
├── permissions.py # Validación de roles
|
||||
├── scheduler.py # Resumen diario y recordatorios
|
||||
├── webhook_client.py # Comunicación con n8n
|
||||
├── calendar.py # Google Calendar
|
||||
├── llm.py # Respuestas inteligentes
|
||||
└── modules/
|
||||
├── onboarding.py
|
||||
├── agenda.py
|
||||
├── citas.py
|
||||
├── equipo.py
|
||||
├── aprobaciones.py
|
||||
├── servicios.py
|
||||
└── admin.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧠 Cerebro del Sistema (`main.py`)
|
||||
|
||||
`main.py` es el orquestador principal. Sus responsabilidades son:
|
||||
|
||||
* Recibir mensajes y callbacks de Telegram
|
||||
* Identificar al usuario y su rol
|
||||
* Mantener contexto de conversación
|
||||
* Delegar acciones a los módulos
|
||||
* Enviar y recibir eventos vía webhook
|
||||
|
||||
`main.py` no contiene lógica de negocio compleja; solo coordina.
|
||||
|
||||
---
|
||||
|
||||
## 🧩 Módulos Funcionales
|
||||
|
||||
Cada módulo ejecuta una responsabilidad clara:
|
||||
|
||||
* **onboarding.py**: bienvenida, `/start`, menú inicial
|
||||
* **agenda.py**: consulta de agenda y pendientes
|
||||
* **citas.py**: flujo de citas con clientes
|
||||
* **equipo.py**: solicitudes del equipo
|
||||
* **aprobaciones.py**: aceptar o rechazar solicitudes
|
||||
* **servicios.py**: información y cotización de servicios
|
||||
* **admin.py**: acciones administrativas
|
||||
|
||||
---
|
||||
|
||||
## 🔁 Flujo General de Datos
|
||||
|
||||
1. Usuario envía mensaje o presiona botón
|
||||
2. Talía valida rol y contexto
|
||||
3. Se ejecuta el módulo correspondiente
|
||||
4. Si requiere lógica externa, se envía webhook a n8n
|
||||
5. n8n responde con decisión
|
||||
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 por n8n
|
||||
* Confirmación explícita
|
||||
|
||||
### Actividades del Equipo
|
||||
|
||||
* Duración flexible
|
||||
* Requieren aprobación de Marco
|
||||
* Solo usuarios autorizados
|
||||
|
||||
---
|
||||
|
||||
## ⏰ 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 webhook.
|
||||
|
||||
Ejemplo de solicitud:
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "request_activity",
|
||||
"from": "team",
|
||||
"duration_hours": 4,
|
||||
"description": "Grabación 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
|
||||
|
||||
```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 en n8n
|
||||
5. Conectar Google Calendar
|
||||
6. Ejecutar con Docker Compose
|
||||
|
||||
---
|
||||
|
||||
## ✨ Filosofía Final
|
||||
|
||||
Talía no es un bot que responde mensajes.
|
||||
Es un sistema de criterio, orden y respeto por el tiempo.
|
||||
|
||||
Si algo no está claro, pregunta.
|
||||
Si algo invade agenda, protege.
|
||||
Si algo importa, lo prioriza.
|
||||
|
||||
Reference in New Issue
Block a user