Metadata-Version: 2.4
Name: qdevops-io
Version: 0.1.0
Summary: Official Python SDK for the QDevOps quantum reproducibility platform (qdevops.io).
Author-email: QDevOps <support@qdevops.io>
Maintainer-email: QDevOps <support@qdevops.io>
License: Proprietary
Project-URL: Homepage, https://qdevops.io
Project-URL: Documentation, https://api.qdevops.io/docs
Project-URL: Benchmarks, https://qdevops.io/bench
Project-URL: Issues, https://qdevops.io/support
Keywords: quantum,qiskit,reproducibility,ibm-quantum,aws-braket,devops
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx<1.0,>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-httpx>=0.30; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"

# qdevops-io — Python SDK

Official Python client for the [QDevOps](https://qdevops.io) quantum reproducibility platform.

The distribution name on PyPI is `qdevops-io`; the import path is `qdevops`
(same convention as `python-dateutil` → `dateutil`).

- Submit Bell / GHZ / QFT / Grover / VQE circuits to the simulator, IBM Quantum, or AWS Braket
- Poll runs to completion, fetch result payloads, diff two runs
- Export pinned environment lockfiles
- Publish results to the public benchmark dashboard at [qdevops.io/bench](https://qdevops.io/bench)

## Install

```bash
pip install qdevops-io
```

Requires Python 3.10+.

## Authenticate

Mint a personal access token at [qdevops.io/account/tokens](https://qdevops.io/account/tokens), then either:

```bash
export QDEVOPS_API_TOKEN="qass_pat_..."
```

…or pass it explicitly:

```python
from qdevops import Client

qd = Client(api_token="qass_pat_...")
```

## Quickstart — run a Bell state on the simulator

```python
from qdevops import Client

with Client() as qd:
    run = qd.submit_run(
        project_id=42,
        circuit="bell",
        backend="simulator",
        params={"shots": 2048},
    )
    print("queued", run.run_id, run.circuit_hash)

    full = qd.wait_for_run(run.run_id, timeout=120)
    if full.status == "SUCCESS":
        print("counts:", full.result.get("counts"))
    else:
        print("failed:", full.failure_reason)
```

## Compare backends

```python
for backend in ("simulator", "ibm", "braket"):
    run = qd.submit_run(project_id=42, circuit="bell", backend=backend)
    finished = qd.wait_for_run(run.run_id)
    print(backend, finished.result.get("expectation"))
```

## Publish a benchmark result

Requires a token with the `benchmarks:write` scope.

```python
qd.publish_benchmark(
    circuit="bell",
    backend="simulator",
    commit_sha="abc1234",
    fidelity=0.984,
    shots=2048,
    duration_ms=210,
    sdk_version="0.1.0",
)
```

## Errors

All non-2xx responses raise a subclass of `qdevops.APIError`:

| Exception              | HTTP |
| ---------------------- | ---- |
| `AuthenticationError`  | 401  |
| `ForbiddenError`       | 403  |
| `NotFoundError`        | 404  |
| `ConflictError`        | 409  |
| `APIError` (generic)   | 4xx/5xx |

`Client.wait_for_run` raises `qdevops.errors.TimeoutError` if a run does not
reach a terminal state within the requested timeout.

## Reference

See the OpenAPI spec at [api.qdevops.io/docs](https://api.qdevops.io/docs).

## License

Proprietary © QDevOps.io
