Saltearse al contenido
ColabEdu.org ALPHA

Batch YAML — Referencia

Curator Batch YAML Pipeline as Code

Los ficheros batch YAML del Curator permiten definir pipelines de ingesta de contenido pedagógico de forma completamente declarativa. Se almacenan en ce-specs/batches/ y se ejecutan con el comando spec batch run.

Un batch puede encadenar cualquier subconjunto de las etapas del pipeline en el orden que necesites: desde el descubrimiento automático de fuentes hasta la ingesta final en el catálogo OAS.

Schema Completo

# ══════════════════════════════════════════════════════════════════════
# Curator Batch Definition — Schema v1
# Ruta: ce-specs/batches/{nombre}.yaml
# ══════════════════════════════════════════════════════════════════════


# ── Metadatos del batch ───────────────────────────────────────────────
batch:
  id:          string   # Identificador único (slug kebab-case)
  name:        string   # Nombre legible del operador
  description: string   # Descripción pedagógica del contenido a ingestar


# ── Contexto curricular ───────────────────────────────────────────────
context:
  standard:      string   # Clave del estándar: AP | LOMLOE | IB | EBAU | COMMON_CORE
  country:       string   # ISO-3166-1 alpha-2: US | ES | MX | GB
  locale:        string   # Idioma: es | en | fr
  subject:       string   # Slug de asignatura: spanish_language_and_culture | lcl | biology
  level:         string   # Nivel educativo: "9-12" | "2 BACH" | "HL" | "SL"
  authority:     string   # Autoridad educativa (opcional): "Comunidad de Madrid"
  program:       string   # Programa específico (opcional): "AP Spanish Language"
  referenceCode: string   # Código base OAS para las specs generadas


# ── Etapas a ejecutar (en orden) ─────────────────────────────────────
operations:
  - taxonomy    # Asegurar nodos de taxonomía en el backend
  - discover    # Descubrir URLs de fuentes documentales
  - fetch       # Descargar documentos al staging local
  - parse       # Extraer specs YAML vía AI (Curator)
  - approval    # Esperar revisión humana (HITL)
  - ingest      # Ingestar specs aprobadas en el catálogo OAS


# ── Configuración por etapa (solo incluir las etapas usadas) ──────────


taxonomy:
  nodes:        # Lista de nodos de taxonomía a asegurar
    - standard: string
      level:    string
      subject:  string


discover:
  types:       [string]   # exams | standards | open_books
  keywords:    [string]   # Términos de búsqueda
  sources:     [string]   # Dominios fuente: educacion.gob.es, collegeboard.org…
  maxResults:  integer    # Límite de resultados


fetch:
  stagingDir:         string    # Directorio local de descarga
  parallelDownloads:  integer   # Descargas paralelas (default: 1)
  urls:               [string]  # URLs estáticas (si se omite DISCOVER)


parse:
  specTypes:  [string]   # C0_STANDARDS | C1_RECIPES | C2_EXERCISES | BLOCK_RUBRIC
  sections:   [string]   # Secciones del documento a procesar (vacío = documento completo)
  filePaths:  [string]   # Rutas de ficheros locales (si se omite FETCH)


approval:
  timeoutHours:  integer   # Horas antes de cancelar la espera (default: 48)
  autoApprove:   boolean   # true = aprobar automáticamente sin revisión humana


ingest:
  targetRepo:  string    # Repositorio destino (siempre: "ce-specs")
  branch:      string    # Rama GitOps: batch/{batch-id}
  specsDir:    [string]  # Directorios locales con YAMLs listos para ingestar

Etapas del pipeline

EtapaDescripciónEndpoint REST
taxonomyAsegura que los nodos de taxonomía (standard → level → subject) existen en el backend antes de procesar contenidoPOST /api/v1/curator/taxonomy/ensure
discoverBusca en fuentes educativas (portales de exámenes, repositorios OER) y construye una lista de URLs de documentosPOST /api/v1/curator/discover
fetchDescarga los documentos descubiertos a un directorio local de staging con progresoPOST /api/v1/curator/fetch
parseEnvía los documentos al servicio Curator AI para extracción de specs OAS vía multimodalPOST /api/v1/curator/parse
approvalBloquea el pipeline hasta que un humano aprueba las specs en la UI de aprobaciónPOST /api/v1/curator/approval/submit + polling
ingestEmpuja las specs aprobadas al spec-manager vía la API de ingesta OASPOST /api/v1/curator/ingest

