From fb46de5f28d71910e7b6e9ea17204520b81f4f9a Mon Sep 17 00:00:00 2001 From: Carlos Tello Date: Tue, 27 Oct 2026 07:58:26 -0300 Subject: [PATCH] feat: arquitectura RAG embebida y asistente UdeCi con botones interactivos (SDD-010, v3.8.25) --- CHANGELOG.md | 25 ++ MEMORY.md | 19 +- backend/app/__init__.py | 2 +- backend/app/models/__init__.py | 4 +- backend/app/models/knowledge_chunk.py | 31 +++ backend/app/services/rag_service.py | 285 ++++++++++++++++++++ backend/routers/ai_chat.py | 185 +++++++------ backend/schemas/ai_chat.py | 7 + backend/setup.py | 2 +- backend/tests/test_ai_chat.py | 32 +-- backend/tests/test_rag_udeci.py | 145 ++++++++++ frontend/package.json | 2 +- frontend/public/js/ai-chat-widget.js | 244 ++++++++++------- frontend/src/app.js | 6 +- frontend/views/partials/ai_chat_widget.html | 196 +++++++++----- specs/010-arquitectura-rag-udeci/plan.md | 61 +++++ specs/010-arquitectura-rag-udeci/spec.md | 58 ++++ specs/010-arquitectura-rag-udeci/tasks.md | 59 ++++ 18 files changed, 1088 insertions(+), 275 deletions(-) create mode 100644 backend/app/models/knowledge_chunk.py create mode 100644 backend/app/services/rag_service.py create mode 100644 backend/tests/test_rag_udeci.py create mode 100644 specs/010-arquitectura-rag-udeci/plan.md create mode 100644 specs/010-arquitectura-rag-udeci/spec.md create mode 100644 specs/010-arquitectura-rag-udeci/tasks.md diff --git a/CHANGELOG.md b/CHANGELOG.md index e62393b..032f901 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,31 @@ El formato está basado en [Keep a Changelog](https://keepachangelog.com/es-ES/1 - **Sincronización Continua Moodle (Fase 6):** Automatización de workers persistentes en background para el procesamiento continuo de la cola de Web Services Moodle 4.1. - **Pruebas de Carga y Hardening (Fase 6):** Pruebas de estrés de concurrencia y validación final de producción. +## [3.8.25] - 2026-10-27 +### Added & Enhanced (Arquitectura RAG Embebida y Asistente UdeCi - SDD-010) +- **Asistente Virtual UdeCi con Arquitectura RAG Embebida**: + - **Especificación SDD-010**: Formalizados artefactos en `specs/010-arquitectura-rag-udeci/` (`spec.md`, `plan.md`, `tasks.md`) con sintaxis EARS y matriz de conocimiento por rol. + - **Identidad Humanizada y Concisa**: + - Rebranding oficial a **UdeCi** (Tutor Virtual Institucional de Admin Edu Space - UniCABA). + - Eliminadas todas las menciones a tecnologías de backend (Llama.cpp, Qwen3, KV Cache) en la interfaz gráfica del usuario final. + - Respuestas breves y precisas (máximo 2 a 3 oraciones o pasos directos) sin rodeos innecesarios. + - **Módulo de Recuperación y Aumentación Semántica (RAG Embebido)**: + - Nuevo modelo relacional `KnowledgeChunk` (`backend/app/models/knowledge_chunk.py`) con título, contenido, rol, palabras clave y categorías. + - `RAGService` (`backend/app/services/rag_service.py`): Ingesta y normalización de fragmentos oficiales para Bedelía (9 pasos, conflictos, optimizador, sheets, Moodle), Docentes (aulas, Gradebook, Meet) y Alumnos (cartelera, materias, notas). + - Búsqueda semántica ponderada por coincidencias de título, contenido y palabras clave con **aislamiento estricto por rol** (`WHERE role IN (:user_role, 'general')`). + - Parámetro de temperatura en `0.1` para forzar apego estricto al contexto recuperado y evitar alucinaciones. + - Nuevo endpoint administrativo `POST /api/chat/rag/reindex` para recarga de la base de conocimiento oficial. + - **Rediseño UX/UI del Chat con Botones y Chips Interactivos**: + - `frontend/views/partials/ai_chat_widget.html`: Cabecera simplificada con avatar amigable, estado "En línea" y barra superior de chips de acción rápida adaptados al perfil del usuario. + - `frontend/public/js/ai-chat-widget.js`: + * Detección y renderizado automático de botones interactivos dentro de las burbujas de respuesta (`OPCIONES: [Opción 1 | Opción 2]`). + * Envío instantáneo al hacer clic en cualquier botón de opción sin necesidad de tipeo manual. + * Mensaje de bienvenida contextual según rol (`docente`, `alumno`, `bedelia`/`admin`). + - **Calidad y Verificación Automatizada**: + - Creada suite `backend/tests/test_rag_udeci.py` con 5 pruebas exhaustivas de RAG, filtrado estricto de roles y opciones interactivas. + - Suite completa de 94 pruebas pasando con éxito (`94 passed`). + - 0 errores de tipado o compilación estática. + ## [3.8.24] - 2026-10-27 ### Added & Integrated (Asistente IA Contextual - SDD-009) - **Integración de Asistente IA con Llama.cpp Local (Qwen3 Coder 30B)**: diff --git a/MEMORY.md b/MEMORY.md index 50ec72c..8c6e44a 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -9,18 +9,13 @@ Memoria del proyecto entre sesiones para la rama `dev`. - Libro de Calificaciones (*Gradebook*) con actas de regularidad inmutables. - Autenticación híbrida (Google OAuth 2.0, Moodle SSO, Local) y Modo Impersonación. - Reinicialización segura del sistema con contraseña de Administrador. -- **Sprint Activo: Integración de Asistente IA (Chatbot Contextual) — SDD-009 (v3.8.24)**: - - **Especificación y Metodología SDD**: Formalizada en `specs/009-asistente-ia-chatbot/` (`spec.md`, `plan.md`, `tasks.md`) con requisitos en sintaxis EARS y matriz de restricciones de rol. - - **Backend Core FastAPI & Llama.cpp Local (`10.0.0.214:8080/v1`)**: - - `backend/schemas/ai_chat.py`: Contratos Pydantic v2 declarativos (`ChatMessage`, `ChatRequest`, `ChatResponse`, `AISettingsSchema`). - - `backend/routers/ai_chat.py`: Router FastAPI con inyección dinámica de System Prompt por rol (Docente, Alumno, Bedelía/Admin), llamada asíncrona no bloqueante con `httpx.AsyncClient` y timeouts generosos (60s-600s), endpoints `/api/chat` y `/api/v1/chat`. - - `backend/routers/admin.py`: Pestaña y endpoints de configuración (`/settings/ai`, `/settings/ai/test`) y enmascaramiento seguro de secretos en `SystemSetting`. - - **Frontend BFF & Widget Flotante**: - - Pestaña "Asistente IA & LLM Local" (`#tab-ai`) en `/admin/settings` con prueba de latencia en vivo contra Llama.cpp. - - Widget flotante interactivo (`partials/ai_chat_widget.html` y `public/js/ai-chat-widget.js`) inyectado en `base.html` con persistencia en `sessionStorage`, detección de roles y renderizado de Markdown. - - Proxy transparente `/api/chat` y `/api/v1/chat` en `frontend/src/app.js`. - - **QA & Pruebas Automatizadas**: 89 tests aprobados al 100% en `pytest` (`89 passed`), 0 errores de tipado o compilación estática. - - **Versión Consolidada**: `v3.8.24`. +- **Sprint Activo: Arquitectura RAG Embebida y Asistente UdeCi — SDD-010 (v3.8.25)**: + - **Especificación y Metodología SDD**: Formalizada en `specs/010-arquitectura-rag-udeci/` (`spec.md`, `plan.md`, `tasks.md`) con requisitos en sintaxis EARS y matriz de conocimiento por rol. + - **Identidad y UX/UI UdeCi**: Rebranding a UdeCi, eliminación de jerga técnica en chat (Llama.cpp, Qwen3, KV Cache), respuestas concisas (2-3 oraciones) y botones interactivos en burbujas (`OPCIONES: [...]`) y barra de chips superior. + - **Motor RAG Embebido en SQLite**: Modelo relacional `KnowledgeChunk`, `RAGService` con tokenización, normalización de acentos, búsqueda ponderada en título/contenido/keywords y filtrado estricto por rol (`WHERE role IN (:user_role, 'general')`). + - **Endpoints y Seguridad**: Integración en `routers/ai_chat.py` con temperatura 0.1 y nuevo endpoint `POST /api/chat/rag/reindex`. + - **QA & Pruebas Automatizadas**: 94 tests aprobados al 100% en `pytest` (`94 passed`), 0 errores de tipado o compilación estática. + - **Versión Consolidada**: `v3.8.25`. ## Decisiones (y por qué) - **Flujo Secuencial de Bedelía (9 Pasos)**: Estandarizar la carga operativa en: 1) Sede -> 2) Aula -> 3) Ciclo Lectivo -> 4) Carrera -> 5) Materia (vinculada a Carrera) -> 6) Comisión (asociada a Materia, Carrera y Ciclo) -> 7) Profesores -> 8) Alumnos -> 9) Reserva de Espacio. Esto asegura consistencia e integridad relacional. diff --git a/backend/app/__init__.py b/backend/app/__init__.py index e59c7f1..4d63b67 100644 --- a/backend/app/__init__.py +++ b/backend/app/__init__.py @@ -7,7 +7,7 @@ from typing import Any from database import db, get_db, engine, SessionLocal, session from config.config import Config -__version__ = "3.8.24" +__version__ = "3.8.25" class DummyContext: def __enter__(self): diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.py index d64c80c..ddc06de 100644 --- a/backend/app/models/__init__.py +++ b/backend/app/models/__init__.py @@ -13,6 +13,7 @@ from .enrollment import StudentEnrollment from .setting import SystemSetting from .grade import MilestoneGrade from .sync_task import MoodleSyncTask +from .knowledge_chunk import KnowledgeChunk __all__ = [ 'User', @@ -38,5 +39,6 @@ __all__ = [ 'StudentEnrollment', 'SystemSetting', 'MilestoneGrade', - 'MoodleSyncTask' + 'MoodleSyncTask', + 'KnowledgeChunk' ] \ No newline at end of file diff --git a/backend/app/models/knowledge_chunk.py b/backend/app/models/knowledge_chunk.py new file mode 100644 index 0000000..fcd4a5e --- /dev/null +++ b/backend/app/models/knowledge_chunk.py @@ -0,0 +1,31 @@ +from datetime import datetime, timezone +from app import db + + +class KnowledgeChunk(db.Model): + """ + Fragmentos de documentación oficial indexados para la arquitectura RAG de UdeCi. + Permite recuperación semántica eficiente y filtrado estricto por rol. + """ + __tablename__ = 'knowledge_chunks' + + id = db.Column(db.Integer, primary_key=True) + title = db.Column(db.String(150), nullable=False) + content = db.Column(db.Text, nullable=False) + role = db.Column(db.String(50), nullable=False, default='general', index=True) + keywords = db.Column(db.String(255), nullable=True, index=True) + category = db.Column(db.String(50), nullable=True, default='manual') + created_at = db.Column(db.DateTime, default=lambda: datetime.now(timezone.utc).replace(tzinfo=None)) + + def __init__(self, **kwargs): + super().__init__(**kwargs) + + def to_dict(self): + return { + 'id': self.id, + 'title': self.title, + 'content': self.content, + 'role': self.role, + 'keywords': self.keywords, + 'category': self.category + } diff --git a/backend/app/services/rag_service.py b/backend/app/services/rag_service.py new file mode 100644 index 0000000..4e8e0bf --- /dev/null +++ b/backend/app/services/rag_service.py @@ -0,0 +1,285 @@ +""" +Servicio RAG Embebido (Retrieval-Augmented Generation) para UdeCi +Almacenamiento y recuperación semántica en base de datos relacional SQLite/PostgreSQL +con aislamiento estricto por rol de usuario. +""" +import re +import unicodedata +from typing import List, Dict, Any, Optional +from app import db +from app.models.knowledge_chunk import KnowledgeChunk + +STOP_WORDS = { + "de", "la", "el", "los", "las", "un", "una", "unos", "unas", "en", "para", "por", + "con", "sobre", "entre", "hacia", "hasta", "desde", "que", "como", "cual", "quien", + "y", "o", "a", "al", "del", "es", "son", "mi", "mis", "tu", "tus", "su", "sus" +} + + +def _normalize_text(text: str) -> str: + """Normaliza texto eliminando acentos, puntuación y convirtiendo a minúsculas.""" + if not text: + return "" + text = unicodedata.normalize('NFKD', text).encode('ASCII', 'ignore').decode('utf-8') + return re.sub(r'[^a-zA-Z0-9\s]', ' ', text.lower()).strip() + + +def _tokenize(text: str) -> List[str]: + """Extrae palabras clave significativas eliminando stop words.""" + norm = _normalize_text(text) + tokens = [t for t in norm.split() if len(t) > 2 and t not in STOP_WORDS] + return tokens + + +OFFICIAL_KNOWLEDGE_BASE = [ + # ------------------------------------------------------------- + # MANUAL OPERATIVO PARA BEDELÍA Y ADMINISTRADORES + # ------------------------------------------------------------- + { + "title": "Circuito Secuencial Canónico de 9 Pasos", + "role": "bedelia", + "keywords": "circuito pasos bedelia carga sedes aulas ciclos carreras materias comisiones profesores alumnos reservas", + "category": "bedelia_manual", + "content": ( + "El flujo operativo oficial de Bedelía en Admin Edu Space consta de 9 pasos secuenciales:\n" + "1. Sedes/Edificios: Dar de alta el campus y sedes institucionales.\n" + "2. Aulas: Crear aulas físicas con piso y aforo, o salas virtuales (Campus Virtual / Meet).\n" + "3. Ciclos Lectivos: Definir el cuatrimestre y vigencia (ej. 2° Cuatrimestre 2026).\n" + "4. Carreras: Crear las carreras oficiales de UniCABA.\n" + "5. Asignaturas: Cargar materias asociadas a una o múltiples carreras (Many-to-Many).\n" + "6. Comisiones: Crear comisiones asignando materia, carrera, ciclo y turno.\n" + "7. Profesores: Asignar los docentes responsables de cada comisión.\n" + "8. Alumnos: Matricular estudiantes en las comisiones correspondientes.\n" + "9. Reservas de Espacio: Asignar aula presencial o enlace virtual para la cursada." + ) + }, + { + "title": "Matriz de Conflictos y Validación de Aulas", + "role": "bedelia", + "keywords": "conflictos superposicion solapamiento aula aforo docente codocencia restriccion diaria", + "category": "bedelia_rules", + "content": ( + "La plataforma aplica una matriz de validación en tiempo real para impedir reservas inválidas:\n" + "- Conflicto Físico: Dos comisiones no pueden ocupar la misma aula presencial en la misma fecha y franja horaria. En aulas virtuales no aplica colisión.\n" + "- Control de Aforo: La cantidad de inscriptos no puede superar la capacidad máxima del aula física.\n" + "- Conflicto Docente: Un profesor no puede dictar dos clases simultáneas, salvo que la comisión tenga co-docencia activa registrada.\n" + "- Restricción Diaria del Alumno: Un estudiante no puede cursar dos materias regulares el mismo día, salvo cursos cortos o autorización expresa de Bedelía." + ) + }, + { + "title": "Optimizador Genético de Aulas con Inteligencia Artificial", + "role": "bedelia", + "keywords": "optimizador genetico aulas algoritmo colisiones capacidad asignacion masiva", + "category": "bedelia_tools", + "content": ( + "El Optimizador Genético de Aulas (disponible en /genetic_optimizer) asigna de forma automatizada aulas físicas a comisiones activas:\n" + "- Resuelve superposiciones horarias y minimiza el aforo ocioso adaptando la capacidad del aula al cupo de la materia.\n" + "- Permite ejecutar la optimización, previsualizar las asignaciones propuestas con desglose de fitness, y aplicar los cambios masivamente en base de datos con un solo clic con registro en Auditoría." + ) + }, + { + "title": "Importador Masivo de Google Sheets", + "role": "bedelia", + "keywords": "importador google sheets sincronizacion masiva cartelera excel preview granular", + "category": "bedelia_tools", + "content": ( + "La herramienta de sincronización (/admin/google_sheets_import) permite ingerir planillas online de UniCABA:\n" + "- Inspección Previa: El botón 'Inspeccionar Sheet Online' muestra una grilla interactiva sin guardar datos directamente.\n" + "- Selección Granular: Permite tildar qué entidades importar (reservas, aulas, comisiones, materias, carreras) y filtrar por día de la semana o carrera.\n" + "- Modificación Manual de Fecha: Permite corregir o forzar una fecha específica para una fila o grupo de comisiones antes de confirmar la sincronización." + ) + }, + { + "title": "Integración y Sincronización con Moodle 4.1", + "role": "bedelia", + "keywords": "moodle sincronizacion cola sync tareas dlq reintentos web services api", + "category": "bedelia_tools", + "content": ( + "Admin Edu Space se conecta con Moodle 4.1 vía REST Web Services mediante una cola asíncrona resiliente (MoodleSyncTask):\n" + "- Las altas y matriculaciones no bloquean al usuario; se encolan y procesan en background con reintentos exponenciales y Dead Letter Queue (DLQ).\n" + "- Los administradores pueden monitorear tareas pendientes y estadísticas en la pestaña Moodle de Configuración Global (/admin/settings)." + ) + }, + + # ------------------------------------------------------------- + # MANUAL OPERATIVO PARA DOCENTES Y PROFESORES + # ------------------------------------------------------------- + { + "title": "Consulta de Aulas Asignadas y Aulas Virtuales para Docentes", + "role": "docente", + "keywords": "docente aulas clases cartelera horario google meet salas virtuales", + "category": "docente_manual", + "content": ( + "Como docente en Admin Edu Space puedes consultar tus espacios áulicos:\n" + "- En el Dashboard Docente (/dashboard) y en la Cartelera de Clases (/schedule/today_schedule) puedes ver tus materias asignadas para hoy y la semana.\n" + "- Se indica el aula presencial asignada con piso y sede, o el botón directo a la sala virtual de Google Meet / Teams si la modalidad es remota.\n" + "- Si requieres un cambio de aula física, debes solicitarlo al personal de Bedelía." + ) + }, + { + "title": "Libro de Calificaciones (Gradebook) y Actas de Regularidad", + "role": "docente", + "keywords": "calificaciones notas parciales recuperatorio gradebook actas regularidad inmutable", + "category": "docente_manual", + "content": ( + "El sistema cuenta con un Libro de Calificaciones digital para cada comisión:\n" + "- El docente puede registrar notas de primer parcial, segundo parcial, recuperatorios y calificar como ausente.\n" + "- El sistema calcula automáticamente la condición académica del alumno (Regular, Promocionado, Libre).\n" + "- Al finalizar el cuatrimestre, el docente puede realizar el Cierre de Acta de Regularidad, quedando registrada de forma inmutable con trazabilidad en auditoría." + ) + }, + { + "title": "Nómina de Alumnos y Comisiones Activas", + "role": "docente", + "keywords": "nomina alumnos estudiantes comisiones lista asistencia cursada", + "category": "docente_manual", + "content": ( + "Los profesores pueden consultar la nómina completa de estudiantes inscriptos en sus asignaturas desde el panel de comisiones:\n" + "- Se visualiza el DNI, nombre, correo institucional y estado de matrícula de cada alumno.\n" + "- No está permitido a los docentes crear carreras, borrar aulas ni alterar parámetros de configuración del sistema; estas acciones están reservadas a Bedelía." + ) + }, + + # ------------------------------------------------------------- + # MANUAL PARA ALUMNOS Y ESTUDIANTES + # ------------------------------------------------------------- + { + "title": "Consulta de Aula y Horarios de Cursada para Alumnos", + "role": "alumno", + "keywords": "alumno aula donde curso hoy horario materias clases cartelera", + "category": "alumno_manual", + "content": ( + "Para saber en qué aula cursas tus materias:\n" + "- Ingresa al Dashboard de Estudiante (/dashboard) o a la Cartelera de Clases (/schedule/today_schedule).\n" + "- Verás la tarjeta de tu clase del día con el nombre de la materia, comisión, horario de inicio y finalización, y el número de aula física asignada.\n" + "- Si la clase es virtual, encontrarás un botón directo para unirte a la videollamada de Google Meet." + ) + }, + { + "title": "Mis Materias Matriculadas y Horarios Semanales", + "role": "alumno", + "keywords": "materias inscripcion matriculadas horario semanal cursada comisiones", + "category": "alumno_manual", + "content": ( + "En la sección 'Mis Materias' (/my_subjects) puedes verificar:\n" + "- La lista de asignaturas en las que te encuentras matriculado en el ciclo lectivo actual.\n" + "- El equipo docente a cargo de cada comisión y los días de cursada asignados.\n" + "- Recuerda que el sistema impide matricularse en dos materias regulares el mismo día para evitar superposiciones de estudio." + ) + }, + { + "title": "Consulta de Calificaciones y Estado Académico", + "role": "alumno", + "keywords": "notas calificaciones parciales regularidad actas estado academico", + "category": "alumno_manual", + "content": ( + "Puedes verificar tu progreso académico ingresando al Libro de Calificaciones de tus materias:\n" + "- Consulta tus notas de parciales y recuperatorios una vez publicadas por el profesor.\n" + "- Verifica tu condición académica final (Regular, Promocionado o Libre).\n" + "- Ante cualquier discrepancia en tus notas o dudas sobre regularidad, consulta directamente a tu profesor o al departamento de Bedelía." + ) + }, + + # ------------------------------------------------------------- + # INFORMACIÓN GENERAL INSTITUCIONAL + # ------------------------------------------------------------- + { + "title": "Acceso a la Plataforma y Soporte Institucional", + "role": "general", + "keywords": "login acceso cuenta google sso unicaba soporte contraseña", + "category": "general", + "content": ( + "Admin Edu Space es la plataforma oficial de gestión de espacios áulicos y cursada de UniCABA:\n" + "- Se puede ingresar mediante correo institucional Google Workspace (@unicaba.edu.ar), login delegado de Moodle con DNI, o cuenta local.\n" + "- Si tienes problemas de acceso, contacta a Soporte IT o al departamento de Bedelía de UniCABA." + ) + } +] + + +class RAGService: + """Servicio de indexación y recuperación semántica de fragmentos RAG.""" + + @classmethod + def reindex_default_knowledge(cls) -> int: + """Puebla o reinicializa la tabla knowledge_chunks con la documentación oficial.""" + try: + KnowledgeChunk.query.delete() + db.session.commit() + except Exception: + db.session.rollback() + + count = 0 + for doc in OFFICIAL_KNOWLEDGE_BASE: + chunk = KnowledgeChunk( + title=doc["title"], + content=doc["content"], + role=doc["role"], + keywords=doc["keywords"], + category=doc.get("category", "manual") + ) + db.session.add(chunk) + count += 1 + + db.session.commit() + return count + + @classmethod + def search_relevant_chunks(cls, query: str, user_role: str, limit: int = 3) -> List[Dict[str, Any]]: + """ + Ejecuta una búsqueda semántica de fragmentos relevantes, + aplicando un filtro estricto por el rol del usuario para evitar fugas de información. + """ + # Asegurar que existan chunks en base de datos + total_chunks = KnowledgeChunk.query.count() + if total_chunks == 0: + cls.reindex_default_knowledge() + + normalized_role = (user_role or "alumno").strip().lower() + if "docente" in normalized_role or "profesor" in normalized_role or "teacher" in normalized_role: + effective_role = "docente" + elif "bedelia" in normalized_role or "admin" in normalized_role: + effective_role = "bedelia" + else: + effective_role = "alumno" + + # Filtrar exclusivamente por rol permitido y documentos generales + allowed_roles = [effective_role, "general"] + candidates = KnowledgeChunk.query.filter(KnowledgeChunk.role.in_(allowed_roles)).all() + + query_tokens = _tokenize(query) + if not query_tokens: + # Si la consulta no tiene tokens específicos, retornar los fragmentos introductorios del rol + return [c.to_dict() for c in candidates[:limit]] + + scored = [] + for chunk in candidates: + score = 0.0 + norm_title = _normalize_text(chunk.title) + norm_content = _normalize_text(chunk.content) + norm_keywords = _normalize_text(chunk.keywords or "") + + for token in query_tokens: + # Coincidencia en título (+5 puntos) + if token in norm_title: + score += 5.0 + # Coincidencia en keywords (+3 puntos) + if token in norm_keywords: + score += 3.0 + # Coincidencia en contenido (+1 punto) + if token in norm_content: + score += 1.0 + + if score > 0: + scored.append((score, chunk)) + + # Ordenar de mayor a menor relevancia + scored.sort(key=lambda x: x[0], reverse=True) + + if scored: + results = [item[1].to_dict() for item in scored[:limit]] + else: + # Fallback a fragmentos generales del rol + results = [c.to_dict() for c in candidates[:limit]] + + return results diff --git a/backend/routers/ai_chat.py b/backend/routers/ai_chat.py index bfe6e51..833a04a 100644 --- a/backend/routers/ai_chat.py +++ b/backend/routers/ai_chat.py @@ -1,73 +1,61 @@ """ -Módulo de Integración de Asistente IA (Chatbot de Ayuda Contextual) -SDD-009: Compatible con OpenAI API y Servidor Local Llama.cpp (Qwen3 Coder 30B) +Módulo de Integración de Asistente IA (UdeCi) con Arquitectura RAG Embebida +SDD-009 / SDD-010: Compatible con OpenAI API y Servidor Local Llama.cpp (Qwen3 Coder 30B) """ +import re import time -from typing import Optional +from typing import Optional, List import httpx from fastapi import APIRouter, HTTPException, Depends, Request, status from dependencies import get_optional_current_user, require_roles from app.models.setting import SystemSetting from app.models.user import User +from app.services.rag_service import RAGService from schemas.ai_chat import ( ChatRequest, ChatResponse, AITestConnectionResponse, - AISettingsSchema + AISettingsSchema, + RAGReindexResponse ) router = APIRouter(tags=["AI Chatbot"]) +DEFAULT_ROLE_OPTIONS = { + "docente": ["📍 Aulas y Google Meet", "📝 Actas de Regularidad", "👥 Ver Comisiones", "❓ Ayuda"], + "bedelia": ["🔄 Flujo de 9 Pasos", "⚠️ Conflictos Áulicos", "🧬 Optimizador IA", "📑 Importar Sheets"], + "alumno": ["📍 ¿Dónde curso hoy?", "📚 Mis Materias", "📊 Mis Calificaciones", "❓ Ayuda"] +} -def generate_system_prompt_for_role(role: Optional[str]) -> str: + +def generate_system_prompt_for_role(role: Optional[str], rag_context: Optional[str] = None) -> str: """ - Genera el System Prompt dinámico según el rol del usuario autenticado, - proporcionándole al LLM las reglas de negocio, manual de uso y restricciones de acceso. + Genera el System Prompt de UdeCi enriquecido con fragmentos de conocimiento oficial (RAG), + imponiendo respuestas cortas, directas y opciones interactivas para el usuario. """ normalized_role = (role or "alumno").strip().lower() - - if normalized_role in ["docente", "profesor", "teacher"]: - return ( - "Eres el Asistente y Tutor Inteligente de Admin Edu Space (UniCABA) para DOCENTES y PROFESORES.\n" - "Tu objetivo es asistir al cuerpo docente guiándolo exclusivamente en las tareas pertinentes a su rol:\n" - "1. Asignaciones de Aula y Espacios: Explicar cómo consultar las aulas físicas asignadas y enlaces a aulas virtuales (Google Meet/Teams) en la cartelera diaria y semanal.\n" - "2. Libro de Calificaciones (Gradebook): Orientar sobre cómo cargar y editar calificaciones de parciales, recuperatorios, notas finales y cerrar actas de regularidad inmutables con trazabilidad.\n" - "3. Nómina de Comisiones y Alumnos: Guiar en la visualización de listas de alumnos inscriptos en sus comisiones activas.\n" - "4. Cronogramas y Horarios: Indicar cómo consultar días y horarios de cursada según el ciclo lectivo vigente.\n" - "REGLAS ESTRICTAS DE SEGURIDAD Y PERMISOS:\n" - "- Si el usuario te consulta sobre cómo crear carreras, modificar asignaciones físicas ajenas, reconfigurar servidores o ingresar a funciones de Bedelía, aclara respetuosamente que esas operaciones están reservadas a Bedelía o Administración de Sistemas.\n" - "- Responde siempre en español institucional, con tono cordial, empático y estructurado en pasos claros." - ) - - elif normalized_role in ["bedelia", "admin", "administrador"]: - return ( - "Eres el Asistente y Tutor Técnico de Nivel 1 de Admin Edu Space (UniCABA) para personal de BEDELÍA y ADMINISTRADORES.\n" - "Tu objetivo es brindar soporte técnico operativo y guiar en el flujo integral de gestión académica y áulica:\n" - "1. Circuito Secuencial Canónico de 9 Pasos: 1) Sedes/Edificios -> 2) Aulas (físicas/virtuales) -> 3) Ciclos Lectivos -> 4) Carreras -> 5) Asignaturas (con carreras asociadas) -> 6) Comisiones -> 7) Profesores -> 8) Alumnos -> 9) Reservas de Espacio.\n" - "2. Matriz de Conflictos: Explicar la validación física en aulas presenciales, control estricto de aforo, superposición horaria docente (con excepción de co-docencia activa) y restricción diaria de cursada para alumnos.\n" - "3. Herramienta de Optimización con IA: Instruir sobre el uso del Optimizador Genético de Aulas para resolver colisiones y maximizar aforo.\n" - "4. Importación Masiva (Google Sheets): Explicar el proceso de inspección previa, selección granular de entidades, filtrado por carrera/día y carga con fechas manuales.\n" - "5. Sincronización Moodle 4.1: Orientar en la gestión de la cola asíncrona (MoodleSyncTask), manejo de reintentos, Dead Letter Queue (DLQ) y sincronización RBAC.\n" - "6. Auditoría Institucional: Indicar cómo auditar eventos en AuditLog por módulo, acción y fecha.\n" - "REGLAS:\n" - "- Responde con precisión técnica, terminología oficial de UniCABA y soluciones directas y accionables." - ) - + if "docente" in normalized_role or "profesor" in normalized_role or "teacher" in normalized_role: + effective_role = "docente" + elif "bedelia" in normalized_role or "admin" in normalized_role: + effective_role = "bedelia" else: - # Rol Alumno / Estudiante (por defecto) - return ( - "Eres el Asistente y Tutor Inteligente de Admin Edu Space (UniCABA) para ESTUDIANTES y ALUMNOS.\n" - "Tu misión es guiar al estudiante sobre cómo cursar y utilizar el sistema:\n" - "1. Cartelera de Clases de Hoy: Enseñar cómo consultar en qué aula física o enlace virtual de Meet le corresponde cursar sus materias hoy y en qué turno.\n" - "2. Mis Asignaturas e Inscripciones: Explicar cómo verificar las materias matriculadas, comisiones, docentes a cargo y horarios de cursada.\n" - "3. Consulta de Calificaciones: Guiar en la visualización de estados académicos, notas parciales, recuperatorios y regularidad en el sistema.\n" - "4. Restricción de Cursada Diaria: Explicar que el sistema restringe cursar dos materias el mismo día salvo cursos cortos o excepciones autorizadas por Bedelía.\n" - "REGLAS ESTRICTAS DE SEGURIDAD:\n" - "- Tienes TERMINANTEMENTE PROHIBIDO enseñar o detallar cómo reservar aulas, cómo alterar notas, cómo sincronizar Moodle o cómo administrar el sistema.\n" - "- Ante cualquier solicitud de índole administrativa o de reclamo de cupos, indica al alumno que debe dirigirse a la Secretaría de Bedelía de UniCABA.\n" - "- Responde en español de forma pedagógica, clara y amigable." - ) + effective_role = "alumno" + + context_section = rag_context if rag_context else "Consulta el sistema con tu usuario institucional." + + return ( + f"Eres UdeCi, el tutor virtual institucional de Admin Edu Space (UniCABA).\n" + f"El usuario tiene el rol de: {effective_role.upper()}.\n\n" + "REGLAS ESTRICTAS DE RESPUESTA:\n" + "1. Respuestas BREVES y PRECISAS: Responde en máximo 2 a 3 oraciones cortas o pasos directos. No des introducciones largas ni rodeos.\n" + "2. INFORMACIÓN OFICIAL: Responde basándote ÚNICAMENTE en la INFORMACIÓN DEL SISTEMA provista abajo. " + "Si la respuesta no está en esta información o el usuario solicita una acción que no corresponde a su rol, " + "indícale amablemente que no dispones de los permisos necesarios y que debe contactar a Bedelía.\n" + "3. Al final de tu mensaje, incluye EXACTAMENTE 2 o 3 opciones breves de seguimiento en este formato:\n" + "OPCIONES: [Opción 1 | Opción 2 | Opción 3]\n\n" + f"INFORMACIÓN OFICIAL DEL SISTEMA (RAG):\n{context_section}" + ) def _get_ai_config() -> dict: @@ -76,16 +64,15 @@ def _get_ai_config() -> dict: enabled = enabled_val in ["true", "True", "1", True] base_url = SystemSetting.get_value("ai_chat_base_url", "http://10.0.0.214:8080/v1") or "http://10.0.0.214:8080/v1" - - # Obtener clave API descifrada api_key = SystemSetting.get_decrypted_value("ai_chat_api_key", "llama") or "llama" model = SystemSetting.get_value("ai_chat_model", "qwen3-coder:30b") or "qwen3-coder:30b" - model_name = SystemSetting.get_value("ai_chat_model_name", "Qwen3 Coder 30B-A3B (Llama.cpp)") or "Qwen3 Coder 30B-A3B (Llama.cpp)" + model_name = SystemSetting.get_value("ai_chat_model_name", "UdeCi (Tutor Virtual)") or "UdeCi (Tutor Virtual)" try: - temperature = float(SystemSetting.get_value("ai_chat_temperature", 0.3)) + # En RAG se recomienda 0.1 para máxima fidelidad a los fragmentos + temperature = float(SystemSetting.get_value("ai_chat_temperature", 0.1)) except (ValueError, TypeError): - temperature = 0.3 + temperature = 0.1 try: timeout = float(SystemSetting.get_value("ai_chat_timeout", 60.0)) @@ -103,6 +90,23 @@ def _get_ai_config() -> dict: } +def _extract_options_from_reply(reply_text: str, role: str) -> tuple[str, List[str]]: + """Extrae las opciones sugeridas al final del texto y limpia la respuesta para el usuario.""" + options = [] + clean_text = reply_text + + match = re.search(r'OPCIONES:\s*\[(.*?)\]', reply_text, re.DOTALL | re.IGNORECASE) + if match: + raw_options = match.group(1).split('|') + options = [opt.strip() for opt in raw_options if opt.strip()] + clean_text = reply_text[:match.start()].strip() + + if not options: + options = DEFAULT_ROLE_OPTIONS.get(role, DEFAULT_ROLE_OPTIONS["alumno"]) + + return clean_text, options + + @router.post("/", response_model=ChatResponse) @router.post("", response_model=ChatResponse) async def get_agent_response( @@ -111,17 +115,18 @@ async def get_agent_response( current_user: Optional[User] = Depends(get_optional_current_user) ): """ - Procesa la conversación del usuario con el agente contextual: - 1. Resuelve el rol del usuario (prioriza sesión JWT o campo user_role). - 2. Inyecta el System Prompt correspondiente al rol. - 3. Envía la solicitud asíncrona no bloqueante hacia el servidor local Llama.cpp. + Procesa la conversación con UdeCi aplicando la arquitectura RAG: + 1. Resuelve el rol del usuario autenticado. + 2. Ejecuta búsqueda semántica en KnowledgeChunk (RAG) filtrando por rol. + 3. Inyecta el contexto oficial en el prompt para Llama.cpp con baja temperatura (0.1). + 4. Genera respuesta breve y extrae opciones de botones interactivos. """ config = _get_ai_config() if not config["enabled"]: raise HTTPException( status_code=status.HTTP_503_SERVICE_UNAVAILABLE, - detail="El servicio de Asistente IA está temporalmente deshabilitado por el administrador." + detail="UdeCi está temporalmente deshabilitado por el administrador." ) # 1. Determinar rol efectivo @@ -138,8 +143,18 @@ async def get_agent_response( else: effective_role = "alumno" - # 2. Inyección de Contexto - system_prompt = generate_system_prompt_for_role(effective_role) + # 2. Búsqueda semántica RAG sobre la última consulta del usuario + last_query = "" + for msg in reversed(request.messages): + if msg.role == "user": + last_query = msg.content + break + + chunks = RAGService.search_relevant_chunks(last_query, effective_role, limit=3) + context_text = "\n\n".join([f"### {c['title']}\n{c['content']}" for c in chunks]) + + # 3. Inyección de Contexto en el System Prompt + system_prompt = generate_system_prompt_for_role(effective_role, context_text) formatted_messages = [{"role": "system", "content": system_prompt}] for msg in request.messages: @@ -148,7 +163,7 @@ async def get_agent_response( payload = { "model": config["model"], "messages": formatted_messages, - "temperature": config["temperature"] + "temperature": 0.1 # Temperatura estricta para evitar alucinaciones } target_url = f"{config['base_url']}/chat/completions" @@ -157,18 +172,19 @@ async def get_agent_response( "Content-Type": "application/json" } - # 3. Petición asíncrona no bloqueante al servidor local + # 4. Inferencia asíncrona no bloqueante async with httpx.AsyncClient(timeout=config["timeout"]) as client: try: response = await client.post(target_url, headers=headers, json=payload) response.raise_for_status() ai_data = response.json() - reply_text = ai_data["choices"][0]["message"]["content"] - return ChatResponse(response=reply_text) + raw_reply = ai_data["choices"][0]["message"]["content"] + clean_reply, options = _extract_options_from_reply(raw_reply, effective_role) + return ChatResponse(response=clean_reply, quick_options=options) except httpx.TimeoutException: raise HTTPException( status_code=status.HTTP_504_GATEWAY_TIMEOUT, - detail=f"El servidor de IA local superó el tiempo límite de espera ({config['timeout']}s)." + detail=f"UdeCi superó el tiempo límite de espera ({config['timeout']}s)." ) except httpx.HTTPStatusError as e: detail_msg = f"Error del motor de IA local ({e.response.status_code}): {e.response.text[:200]}" @@ -176,18 +192,28 @@ async def get_agent_response( except httpx.RequestError as e: raise HTTPException( status_code=status.HTTP_503_SERVICE_UNAVAILABLE, - detail="Error conectando al motor de IA local. Verifique que Llama.cpp esté activo en 10.0.0.214." + detail="Error conectando con UdeCi. Verifique que el servidor local de IA esté disponible." ) +@router.post("/rag/reindex", response_model=RAGReindexResponse) +def reindex_knowledge_base( + current_user: User = Depends(require_roles(["ADMIN"])) +): + """Reindexa y particiona la documentación oficial en fragmentos RAG.""" + count = RAGService.reindex_default_knowledge() + return RAGReindexResponse( + status="success", + indexed_chunks=count, + message=f"Se han reindexado exitosamente {count} fragmentos de conocimiento oficial para UdeCi." + ) + + @router.post("/test-connection", response_model=AITestConnectionResponse) async def test_ai_connection( current_user: User = Depends(require_roles(["ADMIN"])) ): - """ - Verifica la conectividad directa con el servidor local Llama.cpp - consultando el endpoint de modelos /v1/models y calculando la latencia. - """ + """Verifica conectividad directa con el servidor local consultando /v1/models.""" config = _get_ai_config() target_url = f"{config['base_url']}/models" headers = {"Authorization": f"Bearer {config['api_key']}"} @@ -202,14 +228,14 @@ async def test_ai_connection( model_ids = [m.get("id") for m in data.get("data", []) if isinstance(m, dict) and "id" in m] return AITestConnectionResponse( status="success", - message=f"Conexión exitosa con Llama.cpp ({config['base_url']}). Latencia: {latency_ms} ms.", + message=f"Conexión exitosa con el servidor local ({config['base_url']}). Latencia: {latency_ms} ms.", latency_ms=latency_ms, models=model_ids ) else: return AITestConnectionResponse( status="warning", - message=f"Respuesta inesperada del servidor ({resp.status_code}): {resp.text[:200]}", + message=f"Respuesta inesperada ({resp.status_code}): {resp.text[:200]}", latency_ms=latency_ms, models=[] ) @@ -231,11 +257,20 @@ async def test_ai_connection( @router.get("/config") def get_ai_public_config(current_user: Optional[User] = Depends(get_optional_current_user)): - """Retorna metadatos públicos de estado del asistente para el widget del frontend.""" + """Retorna metadatos públicos de estado de UdeCi para el widget del frontend.""" config = _get_ai_config() + role_str = "alumno" + if current_user and hasattr(current_user, "role") and current_user.role: + r = str(current_user.role).lower() + if "docente" in r or "profesor" in r: + role_str = "docente" + elif "bedelia" in r or "admin" in r: + role_str = "bedelia" + return { "status": "success", "enabled": config["enabled"], - "model": config["model"], - "model_name": config["model_name"] + "name": "UdeCi", + "role": role_str, + "default_options": DEFAULT_ROLE_OPTIONS.get(role_str, DEFAULT_ROLE_OPTIONS["alumno"]) } diff --git a/backend/schemas/ai_chat.py b/backend/schemas/ai_chat.py index d77fb8a..ba4f978 100644 --- a/backend/schemas/ai_chat.py +++ b/backend/schemas/ai_chat.py @@ -14,6 +14,13 @@ class ChatRequest(BaseModel): class ChatResponse(BaseModel): response: str = Field(..., description="Respuesta generada por el agente conversacional") + quick_options: Optional[List[str]] = Field(default_factory=list, description="Lista de opciones o preguntas sugeridas para botones interactivos") + + +class RAGReindexResponse(BaseModel): + status: str + indexed_chunks: int + message: str class AISettingsSchema(BaseModel): diff --git a/backend/setup.py b/backend/setup.py index 680c039..3065bd7 100644 --- a/backend/setup.py +++ b/backend/setup.py @@ -2,7 +2,7 @@ from setuptools import setup, find_packages setup( name="edu-space-admin", - version="3.8.24", + version="3.8.25", description="Administrative interface for Edu-Space Classroom Management System (FastAPI ASGI Core)", author="Edu-Space Development Team", author_email="admin@edu-space.com", diff --git a/backend/tests/test_ai_chat.py b/backend/tests/test_ai_chat.py index 516e713..a11e823 100644 --- a/backend/tests/test_ai_chat.py +++ b/backend/tests/test_ai_chat.py @@ -51,26 +51,24 @@ def test_ai_chat_pydantic_schemas_validation(): def test_system_prompt_generation_by_role(): - """Verifica que el System Prompt inyectado se adapte rigurosamente al rol.""" + """Verifica que el System Prompt inyectado se adapte rigurosamente al rol y contenga UdeCi y RAG.""" # Docente prompt_docente = generate_system_prompt_for_role("docente") - assert "DOCENTES y PROFESORES" in prompt_docente - assert "Gradebook" in prompt_docente - assert "Google Meet" in prompt_docente - assert "Bedelía" in prompt_docente # Restricción de permisos + assert "UdeCi" in prompt_docente + assert "DOCENTE" in prompt_docente + assert "INFORMACIÓN OFICIAL DEL SISTEMA (RAG)" in prompt_docente # Alumno prompt_alumno = generate_system_prompt_for_role("alumno") - assert "ESTUDIANTES y ALUMNOS" in prompt_alumno - assert "Cartelera de Clases de Hoy" in prompt_alumno - assert "TERMINANTEMENTE PROHIBIDO" in prompt_alumno + assert "UdeCi" in prompt_alumno + assert "ALUMNO" in prompt_alumno + assert "INFORMACIÓN OFICIAL DEL SISTEMA (RAG)" in prompt_alumno # Bedelía / Admin prompt_bedelia = generate_system_prompt_for_role("bedelia") - assert "BEDELÍA y ADMINISTRADORES" in prompt_bedelia - assert "Circuito Secuencial Canónico de 9 Pasos" in prompt_bedelia - assert "Matriz de Conflictos" in prompt_bedelia - assert "Moodle 4.1" in prompt_bedelia + assert "UdeCi" in prompt_bedelia + assert "BEDELIA" in prompt_bedelia + assert "INFORMACIÓN OFICIAL DEL SISTEMA (RAG)" in prompt_bedelia def test_ai_chat_public_config_endpoint(): @@ -81,7 +79,9 @@ def test_ai_chat_public_config_endpoint(): data = response.json() assert data["status"] == "success" assert "enabled" in data - assert "model" in data + assert data["name"] == "UdeCi" + assert "role" in data + assert "default_options" in data def test_ai_chat_endpoint_success_mock(init_database): @@ -141,7 +141,7 @@ def test_ai_chat_endpoint_validation_error(): assert res2.status_code == 422 -def test_ai_chat_endpoint_connection_failure(): +def test_ai_chat_endpoint_connection_failure(init_database): """Simula error de conexión con el servidor Llama.cpp y verifica HTTP 503.""" client = TestClient(app) @@ -154,10 +154,10 @@ def test_ai_chat_endpoint_connection_failure(): assert res.status_code == 503 data = res.json() assert "detail" in data - assert "10.0.0.214" in data["detail"] or "motor de IA" in data["detail"] + assert "UdeCi" in data["detail"] or "servidor local de IA" in data["detail"] -def test_ai_chat_endpoint_timeout_failure(): +def test_ai_chat_endpoint_timeout_failure(init_database): """Simula tiempo de espera agotado y verifica HTTP 504.""" client = TestClient(app) diff --git a/backend/tests/test_rag_udeci.py b/backend/tests/test_rag_udeci.py new file mode 100644 index 0000000..6facf14 --- /dev/null +++ b/backend/tests/test_rag_udeci.py @@ -0,0 +1,145 @@ +""" +Suite de pruebas automatizadas para la arquitectura RAG y el asistente UdeCi (SDD-010). +Valida indexación de chunks, filtrado estricto por rol, relevancia semántica, +extracción de botones de opciones y endpoints administrativos. +""" +from unittest.mock import AsyncMock, patch, MagicMock +from fastapi.testclient import TestClient +from werkzeug.security import generate_password_hash + +from main import app +from app.models.knowledge_chunk import KnowledgeChunk +from app.models.user import User +from app.services.rag_service import RAGService + + +def test_rag_reindex_default_knowledge(init_database): + """Valida la ingesta y particionamiento de la base de conocimiento oficial.""" + count = RAGService.reindex_default_knowledge() + assert count >= 10 + + # Verificar que los fragmentos están en la base de datos + chunks = KnowledgeChunk.query.all() + assert len(chunks) == count + roles = {c.role for c in chunks} + assert "bedelia" in roles + assert "docente" in roles + assert "alumno" in roles + assert "general" in roles + + +def test_rag_strict_role_filtering(init_database): + """Valida que la recuperación semántica aísle estrictamente los permisos por rol.""" + RAGService.reindex_default_knowledge() + + # 1. Consulta de Alumno intentando averiguar sobre Bedelía + alumno_chunks = RAGService.search_relevant_chunks( + query="como configurar el servidor o crear carreras y comisiones de bedelia", + user_role="alumno", + limit=5 + ) + # Ningún fragmento para Alumno debe ser de rol 'bedelia' o 'docente' + for c in alumno_chunks: + assert c["role"] in ["alumno", "general"], f"Fuga de rol detectada: {c['role']}" + + # 2. Consulta de Docente + docente_chunks = RAGService.search_relevant_chunks( + query="donde veo las actas y aulas de mis materias", + user_role="docente", + limit=5 + ) + for c in docente_chunks: + assert c["role"] in ["docente", "general"], f"Fuga de rol detectada: {c['role']}" + + # 3. Consulta de Bedelía + bedelia_chunks = RAGService.search_relevant_chunks( + query="flujo de 9 pasos y matriz de conflictos", + user_role="bedelia", + limit=3 + ) + titles = [c["title"] for c in bedelia_chunks] + assert any("9 Pasos" in t for t in titles) + assert any("Conflictos" in t for t in titles) + + +def test_rag_semantic_relevance_ranking(init_database): + """Verifica que los términos clave ubiquen el fragmento más idóneo en primera posición.""" + RAGService.reindex_default_knowledge() + + # Búsqueda específica de aulas y Google Meet para Alumno + results = RAGService.search_relevant_chunks("aula donde curso hoy meet", user_role="alumno", limit=2) + assert len(results) > 0 + assert "Consulta de Aula y Horarios" in results[0]["title"] + + +def test_udeci_chat_endpoint_rag_with_quick_options(init_database): + """Verifica la respuesta de UdeCi incluyendo la extracción de botones de opciones.""" + client = TestClient(app) + + mock_response = MagicMock() + mock_response.status_code = 200 + mock_response.json.return_value = { + "choices": [ + { + "message": { + "role": "assistant", + "content": ( + "Cursas en el Aula 102 del Edificio Central a las 18:30 hs.\n" + "OPCIONES: [Ver Cartelera | Mis Materias | Ayuda]" + ) + } + } + ] + } + mock_response.raise_for_status = MagicMock() + + with patch("httpx.AsyncClient.post", new_callable=AsyncMock) as mock_post: + mock_post.return_value = mock_response + + res = client.post("/api/chat", json={ + "messages": [{"role": "user", "content": "¿Dónde curso hoy?"}], + "user_role": "alumno" + }) + assert res.status_code == 200 + data = res.json() + assert "response" in data + assert "Aula 102" in data["response"] + # Verificar que la etiqueta OPCIONES: fue removida del texto para mantenerlo limpio + assert "OPCIONES:" not in data["response"] + # Verificar que quick_options contiene los botones extraídos + assert "quick_options" in data + assert len(data["quick_options"]) == 3 + assert "Ver Cartelera" in data["quick_options"] + + +def test_rag_reindex_endpoint_admin_security(init_database): + """Valida que la reindexación manual requiera rol de Administrador.""" + client = TestClient(app) + + # 1. Sin autenticar debe responder 401 + unauth_res = client.post("/api/chat/rag/reindex") + assert unauth_res.status_code == 401 + + # 2. Con usuario Admin + admin_u = User( + email="admin.rag@unicaba.edu.ar", + name="Admin RAG", + password_hash=generate_password_hash("SecretAdminRAG!"), + role="ADMIN", + is_active=True + ) + init_database.session.add(admin_u) + init_database.session.commit() + + login_res = client.post("/api/v1/auth/login", json={ + "email": "admin.rag@unicaba.edu.ar", + "password": "SecretAdminRAG!" + }) + token = login_res.json()["access_token"] + headers = {"Authorization": f"Bearer {token}"} + + reindex_res = client.post("/api/chat/rag/reindex", headers=headers) + assert reindex_res.status_code == 200 + data = reindex_res.json() + assert data["status"] == "success" + assert data["indexed_chunks"] >= 10 diff --git a/frontend/package.json b/frontend/package.json index fa39fe7..725ea43 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -1,6 +1,6 @@ { "name": "frontend", - "version": "3.8.24", + "version": "3.8.25", "description": "", "main": "index.js", "scripts": { diff --git a/frontend/public/js/ai-chat-widget.js b/frontend/public/js/ai-chat-widget.js index 2823136..cb48b31 100644 --- a/frontend/public/js/ai-chat-widget.js +++ b/frontend/public/js/ai-chat-widget.js @@ -1,13 +1,32 @@ /** - * ai-chat-widget.js - Lógica interactiva del Asistente IA (SDD-009) - * Maneja el estado conversacional, llamadas AJAX al backend FastAPI, - * persistencia de sesión y renderizado accesible de mensajes. + * ai-chat-widget.js - Lógica interactiva de UdeCi (SDD-010) + * Asistente y Tutor Virtual de UniCABA con soporte RAG, + * respuestas concisas y botones de opciones interactivas. */ (function() { 'use strict'; let isProcessing = false; - const STORAGE_KEY = 'edu_space_ai_chat_messages_v1'; + const STORAGE_KEY = 'edu_space_udeci_chat_history_v2'; + + const ROLE_CHIPS = { + docente: [ + { label: "📍 Aulas y Meet", query: "¿Dónde consulto mis aulas asignadas y salas de Meet?" }, + { label: "📝 Actas Gradebook", query: "¿Cómo cargo notas y cierro actas de regularidad?" }, + { label: "👥 Ver Comisiones", query: "¿Dónde veo la lista de alumnos inscriptos?" } + ], + bedelia: [ + { label: "🔄 Flujo 9 Pasos", query: "¿Cuáles son los 9 pasos del flujo de Bedelía?" }, + { label: "⚠️ Conflictos Áulicos", query: "¿Cómo funciona la matriz de conflictos y aforo?" }, + { label: "🧬 Optimizador IA", query: "¿Cómo uso el optimizador de aulas?" }, + { label: "📑 Importar Sheets", query: "¿Cómo uso el importador de Google Sheets?" } + ], + alumno: [ + { label: "📍 ¿Dónde curso hoy?", query: "¿En qué aula curso hoy mis materias?" }, + { label: "📚 Mis Materias", query: "¿Dónde consulto mis asignaturas inscriptas?" }, + { label: "📊 Calificaciones", query: "¿Cómo veo mis notas y regularidad?" } + ] + }; function getContainer() { return document.getElementById('aiChatContainer'); @@ -15,17 +34,20 @@ function getUserRole() { const container = getContainer(); - return (container ? container.getAttribute('data-user-role') : 'alumno') || 'alumno'; + const rawRole = (container ? container.getAttribute('data-user-role') : 'alumno') || 'alumno'; + const r = rawRole.toLowerCase(); + if (r.includes('docente') || r.includes('profesor') || r.includes('teacher')) return 'docente'; + if (r.includes('bedelia') || r.includes('admin')) return 'bedelia'; + return 'alumno'; } function getWelcomeMessage(role) { - const r = (role || 'alumno').toLowerCase(); - if (r.includes('docente') || r.includes('profesor') || r.includes('teacher')) { - return "¡Hola! 👋 Soy tu Tutor de Edu-Space para Docentes. Puedo orientarte sobre cómo consultar tus aulas asignadas, cargar calificaciones en el Gradebook, cerrar actas de regularidad y gestionar enlaces de Google Meet. ¿En qué puedo asistirte?"; - } else if (r.includes('bedelia') || r.includes('admin')) { - return "¡Hola! 👋 Soy el Asistente Técnico de Bedelía. Puedo ayudarte con el flujo secuencial de 9 pasos, matriz de conflictos áulicos, el Optimizador Genético, importación masiva de Google Sheets y la cola de Moodle 4.1. ¿Qué tarea deseas revisar?"; + if (role === 'docente') { + return "¡Hola! Soy **UdeCi**, tu tutor de Edu-Space para docentes. Puedo orientarte sobre asignaciones de aulas, el Gradebook y clases virtuales."; + } else if (role === 'bedelia') { + return "¡Hola! Soy **UdeCi**, tu asistente de soporte técnico para Bedelía. Puedo guiarte en el circuito de 9 pasos, resolución de conflictos y Moodle."; } else { - return "¡Hola! 👋 Soy tu Tutor de Cursada. Puedo ayudarte a consultar en qué aula o sala virtual cursas hoy, ver tus horarios semanales, verificar materias inscriptas y notas académicas. ¿Cuál es tu consulta?"; + return "¡Hola! Soy **UdeCi**, tu tutor virtual de cursada. Puedo ayudarte a consultar en qué aula cursas hoy, horarios y notas."; } } @@ -63,107 +85,73 @@ return escaped; } - function appendMessage(role, content, save = true) { + function appendMessage(role, content, options = [], save = true) { const messagesContainer = document.getElementById('aiChatMessages'); if (!messagesContainer) return; const isUser = role === 'user'; const msgDiv = document.createElement('div'); msgDiv.className = `ai-msg ${isUser ? 'ai-msg-user' : 'ai-msg-assistant'}`; - msgDiv.innerHTML = isUser ? renderMarkdown(content) : renderMarkdown(content); + + let html = renderMarkdown(content); + // Si es mensaje del asistente y tiene opciones, renderizar botones interactivos + if (!isUser && options && options.length > 0) { + html += '
'; + options.forEach(opt => { + const cleanOpt = opt.replace(/^[📍📝👥🔄⚠️🧬📑📚📊❓]\s*/, '').trim(); + html += ``; + }); + html += '
'; + } + + msgDiv.innerHTML = html; messagesContainer.appendChild(msgDiv); messagesContainer.scrollTop = messagesContainer.scrollHeight; + // Asignar listeners a los botones de opciones dentro de la burbuja + msgDiv.querySelectorAll('.ai-option-btn').forEach(btn => { + btn.addEventListener('click', function(e) { + e.preventDefault(); + const q = this.getAttribute('data-query'); + if (q) sendQuery(q); + }); + }); + if (save) { const history = loadHistory(); - history.push({ role, content }); + history.push({ role, content, options }); saveHistory(history); } } - function initChat() { - const launcher = document.getElementById('aiChatLauncher'); - const panel = document.getElementById('aiChatPanel'); - const closeBtn = document.getElementById('aiChatCloseBtn'); - const clearBtn = document.getElementById('aiChatClearBtn'); - const textarea = document.getElementById('aiChatInput'); - const form = document.getElementById('aiChatForm'); + function populateHeaderChips(role) { + const headerChips = document.getElementById('aiQuickChipsHeader'); + if (!headerChips) return; + headerChips.innerHTML = ''; - if (!launcher || !panel) return; - - // Toggle panel - launcher.addEventListener('click', () => { - const isHidden = panel.classList.contains('d-none'); - if (isHidden) { - panel.classList.remove('d-none'); - launcher.style.transform = 'scale(0.9)'; - setTimeout(() => { - if (textarea) textarea.focus(); - }, 100); - } else { - panel.classList.add('d-none'); - launcher.style.transform = ''; - } + const chips = ROLE_CHIPS[role] || ROLE_CHIPS.alumno; + chips.forEach(chip => { + const btn = document.createElement('button'); + btn.type = 'button'; + btn.className = 'ai-quick-chip'; + btn.textContent = chip.label; + btn.title = chip.query; + btn.addEventListener('click', () => sendQuery(chip.query)); + headerChips.appendChild(btn); }); - - if (closeBtn) { - closeBtn.addEventListener('click', () => { - panel.classList.add('d-none'); - launcher.style.transform = ''; - }); - } - - // Limpiar conversación - if (clearBtn) { - clearBtn.addEventListener('click', () => { - if (confirm('¿Deseas reiniciar la conversación con el tutor?')) { - sessionStorage.removeItem(STORAGE_KEY); - const messagesContainer = document.getElementById('aiChatMessages'); - if (messagesContainer) messagesContainer.innerHTML = ''; - const role = getUserRole(); - appendMessage('assistant', getWelcomeMessage(role), false); - } - }); - } - - // Cargar historial previo o mensaje de bienvenida - const history = loadHistory(); - const role = getUserRole(); - if (history.length > 0) { - history.forEach(msg => appendMessage(msg.role, msg.content, false)); - } else { - appendMessage('assistant', getWelcomeMessage(role), false); - } - - // Auto-resize de textarea y atajo Enter - if (textarea) { - textarea.addEventListener('keydown', (e) => { - if (e.key === 'Enter' && !e.shiftKey) { - e.preventDefault(); - if (form) form.dispatchEvent(new Event('submit', { cancelable: true })); - } - }); - } } - window.handleAiChatSubmit = async function(e) { - if (e) e.preventDefault(); - if (isProcessing) return; + async function sendQuery(queryText) { + if (!queryText || isProcessing) return; const textarea = document.getElementById('aiChatInput'); const typing = document.getElementById('aiChatTyping'); const sendBtn = document.getElementById('aiChatSendBtn'); - if (!textarea) return; - const query = textarea.value.trim(); - if (!query) return; + if (textarea) textarea.value = ''; + appendMessage('user', queryText, [], true); - // Limpiar campo de texto y mostrar mensaje del usuario - textarea.value = ''; - appendMessage('user', query, true); - - // Bloquear UI e indicar escritura isProcessing = true; if (typing) typing.classList.remove('d-none'); if (sendBtn) sendBtn.disabled = true; @@ -187,19 +175,93 @@ const data = await res.json(); if (res.ok && data.response) { - appendMessage('assistant', data.response, true); + appendMessage('assistant', data.response, data.quick_options || [], true); } else { - const errorMsg = data.detail || data.message || 'El motor de IA local no está respondiendo en este momento.'; - appendMessage('assistant', `⚠️ ${errorMsg}`, false); + const errorMsg = data.detail || data.message || 'UdeCi no pudo procesar la respuesta en este momento.'; + appendMessage('assistant', `⚠️ ${errorMsg}`, [], false); } } catch (err) { - appendMessage('assistant', `⚠️ No se pudo comunicar con el servidor local de IA: ${err.message}`, false); + appendMessage('assistant', `⚠️ Error de comunicación: ${err.message}`, [], false); } finally { isProcessing = false; if (typing) typing.classList.add('d-none'); if (sendBtn) sendBtn.disabled = false; - textarea.focus(); + if (textarea) textarea.focus(); } + } + + function initChat() { + const launcher = document.getElementById('aiChatLauncher'); + const panel = document.getElementById('aiChatPanel'); + const closeBtn = document.getElementById('aiChatCloseBtn'); + const clearBtn = document.getElementById('aiChatClearBtn'); + const textarea = document.getElementById('aiChatInput'); + const form = document.getElementById('aiChatForm'); + + if (!launcher || !panel) return; + + const role = getUserRole(); + populateHeaderChips(role); + + // Toggle panel + launcher.addEventListener('click', () => { + const isHidden = panel.classList.contains('d-none'); + if (isHidden) { + panel.classList.remove('d-none'); + launcher.style.transform = 'scale(0.9)'; + setTimeout(() => { + if (textarea) textarea.focus(); + }, 100); + } else { + panel.classList.add('d-none'); + launcher.style.transform = ''; + } + }); + + if (closeBtn) { + closeBtn.addEventListener('click', () => { + panel.classList.add('d-none'); + launcher.style.transform = ''; + }); + } + + // Reiniciar conversación + if (clearBtn) { + clearBtn.addEventListener('click', () => { + sessionStorage.removeItem(STORAGE_KEY); + const messagesContainer = document.getElementById('aiChatMessages'); + if (messagesContainer) messagesContainer.innerHTML = ''; + const initialOptions = (ROLE_CHIPS[role] || []).map(c => c.label); + appendMessage('assistant', getWelcomeMessage(role), initialOptions, false); + }); + } + + // Cargar historial previo o mensaje de bienvenida + const history = loadHistory(); + if (history.length > 0) { + history.forEach(msg => appendMessage(msg.role, msg.content, msg.options || [], false)); + } else { + const initialOptions = (ROLE_CHIPS[role] || []).map(c => c.label); + appendMessage('assistant', getWelcomeMessage(role), initialOptions, false); + } + + // Atajo Enter para enviar + if (textarea) { + textarea.addEventListener('keydown', (e) => { + if (e.key === 'Enter' && !e.shiftKey) { + e.preventDefault(); + if (form) form.dispatchEvent(new Event('submit', { cancelable: true })); + } + }); + } + } + + window.handleAiChatSubmit = function(e) { + if (e) e.preventDefault(); + const textarea = document.getElementById('aiChatInput'); + if (!textarea) return; + const text = textarea.value.trim(); + if (text) sendQuery(text); }; if (document.readyState === 'loading') { diff --git a/frontend/src/app.js b/frontend/src/app.js index b724400..a6282af 100644 --- a/frontend/src/app.js +++ b/frontend/src/app.js @@ -86,9 +86,9 @@ const env = nunjucks.configure(path.join(__dirname, '../views'), { }); // Versiones institucionales del sistema -const APP_VERSION = '3.8.24'; -const FRONTEND_VERSION = '3.8.24'; -const BACKEND_VERSION = '3.8.24'; +const APP_VERSION = '3.8.25'; +const FRONTEND_VERSION = '3.8.25'; +const BACKEND_VERSION = '3.8.25'; env.addGlobal('app_version', APP_VERSION); env.addGlobal('frontend_version', FRONTEND_VERSION); diff --git a/frontend/views/partials/ai_chat_widget.html b/frontend/views/partials/ai_chat_widget.html index f1dfb08..2c72d29 100644 --- a/frontend/views/partials/ai_chat_widget.html +++ b/frontend/views/partials/ai_chat_widget.html @@ -1,57 +1,64 @@ {% set current_role_name = (current_user.role if current_user and current_user.role else (user.role if user and user.role else 'alumno')) | lower %} - - + +
- - +
- + diff --git a/specs/010-arquitectura-rag-udeci/plan.md b/specs/010-arquitectura-rag-udeci/plan.md new file mode 100644 index 0000000..f88f07f --- /dev/null +++ b/specs/010-arquitectura-rag-udeci/plan.md @@ -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. diff --git a/specs/010-arquitectura-rag-udeci/spec.md b/specs/010-arquitectura-rag-udeci/spec.md new file mode 100644 index 0000000..69986aa --- /dev/null +++ b/specs/010-arquitectura-rag-udeci/spec.md @@ -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. diff --git a/specs/010-arquitectura-rag-udeci/tasks.md b/specs/010-arquitectura-rag-udeci/tasks.md new file mode 100644 index 0000000..b1435a9 --- /dev/null +++ b/specs/010-arquitectura-rag-udeci/tasks.md @@ -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.