Diseno asistido por IA del esquema de curso

Estado: decisiones arquitectonicas cerradas. Este documento cubre el flujo de creacion de cursos con asistencia de IA: como el admin construye un esquema antes de que exista nada en base de datos, y por que cada pieza esta donde esta.

Complementa a v2-dynamic-courses.md (que cubre el ciclo completo design-time/runtime) y a content-generation.md (pipeline v1). Donde este documento contradice al otro, gana el mas reciente para la fase de diseno; el runtime no se toca aqui.

Depende de: v2-dynamic-courses.md, architecture.md, llm-integration.md.

1. Endpoints de IA sin estado para el diseno

La fase de diseno usa endpoints de IA sin estado. El frontend es el espacio de trabajo: todo el estado vive en React (useState) hasta que el admin confirma. Los endpoints del backend reciben el contexto completo y devuelven resultados sin persistir nada.

1.1 Superficie actual

1.2 Superficie prevista (backlog)

1.3 Patron

Cada endpoint es independiente y testeable en aislamiento. No hay sesiones compartidas ni estado del lado del servidor entre llamadas. El contexto se envia en cada peticion: un esquema son 5-15 nodos, unos pocos KB, un payload trivial.

1.4 Por que sin estado

Ventajas del enfoque elegido:

• Sin datos huerfanos. Una sesion de diseno abandonada no deja rastro en el servidor.
• Resiliente. Un recarga del navegador pierde solo el borrador local, no una sesion de servidor. El admin puede copiar su borrador antes de cerrar si quiere (es JSON plano en React state).
• Extensible. Cada nueva funcionalidad de IA es un endpoint nuevo, sin acoplamiento a una entidad “workspace”. Anadir POST /ai/schema-refine no toca ningun endpoint existente.
• Sin infraestructura extra. No necesita Redis, ni tablas de sesiones, ni cron de limpieza.

2. El curso se crea solo al confirmar

El curso no se crea en base de datos cuando el admin empieza a disenar. Se crea solo cuando el admin acepta el esquema y pulsa “Crear”. En ese momento:

POST /courses                        → crea el curso (titulo, descripcion, delivery_mode)
PUT  /courses/{id}/schema            → escribe los nodos del esquema
POST /courses/{id}/schema/validate   → gate bloqueante (si el admin valida en el acto)

2.1 Consecuencias

• La tabla courses solo contiene cursos reales, nunca borradores.
• No hacen falta jobs de limpieza de borradores abandonados.
• La lista de “Contenido” del panel de admin refleja exactamente lo que existe.
• El flujo de la SPA es una transicion limpia: React state → POST → la entidad existe.

2.2 Contraste con v1

En v1, el curso se crea primero y despues se genera el contenido (POST /courses/{id}/generate). La diferencia es que en v1 el admin no puede disenar nada antes de crear: el curso es un contenedor vacio hasta que el pipeline termina. En el flujo nuevo, toda la fase creativa ocurre antes de que el curso exista.

3. Enrutamiento multi-modelo para tareas de diseno

Distintas tareas de IA en la fase de diseno pueden usar modelos distintos. La infraestructura de resolve_llm_config(org_settings, purpose=...) ya soporta seleccion por proposito.

3.1 Asignacion actual

La propuesta de esquema solo genera estructura: titulos, resumenes, prerrequisitos. No genera contenido de aprendizaje. Eso la hace viable para modelos rapidos y baratos.

3.2 Asignacion prevista (backlog)

El router no necesita cambios: anadir un purpose nuevo es declararlo en la configuracion de la organizacion y pasarlo a resolve_llm_config.

4. Editor interactivo en tiempo real

El editor de esquema separa dos tipos de operaciones por su latencia:

4.1 Operaciones locales (instantaneas, sin IA)

• Editar titulo o resumen de un nodo.
• Borrar un nodo.
• Reordenar nodos (drag & drop).
• Anadir un nodo manualmente.
• Cambiar prerrequisitos.

Estas operaciones mutan el estado de React directamente. No generan llamadas al servidor.

4.2 Operaciones de IA (rapidas, 2-5 s)

• Propuesta inicial a partir de un tema.
• Re-propuesta al cambiar la densidad (intent_density).
• Sugerencia de nodo nuevo (backlog).
• Autocompletado de campos (backlog).

Patron en la UI:

1. El admin acciona (clic, slider).
2. Indicador de carga sutil (nunca modal bloqueante, nunca spinner de pagina completa).
3. La UI sigue siendo interactiva — el admin puede editar otros nodos mientras la IA trabaja.
4. El resultado aparece inline, como el clic-para-explicar (Curio) del runtime: clic → llamada rapida → el resultado aparece en el sitio.

5. Flujo unificado para cursos desde documento y desde tema

Ambos caminos convergen en la misma propuesta de esquema:

Desde documento:                        Desde tema:
  subir PDF                               titulo + descripcion
    → parse a Markdown                       |
    → extraer temas                          → extraer temas
        |                                        |
        └──────────────┬─────────────────────────┘
                       ▼
              proponer esquema (misma llamada)
                       ▼
              editor de esquema (misma UI)

5.1 Diferencias

5.2 Invariante

El endpoint de propuesta de esquema trabaja a partir de temas extraidos, no de documentos crudos. La extraccion de temas es un paso previo (ya implementado en build_schema_graph() como el nodo extract_themes_schema). El documento original, si existe, se usa mas adelante para RAG cuando se genera contenido de nodo en runtime.

6. Backlog: fine-tuning para cursos grandes

Para organizaciones con grandes bases documentales o necesidades de dominio especificas. Nada de esto esta implementado ni planificado a corto plazo.

Prerequisito comun: volumen de datos suficiente. Una organizacion con 5 cursos no tiene datos para fine-tuning. Esto es relevante cuando haya decenas de organizaciones con cientos de cursos validados.