Metadata-Version: 2.4
Name: qml-observer
Version: 0.1.0
Summary: Observability and diagnostic framework for variational quantum machine learning training.
Project-URL: Homepage, https://github.com/insightlabs38-pixel/QML-Observer
Project-URL: Repository, https://github.com/insightlabs38-pixel/QML-Observer
Project-URL: Issues, https://github.com/insightlabs38-pixel/QML-Observer/issues
Project-URL: Documentation, https://github.com/insightlabs38-pixel/QML-Observer/tree/main/docs
Author: QML Observer Contributors
License-Expression: MPL-2.0
License-File: LICENSE
Keywords: barren plateau,observability,pennylane,qiskit,quantum machine learning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.12
Requires-Dist: numpy>=1.26
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: pennylane
Requires-Dist: pennylane>=0.35; extra == 'pennylane'
Provides-Extra: qiskit
Requires-Dist: qiskit-machine-learning>=0.7; extra == 'qiskit'
Requires-Dist: qiskit>=1.0; extra == 'qiskit'
Description-Content-Type: text/markdown

# QML Observer

[![CI](https://github.com/insightlabs38-pixel/QML-Observer/actions/workflows/ci.yml/badge.svg)](https://github.com/insightlabs38-pixel/QML-Observer/actions/workflows/ci.yml)
[![License: MPL-2.0](https://img.shields.io/badge/License-MPL--2.0-brightgreen.svg)](./LICENSE)
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](./pyproject.toml)

An open-source observability and diagnostic framework for variational quantum
machine learning (QML) training. QML Observer watches training runs in real
time, detects pathologies such as probable barren plateaus, stagnation, and
noise-dominated optimization, and can log, warn, pause, or stop training
before expensive quantum computation is wasted.

> **Status:** v0.1.0 — public beta. Core schemas, monitoring engine,
> detectors, diagnosis engine, actions, both the PennyLane and Qiskit
> adapters, JSONL logging, run summaries, compute-saved estimation, the
> CLI, and the calibration benchmark suite are all shipped (Milestones
> 0–8). See `CHANGELOG.md` for the full release notes and
> `docs/roadmap.md` for what's next. **The `0.x` API is not yet stable
> and may change without a major-version bump**, per SemVer's `0.x`
> convention.
>
> Note: the `"pause"` action-policy mode currently behaves identically to
> `"warn"` — a distinct pause-and-preserve-state action (`PauseAction`)
> is planned for Milestone 13 and is not yet implemented. See
> `docs/architecture/actions.md`.

## Scope note

QML Observer targets **simulator-based training only** through the MVP and
all `0.x` releases. Real hardware / cloud QPU integration (IBM Quantum, AWS
Braket, IonQ, etc.) is explicitly out of scope until dedicated funding is
secured. See `docs/roadmap.md` for what hardware support would require.

## Positioning

QML Observer identifies **probable plateau-like failure modes** based on
observed training signals — it does not claim definitive, guaranteed barren
plateau detection in all settings. This distinction is central to the
project's scientific credibility.

## Quickstart

The generic, framework-agnostic path — works with any training loop:

```python
from qml_observer import QMLMonitor
from qml_observer.detectors.barren_plateau import BarrenPlateauDetector
from qml_observer.detectors.convergence import ConvergenceDetector
from qml_observer.detectors.stagnation import StagnationDetector

monitor = QMLMonitor(
    detectors=[
        BarrenPlateauDetector(),
        StagnationDetector(loss_threshold=1e-6, patience=100),
        ConvergenceDetector(loss_threshold=1e-3, gradient_threshold=1e-6, patience=50),
    ],
    policy="warn",
)

for step in range(1000):
    loss, gradients = train_step()  # your own training code
    diagnosis = monitor.update(step=step, loss=loss, gradients=gradients)
    if monitor.should_stop():
        break

print(monitor.finish())
```

Detectors are stateful, so build a fresh list per monitor/run. See the
flagship `examples/pennylane/barren_plateau_demo.py` and
`examples/qiskit/barren_plateau_demo.py` for a complete runnable version
of this pattern with `policy="stop"`.

`monitor.update()` accepts optional `parameters`, `circuit`, `optimizer`,
and `shots` for richer diagnostics. See
[`docs/integrations/generic.md`](./docs/integrations/generic.md) for the
full generic-adapter guide, and the PennyLane/Qiskit examples below for
framework-specific integration.

## Examples

Runnable examples live under `examples/`. PennyLane examples (requires
`pip install -e ".[dev,pennylane]"`):

- `examples/pennylane/basic_monitor.py` — minimal QNode + `QMLMonitor`
  integration, no detectors.
- `examples/pennylane/barren_plateau_demo.py` — the project's flagship
  demo: a healthy run that is never stopped early, contrasted with a
  collapsed-gradient run that is stopped early with an estimated
  compute-saved figure.
- `examples/pennylane/noisy_training.py` — training under a small finite
  shot budget, showing noisier per-step gradient statistics without
  false-positive plateau detection.

Qiskit examples (requires `pip install -e ".[dev,qiskit]"`):

- `examples/qiskit/basic_monitor.py` — minimal `QuantumCircuit` +
  `QMLMonitor` integration via manual parameter-shift gradients, no
  detectors.
- `examples/qiskit/barren_plateau_demo.py` — the Qiskit version of the
  flagship demo: a healthy run that is never stopped early, contrasted
  with a collapsed-gradient run that is stopped early with an estimated
  compute-saved figure.
- `examples/qiskit/vqc_callback_demo.py` — wires `QiskitAdapter.callback`
  directly into a real `qiskit-machine-learning` `VQC` trainer's own
  `callback=` hook, with no manual training loop at all.

## Reporting & CLI

Wire a `RunReporter` into `QMLMonitor` to get a JSONL event/diagnosis log
plus a run summary (including an estimated compute-saved figure) on
`finish()`:

```python
from qml_observer import QMLMonitor
from qml_observer.reporting.reporter import RunReporter

reporter = RunReporter("runs/run.jsonl", framework="pennylane", planned_steps=1000)
monitor = QMLMonitor(reporter=reporter, planned_steps=1000)
```

Then inspect the log from the command line:

```bash
qml-observer report runs/run.jsonl   # human-readable run summary
qml-observer inspect runs/run.jsonl  # every logged record as pretty JSON
```

See [`docs/integrations/qiskit.md`](./docs/integrations/qiskit.md) for the
Qiskit adapter guide.

## Benchmarks & calibration

`benchmarks/run_benchmarks.py` reproduces the false-positive-rate and
detection-latency numbers that chose the detectors' default thresholds;
`benchmarks/qml_observer_benchmark.ipynb` walks through the same results
alongside the live "critical MVP demo". See
[`docs/research/validation.md`](./docs/research/validation.md) for the
full methodology and current results.

## Documentation

Full docs (installation, quickstart, "how to interpret alerts",
architecture, per-detector guides, calibration methodology, and
contributor guides) live under [`docs/`](./docs/index.md).

## Installation

From PyPI:

```bash
pip install qml-observer
```

With an optional framework adapter:

```bash
pip install "qml-observer[pennylane]"
pip install "qml-observer[qiskit]"
```

For local development (editable install with lint/test/type-check tooling):

```bash
pip install -e ".[dev]"
```

**Supported Python versions:** 3.12 and 3.13, on a rolling two-version
window that tracks upstream CPython releases (see `CONTRIBUTING.md`).

**Framework compatibility:**

| Extra        | Tested against        |
|--------------|------------------------|
| `pennylane`  | PennyLane >= 0.35      |
| `qiskit`     | Qiskit >= 1.0, qiskit-machine-learning >= 0.7 |

## Known limitations

- **Diagnoses are probabilistic, not proof.** `POSSIBLE_BARREN_PLATEAU`
  and related issue types describe a pattern consistent with a training
  pathology, observed from loss/gradient statistics — they are not a
  formal, definitive proof of a barren plateau or any other failure mode.
- **`"pause"` currently behaves as `"warn"`.** A distinct pause-and-resume
  action (`PauseAction`) is planned for Milestone 13 and is not yet
  implemented.
- **Simulator-only.** Real hardware/cloud QPU backends (IBM Quantum, AWS
  Braket, IonQ, etc.) are out of scope until Milestone 14+ / dedicated
  funding — see `docs/roadmap.md`.
- **Default detector thresholds are empirically calibrated, not
  universal.** They were tuned against the synthetic benchmark suite in
  `benchmarks/`, not against every possible ansatz/qubit-count/noise
  regime — see `docs/research/validation.md` for methodology and current
  false-positive/detection-latency numbers.
- **Not thread-safe.** One `QMLMonitor` per process/rank is the
  recommended pattern for multi-process training; see the Concurrency
  note in `docs/architecture/overview.md`.
- **No automated recovery yet.** The diagnosis/action layers are
  observational; automatic remediation (re-initialization, ansatz
  switching, etc.) is a post-1.0 feature (Milestone 13).

## Experimental / 0.x API stability

QML Observer is in public beta. The `0.x` API surface may still change
between minor releases as the project incorporates community feedback;
breaking changes will be called out in `CHANGELOG.md` rather than
guaranteed stable per SemVer's `0.x` convention.

## License

Mozilla Public License 2.0 (MPL-2.0). See [`LICENSE`](./LICENSE) and
[`CONTRIBUTING.md`](./CONTRIBUTING.md#license) for rationale.
