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.