# 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]`).