# Especificación: Arquitectura RAG y Asistente UdeCi (SDD-010) ## 1. Contexto y Objetivos del Módulo Como evolución de la especificación SDD-009, el asistente conversacional se renombra oficialmente como **UdeCi** (Tutor Virtual de UniCABA). Para garantizar una experiencia de usuario ágil, institucional y sin saturación cognitiva: 1. **Identidad y Privacidad Técnica**: Se sustituye la exposición de detalles técnicos (Llama.cpp, Qwen3, KV Cache) en la interfaz del chat por una identidad limpia y pedagógica: **UdeCi**, indicando únicamente *"Tutor Virtual UniCABA"* y *"En línea"*. 2. **UX/UI Optimizada con Respuestas Cortas y Botones Interactivos**: Las respuestas deben ser breves (2 a 3 oraciones concisas), acompañadas de botones/chips interactivos de acción rápida tanto en la bienvenida inicial como al final de cada respuesta. 3. **Arquitectura RAG Embebida (Retrieval-Augmented Generation)**: Para evitar el consumo excesivo de ventana de contexto en el LLM (RTX 3090) y erradicar alucinaciones, el sistema implementa un motor semántico vectorial local embebido en SQLite. El sistema extrae los fragmentos oficiales pertinentes a la consulta del usuario aplicando un filtro estricto por rol (`WHERE role IN (:user_role, 'general')`), inyectando únicamente dichos fragmentos en el prompt de UdeCi. --- ## 2. Requisitos Funcionales en Sintaxis EARS ### 2.1 Identidad y Experiencia de Usuario (UdeCi) - **RF-01 (Ubicuo - Identidad Institucional UdeCi)**: `EL SISTEMA presentará al agente conversacional bajo el nombre 'UdeCi' (Tutor Virtual UniCABA), suprimiendo etiquetas técnicas internas (como 'Llama.cpp' o 'Qwen3 Coder 30B') de la vista accesible para estudiantes, docentes y bedelía.` - **RF-02 (Ubicuo - Respuestas Concisas y Estructuradas)**: `EL SISTEMA instruirá a UdeCi en su System Prompt a generar respuestas breves de máximo 2 a 3 párrafos o pasos concisos, evitando redundancias y facilitando la lectura inmediata.` - **RF-03 (Basado en Eventos - Botones de Opciones Rápidas)**: `CUANDO el usuario abra el chat o reciba una respuesta de UdeCi, EL SISTEMA presentará botones de opción rápida (chips clickeables) con consultas frecuentes según su rol (ej: '📍 ¿Dónde curso hoy?', '📝 Calificaciones', '🔄 Flujo de 9 pasos', '⚠️ Conflictos'), enviando la consulta con un solo clic.` ### 2.2 Motor RAG Embebido (Almacén Vectorial y Recuperación Semántica) - **RF-04 (Ubicuo - Almacenamiento Relacional de Fragmentos de Conocimiento)**: `EL SISTEMA mantendrá en la base de datos relacional una tabla 'knowledge_chunks' conteniendo el texto fragmentado, título de la sección, rol de destino ('docente', 'alumno', 'bedelia', 'general'), metadatos y vector semántico ponderado.` - **RF-05 (Basado en Eventos - Ingesta e Indexación de Documentación Oficial)**: `CUANDO se ejecute la inicialización o reindexación del conocimiento (POST /api/chat/rag/reindex), EL SISTEMA dividirá los manuales operativos de Bedelía, Docentes y Alumnos en fragmentos de ~300 a 500 palabras y los persistirá en la tabla de conocimiento.` - **RF-06 (Basado en Eventos - Búsqueda Semántica con Filtro Estricto por Rol)**: `CUANDO un usuario realice una consulta al endpoint /api/chat o /api/v1/chat, EL SISTEMA ejecutará una búsqueda semántica de los 3 fragmentos más relevantes restringiendo la búsqueda exclusivamente al rol del usuario y a la categoría general (WHERE role IN (:user_role, 'general')), impidiendo la filtración de información administrativa hacia roles de menor privilegio.` - **RF-07 (Basado en Estados - Aumento del Prompt con Contexto RAG)**: `MIENTRAS se disponga de fragmentos relevantes para la consulta, EL SISTEMA antepondrá dicha información oficial en el System Prompt de UdeCi, fijando la temperatura en 0.1 para forzar fidelidad estricta al manual institucional.` - **RF-08 (No Deseado - Manejo de Consultas Fuera de Dominio o sin Permisos)**: `SI la consulta del usuario no encuentra correspondencia en la base de conocimiento oficial o solicita acciones prohibidas para su rol, ENTONCES EL SISTEMA instruirá a UdeCi a responder brevemente que no dispone de dicha información y orientará al usuario a contactar a Bedelía.` --- ## 3. Matriz de Opciones Rápidas por Rol | Rol | Botones de Opciones Rápidas Iniciales | | :--- | :--- | | **Docente** | `📍 Aulas y Google Meet`, `📝 Actas de Regularidad`, `👥 Ver Comisiones`, `❓ Ayuda General` | | **Alumno** | `📍 ¿Dónde curso hoy?`, `📚 Mis Materias`, `📊 Mis Calificaciones`, `❓ Ayuda Cursada` | | **Bedelía / Admin** | `🔄 Flujo de 9 Pasos`, `⚠️ Conflictos Áulicos`, `🧬 Optimizador IA`, `📑 Importar Sheets`, `🎓 Moodle 4.1` | --- ## 4. Criterios de Aceptación 1. La cabecera del chat muestra **UdeCi · Tutor Virtual UniCABA** con indicador de estado "En línea", sin menciones a Llama.cpp ni Qwen3. 2. Cada mensaje del asistente incluye o genera chips de opciones rápidas clickeables que disparan consultas inmediatas. 3. El endpoint `/api/chat/` ejecuta la búsqueda RAG en SQLite filtrando por rol, inyecta los fragmentos recuperados en el prompt con `temperature=0.1` y genera respuestas breves y directas. 4. El endpoint administrativo `POST /api/chat/rag/reindex` puebla o actualiza los fragmentos de conocimiento con éxito. 5. 100% de tests aprobados en pytest y cero diagnósticos de error en el Language Server.