Tutor IA: pipeline multi-agente

Pipeline detallado

Pre-LLM (síncrono, costo LLM cero)

1. StudentModelService.getSnapshot(userId, courseId)

   • Carga ConceptMastery (distribución Beta por concepto)
   • Carga misconceptions activas/resolving (con evidence trail)
   • Carga EpisodicMemory (qué funcionó antes)
   • Carga quizContext (avgScore, passRate, totalAttempts, weakAreas)
   • Carga historial de ChatSession (sliding window 10 msgs)

2. RetrievalAgent.retrieve(query, studentModel)

   • Reformula la query usando contexto (sustituye "esto", "aquello" por conceptos actuales)
   • Búsqueda pgvector con filtros (tenantId, courseId)
   • Boost por áreas débiles en quizzes (quizWeakAreas del studentModel)
   • Top-K con reranking semántico

3. PedagogicalAgent.select(studentModel, query)

   • Evalúa mastery promedio + dominio específico de la query
   • Aplica ajustes (chat-quiz divergence, edad, estilo de aprendizaje)
   • Retorna estrategia + adición al system prompt

4. buildEnrichedPrompt(query, studentModel, ragChunks, strategy, misconceptions)

   • Construye el system prompt con:
     • Estrategia pedagógica seleccionada
     • Contexto RAG (top-5 chunks con atribución de fuente)
     • Misconceptions activas (con instrucciones para abordarlas)
     • Intentos de quiz recientes (memoria inter-turno)
     • Contexto de inline quiz trigger (si hubo un quiz reciente)

LLM principal (streaming, SSE)

router.stream(taskType: "chat_tutor", messages, options) resuelve el proveedor mediante TenantTaskModelConfig:

• Claude (primary) → OpenAI → xAI Grok → Google Gemini (cadena de fallback)
• Circuit breaker por proveedor (estado en Redis)
• Middleware de metering: rate limit + verificación de créditos + calculadora de costos
• Streaming mediante Server-Sent Events al cliente

El LLM puede emitir tool calls especiales:

• [INLINE_QUIZ]{...}[/INLINE_QUIZ] — quiz interactivo renderizado en el chat
• present_quiz tool call — formato Vercel AI SDK

Post-LLM (en segundo plano mediante after(), fire-and-forget)

5. EvaluationAgent.evaluate(turn, studentModel) — Haiku, ~$0.001

   • Clasifica la comprensión: correct | partial | incorrect | unclear
   • Detecta StudentMisconception con:
     • source: "chat"
     • sourceSessionId
     • contextSnippet (máx. 500 chars)
     • concepts[] (mapeado a ConceptMastery)
   • Actualiza ConceptMastery (actualización bayesiana mediante beta(alpha+success, beta+failure))
   • Llama a MisconceptionResolutionService.checkAndTransition (state machine)

6. ContentAgent.preGenerate(studentModel, conceptId) — Haiku, ~$0.001

   • Genera ejercicio de follow-up basado en conceptos débiles
   • Almacena en Redis (TTL 30min) para servir en el próximo turno
   • Reduce la latencia percibida por el alumno

7. SessionSummarizer (cada 10 turnos) — Haiku, ~$0.001

   • Resume el historial largo
   • Sustituye mensajes antiguos en el sliding window
   • Preserva los insights pedagógicos relevantes

8. SupervisorAgent.run(turn, courseContext) — Haiku, ~$0.001

   • Clasifica severity (5 niveles) + category (8 tipos)
   • Crea AiSupervisorIncident si severity != "none"
   • Aplica strikes / quarantine / safety cooldown según las reglas

Configuración por administrador

TenantTaskModelConfig

El administrador elige proveedor+modelo por tipo de tarea:

chat_tutor          → Claude Sonnet 4.6 (o GPT-4o, o Grok-3, etc)
chat_evaluation     → Claude Haiku
chat_summarization  → Claude Haiku
chat_supervisor     → Claude Haiku
content_generation  → Claude Haiku
course_review       → Claude Sonnet
gamification_agent  → Claude Sonnet
course_agent        → Claude Sonnet

PedagogicalConfig

Configurabilidad pedagógica por tenant:

• masteryThresholds: umbrales para cambiar estrategia (default 0.3, 0.5, 0.7, 0.9)
• domainOverrides: ajuste por dominio (ej.: matemáticas usa scaffolding más agresivo)
• ageOverrides: ajuste por franja etaria (niño = direct_instruction más frecuente)
• learningStyleOverrides: visual, auditivo, kinestésico

Personalización de plantillas de prompt

El administrador institucional puede editar el system prompt del tutor mediante PromptTemplate (en la base de datos):

• Por taskType (chat_tutor)
• Por proveedor (Anthropic, OpenAI, Google, xAI — variantes optimizadas)
• Por locale (pt-BR, en-US, es-ES, fr-FR)
• Por tenant (o null = global)
• Por curso (override por curso)

Limitaciones técnicas

• Latencia first-token: 800-1500ms (incluyendo el pipeline pre-LLM)
• Latencia total del turno: 2-8s para una respuesta promedio (~300 palabras)
• Context window: limitado por el proveedor (Claude Sonnet 4.6 = 200K, GPT-4o = 128K)
• Idiomas: el tutor responde en el idioma del alumno pero internamente el pipeline es bilingüe (en/pt)
• Imágenes: el tutor acepta imágenes en el input (multimodal Claude/GPT/Gemini) pero RAG es solo texto
• Avatar parlante + voz (salida): disponible como opt-in por curso — avatar parlante en tiempo real con voz TTS mediante HeyGen LiveAvatar o D-ID (BYO key). Ver Avatar & TTS.
• Voz de entrada (STT): hablar con el tutor (voz del alumno → speech-to-text → chat) ya está implementado en B2B (dictado: el habla se convierte en texto en el campo de mensaje, sin autoenvío). Lo que sigue en el roadmap es la conversación bidireccional por voz (bucle con el avatar en tiempo real) y la nota automática de pronunciación.

Ver también

• Tutor IA: visión ejecutiva
• Avatar & TTS
• RAG Ingestion
• Agente Supervisor