🤖 Bot Cabezón

Asistente académico automatizado para WhatsApp orientado a estudiantes del ISPC

Bot Cabezón es un asistente académico automatizado diseñado para centralizar y simplificar el acceso a la información de cursada para los estudiantes de la Tecnicatura Superior en Desarrollo de Software del ISPC (Instituto Superior Politécnico Córdoba).

📖 Contenido

• El Problema y la Solución
• Características Principales
• Stack Tecnológico
• Arquitectura
• Instalación
• Comandos y Uso
• Desarrollo y Decisiones Técnicas
• FAQ

---

💡 El Problema y la Solución

El problema: La Tecnicatura Superior en Desarrollo de Software del ISPC se desarrolla bajo una modalidad mayormente asincrónica, donde gran parte del contenido académico, avisos y actividades se publican en foros de Moodle y distintos canales institucionales.

En la práctica, esto genera varios problemas para los estudiantes:

• Información dispersa entre múltiples foros, mensajes y plataformas.
• Dificultad para encontrar avisos importantes o fechas relevantes.
• Publicaciones que quedan ocultas entre hilos extensos.
• Estudiantes que no tienen claro dónde consultar información oficial.
• Comunicación reactiva y dependencia constante de grupos informales.
• Sensación de desconexión entre estudiantes, docentes y herramientas institucionales.

El resultado es una experiencia académica fragmentada, donde muchos estudiantes terminan perdiendo información importante o recurriendo constantemente a otros estudiantes para resolver dudas administrativas o académicas.

La solución: Bot Cabezón integra en WhatsApp un asistente académico automatizado que centraliza información clave de cursada y reduce fricción en el acceso a datos importantes.

El objetivo del bot es acercar la información académica al entorno donde mas interactúan los alumnos, simplificando el acceso a clases compartiendo los enlaces, avisos institucionales, avisos de exámenes y consultas frecuentes mediante automatización e IA contextualizada.

El asistente permite:

• 📚 Centralizar información académica relevante en un único canal.
• 🔔 Automatizar recordatorios, avisos y notificaciones importantes.
• 🧠 Responder consultas con IA contextualizada usando datos reales del calendario y la base académica.
• 🔍 Recuperar información desde documentos institucionales mediante arquitectura RAG.
• 💬 Reducir la dependencia de mensajes perdidos en grupos o foros extensos.
• ⚡ Brindar respuestas rápidas desde una interfaz cotidiana y accesible como WhatsApp.

Más que un bot de comandos, Cabezón actúa como un asistente académico automatizado orientado a mejorar la experiencia diaria de estudiantes del ISPC en una modalidad educativa distribuida y asincrónica.

---

✨ Características Principales

Característica	Descripción
🤖 Respuestas con IA	Generación de respuestas con contexto académico + RAG sobre PDFs institucionales.
📅 Automatización	Recordatorios automáticos de clases, exámenes y avisos.
🗂️ Contexto dinámico	Perfiles, comisiones, profesores y agenda almacenados en base de datos.
🔐 Gestión Privada	Chat privado por código para completar perfiles y ejecutar flujos de administración.
⚡ Comandos Rápidos	Accesos directos sin IA (!hoy, !examenes, !avisos) para respuestas inmediatas.
🛡️ Moderación	Detección de off-topic, advertencias, bloqueos progresivos y rate limiting.

---

🛠 Stack Tecnológico

Capa	Tecnología	Propósito
Runtime & Lenguaje	Node.js 20+ / TypeScript 5+	Entorno de ejecución y tipado estático
Interfaz	Baileys	Conexión a WhatsApp vía Web Socket
Persistencia	SQLite	Almacenamiento ágil de datos e índices RAG
IA & Embeddings	Gemini 2.5 (Groq fallback) / Google Embeddings	Generación de respuestas y vectorización
Automatización	node-cron	Tareas programadas e indexación incremental
Integraciones	IMAP, RSS	Lectura de correos institucionales y noticias

---

🏗️ Arquitectura & Diseño

El sistema emplea una arquitectura por capas para separar responsabilidades, inyectar dependencias fácilmente y permitir una escalabilidad fluida.

┌─────────────────────────────────────────┐
│   Interfaz: WhatsApp (Baileys)          │ ← Conexión, QR, eventos
├─────────────────────────────────────────┤
│   Controlador: MessageRouterService     │ ← Ruteo: comandos vs IA
├─────────────────────────────────────────┤
│   Lógica de negocio:                    │
│   • AIQueryService (IA + RAG)           │ ← Orquestación IA y moderación
│   • AcademicCalendarService (comandos)  │ ← Respuestas rápidas
│   • PrivateChatWorkflowService          │ ← Flujos privados/admin
├─────────────────────────────────────────┤
│   Contexto dinámico & RAG:              │
│   • KnowledgeContextService             │ ← Datos duros (SQLite)
│   • RagQueryService                     │ ← Búsqueda semántica
├─────────────────────────────────────────┤
│   Persistencia, Tareas & Externos:      │
│   • RagPipelineService                  │ ← Indexación de vectores
│   • SchedulerService (cron)             │ ← Automatización
│   • IMAP / RSS                          │ ← Integraciones externas
└─────────────────────────────────────────┘

