Files

5.4 KiB

Desglose de Tareas: Asistente IA y Chatbot de Ayuda Contextual (SDD-009)

Tareas de Implementación

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