Pregon (Marko Teixido)

Pregón

Sistema inteligente de calendario académico para la Universidad Nacional de Villa Mercedes, potenciado por IA y MCP Server.

!

📝 关于项目

Pregon 这是一个多渠道系统，自动化了UNVIME学术日历的管理。它通过Discord、WhatsApp和Google Calendar提取、处理和分发学术活动，并得到人工智能和现代MCP架构的支持。

🎯 目标

创建一个平台：

• 智能：ia与谷歌双子座2.5 Flash的对话
• 多肛门：不和谐，WhatsApp
• 莫德纳：MCP服务器（模型上下文协议）
• 自动的智能缓存网页抓取
• 可升级：模块化和专业架构
• 生产：CI/CD、Docker、自动化测试

🖼️ 预览

!

✨ 特点

🤖 人工智能

• 谷歌双子座2.5 Flash：最先进的对话模式
• NLP查询解析器：用自然语言处理问题
• 学术背景：了解特定的大学术语
• 智能过滤：按日期、类别、事件类型搜索
• 适应性反应：根据频道调整色调和格式

🔌 MCP服务器（模型上下文协议）

• 建筑标准：兼容MCP支持的任何LLM
• 6专业工具:

- get_eventos_semana：查询未来7天的活动 - buscar_eventos：具有多个过滤器的高级搜索 - get_proximos_examenes：仅按日期范围过滤考试 - agregar_a_google_calendar：与Calendar API直接集成 - generar_link_calendar：创建共享活动的公共URL - enviar_recordatorio：多通道通知系统

• 可扩展：添加新工具的插件架构
• 互操作性：与Claude、GPT-4、Gemini和其他LLM一起工作
• 类型安全：带有pydantic的自动验证方案

🤖 Bot de Discord

• 纺织公司: !pregunta, !ayuda, !hoy
• 嵌入Ricos：带有颜色和表情符号的专业格式
• 聊天转换：具有持续上下文的IA模式

📱 Bot de WhatsApp

• Comandos Simples: EVENTOS, CALENDARIO, AYUDA, BUSCAR
• 聊天自然：在没有特定命令的情况下回答问题
• 链接Directos：单击1将事件添加到日历
• Twilio沙盒：生产前免费测试
• 错误处理：对错误的明确反应

🔍 网络抓取智能

• BeautifulSoup4+lxml：健壮而快速的解析器
• 自动分类:

- 考试（一般、恢复性、补偿性） - 节日（国家、省） - 休息（学校，冬季） - 特别活动（活动、仪式）

• 范围扩展：多天活动→个人活动
• 智能缓存：TTL 6小时优化请求
• 稳健验证：验证日期、文本和结构

📅 谷歌日历集成

• OAuth 2.0流程：使用刷新令牌进行安全身份验证
• 自动创建：将直接事件添加到日历
• 批量操作：有效处理多个事件
• 颜色编码：按可定制颜色分类
• 提醒：配置自动警报

🔔 通知系统

• 管理员模式：具有多个通知程序的可扩展架构
• 支持的频道：Discord Webhooks、WhatsApp（Twilio）
• 调度器集成：cron作业用于计划的通知
• 自定义模板：按事件类型改编的消息
• 智能聚类：每日/每周摘要

!

🏗️ 建筑

🔄 概览

📊 查询流程

!

🚀 技术

后端/核心

MCP（模型上下文协议）

外部整合

DevOps和CI/CD

监控和记录

!

📦 安装

先决条件

• python >= 3.10
• 点 >=23.x
• Git >=2.x
• 码头工人 （可选，用于集装箱化）
• 账户：

- Discord（对位机器人令牌） - Twigio（适用于WhatsApp） - 谷歌云（用于双子座AI和日历API）

______________________________________________________________________

🚀 选项1：快速安装（推荐）

# 1. Clonar repositorio
git clone https://github.com/MarkoTeixido/Pregon.git
cd Pregon

# 2. Crear entorno virtual
python -m venv venv

# Activar (Linux/macOS)
source venv/bin/activate

# Activar (Windows)
venv\Scripts\activate

# 3. Instalar dependencias
pip install --upgrade pip
pip install -r requirements.txt
pip install -r requirements-ai.txt

