Metadata-Version: 2.4
Name: qcos-driver-sdk
Version: 1.0.0
Summary: SoftQuantus QCOS Driver SDK - implement one QPUDriver, pass ACOS-ISA conformance, plug your QPU into QCOS
Author-email: SoftQuantus <partnerships@softquantus.com>
License: Proprietary
Requires-Python: >=3.10
Requires-Dist: pydantic>=2
Provides-Extra: conformance
Requires-Dist: cryptography>=41; extra == 'conformance'
Requires-Dist: qiskit>=1.0; extra == 'conformance'
Description-Content-Type: text/markdown

# QCOS Driver SDK

Implement **one class**, pass **one conformance suite**, and your QPU runs
under QCOS — calibration, predictive routing (PSR), QEC advisor, error
mitigation, billing and the canonical runtime API included. You never need
(or receive) the QCOS core source.

## Install

```bash
pip install qcos-driver-sdk[conformance]
```

The SDK is for the **vendor workstation/CI**. Never install it on a QCOS
server host — the server already provides the `hal` package; your driver
wheel must depend on the SDK only via an optional extra (see
`examples/vendor-driver-demo`).

## 1. Implement your driver

Two methods are mandatory; everything else has defaults. Copy
`ReferenceSimulatorDriver` as a full-contract template.

```python
from qcos_driver_sdk import (
    BackendIdentity, DeviceCapabilities, HardwareSpec, QPUDriver,
)

class AcmeDriver(QPUDriver):
    targets = ("acme.lab1",)          # backend ids you serve

    def device_capabilities(self) -> DeviceCapabilities:
        return DeviceCapabilities(
            backend=BackendIdentity(id="acme.lab1", name="ACME Lab-1", provider="acme"),
            hardware=HardwareSpec(num_qubits=20, is_simulator=False),
        )

    def execute(self, circuit, shots=1024):
        # circuit arrives as OpenQASM 2.0 text at the QCOS dispatch seam;
        # ACOS-ISA certification additionally feeds qiskit QuantumCircuit
        # objects — see ReferenceSimulatorDriver._to_qasm for the pattern.
        counts = my_control_stack.run(circuit, shots)
        return {
            "job_id": "...", "backend_id": "acme.lab1", "shots": shots,
            "counts": counts, "execution_time_ms": 12.3,
            "timestamp": "...", "status": "completed",
        }
```

Rules the dispatch seam enforces:

- **Provenance is honest.** Declare `is_simulator` truthfully; undeclared
  provenance is reported as *simulated*, never as real hardware.
- **Failures are explicit.** Raise, or return `status: "failed"` in-band —
  both are authoritative. QCOS never substitutes a simulator for your id.
- **Declared limits are enforced by you.** ACOS-ISA-006 submits circuits
  exceeding your declared `limits` and expects a limit error.

## 2. Certify

```bash
qcos-driver-cert acme_qcos_driver:AcmeDriver --backend-id acme.lab1 --output report.json
```

Exit code 0 = certified (ACOS-ISA v1.0, 10/10, "QCOS Compatible"). Runs on
real hardware use `--execution-mode hardware`; certification tiers,
signed evidence bundles and the public registry are handled by the
SoftQuantus certification program (partnerships@softquantus.com).

## 3. Ship

Package your driver as a wheel with a `qcos.drivers` entry point:

```toml
[project.entry-points."qcos.drivers"]
acme = "acme_qcos_driver:AcmeDriver"
```

`pip install acme-qcos-driver` on the QCOS host is the whole deployment:
the unified dispatch seam resolves `acme.lab1` through your driver, and
the real-QPU gates (kill-switch, payment, tier) apply automatically.

## Building this SDK (SoftQuantus internal)

The wheel force-includes `hal/` and the ACOS-ISA suite from the server
tree — one source of truth, never edit copies here. Build wheels only:

```bash
python -m build --wheel sdk-driver
```
