feat: arquitectura RAG embebida y asistente UdeCi con botones interactivos (SDD-010, v3.8.25)

This commit is contained in:
2026-10-27 07:58:26 -03:00
parent 4125f7f7bd
commit fb46de5f28
18 changed files with 1088 additions and 275 deletions
+285
View File
@@ -0,0 +1,285 @@
"""
Servicio RAG Embebido (Retrieval-Augmented Generation) para UdeCi
Almacenamiento y recuperación semántica en base de datos relacional SQLite/PostgreSQL
con aislamiento estricto por rol de usuario.
"""
import re
import unicodedata
from typing import List, Dict, Any, Optional
from app import db
from app.models.knowledge_chunk import KnowledgeChunk
STOP_WORDS = {
"de", "la", "el", "los", "las", "un", "una", "unos", "unas", "en", "para", "por",
"con", "sobre", "entre", "hacia", "hasta", "desde", "que", "como", "cual", "quien",
"y", "o", "a", "al", "del", "es", "son", "mi", "mis", "tu", "tus", "su", "sus"
}
def _normalize_text(text: str) -> str:
"""Normaliza texto eliminando acentos, puntuación y convirtiendo a minúsculas."""
if not text:
return ""
text = unicodedata.normalize('NFKD', text).encode('ASCII', 'ignore').decode('utf-8')
return re.sub(r'[^a-zA-Z0-9\s]', ' ', text.lower()).strip()
def _tokenize(text: str) -> List[str]:
"""Extrae palabras clave significativas eliminando stop words."""
norm = _normalize_text(text)
tokens = [t for t in norm.split() if len(t) > 2 and t not in STOP_WORDS]
return tokens
OFFICIAL_KNOWLEDGE_BASE = [
# -------------------------------------------------------------
# MANUAL OPERATIVO PARA BEDELÍA Y ADMINISTRADORES
# -------------------------------------------------------------
{
"title": "Circuito Secuencial Canónico de 9 Pasos",
"role": "bedelia",
"keywords": "circuito pasos bedelia carga sedes aulas ciclos carreras materias comisiones profesores alumnos reservas",
"category": "bedelia_manual",
"content": (
"El flujo operativo oficial de Bedelía en Admin Edu Space consta de 9 pasos secuenciales:\n"
"1. Sedes/Edificios: Dar de alta el campus y sedes institucionales.\n"
"2. Aulas: Crear aulas físicas con piso y aforo, o salas virtuales (Campus Virtual / Meet).\n"
"3. Ciclos Lectivos: Definir el cuatrimestre y vigencia (ej. 2° Cuatrimestre 2026).\n"
"4. Carreras: Crear las carreras oficiales de UniCABA.\n"
"5. Asignaturas: Cargar materias asociadas a una o múltiples carreras (Many-to-Many).\n"
"6. Comisiones: Crear comisiones asignando materia, carrera, ciclo y turno.\n"
"7. Profesores: Asignar los docentes responsables de cada comisión.\n"
"8. Alumnos: Matricular estudiantes en las comisiones correspondientes.\n"
"9. Reservas de Espacio: Asignar aula presencial o enlace virtual para la cursada."
)
},
{
"title": "Matriz de Conflictos y Validación de Aulas",
"role": "bedelia",
"keywords": "conflictos superposicion solapamiento aula aforo docente codocencia restriccion diaria",
"category": "bedelia_rules",
"content": (
"La plataforma aplica una matriz de validación en tiempo real para impedir reservas inválidas:\n"
"- Conflicto Físico: Dos comisiones no pueden ocupar la misma aula presencial en la misma fecha y franja horaria. En aulas virtuales no aplica colisión.\n"
"- Control de Aforo: La cantidad de inscriptos no puede superar la capacidad máxima del aula física.\n"
"- Conflicto Docente: Un profesor no puede dictar dos clases simultáneas, salvo que la comisión tenga co-docencia activa registrada.\n"
"- Restricción Diaria del Alumno: Un estudiante no puede cursar dos materias regulares el mismo día, salvo cursos cortos o autorización expresa de Bedelía."
)
},
{
"title": "Optimizador Genético de Aulas con Inteligencia Artificial",
"role": "bedelia",
"keywords": "optimizador genetico aulas algoritmo colisiones capacidad asignacion masiva",
"category": "bedelia_tools",
"content": (
"El Optimizador Genético de Aulas (disponible en /genetic_optimizer) asigna de forma automatizada aulas físicas a comisiones activas:\n"
"- Resuelve superposiciones horarias y minimiza el aforo ocioso adaptando la capacidad del aula al cupo de la materia.\n"
"- Permite ejecutar la optimización, previsualizar las asignaciones propuestas con desglose de fitness, y aplicar los cambios masivamente en base de datos con un solo clic con registro en Auditoría."
)
},
{
"title": "Importador Masivo de Google Sheets",
"role": "bedelia",
"keywords": "importador google sheets sincronizacion masiva cartelera excel preview granular",
"category": "bedelia_tools",
"content": (
"La herramienta de sincronización (/admin/google_sheets_import) permite ingerir planillas online de UniCABA:\n"
"- Inspección Previa: El botón 'Inspeccionar Sheet Online' muestra una grilla interactiva sin guardar datos directamente.\n"
"- Selección Granular: Permite tildar qué entidades importar (reservas, aulas, comisiones, materias, carreras) y filtrar por día de la semana o carrera.\n"
"- Modificación Manual de Fecha: Permite corregir o forzar una fecha específica para una fila o grupo de comisiones antes de confirmar la sincronización."
)
},
{
"title": "Integración y Sincronización con Moodle 4.1",
"role": "bedelia",
"keywords": "moodle sincronizacion cola sync tareas dlq reintentos web services api",
"category": "bedelia_tools",
"content": (
"Admin Edu Space se conecta con Moodle 4.1 vía REST Web Services mediante una cola asíncrona resiliente (MoodleSyncTask):\n"
"- Las altas y matriculaciones no bloquean al usuario; se encolan y procesan en background con reintentos exponenciales y Dead Letter Queue (DLQ).\n"
"- Los administradores pueden monitorear tareas pendientes y estadísticas en la pestaña Moodle de Configuración Global (/admin/settings)."
)
},
# -------------------------------------------------------------
# MANUAL OPERATIVO PARA DOCENTES Y PROFESORES
# -------------------------------------------------------------
{
"title": "Consulta de Aulas Asignadas y Aulas Virtuales para Docentes",
"role": "docente",
"keywords": "docente aulas clases cartelera horario google meet salas virtuales",
"category": "docente_manual",
"content": (
"Como docente en Admin Edu Space puedes consultar tus espacios áulicos:\n"
"- En el Dashboard Docente (/dashboard) y en la Cartelera de Clases (/schedule/today_schedule) puedes ver tus materias asignadas para hoy y la semana.\n"
"- Se indica el aula presencial asignada con piso y sede, o el botón directo a la sala virtual de Google Meet / Teams si la modalidad es remota.\n"
"- Si requieres un cambio de aula física, debes solicitarlo al personal de Bedelía."
)
},
{
"title": "Libro de Calificaciones (Gradebook) y Actas de Regularidad",
"role": "docente",
"keywords": "calificaciones notas parciales recuperatorio gradebook actas regularidad inmutable",
"category": "docente_manual",
"content": (
"El sistema cuenta con un Libro de Calificaciones digital para cada comisión:\n"
"- El docente puede registrar notas de primer parcial, segundo parcial, recuperatorios y calificar como ausente.\n"
"- El sistema calcula automáticamente la condición académica del alumno (Regular, Promocionado, Libre).\n"
"- Al finalizar el cuatrimestre, el docente puede realizar el Cierre de Acta de Regularidad, quedando registrada de forma inmutable con trazabilidad en auditoría."
)
},
{
"title": "Nómina de Alumnos y Comisiones Activas",
"role": "docente",
"keywords": "nomina alumnos estudiantes comisiones lista asistencia cursada",
"category": "docente_manual",
"content": (
"Los profesores pueden consultar la nómina completa de estudiantes inscriptos en sus asignaturas desde el panel de comisiones:\n"
"- Se visualiza el DNI, nombre, correo institucional y estado de matrícula de cada alumno.\n"
"- No está permitido a los docentes crear carreras, borrar aulas ni alterar parámetros de configuración del sistema; estas acciones están reservadas a Bedelía."
)
},
# -------------------------------------------------------------
# MANUAL PARA ALUMNOS Y ESTUDIANTES
# -------------------------------------------------------------
{
"title": "Consulta de Aula y Horarios de Cursada para Alumnos",
"role": "alumno",
"keywords": "alumno aula donde curso hoy horario materias clases cartelera",
"category": "alumno_manual",
"content": (
"Para saber en qué aula cursas tus materias:\n"
"- Ingresa al Dashboard de Estudiante (/dashboard) o a la Cartelera de Clases (/schedule/today_schedule).\n"
"- Verás la tarjeta de tu clase del día con el nombre de la materia, comisión, horario de inicio y finalización, y el número de aula física asignada.\n"
"- Si la clase es virtual, encontrarás un botón directo para unirte a la videollamada de Google Meet."
)
},
{
"title": "Mis Materias Matriculadas y Horarios Semanales",
"role": "alumno",
"keywords": "materias inscripcion matriculadas horario semanal cursada comisiones",
"category": "alumno_manual",
"content": (
"En la sección 'Mis Materias' (/my_subjects) puedes verificar:\n"
"- La lista de asignaturas en las que te encuentras matriculado en el ciclo lectivo actual.\n"
"- El equipo docente a cargo de cada comisión y los días de cursada asignados.\n"
"- Recuerda que el sistema impide matricularse en dos materias regulares el mismo día para evitar superposiciones de estudio."
)
},
{
"title": "Consulta de Calificaciones y Estado Académico",
"role": "alumno",
"keywords": "notas calificaciones parciales regularidad actas estado academico",
"category": "alumno_manual",
"content": (
"Puedes verificar tu progreso académico ingresando al Libro de Calificaciones de tus materias:\n"
"- Consulta tus notas de parciales y recuperatorios una vez publicadas por el profesor.\n"
"- Verifica tu condición académica final (Regular, Promocionado o Libre).\n"
"- Ante cualquier discrepancia en tus notas o dudas sobre regularidad, consulta directamente a tu profesor o al departamento de Bedelía."
)
},
# -------------------------------------------------------------
# INFORMACIÓN GENERAL INSTITUCIONAL
# -------------------------------------------------------------
{
"title": "Acceso a la Plataforma y Soporte Institucional",
"role": "general",
"keywords": "login acceso cuenta google sso unicaba soporte contraseña",
"category": "general",
"content": (
"Admin Edu Space es la plataforma oficial de gestión de espacios áulicos y cursada de UniCABA:\n"
"- Se puede ingresar mediante correo institucional Google Workspace (@unicaba.edu.ar), login delegado de Moodle con DNI, o cuenta local.\n"
"- Si tienes problemas de acceso, contacta a Soporte IT o al departamento de Bedelía de UniCABA."
)
}
]
class RAGService:
"""Servicio de indexación y recuperación semántica de fragmentos RAG."""
@classmethod
def reindex_default_knowledge(cls) -> int:
"""Puebla o reinicializa la tabla knowledge_chunks con la documentación oficial."""
try:
KnowledgeChunk.query.delete()
db.session.commit()
except Exception:
db.session.rollback()
count = 0
for doc in OFFICIAL_KNOWLEDGE_BASE:
chunk = KnowledgeChunk(
title=doc["title"],
content=doc["content"],
role=doc["role"],
keywords=doc["keywords"],
category=doc.get("category", "manual")
)
db.session.add(chunk)
count += 1
db.session.commit()
return count
@classmethod
def search_relevant_chunks(cls, query: str, user_role: str, limit: int = 3) -> List[Dict[str, Any]]:
"""
Ejecuta una búsqueda semántica de fragmentos relevantes,
aplicando un filtro estricto por el rol del usuario para evitar fugas de información.
"""
# Asegurar que existan chunks en base de datos
total_chunks = KnowledgeChunk.query.count()
if total_chunks == 0:
cls.reindex_default_knowledge()
normalized_role = (user_role or "alumno").strip().lower()
if "docente" in normalized_role or "profesor" in normalized_role or "teacher" in normalized_role:
effective_role = "docente"
elif "bedelia" in normalized_role or "admin" in normalized_role:
effective_role = "bedelia"
else:
effective_role = "alumno"
# Filtrar exclusivamente por rol permitido y documentos generales
allowed_roles = [effective_role, "general"]
candidates = KnowledgeChunk.query.filter(KnowledgeChunk.role.in_(allowed_roles)).all()
query_tokens = _tokenize(query)
if not query_tokens:
# Si la consulta no tiene tokens específicos, retornar los fragmentos introductorios del rol
return [c.to_dict() for c in candidates[:limit]]
scored = []
for chunk in candidates:
score = 0.0
norm_title = _normalize_text(chunk.title)
norm_content = _normalize_text(chunk.content)
norm_keywords = _normalize_text(chunk.keywords or "")
for token in query_tokens:
# Coincidencia en título (+5 puntos)
if token in norm_title:
score += 5.0
# Coincidencia en keywords (+3 puntos)
if token in norm_keywords:
score += 3.0
# Coincidencia en contenido (+1 punto)
if token in norm_content:
score += 1.0
if score > 0:
scored.append((score, chunk))
# Ordenar de mayor a menor relevancia
scored.sort(key=lambda x: x[0], reverse=True)
if scored:
results = [item[1].to_dict() for item in scored[:limit]]
else:
# Fallback a fragmentos generales del rol
results = [c.to_dict() for c in candidates[:limit]]
return results