heterosplit 0.1.0__tar.gz

heterosplit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,90 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: lint & type-check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Install Python 3.12
+        run: uv python install 3.12
+
+      - name: Sync (core + dev toolchain)
+        run: uv sync --python 3.12
+
+      - name: Lint (ruff)
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+
+      - name: Type check (mypy)
+        run: uv run mypy
+
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Install Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Sync (core + dev toolchain)
+        run: uv sync --python ${{ matrix.python-version }}
+
+      - name: Test
+        run: uv run pytest
+
+  coverage:
+    name: coverage (with pyg extra)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Install Python 3.12
+        run: uv python install 3.12
+
+      # Install the [pyg] extra so the PyG adapter + training example run and are
+      # measured — the coverage gate then reflects the whole library, not just the core.
+      - name: Sync (core + dev + pyg)
+        run: uv sync --python 3.12 --extra pyg
+
+      - name: Test with coverage (fail under 90%)
+        run: >
+          uv run --extra pyg pytest
+          --cov --cov-report=term-missing --cov-report=xml --cov-fail-under=90
+
+      - name: Upload coverage
+        uses: actions/upload-artifact@v5
+        with:
+          name: coverage-xml
+          path: coverage.xml

heterosplit-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,63 @@
+name: Release
+
+# Publishes to PyPI when a version tag is pushed (e.g. `git tag v0.1.0 && git push --tags`).
+#
+# One-time setup on PyPI (trusted publishing, no API token needed): create the project's
+# "trusted publisher" with owner=ZubairQazi, repo=heterosplit, workflow=release.yml,
+# environment=pypi. See https://docs.pypi.org/trusted-publishers/. Test first against
+# TestPyPI via the manual "Run workflow" button (target: testpypi).
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Publish target"
+        default: testpypi
+        type: choice
+        options: [testpypi, pypi]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Check that the tag matches the package version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          version="v$(uv run python -c 'import heterosplit; print(heterosplit.__version__)')"
+          if [ "$version" != "${GITHUB_REF_NAME}" ]; then
+            echo "tag ${GITHUB_REF_NAME} != package version ${version}" >&2
+            exit 1
+          fi
+      - uses: actions/upload-artifact@v5
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: ${{ github.event.inputs.target || 'pypi' }}
+    permissions:
+      id-token: write # OIDC trusted publishing
+    steps:
+      - uses: actions/download-artifact@v5
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to TestPyPI
+        if: github.event.inputs.target == 'testpypi'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+      - name: Publish to PyPI
+        if: github.event.inputs.target != 'testpypi'
+        uses: pypa/gh-action-pypi-publish@release/v1

heterosplit-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# uv
+# (uv.lock IS committed; the cache dir is not)
+.uv/
+
+# Test / coverage / typing caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Benchmark / example artifacts
+*.manifest.json
+benchmarks/results/
+examples/output/
+
+# OS / editor cruft
+.DS_Store
+*.swp
+.idea/
+.vscode/

heterosplit-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

heterosplit-0.1.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-12
+
+First public release: a feature-complete v1 of the correctness core, auditor, and
+integrations.
+
+### Added
+
+- **Split regimes (8):** random/transductive, pair, source, destination, either, both,
+  context, and joint cold-start, over a prediction-record model with per-entity-type
+  shared codebooks.
+- **Leakage audit suite:** regime-aware contract checks — entity/pair/context overlap
+  across all splits (incl. val-vs-test), reversed-pair awareness, message-passing
+  reconstruction leakage, duplicate observations, and optional negative-sample and
+  feature-provenance auditors; `raise_for_leakage()` fails on any violation.
+- **Deterministic manifests:** collision-resistant input fingerprint, normalized spec,
+  per-split counts, and index hashes; `digest()` reproducibility key with measurements
+  kept separate. Reloadable without re-running.
+- **Constrained assignment:** seeded longest-processing-time greedy plus a
+  size-preserving local-search refinement (capped for scale).
+- **Message passing:** leakage-safe training-graph reconstruction (held-out edges and,
+  for self-relations, their reverses removed).
+- **Adapters:** PyTorch Geometric `HeteroData` (optional `[pyg]` extra) and a
+  dependency-free tabular adapter.
+- **Datasets:** real DrugComb drug--drug--cell-line loader (streaming CSV + Zenodo
+  downloader).
+- **Reporting & CLI:** JSON/Markdown distribution + audit report; `heterosplit demo` /
+  `heterosplit split`.
+- **Examples & benchmarks:** synthetic generator, corrupted-leakage demo, benchmark
+  harness with a group-shuffle baseline, and an end-to-end GraphSAGE link-prediction
+  example showing the regime changes measured performance.
+- **Docs:** architecture and benchmark methodology; property-based and adversarial-review
+  test coverage (~94%).
+
+[Unreleased]: https://github.com/ZubairQazi/heterosplit/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/ZubairQazi/heterosplit/releases/tag/v0.1.0

