Metadata-Version: 2.5
Name: softqcos
Version: 3.10.0
Summary: SoftQCOS™ CLI - Command-Line Interface for Quantum Circuit Optimization Service
Project-URL: Homepage, https://softquantus.com
Project-URL: Documentation, https://docs.softquantus.com
Project-URL: Portal, https://platform.softquantus.com
Project-URL: License, https://www.apache.org/licenses/LICENSE-2.0
Project-URL: EULA, https://softquantus.com/legal/eula
Author-email: SoftQuantus innovative OÜ <support@softquantus.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: cli,optimization,qaoa,qiskit,quantum,quantum-computing,softqcos,vqe
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
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: Topic :: Scientific/Engineering :: Physics
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: softqcos-sdk<4,>=3.10.0
Requires-Dist: typer>=0.9.0
Provides-Extra: all
Requires-Dist: softqcos-sdk[all]<4,>=3.10.0; extra == 'all'
Provides-Extra: cloud
Requires-Dist: softqcos-sdk[cloud]<4,>=3.10.0; extra == 'cloud'
Provides-Extra: frameworks
Requires-Dist: softqcos-sdk[frameworks]<4,>=3.10.0; extra == 'frameworks'
Provides-Extra: pqc
Requires-Dist: softqcos-sdk[pqc]<4,>=3.10.0; extra == 'pqc'
Provides-Extra: qiskit
Requires-Dist: softqcos-sdk[qiskit]<4,>=3.10.0; extra == 'qiskit'
Provides-Extra: simulation
Requires-Dist: softqcos-sdk[simulation]<4,>=3.10.0; extra == 'simulation'
Provides-Extra: srp
Requires-Dist: softqcos-srp>=3.9.0; extra == 'srp'
Description-Content-Type: text/markdown

# SoftQCOS CLI

