diff --git a/CHANGELOG.md b/CHANGELOG.md index a9d17af..e62393b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,32 @@ 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.24] - 2026-10-27 +### Added & Integrated (Asistente IA Contextual - SDD-009) +- **Integración de Asistente IA con Llama.cpp Local (Qwen3 Coder 30B)**: + - **Especificación SDD-009**: Formalizada la especificación completa en `specs/009-asistente-ia-chatbot/` (`spec.md`, `plan.md`, `tasks.md`) con requisitos EARS y matriz de restricciones de rol. + - **Contratos Fuertes Pydantic v2 (`backend/schemas/ai_chat.py`)**: + - DTOs declarativos `ChatMessage`, `ChatRequest`, `ChatResponse` y `AISettingsSchema` con validación de expresiones regulares, longitudes y rangos de temperatura/timeout. + - **Router FastAPI Asíncrono (`backend/routers/ai_chat.py`)**: + - Implementados endpoints `/api/chat/`, `/api/v1/chat/`, `/test-connection` y `/config` montados en `main.py`. + - Cliente HTTP no bloqueante con `httpx.AsyncClient` y timeout generoso configurable (default 60s, soporte hasta 600s). + - Inyección dinámica de System Prompt adaptado al rol del usuario autenticado: + * **Docente**: Orientación sobre reserva de aulas, actas en Gradebook, cronograma y enlaces a Google Meet. + * **Alumno**: Guía de cursada, aulas del día, materias matriculadas y notas, con prohibición total de acceso a procedimientos de gestión. + * **Bedelía / Admin**: Soporte Nivel 1 en el circuito de 9 pasos, resolución de matriz de conflictos, optimizador genético, importador de Google Sheets y Moodle 4.1. + - Manejo controlado de fallas de red y timeouts retornando HTTP 503/504 descriptivos sin bloquear el servidor. + - **Configuración Global Administrativa (`/admin/settings`)**: + - Agregada pestaña dedicada "Asistente IA & LLM Local" (`#tab-ai`) en `global_config.html`. + - Formulario con switches de habilitación, URL base del servidor (`http://10.0.0.214:8080/v1`), API key cifrada con Fernet, modelo (`qwen3-coder:30b`), temperatura, timeout y límites de contexto/salida. + - Botón interactivo "Probar Conexión con Llama.cpp" con feedback en vivo de latencia y modelos disponibles. + - **Widget de Chatbot Flotante Interactivo en Frontend**: + - Componente parcial `frontend/views/partials/ai_chat_widget.html` inyectado en `base.html` para todos los usuarios autenticados. + - Lógica cliente `frontend/public/js/ai-chat-widget.js` con persistencia en `sessionStorage`, detección de rol, formateo de Markdown, indicador animado de escritura y scroll automático. + - Proxy transparente `/api/chat` en Node.js BFF (`frontend/src/app.js`). + - **Calidad y Verificación Automatizada**: + - Creada suite `backend/tests/test_ai_chat.py` (9 tests unitarios/integración pasando al 100%). + - Suite completa de 89 tests en verde (`89 passed`). 0 errores en compilación de tipos (`py_compile`). + ## [3.8.23] - 2026-10-27 ### Improved & Fixed (UI / UX) - **Importador de Google Sheets: Optimización de Contrastes en Modo Oscuro (`admin/google_sheets_import`)**: diff --git a/MEMORY.md b/MEMORY.md index e74395c..50ec72c 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -9,14 +9,18 @@ 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: Optimización de Contrastes en Modo Oscuro (Google Sheets Import) — v3.8.23**: - - **Rediseño y Alto Contraste en Modo Oscuro (`admin/google_sheets_import`)**: - - Optimizado el contraste visual de pastillas de días de la semana (`.day-pill`), botones rápidos (`.btn-quick-week`), y tarjetas de selección de entidades importables (`.import-entity-card`) para `[data-bs-theme="dark"]`. - - Ajustado el panel de ámbito temporal (`.panel-temporal-box`) con fondos integrados y bordes definidos. - - Sustituidas clases opacas por badges temáticos de alto contraste (`bg-warning-subtle text-warning-emphasis`, `bg-body-secondary text-body`). - - Mejorada la legibilidad de textos secundarios y muted (`#cbd5e1`, `#94a3b8`) y celdas de previsualización en la tabla de importación masiva. - - **QA & Seguridad**: 80 tests aprobados en `pytest` (100%), 0 vulnerabilidades en auditoría de seguridad. - - **Versión Consolidada**: `v3.8.23`. +- **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`. ## 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 2cfcc12..e59c7f1 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.23" +__version__ = "3.8.24" class DummyContext: def __enter__(self): diff --git a/backend/main.py b/backend/main.py index 8bf23bb..b9f47a8 100644 --- a/backend/main.py +++ b/backend/main.py @@ -19,6 +19,7 @@ from routers.admin import admin_router from routers.students import students_router from routers.dashboard import dashboard_router from routers.optimizer import optimizer_router, genetic_router +from routers.ai_chat import router as ai_chat_router # Initialize FastAPI Application app = FastAPI( @@ -51,6 +52,8 @@ app.include_router(students_router) app.include_router(dashboard_router) app.include_router(optimizer_router) app.include_router(genetic_router) +app.include_router(ai_chat_router, prefix="/api/chat") +app.include_router(ai_chat_router, prefix="/api/v1/chat") if __name__ == "__main__": diff --git a/backend/routers/admin.py b/backend/routers/admin.py index 8d09a69..8d2f90e 100644 --- a/backend/routers/admin.py +++ b/backend/routers/admin.py @@ -852,6 +852,18 @@ def get_all_settings(current_user: User = Depends(require_roles(["ADMIN"]))): 'show_role_banner': SystemSetting.get_value('dashboard_role_banner_enabled', 'true') in ['true', 'True', '1', True] } + ai_config = { + 'enabled': SystemSetting.get_value('ai_chat_enabled', 'true') in ['true', 'True', '1', True], + 'base_url': SystemSetting.get_value('ai_chat_base_url', 'http://10.0.0.214:8080/v1'), + 'api_key': SystemSetting.get_masked_value('ai_chat_api_key', '••••••••••••') if SystemSetting.get_value('ai_chat_api_key') else 'llama', + 'model': SystemSetting.get_value('ai_chat_model', 'qwen3-coder:30b'), + 'model_name': SystemSetting.get_value('ai_chat_model_name', 'Qwen3 Coder 30B-A3B (Llama.cpp)'), + 'temperature': float(SystemSetting.get_value('ai_chat_temperature', 0.3) or 0.3), + 'timeout': int(SystemSetting.get_value('ai_chat_timeout', 60) or 60), + 'context_limit': int(SystemSetting.get_value('ai_chat_context_limit', 65536) or 65536), + 'output_limit': int(SystemSetting.get_value('ai_chat_output_limit', 65536) or 65536) + } + return { 'status': 'success', 'settings': { @@ -859,7 +871,9 @@ def get_all_settings(current_user: User = Depends(require_roles(["ADMIN"]))): 'auth_providers': auth_providers, 'google_oauth': google_oauth, 'moodle': moodle_config, - 'ui': ui_config + 'ui': ui_config, + 'ai': ai_config, + 'ai_assistant': ai_config } } @@ -1052,6 +1066,114 @@ async def update_ui_settings( } +@admin_router.post("/settings/ai") +@admin_router.post("/admin/settings/ai") +async def update_ai_settings( + request: Request, + current_user: User = Depends(require_roles(["ADMIN"])) +): + """Actualiza la configuración del proveedor de IA local (Llama.cpp / Qwen3).""" + data = await get_request_payload(request) + + enabled_input = data.get('enabled') + enabled = 'true' if enabled_input in [True, 'true', '1', 'on', 1] else 'false' + base_url = str(data.get('base_url', 'http://10.0.0.214:8080/v1')).strip().rstrip('/') + api_key = str(data.get('api_key', '')).strip() + model = str(data.get('model', 'qwen3-coder:30b')).strip() + model_name = str(data.get('model_name', 'Qwen3 Coder 30B-A3B (Llama.cpp)')).strip() + temperature = str(data.get('temperature', '0.3')).strip() + timeout = str(data.get('timeout', '60')).strip() + context_limit = str(data.get('context_limit', '65536')).strip() + output_limit = str(data.get('output_limit', '65536')).strip() + + SystemSetting.set_value('ai_chat_enabled', enabled, 'Habilitación de Asistente IA', category='ai') + SystemSetting.set_value('ai_chat_base_url', base_url, 'URL base del servidor Llama.cpp', category='ai') + if api_key and api_key != '••••••••••••': + SystemSetting.set_encrypted_value('ai_chat_api_key', api_key, 'Clave API del servidor de IA', category='ai') + SystemSetting.set_value('ai_chat_model', model, 'ID del modelo Llama.cpp', category='ai') + SystemSetting.set_value('ai_chat_model_name', model_name, 'Nombre descriptivo del modelo', category='ai') + SystemSetting.set_value('ai_chat_temperature', temperature, 'Temperatura de generación', category='ai') + SystemSetting.set_value('ai_chat_timeout', timeout, 'Timeout de inferencia en segundos', category='ai') + SystemSetting.set_value('ai_chat_context_limit', context_limit, 'Límite de tokens de contexto', category='ai') + SystemSetting.set_value('ai_chat_output_limit', output_limit, 'Límite de tokens de respuesta', category='ai') + + AuditService.log( + action='UPDATE_AI_SETTINGS', + module='settings', + user=current_user, + details=f"Configuración de Asistente IA actualizada (Modelo: {model}, URL: {base_url})" + ) + + return { + 'status': 'success', + 'message': 'Configuración de Asistente IA guardada exitosamente.', + 'settings': { + 'enabled': enabled == 'true', + 'base_url': base_url, + 'model': model, + 'model_name': model_name, + 'temperature': float(temperature) if temperature else 0.3, + 'timeout': int(timeout) if timeout else 60 + } + } + + +@admin_router.post("/settings/ai/test") +@admin_router.post("/admin/settings/ai/test") +async def test_ai_settings_connection( + request: Request, + current_user: User = Depends(require_roles(["ADMIN"])) +): + """Prueba en tiempo real la conectividad con el servidor de IA local.""" + import time + import httpx + + data = await get_request_payload(request) + base_url = str(data.get('base_url') or SystemSetting.get_value('ai_chat_base_url', 'http://10.0.0.214:8080/v1')).strip().rstrip('/') + api_key = data.get('api_key') + if not api_key or api_key == '••••••••••••': + api_key = SystemSetting.get_decrypted_value('ai_chat_api_key', 'llama') or 'llama' + + target_url = f"{base_url}/models" + headers = {"Authorization": f"Bearer {api_key}"} + + start_time = time.time() + async with httpx.AsyncClient(timeout=10.0) as client: + try: + resp = await client.get(target_url, headers=headers) + latency_ms = round((time.time() - start_time) * 1000, 2) + if resp.status_code == 200: + data_json = resp.json() + models = [m.get("id") for m in data_json.get("data", []) if isinstance(m, dict) and "id" in m] + return { + 'status': 'success', + 'message': f"Conexión exitosa con Llama.cpp ({base_url}). Latencia: {latency_ms} ms.", + 'latency_ms': latency_ms, + 'models': models + } + else: + return { + 'status': 'warning', + 'message': f"Respuesta inesperada del servidor ({resp.status_code}): {resp.text[:200]}", + 'latency_ms': latency_ms, + 'models': [] + } + except httpx.TimeoutException: + return { + 'status': 'error', + 'message': f"Tiempo de espera agotado al conectar a {base_url} (Timeout: 10s).", + 'latency_ms': None, + 'models': [] + } + except httpx.RequestError as e: + return { + 'status': 'error', + 'message': f"No se pudo conectar a {base_url}: {str(e)}", + 'latency_ms': None, + 'models': [] + } + + @admin_router.get("/settings/demo-mode") @admin_router.get("/admin/settings/demo-mode") def get_demo_mode_status(current_user: User = Depends(require_roles(["ADMIN"]))): diff --git a/backend/routers/ai_chat.py b/backend/routers/ai_chat.py new file mode 100644 index 0000000..bfe6e51 --- /dev/null +++ b/backend/routers/ai_chat.py @@ -0,0 +1,241 @@ +""" +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) +""" +import time +from typing import Optional +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 schemas.ai_chat import ( + ChatRequest, + ChatResponse, + AITestConnectionResponse, + AISettingsSchema +) + +router = APIRouter(tags=["AI Chatbot"]) + + +def generate_system_prompt_for_role(role: Optional[str]) -> 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. + """ + 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." + ) + + 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." + ) + + +def _get_ai_config() -> dict: + """Recupera la configuración activa del motor de IA desde SystemSetting.""" + enabled_val = SystemSetting.get_value("ai_chat_enabled", "true") + 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)" + + try: + temperature = float(SystemSetting.get_value("ai_chat_temperature", 0.3)) + except (ValueError, TypeError): + temperature = 0.3 + + try: + timeout = float(SystemSetting.get_value("ai_chat_timeout", 60.0)) + except (ValueError, TypeError): + timeout = 60.0 + + return { + "enabled": enabled, + "base_url": base_url.strip().rstrip("/"), + "api_key": api_key.strip(), + "model": model.strip(), + "model_name": model_name.strip(), + "temperature": temperature, + "timeout": timeout + } + + +@router.post("/", response_model=ChatResponse) +@router.post("", response_model=ChatResponse) +async def get_agent_response( + request: ChatRequest, + req: Request, + 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. + """ + 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." + ) + + # 1. Determinar rol efectivo + effective_role = request.user_role or "alumno" + if current_user: + if getattr(current_user, "is_admin", False) or (getattr(current_user, "role", "") or "").upper() == "ADMIN": + effective_role = "bedelia" + elif hasattr(current_user, "role") and current_user.role: + role_str = str(current_user.role).lower() + if "docente" in role_str or "profesor" in role_str or "teacher" in role_str: + effective_role = "docente" + elif "bedelia" in role_str or "admin" in role_str: + effective_role = "bedelia" + else: + effective_role = "alumno" + + # 2. Inyección de Contexto + system_prompt = generate_system_prompt_for_role(effective_role) + + formatted_messages = [{"role": "system", "content": system_prompt}] + for msg in request.messages: + formatted_messages.append({"role": msg.role, "content": msg.content}) + + payload = { + "model": config["model"], + "messages": formatted_messages, + "temperature": config["temperature"] + } + + target_url = f"{config['base_url']}/chat/completions" + headers = { + "Authorization": f"Bearer {config['api_key']}", + "Content-Type": "application/json" + } + + # 3. Petición asíncrona no bloqueante al servidor local + 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) + 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)." + ) + except httpx.HTTPStatusError as e: + detail_msg = f"Error del motor de IA local ({e.response.status_code}): {e.response.text[:200]}" + raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail=detail_msg) + 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." + ) + + +@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. + """ + config = _get_ai_config() + target_url = f"{config['base_url']}/models" + headers = {"Authorization": f"Bearer {config['api_key']}"} + + start_time = time.time() + async with httpx.AsyncClient(timeout=10.0) as client: + try: + resp = await client.get(target_url, headers=headers) + latency_ms = round((time.time() - start_time) * 1000, 2) + if resp.status_code == 200: + data = resp.json() + 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.", + latency_ms=latency_ms, + models=model_ids + ) + else: + return AITestConnectionResponse( + status="warning", + message=f"Respuesta inesperada del servidor ({resp.status_code}): {resp.text[:200]}", + latency_ms=latency_ms, + models=[] + ) + except httpx.TimeoutException: + return AITestConnectionResponse( + status="error", + message=f"Tiempo de espera agotado al conectar a {config['base_url']} (Timeout: 10s).", + latency_ms=None, + models=[] + ) + except httpx.RequestError as e: + return AITestConnectionResponse( + status="error", + message=f"No se pudo conectar a {config['base_url']}: {str(e)}", + latency_ms=None, + models=[] + ) + + +@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.""" + config = _get_ai_config() + return { + "status": "success", + "enabled": config["enabled"], + "model": config["model"], + "model_name": config["model_name"] + } diff --git a/backend/schemas/__init__.py b/backend/schemas/__init__.py index 30e0a3c..e15e397 100644 --- a/backend/schemas/__init__.py +++ b/backend/schemas/__init__.py @@ -1 +1,3 @@ # Schemas package initialization +from schemas.auth import * +from schemas.ai_chat import * diff --git a/backend/schemas/ai_chat.py b/backend/schemas/ai_chat.py new file mode 100644 index 0000000..d77fb8a --- /dev/null +++ b/backend/schemas/ai_chat.py @@ -0,0 +1,35 @@ +from typing import Optional, List +from pydantic import BaseModel, Field + + +class ChatMessage(BaseModel): + role: str = Field(..., pattern="^(user|assistant|system)$", description="Rol del emisor: user, assistant o system") + content: str = Field(..., min_length=1, description="Contenido textual del mensaje") + + +class ChatRequest(BaseModel): + messages: List[ChatMessage] = Field(..., min_length=1, description="Historial de mensajes de la conversación") + user_role: Optional[str] = Field("alumno", description="Rol del usuario: alumno, docente, bedelia, admin") + + +class ChatResponse(BaseModel): + response: str = Field(..., description="Respuesta generada por el agente conversacional") + + +class AISettingsSchema(BaseModel): + enabled: bool = Field(True, description="Habilitación del servicio de Asistente IA") + base_url: str = Field("http://10.0.0.214:8080/v1", description="URL base de la API compatible OpenAI / Llama.cpp") + api_key: str = Field("llama", description="Clave API para autenticación con el servidor local") + model: str = Field("qwen3-coder:30b", description="Identificador del modelo en Llama.cpp") + model_name: Optional[str] = Field("Qwen3 Coder 30B-A3B (Llama.cpp)", description="Nombre amigable del modelo") + temperature: float = Field(0.3, ge=0.0, le=2.0, description="Temperatura para control de variabilidad (0.0 a 2.0)") + timeout: int = Field(60, ge=5, le=600, description="Tiempo límite de espera en segundos") + context_limit: int = Field(65536, ge=512, description="Ventana de contexto máxima en tokens") + output_limit: int = Field(65536, ge=128, description="Límite máximo de salida de tokens") + + +class AITestConnectionResponse(BaseModel): + status: str + message: str + latency_ms: Optional[float] = None + models: Optional[List[str]] = None diff --git a/backend/setup.py b/backend/setup.py index 74427e4..680c039 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.23", + version="3.8.24", 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 new file mode 100644 index 0000000..516e713 --- /dev/null +++ b/backend/tests/test_ai_chat.py @@ -0,0 +1,257 @@ +""" +Suite de pruebas automatizadas para el módulo de Asistente IA (SDD-009). +Valida contratos Pydantic v2, inyección de System Prompts por rol, +llamadas asíncronas con httpx (mockeadas) y gestión de configuración administrativa. +""" +from unittest.mock import AsyncMock, patch, MagicMock +import pytest +from pydantic import ValidationError +from fastapi.testclient import TestClient +import httpx +from werkzeug.security import generate_password_hash + +from main import app +from schemas.ai_chat import ChatMessage, ChatRequest, ChatResponse, AISettingsSchema +from routers.ai_chat import generate_system_prompt_for_role +from app.models.setting import SystemSetting +from app.models.user import User + + +def test_ai_chat_pydantic_schemas_validation(): + """Valida restricciones de datos y tipos en Pydantic v2.""" + # 1. ChatMessage válido + msg = ChatMessage(role="user", content="¿Dónde curso hoy?") + assert msg.role == "user" + assert msg.content == "¿Dónde curso hoy?" + + # 2. Rechazo por rol inválido + with pytest.raises(ValidationError): + ChatMessage(role="hacker", content="Mensaje") + + # 3. Rechazo por contenido vacío + with pytest.raises(ValidationError): + ChatMessage(role="user", content="") + + # 4. ChatRequest válido + req = ChatRequest(messages=[msg], user_role="docente") + assert len(req.messages) == 1 + assert req.user_role == "docente" + + # 5. ChatRequest rechaza lista vacía de mensajes + with pytest.raises(ValidationError): + ChatRequest(messages=[], user_role="alumno") + + # 6. AISettingsSchema con validaciones de rango + ai_settings = AISettingsSchema(temperature=0.7, timeout=120) + assert ai_settings.temperature == 0.7 + assert ai_settings.timeout == 120 + + with pytest.raises(ValidationError): + AISettingsSchema(temperature=3.5) # Mayor a 2.0 + + +def test_system_prompt_generation_by_role(): + """Verifica que el System Prompt inyectado se adapte rigurosamente al rol.""" + # 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 + + # 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 + + # 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 + + +def test_ai_chat_public_config_endpoint(): + """Verifica el endpoint público /api/chat/config utilizado por el widget.""" + client = TestClient(app) + response = client.get("/api/chat/config") + assert response.status_code == 200 + data = response.json() + assert data["status"] == "success" + assert "enabled" in data + assert "model" in data + + +def test_ai_chat_endpoint_success_mock(init_database): + """Simula una respuesta exitosa 200 de Llama.cpp.""" + client = TestClient(app) + + mock_response = MagicMock() + mock_response.status_code = 200 + mock_response.json.return_value = { + "choices": [ + { + "message": { + "role": "assistant", + "content": "Para consultar el aula de cursada hoy, accede a la Cartelera de Clases en tu panel principal." + } + } + ] + } + mock_response.raise_for_status = MagicMock() + + with patch("httpx.AsyncClient.post", new_callable=AsyncMock) as mock_post: + mock_post.return_value = mock_response + + # Prueba en /api/chat + res = client.post("/api/chat", json={ + "messages": [{"role": "user", "content": "¿En qué aula curso hoy?"}], + "user_role": "alumno" + }) + assert res.status_code == 200 + data = res.json() + assert "response" in data + assert "Cartelera" in data["response"] + + # Prueba en /api/v1/chat + res_v1 = client.post("/api/v1/chat", json={ + "messages": [{"role": "user", "content": "¿Cómo reservo un aula?"}], + "user_role": "docente" + }) + assert res_v1.status_code == 200 + + +def test_ai_chat_endpoint_validation_error(): + """Valida que una petición malformada responda 422 Unprocessable Entity.""" + client = TestClient(app) + + # Mensajes vacíos + res = client.post("/api/chat", json={ + "messages": [], + "user_role": "alumno" + }) + assert res.status_code == 422 + + # Mensaje sin contenido + res2 = client.post("/api/chat", json={ + "messages": [{"role": "user", "content": ""}] + }) + assert res2.status_code == 422 + + +def test_ai_chat_endpoint_connection_failure(): + """Simula error de conexión con el servidor Llama.cpp y verifica HTTP 503.""" + client = TestClient(app) + + with patch("httpx.AsyncClient.post", new_callable=AsyncMock) as mock_post: + mock_post.side_effect = httpx.ConnectError("Connection refused") + + res = client.post("/api/chat", json={ + "messages": [{"role": "user", "content": "Hola tutor"}] + }) + 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"] + + +def test_ai_chat_endpoint_timeout_failure(): + """Simula tiempo de espera agotado y verifica HTTP 504.""" + client = TestClient(app) + + with patch("httpx.AsyncClient.post", new_callable=AsyncMock) as mock_post: + mock_post.side_effect = httpx.TimeoutException("Read timed out") + + res = client.post("/api/chat", json={ + "messages": [{"role": "user", "content": "Pregunta compleja"}] + }) + assert res.status_code == 504 + data = res.json() + assert "tiempo límite" in data["detail"] + + +def test_ai_chat_disabled_flow(init_database): + """Verifica que si ai_chat_enabled es false, se retorne 503 inmediatamente.""" + client = TestClient(app) + + SystemSetting.set_value("ai_chat_enabled", "false", category="ai") + try: + res = client.post("/api/chat", json={ + "messages": [{"role": "user", "content": "Test"}] + }) + assert res.status_code == 503 + assert "deshabilitado" in res.json()["detail"].lower() + finally: + SystemSetting.set_value("ai_chat_enabled", "true", category="ai") + + +def test_admin_settings_ai_crud_and_test_connection(init_database): + """Verifica los endpoints administrativos de guardado y prueba de conexión de IA.""" + client = TestClient(app) + + # 1. Crear usuario Admin + u = User( + email="admin.ai@unicaba.edu.ar", + name="Admin AI Settings", + password_hash=generate_password_hash("AiAdminSecret!"), + role="ADMIN", + is_active=True + ) + init_database.session.add(u) + init_database.session.commit() + + # Login + login_res = client.post("/api/v1/auth/login", json={ + "email": "admin.ai@unicaba.edu.ar", + "password": "AiAdminSecret!" + }) + token = login_res.json()["access_token"] + headers = {"Authorization": f"Bearer {token}"} + + # 2. Consultar GET /admin/settings/all + all_res = client.get("/api/v1/settings/all", headers=headers) + assert all_res.status_code == 200 + all_data = all_res.json() + assert "ai" in all_data["settings"] + assert all_data["settings"]["ai"]["model"] == "qwen3-coder:30b" + + # 3. Actualizar POST /admin/settings/ai + update_res = client.post("/api/v1/settings/ai", headers=headers, json={ + "enabled": True, + "base_url": "http://10.0.0.214:8080/v1", + "api_key": "new_secret_key", + "model": "qwen3-coder:30b", + "model_name": "Qwen3 Coder 30B (Test)", + "temperature": 0.25, + "timeout": 45, + "context_limit": 32768, + "output_limit": 16384 + }) + assert update_res.status_code == 200 + assert update_res.json()["status"] == "success" + + # Verificar persistencia en base de datos + assert SystemSetting.get_value("ai_chat_model_name") == "Qwen3 Coder 30B (Test)" + assert SystemSetting.get_decrypted_value("ai_chat_api_key") == "new_secret_key" + + # 4. Probar conexión POST /admin/settings/ai/test con mock + mock_models_resp = MagicMock() + mock_models_resp.status_code = 200 + mock_models_resp.json.return_value = { + "data": [{"id": "qwen3-coder:30b"}, {"id": "llama-3-8b"}] + } + + with patch("httpx.AsyncClient.get", new_callable=AsyncMock) as mock_get: + mock_get.return_value = mock_models_resp + + test_res = client.post("/api/v1/settings/ai/test", headers=headers, json={ + "base_url": "http://10.0.0.214:8080/v1", + "api_key": "new_secret_key" + }) + assert test_res.status_code == 200 + test_data = test_res.json() + assert test_data["status"] == "success" + assert "qwen3-coder:30b" in test_data["models"] + assert test_data["latency_ms"] is not None diff --git a/frontend/package.json b/frontend/package.json index 42cea3b..fa39fe7 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -1,6 +1,6 @@ { "name": "frontend", - "version": "3.8.23", + "version": "3.8.24", "description": "", "main": "index.js", "scripts": { diff --git a/frontend/public/js/ai-chat-widget.js b/frontend/public/js/ai-chat-widget.js new file mode 100644 index 0000000..2823136 --- /dev/null +++ b/frontend/public/js/ai-chat-widget.js @@ -0,0 +1,210 @@ +/** + * 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. + */ +(function() { + 'use strict'; + + let isProcessing = false; + const STORAGE_KEY = 'edu_space_ai_chat_messages_v1'; + + function getContainer() { + return document.getElementById('aiChatContainer'); + } + + function getUserRole() { + const container = getContainer(); + return (container ? container.getAttribute('data-user-role') : 'alumno') || '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?"; + } 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?"; + } + } + + function loadHistory() { + try { + const raw = sessionStorage.getItem(STORAGE_KEY); + return raw ? JSON.parse(raw) : []; + } catch (e) { + return []; + } + } + + function saveHistory(messages) { + try { + sessionStorage.setItem(STORAGE_KEY, JSON.stringify(messages)); + } catch (e) {} + } + + function renderMarkdown(text) { + if (!text) return ''; + let escaped = text + .replace(/&/g, '&') + .replace(//g, '>'); + + // Negrita **texto** + escaped = escaped.replace(/\*\*(.*?)\*\*/g, '$1'); + // Cursiva *texto* + escaped = escaped.replace(/\*(.*?)\*/g, '$1'); + // Código inline `codigo` + escaped = escaped.replace(/`([^`]+)`/g, '$1'); + // Saltos de línea + escaped = escaped.replace(/\n/g, '
'); + + return escaped; + } + + function appendMessage(role, content, 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); + + messagesContainer.appendChild(msgDiv); + messagesContainer.scrollTop = messagesContainer.scrollHeight; + + if (save) { + const history = loadHistory(); + history.push({ role, content }); + 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'); + + 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 = ''; + } + }); + + 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; + + 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; + + // 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; + + const userRole = getUserRole(); + const rawHistory = loadHistory(); + const payloadMessages = rawHistory.map(m => ({ + role: m.role, + content: m.content + })); + + try { + const res = await fetch('/api/chat', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ + messages: payloadMessages, + user_role: userRole + }) + }); + + const data = await res.json(); + if (res.ok && data.response) { + appendMessage('assistant', data.response, true); + } else { + const errorMsg = data.detail || data.message || 'El motor de IA local no está respondiendo en este momento.'; + appendMessage('assistant', `⚠️ ${errorMsg}`, false); + } + } catch (err) { + appendMessage('assistant', `⚠️ No se pudo comunicar con el servidor local de IA: ${err.message}`, false); + } finally { + isProcessing = false; + if (typing) typing.classList.add('d-none'); + if (sendBtn) sendBtn.disabled = false; + textarea.focus(); + } + }; + + if (document.readyState === 'loading') { + document.addEventListener('DOMContentLoaded', initChat); + } else { + initChat(); + } +})(); diff --git a/frontend/src/app.js b/frontend/src/app.js index 0015ea5..b724400 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.23'; -const FRONTEND_VERSION = '3.8.23'; -const BACKEND_VERSION = '3.8.23'; +const APP_VERSION = '3.8.24'; +const FRONTEND_VERSION = '3.8.24'; +const BACKEND_VERSION = '3.8.24'; env.addGlobal('app_version', APP_VERSION); env.addGlobal('frontend_version', FRONTEND_VERSION); @@ -365,6 +365,33 @@ app.use('/api/genetic', async (req, res) => { } }); +// Proxy transparente hacia la API del Asistente IA (/api/chat) +app.use('/api/chat', async (req, res) => { + try { + const token = req.cookies.auth_token; + const backendBase = (process.env.FLASK_API_URL || 'http://localhost:5000/api/v1').replace(/\/api\/v1\/?$/, ''); + const targetUrl = `${backendBase}/api/chat${req.url}`; + const headers = { ...req.headers }; + delete headers.host; + delete headers['content-length']; + if (token && !headers.authorization) { + headers.authorization = `Bearer ${token}`; + } + const resp = await axios({ + method: req.method, + url: targetUrl, + data: req.body, + params: req.query, + headers, + validateStatus: () => true + }); + return res.status(resp.status).json(resp.data); + } catch (err) { + console.error('API chat proxy error:', err.message); + return res.status(500).json({ error: 'ProxyError', message: 'Error de comunicación con el Asistente IA: ' + err.message }); + } +}); + app.use('/', indexRoutes); app.use('/auth', authRoutes); diff --git a/frontend/src/routes/admin.js b/frontend/src/routes/admin.js index 0d17276..30a0736 100644 --- a/frontend/src/routes/admin.js +++ b/frontend/src/routes/admin.js @@ -1869,6 +1869,8 @@ router.post('/settings/moodle/test', forwardSettingsAction); router.post('/settings/moodle/sync', forwardSettingsAction); router.get('/settings/moodle/stats', forwardSettingsAction); router.post('/settings/ui', forwardSettingsAction); +router.post('/settings/ai', forwardSettingsAction); +router.post('/settings/ai/test', forwardSettingsAction); router.post('/settings/reset_system', forwardSettingsAction); router.post('/system/reset', forwardSettingsAction); diff --git a/frontend/views/admin/settings/global_config.html b/frontend/views/admin/settings/global_config.html index 11ce9c1..f5e99e9 100644 --- a/frontend/views/admin/settings/global_config.html +++ b/frontend/views/admin/settings/global_config.html @@ -88,6 +88,11 @@ Interfaz & Dashboard +