Metadata-Version: 2.4
Name: qdsv-bridge
Version: 0.1.4
Summary: Lightweight Python client for QDSV Bridge, a controlled semantic-to-circuit compiler with family-based export modes.
Project-URL: Homepage, https://qdsv.cloud
Project-URL: Documentation, https://qdsv.cloud/#bridge
Project-URL: Source, https://github.com/qdsvquantum-afk/qdsv-bridge
Author: QDSV / Qruba
License-Expression: MIT
License-File: LICENSE
Keywords: circuit,qasm,qdsv,quantum,sdk,semantic-computation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: requests>=2.31
Description-Content-Type: text/markdown

# QDSV Bridge Developer Preview

[![PyPI](https://img.shields.io/pypi/v/qdsv-bridge.svg)](https://pypi.org/project/qdsv-bridge/)
[![Python](https://img.shields.io/pypi/pyversions/qdsv-bridge.svg)](https://pypi.org/project/qdsv-bridge/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Status](https://img.shields.io/badge/status-developer%20preview-0ea5e9.svg)](#resource-and-multi-user-limits)

Current package version: `0.1.4`.

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 problem-derived circuit materializations, QDSV IR, oracle specs, QASM/Qiskit artifacts or expert construction inputs.

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

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

## 5 Minute Quickstart

Install the SDK:

```bash
pip install qdsv-bridge
```

Build a circuit-oriented artifact from a compact semantic spec:

```python
from qdsv_bridge import QDSVBridgeClient

client = QDSVBridgeClient(api_key="YOUR_QDSV_API_KEY")

spec = {
    "family": "semantic_signal_classification",
    "state_space": {
        "kind": "finite_candidates",
        "candidate_count": 300,
        "candidate_id": "eeg_window",
    },
    "signals": [
        "dwt_cD3_std_score",
        "std_score",
        "activity_score",
        "energy_score",
        "dwt_cD2_std_score",
        "complexity_score",
    ],
    "goal": {
        "kind": "binary_marking",
        "positive_state": "ictal",
    },
    "materialization_policy": {
        "preserve_signal_geometry": True,
        "avoid_fixed_ansatz": True,
        "avoid_forced_dimensionality_reduction": True,
        "report_information_loss": True,
    },
    "target": {
        "format": "qasm3",
        "backend_family": "qiskit",
    },
    "limits": {
        "max_qubits": 10,
        "max_depth": 300,
    },
}

result = client.build(spec)

print(result["status"])
print(result["bridge_mode"])
print(result["circuit_origin"])
print(result["artifact"]["format"])
```

Default cloud endpoint:

```text
https://api.qdsv.cloud/api
```

Private/local Docker endpoint:

```python
client = QDSVBridgeClient.local()
```

## What This Is

- A client SDK for QDSV Bridge.
- A controlled semantic-to-circuit export interface.
- A way to request QDSV IR, oracle specs, QASM/Qiskit artifacts or expert construction inputs.
- 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.

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

For users who need circuit ecosystems, Bridge derives a new circuit artifact from that semantic specification instead of asking the user to adapt the problem to a ready-made template.

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: the circuit, when delivered, is derived from the semantic problem specification.

| API | Commercial name | Intended user | What Bridge returns |
|---|---|---|---|
| `generate()` / `use` | Bridge Use | Basic user who wants to solve without designing circuits. | A new problem-derived circuit artifact, simple explanation, information-loss risk, usage recommendation and ready-to-run example. |
| `build()` / `build` | Bridge Build | Intermediate user who understands Qiskit, QASM or quantum workflows. | A new problem-derived circuit artifact plus QASM/Qiskit, oracle spec, IR summary, preservation report, estimated qubits/depth and digests. |
| `prepare()` / `expert_prepare` | Bridge Expert Prepare | Expert constructor who wants to design a custom circuit. | Validated family, ProblemSpec/IR, oracle spec, predicates, target state/goal, constraints, variables, information-loss risk, encoding/measurement suggestions, estimated limits and evidence. It does not force a final circuit. |
| `evaluate()` / `expert_evaluate` | Bridge Expert Evaluate | Expert evaluator who wants to compare QDSV materializations. | Suggested QDSV circuit artifact, materialization variants, comparison and preservation report. |

Python helpers:

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

Explicit mode:

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

CLI:

```bash
qdsv-bridge export spec.json --mode use --api-key YOUR_QDSV_API_KEY
qdsv-bridge export spec.json --mode build --api-key YOUR_QDSV_API_KEY
qdsv-bridge export spec.json --mode expert_prepare --api-key YOUR_QDSV_API_KEY
qdsv-bridge export spec.json --mode expert_evaluate --api-key YOUR_QDSV_API_KEY
```

Every export response should include traceability metadata:

```json
{
  "mode": "use | build | expert_prepare | expert_evaluate",
  "artifact_type": "qasm3",
  "circuit_origin": "qdsv_derived",
  "semantic_preservation": {"status": "accepted", "score": 1.0},
  "warnings": [],
  "digests": {}
}
```

## Examples By User Type

Basic user:

```python
result = client.generate(spec)
print(result["circuit_origin"])          # qdsv_derived
print(result["circuit"]["status"])       # generated_from_semantic_spec
print(result["ready_to_run_example"])
```

Intermediate developer:

```python
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:

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

Expert evaluator:

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

## Supported Families

Developer Preview families:

- `bounded_semantic_marking`
- `semantic_signal_classification`
- `predicate_marking`
- `state_similarity`
- `combinatorial_relation`
- `distribution_sampling`

`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.

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:

```python
spec = {
    "family": "bounded_semantic_marking",
    "state_space": {
        "kind": "finite_candidates",
        "candidate_count": 128,
        "candidate_id": "candidate",
    },
    "signals": ["risk_score", "value_score", "eligibility_score"],
    "goal": {
        "kind": "marking",
        "predicate": "eligible_candidate",
    },
    "target": {
        "format": "qasm3",
        "backend_family": "qiskit",
    },
    "limits": {
        "max_qubits": 8,
        "max_depth": 250,
    },
}

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`

For `use` and `build`, circuit-oriented targets return a circuit artifact derived from the semantic spec, with explicit QDSV oracle/digest information and preservation metadata.

In Developer Preview, some targets are returned as integration blueprints with semantic oracle insertion points so external platforms can inspect, execute, optimize or complete the materialization safely.

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`

Default cloud endpoint:

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

Local/private Docker endpoint:

```python
client = QDSVBridgeClient.local()
```

Public informational endpoints such as `families()` are open. Value-producing compilation/export operations require an SDK API key.

## Resource And Multi-User Limits

QDSV Bridge accepts compact semantic problem specifications, 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.

Public API minimum limits:

| Limit | Default |
|---|---:|
| Max spec payload | 64 KB |
| Max QASM / circuit artifact payload | 256 KB |
| Max compile time | 5 seconds |
| Max export time | 10 seconds |
| API key required for | `compile`, `export`, `generate`, `build`, `prepare`, `evaluate` |
| Monthly demo quota | 5 compilations/exports per API key |
| Raw data payloads | Not allowed |
| Hardware execution | Not available from Bridge SDK |
| `bounded_semantic_marking` | 1024 candidates / 24 signals |
| `semantic_signal_classification` | 1024 candidates / 32 signals |
| `predicate_marking` | 2048 candidates / 8 signals |
| `state_similarity` | 1024 candidates / 64 signals |
| `combinatorial_relation` | 4096 candidates / 16 signals |
| `distribution_sampling` | 2048 candidates / 16 signals |

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

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

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, API keys, license checks and history belong to the QDSV/Qruba API deployment, not to the local Python package.

Raw dataset payloads are rejected:

```json
{
  "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](examples/)
- [Roadmap](ROADMAP.md)
- [QDSV model site](https://qdsv.cloud/)
- [Qruba Cloud](https://cloud.qruba.site/)
- [PyPI](https://pypi.org/project/qdsv-bridge/)

## 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:

```text
controlled semantic family
-> problem-derived circuit materialization or expert inputs
-> auditable export
```

Not:

```text
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.
