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.