Metadata-Version: 2.4
Name: qai-photonic
Version: 1.3.0
Summary: QAI photonic quantum language, compiler, runtime, and backends
Author: Dmitrii Ershov
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lark>=1.1
Provides-Extra: perceval
Requires-Dist: perceval-quandela<1.3,>=1.2.4; extra == "perceval"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Dynamic: license-file

# QAI

QAI is a photonic-quantum-native language, compiler, typed intermediate representation, runtime, and backend architecture.

QAI source is parsed and semantically analyzed, lowered into backend-independent typed Photonic IR, and executed through backend capability contracts. The current backends include the deterministic Reference backend and a Perceval backend.

## Platform Foundation 1.3

QAI 1.3 adds typed local execution requests and jobs, structured errors, backend capability contracts, versioned platform serialization, experiment manifests, provenance, immutable events, resource controls, and explicit isolation requirements. It preserves the Runtime 1.2 adaptive training and checkpoint APIs. See [the 1.3 release notes](CHANGELOG.md) and [the platform architecture](docs/platform-foundation-1.3.md) for scope and limitations.

## Runtime 1.2

QAI Runtime 1.2 adds adaptive measurement-aware photonic training on top of the Runtime 1.1 finite-shot and Runtime 1.0 exact-gradient stacks.

The 1.2 surface includes:

- explicit physical shot-cost and shifted-program evaluation accounting;
- variance-aware shot allocation for exact generalized photonic shift rules;
- `GlobalMeasurementBudget` for fixed per-gradient budgets and `AdaptiveMeasurementBudget` for pilot-driven adaptive allocation;
- integer-optimal discrete shot allocation;
- finite-shot phase and beam-splitter reflectivity gradients;
- program-level occurrence materialization for tied parameters;
- deterministic independent sub-seeds across shifted measurements and resumable sampler position;
- covariance-safe measurement reuse plus experiment-wide `TotalExperimentBudget` accounting;
- gradient uncertainty, precision refinement, convergence-aware stopping, and opt-in training telemetry;
- differentiable loss contracts and persistent `AdaptiveTrainingState` checkpoint/resume.

Runtime 1.1 fixed-budget training remains available with `GlobalMeasurementBudget`, while Runtime 1.0 exact-gradient training remains the default when measurement controls are omitted.

The source language and parameterized Photonic IR remain version 0.2.

See `docs/runtime-spec-1.2.md` for the Runtime 1.2 contract, `docs/runtime-spec-1.1.md` for the fixed-budget baseline, and `docs/runtime-spec-1.0.md` for exact differentiation.

## Runtime 1.0 exact gradients

Runtime 1.2 retains generalized Fourier parameter-shift rules, topology-aware local photon-number spectra, exact phase gradients, exact interior reflectivity gradients, tied-parameter occurrence summation, mixed phase + reflectivity gradients, and `GradientDescentOptimizer`.

## Example: adaptive measurement-aware training

```python
from qai_core.runtime import (
    AdaptiveMeasurementBudget,
    TotalExperimentBudget,
    GradientDescentOptimizer,
    MeanSquaredError,
)

result = model.fit(
    train_batch,
    feature,
    MeanSquaredError(),
    GradientDescentOptimizer(iterations=24, learning_rate=0.2),
    bounds=bounds,
    backend="reference",
    seed=1234,
    measurement_budget=AdaptiveMeasurementBudget(
        total_shots=4000,
        pilot_shots_per_vector=20,
    ),
    measurement_center_shots=1000,
    total_experiment_budget=TotalExperimentBudget(50000),
)

trained_model = result.model
```

Use `GlobalMeasurementBudget` for the Runtime 1.1 fixed-budget path. Omit measurement controls to use the deterministic exact-gradient Runtime 1.0 path.

## Compatibility

Runtime 1.2 preserves the Runtime 1.1 fixed-budget finite-shot APIs and Runtime 1.0 deterministic gradient APIs, Runtime 0.9 trainer/model APIs, Runtime 0.7 optimizer APIs, Runtime 0.6 deterministic single-parameter grid optimizer, the `qai optimize` CLI, and the 0.6 scalar optimization JSON format.

The QAI source language and parameterized Photonic IR remain version 0.2.

## Architecture

```text
QAI SOURCE (.qai)
    |
    v
Grammar / Parser
    |
    v
SemanticAnalyzer
    |
    v
Typed Photonic IR
    |
    v
Backend API
    |
    +--> Reference
    +--> Perceval
    +--> future QPU

Parameterized Photonic IR
    |
    v
PhotonicModel
    |
    +--> INPUT values from ModelBatch
    +--> TRAINABLE parameters
    +--> FROZEN parameters
    |
    v
Predictions / Loss
    |
    +--> derivative-free optimizer path
    |
    +--> exact photonic gradient path (Runtime 1.0)
    |
    +--> adaptive measurement-aware finite-shot path (Runtime 1.2)
            |
            +--> generalized exact shift rules
            +--> topology-aware spectra
            +--> fixed or adaptive variance-aware shot allocation
            +--> finite-shot backend sampling
            +--> covariance-safe measurement reuse
            +--> total/dynamic experiment budgets
            +--> uncertainty / precision refinement
            +--> telemetry / adaptive checkpoint-resume
            +--> differentiable loss chain rule
            +--> GradientDescentOptimizer
    |
    v
Trainer / trained immutable model
```

Runtime services such as sampling, sweeps, observables, optimization, training, checkpointing, resume, and model persistence remain outside the source language and Photonic IR unless deliberately standardized in a future language/IR revision.

## Development

Create and activate a virtual environment, install the project and test dependencies, then run:

```bash
pytest -q
```

For packaging verification:

```bash
python -m build
```

GitHub Actions tests Python 3.11/3.12 and performs packaging smoke tests as part of release validation. See the [release security guide](docs/release-security-1.3.md) for the current release hold and maintainer checklist, and [SECURITY.md](SECURITY.md) for private vulnerability reporting.

## Specifications

- `docs/language-spec-0.1.md`
- `docs/language-spec-0.2.md`
- `docs/runtime-spec-0.3.md`
- `docs/runtime-spec-0.4.md`
- `docs/runtime-spec-0.5.md`
- `docs/runtime-spec-0.6.md`
- `docs/runtime-spec-0.7.md`
- `docs/runtime-spec-0.8.md`
- `docs/runtime-spec-0.9.md`
- `docs/runtime-spec-1.0.md`
- `docs/runtime-spec-1.1.md`
- `docs/runtime-spec-1.2.md`

## License

See `LICENSE`.
