QCOS Python SDK Reference

Complete reference for the softqcos-sdk Python package.

Version: 2.0.0 · Package: pip install softqcos-sdk · Methods: 224 · Python: 3.10+

Installation

pip install softqcos-sdk

Optional Dependencies

pip install softqcos-sdk[visualization]  # matplotlib, plotly
pip install softqcos-sdk[jupyter]        # Jupyter integration
pip install softqcos-sdk[full]           # Everything

QCOSClient

Main client for interacting with QCOS. Provides access to 16 product APIs via dot notation.

from softqcos_sdk import QCOSClient

client = QCOSClient(
    api_key: str = None,       # Default: $QCOS_API_KEY
    base_url: str = None,      # Default: https://api.softquantus.com
    timeout: float = 30.0,     # Request timeout (seconds)
    max_retries: int = 3,      # Automatic retries with exponential backoff
)

Context Manager

with QCOSClient() as client:
    result = client.jobs.execute(qasm, shots=1024)
# Connection auto-closed

Product APIs

Attribute	Class	Methods	Description
`client.jobs`	`JobsAPI`	10	Job management
`client.circuits`	`CircuitsAPI`	9	Circuit operations
`client.backends`	`BackendsAPI`	26	Backend management (BYOB + IBM + Azure + Braket)
`client.bench`	`BenchAPI`	10	Benchmarking
`client.calibration`	`CalibrationAPI`	13	Calibration (GlassBox™)
`client.billing`	`BillingAPI`	11	Billing (ROI Engine™)
`client.network`	`NetworkAPI`	18	Quantum networking (QuantumNet™)
`client.qec`	`QECAPI`	15	Error correction (QEC Runtime™)
`client.isolation`	`IsolationAPI`	8	Qubit isolation (ZoneGuard™)
`client.dri`	`DRIAPI`	14	Device readiness inspection
`client.ledger`	`LedgerAPI`	14	Metering & governance (QuantumLedger™)
`client.navcore`	`NavCoreAPI`	48	Quantum navigation (NavCore™)
`client.acos`	`ACOSAPI`	8	Certification (ACOS-ISA™)
`client.macro`	`MacroAPI`	4	Macro analysis (Quantum Macro™)
`client.admin`	`AdminAPI`	10	Platform administration
`client.evidence`	`EvidenceAPI`	6	Evidence management

Direct HTTP

response = client.get("/api/v2/jobs")
response = client.post("/api/v2/jobs", json={"qasm": "...", "shots": 1024})
response = client.put("/api/v2/backends/123", json={...})
response = client.delete("/api/v2/backends/123")

AsyncQCOSClient

Async version for concurrent operations:

from softqcos_sdk import AsyncQCOSClient
import asyncio

async def main():
    async with AsyncQCOSClient() as client:
        # Parallel submissions
        results = await asyncio.gather(
            client.jobs.submit(qasm1, shots=1024),
            client.jobs.submit(qasm2, shots=1024),
            client.jobs.submit(qasm3, shots=1024),
        )

asyncio.run(main())

JobsAPI

client.jobs.submit(qasm, shots=1024, backend="aer_simulator", **kwargs) → dict
client.jobs.get(job_id) → dict
client.jobs.results(job_id) → dict
client.jobs.list(**params) → list[dict]
client.jobs.cancel(job_id) → None
client.jobs.evidence(job_id) → dict
client.jobs.bundle(job_id) → dict
client.jobs.verify(job_id) → dict
client.jobs.wait(job_id, *, timeout=300.0, poll_interval=2.0) → dict
client.jobs.execute(qasm, shots=1024, backend="aer_simulator", **kwargs) → dict

Example

from softqcos_sdk import QCOSClient

client = QCOSClient()

# Submit and wait (convenience)
result = client.jobs.execute(
    qasm="OPENQASM 2.0; ...",
    shots=1024,
    backend="aer_simulator"
)
print(result["counts"])  # {"00": 512, "11": 512}

# Or step-by-step
job = client.jobs.submit(qasm, shots=4096)
completed = client.jobs.wait(job["job_id"], timeout=300)
results = client.jobs.results(job["job_id"])

# Evidence
evidence = client.jobs.evidence(job["job_id"])
verification = client.jobs.verify(job["job_id"])
print(f"Valid: {verification['valid']}")