# 4. Configurar variables de entorno
cp .env.example .env
# Editar .env con tus credenciales (ver sección siguiente)

# 5. Ejecutar
python run.py

______________________________________________________________________

🐳 选项2：码头工人（生产）

# 1. Clonar y configurar .env
git clone https://github.com/MarkoTeixido/Pregon.git
cd Pregon
cp .env.example .env
# Editar .env con credenciales

# 2. Construir imágenes
docker-compose build

# 3. Iniciar servicios
docker-compose up -d

# 4. Ver logs
docker-compose logs -f

# 5. Detener
docker-compose down

可用服务：

• discord-bot：Bot de Discord
• whatsapp-webhook：WhatsApp服务器

有用的命令：

# Iniciar solo Discord
docker-compose up -d discord-bot

# Reiniciar servicio
docker-compose restart whatsapp-webhook

# Ver estado
docker-compose ps

# Entrar a contenedor
docker exec -it pregon-discord bash

______________________________________________________________________

⚙️ 环境变量配置

编辑文件 .env 凭你的证件：

# ============================================
# DISCORD
# ============================================
DISCORD_BOT_TOKEN=tu_token_aqui
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
DISCORD_GUILD_ID=tu_server_id

# ============================================
# TWILIO (WhatsApp)
# ============================================
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=tu_auth_token_aqui
TWILIO_WHATSAPP_FROM=whatsapp:+14155238886
TWILIO_WHATSAPP_TO=whatsapp:+54tu_numero

# ============================================
# GOOGLE GEMINI AI
# ============================================
GEMINI_API_KEY=tu_api_key_aqui
LLM_MODEL_GEMINI=gemini-2.5-flash
LLM_TEMPERATURE=0.7
LLM_MAX_TOKENS=2048

# ============================================
# GOOGLE CALENDAR
# ============================================
GOOGLE_CREDENTIALS_PATH=credentials/google_calendar.json
GOOGLE_TOKEN_PATH=credentials/token.json

# ============================================
# CALENDARIO UNVIME
# ============================================
CALENDAR_URL=https://www.unvime.edu.ar/calendario/

# ============================================
# CONFIGURACIÓN GENERAL
# ============================================
ENVIRONMENT=production
LOG_LEVEL=INFO
ENABLE_CACHE=true
CACHE_TTL=21600

______________________________________________________________________

🔑 获取凭据

📘 Discord Bot Token

1. Ve a Discord开发者门户
2. 单击en “新应用程序”
3. 给他一个名字（例如：“Pregon Bot”）
4. 去法兰 “机器人”
5. 单击en “重置令牌” 复制令牌
6. 恩 “特权网关意图” 活动：

- ✅ 消息内容意图 - ✅ 服务器成员意图（操作）

1. Ve a “OAuth2→ URL生成器”
2. 选择范围： bot, applications.commands
3. 选择权限： Send Messages, Embed Links, Read Message History
4. 复制生成的URL并在浏览器中打开以邀请机器人

📱 Twilio WhatsApp Credentials

1. 创建帐户 特维里奥
2. Ve a 控制台→ WhatsApp→ 沙盒
3. 复制图 帐户SID y 身份验证令牌
4. 美国沙盒测试：

- TWILIO_WHATSAPP_FROM=whatsapp:+14155238886

1. 从您的WhatsApp向沙盒发送激活代码
2. 配置Webhook URL（在生产中或使用ngrok）：

- 网址： https://tu-dominio.com/webhook - 方法： POST

🤖 Google Gemini API Key

1. Ve a 谷歌人工智能工作室
2. 单击en “获取API密钥”
3. 选择或创建项目
4. 单击en “创建API密钥”
5. 复制生成的API密钥
6. 免费限制：60次请求/分钟，1500次/天

📅 Google Calendar API

1. Ve a 谷歌云控制台
2. 创建新项目或选择现有项目
3. 习惯 谷歌日历API:

- API库→ Busca“日历”→ 启用

1. 创建OAuth 2.0凭据：

- 凭证→ 创建凭据→ OAuth客户端ID - 应用程序类型：桌面应用程序 - 下载JSON

1. 将JSON保存为 credentials/google_calendar.json
2. 第一次运行时，将打开浏览器进行授权
3. 将自动生成 credentials/token.json

