Metadata-Version: 2.4
Name: catalyst-q
Version: 0.2.0
Summary: Closed-source freemium Python SDK for the Catalyst-Q API
Home-page: https://catalyst-q-sdk.strategic-innovations.ai/docs
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 SDK

[![Documentation](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/)

Catalyst-Q is a closed-source, freemium Python SDK for exact, benchmark-validated quantum circuit execution and optimization workloads through the Catalyst-Q API.

The public SDK focuses on what users need to build: QASM inputs, SDK circuit objects, standard optimization model payloads, accountless development usage, benchmark artifacts, and production licensing. Implementation details are intentionally not documented or distributed in this package.

## Install

```bash
pip install catalyst-q

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

The free developer tier includes 10,000 circuit runs/month for 50-qubit circuits, 500 solver runs/month, and 5M compute units/month for development and evaluation. Production use requires a paid server-side license.

Private, offline, and local workflows require custom licensing. Contact Strategic Innovations AI for private deployment licensing.

## Accepted Inputs

Catalyst-Q accepts the input formats teams already use in 2026 quantum and optimization workflows:

- QASM and OpenQASM-style circuit text
- SDK circuit objects for programmatic circuit construction
- SAT, TSP, Knapsack, Portfolio, QUBO, Max-Cut, DAG Optimization, VRP, and Unit Commitment payloads
- JSON-ready request objects for direct HTTP clients and CI harnesses

## QASM Execution

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

# Send request.method, request.url, request.headers, and request.json
# with your preferred HTTP client.
```

## SDK Circuit 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-circuit", shots=1024)
```

## Optimization Model Payloads

```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")
```

## HD-QML: Extreme Quantum Cognition Machines (EQCM)

The SDK now natively supports **Hyperdimensional Quantum Machine Learning (HD-QML)** via the `EQCMPolicyBuilder` primitive in `catalyst_rain`. This allows autonomous agents to offload dense cognitive weight optimization (up to 800-variable QUBO spaces) to the simulated bifurcation solver in milliseconds.

```python
from catalyst_rain import EQCMPolicyBuilder

# Initialize builder for 10 cognitive heuristics, 8-bit precision (80 variables)
builder = EQCMPolicyBuilder(num_weights=10, bits_per_weight=8)

# Input hyperdimensional resonance scores generated natively at the edge
qubo_matrix = builder.build_qubo_matrix(resonance_scores)

# Ship the optimization landscape to the Catalyst-Q cloud solver
request = client.prepare_qubo({"matrix": qubo_matrix})
```

## Solver Rescue

Use Catalyst-Q as a challenger and MIP-start generator for hard, time-limited operational models. Export a small JSON file from historical solver runs, then generate an executive comparison report with charts, a Markdown audit trail, machine-readable JSON, and `.mst` starts for feasible Catalyst-Q candidates.

```bash
catalyst-q-rescue \
  --input hard-energy-runs.json \
  --output-dir solver-rescue-pilot
```

The report documents measured deltas for supplied cases: feasible rescues, incumbent improvements, gap, runtime, estimated business value, and recommended handoff into the existing solver workflow.

For local-model triage, package one hard case as a rescue copilot dossier. The copilot writes a trace for Catalyst Brain or a local planner, then emits the standard rescue report when a Catalyst-Q candidate is included.

```bash
catalyst-q-rescue-copilot \
  --input solver-rescue-case.json \
  --output-dir solver-rescue-copilot
```

This command is offline. It does not call Ollama, Gurobi, Catalyst Brain, or the hosted Catalyst-Q API; those systems can feed it baseline and candidate runs.

## ATC Flow Replay

Train a small Catalyst Brain/LHW-style adapter from a ZIP knowledge pack, then use it for offline air traffic flow replay. This is shadow-mode decision support for human review; it is not live ATC, separation assurance, or clearance issuance.

```bash
catalyst-q-atc-flow train \
  --zip Catalyst_PostCartesian_Patent_Pack.zip \
  --output-dir atc-flow-model

catalyst-q-atc-flow replay \
  --adapter atc-flow-model/catalyst_airspace_lhw_adapter.json \
  --scenario atc-flow-scenario.json \
  --output-dir atc-flow-replay
```

The replay emits a JSON trace, Markdown plan, and CSV assignment table with capacity checks, modeled delay delta, and a hard `human_review_required` status.

## Benchmarks

```bash
catalyst-q-benchmark --execute-api \
  --base-url https://api.strategic-innovations.ai/v3turbo \
  --output-dir catalyst-q-live-api-benchmarks
```

The harness emits deterministic JSON and Markdown artifacts with `latency_ms`, `response_bytes`, `status_code`, and `response_sha256` for each request. Benchmark claims are empirical and tied to generated artifacts.

## Proof Harness

```bash
catalyst-q-prove --output-dir catalyst-q-proof-results
```

The proof harness emits deterministic TSP and VQE JSON/Markdown artifacts with public baselines, result hashes, and benchmark-limited claim language. The results are evidence for the fixed proof cases only, not a theorem about all workloads.

## Licensing

- Developer Free: development and evaluation only.
- Starter, Team Pro, and Scale: paid production tiers enforced by the hosted API.
- Private, offline, and local workflows: custom licensing only.

Pricing and licensing details are published at https://catalyst-q-sdk.strategic-innovations.ai/docs/pricing.
