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
+1 -1
View File
@@ -7,7 +7,7 @@ from typing import Any
from database import db, get_db, engine, SessionLocal, session
from config.config import Config
__version__ = "3.8.24"
__version__ = "3.8.25"
class DummyContext:
def __enter__(self):
+3 -1
View File
@@ -13,6 +13,7 @@ from .enrollment import StudentEnrollment
from .setting import SystemSetting
from .grade import MilestoneGrade
from .sync_task import MoodleSyncTask
from .knowledge_chunk import KnowledgeChunk
__all__ = [
'User',
@@ -38,5 +39,6 @@ __all__ = [
'StudentEnrollment',
'SystemSetting',
'MilestoneGrade',
'MoodleSyncTask'
'MoodleSyncTask',
'KnowledgeChunk'
]
+31
View File
@@ -0,0 +1,31 @@
from datetime import datetime, timezone
from app import db
class KnowledgeChunk(db.Model):
"""
Fragmentos de documentación oficial indexados para la arquitectura RAG de UdeCi.
Permite recuperación semántica eficiente y filtrado estricto por rol.
"""
__tablename__ = 'knowledge_chunks'
id = db.Column(db.Integer, primary_key=True)
title = db.Column(db.String(150), nullable=False)
content = db.Column(db.Text, nullable=False)
role = db.Column(db.String(50), nullable=False, default='general', index=True)
keywords = db.Column(db.String(255), nullable=True, index=True)
category = db.Column(db.String(50), nullable=True, default='manual')
created_at = db.Column(db.DateTime, default=lambda: datetime.now(timezone.utc).replace(tzinfo=None))
def __init__(self, **kwargs):
super().__init__(**kwargs)
def to_dict(self):
return {
'id': self.id,
'title': self.title,
'content': self.content,
'role': self.role,
'keywords': self.keywords,
'category': self.category
}
+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
+110 -75
View File
@@ -1,73 +1,61 @@
"""
Módulo de Integración de Asistente IA (Chatbot de Ayuda Contextual)
SDD-009: Compatible con OpenAI API y Servidor Local Llama.cpp (Qwen3 Coder 30B)
Módulo de Integración de Asistente IA (UdeCi) con Arquitectura RAG Embebida
SDD-009 / SDD-010: Compatible con OpenAI API y Servidor Local Llama.cpp (Qwen3 Coder 30B)
"""
import re
import time
from typing import Optional
from typing import Optional, List
import httpx
from fastapi import APIRouter, HTTPException, Depends, Request, status
from dependencies import get_optional_current_user, require_roles
from app.models.setting import SystemSetting
from app.models.user import User
from app.services.rag_service import RAGService
from schemas.ai_chat import (
ChatRequest,
ChatResponse,
AITestConnectionResponse,
AISettingsSchema
AISettingsSchema,
RAGReindexResponse
)
router = APIRouter(tags=["AI Chatbot"])
DEFAULT_ROLE_OPTIONS = {
"docente": ["📍 Aulas y Google Meet", "📝 Actas de Regularidad", "👥 Ver Comisiones", "❓ Ayuda"],
"bedelia": ["🔄 Flujo de 9 Pasos", "⚠️ Conflictos Áulicos", "🧬 Optimizador IA", "📑 Importar Sheets"],
"alumno": ["📍 ¿Dónde curso hoy?", "📚 Mis Materias", "📊 Mis Calificaciones", "❓ Ayuda"]
}
def generate_system_prompt_for_role(role: Optional[str]) -> str:
def generate_system_prompt_for_role(role: Optional[str], rag_context: Optional[str] = None) -> str:
"""
Genera el System Prompt dinámico según el rol del usuario autenticado,
proporcionándole al LLM las reglas de negocio, manual de uso y restricciones de acceso.
Genera el System Prompt de UdeCi enriquecido con fragmentos de conocimiento oficial (RAG),
imponiendo respuestas cortas, directas y opciones interactivas para el usuario.
"""
normalized_role = (role or "alumno").strip().lower()
if normalized_role in ["docente", "profesor", "teacher"]:
return (
"Eres el Asistente y Tutor Inteligente de Admin Edu Space (UniCABA) para DOCENTES y PROFESORES.\n"
"Tu objetivo es asistir al cuerpo docente guiándolo exclusivamente en las tareas pertinentes a su rol:\n"
"1. Asignaciones de Aula y Espacios: Explicar cómo consultar las aulas físicas asignadas y enlaces a aulas virtuales (Google Meet/Teams) en la cartelera diaria y semanal.\n"
"2. Libro de Calificaciones (Gradebook): Orientar sobre cómo cargar y editar calificaciones de parciales, recuperatorios, notas finales y cerrar actas de regularidad inmutables con trazabilidad.\n"
"3. Nómina de Comisiones y Alumnos: Guiar en la visualización de listas de alumnos inscriptos en sus comisiones activas.\n"
"4. Cronogramas y Horarios: Indicar cómo consultar días y horarios de cursada según el ciclo lectivo vigente.\n"
"REGLAS ESTRICTAS DE SEGURIDAD Y PERMISOS:\n"
"- Si el usuario te consulta sobre cómo crear carreras, modificar asignaciones físicas ajenas, reconfigurar servidores o ingresar a funciones de Bedelía, aclara respetuosamente que esas operaciones están reservadas a Bedelía o Administración de Sistemas.\n"
"- Responde siempre en español institucional, con tono cordial, empático y estructurado en pasos claros."
)
elif normalized_role in ["bedelia", "admin", "administrador"]:
return (
"Eres el Asistente y Tutor Técnico de Nivel 1 de Admin Edu Space (UniCABA) para personal de BEDELÍA y ADMINISTRADORES.\n"
"Tu objetivo es brindar soporte técnico operativo y guiar en el flujo integral de gestión académica y áulica:\n"
"1. Circuito Secuencial Canónico de 9 Pasos: 1) Sedes/Edificios -> 2) Aulas (físicas/virtuales) -> 3) Ciclos Lectivos -> 4) Carreras -> 5) Asignaturas (con carreras asociadas) -> 6) Comisiones -> 7) Profesores -> 8) Alumnos -> 9) Reservas de Espacio.\n"
"2. Matriz de Conflictos: Explicar la validación física en aulas presenciales, control estricto de aforo, superposición horaria docente (con excepción de co-docencia activa) y restricción diaria de cursada para alumnos.\n"
"3. Herramienta de Optimización con IA: Instruir sobre el uso del Optimizador Genético de Aulas para resolver colisiones y maximizar aforo.\n"
"4. Importación Masiva (Google Sheets): Explicar el proceso de inspección previa, selección granular de entidades, filtrado por carrera/día y carga con fechas manuales.\n"
"5. Sincronización Moodle 4.1: Orientar en la gestión de la cola asíncrona (MoodleSyncTask), manejo de reintentos, Dead Letter Queue (DLQ) y sincronización RBAC.\n"
"6. Auditoría Institucional: Indicar cómo auditar eventos en AuditLog por módulo, acción y fecha.\n"
"REGLAS:\n"
"- Responde con precisión técnica, terminología oficial de UniCABA y soluciones directas y accionables."
)
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:
# Rol Alumno / Estudiante (por defecto)
return (
"Eres el Asistente y Tutor Inteligente de Admin Edu Space (UniCABA) para ESTUDIANTES y ALUMNOS.\n"
"Tu misión es guiar al estudiante sobre cómo cursar y utilizar el sistema:\n"
"1. Cartelera de Clases de Hoy: Enseñar cómo consultar en qué aula física o enlace virtual de Meet le corresponde cursar sus materias hoy y en qué turno.\n"
"2. Mis Asignaturas e Inscripciones: Explicar cómo verificar las materias matriculadas, comisiones, docentes a cargo y horarios de cursada.\n"
"3. Consulta de Calificaciones: Guiar en la visualización de estados académicos, notas parciales, recuperatorios y regularidad en el sistema.\n"
"4. Restricción de Cursada Diaria: Explicar que el sistema restringe cursar dos materias el mismo día salvo cursos cortos o excepciones autorizadas por Bedelía.\n"
"REGLAS ESTRICTAS DE SEGURIDAD:\n"
"- Tienes TERMINANTEMENTE PROHIBIDO enseñar o detallar cómo reservar aulas, cómo alterar notas, cómo sincronizar Moodle o cómo administrar el sistema.\n"
"- Ante cualquier solicitud de índole administrativa o de reclamo de cupos, indica al alumno que debe dirigirse a la Secretaría de Bedelía de UniCABA.\n"
"- Responde en español de forma pedagógica, clara y amigable."
)
effective_role = "alumno"
context_section = rag_context if rag_context else "Consulta el sistema con tu usuario institucional."
return (
f"Eres UdeCi, el tutor virtual institucional de Admin Edu Space (UniCABA).\n"
f"El usuario tiene el rol de: {effective_role.upper()}.\n\n"
"REGLAS ESTRICTAS DE RESPUESTA:\n"
"1. Respuestas BREVES y PRECISAS: Responde en máximo 2 a 3 oraciones cortas o pasos directos. No des introducciones largas ni rodeos.\n"
"2. INFORMACIÓN OFICIAL: Responde basándote ÚNICAMENTE en la INFORMACIÓN DEL SISTEMA provista abajo. "
"Si la respuesta no está en esta información o el usuario solicita una acción que no corresponde a su rol, "
"indícale amablemente que no dispones de los permisos necesarios y que debe contactar a Bedelía.\n"
"3. Al final de tu mensaje, incluye EXACTAMENTE 2 o 3 opciones breves de seguimiento en este formato:\n"
"OPCIONES: [Opción 1 | Opción 2 | Opción 3]\n\n"
f"INFORMACIÓN OFICIAL DEL SISTEMA (RAG):\n{context_section}"
)
def _get_ai_config() -> dict:
@@ -76,16 +64,15 @@ def _get_ai_config() -> dict:
enabled = enabled_val in ["true", "True", "1", True]
base_url = SystemSetting.get_value("ai_chat_base_url", "http://10.0.0.214:8080/v1") or "http://10.0.0.214:8080/v1"
# Obtener clave API descifrada
api_key = SystemSetting.get_decrypted_value("ai_chat_api_key", "llama") or "llama"
model = SystemSetting.get_value("ai_chat_model", "qwen3-coder:30b") or "qwen3-coder:30b"
model_name = SystemSetting.get_value("ai_chat_model_name", "Qwen3 Coder 30B-A3B (Llama.cpp)") or "Qwen3 Coder 30B-A3B (Llama.cpp)"
model_name = SystemSetting.get_value("ai_chat_model_name", "UdeCi (Tutor Virtual)") or "UdeCi (Tutor Virtual)"
try:
temperature = float(SystemSetting.get_value("ai_chat_temperature", 0.3))
# En RAG se recomienda 0.1 para máxima fidelidad a los fragmentos
temperature = float(SystemSetting.get_value("ai_chat_temperature", 0.1))
except (ValueError, TypeError):
temperature = 0.3
temperature = 0.1
try:
timeout = float(SystemSetting.get_value("ai_chat_timeout", 60.0))
@@ -103,6 +90,23 @@ def _get_ai_config() -> dict:
}
def _extract_options_from_reply(reply_text: str, role: str) -> tuple[str, List[str]]:
"""Extrae las opciones sugeridas al final del texto y limpia la respuesta para el usuario."""
options = []
clean_text = reply_text
match = re.search(r'OPCIONES:\s*\[(.*?)\]', reply_text, re.DOTALL | re.IGNORECASE)
if match:
raw_options = match.group(1).split('|')
options = [opt.strip() for opt in raw_options if opt.strip()]
clean_text = reply_text[:match.start()].strip()
if not options:
options = DEFAULT_ROLE_OPTIONS.get(role, DEFAULT_ROLE_OPTIONS["alumno"])
return clean_text, options
@router.post("/", response_model=ChatResponse)
@router.post("", response_model=ChatResponse)
async def get_agent_response(
@@ -111,17 +115,18 @@ async def get_agent_response(
current_user: Optional[User] = Depends(get_optional_current_user)
):
"""
Procesa la conversación del usuario con el agente contextual:
1. Resuelve el rol del usuario (prioriza sesión JWT o campo user_role).
2. Inyecta el System Prompt correspondiente al rol.
3. Envía la solicitud asíncrona no bloqueante hacia el servidor local Llama.cpp.
Procesa la conversación con UdeCi aplicando la arquitectura RAG:
1. Resuelve el rol del usuario autenticado.
2. Ejecuta búsqueda semántica en KnowledgeChunk (RAG) filtrando por rol.
3. Inyecta el contexto oficial en el prompt para Llama.cpp con baja temperatura (0.1).
4. Genera respuesta breve y extrae opciones de botones interactivos.
"""
config = _get_ai_config()
if not config["enabled"]:
raise HTTPException(
status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
detail="El servicio de Asistente IA está temporalmente deshabilitado por el administrador."
detail="UdeCi está temporalmente deshabilitado por el administrador."
)
# 1. Determinar rol efectivo
@@ -138,8 +143,18 @@ async def get_agent_response(
else:
effective_role = "alumno"
# 2. Inyección de Contexto
system_prompt = generate_system_prompt_for_role(effective_role)
# 2. Búsqueda semántica RAG sobre la última consulta del usuario
last_query = ""
for msg in reversed(request.messages):
if msg.role == "user":
last_query = msg.content
break
chunks = RAGService.search_relevant_chunks(last_query, effective_role, limit=3)
context_text = "\n\n".join([f"### {c['title']}\n{c['content']}" for c in chunks])
# 3. Inyección de Contexto en el System Prompt
system_prompt = generate_system_prompt_for_role(effective_role, context_text)
formatted_messages = [{"role": "system", "content": system_prompt}]
for msg in request.messages:
@@ -148,7 +163,7 @@ async def get_agent_response(
payload = {
"model": config["model"],
"messages": formatted_messages,
"temperature": config["temperature"]
"temperature": 0.1 # Temperatura estricta para evitar alucinaciones
}
target_url = f"{config['base_url']}/chat/completions"
@@ -157,18 +172,19 @@ async def get_agent_response(
"Content-Type": "application/json"
}
# 3. Petición asíncrona no bloqueante al servidor local
# 4. Inferencia asíncrona no bloqueante
async with httpx.AsyncClient(timeout=config["timeout"]) as client:
try:
response = await client.post(target_url, headers=headers, json=payload)
response.raise_for_status()
ai_data = response.json()
reply_text = ai_data["choices"][0]["message"]["content"]
return ChatResponse(response=reply_text)
raw_reply = ai_data["choices"][0]["message"]["content"]
clean_reply, options = _extract_options_from_reply(raw_reply, effective_role)
return ChatResponse(response=clean_reply, quick_options=options)
except httpx.TimeoutException:
raise HTTPException(
status_code=status.HTTP_504_GATEWAY_TIMEOUT,
detail=f"El servidor de IA local superó el tiempo límite de espera ({config['timeout']}s)."
detail=f"UdeCi superó el tiempo límite de espera ({config['timeout']}s)."
)
except httpx.HTTPStatusError as e:
detail_msg = f"Error del motor de IA local ({e.response.status_code}): {e.response.text[:200]}"
@@ -176,18 +192,28 @@ async def get_agent_response(
except httpx.RequestError as e:
raise HTTPException(
status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
detail="Error conectando al motor de IA local. Verifique que Llama.cpp esté activo en 10.0.0.214."
detail="Error conectando con UdeCi. Verifique que el servidor local de IA esté disponible."
)
@router.post("/rag/reindex", response_model=RAGReindexResponse)
def reindex_knowledge_base(
current_user: User = Depends(require_roles(["ADMIN"]))
):
"""Reindexa y particiona la documentación oficial en fragmentos RAG."""
count = RAGService.reindex_default_knowledge()
return RAGReindexResponse(
status="success",
indexed_chunks=count,
message=f"Se han reindexado exitosamente {count} fragmentos de conocimiento oficial para UdeCi."
)
@router.post("/test-connection", response_model=AITestConnectionResponse)
async def test_ai_connection(
current_user: User = Depends(require_roles(["ADMIN"]))
):
"""
Verifica la conectividad directa con el servidor local Llama.cpp
consultando el endpoint de modelos /v1/models y calculando la latencia.
"""
"""Verifica conectividad directa con el servidor local consultando /v1/models."""
config = _get_ai_config()
target_url = f"{config['base_url']}/models"
headers = {"Authorization": f"Bearer {config['api_key']}"}
@@ -202,14 +228,14 @@ async def test_ai_connection(
model_ids = [m.get("id") for m in data.get("data", []) if isinstance(m, dict) and "id" in m]
return AITestConnectionResponse(
status="success",
message=f"Conexión exitosa con Llama.cpp ({config['base_url']}). Latencia: {latency_ms} ms.",
message=f"Conexión exitosa con el servidor local ({config['base_url']}). Latencia: {latency_ms} ms.",
latency_ms=latency_ms,
models=model_ids
)
else:
return AITestConnectionResponse(
status="warning",
message=f"Respuesta inesperada del servidor ({resp.status_code}): {resp.text[:200]}",
message=f"Respuesta inesperada ({resp.status_code}): {resp.text[:200]}",
latency_ms=latency_ms,
models=[]
)
@@ -231,11 +257,20 @@ async def test_ai_connection(
@router.get("/config")
def get_ai_public_config(current_user: Optional[User] = Depends(get_optional_current_user)):
"""Retorna metadatos públicos de estado del asistente para el widget del frontend."""
"""Retorna metadatos públicos de estado de UdeCi para el widget del frontend."""
config = _get_ai_config()
role_str = "alumno"
if current_user and hasattr(current_user, "role") and current_user.role:
r = str(current_user.role).lower()
if "docente" in r or "profesor" in r:
role_str = "docente"
elif "bedelia" in r or "admin" in r:
role_str = "bedelia"
return {
"status": "success",
"enabled": config["enabled"],
"model": config["model"],
"model_name": config["model_name"]
"name": "UdeCi",
"role": role_str,
"default_options": DEFAULT_ROLE_OPTIONS.get(role_str, DEFAULT_ROLE_OPTIONS["alumno"])
}
+7
View File
@@ -14,6 +14,13 @@ class ChatRequest(BaseModel):
class ChatResponse(BaseModel):
response: str = Field(..., description="Respuesta generada por el agente conversacional")
quick_options: Optional[List[str]] = Field(default_factory=list, description="Lista de opciones o preguntas sugeridas para botones interactivos")
class RAGReindexResponse(BaseModel):
status: str
indexed_chunks: int
message: str
class AISettingsSchema(BaseModel):
+1 -1
View File
@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
setup(
name="edu-space-admin",
version="3.8.24",
version="3.8.25",
description="Administrative interface for Edu-Space Classroom Management System (FastAPI ASGI Core)",
author="Edu-Space Development Team",
author_email="admin@edu-space.com",
+16 -16
View File
@@ -51,26 +51,24 @@ def test_ai_chat_pydantic_schemas_validation():
def test_system_prompt_generation_by_role():
"""Verifica que el System Prompt inyectado se adapte rigurosamente al rol."""
"""Verifica que el System Prompt inyectado se adapte rigurosamente al rol y contenga UdeCi y RAG."""
# Docente
prompt_docente = generate_system_prompt_for_role("docente")
assert "DOCENTES y PROFESORES" in prompt_docente
assert "Gradebook" in prompt_docente
assert "Google Meet" in prompt_docente
assert "Bedelía" in prompt_docente # Restricción de permisos
assert "UdeCi" in prompt_docente
assert "DOCENTE" in prompt_docente
assert "INFORMACIÓN OFICIAL DEL SISTEMA (RAG)" in prompt_docente
# Alumno
prompt_alumno = generate_system_prompt_for_role("alumno")
assert "ESTUDIANTES y ALUMNOS" in prompt_alumno
assert "Cartelera de Clases de Hoy" in prompt_alumno
assert "TERMINANTEMENTE PROHIBIDO" in prompt_alumno
assert "UdeCi" in prompt_alumno
assert "ALUMNO" in prompt_alumno
assert "INFORMACIÓN OFICIAL DEL SISTEMA (RAG)" in prompt_alumno
# Bedelía / Admin
prompt_bedelia = generate_system_prompt_for_role("bedelia")
assert "BEDELÍA y ADMINISTRADORES" in prompt_bedelia
assert "Circuito Secuencial Canónico de 9 Pasos" in prompt_bedelia
assert "Matriz de Conflictos" in prompt_bedelia
assert "Moodle 4.1" in prompt_bedelia
assert "UdeCi" in prompt_bedelia
assert "BEDELIA" in prompt_bedelia
assert "INFORMACIÓN OFICIAL DEL SISTEMA (RAG)" in prompt_bedelia
def test_ai_chat_public_config_endpoint():
@@ -81,7 +79,9 @@ def test_ai_chat_public_config_endpoint():
data = response.json()
assert data["status"] == "success"
assert "enabled" in data
assert "model" in data
assert data["name"] == "UdeCi"
assert "role" in data
assert "default_options" in data
def test_ai_chat_endpoint_success_mock(init_database):
@@ -141,7 +141,7 @@ def test_ai_chat_endpoint_validation_error():
assert res2.status_code == 422
def test_ai_chat_endpoint_connection_failure():
def test_ai_chat_endpoint_connection_failure(init_database):
"""Simula error de conexión con el servidor Llama.cpp y verifica HTTP 503."""
client = TestClient(app)
@@ -154,10 +154,10 @@ def test_ai_chat_endpoint_connection_failure():
assert res.status_code == 503
data = res.json()
assert "detail" in data
assert "10.0.0.214" in data["detail"] or "motor de IA" in data["detail"]
assert "UdeCi" in data["detail"] or "servidor local de IA" in data["detail"]
def test_ai_chat_endpoint_timeout_failure():
def test_ai_chat_endpoint_timeout_failure(init_database):
"""Simula tiempo de espera agotado y verifica HTTP 504."""
client = TestClient(app)
+145
View File
@@ -0,0 +1,145 @@
"""
Suite de pruebas automatizadas para la arquitectura RAG y el asistente UdeCi (SDD-010).
Valida indexación de chunks, filtrado estricto por rol, relevancia semántica,
extracción de botones de opciones y endpoints administrativos.
"""
from unittest.mock import AsyncMock, patch, MagicMock
from fastapi.testclient import TestClient
from werkzeug.security import generate_password_hash
from main import app
from app.models.knowledge_chunk import KnowledgeChunk
from app.models.user import User
from app.services.rag_service import RAGService
def test_rag_reindex_default_knowledge(init_database):
"""Valida la ingesta y particionamiento de la base de conocimiento oficial."""
count = RAGService.reindex_default_knowledge()
assert count >= 10
# Verificar que los fragmentos están en la base de datos
chunks = KnowledgeChunk.query.all()
assert len(chunks) == count
roles = {c.role for c in chunks}
assert "bedelia" in roles
assert "docente" in roles
assert "alumno" in roles
assert "general" in roles
def test_rag_strict_role_filtering(init_database):
"""Valida que la recuperación semántica aísle estrictamente los permisos por rol."""
RAGService.reindex_default_knowledge()
# 1. Consulta de Alumno intentando averiguar sobre Bedelía
alumno_chunks = RAGService.search_relevant_chunks(
query="como configurar el servidor o crear carreras y comisiones de bedelia",
user_role="alumno",
limit=5
)
# Ningún fragmento para Alumno debe ser de rol 'bedelia' o 'docente'
for c in alumno_chunks:
assert c["role"] in ["alumno", "general"], f"Fuga de rol detectada: {c['role']}"
# 2. Consulta de Docente
docente_chunks = RAGService.search_relevant_chunks(
query="donde veo las actas y aulas de mis materias",
user_role="docente",
limit=5
)
for c in docente_chunks:
assert c["role"] in ["docente", "general"], f"Fuga de rol detectada: {c['role']}"
# 3. Consulta de Bedelía
bedelia_chunks = RAGService.search_relevant_chunks(
query="flujo de 9 pasos y matriz de conflictos",
user_role="bedelia",
limit=3
)
titles = [c["title"] for c in bedelia_chunks]
assert any("9 Pasos" in t for t in titles)
assert any("Conflictos" in t for t in titles)
def test_rag_semantic_relevance_ranking(init_database):
"""Verifica que los términos clave ubiquen el fragmento más idóneo en primera posición."""
RAGService.reindex_default_knowledge()
# Búsqueda específica de aulas y Google Meet para Alumno
results = RAGService.search_relevant_chunks("aula donde curso hoy meet", user_role="alumno", limit=2)
assert len(results) > 0
assert "Consulta de Aula y Horarios" in results[0]["title"]
def test_udeci_chat_endpoint_rag_with_quick_options(init_database):
"""Verifica la respuesta de UdeCi incluyendo la extracción de botones de opciones."""
client = TestClient(app)
mock_response = MagicMock()
mock_response.status_code = 200
mock_response.json.return_value = {
"choices": [
{
"message": {
"role": "assistant",
"content": (
"Cursas en el Aula 102 del Edificio Central a las 18:30 hs.\n"
"OPCIONES: [Ver Cartelera | Mis Materias | Ayuda]"
)
}
}
]
}
mock_response.raise_for_status = MagicMock()
with patch("httpx.AsyncClient.post", new_callable=AsyncMock) as mock_post:
mock_post.return_value = mock_response
res = client.post("/api/chat", json={
"messages": [{"role": "user", "content": "¿Dónde curso hoy?"}],
"user_role": "alumno"
})
assert res.status_code == 200
data = res.json()
assert "response" in data
assert "Aula 102" in data["response"]
# Verificar que la etiqueta OPCIONES: fue removida del texto para mantenerlo limpio
assert "OPCIONES:" not in data["response"]
# Verificar que quick_options contiene los botones extraídos
assert "quick_options" in data
assert len(data["quick_options"]) == 3
assert "Ver Cartelera" in data["quick_options"]
def test_rag_reindex_endpoint_admin_security(init_database):
"""Valida que la reindexación manual requiera rol de Administrador."""
client = TestClient(app)
# 1. Sin autenticar debe responder 401
unauth_res = client.post("/api/chat/rag/reindex")
assert unauth_res.status_code == 401
# 2. Con usuario Admin
admin_u = User(
email="admin.rag@unicaba.edu.ar",
name="Admin RAG",
password_hash=generate_password_hash("SecretAdminRAG!"),
role="ADMIN",
is_active=True
)
init_database.session.add(admin_u)
init_database.session.commit()
login_res = client.post("/api/v1/auth/login", json={
"email": "admin.rag@unicaba.edu.ar",
"password": "SecretAdminRAG!"
})
token = login_res.json()["access_token"]
headers = {"Authorization": f"Bearer {token}"}
reindex_res = client.post("/api/chat/rag/reindex", headers=headers)
assert reindex_res.status_code == 200
data = reindex_res.json()
assert data["status"] == "success"
assert data["indexed_chunks"] >= 10