6.5 KiB
6.5 KiB
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.pyChatMessage(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 = Truebase_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_settingsusandoSystemSetting: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 enmain.pybajo/api/chaty/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.RequestErroro respuestas no 2xx y levantaHTTPException(status_code=503, detail="Error conectando al motor de IA local."). - Retorna
ChatResponse(response=ai_data["choices"][0]["message"]["content"]).
- Extrae rol del usuario (priorizando usuario autenticado en JWT si está presente, o
- Endpoint
POST /test-connection:- Verifica conectividad directa con
{base_url}/modelsusando el clientehttpx.AsyncClient.
- Verifica conectividad directa con
backend/routers/admin.py:- Actualizar
get_all_settingspara retornar el bloqueai_assistantcon valores activos y clave API enmascarada. - Endpoints
@admin_router.post("/settings/ai")y@admin_router.post("/settings/ai/test").
- Actualizar
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 iconobi 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).
- Pestaña
- Widget de Chatbot Flotante (
frontend/views/partials/ai_chat_widget.htmle inyección enbase.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 ensessionStoragey detecta el rol actual del usuario desde la sesión.
2. Plan de Pruebas Automatizadas
- Pruebas de Backend (
backend/tests/test_ai_chat.py):- Validación de contratos con Pydantic: prueba de
ChatRequestválido, rechazo con 422 ante payload malformado o contenido vacío. - Generación de System Prompt: verificación de directivas específicas para
alumno,docenteybedelia. - Simulación de respuesta exitosa de Llama.cpp (Mock de
httpx.AsyncClient) verificando código 200 y formatoChatResponse. - 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.pypara guardar y consultar configuración de IA.
- Validación de contratos con Pydantic: prueba de
- 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.htmlsin interferir con otros elementos de la UI ni romper el layout en modo oscuro o móvil.
- Verificación de renderizado de la pestaña de IA en
3. Plan de Despliegue en Producción (Principio 9 de la Constitución)
- Verificación de 0 errores estáticos con Pyright (
@[current_problems]). - Ejecución completa de la suite de pruebas unitarias (
pytest tests -v). - Bump de versión semántica en
package.json,app.js,__init__.py,setup.pyyopenapi.py. - Registro de cambios en
CHANGELOG.mdyMEMORY.md. - Ejecución de
git push origin deval repositorio remoto. - Despliegue en el contenedor de producción LXC
10.0.0.217(https://eduspace.oemspot.com.ar) y verificación de disponibilidad.