______________________________________________________________________

🧪 验证安装

# Activar entorno virtual
source venv/bin/activate  # Linux/macOS
# o
venv\Scripts\activate  # Windows

# Ejecutar script principal
python run.py

# Deberías ver el menú:
# ══════════════════════════════════════════
# 🤖 PREGON - Sistema de Calendario UNViMe
# ══════════════════════════════════════════
# 
# 1. Bot de Discord
# 2. Webhook de WhatsApp
# 3. MCP Server
# 4. Scheduler
# 5. Salir

!

🎮 使用

🤖 Discord机器人

可用命令

🔍 Consultas
!pregunta      - Pregunta al asistente IA
!eventos                 - Eventos de la próxima semana
!hoy                     - Eventos de hoy
!buscar         - Buscar eventos específicos

📅 Google Calendar
!calendario              - Links para agregar eventos
!agregar menu            - Menú interactivo para agregar

ℹ️ Ayuda
!ayuda                   - Muestra todos los comandos
!ping                    - Verifica que el bot está activo

使用示例

!pregunta ¿Cuándo son los exámenes de diciembre?
!pregunta ¿Hay clases el 25 de diciembre?
!pregunta Dame los recesos de 2025
!buscar feriado
!buscar receso invierno
!eventos
!hoy

聪明的答案

机器人理解：

• ✅ 自然语言问题
• ✅ 同义词（考试/评估，假期/节假日）
• ✅ 相对日期（“下周”，“下个月”）
• ✅ 日期范围（“1月至3月”）
• ✅ 类别（考试、假期、休息）

______________________________________________________________________

📱 WhatsApp机器人

命令

EVENTOS         - Ver próximos 7 eventos
CALENDARIO      - Links para agregar a Google Calendar
AYUDA           - Lista de comandos disponibles
BUSCAR   - Buscar eventos específicos

对话方式

您还可以在没有命令的情况下提出自然问题：

¿Cuándo empiezan las clases?
¿Hay feriados en julio?
¿Cuándo son los exámenes?
Dame el calendario de diciembre

配置Webhook（本地开发）

# Terminal 1: Iniciar servidor Flask
python run.py
# Seleccionar opción 2 (WhatsApp)

# Terminal 2: Exponer con ngrok
ngrok http 5000

# Copiar la URL HTTPS (ej: https://abc123.ngrok.io)
# Ir a Twilio Console → WhatsApp Sandbox Settings
# Webhook URL: https://abc123.ngrok.io/webhook
# Method: POST

______________________________________________________________________

🔌 MCP服务器

import asyncio
from src.mcp.server import get_mcp_server

async def main():
    # Obtener instancia del servidor
    server = get_mcp_server()
    
    # Listar herramientas disponibles
    tools = await server.list_tools()
    print(f"Herramientas: {[t['name'] for t in tools]}")
    
    # Ejecutar herramienta: obtener eventos de la semana
    response = await server.call_tool(
        "get_eventos_semana",
        {}
    )
    print(f"Eventos esta semana: {response}")
    
    # Buscar eventos específicos
    response = await server.call_tool(
        "buscar_eventos",
        {
            "categoria": "examen",
            "desde": "2025-12-01",
            "hasta": "2025-12-31"
        }
    )
    print(f"Exámenes en diciembre: {response}")
    
    # Generar link de calendario
    response = await server.call_tool(
        "generar_link_calendar",
        {
            "titulo": "Examen Final",
            "fecha": "2025-12-15",
            "descripcion": "Matemática I"
        }
    )
    print(f"Link: {response}")

# Ejecutar
asyncio.run(main())

!

📊 项目结构

!

🎓 技术决定和学习

为什么蟒蛇？

为什么是MCP服务器？

• 标准弹出由 Anthropic、OpenAI 采用的协议
• 互操作性：适用于任何兼容的LLM
• 脱钩：人工智能和工具之间的明确分离
• 可重复使用：我可以在其他项目中使用这些工具
• 未来考验：尖端技术（2024-2025）

为什么双子座2.5闪光？

为什么选择BeautifulSoup+LXML？

# Alternativa 1: Selenium (rechazada)
# ❌ Más lento (navegador headless)
# ❌ Más recursos (RAM, CPU)
# ✅ JS rendering

