QDSV Bridge Developer Preview

Current package version: 0.1.7.

Documentation site: https://qdsvquantum-afk.github.io/qdsv-bridge/

QDSV Bridge is a lightweight Python client SDK for a controlled semantic-to-circuit bridge built on QDSV - Quantum Declarative Semantic Value.

It turns supported problem-family specifications into canonical QDSV ProblemSpec/IR, executable QASM/Qiskit circuit materializations, oracle specs or expert construction inputs.

Bridge never labels a scaffold as a completed circuit. Circuit exports are produced through the same canonical QDSV materializer used by the Aer and IBM hardware routes. A circuit request must provide computable semantics through compact prepared_candidates plus a structured threshold, or through a canonical goal.predicate_ir. Otherwise Bridge returns expert semantic inputs or rejects the circuit export explicitly.

The public developer preview is available without an API key:

from qdsv_bridge import QDSVBridgeClient

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

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

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

QDSV Bridge is not a template selector and not a free arbitrary circuit generator. Its core rule is:

do not force the problem into a prefabricated circuit;
derive the circuit or construction inputs from the semantic problem specification.

Choose A Delivery Mode

Bridge has one SDK with four delivery modes. Choose the mode by the output you need, not by creating a different kind of project.

First choose the problem family in spec["family"], then choose how much control you want over the returned artifact:

If you are not sure where to start, use:

result = client.generate(spec)  # basic

If you want to inspect or route the artifact into Qiskit, Braket or another OpenQASM-oriented workflow, use:

result = client.build(spec)  # intermediate/developer

Expert users have two separate routes: prepare when they want semantic construction ingredients, and evaluate when they want to compare possible materializations.

5 Minute Quickstart

Install the SDK:

pip install qdsv-bridge

For the optional Qiskit artifact inspection path:

pip install "qdsv-bridge[qiskit]"

The Qiskit extra is intentionally version-capped to the current supported major series (qiskit>=2,<3) to follow Qiskit Ecosystem compatibility guidance.

Build a QASM3 artifact from a compact semantic spec. No key is required in the public preview:

from qdsv_bridge import QDSVBridgeClient

client = QDSVBridgeClient()

spec = {
    "family": "bounded_semantic_marking",
    "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", "influence": 1, "priority": 1}
        ],
    },
    "target": {
        "format": "qasm3",
        "backend_family": "qiskit",
    },
    "limits": {
        "max_qubits": 8,
        "max_depth": 160,
    },
}

result = client.generate(spec)  # basic-user mode

print(result["status"])
print(result["bridge_mode"])
print(result["circuit_origin"])
print(result["artifact"]["format"])
print(result["materialization_evidence"]["formula_evaluated_on"])
print(result["materialization_evidence"]["candidate_precomputed"])

For a developer-oriented package with oracle spec, IR summary, digests and preservation evidence:

result = client.build(spec)

print(result["editable_artifacts"]["oracle_spec"])
print(result["editable_artifacts"]["ir_summary"])
print(result["digests"])

Colab Notebooks

Use these notebooks when you want to try Bridge without setting up a local project:

Each notebook follows the same route:

problem spec -> Bridge artifact -> shareable report

IBM/Qiskit Workflow

For Qiskit-oriented users, see the public integration guide:

• QDSV Bridge for IBM/Qiskit Workflows
• Open 04 IBM/Qiskit Artifact Demo

Amazon Braket OpenQASM Workflow

For Braket-oriented users, see the public OpenQASM integration guide:

• QDSV Bridge for Amazon Braket OpenQASM Workflows
• Amazon Braket Community Submission Path
• Open 05 AWS Braket OpenQASM Demo

QDSV Bridge exports OpenQASM artifacts that can be inspected and executed in Braket-oriented workflows using the Amazon Braket SDK and LocalSimulator. This is not an official Amazon Braket integration and does not include managed AWS hardware execution.

OpenQASM-First Interoperability

For a provider-neutral view of the Bridge artifact handoff, see:

• QDSV Bridge OpenQASM-First Interoperability

Bridge uses OpenQASM as a public artifact boundary between controlled semantic problem specifications and framework-specific workflows such as Qiskit or Amazon Braket.

Default cloud endpoint:

https://api.qdsv.cloud/api

Private/local Docker endpoint:

client = QDSVBridgeClient.local()

What This Is

• A client SDK for QDSV Bridge.
• A controlled interface to the canonical QDSV ProblemSpec/IR circuit materializer.
• A way to request QDSV IR, oracle specs, QASM/Qiskit artifacts or expert construction inputs.
• A way to generate shareable Bridge Reports in JSON, Markdown or HTML.
• A bridge for users who need circuit ecosystems but do not want to start from prebuilt templates.

What This Is Not

