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.
|
||||
Reference in New Issue
Block a user