Vincent Bourdon
237 lines
12 KiB
Markdown
237 lines
12 KiB
Markdown
# quantum-bridge-mcp — Design Spec
|
||
|
||
**Date:** 2026-04-28
|
||
**Status:** Approved (revised after competitive analysis)
|
||
**Author:** Vincent Bourdon
|
||
|
||
---
|
||
|
||
## 1. Problème et positionnement
|
||
|
||
Les développeurs sans expertise quantique ne peuvent pas intégrer du calcul quantique dans leurs projets sans quitter leur workflow et apprendre Qiskit. L'écosystème MCP quantique existant (Qiskit/mcp-servers officiel IBM, plusieurs forks communautaires) est **100% Python**, dépend de l'installation lourde de Qiskit (~200 Mo + venv + résolution pip), et requiert souvent un compte IBM même pour de la simulation locale.
|
||
|
||
**Cible :** développeurs qui veulent intégrer ou prototyper du calcul quantique simulé sans installer l'écosystème Python/Qiskit.
|
||
|
||
**Positionnement :** *« Le simulateur quantique le plus léger et le plus performant pour Claude — un binaire, zéro setup, zéro réseau, zéro compte »*.
|
||
|
||
Trois angles défendables face au MCP officiel IBM :
|
||
- **Léger** : binaire unique ~10 Mo vs ~200 Mo de Qiskit + dépendances Python
|
||
- **Rapide à démarrer** : pas de cold start Python, pas de pip resolve
|
||
- **Performant** : moteur Spinoza (pure Rust), top tier single-thread sur 5–25 qubits
|
||
- **Privacy / air-gapped** : aucune télémétrie, aucun appel réseau, fonctionne hors-ligne et en CI minimal
|
||
|
||
---
|
||
|
||
## 2. Scope V1 vs V1.5
|
||
|
||
| Phase | Périmètre | Cible |
|
||
|-------|-----------|-------|
|
||
| **V1** | Simulateur local uniquement, mode synchrone, OpenQASM 3.0 | livrable rapide, valeur immédiate |
|
||
| **V1.5** | Ajout backend IBM Quantum (token utilisateur), mode asynchrone avec persistence des job_ids pour reprise de session | après validation V1 |
|
||
|
||
V1 ne couvre **pas** : IBM Quantum, autres providers (AWS Braket, Azure, IonQ), simulation avec bruit, monétisation/tiers, gestion de licence.
|
||
|
||
---
|
||
|
||
## 3. Outils MCP exposés (V1)
|
||
|
||
| Outil | Description |
|
||
|-------|-------------|
|
||
| `list_backends` | Liste les backends disponibles (en V1 : seulement le simulateur local + ses capacités : qubits max, gates supportées) |
|
||
| `validate_circuit` | Parse un programme OpenQASM 3.0, vérifie sémantique (qubits déclarés, gates supportées, mesures bien formées). Retourne diagnostics structurés. |
|
||
| `run_circuit` | Exécute un circuit OpenQASM 3.0 sur le simulateur local (synchrone). Retourne counts + statevector optionnel + métadonnées. |
|
||
|
||
Trois outils en V1, contre six initialement prévus. La compression vient du mode synchrone (pas de cycle submit/status/results pour le local) et du retrait du `select_backend` (un seul backend en V1) et de `estimate_cost` (gratuit en local).
|
||
|
||
V1.5 réintroduira : `submit_circuit`, `get_job_status`, `get_results` (cycle async pour IBM), `select_backend`, `estimate_cost`.
|
||
|
||
Claude se charge de générer le circuit OpenQASM **et** d'interpréter les counts en langage clair. Le MCP fait exclusivement parsing, validation et exécution.
|
||
|
||
---
|
||
|
||
## 4. Architecture (V1)
|
||
|
||
```
|
||
Claude (génère le circuit OpenQASM 3.0)
|
||
↓
|
||
MCP Server (JSON-RPC sur stdio via rmcp)
|
||
↓
|
||
┌─────────────────────┐
|
||
│ validate_circuit │ → oq3_semantics
|
||
│ │ (AST + analyse sémantique)
|
||
└─────────────────────┘
|
||
↓
|
||
┌─────────────────────┐
|
||
│ run_circuit │ → AST → mapping vers gates Spinoza
|
||
│ │ → spinoza::simulate
|
||
│ │ → counts (sampling N shots)
|
||
└─────────────────────┘
|
||
↓
|
||
Retour à Claude
|
||
(counts + métadonnées brutes — Claude interprète)
|
||
```
|
||
|
||
### Composants internes
|
||
|
||
1. **MCP layer** — utilise le SDK officiel `rmcp` (modelcontextprotocol/rust-sdk) plutôt qu'une implémentation JSON-RPC manuelle. Réduit dette de maintenance et risque de divergence avec le protocole.
|
||
|
||
2. **CircuitValidator** — wrappe `oq3_semantics` (parser officiel Qiskit en Rust). Produit des diagnostics structurés (ligne, colonne, message) que Claude peut afficher tel quel à l'utilisateur. Vérifie :
|
||
- syntaxe OpenQASM 3.0 valide
|
||
- tous les qubits référencés sont déclarés
|
||
- toutes les gates utilisées sont supportées par le moteur
|
||
- nombre de qubits ≤ limite configurable (défaut 28, ajustable selon RAM)
|
||
- mesures correctement mappées sur des classical bits
|
||
|
||
3. **CircuitExecutor** — convertit l'AST OpenQASM 3 en séquence de gates Spinoza, lance la simulation, échantillonne N shots à partir des probabilités du statevector final.
|
||
|
||
4. **Pas de JobTracker, pas de persistence** en V1 — l'exécution est synchrone, retour direct. Ces composants reviennent en V1.5 pour les jobs IBM.
|
||
|
||
5. **Pas de ResultInterpreter en Rust** — l'interprétation langage naturel des counts (« état de Bell », « superposition », etc.) est laissée à Claude qui le fait nativement bien mieux qu'une table de patterns figée.
|
||
|
||
### Gates supportées (V1)
|
||
|
||
Pauli (X, Y, Z), Hadamard (H), phase (S, T, Sdg, Tdg), rotations (RX, RY, RZ), CNOT, CZ, SWAP, Toffoli (CCX), mesures.
|
||
|
||
Toute gate non listée doit produire une erreur explicite via `validate_circuit` avec la liste des gates supportées.
|
||
|
||
---
|
||
|
||
## 5. Stack technique
|
||
|
||
| Composant | Choix | Justification |
|
||
|-----------|-------|---------------|
|
||
| Langage | Rust (édition 2021) | Cohérence positionnement, perf, binaire unique |
|
||
| MCP SDK | `rmcp` (officiel) | Évite réimplémenter JSON-RPC stdio à la main |
|
||
| Parser OpenQASM 3 | `oq3_semantics` (Qiskit/openqasm3_parser) | Officiel, AST + analyse sémantique, bons diagnostics |
|
||
| Moteur simulation | `spinoza` (QuState/Wells Fargo) | Pure Rust, top tier 5–25 qubits, mode f32 optionnel |
|
||
| Async runtime | `tokio` | Nécessaire pour rmcp |
|
||
| Sérialisation | `serde` + `serde_json` | Standard |
|
||
| Logs | `tracing` | Standard observabilité Rust |
|
||
|
||
Aucune dépendance Python en runtime. Distribution : binaires précompilés via `cargo-dist` (Linux/macOS/Windows × x86_64/arm64) + `cargo install` pour les utilisateurs Rust.
|
||
|
||
---
|
||
|
||
## 6. Performances cibles
|
||
|
||
Cibles basées sur Spinoza single-thread sur laptop moderne (M-series ou Ryzen équivalent) :
|
||
|
||
| Circuit | Cible |
|
||
|---------|-------|
|
||
| Bell (2 qubits, 2 gates, 1024 shots) | **< 5 ms** |
|
||
| 10 qubits / 50 gates / 10k shots | **< 50 ms** |
|
||
| 20 qubits / 100 gates / 10k shots | **< 500 ms** |
|
||
| 25 qubits / 100 gates / 1k shots | **< 5 s** |
|
||
| Limite pratique RAM 16 Go | **28 qubits** |
|
||
|
||
Mode `--f32` optionnel pour +30% de vitesse et +1 qubit à RAM égale (perte de précision négligeable pour les counts en pratique).
|
||
|
||
---
|
||
|
||
## 7. Structure de fichiers
|
||
|
||
```
|
||
quantum-bridge-mcp/
|
||
├── src/
|
||
│ ├── main.rs # Point d'entrée, MCP server stdio (rmcp)
|
||
│ ├── tools/
|
||
│ │ ├── mod.rs
|
||
│ │ ├── list_backends.rs
|
||
│ │ ├── validate_circuit.rs
|
||
│ │ └── run_circuit.rs
|
||
│ ├── validator.rs # Wrapper oq3_semantics
|
||
│ ├── executor.rs # AST → Spinoza
|
||
│ └── error.rs # Diagnostics structurés
|
||
├── tests/
|
||
│ ├── integration/ # Tests intégration MCP
|
||
│ ├── reference/ # Circuits QASM3 + résultats Qiskit attendus
|
||
│ └── proptest/ # Property-based tests
|
||
├── benches/ # Benchmarks Criterion
|
||
├── scripts/
|
||
│ └── gen_reference.py # Génère counts/statevectors via Qiskit Aer
|
||
├── Cargo.toml
|
||
├── .github/workflows/
|
||
│ ├── ci.yml # Tests Rust + cross-validation Qiskit
|
||
│ └── release.yml # cargo-dist
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 8. Stratégie de tests
|
||
|
||
Sept couches, du plus déterministe au plus statistique :
|
||
|
||
1. **Unit tests gates** — chaque gate appliquée à un état initial connu produit le statevector exact attendu (tolérance 1e-10).
|
||
|
||
2. **Tests statistiques counts** — circuits canoniques (Bell, GHZ, superposition uniforme) exécutés en N=10k shots, comparaison aux distributions attendues via test du chi² (α=0.01).
|
||
|
||
3. **Cross-validation Qiskit** *(critique)* — un dossier `tests/reference/` contient ~30 circuits QASM3 avec leurs statevectors et counts pré-calculés via Qiskit Aer (script Python séparé, exécuté en CI). Comparaison bit-à-bit du statevector (tolérance 1e-10) et statistique des counts. **Indispensable** pour rattraper les bugs d'endianness / ordre de qubits.
|
||
|
||
4. **Property-based tests** (`proptest`) — invariants : `U·U† = I`, `Σ|amplitudes|² = 1`, idempotence des mesures pures.
|
||
|
||
5. **Tests de validation** — golden tests : dossier de fichiers QASM3 invalides + messages d'erreur exacts attendus. Couvre : qubit hors range, gate non supportée, mesure mal mappée, syntaxe invalide.
|
||
|
||
6. **Tests protocole MCP** — roundtrip JSON-RPC sur mock stdio, conformité schéma tools, format erreurs MCP.
|
||
|
||
7. **Smoke perf** (Criterion) — Bell < 5 ms, 20 qubits / 100 gates < 500 ms, alarmes si régression > 20%.
|
||
|
||
CI : Rust toolchain + Python 3.11 + Qiskit Aer pour la couche 3 (Python utilisé **uniquement** en CI, jamais runtime).
|
||
|
||
---
|
||
|
||
## 9. Distribution
|
||
|
||
| Cible | Méthode | Audience |
|
||
|-------|---------|----------|
|
||
| `cargo install quantum-bridge-mcp` | crates.io | Utilisateurs Rust |
|
||
| Binaires précompilés | GitHub Releases via `cargo-dist` | Cible principale (devs sans Rust) |
|
||
| Installer one-liner | `curl ... \| sh` | Setup rapide depuis README Claude |
|
||
| Homebrew tap | `brew install vbourdon/tap/quantum-bridge-mcp` | macOS power users (post-V1) |
|
||
|
||
Targets de build : `x86_64-unknown-linux-gnu`, `aarch64-unknown-linux-gnu`, `x86_64-apple-darwin`, `aarch64-apple-darwin`, `x86_64-pc-windows-msvc`.
|
||
|
||
---
|
||
|
||
## 10. Critères de succès V1
|
||
|
||
- [ ] Binaire installable sans Rust toolchain sur Linux/macOS/Windows
|
||
- [ ] Bell state < 5 ms sur laptop moderne
|
||
- [ ] 20 qubits / 100 gates / 10k shots < 500 ms
|
||
- [ ] Les 3 outils MCP sont opérationnels et conformes au protocole
|
||
- [ ] Validation produit des messages d'erreur actionnables (ligne, colonne, suggestion)
|
||
- [ ] Cross-validation Qiskit passe sur les 30 circuits de référence
|
||
- [ ] README avec exemple d'usage Claude Code end-to-end
|
||
- [ ] CI verte (lint, tests Rust, cross-validation Qiskit)
|
||
|
||
---
|
||
|
||
## 11. Hors scope V1 (pour mémoire)
|
||
|
||
Repoussé en V1.5 :
|
||
- Backend IBM Quantum (token utilisateur, REST API ou Qiskit Runtime)
|
||
- Mode asynchrone (`submit_circuit` / `get_job_status` / `get_results`)
|
||
- Persistence des job_ids (sled ou JSON file dans `~/.local/share/quantum-bridge-mcp/`)
|
||
- `select_backend` / `estimate_cost`
|
||
- Gestion d'erreurs réseau, retry, backoff
|
||
|
||
Repoussé en V2+ :
|
||
- Simulation avec bruit (decoherence, gate errors, readout errors)
|
||
- Simulation par densité matricielle
|
||
- Autres providers quantiques (AWS Braket, Azure Quantum, IonQ)
|
||
- Monétisation / système de licences
|
||
- Dashboard web d'usage
|
||
- Support OpenQASM 2.0 (le standard a basculé sur 3.0)
|
||
|
||
---
|
||
|
||
## 12. Risques identifiés
|
||
|
||
| Risque | Mitigation |
|
||
|--------|------------|
|
||
| `oq3_semantics` mal documenté ou incomplet sur certaines features QASM3 | POC parsing dès la 1ère semaine, fallback sur `jlapeyre/openqasm-rust` si bloquant |
|
||
| Spinoza API instable ou licence ambiguë | Vérifier licence (Apache 2.0 attendu) avant intégration ; alternative roqoqo identifiée |
|
||
| MCP officiel IBM cannibalise le projet | Le positionnement « binaire léger » reste défendable ; surveiller leur roadmap |
|
||
| Bugs d'endianness silencieux | Cross-validation Qiskit obligatoire en CI dès le début |
|
||
| RAM saturée à 28+ qubits chez user | Limite configurable, message d'erreur clair suggérant V1.5/IBM |
|