• It is not the private QDSV Runtime.
• It is not a bulk data processing SDK.
• It is not a hardware execution SDK.
• It is not an arbitrary circuit generator.
• It is not a selector of prefabricated circuit templates.
• It does not expose CAP, backend selection heuristics, private lowering internals, QuEST/Aer/IBM adapters, secrets or production configuration.

Why This Exists

Traditional quantum workflows often start by asking users to choose a circuit, encoding, ansatz or measurement pattern. That can force the data to adapt to a circuit.

QDSV Bridge starts from a controlled semantic family. The family defines what kind of problem is allowed, what concepts belong to it, what patterns are excluded and what evidence must be produced.

problem family spec
-> family ontology validation
-> semantic ProblemSpec / IR
-> oracle specification
-> materialization policy
-> generated circuit artifact or expert construction inputs

For users who want a simpler starting point, Bridge can generate executable problem-derived circuits when the specification includes computable prepared signals or a canonical predicate. It refuses to present incomplete blueprints as completed circuits.

For expert constructors, Bridge can also return the key semantic inputs needed to design a custom circuit without forcing a final circuit.

Bridge Modes

QDSV Bridge is one SDK with multiple output depths. The modes do not change the core principle: a circuit is delivered only after canonical QDSV ProblemSpec/IR materialization succeeds.

Python helpers:

client.generate(spec)  # mode="use"
client.build(spec)     # mode="build"
client.prepare(spec)   # mode="expert_prepare"
client.evaluate(spec)  # mode="expert_evaluate"

Explicit mode:

client.export(spec, mode="build")
client.explain(spec, mode="expert_prepare")

CLI:

qdsv-bridge export spec.json --mode use
qdsv-bridge export spec.json --mode build
qdsv-bridge export spec.json --mode expert_prepare
qdsv-bridge export spec.json --mode expert_evaluate
qdsv-bridge report spec.json --mode build --format markdown --output bridge_report.md

Every export response should include traceability metadata:

{
  "mode": "use | build | expert_prepare | expert_evaluate",
  "artifact_type": "qasm3",
  "circuit_origin": "qdsv_canonical_problem_ir_materializer",
  "semantic_preservation": {"status": "verified_canonical_materialization", "score": null},
  "materialization_evidence": {
    "formula_evaluated_on": "qpu_circuit",
    "candidate_precomputed": false,
    "precomputed_result_table": false
  },
  "warnings": [],
  "digests": {}
}

Examples By User Type

Basic user:

result = client.generate(spec)
print(result["circuit_origin"])          # qdsv_canonical_problem_ir_materializer
print(result["circuit"]["status"])       # materialized_from_canonical_problem_ir
print(result["ready_to_run_example"])

Intermediate developer:

result = client.build(spec)
print(result["artifact"]["format"])
print(result["editable_artifacts"]["oracle_spec"])
print(result["editable_artifacts"]["ir_summary"])
print(result["digests"])

Expert constructor:

inputs = client.prepare(spec)
print(inputs["expert_inputs"]["encoding_suggestions"])
print(inputs["expert_inputs"]["measurement_suggestions"])

Expert evaluator:

comparison = client.evaluate(spec)
print(comparison["materialization_variants"])
print(comparison["comparison"])

Supported Families

Developer Preview families:

bounded_semantic_marking is the controlled fallback family. Use it when the problem is finite, bounded and semantic, but no specialized Bridge family exists yet.

It is not a universal free-form mode: it still requires a bounded state space, declared goal, limits, excluded patterns and preservation reporting.

Current executable-circuit boundary:

• bounded_semantic_marking, semantic_signal_classification and predicate_marking can use the coherent formula route when supplied with compact prepared_candidates and a structured threshold;
• bounded families can use the canonical finite-domain route when supplied with goal.predicate_ir;
• other family/mode combinations remain expert semantic inputs until a canonical materializer exists;
• Bridge returns an explicit error rather than substituting a uniform-superposition scaffold.

Each family has:

• ontology boundary;
• allowed state-space kinds;
• allowed goal kinds;
• allowed semantic operations;
• excluded patterns;
• public limits;
• export targets;
• evidence / digest contract.

Fallback example:

spec = {
    "family": "bounded_semantic_marking",
    "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", "influence": 1, "priority": 1}
        ],
    },
    "target": {
        "format": "qasm3",
        "backend_family": "qiskit",
    },
    "limits": {
        "max_qubits": 8,
        "max_depth": 160,
    },
}

result = client.build(spec)
print(result["family"])
print(result["circuit_origin"])
print(result["warnings"])

What It Exports

Depending on target.format, QDSV Bridge can export:

• problem_spec
• ir
• oracle_spec
• qasm2
• qasm3
• qiskit_blueprint

Bridge Report

Bridge Report turns the same auditable export package into a document users can share, attach to technical notes or keep as reproducibility evidence.

Supported report formats:

• json
• markdown
• html

Python:

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

CLI:

