Saltar a contenido

Documento de Contexto Maestro: Tutor Socrático IMB

Gobernanza y Autoridad: Este documento es el nodo raíz (MASTER-00) del grafo de especificaciones del proyecto Tutor Socrático IMB. Define la identidad, objetivos de negocio, arquitectura de alto nivel, restricciones no negociables y lineamientos de gobernanza para todo el ciclo de vida del sistema.

1. Identidad del Proyecto y Propósito

  • Nombre del Sistema: Tutor Socrático IMB
  • Cliente / Organización: IMB Institute (International Management and Business Institute S.A.C. — RUC 20614051320, Perú).
  • Tipo de Solución: Asistente conversacional socrático embebido para capacitación corporativa B2B.
  • Alcance Operativo: Sistema interno exclusivo (single-tenant para IMB Institute; no es un SaaS comercial).
  • Plataforma del Piloto (MVP 0): 1 curso de certificación activo, cohorte de ~100 participantes profesionales, frontend Flutter Web responsive embebible, autenticación propia mediante JWT emitida por backend FastAPI.
  • Visión a Largo Plazo (Fase M04+): Integración nativa con LMS Moodle (formacion.imbinstitute.com) vía LTI/API y soporte multiplataforma para aplicación móvil nativa.

2. Problema de Negocio y Justificación

ID Problema Identificado Impacto Medido / Justificación
P01 Instructores no pueden brindar soporte 24/7 a profesionales en activo. ~12 horas semanales por docente en consultas repetitivas fuera de horario no facturables.
P02 Estudiantes recurren a ChatGPT/Claude, obteniendo respuestas directas que evitan el razonamiento. Pérdida del valor formativo y pedagógico diferencial del método interactivo de IMB.
P03 Falta de visibilidad sobre los conceptos con mayor fricción y el progreso real. Dificultad para las áreas de RR.HH. y docentes de medir la asimilación conceptual y el ROI de capacitación.
P04 Bloqueos cognitivos fuera de horario provocan frustración y deserción. Caída en la tasa de finalización de cursos por falta de asistencia inmediata contextualizada al material.

3. Actores del Sistema

  1. Estudiante Corporativo: Profesional en activo que interactúa con el tutor para resolver dudas, realizar sesiones socráticas de práctica guiada o solicitar ayuda directa sobre su curso.
  2. Instructor / Docente: Experto de IMB que gestiona el curso, revisa métricas agregadas de fricción conceptual y valida la calidad del material cargado.
  3. Administrador de Sistemas (IMB): Gestiona índices RAG, versionado de prompts, feature flags, auditoría y control de consumo de tokens.
  4. Sistema LMS Moodle: Aula virtual corporativa (integración planificada post-MVP; en MVP 0 el acceso se gestiona de forma autónoma con credenciales locales).

4. Pilares Pedagógicos y Modos de Interacción

A. Modos de Interacción del Tutor

flowchart TD
    Inicio[Estudiante ingresa al Tutor] --> Selector{Selección de Modo}
    Selector -->|Modo Práctica| Socratica[Sesión Socrática Guiada: 6–8 turnos de preguntas reflexivas]
    Selector -->|Modo Consulta| AyudaDirecta[Ayuda Directa Adaptable: respuesta y explicación inmediata]
    Socratica --> Evaluacion[Progreso Conceptual: Explorando → En Progreso → Dominado]
    AyudaDirecta --> Resolucion[Desbloqueo Conceptual Inmediato]
  1. Modo Práctica Socrática (Aprendizaje Guiado):
  2. Diálogo progresivo de 6 a 8 turnos.
  3. El tutor realiza preguntas que guían al estudiante a descubrir la respuesta por sí mismo.
  4. Escalamiento de soporte: Pistas Nivel 1 (orientación conceptual) y Validación Nivel 2 (evaluación de razonamiento).

  5. Regla Innegociable: NUNCA entregar la respuesta final directa durante este modo.

  6. Modo Ayuda Directa Adaptable (Desbloqueo Inmediato):

  7. Orientado a dudas puntuales de conceptos no comprendidos.
  8. Proporciona una explicación concisa y pedagógica basada exclusivamente en los materiales indexados del curso.

5. Reglas de Oro Arquitectónicas (Innegociables)

  1. Control Pedagógico Socrático: El pipeline de generación bloquea activamente cualquier intento de bypass o prompt injection que solicite soluciones directas en modo socrático.
  2. Aislamiento Multi-Curso Estricto (curso_id obligatorio): Toda consulta vectorial, recuperación RAG, sesión conversacional y métrica debe incluir y filtrar obligatoriamente por el curso_id extraído del token JWT autenticado.
  3. Presupuesto y Control OPEX:
  4. Límite estricto de 50,000 tokens diarios por usuario (input + output), gestionado en tiempo real en Redis.
  5. Costo operativo objetivo: ≤ S/ 10.00 por usuario/mes.
  6. Activación automática de mecanismos de mitigación (Plan B / Rate Limiting estricto) ante consumos anómalos (>80% del budget diario).
  7. Contrato de API Único: docs/api/openapi.yaml es la única fuente de verdad técnica de la API. Las especificaciones BE-XX y FE-XX referencian operationId sin duplicar contratos.
  8. Bus de Eventos Asíncrono Resiliente: Se implementa el patrón Transactional Outbox sobre PostgreSQL + cola en Redis y despacho desacoplado por worker cron. Prohibido el uso de buses volátiles en memoria para eventos de dominio.
  9. Privacidad y Protección de Datos (PII): Los datos personales se anonimizan y enmascaran en el servidor antes de invocar a los modelos LLM. Los registros de auditoría y logs se almacenan pseudonimizados.
  10. Versionado de Prompts como Código: Todo prompt del sistema se versiona en el directorio /prompts/ con metadata YAML y estructura XML delimitada para maximizar el prompt caching de Gemini.

