Files

3.5 KiB

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.