CircuitsAPI

client.circuits.submit(qasm, **kwargs) → dict
client.circuits.get(circuit_id) → dict
client.circuits.list(**params) → list[dict]
client.circuits.delete(circuit_id) → None
client.circuits.validate(qasm) → dict
client.circuits.convert(qasm, target_format="qiskit") → dict
client.circuits.stats(circuit_id) → dict
client.circuits.optimize(qasm, target_backend=None, **kwargs) → dict
client.circuits.simulate(qasm, shots=1024, **kwargs) → dict

Example

# Validate before submitting
validation = client.circuits.validate(qasm)
if validation["valid"]:
    # Optimize for target backend
    optimized = client.circuits.optimize(qasm, target_backend="ibm_brisbane")
    print(f"Depth: {optimized['original_depth']} → {optimized['optimized_depth']}")

    # Simulate
    sim = client.circuits.simulate(qasm, shots=1024)
    print(sim["counts"])

BackendsAPI

User Backends (BYOB)

client.backends.providers() → list[dict]
client.backends.list() → list[dict]
client.backends.get(backend_id) → dict
client.backends.add(**kwargs) → dict
client.backends.update(backend_id, **kwargs) → dict
client.backends.delete(backend_id) → None
client.backends.validate(**kwargs) → dict
client.backends.execute(**kwargs) → dict
client.backends.all_backends() → list[dict]

IBM Quantum

client.backends.ibm_backends() → list[dict]
client.backends.ibm_estimate(**kwargs) → dict
client.backends.ibm_execute(**kwargs) → dict
client.backends.ibm_status(job_id) → dict
client.backends.ibm_cancel(job_id) → None

Azure Quantum

client.backends.azure_providers() → list[dict]
client.backends.azure_targets() → list[dict]
client.backends.azure_backends() → list[dict]
client.backends.azure_estimate(**kwargs) → dict
client.backends.azure_execute(**kwargs) → dict
client.backends.azure_status(job_id) → dict
client.backends.azure_cancel(job_id) → None

AWS Braket

client.backends.braket_backends() → list[dict]
client.backends.braket_estimate(**kwargs) → dict
client.backends.braket_execute(**kwargs) → dict
client.backends.braket_status(job_id) → dict
client.backends.braket_cancel(job_id) → None

BenchAPI

client.bench.run(backend, **kwargs) → dict
client.bench.report(benchmark_id) → dict
client.bench.download(benchmark_id) → bytes
client.bench.suites(suite_id=None) → list[dict]
client.bench.workloads() → list[dict]
client.bench.verify(benchmark_id) → dict
client.bench.health() → dict
client.bench.selftest() → dict
client.bench.metrics_coverage() → dict
client.bench.metrics_kpis() → dict

Example

# Run benchmark
report = client.bench.run(
    backend="aer_simulator",
    suite_id="standard",
    shots=4096,
    repetitions=5
)
print(f"Score: {report['score']}, Fidelity: {report['fidelity']}")

# Download PDF report
pdf = client.bench.download(report["benchmark_id"])
with open("benchmark_report.pdf", "wb") as f:
    f.write(pdf)

CalibrationAPI (GlassBox™)

client.calibration.health() → dict
client.calibration.info() → dict
client.calibration.devices() → list[dict]
client.calibration.device_state(device_name) → dict
client.calibration.qubit(device_name, qubit_id) → dict
client.calibration.compile(qasm, **kwargs) → dict
client.calibration.compile_status(compilation_id) → dict
client.calibration.evidence_create(**kwargs) → dict
client.calibration.evidence_get(bundle_id) → dict
client.calibration.evidence_verify(**kwargs) → dict
client.calibration.evidence_sign(bundle_id) → dict
client.calibration.evidence_finalize(bundle_id) → dict
client.calibration.evidence_audit(bundle_id) → dict

Example

# Check device calibration
devices = client.calibration.devices()
state = client.calibration.device_state("ibm_brisbane")
print(f"T1: {state['t1']}μs, T2: {state['t2']}μs")
print(f"Readout error: {state['readout_error']}")

# Check specific qubit
qubit = client.calibration.qubit("ibm_brisbane", 0)

