quantum-bridge-mcp/docs/superpowers/specs/2026-04-29-quantum-tutor-design.md

Quantum Tutor — Design Spec

Date: 2026-04-29
Status: Approved
Scope: Extension pédagogique de quantum-bridge-mcp — 4 nouveaux outils MCP + curriculum JSON + suivi de progression

---

1. Contexte et objectif

quantum-bridge-mcp est un serveur MCP Rust qui expose 3 outils de simulation de circuits OpenQASM 3.0. Ce module ajoute une couche pédagogique au-dessus des outils existants : un tuteur quantique qui guide l'utilisateur à travers un curriculum structuré, vérifie ses exercices, et suit sa progression.

Utilisateur cible : débutant en informatique quantique avec des notions vagues de superposition/intrication. Objectif : aller des bases jusqu'aux algorithmes (Grover).

Style d'apprentissage : explication courte → exercice guidé → exploration libre. Maths introduites progressivement quand elles deviennent nécessaires.

---

2. Nouveaux outils MCP

2.1 get_lesson

get_lesson(module_id: u32, lesson_id?: u32) → JSON

Retourne le contenu d'une leçon : explication du concept, circuit(s) d'illustration à exécuter, et exercice(s) à résoudre.

Paramètres :

• module_id : 1–7 (voir curriculum §4)
• lesson_id : optionnel ; si absent, retourne la première leçon non complétée du module

Réponse :

{
  "module_id": 2,
  "lesson_id": 1,
  "title": "La porte H et la superposition",
  "concept": "...",
  "example_circuit": "OPENQASM 3.0;\n...",
  "what_to_observe": "Lance run_circuit avec 1000 shots. Tu devrais voir ~500 '0' et ~500 '1'.",
  "exercise": {
    "id": "2-1-a",
    "prompt": "Écris un circuit qui met un qubit en superposition parfaite et le mesure.",
    "hint": "Une seule porte suffit avant la mesure."
  }
}

Comportement : si lesson_id est absent et que get_progress() indique que le module est déjà complété, retourne un résumé du module avec suggestion d'avancer.

---

2.2 check_exercise

check_exercise(exercise_id: str, circuit: str) → JSON

Vérifie si le circuit soumis résout l'exercice identifié par exercise_id. Exécute le circuit en interne (1024 shots), compare les résultats aux critères définis dans curriculum.json, met à jour la progression.

Paramètres :

• exercise_id : identifiant de l'exercice (ex: "2-1-a")
• circuit : source OpenQASM 3.0

Réponse (succès) :

{
  "passed": true,
  "exercise_id": "2-1-a",
  "feedback": "Parfait ! Ta porte H crée bien une superposition équilibrée. Tu observes ~50% de '0' et ~50% de '1'.",
  "counts": {"0": 512, "1": 512},
  "progress_updated": true
}

Réponse (échec) :

{
  "passed": false,
  "exercise_id": "2-1-a",
  "feedback": "Ton circuit produit toujours '0'. Le qubit n'est pas en superposition. Essaie d'ajouter une porte avant la mesure.",
  "counts": {"0": 1024},
  "hint": "La porte H transforme |0⟩ en (|0⟩ + |1⟩)/√2."
}

Critères de vérification (définis par exercice dans curriculum.json) :

• required_outcomes : liste de bitstrings qui doivent apparaître (avec proportion min/max optionnelle)
• forbidden_outcomes : bitstrings qui ne doivent pas apparaître
• statevector_check : optionnel — amplitudes attendues avec tolérance ε=1e-6

Erreurs : si le circuit est invalide, retourne l'erreur de validation avec position (réutilise CircuitValidator).

---

2.3 explain_result

explain_result(circuit: str, counts: object, statevector?: array) → JSON

Génère une explication pédagogique de ce qui s'est passé dans le circuit : quelles portes ont fait quoi, pourquoi on observe cette distribution, ce que ça signifie quantiquement.

Paramètres :

