Files
admin-edu-space/specs/009-asistente-ia-chatbot/plan.md
T

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