BillingAPI (ROI Engine™)

client.billing.providers() → list[dict]
client.billing.pricebook() → dict
client.billing.plans() → list[dict]
client.billing.calculate(**kwargs) → dict
client.billing.scenarios(**kwargs) → list[dict]
client.billing.compare_providers(**params) → dict
client.billing.report_data(**kwargs) → dict
client.billing.report_pdf(**kwargs) → bytes
client.billing.report_latex(**kwargs) → str
client.billing.v1_providers() → list[dict]
client.billing.v1_calculate(**kwargs) → dict

Example

# Cost estimate
estimate = client.billing.calculate(
    provider="ibm",
    backend="ibm_brisbane",
    shots=10000,
    circuits=5
)
print(f"Total: ${estimate['total_cost']:.4f}")

# Multi-scenario comparison
scenarios = client.billing.scenarios(
    backends=["ibm_brisbane", "ionq_harmony"],
    shots=[1000, 10000, 100000],
    circuits=5
)

# Compare providers
comparison = client.billing.compare_providers(shots=10000)

NetworkAPI (QuantumNet™)

# Service
client.network.health() → dict
client.network.status() → dict
client.network.topology() → dict
client.network.backends() → list[dict]

# Quantum operations
client.network.entangle(**kwargs) → dict
client.network.teleport(**kwargs) → dict
client.network.remote_cnot(**kwargs) → dict
client.network.barrier(**kwargs) → dict

# Phase 0 research
client.network.ion_species() → list[dict]
client.network.phase0_sweep(**kwargs) → dict
client.network.phase0b_analyze(**kwargs) → dict
client.network.phase0b_recommend(**kwargs) → dict

# Network jobs
client.network.jobs() → list[dict]
client.network.job_status(job_id) → dict
client.network.job_result(job_id) → dict
client.network.job_evidence(job_id) → dict

# Evidence
client.network.evidence(evidence_id) → dict
client.network.evidence_bundle(job_id) → dict

QECAPI (QEC Runtime™)

client.qec.health() → dict
client.qec.codes() → list[dict]
client.qec.code(code_id) → dict
client.qec.create_code(**kwargs) → dict
client.qec.decode(**kwargs) → dict
client.qec.syndrome(**kwargs) → dict
client.qec.compile(**kwargs) → dict
client.qec.pipeline(**kwargs) → dict
client.qec.zones() → list[dict]
client.qec.zone(zone_id) → dict
client.qec.zone_create(**kwargs) → dict
client.qec.zone_delete(zone_id) → None
client.qec.certify(**kwargs) → dict
client.qec.isolation_evidence(evidence_id) → dict
client.qec.isolation_certificates() → list[dict]

IsolationAPI (ZoneGuard™)

client.isolation.health() → dict
client.isolation.crosstalk() → dict
client.isolation.zones() → list[dict]
client.isolation.zone(zone_id) → dict
client.isolation.allocate(**kwargs) → dict
client.isolation.execute(**kwargs) → dict
client.isolation.delete(zone_id) → None
client.isolation.evidence(evidence_id) → dict

DRIAPI

# Assessment
client.dri.health() → dict
client.dri.run(**kwargs) → dict
client.dri.probe(**kwargs) → dict
client.dri.list() → list[dict]
client.dri.report(rating_id) → dict
client.dri.summary(rating_id) → dict
client.dri.evidence(bundle_id) → dict

# Proof-of-Quantum
client.dri.proof_run(**kwargs) → dict
client.dri.proof(test_id) → dict
client.dri.proof_report(test_id) → dict
client.dri.proof_certificate(test_id) → bytes
client.dri.proof_compare(**kwargs) → dict
client.dri.proof_compare_result(comparison_id) → dict
client.dri.proof_compare_certificate(comparison_id) → bytes

LedgerAPI (QuantumLedger™)

client.ledger.jobs(**params) → list[dict]
client.ledger.job(job_id) → dict
client.ledger.tenants(tenant_id=None) → list[dict] | dict
client.ledger.tenant_create(**kwargs) → dict
client.ledger.budgets(tenant_id=None) → list[dict]
client.ledger.budget_create(**kwargs) → dict
client.ledger.projects() → list[dict]
client.ledger.project_create(**kwargs) → dict
client.ledger.pricing() → dict
client.ledger.estimate(**kwargs) → dict
client.ledger.provenance(job_id) → dict
client.ledger.usage() → dict
client.ledger.audit() → dict
client.ledger.chargeback(**kwargs) → dict

