@metaharness/example-qiskit

v0.2.0

Published

4 days ago

MetaHarness example — IBM Quantum / Qiskit Runtime agent scaffold: build + simulate quantum circuits locally before any hardware submission (npx @metaharness/example-qiskit my-bot)

Downloads

253

0High
0Medium
0Low

ruvnet

metaharness quantum-computing qiskit ibm-quantum qiskit-ibm-runtime ai-agent mcp npx scaffold openqasm quantum-circuit simulation ruqu

@metaharness/example-qiskit

Scaffold a MetaHarness agent pre-wired to IBM Quantum — build and simulate circuits locally before touching real hardware.

Illustrative output. The circuits, simulation results, and fidelity reports produced by this scaffold are illustrative examples generated by AI agents. They are not certified quantum computations. Local fake-backend results are noisy simulations; real QPU results require a paid IBM Quantum plan and are subject to queue times and hardware availability. Do not use this scaffold for production scientific, financial, or cryptographic workloads.

Intro

@metaharness/example-qiskit scaffolds an agent harness that translates natural-language quantum tasks into OpenQASM 3 circuits, simulates them locally (zero credentials required), validates circuit fidelity against a hardware-noise model, and — only when you explicitly opt in — submits a verified job to IBM Quantum Platform.

What it IS:

