Architecture
Cette page montre comment Studium est assemblé : quelle unité fait quoi, comment une leçon va des sources jusqu'à la réponse d'un apprenant, et où l'état est conservé. Lisez-la avant de modifier du code qui traverse une frontière entre paquets. Les termes scène, classe de clé ou FSRS sont définis dans le glossaire.
Un seul contrat, plusieurs surfaces
Tout ce que joue un apprenant est un bundle de leçon : un fichier lesson.json validé par le schéma
LessonBundle (version 1.4, packages/lesson-bundle-schema).
Il contient les scènes, les concepts et le graphe de parcours (Learning Workflow Graph, LWG) qui les relie.
Les outils d'auteur écrivent des bundles ; toutes les surfaces les lisent par le même hôte. Les couches :
| Couche | Unités | Rôle |
|---|---|---|
| Contrat de cours | lesson-bundle-schema, learning-workflow-schema |
le format du bundle et le graphe typé |
| Moteur adaptatif | lesson-session, adaptation-engine, learner-state, reasoning-scorer |
correction, navigation, maîtrise, planification des révisions |
| Hôte de sessions | lesson-session-host |
une session par apprenant et par leçon ; persistance ; masquage des clés ; plan d'étude ; contrôles d'auteur |
| Transports | apps/lesson-mcp (MCP en stdio, adaptateur HTTP), apps/lesson-server (HTTP), canal fichier .studium-session/ |
le contrat public de session |
| Clients apprenant | extension VS Code, tout assistant MCP | présentation |
| Surfaces de relecture | tableau de bord enseignant, Observatory | vues enseignant et opérateur, séparées des clients apprenant |
Le trajet d'une réponse
- Un client appelle
start_lesson_sessionavec une référence de bundle. L'hôte la cherche dansBUNDLES_ROOT, puis dans la bibliothèque de l'apprenant, charge le bundle et le valide. - L'hôte renvoie la scène courante sous forme de projection publique :
public-scene.tsretire tous les champs qui portent la réponse (bonnes réponses, points clés, réponses modèles) avant que quoi que ce soit ne sorte du serveur, que ce soit par MCP, par HTTP ou par le canal fichier. - Le client envoie la réponse avec
submit_response. La session la corrige, applique le signal au modèle de l'apprenant, choisit l'étape suivante et se déplace dans le graphe. - Seule une réponse mesurée fait bouger la maîtrise. Sans modèle juge (
LITELLM_BASE_URLvide), une réponse ouverte reçoit la référence à laquelle se comparer, jamais un décompte de couverture ; l'auto-évaluation (rate_recall) planifie les révisions mais ne touche jamais la maîtrise. Voir honnêteté et provenance. - Les passages cités et la référence ne sont libérés que lorsque l'apprenant quitte la scène pour de bon.
- L'hôte écrit l'état de l'apprenant dans le répertoire de données. Si
STUDIUM_TELEMETRY_CONSENTest activé et le stockage durable, il ajoute aussi des événements pseudonymisés àtelemetry.jsonl, queclass_reportagrège au-dessus d'un seuil de cinq apprenants.
Où vit l'état
| Quoi | Par défaut | Réglé par |
|---|---|---|
| Leçons lues | BUNDLES_ROOT, puis ~/.studium/library |
BUNDLES_ROOT, STUDIUM_HOME |
| Leçons et sources écrites par la création | ~/.studium/library seulement, jamais BUNDLES_ROOT |
STUDIUM_HOME |
| État de l'apprenant | ~/.studium/data |
STUDIUM_DATA_DIR, STUDIUM_HOME |
| Tout en mémoire | désactivé | STUDIUM_EPHEMERAL=1 (tests, démos, CI) |
| Dossiers d'apprenant sur disque | pseudonymes HMAC | STUDIUM_PSEUDO_SECRET, sinon <répertoire de données>/.studium-secret |
Seul le point d'entrée stdio applique ces défauts
(persistence.ts) ; le code de bibliothèque et
ses tests restent en mémoire tant qu'ils ne configurent pas de répertoire. La liste complète est dans la
configuration.
Deux voies d'auteur
| Voie conversation | Voie paquet | |
|---|---|---|
| Pour | un apprenant autonome avec son assistant IA | un enseignant qui prépare un cours |
| Entrée | outils MCP get_authoring_guide, prepare_sources, create_lesson |
tools/experience_packet.py passages, prepare, check, bundle, approve |
| Code | apps/lesson-mcp/src/authoring-tools.ts, authoring-draft/ |
tools/experience_packet.py |
| Contrôles | citations comparées aux passages caractère par caractère, aucun TODO, graphe de concepts cohérent, lint du bundle |
validation du schéma, constats structurés (check --json), lint du bundle |
| Résultat | <bibliothèque>/<course_id>/lesson.json, marqué rédigé par l'IA, non validé par un enseignant |
un dossier de cours ; approve écrit approval.json, lié à l'empreinte SHA-256 de lesson.json |
| Guide | Apprendre un sujet en conversation | Écrire une leçon |
Les deux voies aboutissent au même format de bundle et passent toutes deux par
tools/bundle_lint.mjs. Les services FastAPI planner et scene-synth
sont conservés comme code hérité et de recherche ; ce n'est pas une voie d'auteur prise en charge.
Carte des unités
C'est la carte du dépôt : chaque application, paquet, service et dossier, avec son rôle. La façon dont les panneaux atteignent chaque hôte est décrite dans Panneaux de leçon pour les développeurs.
Applications
| Unité | Rôle | README |
|---|---|---|
apps/lesson-mcp |
serveur MCP (40 outils, stdio) et adaptateur HTTP des opérations de leçon | README |
apps/studium-vscode |
extension VS Code : panneau de leçon, participant de chat, serveur MCP embarqué | README |
apps/lesson-panel-ui |
Rendu partagé des leçons et graphes, adaptateurs VS Code et MCP Apps | README |
apps/claude-code-mod |
Plugin Claude Code : panneau natif utilisant les outils partagés | README |
apps/lesson-server |
serveur HTTP Fastify pour les leçons, clés masquées | README |
apps/teacher-dashboard |
tableau de bord Next.js : analyses de classe, bibliothèque et relecture des leçons | README |
apps/student-runtime |
application de bureau Tauri, gelée | README |
apps/author-web |
application d'auteur Next.js, héritée | README |
Paquets TypeScript
| Unité | Rôle | README |
|---|---|---|
lesson-bundle-schema |
schéma LessonBundle 1.4 (Zod) et son miroir Python | README |
learning-workflow-schema |
graphe de parcours : nœuds concept et tâche, arêtes typées | README |
lesson-plan-schema |
sous-schéma de plan de leçon (JSON Schema, types, miroir Pydantic) | README |
lesson-schema |
ancien schéma de leçon v1 (ADR 003) ; le schéma de bundle fait foi | README |
lesson-session |
un apprenant dans une leçon : correction, navigation, tuteur | README |
lesson-session-host |
hôte multi-sessions : persistance, masquage, plan d'étude, auteur | README |
lesson-panel |
vue publique, actions et composition communes aux harnais | README |
adaptation-engine |
mise à jour bêta de la maîtrise, planification FSRS, routage dans le graphe | README |
learner-state |
types du modèle de l'apprenant : maîtrise, calibration, confiance | README |
reasoning-scorer |
classe le raisonnement d'un tour de tutorat | README |
llm-client |
client de modèle : simulé ou point d'accès compatible LiteLLM | README |
perspicacite-client |
métadonnées de DOI via le service Perspicacité, repli hors ligne | README |
telemetry-events |
schéma des événements de télémétrie (TypeScript et Python) | README |
typed-graph-lens |
vue de graphe typé avec état en direct, pour le panneau graphe de VS Code | README |
activity-presentation |
rendus HTML portables, KaTeX intégré, pour viewers et rapports | README |
Services Python
| Unité | Rôle | README |
|---|---|---|
services/analytics-collector |
stocke la télémétrie et sert des agrégats de classe (service de développement et de démo) | README |
services/observatory |
page opérateur en lecture seule : provenance, évaluations, validité | README |
services/ingest |
ingestion des sources : extraction PDF, BibTeX, résolution de DOI | README |
services/planner |
planificateur hérité et de recherche ; répond 503 sans modèle configuré | README |
services/scene-synth |
synthèse de scènes héritée et de recherche | README |
Autres dossiers
| Dossier | Contenu |
|---|---|
design/ |
jetons de design, pont VS Code, composants, aperçu |
ui/ |
thème commun des viewers et catalogue d'aide contextuelle |
tools/ |
scripts d'auteur, de lint, de rapport et d'audit ; pytest_all.py |
eval/ |
banc d'évaluation et études de validité |
fixtures/ |
leçons d'exemple, dont atomistique-l1 |
skills/ |
skills d'assistant pour étudiants, enseignants et apprenants autonomes (skills) |
Limites
L'adaptateur HTTP expose les 25 opérations de leçon et rate_recall ; les autres outils d'étude et les
outils d'auteur et enseignant n'existent qu'en MCP. Aucun canal unique ne relie l'hôte aux deux surfaces de relecture : elles lisent sur
disque les artefacts de cours et de relecture.