NavCoreAPI (48 methods)

# Core Navigation
client.navcore.status() → dict
client.navcore.algorithms() → list[dict]
client.navcore.navigate(**kwargs) → dict
client.navcore.spoof_detect(**kwargs) → dict
client.navcore.sensor_simulate(**kwargs) → dict

# QRNG
client.navcore.qrng_bytes(**kwargs) → dict
client.navcore.qrng_uuid() → dict
client.navcore.qrng_nonce() → dict

# PQC
client.navcore.pqc_keypair(**kwargs) → dict
client.navcore.pqc_sign(**kwargs) → dict
client.navcore.pqc_verify(**kwargs) → dict

# RAIM
client.navcore.raim_status() → dict
client.navcore.raim_threats() → list[dict]
client.navcore.raim_process(**kwargs) → dict
client.navcore.raim_exclude(**kwargs) → dict
client.navcore.raim_statistics() → dict
client.navcore.raim_quantum_verification() → dict
client.navcore.raim_hybrid_fusion() → dict

# Time
client.navcore.time_utc() → dict
client.navcore.time_network() → dict
client.navcore.time_sync(**kwargs) → dict

# Standards & Compliance
client.navcore.sosa_profiles() → list[dict]
client.navcore.sosa_validate(**kwargs) → dict
client.navcore.victory_services() → list[dict]
client.navcore.victory_publish(**kwargs) → dict
client.navcore.face_status() → dict
client.navcore.conformance_report() → dict

# HAL
client.navcore.hal_sensors() → list[dict]
client.navcore.hal_register(**kwargs) → dict

# Quantum Processing
client.navcore.quantum_status() → dict
client.navcore.quantum_process(**kwargs) → dict
client.navcore.quantum_configure(**kwargs) → dict
client.navcore.quantum_performance() → dict
client.navcore.quantum_sequences() → list[dict]
client.navcore.quantum_circuit_run(**kwargs) → dict
client.navcore.noise_characterize(**kwargs) → dict

# Kalman Filter
client.navcore.kalman_update(**kwargs) → dict
client.navcore.kalman_predict(**kwargs) → dict
client.navcore.kalman_state() → dict
client.navcore.kalman_reset(**kwargs) → dict

# OSNMA
client.navcore.osnma_status() → dict
client.navcore.osnma_satellites() → list[dict]
client.navcore.osnma_verify(**kwargs) → dict

# NIS2 Compliance
client.navcore.nis2_status() → dict
client.navcore.nis2_gaps() → list[dict]
client.navcore.nis2_incident(**kwargs) → dict
client.navcore.compliance_audit() → dict
client.navcore.compliance_summary() → dict

ACOSAPI (ACOS-ISA™)

client.acos.health() → dict
client.acos.tiers() → list[dict]
client.acos.tests() → list[dict]
client.acos.certify(backend, tier="bronze", **kwargs) → dict
client.acos.verify(certificate_id) → dict
client.acos.certificates() → list[dict]
client.acos.certificate(certificate_id) → dict
client.acos.evidence(evidence_id) → dict

Certification Tiers: bronze → silver → gold → platinum

MacroAPI (Quantum Macro™)

client.macro.health() → dict
client.macro.market_sizing(**params) → dict    # TAM/SAM analysis
client.macro.energy_optimize(**kwargs) → dict  # kWh savings
client.macro.risk_analysis(**kwargs) → dict    # ROI/risk score

AdminAPI

client.admin.health_ready() → dict
client.admin.health_live() → dict
client.admin.tenants() → list[dict]
client.admin.tenant_usage(tenant_id) → dict
client.admin.metrics() → dict
client.admin.rate_limits() → dict
client.admin.circuit_breakers() → dict
client.admin.circuit_breaker_reset(service_name) → dict
client.admin.backends_status() → dict
client.admin.backend_capabilities(backend_id) → dict

EvidenceAPI

