SoftQCOS™ SDK v3.5

Typed, synchronous Python client for the SoftQuantus QCOS™ API Gateway. Covers the documented product surface; it is not a wrapper over every mounted route.

pip install softqcos-sdk

Quick Start

from softqcos_sdk import QCOSClient

client = QCOSClient(api_key="sk-...")

# Submit a quantum job
job = client.jobs.submit(qasm="OPENQASM 2.0; ...", shots=1024)
result = client.jobs.wait(job["job_id"])
print(result["result"]["counts"])

# Or use the blocking shortcut
result = client.jobs.execute(qasm="OPENQASM 2.0; ...", shots=1024)

Product APIs

Generation with provenance

client.generate asks for a world, a character, a branch or a distribution and gets back structured data plus the origin of the entropy behind it. The output is classically derived from a quantum seed — it is not computed on a QPU, and it is not faster because a QPU exists. What is certifiable is the seed's origin, and the response names it along with the digest and the expander, so a third party can reproduce the result without running our code.

gen = client.generate.terrain(width=128, height=128, biomes=6)

gen.data["heightmap"]        # the world
gen.provenance.quantum       # observed from the backend that answered — never echoed
gen.provenance.backend       # e.g. "cloud_ibm" or "simulated"
gen.provenance.seed_sha256   # what makes the world reproducible
print(gen.certificate())     # the line you can publish

Every method returns a Generation, which cannot be built without provenance: a response missing it raises ProvenanceMissingError rather than degrading into bare data.

quantum_required=True fails rather than substituting. It defaults to False on every method — today most deployments have no quantum entropy source reachable, so True by default would fail every call. Set it whenever the origin will be claimed publicly:

from softqcos_sdk import QuantumEntropyUnavailableError

try:
    gen = client.generate.seed(quantum_required=True)   # or .certified_seed()
except QuantumEntropyUnavailableError:
    ...  # no quantum source answered. Decide explicitly — this SDK will not
         # quietly retry classically on your behalf and hand back a result
         # you would go on to describe as quantum.

Already have a result and only now need to claim its origin? gen.require_quantum() raises unless provenance.quantum is true.

Async Client

Not available. There is no AsyncQCOSClient; importing it raises ImportError. Every method on QCOSClient is synchronous.

QCOSClient does define __aenter__ / __aexit__, so async with QCOSClient(...) enters without complaint — but the first await client.jobs.submit(...) fails, because submit is not a coroutine. Do not rely on that context manager as evidence of async support.

Run the client in a thread if you need it off the event loop:

import asyncio
from softqcos_sdk import QCOSClient

client = QCOSClient(api_key="sk-...")
result = await asyncio.to_thread(
    client.jobs.execute, qasm="OPENQASM 2.0; ...", shots=1024
)

Configuration

Examples

# Calibration
devices = client.calibration.devices()
state = client.calibration.device_state("ibm_fez")

# Benchmarking
report = client.bench.run(backend="aer_simulator", suite="standard")
client.bench.verify(report["benchmark_id"])

# DRI — Device Reliability Index
dri = client.dri.run(backend="ibm_fez")
proof = client.dri.proof_run(backend="ibm_fez")

# Billing & ROI
estimate = client.billing.calculate(backend="ibm_fez", shots=10000)
plans = client.billing.plans()

# NavCore — GNSS/PNT
#
# Post-quantum signatures work: liboqs 0.16.0 is built into the API image, and
# navcore.algorithms() reports per scheme what the deployment can sign with.
# The keys are client-held — pqc_keypair returns the private key once, the
# server keeps no copy, and pqc_sign takes it back as a request field.
kp = client.navcore.pqc_keypair(algorithm="ml-dsa-65")
sig = client.navcore.pqc_sign(
    message=b64_message, private_key=kp["private_key"], key_id=kp["key_id"]
)
ok = client.navcore.pqc_verify(
    message=b64_message,
    signature=sig["signature"],
    public_key=kp["public_key"],
    algorithm=sig["mechanism"],   # the exact mechanism, matched exactly
)["valid"]
#
# Two calls were listed here that do not work against the deployed service and
# have been removed rather than left as examples:
#   navcore.navigate(...)      -> the route does not exist (404)
#   navcore.qrng_bytes(...)    -> 503, the QRNG backend is not configured
# The read-only NavCore endpoints under /api/v1/navcore/* respond normally.

# Network — Multi-QPU
topo = client.network.topology()
# network.teleport(...) is omitted deliberately: the endpoint accepts a request
# but does not complete a teleport against real nodes. Do not build on it yet.

# Error handling
from softqcos_sdk import QCOSError, AuthenticationError, RateLimitError

try:
    result = client.jobs.submit(qasm="invalid")
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
except AuthenticationError:
    print("Invalid API key")
except QCOSError as e:
    print(f"API error: {e}")

License

Copyright © 2024-2026 SoftQuantus innovative OÜ. All Rights Reserved.

QCOS™ is a trademark of SoftQuantus innovative OÜ. Registry Code: 17048927 | Tallinn, Estonia

• License: https://softquantus.com/legal/license
• EULA: https://softquantus.com/legal/eula
• Portal: https://platform.softquantus.com