QDSV Bridge

Source/package version: 0.6.1. See the PyPI badge for publication status.

QDSV Bridge is a lightweight Python client SDK that converts supported semantic problem specifications into executable OpenQASM/Qiskit-compatible circuit artifacts or validated expert construction packages.

Circuit delivery is conditional on capability and resource validation. Bridge does not execute circuits, generate arbitrary circuits or embed precomputed answers.

• Documentation
• PyPI
• Source

Status And Scope

QDSV Bridge is a Developer Preview for bounded, problem-first circuit construction. The public service is provided without an SLA and may change or be temporarily unavailable.

Bridge validates the semantic-to-circuit construction path and reports the resources required by the generated artifact. It can also derive an exact, target-independent logical optimization and recommend it when contractual replay passes and protected logical metrics do not regress. It does not validate the user's domain assumptions, execute on a simulator or QPU, choose a provider, manage credentials, mitigate noise or interpret experimental results.

The public SDK supports Python 3.9 and later. Before 1.0, minor releases may introduce contract changes; deprecations and migration notes are recorded in the changelog.

Installation

Install the client:

pip install qdsv-bridge

Install the optional Qiskit inspection dependencies:

pip install "qdsv-bridge[qiskit]"

The Qiskit extra is capped at qiskit>=2,<3 to preserve compatibility with the currently tested Qiskit major version.

Quickstart

The public Developer Preview does not require an API key:

from qdsv_bridge import QDSVBridgeClient, select_recommended_artifact

client = QDSVBridgeClient()

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)
recommended = select_recommended_artifact(result)

print(result["status"])
print(result["artifact"]["role"])  # Canonical source of truth.
print(result["recommended_artifact_role"])
print(recommended["format"])
print(recommended["content"])
print(result["construction_verification"])

When materialization succeeds within the supported capability and resource limits, generate() returns the completed canonical circuit and loading guidance. Bridge also attempts the frozen qiskit_structural_exact_v1 logical profile by default. The canonical artifact is never replaced silently; select_recommended_artifact() returns the accepted optimized artifact when available and otherwise returns the canonical artifact.

The optimization is exact and target-independent. It does not perform layout, routing, scheduling, calibration-aware selection, noise suppression, mitigation or hardware execution. Those operations remain in Runtime/HSP.

For a minimal multi-criteria ScoreModel example, run examples/score_model_v2.py. Prepared metrics and the cutoff use one declared scale, and priority represents a domain priority, not the position of a criterion. The SDK example does not reproduce private ScoreModel aggregation or compiler rules.

Compound Business Predicates

Use build_predicate_spec() when the business rule is already an explicit, public predicate. The helper supports nested boolean composition and field-to-field comparisons while preserving candidate order. It translates the declared rule; it does not evaluate it or add expected answers.

from qdsv_bridge import QDSVBridgeClient, build_predicate_spec

rows = [
    {"quality": 800, "delivery": 700, "compliance": 1},
    {"quality": 720, "delivery": 600, "compliance": 1},
]
predicate = {
    "op": "and",
    "args": [
        {
            "op": "gte",
            "left": {"op": "field", "name": "quality"},
            "right": {"op": "const", "value": 700},
        },
        {
            "op": "gte",
            "left": {"op": "field", "name": "delivery"},
            "right": {"op": "const", "value": 650},
        },
        {
            "op": "eq",
            "left": {"op": "field", "name": "compliance"},
            "right": {"op": "const", "value": 1},
        },
    ],
}

spec = build_predicate_spec(rows=rows, predicate=predicate)
result = QDSVBridgeClient().generate(spec)

The complete runnable example is examples/compound_business_predicate.py. Do not include labels, expected decisions or precomputed predicate results in rows; only provide the prepared business inputs referenced by the predicate.

Ideal Circuit And Hardware Handoff

When Bridge materializes a circuit, the response includes a backend-neutral circuit_realization_package. It links the logical circuit to the canonical semantic, quantum and reversible-plan digests and includes the public result, measurement and decoder contracts.

package = result["circuit_realization_package"]

print(package["canonical_identity"])
print(package["logical_realization"])
print(package["validation"])
print(result["target_handoff"])

This package establishes what the canonical ideal circuit represents; it is not evidence that a specific QPU will preserve the ideal result. target_handoff states the remaining work for a real backend, including target transpilation, physical-resource review and any supported mitigation. Bridge does not apply those target-specific adjustments or execute the circuit.

For managed IBM execution, send the package through QDSV Runtime/HSP or Qruba's hardware flow. If you choose to run the artifact yourself, Bridge's handoff means: this is the ideal logical circuit; for IBM real hardware you must use Runtime/HSP or an equivalent user-controlled physical workflow.

Ideal dynamic replay is reported only when it was actually performed. resource_limited, not_run or unsupported remain explicit evidence states and are never promoted to passed.

Canonical And Optimized Logical Artifacts