client.evidence.artifacts(job_id) → list[dict]
client.evidence.artifact(job_id, artifact_name) → dict
client.evidence.capabilities(job_id) → dict
client.evidence.download(job_id, output_dir=".") → str
client.evidence.verify(evidence_hash) → dict
client.evidence.public_key() → str  # PEM format

Data Models

All models use Pydantic v2 with optional fields for forward/backward compatibility.

Model	Key Fields
`JobResult`	`job_id`, `status`, `counts`, `backend`, `shots`, `created_at`, `completed_at`, `error`
`CircuitInfo`	`circuit_id`, `name`, `qasm`, `num_qubits`, `depth`, `gate_count`
`ProviderInfo`	`provider`, `name`, `status`, `backends`, `region`
`BackendInfo`	`backend_id`, `name`, `provider`, `num_qubits`, `status`, `queue_length`, `basis_gates`
`BenchmarkReport`	`benchmark_id`, `suite`, `backend`, `score`, `fidelity`, `depth_ratio`
`DeviceState`	`device_name`, `num_qubits`, `t1`, `t2`, `readout_error`, `gate_errors`
`EvidenceBundle`	`bundle_id`, `job_id`, `hash` (SHA-256), `signature`, `finalized_at`
`PricebookEntry`	`provider`, `backend`, `price_per_shot`, `price_per_second`, `currency`, `tier`
`Certificate`	`certificate_id`, `backend`, `tier`, `score`, `valid`, `issued_at`, `expires_at`
`HealthStatus`	`status` (ok/degraded/down), `service`, `version`, `uptime`

JobResult Helpers

result = JobResult(**data)
result.is_complete()          # True if COMPLETED
result.is_successful()        # True if COMPLETED without error
result.get_probabilities()    # Normalized counts as probabilities

Error Handling

from softqcos_sdk.exceptions import (
    QCOSError,
    AuthenticationError,
    RateLimitError,
    ValidationError,
    JobNotFoundError,
    ResourceNotFoundError,
    ConflictError,
    TimeoutError,
    ServerError,
)

try:
    result = client.jobs.execute(qasm, shots=1024)
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except ValidationError as e:
    print(f"Invalid input: {e.detail}")
except JobNotFoundError:
    print("Job not found")
except ServerError:
    print("Server error, try again later")
except QCOSError as e:
    print(f"Error {e.status_code}: {e.detail}")

Automatic Retries

The SDK automatically retries on:

Connection errors
Read timeouts
HTTP 429 (Rate Limited)

Default: 3 retries with exponential backoff (1s → 2s → 4s).

Installation​

Optional Dependencies​

QCOSClient​

Context Manager​

Product APIs​

Direct HTTP​

AsyncQCOSClient​

JobsAPI​

Example​

CircuitsAPI​

Example​

BackendsAPI​

User Backends (BYOB)​

IBM Quantum​

Azure Quantum​

AWS Braket​

BenchAPI​

Example​

CalibrationAPI (GlassBox™)​

Example​

BillingAPI (ROI Engine™)​

Example​

NetworkAPI (QuantumNet™)​

QECAPI (QEC Runtime™)​

IsolationAPI (ZoneGuard™)​

DRIAPI​

LedgerAPI (QuantumLedger™)​

NavCoreAPI (48 methods)​

ACOSAPI (ACOS-ISA™)​

MacroAPI (Quantum Macro™)​

AdminAPI​

EvidenceAPI​

Data Models​

JobResult Helpers​

Error Handling​

Automatic Retries​

Installation

Optional Dependencies

QCOSClient

Context Manager

Product APIs

Direct HTTP

AsyncQCOSClient

JobsAPI

Example

CircuitsAPI

Example

BackendsAPI

User Backends (BYOB)

IBM Quantum

Azure Quantum

AWS Braket

BenchAPI

Example

CalibrationAPI (GlassBox™)

Example

BillingAPI (ROI Engine™)

Example

NetworkAPI (QuantumNet™)

QECAPI (QEC Runtime™)

IsolationAPI (ZoneGuard™)

DRIAPI

LedgerAPI (QuantumLedger™)

NavCoreAPI (48 methods)

ACOSAPI (ACOS-ISA™)

MacroAPI (Quantum Macro™)

AdminAPI

EvidenceAPI

Data Models

JobResult Helpers

Error Handling

Automatic Retries