hnep 0.1.0__tar.gz

hnep-0.1.0/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+All notable changes to HNEP are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/) and
+this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — 2026-06-21
+
+First public release. The library is feature-complete for the QCT workflow
+and is published as an **alpha** — APIs may shift in 0.x as users discover
+edge cases. Semver guarantees begin at 1.0.
+
+### Added — Core
+- `hnep.evaluate(model, dataset)` — top-level one-line evaluation.
+- `HNEPResult` aggregating QCT verdict + per-probe results + manifest, with
+  `.to_html()`, `.to_json()`, `.to_csv()` exports.
+- `Dataset`, `ModelInterface` — the framework-agnostic adapter contract.
+
+### Added — Probes
+- `SurrogationProbe` — 8-surrogate ladder (Ridge, KNN, RF, GB, four MLPs)
+  with bootstrap confidence intervals and the most-conservative headline SS.
+- `InterventionProbe` — `do()`-operator family: `zero_quantum`,
+  `random_noise`, `permute`, `constant`. Headline = zero-quantum drop.
+- Both probes report per-sample data, per-sub-probe scores, and a notes
+  field for caveats (e.g. surrogate failure modes).
+
+### Added — Classifier
+- `QCTClassifier` mapping (surrogation, intervention) → one of
+  `Genuine` / `Regularizer` / `Ignored` / `Dead Weight` / `Inconclusive`.
+- Inconclusive is emitted when a bootstrap CI straddles a threshold.
+- Tunable thresholds via `Thresholds(ss_replaceable, intervention_load_bearing)`.
+
+### Added — Adapters
+- `FunctionalAdapter` — wrap any model with three callables.
+- `PrecomputedAdapter` — wrap cached arrays + a decoder function.
+- `JaxFlaxAdapter` — for Flax models conforming to the thesis surface
+  (`forward_with_quantum`, `extract_quantum_outputs`).
+- `PyTorchAdapter` — skeleton template subclassed by the user.
+- Heavier adapters lazy-import their framework (`hnep[jax]` / `hnep[pytorch]`).
+
+### Added — Cost-utility
+- `compute_qus()` returning a `QuantumUtilityScore` (R² gain per compute
+  multiplier) with a categorical verdict.
+- `pareto_frontier()` filtering dominated points in (accuracy, cost) space.
+- `estimate_hardware_cost()` projecting NISQ cost across IBM / IonQ /
+  Rigetti / IQM (indicative, user-overridable).
+
+### Added — Visualisations
+- `plot_qct_plane()` — the HNEP logo. Four shaded quadrants, threshold
+  lines, confidence rectangles per model.
+- `plot_convergent_validity_radar()` — N-axis radar (one per probe),
+  overlay multiple models.
+- `plot_pareto_with_hardware_cost()` — log-x R² vs compute with optional
+  NISQ price annotations.
+
+### Added — Reports
+- `render_html_report()` — self-contained HTML report with embedded base64
+  figures, verdict card colour-coded by QCT class, probe table with
+  confidence bars, manifest section.
+- `HNEPResult.to_html(path, other_results=...)` for A/B comparisons.
+
+### Added — Tooling
+- `hnep` CLI with `--version` and stubs for `evaluate` / `replay`.
+- Manifest files (`hnep_version`, `timestamp`, `platform`, `thresholds`,
+  probes run, runtime) attached to every result.
+- Sphinx documentation site (Furo theme).
+- GitHub Actions CI: tests across Python 3.9 – 3.12, lint, build, docs.
+- Type-hint marker (`py.typed`).
+- pyproject extras: `[jax]`, `[pytorch]`, `[pennylane]`, `[qiskit]`,
+  `[molecular]`, `[reports]`, `[all]`, `[dev]`.
+
+### Tests
+- 77 tests passing — smoke, probes, classifier, cost-utility, visuals,
+  reports, adapters.
+
+### Known limitations
+- Probe thresholds are picked by inspection (SS < 0.2, Δ ≥ 0.05). A
+  permutation-derived threshold is on the v0.2 roadmap.
+- Visualisation styling is not yet customisable.
+- `hnep evaluate` and `hnep replay` CLI subcommands are stubs (full
+  wire-up lands in v0.2).
+- Molecular utilities (RDKit gallery, atom-level QCI) are scheduled for v0.2.

hnep-0.1.0/CONTRIBUTING_HNEP.md

