qcos-driver-sdk 1.0.0

SoftQuantus QCOS Driver SDK - implement one QPUDriver, pass ACOS-ISA conformance, plug your QPU into QCOS

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

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.

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

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 ([e-mail]).

3. Ship

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

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

python -m build --wheel sdk-driver