feat: integración de Asistente IA contextual con Llama.cpp Qwen3 Coder 30B (SDD-009, v3.8.24)
This commit is contained in:
@@ -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.
|
||||
@@ -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]`).
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user