Format du bundle de leçon

Une leçon Studium est un fichier JSON, lesson.json, en général rangé dans son propre dossier avec les médias qu'il cite. Toutes les surfaces (serveur MCP, panneau VS Code, serveurs HTTP, tableau de bord enseignant) lisent ce même format. Cette page le décrit champ par champ ; les tables sont générées à partir des schémas Zod de packages/lesson-bundle-schema, qui font foi, et restent en anglais. Un miroir Pydantic pour les services Python se trouve dans packages/lesson-bundle-schema/python/.

Pour écrire une leçon, partez de Écrire une leçon ou laissez un assistant la construire avec les outils d'auteur. Ce que chaque type de scène demande à l'apprenant est expliqué dans Types de scènes.

Un bundle sur disque

mon-cours/
  lesson.json      le bundle (ce format)
  approval.json    écrit par `experience_packet.py approve`, lié aux octets exacts de lesson.json
  media/...        fichiers cités par render_assets ou image_path, relatifs au dossier

Un bundle_ref (l'argument de start_lesson_session) est un chemin relatif au dossier des leçons : un lesson.json, son dossier ou un bundle .zip. Les leçons construites par un assistant arrivent dans la bibliothèque de l'apprenant, <STUDIUM_HOME>/library (voir Configuration). Exemples complets : fixtures/capsule-run-demo/lesson.json (deux scènes) et fixtures/atomistique-l1/lesson.json (un cours entier).

Vérifier un bundle

# Schéma : code 0 et « OK <fichier>: N scenes » quand le fichier est valide
node_modules/.pnpm/node_modules/.bin/tsx tools/bundle_validate.ts chemin/vers/lesson.json

# Relecture pédagogique : les ERROR font échouer, les WARN et INFO non
node tools/bundle_lint.mjs chemin/vers/lesson.json

Le linter va au-delà du schéma : un quiz a exactement un choix correct, un gabarit TODO non rempli est une erreur, les relations du graphe et les types de supports doivent être connus, et les bundles d'autoformation reçoivent des constats sur l'auteur de la clé. Les deux commandes sont décrites dans la référence des commandes.

Qui l'a écrit, et qui l'a vérifié

metadata.authoring indique à chaque surface comment présenter la leçon honnêtement :

Champ Valeurs Sens
mode teacher, self_study Une leçon d'enseignant, ou une leçon que l'apprenant (ou son assistant) a faite à partir de références de son choix.
drafted_by agent, learner, teacher Qui a écrit le contenu et ses clés de réponse. Un brouillon agent s'ouvre sur un avis : une IA l'a rédigé à partir des sources de l'apprenant et aucun enseignant ne l'a vérifié.
author_is_learner true, false La personne qui répond a aussi écrit la leçon.
learner_profile {minutes_per_day?, target_date?} Les minutes par jour de l'apprenant (de 1 à 600) et sa date visée, conservées par create_lesson ; le plan d'étude dimensionne l'étape suivante avec les minutes. Ce que l'apprenant a dit savoir ou aimer n'est jamais conservé ici.

Deux autres champs portent la provenance. Une scène marquée diagnostic: true est une question d'ouverture sur ce que l'apprenant sait déjà : elle est jouée une fois et n'est jamais choisie pour une révision. Une citation de evidence.bibliographic_refs[] peut porter la license de la source, que les surfaces affichent après son titre.

Un bundle sans metadata.authoring (bundles plus anciens) est lu comme une leçon d'enseignant. validated_by et validated_at consignent la relecture de l'enseignant ; experience_packet.py approve les renseigne et écrit approval.json avec l'empreinte SHA-256 des octets finaux, si bien que toute modification ultérieure apparaît comme non approuvée. Seul ce registre fait lire une leçon comme validée : le texte de validated_by seul se lit « aucune approbation enregistrée ». Un bundle d'autoformation ne peut pas être approuvé.

Référence des champs

Schema version: 1.4. Field tables are generated from the Zod schemas; rules that span several fields (weights that sum to 1, ids that must exist) are checked by the schema and the linter but do not appear here.

Bundle

Field Type Required Description
schema_version 1.4 yes
bundle_id string yes
source_plan_id string yes
metadata object yes See Metadata.
concepts array of objects, at least 1 item yes See Concept.
scenes array of objects of 13 shapes, at least 1 item yes See Scene types.
rules array of objects yes See Adaptation rule.
validated_by string (at least 3 chars) yes
validated_at string, date-time yes
assessment_blueprint object no See Assessment blueprint.
learning_workflow_graph object or null no
universes object or null no

Metadata

Field Type Required Description
title string yes
target string yes
duration_minutes integer (> 0) yes
language string (at least 2 chars) yes
discipline string yes
authoring object no
authoring.mode one of teacher, self_study yes
authoring.author_is_learner boolean no Default false.
authoring.drafted_by one of agent, learner, teacher no
authoring.note string no
authoring.learner_profile object no

Concept

Field Type Required
id string yes
title string yes
description string yes
bloom_level_target one of remember, understand, apply, analyze, evaluate, create yes

Scene fields

Every scene, whatever its type, has these fields.

Field Type Required Description
id string (non-empty) yes
type one of intro, concept, quiz, meta_checkpoint, reproduction, ai_critique, discussion, spot_the_flaw, explain_back, comparison, summary_audit, prompt_practice, communication_sim yes
title string (non-empty) yes
objective_refs array of string yes
concept_refs array of string yes
estimated_seconds integer (≥ 0) yes
adaptation_hooks array of string yes
render_assets array of objects no See Render asset.
evidence object no See Evidence.
diagnostic boolean no

Scene types

13 types. Each table lists the fields a type adds to the scene fields.

intro

Field Type Required
markdown string yes

concept

Field Type Required
markdown string yes
image_path string no

quiz

Field Type Required
question string yes
choices array of objects, 2–6 items yes
choices[].id string yes
choices[].text string yes
choices[].correct boolean yes
feedback_correct string yes
feedback_incorrect string yes
hints array of string yes

meta_checkpoint

Field Type Required
pre_question string yes
post_question string yes
scale_labels array of string, 5 items yes

reproduction

Field Type Required
task_card_id string yes
steps array of objects, at least 1 item yes
steps[].step_id string yes
steps[].instruction string yes
steps[].expected_input_schema object (free form) yes
steps[].expected_output string or object (free form) yes
prov_derived_from string, uri no
image_path string no
reference_result object no
reference_result.ran boolean yes
reference_result.passed boolean yes
reference_result.landmark string or null yes
reference_result.figure_path string or null yes
reference_result.checks array of objects yes
reference_result.checks[].check string yes
reference_result.checks[].passed boolean yes
reference_result.provenance object yes
reference_result.provenance.capsule_doi string or null yes
reference_result.provenance.cmd array of string yes
reference_result.provenance.env string yes
run_manifest object no
run_manifest.capsule_ref string (non-empty) yes
run_manifest.cmd array of string, at least 1 item yes
run_manifest.working_dir string or null no
run_manifest.timeout_s number (> 0) no
run_manifest.requirements array of string no
run_manifest.expected_outputs array of string yes
run_manifest.verify_checks array of string yes
run_manifest.research_question string no
run_manifest.landmark_pattern string no

ai_critique

Field Type Required
claims array of objects, 1–3 items yes
claims[].id string yes
claims[].text string yes
claims[].flaws_expected array of string yes
rubric object yes
rubric.completeness number (0–1) yes
rubric.evidence_quality number (0–1) yes
rubric.tone number (0–1) yes

discussion

Field Type Required
topic string (non-empty) yes
seed_claim string (non-empty) yes
target_signals array of one of justification, hypothesis, question, counterexample, synthesis, at least 1 item yes
max_turns integer (> 0) yes

spot_the_flaw

Field Type Required
flawed_content string (non-empty) yes
claims array of objects, 1–5 items yes
claims[].id string yes
claims[].text string yes
claims[].flaws_expected array of string, at least 1 item yes
model_correction string (non-empty) yes
rubric object yes
rubric.completeness number (0–1) yes
rubric.evidence_quality number (0–1) yes
rubric.tone number (0–1) yes
reference_result object no
reference_result.ran boolean yes
reference_result.passed boolean yes
reference_result.landmark string or null yes
reference_result.figure_path string or null yes
reference_result.checks array of objects yes
reference_result.checks[].check string yes
reference_result.checks[].passed boolean yes
reference_result.provenance object yes
reference_result.provenance.capsule_doi string or null yes
reference_result.provenance.cmd array of string yes
reference_result.provenance.env string yes
sound_claims array of objects no
sound_claims[].id string yes
sound_claims[].text string yes
reference_from_run string no
regenerate_from_run boolean no
verdict_deck boolean no

explain_back

Field Type Required
prompt string (non-empty) yes
key_points array of objects, 1–6 items yes
key_points[].id string yes
key_points[].text string yes
key_points[].cues array of string, at least 1 item yes
model_explanation string (non-empty) yes
rubric object yes
rubric.completeness number (0–1) yes
rubric.evidence_quality number (0–1) yes
rubric.tone number (0–1) yes

comparison

Field Type Required
prompt string (non-empty) yes
artifact_a string (non-empty) yes
artifact_b string (non-empty) yes
key_points array of objects, at least 1 item yes
key_points[].id string yes
key_points[].text string yes
key_points[].cues array of string, at least 1 item yes
model_answer string (non-empty) yes
rubric object yes
rubric.completeness number (0–1) yes
rubric.evidence_quality number (0–1) yes
rubric.tone number (0–1) yes

summary_audit

Field Type Required
source_content string (non-empty) yes
ai_summary string (non-empty) yes
claims array of objects, 1–5 items yes
claims[].id string yes
claims[].text string yes
claims[].flaws_expected array of string, at least 1 item yes
model_correction string (non-empty) yes
rubric object yes
rubric.completeness number (0–1) yes
rubric.evidence_quality number (0–1) yes
rubric.tone number (0–1) yes

prompt_practice

Field Type Required
task string (non-empty) yes
starter_prompt string no
key_points array of objects, at least 1 item yes
key_points[].id string yes
key_points[].text string yes
key_points[].cues array of string, at least 1 item yes
model_prompt string (non-empty) yes
rubric object yes
rubric.completeness number (0–1) yes
rubric.evidence_quality number (0–1) yes
rubric.tone number (0–1) yes

communication_sim

Field Type Required
scenario string (non-empty) yes
prompt string (non-empty) yes
key_points array of objects, at least 1 item yes
key_points[].id string yes
key_points[].text string yes
key_points[].cues array of string, at least 1 item yes
model_response string (non-empty) yes
rubric object yes
rubric.completeness number (0–1) yes
rubric.evidence_quality number (0–1) yes
rubric.tone number (0–1) yes

Adaptation rule

Field Type Required
id string yes
when map of string yes
action object, one of 5 shapes yes
action.kind one of advance_to_next_scene, replay_current_scene, skip_to_next_concept, show_calibration_panel, show_explanation_panel yes
action.reason string in replay_current_scene
modulator one of M1, M3, M6 yes
explanation_short string yes

Render asset

Field Type Required
kind one of image, audio, video, svg, equation_latex, plot_spec, code, data_csv, protocol_md, executed_result, orbital, mol_3d, spectrum yes
title string no
payload string no
path string no
language string no
format string no
provenance string no
meta object (free form) no
legend array of objects, at least 1 item no
legend[].symbol string yes
legend[].meaning string yes

Evidence

Field Type Required
bibliographic_refs array of objects no
bibliographic_refs[].perspicacite_doc_id string (non-empty) yes
bibliographic_refs[].doi string no
bibliographic_refs[].title string (non-empty) yes
bibliographic_refs[].authors array of string yes
bibliographic_refs[].year integer no
bibliographic_refs[].excerpt string (≤ 500 chars) yes
bibliographic_refs[].relevance_score number (0–1) yes
bibliographic_refs[].prov_derived_from string (non-empty) yes
bibliographic_refs[].license string (non-empty) no
case_studies array of objects no
case_studies[].title string (non-empty) yes
case_studies[].summary string (≤ 1000 chars) yes
case_studies[].source_refs array of string yes
abs_asset object no
abs_asset.asset_type one of spectrum_viewer_svg, code_snippet, data_csv, protocol_card_md, script_snippet, plot_spec, equation_latex, orbital_viewer_3d, molecule_3d, spectrum_data yes
abs_asset.payload_inline string no
abs_asset.payload_path string no
abs_asset.abs_task_card_id string no
abs_asset.prov_derived_from string (non-empty) yes
abs_asset.legend array of objects, at least 1 item no
abs_asset.legend[].symbol string yes
abs_asset.legend[].meaning string yes
enrichment_metadata object yes
enrichment_metadata.enricher_version string (non-empty) yes
enrichment_metadata.perspicacite_mode_used one of basic, advanced, profound, agentic, passages yes
enrichment_metadata.timestamp string (non-empty) yes
enrichment_metadata.degraded boolean yes

Assessment blueprint

Field Type Required
dimensions array of objects, at least 1 item yes
dimensions[].id string (non-empty) yes
dimensions[].label string (non-empty) yes
dimensions[].weight number (0–1) yes
dimensions[].metrics array of objects, at least 1 item yes
dimensions[].metrics[].endpoint one of progress, calibration, autonomy, ai_literacy, reasoning, ai_audit yes
dimensions[].metrics[].field string (non-empty) yes
dimensions[].metrics[].weight_in_dimension number (0–1) yes

Tenir cette page à jour

pnpm docs:gen     # réécrit les sections générées à partir des schémas
pnpm docs:check   # échoue quand une section générée ne correspond plus au code

Voir la source de cette page sur GitHub