Metadata-Version: 2.4
Name: hnep
Version: 0.2.0
Summary: Hybrid Network Evaluation Protocol — multi-method evaluation for hybrid quantum-classical models
Author-email: Pratik Priyanshu <priyanshupriyam123vv@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Pratik25priyanshu20/HNEP
Project-URL: Documentation, https://github.com/Pratik25priyanshu20/HNEP
Project-URL: Source, https://github.com/Pratik25priyanshu20/HNEP
Project-URL: Issues, https://github.com/Pratik25priyanshu20/HNEP/issues
Keywords: quantum machine learning,evaluation,QML,hybrid models,benchmarking,surrogation,intervention
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: scikit-learn>=1.3
Requires-Dist: pandas>=2.0
Requires-Dist: matplotlib>=3.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: tqdm>=4.65
Provides-Extra: jax
Requires-Dist: jax>=0.4.0; extra == "jax"
Requires-Dist: flax>=0.8.0; extra == "jax"
Requires-Dist: optax>=0.2.0; extra == "jax"
Provides-Extra: pytorch
Requires-Dist: torch>=2.0; extra == "pytorch"
Provides-Extra: qiskit
Requires-Dist: qiskit>=1.0; extra == "qiskit"
Provides-Extra: pennylane
Requires-Dist: pennylane>=0.35; extra == "pennylane"
Provides-Extra: molecular
Requires-Dist: rdkit; extra == "molecular"
Provides-Extra: reports
Requires-Dist: jinja2>=3.1; extra == "reports"
Requires-Dist: plotly>=5.18; extra == "reports"
Provides-Extra: all
Requires-Dist: jax>=0.4.0; extra == "all"
Requires-Dist: flax>=0.8.0; extra == "all"
Requires-Dist: optax>=0.2.0; extra == "all"
Requires-Dist: torch>=2.0; extra == "all"
Requires-Dist: pennylane>=0.35; extra == "all"
Requires-Dist: rdkit; extra == "all"
Requires-Dist: jinja2>=3.1; extra == "all"
Requires-Dist: plotly>=5.18; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.5; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# HNEP — Hybrid Network Evaluation Protocol

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
[![Version](https://img.shields.io/badge/version-0.2.0-orange.svg)](#)
[![Tests](https://img.shields.io/badge/tests-170%20passing-brightgreen.svg)](#)
[![Style](https://img.shields.io/badge/style-ruff-orange.svg)](#)

> **Does the quantum component in your hybrid model actually contribute meaningful computation, or could a classical surrogate replace it?**

Most QML benchmarks report end-task accuracy and call it a day.
**HNEP applies multiple independent probes** to your trained hybrid model — surrogation, structural intervention, error diversity, representation analysis — and returns a verdict you can defend.

---

## Install

```bash
pip install hnep
```

Optional framework extras:

```bash
pip install "hnep[jax]"          # JAX / Flax models
pip install "hnep[pytorch]"      # PyTorch models
pip install "hnep[pennylane]"    # PennyLane quantum backend
pip install "hnep[molecular]"    # RDKit-based molecular utilities
pip install "hnep[reports]"      # interactive HTML reports (jinja2, plotly)
pip install "hnep[all]"          # everything
```

## 30-second quickstart

```python
import hnep

# Wrap your trained model in any of HNEP's adapters
adapter = hnep.FunctionalAdapter(
    name="my_model",
    predict_fn=my_predict,
    extract_quantum_fn=my_extract_quantum,
    predict_with_override_fn=my_predict_override,
    quantum_dim=4,
)

# Run the full HNEP protocol
result = hnep.evaluate(adapter, my_dataset)

print(result.qct_verdict)           # → "Regularizer"
print(result.qct_confidence)        # → 0.94
result.to_html("report.html")       # full HTML report with figures
```

The report opens in your browser as a self-contained HTML file with the **QCT plane**, the **convergent-validity radar**, and a manifest your run can be replayed from.

## What HNEP returns

```text
HNEP Evaluation Report
============================================================
Model:       Hybrid-V1
Dataset:     ESOL (n=1128, scaffold split)

QCT Verdict: Regularizer  (confidence: 0.94)
------------------------------------------------------------
  surrogation    score=0.077  [0.06, 0.10]   → REPLACEABLE
  intervention   score=0.29   [0.22, 0.36]   → LOAD-BEARING
------------------------------------------------------------

Notes:
  • Surrogate swap is safe at inference. Quantum's role appears
    confined to the training phase.
```

## The QCT taxonomy

HNEP classifies your model into one of four roles plus an honest fallback:

|                | LOAD-BEARING        | NOT LOAD-BEARING   |
|----------------|---------------------|--------------------|
| **NECESSARY**  | Genuine Contributor | Unique-but-Ignored |
| **REPLACEABLE**| Architectural Regularizer | Dead Weight  |

When the bootstrap confidence intervals straddle a threshold, HNEP returns `Inconclusive` rather than guessing.

## Adapters

Wrap your model in one line:

| Adapter | Use when |
|---------|----------|
| `FunctionalAdapter` | You can write three Python callbacks. **Most users start here.** |
| `PrecomputedAdapter` | You already cached the test-set extractions to disk. |
| `JaxFlaxAdapter`    | Your model is a Flax module with our standard conventions. |
| `PyTorchAdapter`    | Your model is a `torch.nn.Module` — subclass + override 2 hooks. |

See [`hnep/examples/`](hnep/examples) for runnable examples of each.

## What's in v0.2.0

**Six probes** — each independently answers one question about your hybrid:

| Probe | Question |
|---|---|
| `SurrogationProbe` | Can a classical surrogate reproduce the quantum output? |
| `InterventionProbe` | Does removing the quantum branch hurt performance? |
| `NoiseProbe` | Is the verdict stable under realistic quantum noise? |
| `TemporalProbe` | Does the verdict change across training checkpoints? |
| `ErrorDiversityProbe` | Do quantum and classical branches err on the same molecules? |
| `RepresentationProbe` | CKA + mutual information — which embedding is more target-aligned? |

**Killer outputs**

* `plot_qct_plane`, `plot_convergent_validity_radar`, `plot_pareto_with_hardware_cost`
* `plot_disagreement_heatmap` — probes × datasets verdict grid
* `plot_activation_atlas` — UMAP/t-SNE/PCA projection of quantum outputs
* **Molecular Chemistry Gallery** — RDKit-rendered top-K / bottom-K molecules by QCI, embedded in the HTML report
* **HNEPCard** — single-glance summary card (text / Markdown / HTML)
* **Verdict explainer** — `result.explain()` returns a deterministic plain-English paragraph naming the evidence behind the verdict
* **Paper-ready exports** — `result.to_latex()` (`booktabs` tables) and `result.to_markdown()` (README-ready)
* HTML / JSON / CSV reports + manifest files for reproducibility

**CLI**

```bash
hnep card result.json --format markdown
hnep compare model_a.json model_b.json model_c.json --format html -o compare.html
```

**Adapters** — Functional, Precomputed, JAX/Flax, PyTorch skeleton (heavy deps lazy-imported).

## Roadmap

See [`docs/HNEP_LIBRARY_ROADMAP.md`](docs/HNEP_LIBRARY_ROADMAP.md) for the version-by-version plan.

* **v0.3** — permutation-derived thresholds, atom-level QCI, Weights & Biases / Hugging Face / GitHub Action integrations
* **v0.4** — `hnep.dev` web sandbox
* **v0.5** — HNEP Doctor (AI-powered recommendations)
* **v1.0** — frozen API, HNEP Arena leaderboard, governance committee

## Documentation

Locally:

```bash
pip install "hnep[dev]"
cd docs_hnep && make html
open _build/html/index.html
```

Or skim the [Sphinx source files](docs_hnep/) directly.

## Citing HNEP

```bibtex
@misc{priyanshu2026hnep,
  title  = {HNEP: Hybrid Network Evaluation Protocol for Quantum Machine Learning},
  author = {Priyanshu, Pratik},
  year   = {2026},
  url    = {https://github.com/Pratik25priyanshu20/HNEP},
}
```

## License

MIT. See [LICENSE](LICENSE).