@@ -0,0 +1,58 @@
+# Contributing to HNEP
+
+Thanks for your interest in making HNEP better.
+
+HNEP is an alpha-stage library: APIs are still moving, and bug reports +
+feature suggestions are especially welcome.
+
+## Quick links
+- 🐛 Bug report: open a GitHub issue with the `bug` label.
+- 💡 Feature suggestion: open a GitHub issue with the `enhancement` label.
+- 📖 Documentation fix: a PR is faster than an issue.
+- 🤔 Methodology question: open a GitHub discussion rather than an issue.
+
+## Setting up a dev environment
+
+```bash
+git clone https://github.com/pratikpriyanshu/hnep.git
+cd hnep
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest tests/ -q
+```
+
+## Style + tests
+
+- Format with **ruff** (`ruff format hnep tests`) — line length 100.
+- Lint with **ruff** (`ruff check hnep tests`).
+- All new functionality needs at least one test in `tests/`.
+- For numerical results, prefer `pytest.approx` with explicit tolerances.
+
+## Writing a new probe
+
+A probe is a subclass of `hnep.Probe` that implements
+`.run(model, dataset, verbose) -> ProbeResult`. The `ProbeResult` dataclass
+is the uniform return format — see `hnep/examples/05_custom_probe.py` for
+a worked example.
+
+## Writing a new adapter
+
+Adapters subclass `hnep.ModelInterface` and implement three methods:
+`predict`, `extract_quantum_output`, `predict_with_quantum_override`.
+Two optional hooks (`get_classical_embedding`, `get_quantum_input`) unlock
+richer probes — implement them when you can.
+
+## Submitting a PR
+
+1. Fork the repo and create a feature branch.
+2. Make the change. Add tests.
+3. Run `pytest tests/`, `ruff check hnep tests`, and `ruff format --check
+   hnep tests`.
+4. Update the `CHANGELOG.md` under `Unreleased`.
+5. Open a PR. Small PRs review faster than large ones.
+
+## Code of conduct
+
+Be excellent to each other. The discussion norms are: ask before
+assuming, criticise ideas not people, and assume good faith.

hnep-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pratik Priyanshu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hnep-0.1.0/MANIFEST.in

@@ -0,0 +1,28 @@
+# Tell setuptools what to include in the sdist beyond default heuristics.
+
+include LICENSE
+include README_HNEP.md
+include CHANGELOG.md
+include CONTRIBUTING_HNEP.md
+include pyproject.toml
+recursive-include hnep *.py *.typed
+recursive-include hnep/examples *.py
+recursive-include tests *.py
+
+# Documentation source (for users who build docs from sdist)
+recursive-include docs_hnep *.rst *.py Makefile
+
+# Exclude development / thesis-only artifacts
+prune src
+prune scripts
+prune notebooks
+prune experiments
+prune data
+prune config
+prune deployment
+prune api
+prune docs
+
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude .DS_Store

hnep-0.1.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: hnep
+Version: 0.1.0
+Summary: Hybrid Network Evaluation Protocol — multi-method evaluation for hybrid quantum-classical models
+Author: Quantum Drug Discovery Team
+Author-email: Pratik Priyanshu <priyanshupriyam123vv@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/pratikpriyanshu/hnep
+Project-URL: Documentation, https://github.com/pratikpriyanshu/hnep
+Project-URL: Source, https://github.com/pratikpriyanshu/hnep
+Project-URL: Issues, https://github.com/pratikpriyanshu/hnep/issues
+Keywords: quantum machine learning,evaluation,QML,hybrid models,benchmarking,surrogation,intervention
+Classifier: Development Status :: 3 - Alpha
+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: author
+Dynamic: license-file
+Dynamic: requires-python
+
+# 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.1.0-orange.svg)](#)
+[![Tests](https://img.shields.io/badge/tests-77%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.1.0
+
+* Surrogation probe — 8-surrogate ladder (linear, KNN, trees, MLPs)
+* Intervention family — zero, random-noise, permutation, constant
+* QCT classifier with bootstrap confidence intervals
+* Cost-utility analysis: Pareto frontier + QUS + NISQ hardware cost projection
+* Killer figures: QCT plane, convergent validity radar, Pareto plot
+* HTML / JSON / CSV reports
+* Manifest files for reproducibility
+* CLI: `hnep evaluate`, `hnep replay`
+* Four adapters (Functional, Precomputed, JAX/Flax, PyTorch skeleton)
+
+## Roadmap
+
+See [`docs/HNEP_LIBRARY_ROADMAP.md`](docs/HNEP_LIBRARY_ROADMAP.md) for the version-by-version plan.
+
+* **v0.2** — molecular chemistry gallery, atom-level QCI, more probes
+* **v0.3** — 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/pratikpriyanshu/hnep},
+}
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).