Flujo de una consulta con IA:

1. Mensaje recibido → Gateway valida permisos.
2. MessageRouterService deriva a AIQueryService.
3. Se verifica moderación (off-topic, rate limit).
4. Se ensambla el contexto uniendo datos de SQLite y búsqueda RAG.
5. El modelo de IA genera la respuesta contextualizada y se envía al grupo.

---

⚙️ Instalación y Configuración

Requisitos Previos

• Node.js 20.x+ y npm 10.x+
• Git
• Cuenta de WhatsApp (cualquier número)
• API Key de Gemini (Google AI Studio)

Pasos

1. Clonar e instalar dependencias:

   git clone <URL_DEL_REPOSITORIO>
   cd bot-cabezon
   npm install

2. Configurar entorno: Copia .env.example a .env y completa las variables clave:

   WHATSAPP_GROUP_ID=1203630xxxxxxxx@g.us # O usa WHATSAPP_GROUP_IDS separado por comas
   ADMIN_PASSWORD=tu_password_fuerte
   ADMIN_SEED_CODES=123456,654321
   GEMINI_API_KEY=tu_gemini_api_key
   SQLITE_PATH=data/chatbot.db

3. Compilar e iniciar:

   npm run build
   npm start # Para desarrollo: npm run dev

4. Vincular WhatsApp: Escanea el código QR que aparecerá en la terminal desde Dispositivos vinculados en tu app de WhatsApp. Escribe !menu en el grupo para verificar.

---

🤖 Comandos y Uso

El bot soporta dos modos: comandos rápidos (con !) y consultas con IA contextualizada (lenguaje natural o mediante mención con @).

🔹 Consultas con IA

En el grupo: Escribí preguntas en lenguaje natural. El bot responde con contexto académico del calendario y documentos institucionales.

Ejemplos:

• "¿Cuándo es el examen de Estructuras?"
• "Qué materias tengo que ver esta semana?"
• "Me falta Cálculo, ¿cuándo se recupera?"

Mencionar al bot (@cabezon): Si quieres forzar una respuesta con IA en un contexto específico, menciona al bot con @cabezon seguido de tu pregunta:

• @cabezon ¿Cuáles son las fechas de los exámenes finales?
• @cabezon Necesito correlativas de Algoritmos

🔹 Comandos rápidos (En Grupos)

Comando	Alias	Descripción
!menu	!m	Abre el menú interactivo con opciones de navegación
!hoy	!clases	Muestra las clases/materias del día (fecha, horario, profesor)
!enlace	!e	Devuelve el enlace de Meet/Zoom de la clase en curso o próxima (ventana 10 min antes)
!examenes	!ex	Lista los próximos exámenes (fecha, hora, tipo, comisión)
!avisos	!av	Avisos e informes institucionales vigentes
!semana	!s	Agenda académica de esta semana
!semana-que-viene	!sv	Agenda de la próxima semana
!noticias	!n	Últimas noticias de tecnología (RSS)
!help	!he	Muestra ayuda con todos los comandos disponibles

🔹 Chat Privado (Gestión y Administración)

Registro de usuario: El bot te pedirá que completes tu perfil (nombre, cumpleaños, email, comisión) en privado.

Comandos administrativos: Requieren autenticación previa con !soyadmin [codigo]:

• !panel: Panel de administración general
• !agregarexamen: Crear nuevo examen en el calendario
• !editarexamen: Editar examen existente
• !eliminaravisos: Limpiar avisos vencidos
• !log-moderacion: Ver estadísticas de moderación y bloqueos
• !log-errores: Ver log de errores del bot
• !stats: Estadísticas generales de uso

---

📖 Desarrollo y Decisiones Técnicas

En desarrollo

Scripts Útiles

npm run dev           # Hot reload
npm run rag:index     # Indexa PDFs nuevos en data/ai-context/
npm run rag:test      # Prueba interactiva del motor RAG
npm run cleanup:data  # ⚠️ Limpia la BD y vectores

¿Por qué esta arquitectura?

• RAG vs Fine-tuning: Se eligió RAG porque permite actualizar fechas, manuales y PDF institucionales sin costos de reentrenamiento, garantizando respuestas explicables y referenciadas.
• Contexto Mixto (RAG + SQLite): RAG procesa documentos estáticos, pero la BD maneja el conocimiento "caliente" (qué alumno pregunta, de qué comisión es, qué clase toca hoy).
• Baileys vs API Oficial: Para esta etapa Alpha, Baileys permite iterar rápido y gratis en grupos estándar. La lógica está desacoplada para facilitar una futura migración a la WhatsApp Business API.
• Moderación: El sistema progresivo (warnings → ban temporal) asegura el acceso democrático y educa al usuario antes de penalizarlo.

---

❓ FAQ

• En desarrollo

---

Hecho para estudiantes del ISPC.