result["artifact"] remains the immutable canonical artifact for backward compatibility and auditability. The optional result["optimized_logical_artifact"] is a child artifact linked to it by digest. Bridge recommends the child only when exact full-state replay, register and measurement preservation, valid-domain checks and the Pareto no-regression policy all pass.

canonical = result["artifact"]
recommended = select_recommended_artifact(result)

print(result["logical_optimization"]["resources_before"])
print(result["logical_optimization"]["resources_after"])
print(result["recommended_artifact_role"])

Set target.logical_optimization to false only when byte-for-byte canonical delivery is required. Basic users do not need to configure passes, logical bases or seeds.

Reproducible benchmarks can freeze the public profile explicitly. The bounded-predicate helper accepts the same contract:

spec = build_predicate_spec(
    rows=rows,
    predicate=predicate,
    logical_optimization={
        "mode": "auto",
        "profile": "qiskit_structural_exact_v1",
        "acceptance_policy": "pareto_no_regression_v1",
    },
)

mode, rather than an enabled field, is the versioned public switch. Custom passes, physical targets, layouts, routing and approximation settings are intentionally rejected.

Delivery Modes

Bridge uses one specification and offers four output depths:

evaluate() evaluates construction evidence. It does not execute the circuit on a simulator or QPU and does not compare runtime results.

Start By User Type

All four modes reuse the spec from the Quickstart. Users can begin with one call and move to a deeper delivery mode without redefining the problem.

Basic user - receive the completed quantum core and loading guidance:

result = client.generate(spec)
recommended = select_recommended_artifact(result)
print(recommended["content"])
print(result["ready_to_run_example"])

Intermediate developer - receive editable QASM/Qiskit artifacts and digests:

package = client.build(spec)
print(package["editable_artifacts"]["artifact_content"])
print(package["editable_artifacts"]["oracle_spec"])
print(package["digests"])

Expert constructor - receive the validated construction package without forcing a circuit:

prepared = client.prepare(spec)
inputs = prepared["expert_inputs"]
print(inputs["construction_status"])
print(inputs["relevant_variables"])
print(inputs["missing_capabilities"])
print(inputs["encoding_suggestions"])

Expert evaluator - review construction evidence and labeled alternatives without executing the circuit:

review = client.evaluate(spec)
print(review["construction_verification"])
print(review["materialization_evidence"])
print(review["construction_alternatives"])
print(review["comparison"]["comparative_execution_performed"])

Outputs And Outcomes

Supported public artifact targets are:

Circuit-oriented targets are returned only when the full supported construction succeeds. Typical outcomes are:

Handle API rejections explicitly:

from qdsv_bridge import QDSVBridgeAPIError, QDSVBridgeHTTPError

try:
    result = client.generate(spec)
except QDSVBridgeHTTPError as error:
    print(error.status_code)
    print(error.payload)
except QDSVBridgeAPIError as error:
    print(f"Bridge service unavailable: {error}")

The current operation catalog and service limits are available from:

catalog = client.capabilities()

For the detailed operation contract and ScoreModel v2 capabilities, see the technical documentation and ScoreModel tutorial.

Limits And Privacy

Bridge accepts compact semantic specifications and bounded prepared numeric inputs. It is not a bulk-data service and does not accept raw datasets or hardware-execution requests.

Public Preview limits are configurable and include payload, compilation time, artifact size, qubit and depth ceilings. A semantically valid problem may still be rejected when its materialized circuit exceeds the active resource limits. Query client.capabilities() for the current deployment contract.

Do not submit personal, confidential, regulated or security-sensitive data to the public preview. The public preview provides no contractual retention guarantee. Use a private deployment for sensitive workloads and review the security policy before reporting a vulnerability.

Default public endpoint:

client = QDSVBridgeClient()  # https://api.qdsv.cloud/api

Private/local endpoint for an existing QDSV Docker deployment:

client = QDSVBridgeClient.local()  # http://localhost:18080/api

Tested Compatibility

Bridge does not provide managed IBM Quantum or Amazon Braket hardware execution.

Integrations And Examples

• First Bridge workflow
• ScoreModel v2 circuit delivery
• IBM/Qiskit artifact workflow
• OpenQASM-first interoperability
• Amazon Braket LocalSimulator conversion
• Python examples
• Colab notebooks

The notebooks cover problem-first circuit delivery, expert construction inputs, Qiskit inspection and the tested Braket LocalSimulator conversion flow.

Reports

Bridge can render the same public construction evidence as JSON, Markdown or HTML:

report = client.report(spec, mode="build", format="markdown")
print(report["content"])

Reports identify the accepted specification, delivered artifact, warnings, resource evidence and digests. They do not claim simulator or hardware execution.

Support And Security

• General questions and defects: GitHub Issues
• Sensitive security reports: follow SECURITY.md; do not open a public issue
• Release history: CHANGELOG.md
• Roadmap: ROADMAP.md

License

The client SDK, examples, documentation and tests in this repository are licensed under the MIT License.

QDSV, QIntent and Qruba names and marks belong to their respective owners. The MIT License does not grant trademark rights.