7.3 KiB
Especificación: Asistente IA y Chatbot de Ayuda Contextual (SDD-009)
1. Contexto y Objetivos del Módulo
La plataforma Admin Edu Space coordina el ecosistema académico de UniCABA para múltiples perfiles: personal de Bedelía, docentes y estudiantes. Debido a la amplitud de funciones (gestión de espacios áulicos, sincronización con Moodle 4.1, actas de regularidad, asignación de comisiones y consultas de cursada), los usuarios requieren orientación inmediata y contextualizada sobre cómo operar el sistema según su propio nivel de privilegios y responsabilidades.
Este módulo implementa un asistente conversacional (chatbot de ayuda contextual) impulsado por un modelo de lenguaje local (Llama.cpp ejecutando Qwen3 Coder 30B-A3B) hosteado en la infraestructura institucional (http://10.0.0.214:8080/v1).
El agente conversacional actúa como un tutor interactivo cuyas respuestas y contexto están estrictamente acotados al rol del usuario autenticado (alumno, docente, bedelia / admin), previniendo la divulgación de capacidades no autorizadas y ofreciendo instrucciones paso a paso directamente aplicables a su flujo de trabajo.
2. Requisitos Funcionales en Sintaxis EARS
2.1 Configuración Global del Proveedor de IA (/admin/settings)
-
RF-01 (Ubicuo - Pestaña de Configuración IA en el Panel de Administración):
EL SISTEMA presentará una pestaña dedicada 'Asistente IA & LLM Local' en la vista de Configuración Global (/admin/settings) accesible exclusivamente para administradores. -
RF-02 (Basado en Eventos - Persistencia de Parámetros del Motor de IA):
CUANDO el administrador actualice la URL base (default: http://10.0.0.214:8080/v1), la clave API, el identificador del modelo (default: qwen3-coder:30b), la temperatura, el timeout o el estado de activación, EL SISTEMA validará los datos mediante Pydantic v2 y los persistirá de forma segura en la tabla system_settings. -
RF-03 (Basado en Eventos - Prueba de Conectividad con el Servidor Local):
CUANDO el administrador presione el botón 'Probar Conexión con Llama.cpp', EL SISTEMA ejecutará una verificación asíncrona contra el endpoint /v1/models o un healthcheck del servidor local, retornando el estado de latencia y disponibilidad en la interfaz. -
RF-04 (No Deseado - Degradación Controlada ante Servidor de IA Inaccesible):
SI el servidor de Llama.cpp no responde dentro del tiempo límite o se encuentra fuera de línea, ENTONCES EL SISTEMA capturará la excepción de red y retornará un error HTTP 503 con un mensaje descriptivo en español, sin bloquear el servidor FastAPI ni degradar la experiencia general de la plataforma.
2.2 Backend Core y API REST (backend/routers/ai_chat.py)
-
RF-05 (Ubicuo - Validación de Contratos con Pydantic v2):
EL SISTEMA validará las solicitudes al endpoint de chat mediante esquemas Pydantic v2 (ChatRequest, ChatMessage, ChatResponse), exigiendo formato válido de mensajes, longitud mínima de contenido y roles reconocidos, respondiendo con HTTP 422 Unprocessable Entity en caso de discordancia de esquema. -
RF-06 (Basado en Eventos - Inferencia Asíncrona no Bloqueante con httpx):
CUANDO un usuario autenticado envíe una consulta al asistente (/api/chat o /api/v1/chat), EL SISTEMA procesará la llamada utilizando httpx.AsyncClient con await no bloqueante y timeout configurable (default: 60s con soporte de hasta 600s), preservando la concurrencia de FastAPI. -
RF-07 (Basado en Estados - Inyección Dinámica de System Prompt según Rol):
MIENTRAS el usuario posea un rol específico ('alumno', 'docente', 'bedelia' o 'admin'), EL SISTEMA antepondrá de forma invisible en el payload enviado al LLM el manual de instrucciones y las restricciones de seguridad correspondientes a dicho perfil. -
RF-08 (No Deseado - Restricción de Alcance y Prevención de Fuga de Permisos):
SI un usuario con rol 'alumno' indaga sobre funciones administrativas, edición de aulas, modificación de notas o sincronización de Moodle, ENTONCES EL SISTEMA instruirá al LLM a declinar amablemente la respuesta indicando que dicha operación está reservada al personal de Bedelía o Secretaría Académica.
2.3 Interfaz de Usuario y Widget del Chatbot (Frontend BFF & UI)
-
RF-09 (Opcional - Widget Flotante del Asistente en la Interfaz):
DONDE el usuario se encuentre autenticado y la integración de IA esté habilitada, EL SISTEMA desplegará un botón flotante y un panel de chat interactivo en el extremo inferior de la pantalla, con micro-animaciones, soporte de modo oscuro/claro y visor de respuestas con formato legible. -
RF-10 (Basado en Eventos - Transmisión de Consulta e Indicador de Carga):
CUANDO el usuario envíe una pregunta mediante el widget de chat, EL SISTEMA mostrará un indicador animado de procesamiento ('El tutor está escribiendo...'), mantendrá el foco del scroll y presentará la respuesta generada por el modelo al finalizar la inferencia.
3. Matriz de Prompts de Sistema por Rol (Contextual Guidance)
| Rol del Usuario | Enfoque del Tutor IA | Reglas y Restricciones Específicas |
|---|---|---|
Docente (docente, profesor, teacher) |
Asistente de Gestión de Cátedra | Enseña a: consultar asignaciones de aula, registrar asistencia, cargar actas de regularidad en el Gradebook, verificar horarios semanales y enlaces de aulas virtuales (Google Meet). Prohibido: habilitar o explicar cómo crear carreras o reconfigurar servidores. |
Alumno (alumno, estudiante, student) |
Asistente de Cursada y Orientación | Enseña a: consultar materias matriculadas, consultar cartelera de clases del día, verificar horarios, identificar aulas asignadas y consultar estado académico. Estrictamente prohibido: detallar procedimientos de Bedelía, administración de espacios o edición de calificaciones. |
Bedelía / Admin (bedelia, admin, administrador) |
Soporte Técnico Nivel 1 y Operación Áulica | Enseña a: flujo secuencial de 9 pasos (Sedes -> Aulas -> Ciclos -> Carreras -> Materias -> Comisiones -> Profesores -> Alumnos -> Reservas), resolución de matriz de conflictos físicos/docentes, importación de Google Sheets con previsualización, sincronización con Moodle 4.1 y monitoreo de auditoría. |
4. Criterios de Aceptación y Validación
- Configuración Global: La pestaña "Asistente IA & LLM Local" en
/admin/settingsdebe cargar la configuración actual, permitir su edición y probar conectividad con respuesta en vivo. - Contrato de API:
POST /api/chat/oPOST /api/v1/chat/debe validar con PydanticChatRequesty responder conChatResponse.- Cargas no válidas deben retornar
422 Unprocessable Entity. - Si el servidor local de Llama.cpp no responde, debe retornar
503 Service Unavailablecon mensaje amigable.
- Seguridad y Aislamiento por Rol: Las consultas de un alumno deben recibir respuestas adaptadas al estudiante y rechazar peticiones de gestión áulica.
- Widget de UI: El widget flotante debe integrarse armónicamente en el layout general de la aplicación (
base.html), respetando temas claro y oscuro (data-bs-theme), permitiendo abrir, minimizar y enviar mensajes fluidamente. - Calidad y Robustez: 100% de la suite de pruebas unitarias/integración aprobadas en pytest y cero errores de diagnóstico en Pyright (
@[current_problems]).