# Alternativa 2: BeautifulSoup + lxml (elegida)
# ✅ Rápido (parser en C)
# ✅ Ligero (solo parsing HTML)
# ✅ Robusto (tolera HTML mal formado)
# ❌ No ejecuta JavaScript

决定：Unvime不需要JS，BS4就足够了。

6小时缓存：为什么？

# Análisis de cambios del calendario UNViMe:
# - Actualización: 1-2 veces por semestre
# - Frecuencia de consultas: ~100/día
# - Sin caché: 100 requests/día al servidor
# - Con caché 6h: 4 requests/día

# TTL Options:
# 1h   → Demasiado frecuente, desperdicio
# 24h  → Podría perder cambios importantes
# 6h   → Balance perfecto ✅

结果：96%的请求减少。

为什么要多频道（Discord+WhatsApp）？

• 最大范围：discord=年轻学生，WhatsApp=教师/家长
• 灵活性：用户选择他们最喜欢的平台
• 学习：演示多个API的集成
• 专业人士：真正的应用程序是多平台的

Docker多阶段构建

# STAGE 1: Builder (imagen pesada con build tools)
FROM python:3.10-slim as builder
RUN apt-get install gcc g++ make  # Solo en build
RUN pip install -r requirements.txt

# STAGE 2: Runtime (imagen ligera solo con runtime)
FROM python:3.10-slim
COPY --from=builder /opt/venv /opt/venv  # Solo venv
# Resultado: Imagen final 40% más pequeña

通知体系结构

# Manager Pattern:
class NotificationManager:
    def __init__(self):
        self.notifiers = [
            DiscordNotifier(),
            WhatsAppNotifier(),
            # Fácil agregar: TelegramNotifier(), EmailNotifier()
        ]
    
    def send_all(self, message):
        for notifier in self.notifiers:
            notifier.send(message)

# Ventaja: Agregar canales sin modificar lógica existente

!

🚀 生产部署

铁路（推荐）

铁路 从GitHub自动部署：

1. 连接存储库:

- Ve a 铁路 - 新项目→ 从GitHub部署 - 选择 MarkoTeixido/Pregon

1. 配置服务:

   Service 1: Pregon-Discord
   - Start Command: python entrypoints/discord_service.py
   - Environment: production

   Service 2: Pregon-WhatsApp  
   - Start Command: python entrypoints/whatsapp_service.py
   - Port: 5000
   - Environment: production

1. 环境变量:

- 复制所有VAR .env - 铁路→ 设置→ 变量 - 添加： DISCORD_BOT_TOKEN, GEMINI_API_KEY等等。

1. 自动部署:

- 卡达推a main 自动重新部署 - 铁路仪表板上的实时日志

______________________________________________________________________

!

🧪 测试y CI/CD

自动化测试

# Ejecutar todos los tests
pytest

# Con coverage
pytest --cov=src --cov-report=html

# Solo tests de integración
pytest -m integration

# Solo tests unitarios
pytest -m unit

GitHub操作工作流

该项目有4个自动化工作流：

1. 构建 (.github/workflows/build.yml):

- ✅ 验证代码编译 - ✅ 验证依赖项的安装 - ⏰ 每次推都会执行

1. 测试 (.github/workflows/tests.yml):

- ✅ 运行完整的测试套件 - ✅ 一般报告 - ⏰ 在PRS中运行并将其推到main

1. 棉绒 (.github/workflows/lint.yml):

- ✅ 使用 flake8 检查 PEP 8 - ✅ 用Mypy检查类型 - ⏰ 在每个提交中执行

1. 码头工人 (.github/workflows/docker.yml):

- ✅ 图像构建 - ✅ 推送Docker Hub（en版本） - ⏰ 在标签上运行

实际覆盖范围

Tests: 47 passed
Coverage: 52%
Lines: 2,341
Branches: 412

!

📄 许可证

这个项目在 麻省理工学院许可证.

!

👨‍💻 作者

马科 Teixido\ *系统工程专业学生*\ *梅赛德斯别墅国立大学*

• 🌐 投资组合: markoteisido.site
• 🐙 GitHub: @马可

Hecho para la comunidad de UNViMe