Metadata-Version: 2.4
Name: catalyst-q
Version: 0.3.0
Summary: Exact, certificate-backed quantum-circuit execution & optimization — Python SDK for the Catalyst-Q API
Author: Strategic Innovations AI
License: Proprietary
Project-URL: Homepage, https://catalyst-q-sdk.strategic-innovations.ai/docs
Project-URL: Documentation, https://catalyst-q-sdk.strategic-innovations.ai/docs
Project-URL: Benchmarks, https://catalyst-q-sdk.strategic-innovations.ai/docs/benchmarks
Project-URL: Pricing, https://catalyst-q-sdk.strategic-innovations.ai/docs/pricing
Keywords: catalyst-q,quantum-sdk,benchmarking,circuit-simulation,optimization,np-solvers,cloudflare
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Catalyst-Q

[![Docs](https://img.shields.io/badge/docs-catalyst--q-0f6b57.svg)](https://catalyst-q-sdk.strategic-innovations.ai/docs)
[![License](https://img.shields.io/badge/License-Proprietary-bb6b00.svg)](https://catalyst-q-sdk.strategic-innovations.ai/docs/pricing)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

**Exact answers you can re-check — for quantum circuits and hard optimization, with replayable evidence attached.**

Catalyst-Q is a Python SDK + hosted API for **exact, certificate-backed** quantum-circuit execution and combinatorial optimization. Every result ships with a re-runnable proof artifact (a `.rain` certificate): a number you can verify yourself, not a black-box guess. Implementation details are intentionally not distributed in this package; what you get is a clean client for building.

```bash
pip install catalyst-q
```

## What it's good at

**1. Exact circuit execution with replayable evidence.**
Catalyst-Q answers the observable you ask for — an amplitude, a basis-state
probability, a Pauli expectation, or a sampled distribution — through hosted,
certificate-backed execution. On fixed public benchmark cases (SuperMarQ,
QED-C, QASMBench, MQT) the SDK emits exact results and deterministic artifacts
you can re-run and inspect. The public package documents the request/response
contract, evidence format, and benchmark harness; proprietary implementation
details stay server-side.

**2. Optimization with a proof, not a promise.**
QUBO, SAT, TSP, Max-Cut, Portfolio, Knapsack, Vehicle Routing, Unit Commitment, and DAG optimization — solved to an **exact certificate** where provable, or used as a **challenger / MIP-start generator** on hard, time-limited operational models. You get the answer *and* the evidence.

**3. Chemistry-grade VQE.**
Ground-state energies validated to **far below chemical accuracy** on the fixed proof cases (e.g. H₂/STO-3G), with the variational parameter count held flat as system size grows. Evidence ships as deterministic JSON/Markdown artifacts.

**4. Everything is re-runnable.**
The proof and benchmark harnesses emit deterministic artifacts with public baselines, result hashes, and latency/size telemetry. Claims are tied to generated evidence for the fixed cases — not asserted as theorems about all workloads.

### Honest scope
Catalyst-Q is **exact and memory-bounded for the published benchmark circuit
families**; the main variable that scales is *time*, and it scales with the
circuit's real structure — fast for structured, bounded-treewidth, and low-magic
circuits at large scale, and slower (worst-case exponential, as for any exact
method) for fully volume-law random circuits. It makes **no** claims of Shor's
algorithm, breaking cryptography, broad hardware-advantage claims, or solving
NP in general. Benchmark numbers refer to the specific generated artifacts.

## Install

```bash
pip install catalyst-q

# Controlled hosted index:
pip install --index-url https://catalyst-q-sdk.strategic-innovations.ai/simple catalyst-q
```

Free developer tier: full public gate set up to 100 qubits for evaluation, with
10 hosted API executions/month and 100 compute credits/month. Production use
requires a paid server-side license. Private/offline/local deployment requires
custom licensing — contact Strategic Innovations AI.

## Quickstart

### Run a circuit (SDK objects)

```python
from catalyst_q import CatalystQClient, QuantumCircuit

client = CatalystQClient()
circuit = QuantumCircuit(2).h(0).cx(0, 1).measure(0, 0).measure(1, 1)
request = client.prepare_execute(circuit, workflow_id="bell", shots=1024)
# send request.method / request.url / request.headers / request.json with your HTTP client
```

### Run a circuit (QASM)

```python
from catalyst_q import CatalystQClient

client = CatalystQClient()
qasm = """
OPENQASM 2.0;
qreg q[2]; creg c[2];
h q[0]; cx q[0],q[1];
measure q[0] -> c[0]; measure q[1] -> c[1];
"""
request = client.prepare_qasm(qasm, workflow_id="bell-qasm", shots=1024)
```

### Solve an optimization model (with a certificate)

```python
from catalyst_q import CatalystQClient, MaxCutProblem

client = CatalystQClient()
problem = MaxCutProblem(edges=[(0, 1, 1.0), (1, 2, 2.0), (0, 2, 0.5)], nodes=3)
request = client.prepare_maxcut(problem, workflow_id="maxcut-demo")
```

Accepted inputs: QASM / OpenQASM circuit text, SDK circuit objects, and SAT / TSP / Knapsack / Portfolio / QUBO / Max-Cut / DAG / VRP / Unit-Commitment payloads — plus JSON-ready request objects for direct HTTP clients and CI harnesses.

## Prove it yourself

```bash
catalyst-q-prove   --output-dir catalyst-q-proof-results      # deterministic TSP + VQE evidence
catalyst-q-benchmark --execute-api \
  --base-url https://api.strategic-innovations.ai/v3turbo \
  --output-dir catalyst-q-live-api-benchmarks                 # latency / bytes / status / sha256 per request
```

Both emit deterministic JSON + Markdown artifacts with public baselines, result hashes, and benchmark-limited claim language — evidence for the fixed cases, re-runnable by you.

## Operational add-ons

- **Solver Rescue** — `catalyst-q-rescue` / `catalyst-q-rescue-copilot`: use Catalyst-Q as a challenger and MIP-start (`.mst`) generator for hard, time-limited models; emits an executive comparison report (feasible rescues, incumbent improvements, gap, runtime, estimated value) with a Markdown audit trail. The copilot path is fully offline.
- **HD-QML (EQCM)** — `EQCMPolicyBuilder` in `catalyst_rain`: build a QUBO landscape (up to ~800 variables) from edge-side resonance scores and ship it to the cloud solver in milliseconds.
- **ATC Flow Replay** — `catalyst-q-atc-flow`: train a small adapter from a knowledge pack and run **shadow-mode** air-traffic-flow decision support for human review. Not live ATC, separation assurance, or clearance issuance; every plan carries a hard `human_review_required` status.

## Licensing

- **Developer Free** — $0 for development and evaluation only; 100 qubits, 10 hosted API executions/month, and 100 compute credits/month.
- **Starter Production** — $99/month for one production app or pilot; 250 qubits and 2,000 compute credits/month.
- **Team Pro** — $399/month for team workflows and CI; 500 qubits and 12,000 compute credits/month.
- **Scale** — $1,500/month and up for embedded production use; 2,000 qubits and 75,000 compute credits/month.
- **Private / offline / local** — custom licensing only.

Credits scale with qubit level, circuit depth, shot count, solver problem size,
and replayable evidence workflows. Local validation and malformed-request
preflight checks should not consume credits; accepted hosted executions do.

Pricing: https://catalyst-q-sdk.strategic-innovations.ai/docs/pricing
