API HTTP

Studium propose deux serveurs HTTP locaux. Utilisez l'API de leçon d'apps/lesson-mcp pour piloter des leçons depuis un script ou un harnais sans MCP ; elle expose les 25 opérations de leçon des outils MCP, ainsi que rate_recall. L'ancien lesson-server (apps/lesson-server) sert les salles entre pairs et les pages de cours du tableau de bord enseignant. Les deux cachent les clés de réponse : une scène est envoyée dans sa projection publique, jamais avec sa clé.

API de leçon lesson-server
Démarrage pnpm --filter @studium/lesson-mcp api pnpm --filter @studium/lesson-server start
Adresse http://127.0.0.1:8130 (STUDIUM_API_PORT) http://127.0.0.1:8010 (PORT)
Authentification jeton Bearer, boucle locale uniquement, origines de navigateur refusées aucune (boucle locale uniquement)
Opérations 26 : les 25 outils de leçon et rate_recall, avec découverte sessions, salles entre pairs, cours
Relances idempotentes avec request_id aucune

Aucun des deux n'est fait pour une classe sur Internet : ils n'écoutent que sur 127.0.0.1 et leurs sessions appartiennent au processus en cours. Les identifiants de session ne passent pas de l'un à l'autre.

API de leçon

La démarrer

export STUDIUM_API_TOKEN="$(openssl rand -hex 32)"   # au moins 32 caractères ; à partager avec les clients, jamais dans un chat ni dans Git
BUNDLES_ROOT="$PWD/fixtures" pnpm --filter @studium/lesson-mcp api

Lancez-la dans un terminal que vous gardez ouvert. Elle n'écoute que sur 127.0.0.1, refuse les requêtes de navigateur qui portent un en-tête Origin et lit les leçons dans BUNDLES_ROOT (par défaut le dossier fixtures/ du clone). Gardez le jeton dans votre environnement, jamais dans une conversation ni dans Git.

L'API n'appelle jamais de modèle sans STUDIUM_API_LIVE=1 et LITELLM_BASE_URL. L'état de l'apprenant reste en mémoire tant que STUDIUM_DATA_DIR n'est pas fixée (voir Configuration).

L'appeler

Route Méthode Rôle
/health GET {schema: "studium/http/v1", status: "ready", sessions: "process-local"}
/v1/operations GET Toutes les opérations : name, description, mutating, requires_scene_id, input_schema (JSON Schema)
/v1/operations/<nom> POST Exécute une opération. Le résultat a les mêmes champs que l'outil MCP, sans l'enveloppe MCP.

Chaque requête porte Authorization: Bearer <jeton> ; le corps d'un POST est du JSON (content-type: application/json, 1 Mio au plus) dans cette enveloppe :

{
  "request_id": "start-001",
  "expected_scene_id": "s-intro",
  "arguments": { "bundle_ref": "capsule-judgment-demo/lesson.json", "learner_id": "local-student" }
}
Champ Quand
arguments Toujours : les arguments de l'outil, vérifiés par son schéma.
request_id Pour toute opération qui modifie l'état. Réutilisez-le, avec des arguments identiques, pour relancer sans risque : la réponse conservée est renvoyée et rien ne s'exécute deux fois.
expected_scene_id submit_response, submit_turn, submit_run_result, request_hint, record_experiment : la scène à laquelle l'apprenant répond. Une scène qui a changé donne 409 stale_scene.

Quand submit_response renvoie self_rating: {requested: true, scene_id, ...}, demandez à l'apprenant de choisir again, hard, good ou easy, puis appelez rate_recall avec un nouveau request_id et arguments: {session_id, scene_id, grade}. Cette opération n'exige pas expected_scene_id, car son argument scene_id identifie la demande d'auto-évaluation consommée. Une relance identique avec le même request_id renvoie la réponse conservée ; un autre identifiant ne peut pas enregistrer une seconde note pour la même demande.

curl -s -H "Authorization: Bearer $STUDIUM_API_TOKEN" http://127.0.0.1:8130/v1/operations
curl -s -X POST -H "Authorization: Bearer $STUDIUM_API_TOKEN" -H 'content-type: application/json' \
  -d '{"request_id":"start-001","arguments":{"bundle_ref":"capsule-judgment-demo/lesson.json","learner_id":"local-student"}}' \
  http://127.0.0.1:8130/v1/operations/start_lesson_session

Le dépôt fournit aussi un petit client qui lit le jeton dans l'environnement et ne l'affiche jamais :

pnpm --silent --filter @studium/lesson-mcp api:call health
pnpm --silent --filter @studium/lesson-mcp api:call operations
pnpm --silent --filter @studium/lesson-mcp api:call start_lesson_session /chemin/absolu/start.json

