Metadata-Version: 2.5
Name: softqcos-sdk
Version: 3.8.1
Summary: SoftQCOS™ SDK — Full-coverage Python client for the QCOS™ API Gateway
Project-URL: Homepage, https://softquantus.com
Project-URL: Documentation, https://docs.softquantus.com/sdk
Project-URL: Portal, https://platform.softquantus.com
Project-URL: License, https://softquantus.com/legal/license
Project-URL: EULA, https://softquantus.com/legal/eula
Author-email: SoftQuantus innovative OÜ <support@softquantus.com>
License: Proprietary - SoftQuantus innovative OÜ
Keywords: benchmarking,calibration,optimization,qcos,quantum,quantum-computing,sdk,softqcos
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: all
Requires-Dist: amazon-braket-sdk>=1.70.0; extra == 'all'
Requires-Dist: azure-quantum>=0.28.0; extra == 'all'
Requires-Dist: cirq>=1.3.0; extra == 'all'
Requires-Dist: pennylane>=0.34.0; extra == 'all'
Requires-Dist: qiskit-aer>=0.13.0; extra == 'all'
Requires-Dist: qiskit-ibm-runtime>=0.20.0; extra == 'all'
Requires-Dist: qiskit>=1.0.0; extra == 'all'
Provides-Extra: azure
Requires-Dist: azure-quantum>=0.28.0; extra == 'azure'
Provides-Extra: braket
Requires-Dist: amazon-braket-sdk>=1.70.0; extra == 'braket'
Provides-Extra: cirq
Requires-Dist: cirq>=1.3.0; extra == 'cirq'
Provides-Extra: cloud
Requires-Dist: amazon-braket-sdk>=1.70.0; extra == 'cloud'
Requires-Dist: azure-quantum>=0.28.0; extra == 'cloud'
Requires-Dist: qiskit-ibm-runtime>=0.20.0; extra == 'cloud'
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.22.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Provides-Extra: frameworks
Requires-Dist: cirq>=1.3.0; extra == 'frameworks'
Requires-Dist: pennylane>=0.34.0; extra == 'frameworks'
Requires-Dist: qiskit>=1.0.0; extra == 'frameworks'
Provides-Extra: ibm
Requires-Dist: qiskit-ibm-runtime>=0.20.0; extra == 'ibm'
Provides-Extra: pennylane
Requires-Dist: pennylane>=0.34.0; extra == 'pennylane'
Provides-Extra: qiskit
Requires-Dist: qiskit>=1.0.0; extra == 'qiskit'
Provides-Extra: simulation
Requires-Dist: qiskit-aer>=0.13.0; extra == 'simulation'
Requires-Dist: qiskit>=1.0.0; extra == 'simulation'
Description-Content-Type: text/markdown

# 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.

```bash
pip install softqcos-sdk
```

## Quick Start

```python
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

| Property            | Product                 | Prefix                    |
|---------------------|-------------------------|---------------------------|
| `client.jobs`       | QCOS Jobs™              | `/v1/jobs/*`              |
| `client.circuits`   | QCOS Circuits™          | `/api/v1/circuits/*`      |
| `client.bench`      | QCOS Bench™             | `/api/v1/bench/*`         |
| `client.calibration`| QCOS GlassBox™          | `/api/v1/glassbox/*`      |
| `client.billing`    | QCOS ROI Engine™        | `/api/v1/roi/*`           |
| `client.network`    | QCOS QuantumNet™        | `/api/v1/network/*`       |
| `client.qec`        | QCOS QEC Runtime™       | `/api/v1/qec/*`           |
| `client.isolation`  | QCOS ZoneGuard™         | `/api/v1/isolation/*`     |
| `client.dri`        | QCOS DRI™               | `/api/v1/dri/*`           |
| `client.ledger`     | QCOS QuantumLedger™     | `/api/v1/ledger/*`        |
| `client.navcore`    | QCOS NavCore™           | `/api/v1/navcore/*`       |
| `client.acos`       | ACOS-ISA™               | `/api/v1/acos/*`          |
| `client.macro`      | Quantum Macro™          | `/api/v1/macro/*`         |
| ~~`client.admin`~~  | withdrawn 2026-07-28    | `/api/admin/*` returns 404 |
| `client.evidence`   | QCOS Evidence™          | `/api/v1/runtime/jobs/{id}/artifacts/*` |
| `client.backends`   | QCOS Backends™          | `/api/v1/backends/*`      |
| `client.generate`   | Quantum Application Runtime | `/api/v1/runtime/generate` |

## 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.

```python
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:

```python
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:

```python
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

| Environment Variable | Description                              | Default                        |
|---------------------|------------------------------------------|--------------------------------|
| `QCOS_API_KEY`      | API key (required if not passed to ctor) | —                              |
| `QCOS_API_URL`      | API gateway URL                          | `https://api.softquantus.com`  |

## Examples

```python
# Calibration
devices = client.calibration.devices()
state = client.calibration.device_state("ibm_brisbane")

# 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_brisbane")
proof = client.dri.proof_run(backend="ibm_brisbane")

# Billing & ROI
estimate = client.billing.calculate(backend="ibm_brisbane", 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
