# 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.