API Reference¶

Client¶

class qdsv_bridge.QDSVBridgeClient(api_url=None, api_key=None, *, timeout=30.0, max_retries=2, retry_backoff=0.25, license_key=None, sdk_name='qdsv-bridge')¶

Bases: object

Client for QDSV Bridge public API endpoints.

Parameters:

api_url (str | None)
api_key (str | None)
timeout (float)
max_retries (int)
retry_backoff (float)
license_key (str | None)
sdk_name (str)

build(spec)¶

Return logical artifacts, editable views, evidence and digests.

Parameters:: spec (Mapping[str, Any])
Return type:: dict[str, Any]

capabilities()¶

Return operation-level compiler capabilities and service limits.

Return type:: dict[str, Any]

compile(spec, *, mode=None)¶

Parameters:

spec (Mapping[str, Any])
mode (str | None)

Return type:

dict[str, Any]

composition_capabilities()¶

Return Semantic Composition Engine publication and evidence policy.

The SCE lives in the Bridge service. The SDK only requests public capabilities and candidate packages; it does not contain or run the private compiler.

Return type:: dict[str, Any]

explain(spec, *, mode=None)¶

Parameters:

spec (Mapping[str, Any])
mode (str | None)

Return type:

dict[str, Any]

export(spec, *, mode=None)¶

Parameters:

spec (Mapping[str, Any])
mode (str | None)

Return type:

dict[str, Any]

families()¶

Compatibility alias for the capability catalog endpoint.

Return type:: dict[str, Any]

generate(spec)¶

Generate a canonical circuit and optional validated logical child.

Parameters:: spec (Mapping[str, Any])
Return type:: dict[str, Any]

generate_composition_candidate(*, name, expression, domains=None, description=None, source=None, publication_target='internal_candidate', semantic_cross_check_max_cases=None)¶

Generate a composite operation candidate through the Bridge backend.

OFFICIAL_CANDIDATE requires server-side operation-program verification plus semantic cross-check over the declared finite domain. Reference outputs may be used for verification evidence, but not for materialization.

Parameters:

name (str)
expression (Mapping[str, Any])
domains (list[Mapping[str, Any]] | None)
description (str | None)
source (str | None)
publication_target (str)
semantic_cross_check_max_cases (int | None)

Return type:

dict[str, Any]

classmethod local(*, api_url='http://localhost:18080/api', api_key=None, timeout=30.0, max_retries=2, retry_backoff=0.25, license_key=None)¶

Parameters:

api_url (str)
api_key (str | None)
timeout (float)
max_retries (int)
retry_backoff (float)
license_key (str | None)

Return type:

QDSVBridgeClient

report(spec, *, mode=None, format='markdown')¶

Generate a shareable Bridge Report in markdown, html or json format.

Parameters:

spec (Mapping[str, Any])
mode (str | None)
format (str)

Return type:

dict[str, Any]

validate(spec, *, mode=None)¶

Parameters:

spec (Mapping[str, Any])
mode (str | None)

Return type:

dict[str, Any]

Domain Requests¶

qdsv_bridge.predicate_request(*, candidates, rule, candidate_id_field='candidate_index', format='qasm3', framework='qiskit', mode='build', shots=1024, max_qubits=None, max_depth=None, logical_optimization=True, metadata=None)¶

Create a bounded predicate request without constructing a circuit.

Parameters:

candidates (Sequence[Mapping[str, Any]])
rule (Mapping[str, Any])
candidate_id_field (str)
format (str)
framework (str)
mode (str)
shots (int)
max_qubits (int | None)
max_depth (int | None)
logical_optimization (bool | Mapping[str, Any])
metadata (Mapping[str, Any] | None)

Return type:

dict[str, Any]

qdsv_bridge.score_request(*, candidates, decision, criteria=None, groups=None, candidate_id_field='candidate_index', format='qasm3', framework='qiskit', mode='build', shots=1024, penalty=0, numeric_preferences=None, max_qubits=None, max_depth=None, logical_optimization=True, metadata=None)¶

Create a bounded multi-criterion decision request without computing scores.

Parameters:

candidates (Sequence[Mapping[str, Any]])
decision (Mapping[str, Any])
criteria (Sequence[Mapping[str, Any]] | None)
groups (Sequence[Mapping[str, Any]] | None)
candidate_id_field (str)
format (str)
framework (str)
mode (str)
shots (int)
penalty (Any)
numeric_preferences (Mapping[str, Any] | None)
max_qubits (int | None)
max_depth (int | None)
logical_optimization (bool | Mapping[str, Any])
metadata (Mapping[str, Any] | None)

Return type:

dict[str, Any]

Qiskit Adapter¶

class qdsv_bridge.QDSVBridge(client=None)¶

Explicit Bridge-to-Qiskit facade.

Calling export() is the only remote operation. Circuit loading is separate and works only on the verified public artifact returned by that call. The facade rejects non-domain-v1 input rather than accepting any lower-level representation.

Parameters:: client (QDSVBridgeClient | None)

export(request, *, mode=None)¶

Request a public artifact from QDSV and verify its delivery digest.

Parameters:

request (Mapping[str, Any])
mode (str | None)

Return type:

QDSVBridgeArtifact

materialize(request, *, mode=None)¶

Explicitly export from Bridge, verify bytes, then return a QuantumCircuit.

Parameters:

request (Mapping[str, Any])
mode (str | None)

Return type:

Any

class qdsv_bridge.QDSVBridgeArtifact(content, format, language, request_digest, artifact_digest, compiler_build_digest, resources, warnings)¶

A verified public OpenQASM artifact delivered by Bridge.

Instances are created only from an export response whose public artifact digest matches the exact delivered OpenQASM bytes.

Parameters:

content (str)
format (str)
language (str)
request_digest (str)
artifact_digest (str)
compiler_build_digest (str)
resources (Mapping[str, Any])
warnings (tuple[str, ...])

classmethod from_public_response(response)¶

Validate a frozen 0.7 public export response before local parsing.

Parameters:: response (Mapping[str, Any])
Return type:: QDSVBridgeArtifact

to_quantum_circuit()¶

Load this already verified artifact into QuantumCircuit.

This method never calls Bridge or any other network service.

Return type:: Any

qdsv_bridge.to_quantum_circuit(response)¶

Compatibility helper that verifies then loads a public export response.

Parameters:: response (Mapping[str, Any])
Return type:: Any

Compatibility Helpers¶

qdsv_bridge.to_braket_openqasm(source)¶

Convert a canonical Bridge QASM3 artifact for Braket execution.

Parameters:: source (str)
Return type:: str

Exceptions¶

class qdsv_bridge.QDSVBridgeError¶: Base exception for the QDSV Bridge SDK.

class qdsv_bridge.QDSVBridgeAPIError¶: Raised when a transport error prevents calling the API.

class qdsv_bridge.QDSVBridgeArtifactError¶: Raised when a public artifact cannot be verified or loaded safely.

class qdsv_bridge.QDSVBridgeHTTPError(status_code, payload)¶

Raised when the API returns an HTTP error response.

Parameters:

status_code (int)
payload (Any)