Ejemplos reales

batch_02_ap_slc_frq_2024.yaml
batch:
  id: batch-02-ap-slc-frq-2024
  name: "Batch 02 — AP Spanish Language FRQ 2024"
  description: >
    AP Spanish Language and Culture — Free-Response Questions 2024.
    Secciones: Task 1 (Email), Task 2 (Ensayo), Task 3 (Conversación),
    Task 4 (Presentación oral/escrita).


context:
  standard: AP
  country: US
  locale: es
  subject: spanish_language_and_culture
  level: HL
  referenceCode: us.ap.spanish_language_and_culture.ap_spanish_language_2024_frq.v1


operations: [parse, ingest]


parse:
  filePaths:
    - "/ruta/a/ce-specs/sources/us/ap/c2_exams/ap_spanish_language_2024_frq.pdf"
  specTypes: [C0_STANDARDS, C2_EXERCISES]
  sections:
    - "Task 1"
    - "Task 2"
    - "Task 3"
    - "Task 4"


ingest:
  targetRepo: ce-specs
  branch: batch/batch-02-ap-slc-frq-2024

Comandos CLI

Ventana de terminal
# Ejecutar un batch
./ce-cli.sh --env local "spec batch run --batch ce-specs/batches/batch_02_ap_slc_frq_2024.yaml"


# Dry-run: ver el plan de ejecución sin correr nada
./ce-cli.sh --env local "spec batch run --batch mi_batch.yaml --dry-run"


# Reanudar desde una etapa específica (tras un fallo)
./ce-cli.sh --env local "spec batch run --batch mi_batch.yaml --from parse"


# Ver estado del último batch ejecutado
./ce-cli.sh --env local "spec batch status"


# Generar un batch YAML con IA desde una descripción en lenguaje natural
./ce-cli.sh --env local \
  "spec batch generate 'exámenes EBAU de lengua castellana Madrid 2024 y 2025' --out mi_batch.yaml"

Flags disponibles

FlagAliasDescripción
--batch <file>-bRuta al fichero YAML de batch
--from <stage>-fReanudar desde la etapa indicada: taxonomy|discover|fetch|parse|approval|ingest
--dry-run-dMuestra el plan de ejecución sin ejecutar nada

Checkpoint y recuperación

El CLI persiste el estado del batch en .ce-batch-state.json en el directorio de trabajo. Si el pipeline falla en cualquier etapa, puedes reanudarlo desde donde se quedó:

Ventana de terminal
# Ver el checkpoint actual
cat .ce-batch-state.json


# Reanudar desde parse (tras corregir el error)
./ce-cli.sh --env local "spec batch run --batch mi_batch.yaml --from parse"

El state file guarda:

  • batchId, status (RUNNING | COMPLETED | FAILED | PAUSED)
  • discoveredUrls[], fetchedFiles[], parsedSpecs[]
  • approvalWorkflowIds[], ingestedReferenceCodes[]
  • log[] con el historial de ejecución

Tipos de spec válidos (specTypes)

ValorCapa OASDescripción
C0_STANDARDSC0Estándares normativos ingestados desde documentos oficiales
BLOCK_RUBRICC0Rúbricas de evaluación inmutables
C1_RECIPESC1Recetas pedagógicas ensambladas
C2_EXERCISESC2Ejercicios con contexto
INTERACTIVE_LESSONC2Lecciones interactivas con slides
RESOURCE_LEARNINGC2Punteros OER anotados

Dónde viven los ficheros

ce-specs/
└── batches/
    ├── batch_01_ap_slc_frq_2023.yaml
    ├── batch_02_ap_slc_frq_2024.yaml
    ├── batch_03_ap_slit_frq_2024.yaml
    ├── batch_04_ap_slc_scoring_guide.yaml
    ├── batch_06_ebau_madrid_2024_25.yaml
    ├── batch_10_rubricas_lcl_nacional.yaml
    ├── discover_spanish_california.yaml
    └── ...

Ver También

🌍 Built in California & Spain
San Jose | Madrid | Ciudad de México