feat: integración de Asistente IA contextual con Llama.cpp Qwen3 Coder 30B (SDD-009, v3.8.24)

This commit is contained in:
2026-10-27 07:37:00 -03:00
parent 502865e45b
commit 4125f7f7bd
20 changed files with 1692 additions and 16 deletions
+90
View File
@@ -0,0 +1,90 @@
# Plan Técnico: Asistente IA y Chatbot de Ayuda Contextual (SDD-009)
## 1. Arquitectura Técnica de la Solución (4 Capas)
### 1.1 Capa de Esquemas y Contratos (Schemas / DTOs con Pydantic v2)
- **Archivo**: `backend/schemas/ai_chat.py`
- `ChatMessage(BaseModel)`:
- `role: str = Field(pattern="^(user|assistant|system)$")`
- `content: str = Field(min_length=1)`
- `ChatRequest(BaseModel)`:
- `messages: list[ChatMessage]`
- `user_role: str = Field(default="alumno", description="Rol del usuario: alumno, docente, bedelia, admin")`
- `ChatResponse(BaseModel)`:
- `response: str`
- `AISettingsSchema(BaseModel)`:
- `enabled: bool = True`
- `base_url: str = Field(default="http://10.0.0.214:8080/v1")`
- `api_key: str = Field(default="llama")`
- `model: str = Field(default="qwen3-coder:30b")`
- `temperature: float = Field(default=0.3, ge=0.0, le=2.0)`
- `timeout: int = Field(default=60, ge=5, le=600)`
- `context_limit: int = Field(default=65536)`
- `output_limit: int = Field(default=65536)`
### 1.2 Capa de Persistencia y Configuración (Storage & SystemSettings)
- Persistencia en tabla relacional `system_settings` usando `SystemSetting`:
- `ai_chat_enabled`: 'true' | 'false' (default: 'true')
- `ai_chat_base_url`: URL del endpoint compatible OpenAI (default: `http://10.0.0.214:8080/v1`)
- `ai_chat_api_key`: Clave API cifrada con Fernet (`SystemSetting.set_encrypted_value`)
- `ai_chat_model`: ID del modelo a cargar (default: `qwen3-coder:30b`)
- `ai_chat_temperature`: Float string (default: '0.3')
- `ai_chat_timeout`: Entero en segundos (default: '60')
- `ai_chat_context_limit`: Entero (default: '65536')
- `ai_chat_output_limit`: Entero (default: '65536')
### 1.3 Capa de Lógica de Negocio y Routers FastAPI (`backend/routers/`)
- **`backend/routers/ai_chat.py`**:
- `APIRouter(prefix="/api/chat", tags=["AI Chatbot"])` con inclusión adicional en `main.py` bajo `/api/chat` y `/api/v1/chat`.
- Función de inyección de prompt por rol:
`generate_system_prompt_for_role(role: str) -> str`:
- **Docente**: Manual de Reserva de Aulas, Registro de Asistencia, Carga de Actas de Regularidad en Gradebook, Horarios y Aulas Virtuales (Google Meet).
- **Alumno**: Manual de Cursada, Consulta de Cartelera del Día, Identificación de Aulas/Salas, Inscripciones, Consulta de Calificaciones. Regla estricta: No brindar instrucciones sobre administración o alteración de datos de Bedelía.
- **Bedelía / Admin**: Manual Operativo de 9 Pasos, Resolución de Conflictos, Optimizador Genético, Importación de Google Sheets con previsualización, Sincronización Moodle 4.1 y Auditoría.
- Endpoint `POST /` (`/api/chat/` y `/api/v1/chat/`):
- Extrae rol del usuario (priorizando usuario autenticado en JWT si está presente, o `request.user_role`).
- Genera System Prompt y compone el historial en formato estándar OpenAI compatible:
`{"model": model, "messages": [{"role": "system", "content": system_prompt}, ...], "temperature": temperature}`.
- Ejecuta llamada asíncrona no bloqueante con `httpx.AsyncClient(timeout=timeout)`.
- Captura `httpx.RequestError` o respuestas no 2xx y levanta `HTTPException(status_code=503, detail="Error conectando al motor de IA local.")`.
- Retorna `ChatResponse(response=ai_data["choices"][0]["message"]["content"])`.
- Endpoint `POST /test-connection`:
- Verifica conectividad directa con `{base_url}/models` usando el cliente `httpx.AsyncClient`.
- **`backend/routers/admin.py`**:
- Actualizar `get_all_settings` para retornar el bloque `ai_assistant` con valores activos y clave API enmascarada.
- Endpoints `@admin_router.post("/settings/ai")` y `@admin_router.post("/settings/ai/test")`.
### 1.4 Capa de Frontend BFF y Vistas (Express, Nunjucks & Vanilla JS)
- **Vista de Configuración Global (`frontend/views/admin/settings/global_config.html`)**:
- Pestaña `#tab-ai` ("Asistente IA & LLM Local") con icono `bi bi-cpu`.
- Formulario estructurado para configuración de servidor Llama.cpp, modelo, apiKey, parámetros de generación y límites de contexto.
- Botón interactivo "Probar Conexión con Llama.cpp" con feedback dinámico (spinner, alerta de éxito o error con código HTTP y latencia).
- **Widget de Chatbot Flotante (`frontend/views/partials/ai_chat_widget.html` e inyección en `base.html`)**:
- Botón flotante animado en la esquina inferior derecha con icono de asistente.
- Panel colapsable de conversación con cabecera estilizada, avatar institucional, indicador de estado de conexión ("Llama.cpp · Qwen3 Coder 30B") y botón de cierre/minimizar.
- Historial de mensajes con burbujas diferenciadas para usuario y tutor IA, formateo de listas y código, y animación de escritura.
- Input con soporte de multilínea y envío con Enter / clic en botón de enviar.
- Script frontend (`frontend/public/js/ai-chat-widget.js`) que maneja la comunicación AJAX con el backend, almacena el historial temporal en `sessionStorage` y detecta el rol actual del usuario desde la sesión.
---
## 2. Plan de Pruebas Automatizadas
1. **Pruebas de Backend (`backend/tests/test_ai_chat.py`)**:
- Validación de contratos con Pydantic: prueba de `ChatRequest` válido, rechazo con 422 ante payload malformado o contenido vacío.
- Generación de System Prompt: verificación de directivas específicas para `alumno`, `docente` y `bedelia`.
- Simulación de respuesta exitosa de Llama.cpp (Mock de `httpx.AsyncClient`) verificando código 200 y formato `ChatResponse`.
- Manejo de fallas de red / servidor caído: verificación de respuesta HTTP 503 controlada con detalle descriptivo.
- Endpoints de configuración administrativa en `backend/routers/admin.py` para guardar y consultar configuración de IA.
2. **Pruebas de Frontend y UI**:
- Verificación de renderizado de la pestaña de IA en `/admin/settings`.
- Inclusión del widget de chat en `base.html` sin interferir con otros elementos de la UI ni romper el layout en modo oscuro o móvil.
---
## 3. Plan de Despliegue en Producción (Principio 9 de la Constitución)
1. Verificación de 0 errores estáticos con Pyright (`@[current_problems]`).
2. Ejecución completa de la suite de pruebas unitarias (`pytest tests -v`).
3. Bump de versión semántica en `package.json`, `app.js`, `__init__.py`, `setup.py` y `openapi.py`.
4. Registro de cambios en `CHANGELOG.md` y `MEMORY.md`.
5. Ejecución de `git push origin dev` al repositorio remoto.
6. Despliegue en el contenedor de producción LXC `10.0.0.217` (`https://eduspace.oemspot.com.ar`) y verificación de disponibilidad.
+70
View File
@@ -0,0 +1,70 @@
# Especificación: Asistente IA y Chatbot de Ayuda Contextual (SDD-009)
## 1. Contexto y Objetivos del Módulo
La plataforma **Admin Edu Space** coordina el ecosistema académico de UniCABA para múltiples perfiles: personal de Bedelía, docentes y estudiantes. Debido a la amplitud de funciones (gestión de espacios áulicos, sincronización con Moodle 4.1, actas de regularidad, asignación de comisiones y consultas de cursada), los usuarios requieren orientación inmediata y contextualizada sobre cómo operar el sistema según su propio nivel de privilegios y responsabilidades.
Este módulo implementa un **asistente conversacional (chatbot de ayuda contextual)** impulsado por un modelo de lenguaje local (**Llama.cpp** ejecutando `Qwen3 Coder 30B-A3B`) hosteado en la infraestructura institucional (`http://10.0.0.214:8080/v1`).
El agente conversacional actúa como un tutor interactivo cuyas respuestas y contexto están estrictamente acotados al rol del usuario autenticado (`alumno`, `docente`, `bedelia` / `admin`), previniendo la divulgación de capacidades no autorizadas y ofreciendo instrucciones paso a paso directamente aplicables a su flujo de trabajo.
---
## 2. Requisitos Funcionales en Sintaxis EARS
### 2.1 Configuración Global del Proveedor de IA (`/admin/settings`)
- **RF-01 (Ubicuo - Pestaña de Configuración IA en el Panel de Administración)**:
`EL SISTEMA presentará una pestaña dedicada 'Asistente IA & LLM Local' en la vista de Configuración Global (/admin/settings) accesible exclusivamente para administradores.`
- **RF-02 (Basado en Eventos - Persistencia de Parámetros del Motor de IA)**:
`CUANDO el administrador actualice la URL base (default: http://10.0.0.214:8080/v1), la clave API, el identificador del modelo (default: qwen3-coder:30b), la temperatura, el timeout o el estado de activación, EL SISTEMA validará los datos mediante Pydantic v2 y los persistirá de forma segura en la tabla system_settings.`
- **RF-03 (Basado en Eventos - Prueba de Conectividad con el Servidor Local)**:
`CUANDO el administrador presione el botón 'Probar Conexión con Llama.cpp', EL SISTEMA ejecutará una verificación asíncrona contra el endpoint /v1/models o un healthcheck del servidor local, retornando el estado de latencia y disponibilidad en la interfaz.`
- **RF-04 (No Deseado - Degradación Controlada ante Servidor de IA Inaccesible)**:
`SI el servidor de Llama.cpp no responde dentro del tiempo límite o se encuentra fuera de línea, ENTONCES EL SISTEMA capturará la excepción de red y retornará un error HTTP 503 con un mensaje descriptivo en español, sin bloquear el servidor FastAPI ni degradar la experiencia general de la plataforma.`
### 2.2 Backend Core y API REST (`backend/routers/ai_chat.py`)
- **RF-05 (Ubicuo - Validación de Contratos con Pydantic v2)**:
`EL SISTEMA validará las solicitudes al endpoint de chat mediante esquemas Pydantic v2 (ChatRequest, ChatMessage, ChatResponse), exigiendo formato válido de mensajes, longitud mínima de contenido y roles reconocidos, respondiendo con HTTP 422 Unprocessable Entity en caso de discordancia de esquema.`
- **RF-06 (Basado en Eventos - Inferencia Asíncrona no Bloqueante con httpx)**:
`CUANDO un usuario autenticado envíe una consulta al asistente (/api/chat o /api/v1/chat), EL SISTEMA procesará la llamada utilizando httpx.AsyncClient con await no bloqueante y timeout configurable (default: 60s con soporte de hasta 600s), preservando la concurrencia de FastAPI.`
- **RF-07 (Basado en Estados - Inyección Dinámica de System Prompt según Rol)**:
`MIENTRAS el usuario posea un rol específico ('alumno', 'docente', 'bedelia' o 'admin'), EL SISTEMA antepondrá de forma invisible en el payload enviado al LLM el manual de instrucciones y las restricciones de seguridad correspondientes a dicho perfil.`
- **RF-08 (No Deseado - Restricción de Alcance y Prevención de Fuga de Permisos)**:
`SI un usuario con rol 'alumno' indaga sobre funciones administrativas, edición de aulas, modificación de notas o sincronización de Moodle, ENTONCES EL SISTEMA instruirá al LLM a declinar amablemente la respuesta indicando que dicha operación está reservada al personal de Bedelía o Secretaría Académica.`
### 2.3 Interfaz de Usuario y Widget del Chatbot (Frontend BFF & UI)
- **RF-09 (Opcional - Widget Flotante del Asistente en la Interfaz)**:
`DONDE el usuario se encuentre autenticado y la integración de IA esté habilitada, EL SISTEMA desplegará un botón flotante y un panel de chat interactivo en el extremo inferior de la pantalla, con micro-animaciones, soporte de modo oscuro/claro y visor de respuestas con formato legible.`
- **RF-10 (Basado en Eventos - Transmisión de Consulta e Indicador de Carga)**:
`CUANDO el usuario envíe una pregunta mediante el widget de chat, EL SISTEMA mostrará un indicador animado de procesamiento ('El tutor está escribiendo...'), mantendrá el foco del scroll y presentará la respuesta generada por el modelo al finalizar la inferencia.`
---
## 3. Matriz de Prompts de Sistema por Rol (Contextual Guidance)
| Rol del Usuario | Enfoque del Tutor IA | Reglas y Restricciones Específicas |
| :--- | :--- | :--- |
| **Docente** (`docente`, `profesor`, `teacher`) | Asistente de Gestión de Cátedra | Enseña a: consultar asignaciones de aula, registrar asistencia, cargar actas de regularidad en el Gradebook, verificar horarios semanales y enlaces de aulas virtuales (Google Meet). Prohibido: habilitar o explicar cómo crear carreras o reconfigurar servidores. |
| **Alumno** (`alumno`, `estudiante`, `student`) | Asistente de Cursada y Orientación | Enseña a: consultar materias matriculadas, consultar cartelera de clases del día, verificar horarios, identificar aulas asignadas y consultar estado académico. Estrictamente prohibido: detallar procedimientos de Bedelía, administración de espacios o edición de calificaciones. |
| **Bedelía / Admin** (`bedelia`, `admin`, `administrador`) | Soporte Técnico Nivel 1 y Operación Áulica | Enseña a: flujo secuencial de 9 pasos (Sedes -> Aulas -> Ciclos -> Carreras -> Materias -> Comisiones -> Profesores -> Alumnos -> Reservas), resolución de matriz de conflictos físicos/docentes, importación de Google Sheets con previsualización, sincronización con Moodle 4.1 y monitoreo de auditoría. |
---
## 4. Criterios de Aceptación y Validación
1. **Configuración Global**: La pestaña "Asistente IA & LLM Local" en `/admin/settings` debe cargar la configuración actual, permitir su edición y probar conectividad con respuesta en vivo.
2. **Contrato de API**:
- `POST /api/chat/` o `POST /api/v1/chat/` debe validar con Pydantic `ChatRequest` y responder con `ChatResponse`.
- Cargas no válidas deben retornar `422 Unprocessable Entity`.
- Si el servidor local de Llama.cpp no responde, debe retornar `503 Service Unavailable` con mensaje amigable.
3. **Seguridad y Aislamiento por Rol**: Las consultas de un alumno deben recibir respuestas adaptadas al estudiante y rechazar peticiones de gestión áulica.
4. **Widget de UI**: El widget flotante debe integrarse armónicamente en el layout general de la aplicación (`base.html`), respetando temas claro y oscuro (`data-bs-theme`), permitiendo abrir, minimizar y enviar mensajes fluidamente.
5. **Calidad y Robustez**: 100% de la suite de pruebas unitarias/integración aprobadas en pytest y cero errores de diagnóstico en Pyright (`@[current_problems]`).
+70
View File
@@ -0,0 +1,70 @@
# Desglose de Tareas: Asistente IA y Chatbot de Ayuda Contextual (SDD-009)
## Tareas de Implementación
- [x] **Tarea 1: Esquemas Pydantic v2 y Modelos de Contrato para Chatbot y Configuración**
- **Estimación**: 20 min
- **Acciones**:
- Crear `backend/schemas/ai_chat.py` con `ChatMessage`, `ChatRequest`, `ChatResponse`, `AISettingsSchema` y validaciones estrictas (`Field`, `pattern`, `min_length`).
- Validar que los payloads inválidos fallen con 422 Unprocessable Entity.
- **Hecho cuando**: Los modelos validan correctamente los tipos, roles y longitudes, y rechazan payloads sin mensajes o con roles inválidos.
- [x] **Tarea 2: Lógica de Negocio de System Prompts por Rol y Router FastAPI (`backend/routers/ai_chat.py`)**
- **Estimación**: 30 min
- **Acciones**:
- Crear `backend/routers/ai_chat.py` con `APIRouter(prefix="/api/chat", tags=["AI Chatbot"])` y alias `/api/v1/chat`.
- Implementar `generate_system_prompt_for_role(role: str) -> str` con los manuales operativos para:
- `Docente`: Reserva de aulas, actas de regularidad, asistencia, links a Meet.
- `Alumno`: Consulta de horarios, cartelera, notas en Gradebook, prohibición explícita de gestión administrativa.
- `Bedelía / Admin`: Circuito secuencial de 9 pasos, resolución de conflictos, importación de sheets, Moodle 4.1.
- Implementar endpoint `POST /` con `httpx.AsyncClient(timeout=...)` hacia la URL base de Llama.cpp (`http://10.0.0.214:8080/v1/chat/completions`).
- Manejar excepciones de red y timeout mapeando a HTTP 503 controlado.
- Implementar endpoint `POST /test-connection` para probar el servidor local.
- Registrar el router en `backend/main.py`.
- **Hecho cuando**: Los endpoints `/api/chat` y `/api/v1/chat` están documentados en Swagger `/docs` y procesan consultas asíncronas con System Prompt inyectado.
- [x] **Tarea 3: Persistencia y Gestión de Configuración de IA en `backend/routers/admin.py`**
- **Estimación**: 25 min
- **Acciones**:
- Extender `get_all_settings` en `backend/routers/admin.py` para devolver el objeto `ai_assistant` con parámetros de Llama.cpp, modelo (`qwen3-coder:30b`) y API key enmascarada.
- Crear endpoints `@admin_router.post("/settings/ai")` y `@admin_router.post("/settings/ai/test")` que guarden en `SystemSetting` con auditoría en `AuditLog`.
- **Hecho cuando**: La configuración de IA se guarda y se recupera correctamente a través de la API administrativa.
- [x] **Tarea 4: Pestaña de Configuración Global en Frontend (`global_config.html`)**
- **Estimación**: 25 min
- **Acciones**:
- Agregar pestaña `#tab-ai` ("Asistente IA & LLM Local") en `frontend/views/admin/settings/global_config.html`.
- Maquetar formulario con los parámetros definidos en SDD-009: Base URL, API Key, Model ID, Model Name, Context Limit, Output Limit, Timeout, Temperatura y switch de habilitación.
- Implementar manejadores JavaScript en la vista para guardar configuración y ejecutar el botón "Probar Conexión con Llama.cpp" con feedback interactivo.
- **Hecho cuando**: El administrador puede editar los parámetros del LLM y probar la conexión desde `/admin/settings`.
- [x] **Tarea 5: Widget Flotante del Chatbot en la UI (`ai_chat_widget.html` & `ai-chat-widget.js`)**
- **Estimación**: 30 min
- **Acciones**:
- Crear `frontend/views/partials/ai_chat_widget.html` e incluirlo en `frontend/views/base.html` para usuarios autenticados.
- Diseñar interfaz flotante premium con Bootstrap 5 y Vanilla CSS (botón lanzador con animación sutil, ventana de chat responsiva, badge de rol de usuario, avatar institucional, indicador de tipeo y lista de mensajes).
- Desarrollar `frontend/public/js/ai-chat-widget.js` para enviar mensajes por AJAX a `/api/v1/chat/`, manejar scroll, formatear respuestas y persistir temporalmente la sesión en `sessionStorage`.
- **Hecho cuando**: El usuario puede interactuar con el chatbot desde cualquier pantalla del sistema, recibiendo respuestas contextualizadas a su rol.
- [x] **Tarea 6: Suite de Pruebas Automatizadas en Backend (`test_ai_chat.py`)**
- **Estimación**: 25 min
- **Acciones**:
- Crear `backend/tests/test_ai_chat.py` con tests para:
- Validación de esquemas Pydantic `ChatRequest`, `ChatMessage`, `ChatResponse`.
- Inyección correcta de system prompt según rol (alumno, docente, bedelia).
- Mocking de `httpx.AsyncClient` para simular respuesta 200 de Llama.cpp.
- Mocking de falla de conexión para verificar HTTP 503 descriptivo.
- Endpoints de guardado y consulta de configuración de IA.
- Ejecutar `pytest tests -v` y validar 100% verde (89 tests pasando).
- Verificar con `py_compile` (Principio 10) que haya 0 errores o advertencias.
- **Hecho cuando**: Todas las pruebas unitarias e integradas pasan con éxito y no hay problemas en el analizador de código.
- [x] **Tarea 7: Bump Semántico a v3.8.24, Git Push y Despliegue en Producción**
- **Estimación**: 20 min
- **Acciones**:
- Incrementar versión semántica a `v3.8.24` en `package.json`, `app.js`, `__init__.py`, `setup.py` y `openapi.py`.
- Actualizar `CHANGELOG.md` y `MEMORY.md`.
- Ejecutar `git add .`, commit y `git push origin dev`.
- Desplegar en el contenedor de producción LXC `10.0.0.217` (`https://eduspace.oemspot.com.ar`) y verificar HTTP 200 en `/version` y `/admin/settings`.
- **Hecho cuando**: La versión `v3.8.24` está activa en producción y verificada en caliente.