A one-command scaffold for a quantum-capable MetaHarness agent
A two-stage simulation gate (ideal statevector via ruqu_simulate then noisy fake-backend via IBM Qiskit Runtime's fake_provider) that runs entirely offline
A demonstration of MetaHarness tiered routing, MCP default-deny, slash commands, and verification-gated output applied to quantum computing

What it is NOT:

A replacement for the IBM Qiskit Runtime Python SDK (qiskit-ibm-runtime)
A production quantum computing framework or scientific instrument
A certified or NIST-compliant quantum tool
An official IBM product

Features

| MetaHarness capability | How it is shown | |---|---| | Tiered model routing (ADR-026) | Haiku handles REST calls and result parsing; Sonnet/Opus handles circuit planning and fidelity analysis | | MCP default-deny (ADR-022) | .harness/mcp-policy.json grants only 6 tools: ruqu_simulate, ruqu_verify, ruqu_replay, fetch, read_file, write_file — all others denied, all calls logged to .harness/mcp-audit.jsonl | | Slash command | /qiskit drives the full plan → simulate → verify pipeline | | Specialized agents | circuit-planner (NL to QASM, frontier tier) · sim-executor (REST calls + ruqu tools, cheap tier) · verify-reporter (fidelity gate, frontier tier) | | Verification gate (ADR-050) | Hardware submission is blocked until KL divergence between ideal and noisy distributions passes a configurable threshold; gate result written to .harness/output/verify-report.json |

Quantum-specific capabilities

| Capability | Notes | |---|---| | OpenQASM 3 circuit generation | Common patterns (Bell state, GHZ, variational ansatz) via Tier-1 WASM templates; arbitrary circuits via frontier-tier planning | | Ideal statevector simulation | ruqu_simulate (ruqu-mcp, n_qubits ≤ 16) — no credentials needed | | Noisy hardware simulation | IBM Qiskit Runtime FakeManilaV2 (5 qubits) or FakeBrisbane (127 qubits) noise snapshots via Python subprocess | | SamplerV2 bitstring distributions | Measurement sampling from noise model; results as bitstring count dictionaries | | EstimatorV2 expectation values | Pauli observable expectation values against a parameterised circuit | | Real QPU job submission | Opt-in only via --submit-to-hardware; requires QISKIT_IBM_TOKEN + QISKIT_IBM_INSTANCE | | Job status polling | IBM REST API GET /jobs/{id} polling until terminal state | | Circuit audit trail | Every circuit identified by content-derived SHA-256 ID; full audit in .harness/mcp-audit.jsonl |

Quickstart

npx @metaharness/example-qiskit@latest my-quantum-bot
cd my-quantum-bot
npm install
npm run doctor

npm run doctor checks for Node >=20, verifies the ruqu-mcp server is reachable, and confirms that Python + qiskit-ibm-runtime are available (or warns that local-only mode will be used).

To scaffold for a specific host:

# Default: Claude Code
npx @metaharness/example-qiskit@latest my-quantum-bot

# Codex, Copilot, GitHub Actions, etc.
npx @metaharness/example-qiskit@latest my-quantum-bot --host copilot
npx @metaharness/example-qiskit@latest my-quantum-bot --host github-actions

# All hosts at once
npx @metaharness/example-qiskit@latest my-quantum-bot --host all

Configuration

Environment variables

| Variable | Required for | Where to get it | |---|---|---| | QISKIT_IBM_TOKEN | IBM hardware access and backend listing | IBM Quantum Platform → Account → API keys | | QISKIT_IBM_INSTANCE | IBM hardware access | IBM Cloud console → Quantum Computing → Service instance → CRN | | QISKIT_IBM_CHANNEL | Optional, defaults to ibm_quantum_platform | Set to ibm_quantum_platform (recommended) or ibm_cloud | | IQP_API_TOKEN | Direct REST API calls (same 44-character key as QISKIT_IBM_TOKEN) | Same source as above |

None of these are required for local simulation. When all are absent the harness runs in local-only mode using ruqu_simulate and Python fake backends — no network calls, no credentials, no QPU minutes spent.

Sandbox / test mode

IBM Quantum Platform does not offer a separate sandbox tier with test credentials (unlike Stripe or Twilio). Safety is achieved structurally:

Default: all simulation is local (ruqu_simulate + FakeManilaV2 noise model). No IBM network call is made.
Read-only cloud probe: with credentials set, GET /backends is called to list available backends. This is read-only and has no cost.
Hardware submission: gated behind --submit-to-hardware. This is the only call with cost or queue implications.

To use the harness safely without IBM credentials, simply omit all env vars. Local simulation is always available and produces meaningful fidelity results.

# Full local-only run — zero credentials, zero cost
/qiskit "Prepare a Bell state and measure both qubits"

# Cloud-enabled, read-only backend listing (credentials required)
/qiskit "List available IBM quantum backends" --list-backends

# Hardware submission (explicit opt-in, credentials required)
/qiskit "Run Bell state on ibm_brisbane" --submit-to-hardware

Usage

Slash command

/qiskit <natural-language circuit description> [--backend <name>] [--shots <n>] [--submit-to-hardware]

Examples:

/qiskit "Prepare a 2-qubit Bell state and measure"
/qiskit "Build a 3-qubit GHZ state" --shots 2048
/qiskit "Estimate <ZZ> expectation value for a parameterised ansatz"
/qiskit "Run my Bell circuit on ibm_manila" --submit-to-hardware

Pipeline stages:

circuit-planner (frontier tier) translates the description to an OpenQASM 3 string
sim-executor (cheap tier) calls ruqu_simulate for ideal statevector probabilities
sim-executor calls the Python fake backend (or IBM REST API for hardware) for noisy SamplerV2 bitstring distributions
verify-reporter (frontier tier) computes KL divergence, checks against the fidelity threshold (default 0.05), and writes .harness/output/verify-report.json
If --submit-to-hardware was passed and the gate passes, sim-executor submits the job and polls GET /jobs/{id} to completion

Representative prompts

Create a 5-qubit Quantum Fourier Transform circuit and simulate it locally — show me the probability distribution.

Build a variational ansatz with 3 qubits and 2 layers, estimate the <ZZI> + <IZZ> observable, and check fidelity against FakeManilaV2.

List all available IBM Quantum backends sorted by qubit count.

Safety

Secrets via environment only. No token, key, or CRN value is ever written to a scaffolded file. .harness/ and .env are listed in the generated .gitignore.
Local simulation by default. Hardware submission requires --submit-to-hardware. Without this flag, the harness never calls POST /jobs.
Qubit limit enforced. ruqu_simulate rejects circuits with more than 16 qubits (ruqu-mcp v0.0 spec limit). Circuits above this limit are flagged before any IBM call.
MCP surface is minimal. Only 6 MCP tools are granted (see How it works). All invocations are logged.
Not for production. This example is illustrative. Quantum computing results are probabilistic; fake-backend noise models are approximations of real QPU behaviour, not certified reproductions. Do not use this scaffold for production scientific, financial, pharmaceutical, or cryptographic workloads.

How it works

Agents

circuit-planner  ──(QASM string)──▶  sim-executor  ──(results)──▶  verify-reporter
   [Sonnet/Opus]                        [Haiku]                       [Sonnet/Opus]
        │                                   │                               │
   NL → QASM                       ruqu_simulate                   KL divergence gate
   parameter manifest               FakeManilaV2                   verify-report.json
                                    IBM REST API                    hardware go/no-go

Routing tiers

| Tier | Model | Tasks | |---|---|---| | 1 — WASM booster | <1ms, $0 | Template Bell/GHZ/QFT QASM strings without LLM | | 2 — Haiku | ~500ms, ~$0.0002 | REST call formatting, JSON parsing, bitstring distribution tabulation | | 3 — Sonnet/Opus | 2–5s, ~$0.003–0.015 | NL circuit planning, fidelity analysis, gate decision, final report |

MCP policy — granted tools

{
  "default": "deny",
  "audit_log": ".harness/mcp-audit.jsonl",
  "grants": [
    { "tool": "ruqu_simulate",  "reason": "local statevector simulation — no hardware, no credentials" },
    { "tool": "ruqu_verify",    "reason": "circuit structure validation and audit-code checking" },
    { "tool": "ruqu_replay",    "reason": "deterministic re-execution for verification gate" },
    { "tool": "fetch",          "reason": "IBM Quantum REST API calls (backends, job submit, job status)" },
    { "tool": "read_file",      "reason": "read QASM circuit files from working directory" },
    { "tool": "write_file",     "reason": "write simulation results and circuit artefacts to .harness/output/" }
  ]
}

All other MCP tools are denied. Every granted-tool invocation is appended to .harness/mcp-audit.jsonl with timestamp, tool name, content-derived circuit ID, and result summary.

Verification gate

The gate in verify-reporter computes the KL divergence between the ideal probability distribution (from ruqu_simulate) and the noisy bitstring distribution (from SamplerV2 on FakeManilaV2). If divergence exceeds the threshold (default 0.05, configurable via QISKIT_FIDELITY_THRESHOLD), the gate fails and hardware submission is blocked regardless of flags. The full gate report is written to .harness/output/verify-report.json.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@metaharness/example-qiskit

Intro

Features

Quantum-specific capabilities

Quickstart

Configuration

Environment variables

Sandbox / test mode

Usage

Slash command

Representative prompts

Safety

How it works

Agents

Routing tiers

MCP policy — granted tools

Verification gate

Links