6. Stack Tecnológico Fijado (Línea Base 2026)

# Backend & Persistencia
python = "3.13.14"
fastapi = "0.141.1"
sqlalchemy = "2.0.51"
alembic = "1.19.1"
postgresql = "16.x"
pgvector = "0.5.0"            # Búsqueda vectorial HNSW (strict_order)
redis = "5.x"                 # Cache semántico, rate limiting y cola outbox
pydantic = "2.13.4"
opentelemetry-sdk = "1.44.0"

# Modelos de Inteligencia Artificial (SDK google-genai 2.17.x)
llm_default = "gemini-3.6-flash"         # Producción / Generación conversacional
llm_reasoning = "gemini-2.5-pro"         # Evaluación compleja y LLM-as-a-Judge
embeddings = "gemini-embedding-001"      # Vectorización semántica (768 dimensiones)

# Frontend Multiplataforma
flutter = "3.47.0"            # Web para MVP 0; Android/iOS en Fase M04
dart = "3.13.0"
riverpod = "3.4.x"            # Gestión de estado reactivo
dio = "5.11.x"                # Cliente HTTP con interceptores de auth y correlación

7. Arquitectura de Bounded Contexts (Clean Architecture + DDD)

El sistema se estructura en un Monolito Modular estructurado en capas (Domain, Application, Infrastructure, Adapters):

src/
├── conversation/       # Bounded Context: Ciclo de vida de sesiones socráticas, mensajes y progreso
├── knowledge/          # Bounded Context: Ingesta de materiales, indexación y recuperación RAG
├── identity/           # Bounded Context: Autenticación, roles, emisión y validación de JWT
├── administration/     # Bounded Context: Gestión de prompts, feature flags y logs de auditoría
├── monitoring/         # Bounded Context: Métricas de observabilidad, telemetría y OpenTelemetry
└── shared/             # Kernel compartido: Value objects, utilidades de fecha y jerarquía de excepciones

8. Gobernanza Documental y Grafo de Trazabilidad (DocuGraph)

El proyecto sigue una metodología de documentación atómica estructurada en DAG (Grafo Acíclico Dirigido) gestionada y validada mediante DocuGraph:

Nivel / Fase Documento / Identificador Rol en el Grafo
Fase 0 (Raíz) MASTER-00 (docs/00_MASTER_CONTEXT.md) Raíz del DAG: Contexto maestro, reglas de oro y decisiones transversales.
Fase 1 (Negocio) VISION-00 (docs/00_BUSINESS_VISION.md) Visión de negocio, actores y justificación de retorno de inversión.
Fase 1 (Historias) US-01 .. US-04 (docs/user_stories/) Historias de usuario atómicas con criterios de aceptación de negocio.
Fase 2 (Alcance) SPEC-02 (docs/02_GLOBAL_SPEC.md) Alcance formal, exclusiones explícitas y criterios Go / No Go.
Fase 2 (Arquitectura) ARCH-03 (docs/03_ARCHITECTURE.md) Definición de servicios, despliegue físico y límites de bounded contexts.
Fase 2.5 (UX/UI) IX-01 .. IX-03 (docs/interaction/) Especificaciones de interacción, flujos de pantalla y transiciones.
Fase 3 (Contratos) openapi.yaml (docs/api/) Contrato OpenAPI único y formal de endpoints.
Fase 3 (Backend) BE-01 .. BE-10 (docs/backend/) Especificaciones atómicas de backend por operationId.
Fase 3 (Frontend) FE-01 .. FE-04 (docs/frontend/) Especificaciones atómicas de componentes y flujos de UI en Flutter.
Fase 3 (Dominio) SCHEMA-01, GLOSSARY-01 (docs/domain/) DDL relacional, índices vectoriales y glosario terminológico.
Backlog & Estado MANIFEST-01 (docs/01_PROJECT_MANIFEST.md) Registro vivo del estado de tareas e iteraciones.

9. Criterios de Calidad y Puertas de Aprobación (Gates)

  • Gate 0 (Arquitectura y Especificación): Trazabilidad 100% validada en DocuGraph (validate_traceability sin errores de asimetría o enlaces rotos).
  • Gate 1 (Implementación Backend): Cobertura de pruebas unitarias y de integración pytest ≥ 80% en la capa de dominio, cumplimiento estricto de tipos con mypy y estilo limpio con ruff.
  • Gate 2 (Pedagógico y Seguridad): Calificación ≥ 90% en el benchmark adversarial de control pedagógico ejecutado con LLM-as-a-Judge en staging.
  • Gate 3 (Frontend & UX): Aplicación Flutter Web responsive validada en breakpoints M3 (<600px, 600–840px, ≥840px), con feedback flotante accesible (WCAG 2.1 AA) y targets táctiles ≥ 56×56 px.