heterosplit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zubair Qazi
+
+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.

heterosplit-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.5
+Name: heterosplit
+Version: 0.1.0
+Summary: Leakage-safe entity-disjoint splits and audits for heterogeneous link-prediction datasets.
+Project-URL: Homepage, https://github.com/ZubairQazi/heterosplit
+Project-URL: Repository, https://github.com/ZubairQazi/heterosplit
+Project-URL: Issues, https://github.com/ZubairQazi/heterosplit/issues
+Author: Zubair Qazi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cold-start,data-splitting,gnn,graph,leakage,link-prediction,pytorch-geometric
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Provides-Extra: pyg
+Requires-Dist: torch-geometric>=2.5; extra == 'pyg'
+Requires-Dist: torch>=2.1; extra == 'pyg'
+Description-Content-Type: text/markdown
+
+# HeteroSplit
+
+**Leakage-safe entity-disjoint splits and audits for heterogeneous link-prediction datasets.**
+
+[![CI](https://github.com/ZubairQazi/heterosplit/actions/workflows/ci.yml/badge.svg)](https://github.com/ZubairQazi/heterosplit/actions/workflows/ci.yml)
+![coverage](https://img.shields.io/badge/coverage-94%25-brightgreen)
+![python](https://img.shields.io/badge/python-3.10--3.13-blue)
+[![license: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+HeteroSplit constructs, validates, and *reports* cold-start / inductive splits for
+heterogeneous link-prediction tasks (drug–drug–cell-line synergy, drug–target
+interaction, recommendation, knowledge graphs). It is designed to **complement**
+PyTorch Geometric — it focuses narrowly on split *semantics* and leakage *auditing*,
+and does not replace PyG's loaders, samplers, or training stack.
+
+> **Status:** early release (`0.1.x`). APIs may change. This is positioned as a
+> reusable implementation of entity-disjoint split policies and leakage audits for
+> PyG `HeteroData` link-prediction tasks — not (yet) a research novelty claim.
+
+## Why
+
+Graph libraries make *random* node/edge splitting easy, but cold-start experiments
+often rely on one-off scripts with ambiguous semantics. A nominally "cold" test set
+can still leak information through:
+
+- the same entity appearing in training under another edge or relation;
+- reverse edges left in the message-passing graph;
+- an unordered pair reversed across splits;
+- context entities (e.g. cell lines) crossing a supposedly disjoint boundary;
+- features / precomputed embeddings fit using held-out entities;
+- negative sampling that pulls entities or pairs from the wrong regime.
+
+HeteroSplit makes the split *contract* explicit, enforces it, and produces evidence
+(a serializable **manifest** + **audit report**) that the contract holds.
+
+**Why it matters (real DrugComb):** a small GraphSAGE link predictor scores **AUC 0.84**
+under a random split but **0.27** on genuinely unseen drugs (either-cold-start) — random
+splitting massively overestimates cold-start performance. See
+[benchmarks](docs/benchmarks.md#real-data-drugcomb).
+
+## Install
+
+The correctness core is pure Python + NumPy:
+
+```bash
+pip install heterosplit
+```
+
+PyTorch Geometric integration is an optional extra:
+
+```bash
+pip install "heterosplit[pyg]"
+```
+
+### From source (development)
+
+This project uses [`uv`](https://docs.astral.sh/uv/):
+
+```bash
+git clone https://github.com/ZubairQazi/heterosplit
+cd heterosplit
+uv sync                 # creates .venv and installs the dev toolchain
+uv run pytest           # run the test suite
+uv run --extra pyg pytest   # include the PyG adapter tests
+```
+
+## Quickstart
+
+```python
+from heterosplit import make_synthetic_dataset, split_records
+
+# A DrugComb-shaped dataset: (drug, drug, cell-line) synergy observations.
+# Swap in your own PredictionRecords / HeteroData for real data.
+data = make_synthetic_dataset(
+    n_records=5000,
+    n_source_entities=120,
+    n_context_entities=30,
+    n_labels=2,
+    source_type="drug",
+    context_type="cell_line",
+    relation="synergy",
+    seed=42,
+)
+
+# Joint cold-start: a test triple must involve an unseen drug AND an unseen cell line.
+spec = data.spec(
+    "joint_cold_start",
+    holdout={"drug": "either", "cell_line": "all"},
+    ratios=(0.8, 0.1, 0.1),
+    stratify_by="label",
+    seed=42,
+)
+
+result = split_records(data.records, spec)
+result.audit.raise_for_leakage()  # fails loudly on any leakage
+result.manifest.save("split-manifest.json")  # deterministic, reloadable
+
+train_edges = result.message_passing_edge_index()  # leakage-safe training graph
+```
+
+Runnable versions live in [`examples/`](examples/) (`quickstart.py`,
+`recommendation.py`, `drugcomb.py`, `corrupted_leakage.py`), or try the CLI:
+
+```bash
+uv run heterosplit demo --regime joint_cold_start
+uv run heterosplit split --input data.csv --spec spec.json --out-dir out/
+```
+
+### Real data: DrugComb
+
+The [DrugComb](https://drugcomb.org) drug–drug–cell-line synergy corpus is wired up
+directly (CC-BY-4.0):
+
+```python
+from heterosplit.datasets.drugcomb import download_drugcomb_summary, load_drugcomb_csv
+
+download_drugcomb_summary("drugcomb.csv")  # ~1.4 GB, once
+records = load_drugcomb_csv("drugcomb.csv", max_rows=200_000)  # streams; filters mono-therapy rows
+```
+
+`records_from_drugcomb(frame, ...)` maps an in-memory DrugComb frame (dict or DataFrame)
+if you already have one.
+
+## Documentation
+
+- [Architecture / design](docs/architecture.md)
+- [Benchmarks & methodology](docs/benchmarks.md)
+
+## Split taxonomy (v1 target)
+
+| Regime | Test-set contract |
+|---|---|
+| Random / transductive | Test edges are unseen; entities may have appeared in training. |
+| Pair cold-start | The `(s, d)` pair is unseen, but each entity may appear separately. |
+| Source cold-start | Test source entities never appear as training sources. |
+| Destination cold-start | Test destination entities never appear as training destinations. |
+| Either-entity cold-start | At least one endpoint of each test edge is unseen. |
+| Both-entity cold-start | Both endpoints of every test edge are unseen. |
+| Context cold-start | Test context entities never occur in training. |
+| Joint cold-start | A configured combination of endpoint and context disjointness. |
+
+## Leakage audit & manifests
+
+Every split ships with an **audit** and a reproducible **manifest**:
+
+- `result.audit` turns the regime's contract into machine-checkable findings — entity /
+  pair / context overlap (across *all* splits, including val-vs-test), reversed unordered
+  pairs, message-passing leakage, duplicate observations, and optional negative-sample /
+  feature-provenance checks. Each finding has a count, severity, and concrete offending
+  ids; `raise_for_leakage()` fails on any violation.
+- `result.manifest` records library/schema versions, a collision-resistant input
+  fingerprint, the normalized spec, per-split counts, and hashes of the split indices.
+  `manifest.digest()` is a stable reproducibility key; runtime/memory measurements are
+  kept separate so a fixed input + spec + seed always produce the same digest.
+
+## License
+
+[MIT](LICENSE)

heterosplit-0.1.0/README.md

@@ -0,0 +1,158 @@
+# HeteroSplit
+
+**Leakage-safe entity-disjoint splits and audits for heterogeneous link-prediction datasets.**
+
+[![CI](https://github.com/ZubairQazi/heterosplit/actions/workflows/ci.yml/badge.svg)](https://github.com/ZubairQazi/heterosplit/actions/workflows/ci.yml)
+![coverage](https://img.shields.io/badge/coverage-94%25-brightgreen)
+![python](https://img.shields.io/badge/python-3.10--3.13-blue)
+[![license: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+HeteroSplit constructs, validates, and *reports* cold-start / inductive splits for
+heterogeneous link-prediction tasks (drug–drug–cell-line synergy, drug–target
+interaction, recommendation, knowledge graphs). It is designed to **complement**
+PyTorch Geometric — it focuses narrowly on split *semantics* and leakage *auditing*,
+and does not replace PyG's loaders, samplers, or training stack.
+
+> **Status:** early release (`0.1.x`). APIs may change. This is positioned as a
+> reusable implementation of entity-disjoint split policies and leakage audits for
+> PyG `HeteroData` link-prediction tasks — not (yet) a research novelty claim.
+
+## Why
+
+Graph libraries make *random* node/edge splitting easy, but cold-start experiments
+often rely on one-off scripts with ambiguous semantics. A nominally "cold" test set
+can still leak information through:
+
+- the same entity appearing in training under another edge or relation;
+- reverse edges left in the message-passing graph;
+- an unordered pair reversed across splits;
+- context entities (e.g. cell lines) crossing a supposedly disjoint boundary;
+- features / precomputed embeddings fit using held-out entities;
+- negative sampling that pulls entities or pairs from the wrong regime.
+
+HeteroSplit makes the split *contract* explicit, enforces it, and produces evidence
+(a serializable **manifest** + **audit report**) that the contract holds.
+
+**Why it matters (real DrugComb):** a small GraphSAGE link predictor scores **AUC 0.84**
+under a random split but **0.27** on genuinely unseen drugs (either-cold-start) — random
+splitting massively overestimates cold-start performance. See
+[benchmarks](docs/benchmarks.md#real-data-drugcomb).
+
+## Install
+
+The correctness core is pure Python + NumPy:
+
+```bash
+pip install heterosplit
+```
+
+PyTorch Geometric integration is an optional extra:
+
+```bash
+pip install "heterosplit[pyg]"
+```
+
+### From source (development)
+
+This project uses [`uv`](https://docs.astral.sh/uv/):
+
+```bash
+git clone https://github.com/ZubairQazi/heterosplit
+cd heterosplit
+uv sync                 # creates .venv and installs the dev toolchain
+uv run pytest           # run the test suite
+uv run --extra pyg pytest   # include the PyG adapter tests
+```
+
+## Quickstart
+
+```python
+from heterosplit import make_synthetic_dataset, split_records
+
+# A DrugComb-shaped dataset: (drug, drug, cell-line) synergy observations.
+# Swap in your own PredictionRecords / HeteroData for real data.
+data = make_synthetic_dataset(
+    n_records=5000,
+    n_source_entities=120,
+    n_context_entities=30,
+    n_labels=2,
+    source_type="drug",
+    context_type="cell_line",
+    relation="synergy",
+    seed=42,
+)
+
+# Joint cold-start: a test triple must involve an unseen drug AND an unseen cell line.
+spec = data.spec(
+    "joint_cold_start",
+    holdout={"drug": "either", "cell_line": "all"},
+    ratios=(0.8, 0.1, 0.1),
+    stratify_by="label",
+    seed=42,
+)
+
+result = split_records(data.records, spec)
+result.audit.raise_for_leakage()  # fails loudly on any leakage
+result.manifest.save("split-manifest.json")  # deterministic, reloadable
+
+train_edges = result.message_passing_edge_index()  # leakage-safe training graph
+```
+
+Runnable versions live in [`examples/`](examples/) (`quickstart.py`,
+`recommendation.py`, `drugcomb.py`, `corrupted_leakage.py`), or try the CLI:
+
+```bash
+uv run heterosplit demo --regime joint_cold_start
+uv run heterosplit split --input data.csv --spec spec.json --out-dir out/
+```
+
+### Real data: DrugComb
+
+The [DrugComb](https://drugcomb.org) drug–drug–cell-line synergy corpus is wired up
+directly (CC-BY-4.0):
+
+```python
+from heterosplit.datasets.drugcomb import download_drugcomb_summary, load_drugcomb_csv
+
+download_drugcomb_summary("drugcomb.csv")  # ~1.4 GB, once
+records = load_drugcomb_csv("drugcomb.csv", max_rows=200_000)  # streams; filters mono-therapy rows
+```
+
+`records_from_drugcomb(frame, ...)` maps an in-memory DrugComb frame (dict or DataFrame)
+if you already have one.
+
+## Documentation
+
+- [Architecture / design](docs/architecture.md)
+- [Benchmarks & methodology](docs/benchmarks.md)
+
+## Split taxonomy (v1 target)
+
+| Regime | Test-set contract |
+|---|---|
+| Random / transductive | Test edges are unseen; entities may have appeared in training. |
+| Pair cold-start | The `(s, d)` pair is unseen, but each entity may appear separately. |
+| Source cold-start | Test source entities never appear as training sources. |
+| Destination cold-start | Test destination entities never appear as training destinations. |
+| Either-entity cold-start | At least one endpoint of each test edge is unseen. |
+| Both-entity cold-start | Both endpoints of every test edge are unseen. |
+| Context cold-start | Test context entities never occur in training. |
+| Joint cold-start | A configured combination of endpoint and context disjointness. |
+
+## Leakage audit & manifests
+
+Every split ships with an **audit** and a reproducible **manifest**:
+
+- `result.audit` turns the regime's contract into machine-checkable findings — entity /
+  pair / context overlap (across *all* splits, including val-vs-test), reversed unordered
+  pairs, message-passing leakage, duplicate observations, and optional negative-sample /
+  feature-provenance checks. Each finding has a count, severity, and concrete offending
+  ids; `raise_for_leakage()` fails on any violation.
+- `result.manifest` records library/schema versions, a collision-resistant input
+  fingerprint, the normalized spec, per-split counts, and hashes of the split indices.
+  `manifest.digest()` is a stable reproducibility key; runtime/memory measurements are
+  kept separate so a fixed input + spec + seed always produce the same digest.
+
+## License
+
+[MIT](LICENSE)

heterosplit-0.1.0/RELEASING.md

@@ -0,0 +1,39 @@
+# Releasing
+
+HeteroSplit publishes to PyPI via GitHub Actions using **trusted publishing** (OIDC — no
+API tokens stored in the repo).
+
+## One-time PyPI setup
+
+1. Create the project on PyPI (and, for a dry run, TestPyPI).
+2. Add a **trusted publisher** for it (PyPI → project → Publishing):
+   - Owner: `ZubairQazi`
+   - Repository: `heterosplit`
+   - Workflow: `release.yml`
+   - Environment: `pypi` (and `testpypi` for the dry run)
+3. In the GitHub repo, create matching environments named `pypi` and `testpypi`
+   (Settings → Environments).
+
+See <https://docs.pypi.org/trusted-publishers/>.
+
+## Cutting a release
+
+1. Bump `__version__` in `src/heterosplit/__init__.py` (single source of truth; hatchling
+   reads it).
+2. Move the `Unreleased` notes in `CHANGELOG.md` under a new version heading with today's
+   date.
+3. Commit, then tag and push:
+
+   ```bash
+   git commit -am "release: v0.1.1"
+   git tag v0.1.1
+   git push && git push --tags
+   ```
+
+   The `release.yml` workflow builds the sdist + wheel, verifies the tag matches
+   `__version__`, and publishes to PyPI.
+
+## Dry run (TestPyPI)
+
+Use the workflow's **Run workflow** button (Actions → Release) with target `testpypi`
+before a real release.