qdsv-bridge report spec.json --mode build --format markdown --output bridge_report.md
qdsv-bridge report spec.json --mode build --format html --output bridge_report.html
qdsv-bridge report spec.json --mode build --format json --output bridge_report.json

Each Bridge Report includes:

1. Problem and deliverable contract.
2. Family and mode used.
3. Validations and canonical materialization evidence.
4. Generated executable QASM/Qiskit content when requested.
5. Circuit policy and template-use status.
6. Digests.
7. Resource limits and warnings.
8. Reproducibility metadata.

Bridge Report is the public trust document for Bridge: it makes clear what was derived, what was preserved, what was warned about and which digests identify the exported artifacts.

For use and build, circuit-oriented targets return a circuit only when canonical QDSV materialization succeeds, together with formula/oracle digests and actual circuit metrics.

Bridge does not insert placeholder oracle comments and call them completed circuits. Incomplete specifications must use expert_prepare or add computable semantic inputs.

For expert_prepare, Bridge may intentionally return construction inputs instead of forcing a final circuit. This is useful when an expert wants to design a custom circuit with the correct semantic ingredients.

Public Endpoints

The SDK calls the QDSV API:

• GET /api/bridge/families
• POST /api/bridge/validate
• POST /api/bridge/compile
• POST /api/bridge/explain
• POST /api/bridge/export
• POST /api/bridge/report

Default cloud endpoint:

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

Local/private Docker endpoint:

client = QDSVBridgeClient.local()

Public informational endpoints such as families() are open. Developer Preview value-producing operations can be used without an API key and are limited by rate limits, payload limits and a demo quota per caller bucket. Deployments can optionally enable API-key-only access for partners, pilots or private environments.

Resource And Multi-User Limits

QDSV Bridge accepts compact semantic problem specifications and small prepared numeric signal tables, not raw datasets.

Do not send:

• full CSV files;
• raw datasets;
• thousands of rows;
• sensitive records;
• training data;
• hardware execution requests.

Send:

• problem family;
• finite state-space size;
• prepared signal or variable names;
• goal / predicate / ranking intent;
• target format;
• qubit/depth limits;
• materialization policy.
• compact prepared_candidates containing only the bounded numeric signals required by the formula, when requesting a coherent circuit;
• or a canonical goal.predicate_ir for bounded predicate materialization.

Public API minimum limits:

Default API rate limits may be configured by the QDSV deployment:

• families: 60/minute
• validate: 30/minute
• compile: 20/minute
• explain: 20/minute
• export: 10/minute
• report: 10/minute

Rate limits use Authorization, x-api-key or x-license-key when present. Otherwise they fall back to IP plus SDK name.

API keys are optional for the open Developer Preview path. They become useful for higher quotas, partner access, private pilots, usage attribution or deployments configured with QDSV_BRIDGE_API_KEY_REQUIRED=true.

In the current public deployment, rate limiting is in-memory per API instance. If Cloud Run scales to multiple instances, the effective limit may multiply until a distributed rate-limit store is enabled.

The SDK itself is stateless and does not block multiple users. Multi-user control, quotas, optional API keys, license checks and history belong to the QDSV/Qruba API deployment, not to the local Python package.

Raw dataset payloads are rejected:

{
  "detail": {
    "error_code": "E_BRIDGE_RAW_DATA_NOT_ALLOWED",
    "message": "Raw datasets are not allowed in Bridge specs. Provide semantic signals, predicates, candidates, or summarized problem structure instead.",
    "detail": {
      "forbidden_fields": ["rows"]
    }
  }
}

Examples And Roadmap

• Examples
• Roadmap
• QDSV model site
• Qruba Cloud
• PyPI

Current public artifact targets are problem_spec, ir, oracle_spec, qasm2, qasm3 and qiskit_blueprint.

PennyLane, Azure Quantum/Q#, Cirq, VS Code, TypeScript clients, Amazon Braket managed hardware execution and packaged NISQ recipes such as QUBO/QAOA/VQE/Grover are planned integrations or higher-level examples. They should not be described as current public Bridge capabilities.

Important Boundaries

QDSV Bridge does not expose:

• QDSV Runtime internals;
• CAP internals;
• backend selection heuristics;
• private QuEST/Aer/IBM adapters;
• native lowering internals;
• unrestricted circuit generation;
• arbitrary Python execution;
• prefabricated circuit selection as the main product;
• user-supplied free circuits as family contracts.

Product principle:

controlled semantic family
-> canonical ProblemSpec / IR
-> executable circuit materialization or expert inputs
-> auditable export

Not:

any input -> arbitrary circuit

Open SDK, Private Runtime

This repository is open-core:

• Open under MIT: Python client SDK, examples, docs and tests.
• Not included: QDSV Runtime, ontology compiler internals, CAP, lowering, advanced materialization, backend adapters, private endpoints, secrets or production configuration.

QDSV, QIntent and Qruba names and marks are project marks of their respective owners. The MIT License for this repository does not grant trademark rights.