Les opérations en lecture seule (get_*, explain_last_adaptation, list_community_bundles) n'exigent pas de request_id et sont recalculées à chaque appel. forget_session prend session_id ou learner_id, comme par MCP ; avec learner_id, aucune session n'a besoin d'être ouverte, et une requête rejouée sur l'une des sessions qu'il a fermées répond 410 forgotten. Les autres outils d'étude (get_study_plan, list_lessons, start_review_session) et tous les outils d'auteur et d'enseignant ne sont pas servis ici dans cette version ; passez par MCP.

Erreurs

Une erreur est un objet {error, code} avec ces statuts :

Statut Codes Que faire
400 invalid_json, invalid_input, request_id_required, scene_required, invalid_bundle Corriger la requête d'après le schéma de découverte ; rien n'a été enregistré.
401, 403 unauthorized, local_only, origin_rejected Vérifier le jeton, et que le client est local et n'est pas un navigateur.
404 not_found, session_not_found Route ou session inconnue (un redémarrage met fin à toutes les sessions). Ne pas inventer de reprise.
409 stale_scene, request_conflict Relire la scène courante ; ou un request_id a été réutilisé avec un autre contenu.
410 session_closed, forgotten La session a été fermée ou effacée ; en ouvrir une nouvelle, sans jamais recréer des données effacées.
413, 415 body_too_large, media_type Envoyer du JSON de moins de 1 Mio ; passer les médias par référence.
422 operation_failed Le moteur de leçon a refusé l'opération ; lire error.
503 busy, receipt_limit Relancer avec le même request_id ; ou exporter puis redémarrer après 512 modifications (16 Mio de réponses conservées).

Les opérations s'exécutent une à une. Après une erreur réseau, renvoyez le même fichier avec le même request_id plutôt qu'une seconde réponse. Pour changer de harnais en cours de leçon, transmettez l'adresse, le session_id et la langue, et commencez par get_operator_context ; ne redémarrez pas la leçon.

Un redémarrage du serveur met fin à ses sessions : un appel sur un ancien session_id répond session not found et dit comment reprendre. Avec un stockage durable, un nouveau start_lesson_session pour le même apprenant et la même leçon reprend à la première étape non terminée. Sur un panneau ou un volet, l'action suivante de l'apprenant sur l'ancienne session remplace la scène par « Séance perdue (le serveur a redémarré ou la séance a été fermée). Rouvre la leçon : ta progression est conservée. » et un bouton pour rouvrir : celui du panneau MCP Apps et celui du volet Claude Code ouvrent la même leçon pour le même apprenant (le volet Claude Code donne aussi /studium <bundle_ref>), celui du volet VS Code le ferme et ouvre la leçon dans un nouveau volet. Rien n'est relancé tout seul.

Garder le journal

Exportez ce que vous voulez garder avant d'arrêter un serveur en mémoire. Avec context.json contenant {"arguments":{"session_id":"<id>"}} :

pnpm --silent --filter @studium/lesson-mcp api:call get_experiment_journal context.json > journal.json
.venv/bin/python tools/learner_report.py export new-report --journal journal.json

Voir Rapport de l'apprenant pour le contenu du rapport.

lesson-server

Un serveur Fastify pour le tableau de bord enseignant. Les réponses sont {success, ok, ...} en cas de succès et {success: false, ok: false, error} sinon.

Route Méthode Corps ou paramètres Réponse
/sessions POST {bundle_ref, learner_id?} 201 {session_id, presentation}
/sessions/:id GET {presentation}
/sessions/:id/respond POST {input} (une réponse, comme pour submit_response) {transition} ; 409 si la session ne peut pas l'accepter
/sessions/:id/turns POST {text} {accepted: true}
/sessions/:id/state GET {state}
/sessions/:id DELETE {forgotten: true} : efface la session
/rooms POST {bundle_ref} 201, la nouvelle salle entre pairs
/rooms/join POST {join_code, session_id} la salle
/rooms/:id/ratings POST {rater_session_id, target_session_id, passed, rating (1–5), helpful} l'évaluation
/rooms/:id GET ?teacher_key= l'état de la salle
/rooms/:id/close POST {teacher_key} la salle fermée
/courses GET ?ref= (un chemin sous BUNDLES_ROOT) {course} : ordre du cours et prérequis

Il n'a pas d'authentification : gardez-le sur une machine que vous contrôlez. Sa configuration (BUNDLES_ROOT, PORT, LITELLM_BASE_URL) se trouve dans Configuration.

Voir la source de cette page sur GitHub