Metadata-Version: 2.4
Name: qml-observer
Version: 0.5.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: dashboard
Requires-Dist: fastapi>=0.110; extra == 'dashboard'
Requires-Dist: uvicorn>=0.29; extra == 'dashboard'
Provides-Extra: dev
Requires-Dist: httpx>=0.27; 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)
[![PyPI](https://img.shields.io/pypi/v/qml-observer.svg?cacheSeconds=3600)](https://pypi.org/project/qml-observer/)
[![Python versions](https://img.shields.io/pypi/pyversions/qml-observer.svg)](https://pypi.org/project/qml-observer/)
[![License: MPL-2.0](https://img.shields.io/badge/License-MPL--2.0-brightgreen.svg)](./LICENSE)

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.5.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, the calibration benchmark suite, webhook alerting (including a
> Slack-compatible formatter, alert deduplication/cooldowns, evidence
> redaction, and a webhook-URL SSRF safeguard), an optional read-only
> dashboard (`qml-observer[dashboard]`: live loss/gradient charts, a
> diagnosis panel, compute-usage panel, run history, and data export),
> and opt-in research-grade diagnostics (`qml_observer.advanced`: QFIM
> estimation/conditioning, parameter-redundancy detection,
> Hessian-vector products, loss-landscape sampling, and qubit/depth
> gradient-variance scaling analysis — see `docs/research/geometry.md`)
> are all shipped (Milestones 0–12). 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`.

## Architecture

<p align="center">
  <img src="docs/architecture/diagrams/readme_architecture.svg" alt="QML Observer pipeline: training loop through an adapter into QMLMonitor, statistics, detectors, diagnosis engine, and action policy, which logs, warns, or stops training" width="260">
</p>

Training events flow one-way through the pipeline above; nothing here ever
owns or drives the quantum computation itself (plan.md §2). See
[`docs/architecture/overview.md`](docs/architecture/overview.md) for the
full, module-by-module breakdown, including the diagnosis engine's
weighted-evidence scoring and the opt-in telemetry layer.