[![PyPI version](https://img.shields.io/pypi/v/softqcos.svg)](https://pypi.org/project/softqcos/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)

The `softqcos` command talks to the QCOS REST API at `https://api.softquantus.com`.
It has no privileges of its own: every command is a call to `/api/v1/*` made
with your API key, and runs only what that API serves.

The CLI, the Python SDK (`softqcos-sdk`) and the MCP server (`softqcos-mcp`)
are released together and always carry the same version number. The table at
the end of this page lists what each version added.

## Install

```bash
pip install softqcos
softqcos --version
```

The PyPI package is `softqcos`; it installs `softqcos-sdk` as a dependency.
Python 3.10 or newer. Every command, including offline `softqcos verify` of
RSA-PSS and Ed25519 seals, works from that plain install.

The extras forward to the SDK's:

```bash
pip install "softqcos[simulation]"   # Qiskit + Aer: run circuits locally
pip install "softqcos[pqc]"          # liboqs-python: verify ML-DSA (FIPS 204) seals
pip install "softqcos[all]"          # every SDK extra (qiskit, cirq, pennylane, ibm, braket, azure, pqc)
```

`pqc` installs `liboqs-python`, which is only the binding: the native liboqs
shared library must be installed too, either by running `python -c "import oqs"`
once (it downloads and builds liboqs into `~/_oqs`; needs `git`, `cmake` and a C
compiler) or by setting `OQS_INSTALL_PATH` to the prefix of a shared build.
`softqcos evidence verify` never builds it for you; without it an ML-DSA seal
reports `signature_valid: None`, with the reason.

## Sign in

Create an API key at <https://platform.softquantus.com/#apikeys>, then:

```bash
softqcos auth login
```

`auth login` asks for the key, checks that `https://api.softquantus.com/api/v1/status`
answers, and saves both in `~/.softqcos/config.json` (file mode `0600`). In CI,
skip the file and set the environment instead:

```bash
export QCOS_API_KEY="<your key>"
```

Settings are resolved in this order: environment variable, then
`~/.softqcos/config.json`, then the default.

| Setting | Environment variable | Default |
|---|---|---|
| API key | `QCOS_API_KEY` | none |
| API URL | `QCOS_API_URL` | `https://api.softquantus.com` |
| Platform URL | `QCOS_PLATFORM_URL` | `https://platform.softquantus.com` |

```bash
softqcos config                      # show what is stored
softqcos config set api_url https://api.softquantus.com
softqcos config --reset              # delete ~/.softqcos/config.json
softqcos auth status                 # key and license status
softqcos auth logout                 # release the local license
```

`softqcos doctor` checks the config file, the URLs, that a key is present, and
that the API answers `GET /api/v1/status`. That route does not need a key, so
a passing `doctor` does **not** prove the key is valid. The first authenticated
command does.

## First job, on a simulator

Save a Bell circuit as `bell.qasm`:

```text
OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
h q[0];
cx q[0],q[1];
measure q -> c;
```

Ask for an estimate first. `--dry-run` executes nothing:

```bash
softqcos jobs submit --circuit bell.qasm --backend simulator_aer --shots 1024 --dry-run
```

Then submit, and read the result with the job id it prints:

```bash
softqcos jobs submit --circuit bell.qasm --backend simulator_aer --shots 1024
softqcos jobs status <job_id>
softqcos jobs results <job_id>
softqcos jobs list --limit 5
```

`--backend` defaults to `simulator_aer`. A QPU backend costs money: use
`--max-cost-usd` to refuse a run above a ceiling, and `--confirm-cost` once
you have read the estimate. Every command takes `--json` for scripts.

## Commands

`softqcos --help` lists the root commands; every group has its own `--help`.

| Command | What it does |
|---|---|
| `auth` | `login`, `status`, `logout`, `license` |
| `config` | show, `set`, `--reset` the local config |
| `doctor` | local config and API reachability |
| `info`, `version`, `welcome` | environment, version, product overview |
| `jobs` | `submit`, `status`, `results`, `list`, `cancel`, `approve`, `evidence`, `bundle`, `events`, `verify` |
| `circuits` | circuit management, optimization, simulation |
| `algorithms` | Shor, Grover, QFT, QPE, QAOA and the other algorithm runners |
| `backends` | your own backend credentials (bring your own backend) |
| `billing` | pricing and ROI estimates |
| `webhooks` | HMAC-signed job events pushed to your endpoint |
| `research` | preregistered studies, evidence and claims |
| `verify` | verify an evidence record offline: `softqcos verify record.json --trust-bundle bundle.json` (exit 0 valid, 1 invalid, 2 unreadable) |
| `api` | JSON-first commands for agents and automation (below) |
| `generate` | seeded content generation with entropy provenance (below) |
| `extensions` | 31 specialised domains: `softqcos extensions --help` |
| `license` | `activate`, `status`, `deactivate` |
| `srp` | Research Package runtime, see the note below |

`softqcos extensions` holds the specialised domains: `qec`, `network`,
`calibration`, `chemistry`, `state`, `dynamics`, `evidence`, `qubo`, `science`
and more. Each of them also answers at the root (`softqcos qec ...`) for older
scripts. Those root aliases are not listed in `--help`. New scripts should use
`softqcos extensions <group>`.

Removed in 3.9.2: `admin`, `macro`, `autopilot`, `nvqlink` and `zne`. Every one
of their commands called a route the API does not serve, so each answered
`404`.

`softqcos srp` needs the `softqcos[srp]` extra. That extra depends on
`softqcos-srp`, which is not published on PyPI yet, so `pip install "softqcos[srp]"`
fails today.

### `softqcos api`

Stable JSON-first commands for agents, MCP bridges, Cursor, Copilot, and scripts:

```bash
softqcos api workspace init --json
softqcos api workspace discover --json
softqcos api job validate --input jobs/bell.qcos.json --json
softqcos api job plan --input jobs/bell.qcos.json --json
softqcos api run local --input jobs/bell.qcos.json --json
softqcos api result summary --input results/<run_id>/summary.json --json
```

These commands return structured payloads with `status`, `capability`, `artifacts`,
`metrics`, and `next_actions` so AI agents can continue workflows reliably.

QCOS GPU planning commands:

```bash
softqcos api gpu detect --json
softqcos api gpu benchmark --input circuits/bell.qasm --json
softqcos api gpu engine-detect --json
softqcos api gpu estimate-memory --qubits 30 --precision fp64 --json
softqcos api gpu plan --input circuits/bell.qasm --json
softqcos api gpu simulate --input circuits/bell.qasm --fallback-aer --json
softqcos api backend plan --input circuits/bell.qasm --json
softqcos api backend compare --input circuits/bell.qasm --execute-aer --json
softqcos api hybrid detect --json
softqcos api hybrid qec-plan --code surface --distance 5 --rounds 3 --json
softqcos api qlink plan-feedback-loop --qpu lab-qpu-1 --latency-budget-us 100 --qec --json
```

### `softqcos generate`

Structured content for games, design tools and simulations, expanded from a seed
the runtime draws. The expansion is a named deterministic function, so anyone
holding the seed digest can reproduce the output; **nothing here is computed on a
QPU** and nothing here is faster because of quantum.

```bash
softqcos generate tasks
softqcos generate seed --seed-bytes 32
softqcos generate terrain --width 64 --height 64 --biomes 4
softqcos generate character --personality 8 --traits 8 --relationships 3
softqcos generate narrative-branch -o ally -o betray --weight 1 --weight 3
softqcos generate distribution --samples 1000 --shape normal
```

Every successful run prints where the entropy came from — the backend that
answered, whether it was genuinely quantum, and the seed digest:

```text
Provenance
  backend        cloud_ibm
  quantum        yes — a quantum source produced the seed
  entropy_bits   256.0
  expander       splitmix64/v1
  seed_sha256
    a1a1...
```

`--quantum-required` refuses classical entropy instead of substituting it: if no
quantum source answers, the command fails, nothing is generated, and the error
says so. Use it whenever the origin of the result will be claimed publicly.

```bash
softqcos generate terrain --quantum-required     # exits non-zero if no QPU entropy
softqcos generate terrain --json                 # full response, provenance included
```

### `softqcos extensions science`

The Scientific Runtime (experimental): one contract for a scientific problem,
a planner that says which solver fits it, and a result that carries its own
validation. The algorithms are entries of one catalog, not separate products.

```bash
softqcos extensions science capabilities
softqcos extensions science algorithms --capability eigensolve --status available
softqcos extensions science algorithms --experimental-quantum
softqcos extensions science plan eigensolve --model transverse_field_ising --sites 4 --field 1.0 --tolerance 1e-3
softqcos extensions science eigensolve --model transverse_field_ising --sites 4 --field 1.0 --n-states 2
softqcos extensions science eigensolve --model transverse_field_ising --sites 4 --field 1.0 --algorithm vqe --seed 7
softqcos extensions science evolve --model transverse_field_ising --sites 4 --field 1.0 --total-time 2.0 --observable Z0=ZIII
softqcos extensions science optimize --problem qubo.json
softqcos extensions science simulate --model fermi_hubbard --sites 2 --interaction 4.0 --particle-number 2 --total-time 1.0
softqcos extensions science resource-estimate --model transverse_field_ising --sites 4 --field 1.0 --tolerance 1e-3
softqcos extensions science validate --model transverse_field_ising --sites 4 --field 1.0 --claimed-value -4.7588 --tolerance 1e-3
```

A problem is a JSON object: `--problem FILE` (`-` reads stdin), or a lattice
model described with `--model` and `--sites`. A flag overrides the same field of
the file. `qubo.json` above is
`{"qubo": {"linear": [-1.0, -2.0, 1.0], "quadratic": [[0, 1, 3.0], [1, 2, -2.0]]}}`.

Every computation prints its verdict first:

```text
eigensolve  algorithm=vqe  substrate=local_cpu_statevector  qubits=4  runtime=5.145139 s
validation: FAILED  |error|=0.01426626188  tolerance=1e-06  reference=exact_diagonalization
```

That run is the sixth command above, and the verdict is the point: the
hardware-efficient ansatz at its default depth stops 1.4e-2 above the exact
ground energy, and the runtime says so instead of returning a number that looks
like an answer. A result that misses its tolerance is still a result — the API
answers 200 and the command exits 0; read the status, or pass `--json`.

**Nothing here reaches a QPU or a GPU.** The quantum algorithms run on the API
host's exact statevector simulator (16 qubits by default; `capabilities` prints
the limits). `plan` lists what a problem would cost on hardware without running
it. The catalog is larger than what executes: entries marked `planned`,
`experimental_quantum` (VQLS, HHL, amplitude estimation) or
`resource_estimate_only` (QPE, qubitization) are refused with the list of
algorithms that do run. The catalog and the planner need a key with `qcos:read`;
the computations need `qcos:execute`.

## What each version added

Generated from the code at release time, so it cannot drift from what this
version runs. Command paths as you type them.

<!-- BEGIN release-surface: generated by scripts/gen_client_surface.py; edit the script, not this block -->

Package version on this source tree: **3.10.0**. `softqcos-sdk`, `softqcos` and
`softqcos-mcp` always carry the same number, so the row a name sits in is the
first version of THIS package that has it. A version is listed once it is tagged;
it reaches PyPI when that release is published, and
`pip index versions softqcos` shows which versions PyPI has.

| Version | Added |
|---|---|
| 3.10.0 | `softqcos extensions science`, `softqcos extensions science algorithm`, `softqcos extensions science algorithms`, `softqcos extensions science capabilities`, `softqcos extensions science eigensolve`, `softqcos extensions science evolve`, `softqcos extensions science optimize`, `softqcos extensions science plan`, `softqcos extensions science resource-estimate`, `softqcos extensions science simulate`, `softqcos extensions science validate` |
| 3.9.2 | `softqcos billing report-data` |
| 3.9.0 | `softqcos evidence get`, `softqcos evidence list`, `softqcos evidence runtime`, `softqcos evidence trust`, `softqcos extensions evidence runtime`, `softqcos extensions hal`, `softqcos extensions hal backend`, `softqcos extensions hal backends`, `softqcos extensions hal cancel`, `softqcos extensions hal result`, `softqcos extensions hal status`, `softqcos extensions hal submit`, `softqcos extensions research-apps`, `softqcos extensions research-apps get`, `softqcos extensions research-apps list`, `softqcos extensions research-apps molecular-vqe`, `softqcos extensions research-apps molecular-vqe run`, `softqcos extensions research-apps plan`, `softqcos quantus`, `softqcos quantus advantage`, `softqcos quantus analyze`, `softqcos quantus backends`, `softqcos quantus build`, `softqcos quantus coefficient`, `softqcos quantus compile`, `softqcos quantus evidence`, `softqcos quantus execute`, `softqcos quantus explain`, `softqcos quantus get`, `softqcos quantus lifecycle`, `softqcos quantus normalize`, `softqcos quantus rules`, `softqcos quantus seal`, `softqcos quantus store`, `softqcos quantus suitability`, `softqcos quantus validate`, `softqcos srp`, `softqcos srp compare`, `softqcos srp init`, `softqcos srp inspect`, `softqcos srp run`, `softqcos srp status`, `softqcos srp validate` |
| 3.8.3 | `softqcos extensions evidence`, `softqcos extensions evidence get`, `softqcos extensions evidence list`, `softqcos extensions evidence trust`, `softqcos extensions evidence verify` |
| 3.8.2 | `softqcos extensions dynamics`, `softqcos extensions dynamics analyze`, `softqcos extensions state`, `softqcos extensions state analyze` |
| <=3.8.0 | 329 commands, all present in 3.8.0, the first version of the shared numbering |

Removed (no longer exists):

- `softqcos admin`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos admin audit`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos admin backends-status`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos admin circuit-breakers`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos admin config`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos admin health`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos admin logs`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos admin metrics`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos admin rate-limits`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos admin tenants`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos admin usage`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos evidence artifacts`: since `<=3.8.0`, removed in `3.8.3`
- `softqcos evidence capabilities`: since `<=3.8.0`, removed in `3.8.3`
- `softqcos evidence download`: since `<=3.8.0`, removed in `3.8.3`
- `softqcos evidence public-key`: since `<=3.8.0`, removed in `3.8.3`
- `softqcos extensions autopilot`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos extensions autopilot execute`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos extensions autopilot plan`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos extensions autopilot recommend`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos extensions autopilot vendors`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos extensions macro`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos extensions macro energy-optimize`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos extensions macro health`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos extensions macro market-sizing`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos extensions macro risk-analysis`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos extensions provider-hub list`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos extensions provider-hub register`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos extensions provider-hub remove`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos extensions qlink`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos extensions qlink profile`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos extensions qlink simulate`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos extensions qlink status`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos extensions qlink transfer`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos extensions qubo energy-dispatch`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos extensions qubo portfolio`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos extensions zne`: since `<=3.8.0`, removed in `3.9.2`
- `softqcos extensions zne mitigate`: since `<=3.8.0`, removed in `3.9.2`

<!-- END release-surface -->

## License

Apache License, Version 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).

Copyright 2024-2026 SoftQuantus innovative OÜ (registry code 17048927, Tallinn, Estonia).
QCOS™ and SoftQuantus™ are trademarks of SoftQuantus innovative OÜ; the license does
not grant trademark rights. The QCOS service reached through this package is governed by
the SoftQuantus Terms of Service, not by this license.

- Terms: https://softquantus.com/legal/terms
- Privacy: https://softquantus.com/legal/privacy
- Portal: https://platform.softquantus.com

## Company

**SoftQuantus innovative OÜ**
Registry Code: 17048927
Address: Veskiposti tn 2-1002, Tallinn, 10138, Estonia

## Contact

- **Support:** support@softquantus.com
- **Licensing:** licensing@softquantus.com
- **Legal:** legal@softquantus.com

---

© 2024-2026 SoftQuantus innovative OÜ. All Rights Reserved.
QCOS™ is a trademark of SoftQuantus innovative OÜ.
