marcogll/talia_bot
1
0
Fork 0
mirror of https://github.com/marcogll/talia_bot.git synced 2026-01-13 21:35:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

Refine language and structure in README.md

Browse Source 
Updated wording for clarity and consistency throughout the README. Adjusted sections on purpose, personality, roles, architecture, and deployment instructions.
This commit is contained in:
Marco Gallegos
2025-12-15 12:21:06 -06:00
committed by GitHub
parent c828a77d66
commit be51ea1c92
1 changed files with 78 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files

156
README.md
View File

@@ -1,78 +1,78 @@
# 🤍 Talía — Asistente Ejecutiva Inteligente # 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 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 toma decisiones arbitrarias: consulta, valida, confirma y ejecuta. Talía no improvisa ni asume. **Consulta, valida, confirma y ejecuta.**
--- ---
## 🎯 Objetivo del Sistema ## 🎯 Propósito del Sistema
Talía existe para reducir fricción operativa y proteger el tiempo ejecutivo. Sus objetivos principales son: 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 y trabajo * Centralizar todas las solicitudes de agenda, citas y actividades
* Validar disponibilidad real antes de comprometer tiempo * Validar disponibilidad real antes de comprometer tiempo
* Priorizar clientes sin romper compromisos existentes * Priorizar clientes sin romper compromisos existentes
* Delegar lógica compleja de negocio a n8n * Delegar reglas de negocio y disponibilidad a flujos en n8n
* Mantener trazabilidad total mediante webhooks * Mantener trazabilidad completa mediante eventos webhook
* Permitir crecimiento modular y escalable * Escalar de forma modular sin romper flujos existentes
--- ---
## 🧠 Personalidad y Actitud ## 🧠 Personalidad, Actitud y Voz
Talía se comporta como una asistente ejecutiva profesional: Talía se comporta como una asistente ejecutiva profesional:
* Educada, clara y precisa * Educada, clara y precisa en cada respuesta
* Proactiva, pero nunca invasiva * Proactiva, pero nunca invasiva
* Siempre confirma antes de agendar * Siempre confirma antes de agendar o ejecutar acciones
* No improvisa ni asume disponibilidad * No improvisa horarios ni decisiones
* Comunica decisiones con calma y orden * Comunica decisiones con calma, orden y neutralidad
No es informal, no es robótica y no es sassy. Su rol es ordenar el día, no interrumpirlo. 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 Permisos ## 👥 Roles y Niveles de Acceso
### Marco (Owner) ### Marco (Owner)
* Consulta agenda y pendientes * Consulta agenda, pendientes y solicitudes activas
* Recibe resumen diario automático a las 7:00 AM * Recibe resumen diario automático a las 7:00 AM
* Aprueba o rechaza solicitudes del equipo * Aprueba o rechaza solicitudes del equipo
* Puede interactuar desde su número privado * Puede interactuar desde su número privado
* Tiene prioridad absoluta en decisiones * Tiene prioridad absoluta sobre cualquier decisión
### Clientes ### Clientes
* Solicitan citas de 30 minutos * Solicitan citas de duración fija (30 minutos)
* Solo ven horarios disponibles * Visualizan únicamente horarios disponibles
* No acceden a la agenda completa * No tienen acceso a la agenda completa
### Equipo Autorizado ### Equipo Autorizado
* Puede proponer actividades de mayor duración * Puede proponer actividades de mayor duración (ej. grabaciones)
* Puede solicitar acciones operativas * Puede solicitar acciones operativas
* Requiere aprobación para agendar tiempo * Toda actividad que consuma tiempo requiere aprobación
### Administradores ### Administradores
* Ejecutan acciones sensibles * Ejecutan acciones sensibles
* Requieren doble validación * Requieren validación adicional
* Acceso a datos internos * Acceden a flujos administrativos restringidos
--- ---
## 🏗️ Arquitectura General ## 🏗️ Arquitectura del Sistema
Talía está construida en capas claramente definidas: Talía está construida en capas desacopladas que se comunican por eventos:
1. Interfaz conversacional (Telegram / WhatsApp) 1. **Interfaz Conversacional** – Telegram / WhatsApp
2. Cerebro central en Python 2. **Cerebro Central** – Python
3. Automatización y reglas de negocio en n8n 3. **Automatización y Reglas** – n8n
4. Servicios externos (Google Calendar, APIs, IA) 4. **Servicios Externos** – Google Calendar, IA, APIs
Cada capa es desacoplada y se comunica mediante eventos y webhooks. Cada capa es independiente y puede evolucionar sin afectar a las demás.
--- ---
@@ -80,65 +80,65 @@ Cada capa es desacoplada y se comunica mediante eventos y webhooks.
```text ```text
talia-bot/ talia-bot/
├── docker-compose.yml ├── docker-compose.yml # Orquestación de contenedores
├── Dockerfile ├── Dockerfile # Imagen del bot
├── .env.example ├── .env.example # Variables de entorno
├── README.md ├── README.md # Documentación
└── app/ └── app/
├── main.py # Cerebro del bot ├── main.py # Cerebro del bot
├── config.py # Configuración global ├── config.py # Configuración y credenciales
├── permissions.py # Validación de roles ├── permissions.py # Roles y validaciones
├── scheduler.py # Resumen diario y recordatorios ├── scheduler.py # Resumen diario y recordatorios
├── webhook_client.py # Comunicación con n8n ├── webhook_client.py # Comunicación con n8n
├── calendar.py # Google Calendar ├── calendar.py # Integración Google Calendar
├── llm.py # Respuestas inteligentes ├── llm.py # Respuestas inteligentes (IA)
└── modules/ └── modules/
├── onboarding.py ├── onboarding.py # Bienvenida y menú inicial
├── agenda.py ├── agenda.py # Consulta de agenda
├── citas.py ├── citas.py # Citas con clientes
├── equipo.py ├── equipo.py # Solicitudes del equipo
├── aprobaciones.py ├── aprobaciones.py # Aprobaciones del owner
├── servicios.py ├── servicios.py # Servicios y cotizaciones
└── admin.py └── admin.py # Acciones administrativas
``` ```
--- ---
## 🧠 Cerebro del Sistema (`main.py`) ## 🧠 Cerebro del Sistema (`main.py`)
`main.py` es el orquestador principal. Sus responsabilidades son: `main.py` actúa como **orquestador central**. No contiene reglas de negocio complejas. Sus funciones son:
* Recibir mensajes y callbacks de Telegram * Recibir mensajes y callbacks
* Identificar al usuario y su rol * Identificar usuario y rol
* Mantener contexto de conversación * Mantener contexto conversacional
* Delegar acciones a los módulos * Delegar acciones a módulos
* Enviar y recibir eventos vía webhook * Emitir y recibir eventos vía webhook
`main.py` no contiene lógica de negocio compleja; solo coordina. Toda decisión importante se valida externamente.
--- ---
## 🧩 Módulos Funcionales ## 🧩 Módulos Funcionales
Cada módulo ejecuta una responsabilidad clara: Cada módulo cumple una responsabilidad única:
* **onboarding.py**: bienvenida, `/start`, menú inicial * **onboarding.py**: inicio de conversación y opciones
* **agenda.py**: consulta de agenda y pendientes * **agenda.py**: consulta de agenda y pendientes
* **citas.py**: flujo de citas con clientes * **citas.py**: flujo de citas con clientes
* **equipo.py**: solicitudes del equipo * **equipo.py**: solicitudes internas del equipo
* **aprobaciones.py**: aceptar o rechazar solicitudes * **aprobaciones.py**: aceptar o rechazar solicitudes
* **servicios.py**: información y cotización de servicios * **servicios.py**: información y cotización de proyectos
* **admin.py**: acciones administrativas * **admin.py**: acciones administrativas
--- ---
## 🔁 Flujo General de Datos ## 🔁 Flujo General de Ejecución
1. Usuario envía mensaje o presiona botón 1. Usuario envía mensaje o interactúa con botones
2. Talía valida rol y contexto 2. Talía valida identidad y permisos
3. Se ejecuta el módulo correspondiente 3. Se ejecuta el módulo correspondiente
4. Si requiere lógica externa, se envía webhook a n8n 4. Si se requiere lógica externa, se envía evento a n8n
5. n8n responde con decisión 5. n8n evalúa reglas y responde
6. Talía comunica el resultado 6. Talía comunica el resultado
7. Si aplica, se agenda en Google Calendar 7. Si aplica, se agenda en Google Calendar
@@ -149,20 +149,20 @@ Cada módulo ejecuta una responsabilidad clara:
### Citas con Clientes ### Citas con Clientes
* Duración fija: 30 minutos * Duración fija: 30 minutos
* Disponibilidad definida por n8n * Disponibilidad definida exclusivamente por n8n
* Confirmación explícita * Confirmación explícita antes de agendar
### Actividades del Equipo ### Actividades del Equipo
* Duración flexible * Duración flexible
* Requieren aprobación de Marco * Requieren aprobación del owner
* Solo usuarios autorizados * Solo usuarios autorizados pueden solicitarlas
--- ---
## ⏰ Resumen Diario ## ⏰ Resumen Diario
Todos los días a las 7:00 AM, Talía envía a Marco: Todos los días a las **7:00 AM**, Talía envía a Marco:
* Agenda del día * Agenda del día
* Pendientes activos * Pendientes activos
@@ -172,16 +172,16 @@ Todos los días a las 7:00 AM, Talía envía a Marco:
## 🔌 Webhooks ## 🔌 Webhooks
Toda acción relevante genera o responde un webhook. Toda acción relevante genera o responde un evento webhook.
Ejemplo de solicitud: Ejemplo:
```json ```json
{ {
"event": "request_activity", "event": "request_activity",
"from": "team", "from": "team",
"duration_hours": 4, "duration_hours": 4,
"description": "Grabación proyecto" "description": "Grabación de proyecto"
} }
``` ```
@@ -204,7 +204,7 @@ TIMEZONE=America/Mexico_City
--- ---
## 🐳 Despliegue con Docker ## 🐳 Despliegue con Docker Compose
```yaml ```yaml
version: "3.9" version: "3.9"
@@ -224,17 +224,17 @@ services:
1. Clonar el repositorio 1. Clonar el repositorio
2. Crear archivo `.env` 2. Crear archivo `.env`
3. Configurar bot de Telegram 3. Configurar bot de Telegram
4. Configurar flujos en n8n 4. Configurar flujos y reglas en n8n
5. Conectar Google Calendar 5. Conectar Google Calendar
6. Ejecutar con Docker Compose 6. Levantar servicios con Docker Compose
--- ---
## ✨ Filosofía Final ## ✨ Principio Rector
Talía no es un bot que responde mensajes. Talía no es un bot que responde mensajes.
Es un sistema de criterio, orden y respeto por el tiempo. Es un sistema de criterio, orden y protección del tiempo.
Si algo no está claro, pregunta. Si algo no está claro, pregunta.
Si algo invade agenda, protege. Si algo invade la agenda, protege.
Si algo importa, lo prioriza. Si algo es importante, lo prioriza.