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
+61
View File
@@ -0,0 +1,61 @@
# Plan Técnico: Arquitectura RAG Embebida y Asistente UdeCi (SDD-010)
## 1. Arquitectura Técnica de la Solución (4 Capas)
### 1.1 Capa de Esquemas y Contratos (`backend/schemas/ai_chat.py`)
- Extender `ChatResponse` para soportar sugerencias de acciones / botones opcionales:
- `quick_options: Optional[List[str]] = Field(default_factory=list, description="Lista de opciones o preguntas de seguimiento en botones")`
- `RAGReindexResponse(BaseModel)`:
- `status: str`
- `indexed_chunks: int`
- `message: str`
### 1.2 Capa de Persistencia y Base de Datos (`backend/app/models/knowledge_chunk.py`)
- Modelo SQLAlchemy 2.0 `KnowledgeChunk`:
- `id`: Integer primary key
- `title`: String(150), nullable=False
- `content`: Text, nullable=False
- `role`: String(50), index=True (ej. 'alumno', 'docente', 'bedelia', 'general')
- `keywords`: String(255), index=True
- `category`: String(50), default='manual'
- `created_at`: DateTime
- Métodos de búsqueda semántica local:
- Búsqueda híbrida ponderada (palabras clave + coincidencia contextual normalizada + filtro estricto de rol `role IN (:role, 'general')`).
### 1.3 Capa de Lógica RAG y Routers FastAPI (`backend/routers/ai_chat.py`)
- **`RAGService`**:
- `search_relevant_chunks(query: str, user_role: str, limit: int = 3) -> List[KnowledgeChunk]`: Realiza la consulta filtrada en SQLite y extrae los 3 fragmentos más relevantes.
- `reindex_default_knowledge() -> int`: Ingesta y particiona los manuales de Bedelía (9 pasos, matriz de conflictos, optimizador genético, sheets, Moodle), Docentes (aulas, actas Gradebook, Meet) y Alumnos (cartelera, materias, notas).
- **Prompt Dinámico RAG**:
- Inyecta únicamente los fragmentos recuperados.
- Instruye a UdeCi a responder de forma **breve** (2 a 3 oraciones o pasos directos), en tono cordial institucional, y a proponer 2 o 3 opciones en formato de botones `[Opción 1 | Opción 2]`.
- Temperatura fijada en `0.1` para eliminar alucinaciones.
- **Endpoints**:
- `POST /api/chat/` (y `/api/v1/chat/`): Procesa la consulta mediante RAG + Llama.cpp.
- `POST /api/chat/rag/reindex`: Endpoint administrativo para reindexar la base de conocimiento.
### 1.4 Capa de Frontend BFF y UI (Widget UdeCi)
- **`frontend/views/partials/ai_chat_widget.html`**:
- Reemplazo total de nombres técnicos por **UdeCi · Tutor Virtual UniCABA**.
- Barra de opciones rápidas con botones/chips según el rol del usuario.
- **`frontend/public/js/ai-chat-widget.js`**:
- Renderizado de chips de botones interactivos debajo de los mensajes.
- Al hacer clic en cualquier chip, envía automáticamente la pregunta al chat.
- Parseo automático de opciones devueltas por UdeCi para renderizarlas como botones de seguimiento.
---
## 2. Plan de Pruebas Automatizadas (`backend/tests/test_rag_udeci.py`)
1. Validación de partición e indexación de fragmentos en `KnowledgeChunk`.
2. Verificación de filtrado estricto por rol: un alumno nunca recibe fragmentos con `role='bedelia'`.
3. Verificación de búsqueda semántica retornando los fragmentos oficiales pertinentes.
4. Verificación de formato de respuesta breve con botones de opciones `quick_options`.
5. Ejecución del 100% de la suite de pruebas (`pytest tests -v`).
---
## 3. Plan de Despliegue en Producción
1. Cero errores estáticos (`py_compile`).
2. Suite completa de tests en verde.
3. Bump semántico a `v3.8.25` en `package.json`, `app.js`, `__init__.py`, `setup.py`, `CHANGELOG.md` y `MEMORY.md`.
4. `git push origin dev` y despliegue SSH a LXC `10.0.0.217` con reinicio de servicios y smoke test.
+58
View File
@@ -0,0 +1,58 @@
# 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.
+59
View File
@@ -0,0 +1,59 @@
# Desglose de Tareas: Arquitectura RAG Embebida y Asistente UdeCi (SDD-010)
## Tareas de Implementación
- [x] **Tarea 1: Modelo Relacional KnowledgeChunk y Esquemas Pydantic v2 RAG**
- **Estimación**: 20 min
- **Acciones**:
- Crear `backend/app/models/knowledge_chunk.py` con el modelo `KnowledgeChunk` (id, title, content, role, keywords, category, created_at).
- Actualizar `backend/schemas/ai_chat.py` agregando `quick_options` en `ChatResponse` y el esquema `RAGReindexResponse`.
- **Hecho cuando**: El modelo se crea en base de datos y los esquemas validan los nuevos campos de respuesta y opciones.
- [x] **Tarea 2: Servicio RAG de Ingesta, Particionamiento y Búsqueda Semántica con Filtro de Rol**
- **Estimación**: 30 min
- **Acciones**:
- Crear `backend/app/services/rag_service.py` con:
- `reindex_default_knowledge()`: Fragmentos oficiales para Bedelía (9 pasos, conflictos, optimizador, sheets, Moodle), Docentes (aulas, actas Gradebook, Meet) y Alumnos (cartelera, materias, notas).
- `search_relevant_chunks(query, user_role, limit)`: Búsqueda ponderada filtrando estrictamente por `role IN (user_role, 'general')`.
- **Hecho cuando**: La búsqueda semántica retorna los fragmentos exactos y respeta el aislamiento estricto de roles.
- [x] **Tarea 3: Actualización del Router FastAPI con Pipeline RAG y Redacción Concisa**
- **Estimación**: 25 min
- **Acciones**:
- Modificar `backend/routers/ai_chat.py` para invocar `RAGService.search_relevant_chunks(...)`.
- Adaptar el System Prompt para:
* Identificar al agente como **UdeCi**.
* Imponer respuestas directas y breves (máximo 2 a 3 oraciones).
* Extraer o estructurar opciones con botones para el usuario.
* Fijar temperatura en `0.1` para ceñirse a los fragmentos RAG.
- Agregar endpoint `POST /api/chat/rag/reindex` para recarga de la base de conocimiento.
- **Hecho cuando**: El endpoint devuelve respuestas breves respaldadas en RAG con botones de opciones y temperatura 0.1.
- [x] **Tarea 4: Rediseño UX/UI del Widget de Chat UdeCi con Botones de Acción Rápida**
- **Estimación**: 30 min
- **Acciones**:
- Modificar `frontend/views/partials/ai_chat_widget.html`:
* Renombrar a **UdeCi · Tutor Virtual UniCABA**.
* Eliminar referencias técnicas (Llama.cpp, Qwen3, KV Cache).
* Añadir barra de chips de opciones iniciales por rol.
- Actualizar `frontend/public/js/ai-chat-widget.js`:
* Soporte para renderizar chips de opciones dentro de la conversación.
* Envío automático al hacer clic en un botón.
* Parsing de botones de seguimiento desde la respuesta de UdeCi.
- **Hecho cuando**: El usuario interactúa con UdeCi viendo solo información pedagógica y usando botones rápidos para consultar.
- [x] **Tarea 5: Suite de Pruebas Automatizadas en Backend (`test_rag_udeci.py`)**
- **Estimación**: 20 min
- **Acciones**:
- Crear `backend/tests/test_rag_udeci.py` validando ingesta, búsqueda con filtro de roles, respuesta corta y botones de opciones.
- Ejecutar suite completa `pytest tests -v` y validar 100% verde (94 pasados).
- **Hecho cuando**: Todas las pruebas unitarias pasan con éxito y 0 errores en `py_compile`.
- [x] **Tarea 6: Bump Semántico a v3.8.25, Git Push y Despliegue en Producción**
- **Estimación**: 20 min
- **Acciones**:
- Incrementar versión semántica a `v3.8.25` en descriptores y documentación.
- Actualizar `CHANGELOG.md` y `MEMORY.md`.
- Ejecutar `git add .`, commit y `git push origin dev`.
- Desplegar en producción LXC `10.0.0.217` y verificar en caliente.
- **Hecho cuando**: Producción corre en `v3.8.25` con UdeCi y RAG activos.