# 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.