Metadata-Version: 2.4
Name: advay-platform-server
Version: 0.3.0
Summary: Advay Labs quantum platform SDK — run OpenQASM 3 circuits against the SQPU emulator, get resource projections and noise estimates
Author-email: Advay Labs Private Limited <support@advaylabs.com>
Maintainer-email: Advay Labs Private Limited <support@advaylabs.com>
License: Proprietary
Project-URL: Homepage, https://advaylabs.com
Project-URL: Documentation, https://advaylabs.com/docs
Project-URL: API Console, https://advaylabs.com/dashboard
Project-URL: Issue Tracker, https://advaylabs.com/support
Keywords: quantum,quantum-computing,qasm,openqasm,qiskit,simulator,surface-code,fault-tolerance,advay-labs,sqpu
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python
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 :: Only
Classifier: Operating System :: OS Independent
Classifier: License :: Other/Proprietary License
Classifier: Natural Language :: English
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: stim>=1.13
Requires-Dist: qiskit>=1.0
Requires-Dist: qiskit_qasm3_import>=0.5
Requires-Dist: pymatching>=2.1
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# advay-platform

[![Python: 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: Proprietary](https://img.shields.io/badge/license-Proprietary-orange.svg)](#license)

Python SDK for the **Advay Labs Quantum Platform**. Run OpenQASM 3
circuits against our hosted SQPU emulator, get realistic noise projections
and surface-code resource estimates, all from a single `pip install`.

```bash
pip install advay-platform
```

## What you get

- **Cloud emulator access** — submit OpenQASM 3 circuits to
  `dev.advaylabs.com`, get counts back.
- **Local emulator** — the same compute stack also runs offline on your
  machine for unit tests and CI; no API key required for local use.
- **Resource projection** — surface-code physical-qubit cost, code distance,
  T-factory count, and wall-clock for your circuit on the SQPU roadmap
  device, with factor-of-2 honest bounds.
- **Noise projection** — end-to-end success probability under three
  control modes (`full` / `hybrid` / `reduced`), calibrated to the digital
  twin's gate-time ceilings.
- **OpenQASM 3 support** — classical control flow (`if_else`), mid-circuit
  measurement, and proper feedforward simulation included.
- **Qiskit interop** — `qiskit.QuantumCircuit` objects are accepted as
  input alongside QASM strings.

## Quick start

### Run a circuit against the cloud API

```python
import os
import requests

QASM = """
OPENQASM 3.0;
include "stdgates.inc";
qubit[2] q;
bit[2]   c;
h  q[0];
cx q[0], q[1];
c[0] = measure q[0];
c[1] = measure q[1];
"""

resp = requests.post(
    "https://advaylabs.com/api/v1/run",
    headers={"Authorization": f"Bearer {os.environ['ADVAY_API_KEY']}"},
    json={"qasm": QASM, "options": {"shots": 1024}},
    timeout=60,
).json()

print(resp["response"]["status"])                 # "succeeded"
print(resp["response"]["ideal_result"]["counts"]) # {'00': 510, '11': 514}
```

You'll need an API key from [the dashboard](https://advaylabs.com/dashboard/api-keys).

### Run a circuit locally (offline)

```python
from advay_platform import run_circuit, RunOptions

result = run_circuit(open("bell.qasm").read(), RunOptions(shots=1024))
print(result.ideal_result.counts)
```

The full emulator is bundled in the wheel — no network call required.
Useful for CI and quick iteration on small circuits.

### Typed request options

```python
from advay_platform import RunOptions

opts = RunOptions(
    shots=1024,
    control_mode="hybrid",   # "full" | "hybrid" | "reduced"
    seed=42,                  # repeatable runs
    execute=True,             # set False to skip ideal execution
    resource_estimate=True,
    noise_projection=True,
)
```

Pass `opts.model_dump()` as the `options` field when calling the REST API,
or pass the `RunOptions` object directly to the local `run_circuit()`.

## What the response contains

Every `run_circuit()` call (and every `POST /api/v1/run`) returns four
chunks:

```
response
├── circuit_summary      # qubits, depth, gate counts, Clifford check
├── ideal_result         # noiseless simulator counts
├── resource_projection  # surface-code physical qubits, code distance,
│                        # T-factories, wall-clock — with factor-of-2 bounds
├── noise_projection     # end-to-end success probability per control mode
└── provenance           # run_id, platform version, twin version, tags
```

See the [response format reference](https://advaylabs.com/docs/response-format)
for field-by-field details.

## CLI

The wheel installs an `advay-platform` command:

```bash
# Platform info
advay-platform info

# Run a QASM file
advay-platform run bell.qasm --shots 1024 --output-format json

# Pipe QASM from stdin
cat bell.qasm | advay-platform run - --shots 256
```

## Supported gates

**Clifford** (fast, no qubit cap):
`i`, `x`, `y`, `z`, `h`, `s`, `sdg`, `sx`, `sxdg`, `cx`, `cy`, `cz`,
`swap`, `iswap`, `measure`, `reset`, `barrier`.

**Non-Clifford** (state-vector simulator, ≤22 qubits by default):
`t`, `tdg`, `rx`, `ry`, `rz`, `p`, `u`, `u1`, `u2`, `u3`, `ccx`, `ccz`,
`cswap`, `crx`, `cry`, `crz`, `cp`, `cu`, `rxx`, `ryy`, `rzz`, `mcx`, `mcz`.

Classical feedback (`if_else`, mid-circuit measurement, conditional
gates) is fully supported in both the local emulator and the cloud API.

## Compatibility

| Component | Version |
|-----------|---------|
| Python | 3.10, 3.11, 3.12 |
| OS | Linux, macOS, Windows (pure-Python wheel) |
| qiskit | ≥ 1.0 |
| OpenQASM | 3.0 |

## Free tier

- 30-day free trial on signup.
- 20 SDK calls per day on the free tier.
- Verified academic emails (`.edu`, `.ac.uk`, `.ac.in`, `.edu.au`, …) get
  the free tier with no expiry and no daily cap.

Upgrade to the researcher or commercial tier via
[support@advaylabs.com](mailto:support@advaylabs.com).

## Documentation

- **Getting started**: <https://advaylabs.com/docs/getting-started>
- **API reference**: <https://advaylabs.com/docs/api-reference>
- **Examples**: <https://advaylabs.com/docs/examples>
- **Troubleshooting**: <https://advaylabs.com/docs/troubleshooting>

## Support

- Email: <support@advaylabs.com>
- Status: <https://advaylabs.com/status>

## License

Proprietary. © 2026 Advay Labs Private Limited. All rights reserved.

See LICENSE for terms. Free for evaluation and research use under the
preview tier; commercial use requires a license agreement — contact
[support@advaylabs.com](mailto:support@advaylabs.com).
