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
+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"])
}