feat: arquitectura RAG embebida y asistente UdeCi con botones interactivos (SDD-010, v3.8.25)
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user