niobium — the Qubitra Python SDK

The Python client for the Qubitra platform. Codename niobium; it installs as qubitra-sdk and imports as qubitra (ADR-0041 D1).

The SDK speaks q-platform vocabulary — Backends, Jobs, Offerings — and talks to the Qubitra API's public /v1 surface. Which backend a Job actually lands on, and the supply chain behind it, is the platform's business: the SDK never names a vendor.

Install

pip install qubitra-sdk

Inside this repo it is a uv workspace member, so uv sync at the root installs it editable and no publish step is involved.

Quickstart

from qubitra import QubitraClient

BELL = (
    'OPENQASM 3.0; include "stdgates.inc"; qubit[2] q; bit[2] c; '
    "h q[0]; cx q[0], q[1]; c = measure q;"
)

with QubitraClient() as client:
    for backend in client.backends.list():
        print(backend.id, backend.qubit_count, backend.supported_formats)

    job = client.jobs.submit(
        backend_id="sim-statevector-26q",
        circuit=BELL,
        shots=1024,
        name="bell-pair",
    )

    job = client.jobs.wait(job.id, timeout=600)
    if job.status.is_terminal and job.error:
        raise SystemExit(f"job {job.id} failed: {job.error}")

    print(client.jobs.result(job.id).counts)   # {"00": 512, "11": 512}

include "stdgates.inc"; is required: OpenQASM 3 defines no gates of its own, so h and cx are undefined without it.

Runnable versions sit in examples/: submit_bell_pair.py is the whole path, list_backends.py is the read-only smoke test, estimate_expectation.py submits an estimator PUB, and parameter_sweep.py sweeps an input declaration. All take their key from the environment:

QUBITRA_API_KEY=qpk_... uv run pkg/niobium/examples/submit_bell_pair.py

Against a local stack (mise run dev:qplat), add QUBITRA_API_URL=http://localhost:8080 and mint a key on the console's API keys page.

Configuration

Both are also constructor arguments — QubitraClient(api_key=…, api_url=…) — which take precedence over the environment.

Surface

A job carries an ordered list of PUBs (ADR-0049 D3) — a Pub is a circuit plus optional observables, parameter_values rows and shots. JobResult.pubs comes back index-aligned with the submission, each entry one of CountsResult, ProbabilitiesResult, ExpectationValuesResult or ErrorResult. result.counts, .values, .probabilities and .shots read the first entry, which is the whole answer for a single-circuit submission.

A Session is a correlation scope and a budget envelope (ADR-0049 D4) — not a hardware reservation. It holds no backend and buys no queue priority; it groups a run's jobs for reporting and bounds what the run may spend.

jobs.result is valid once a Job is COMPLETED; asking earlier raises InvalidRequestError.

Every failure is a QubitraError: AuthenticationError, NotFoundError, InvalidRequestError, InsufficientCreditsError, or ProviderError. Each carries the platform's RFC 9457 Problem Details body (ADR-0008) on .detail and its HTTP status on .status_code.

Models are frozen pydantic models; the package ships py.typed, so a caller's type checker sees the whole surface.

Layout

• src/qubitra/ — the public facade: client.py, models.py, errors.py, credentials.py.
• src/qubitra/_providers/ — the adapter seam (ADR-0041 D2). base.py is the protocol the facade depends on; qubitra.py implements it over /v1. A second platform slots in here without touching the facade.
• tests/ — facade behaviour over a fake adapter, plus contract tests driving the adapter's real request path against an httpx MockTransport.

The SDK is synchronous (ADR-0041 D7); client objects own their transport, so an async twin is additive.

Tasks

mise exec -- uv run pytest pkg/niobium -q     # tests
mise exec -- mypy pkg/niobium                 # types
mise exec -- ruff check pkg/niobium           # lint