Files
admin-edu-space/specs/009-asistente-ia-chatbot/spec.md
T

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

  1. Configuración Global: La pestaña "Asistente IA & LLM Local" en /admin/settings debe cargar la configuración actual, permitir su edición y probar conectividad con respuesta en vivo.
  2. Contrato de API:
    • POST /api/chat/ o POST /api/v1/chat/ debe validar con Pydantic ChatRequest y responder con ChatResponse.
    • Cargas no válidas deben retornar 422 Unprocessable Entity.
    • Si el servidor local de Llama.cpp no responde, debe retornar 503 Service Unavailable con mensaje amigable.
  3. Seguridad y Aislamiento por Rol: Las consultas de un alumno deben recibir respuestas adaptadas al estudiante y rechazar peticiones de gestión áulica.
  4. 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.
  5. 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]).