• circuit : source OpenQASM 3.0 (le circuit qui vient d'être exécuté)
• counts : résultat de run_circuit (bitstring → count)
• statevector : optionnel — amplitudes complexes de run_circuit avec return_statevector: true

Réponse :

{
  "gate_breakdown": [
    {"gate": "h q[0]", "qubit": 0, "description": "Hadamard — crée une superposition égale", "effect_on_zero": "Transforme |0⟩ en (|0⟩+|1⟩)/√2"},
    {"gate": "cx q[0], q[1]", "control": 0, "target": 1, "description": "CNOT — flip la cible si le contrôle est |1⟩"}
  ],
  "num_qubits": 2,
  "key_concept": "intrication",
  "dominant_outcomes": ["00", "11"],
  "missing_outcomes": ["01", "10"],
  "statevector_summary": {"non_zero_amplitudes": [0, 3], "zero_amplitudes": [1, 2]}
}

Implémentation : le serveur Rust analyse le circuit via CircuitValidator et retourne des données structurées (liste de gates avec descriptions depuis curriculum.json, statistiques des counts, concept clé). C'est Claude (le client MCP) qui synthétise l'explication en langage naturel à partir de ces données — cette séparation exploite les capacités respectives du simulateur (analyse structurelle) et du LLM (narration pédagogique).

---

2.4 get_progress

get_progress() → JSON

Retourne l'état de progression de l'utilisateur dans le curriculum.

Réponse :

{
  "current_module": 2,
  "current_lesson": 1,
  "modules": [
    {"id": 1, "title": "Le qubit", "status": "completed", "exercises_solved": 3},
    {"id": 2, "title": "Superposition", "status": "in_progress", "exercises_solved": 0},
    {"id": 3, "title": "Interférence", "status": "locked", "exercises_solved": 0}
  ],
  "total_exercises_solved": 3,
  "total_exercises": 18,
  "percent_complete": 17
}

Persistence : fichier JSON à ~/.config/quantum-bridge-mcp/progress.json. Créé automatiquement au premier appel avec progression à zéro.

---

3. Architecture interne

Nouveaux fichiers

curriculum/
  curriculum.json          — leçons, exercices, critères de vérification, descriptions de gates
src/
  tutor.rs                 — CurriculumLoader + ExerciseChecker (logique de vérification)
  progress.rs              — ProgressStore (lecture/écriture progress.json)
  tools/
    tutor_tools.rs         — handlers MCP des 4 nouveaux outils

Réutilisation des composants existants

Composant existant	Réutilisé par
CircuitValidator (src/validator.rs)	check_exercise (validation avant exécution), explain_result (analyse des gates)
LocalSimulator via CanExecute	check_exercise (exécution interne des circuits)
CircuitSource, ShotCount, SimulationResult (src/types.rs)	check_exercise, explain_result
Trait Backend	check_exercise — dépend de &dyn Backend, compatible IBM V1.5

Contraintes d'architecture

• Les outils tutor dépendent de &dyn Backend, jamais de LocalSimulator directement (même règle que les outils existants).
• check_exercise utilise ShotCount(1024) fixe pour la vérification (reproductibilité statistique).
• ExerciseChecker compare avec tolérance : un résultat passe si chaque outcome requis représente au moins min_ratio - 2σ des shots (σ calculé pour N=1024 shots, distribution binomiale).

---

4. Curriculum — structure des 7 modules

Module	Titre	Concepts clés	Nb exercices
1	Le qubit	États |0⟩/|1⟩, gate X, mesure	2
2	Superposition	Gate H, état |+⟩, distribution 50/50	3
3	Interférence et phase	H·H=I, phase relative, gates Z/S/T/RZ	3
4	2 qubits et intrication	Bell state, CNOT, mesure corrélée	3
5	Circuits multi-qubits	GHZ, Toffoli, statevecteur complet	3
6	Premiers algorithmes	Deutsch-Jozsa, Bernstein-Vazirani, téléportation	2
7	Algorithme de Grover	Oracle de phase, opérateur de diffusion	2

Total : 18 exercices sur 7 modules.

Les modules 2–7 sont verrouillés jusqu'à complétion du module précédent. Exception : le module suivant se déverrouille dès qu'au moins 2/3 des exercices du module courant sont résolus.

---

5. Format curriculum.json (schéma)

{
  "version": "1.0",
  "gate_descriptions": {
    "h": {
      "short": "Hadamard — crée une superposition égale",
      "effect_on_zero": "Transforme |0⟩ en (|0⟩+|1⟩)/√2",
      "effect_on_one": "Transforme |1⟩ en (|0⟩-|1⟩)/√2"
    }
  },
  "modules": [
    {
      "id": 1,
      "title": "Le qubit",
      "lessons": [
        {
          "id": 1,
          "title": "États |0⟩ et |1⟩",
          "concept": "...",
          "example_circuit": "OPENQASM 3.0;\n...",
          "what_to_observe": "...",
          "exercises": [
            {
              "id": "1-1-a",
              "prompt": "...",
              "hint": "...",
              "criteria": {
                "required_outcomes": [{"bitstring": "1", "min_ratio": 0.95}],
                "forbidden_outcomes": ["0"]
              }
            }
          ]
        }
      ]
    }
  ]
}

---

6. Tests

• Unitaires : ExerciseChecker avec critères simples (gate X → bitstring "1" avec ratio 1.0)
• Intégration : check_exercise roundtrip via MCP JSON-RPC pour 3 exercices représentatifs (un par module difficile)
• Golden files : tests/tutor/ — circuits d'exercices + résultats attendus (pass/fail)
• Progress : ProgressStore — création, mise à jour, lecture, reset

---

7. Hors scope (V1)

• Visualisation sphère de Bloch (V2)
• Dessin de circuits en ASCII/SVG (V2)
• Explications générées par LLM (V2)
• Support multi-utilisateurs (V2)
• Gamification / badges (V2)