Getting Started¶

Installation¶

Install QDSV Bridge from PyPI:

pip install qdsv-bridge

For optional Qiskit artifact inspection:

pip install "qdsv-bridge[qiskit]"

The Qiskit extra is version-capped to the current supported major series (qiskit>=2,<3) to preserve compatibility with the currently tested Qiskit major version.

Create a client for the public developer preview:

from qdsv_bridge import QDSVBridgeClient

client = QDSVBridgeClient()

Use a private/local Docker node only when you are running QDSV privately:

client = QDSVBridgeClient.local()

First Artifact¶

Use generate for the simplest delivery mode:

spec = {
    "state_space": {
        "kind": "finite_candidates",
        "candidate_count": 2,
        "candidate_id": "candidate",
    },
    "signals": ["eligibility_score"],
    "prepared_candidates": [
        {"eligibility_score": 0},
        {"eligibility_score": 1},
    ],
    "goal": {
        "kind": "marking",
        "threshold": 1,
        "criteria": [
            {"signal": "eligibility_score", "importance": 1, "priority": 1}
        ],
    },
    "target": {
        "format": "qasm3",
        "backend_family": "qiskit",
    },
    "limits": {
        "max_qubits": 8,
        "max_depth": 160,
    },
}

result = client.generate(spec)

print(result["status"])
print(result["bridge_mode"])
print(result["artifact"]["format"])
print(result["construction_verification"])

Delivery Modes¶

Bridge has one SDK with four delivery modes:

generate for users who want canonically materialized, ready-to-run circuits.
build for executable OpenQASM/Qiskit artifacts plus materialization evidence.
prepare for expert semantic construction inputs.
evaluate for the actual materialization evidence plus explicitly labeled conceptual alternatives. It evaluates construction evidence; it does not execute a circuit or claim a simulator/QPU comparison.

generate and build reject incomplete circuit specifications. They never replace the semantic oracle with a placeholder scaffold.

Materialization is capability-driven. The optional legacy family field is only a descriptive compatibility label. Use client.capabilities() to inspect the operation-level compiler boundary.

Construction verification¶

Every completed circuit includes a construction_verification passport. It records semantic validation, complete operation-graph coverage, reversible contract checks, no-precomputed-answer checks, actual resource enforcement and digest linkage. Bridge does not execute the artifact or validate the truth of the user’s domain model or data.