matching-pmh 0.6.0__tar.gz

matching_pmh-0.6.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.venv/
+.venv-pypi-test/
+.venv-pypi-verify/
+venv/
+artifacts/
+tmp_trainer/
+tmp_pmh_trainer/
+*.pt
+.DS_Store

matching_pmh-0.6.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## 0.6.0
+
+- **`pmh-train` CLI**: `list-methods`, `estimate --config job.json`, `preflight`, `run --config job.json`.
+- **`pmh.catalog`**: D1–D7 input requirements and job validation.
+- **Example 11**: Qwen/T7A JSONL (`style_pairs` + `preference_pairs`), optional LoRA + DPO+PMH demo.
+- **Bundled samples**: `examples/data/*.jsonl`, `examples/configs/*.json`.
+- **HF**: `load_preference_pairs_jsonl` for DPO schema.
+- **Publishing**: TestPyPI workflow (`publish-testpypi.yml`), updated `PUBLISHING.md`.
+
+## 0.5.0
+
+- HF `PMHTrainer`, CORAL baseline, CI matrix, Office-31 example.
+
+## 0.4.0
+
+- Hugging Face D7, Lightning callback, Office-31 loader.
+
+## 0.3.0
+
+- Torch/sklearn/vision integrations, MkDocs.
+
+## 0.2.0
+
+- Artifacts, `PMHLoss`, configs.
+
+## 0.1.0
+
+- Core estimators D1–D7 and penalties.

matching_pmh-0.6.0/CITATION.cff

@@ -0,0 +1,25 @@
+cff-version: 1.2.0
+title: "matching-pmh: reference library for the matching principle"
+message: "If you use this software, please cite the matching-principle paper."
+type: software
+authors:
+  - family-names: Rajput
+    given-names: Vishal
+repository-code: "https://github.com/matching-pmh/matching-pmh"
+url: "https://github.com/matching-pmh/matching-pmh"
+license: MIT
+version: 0.6.0
+keywords:
+  - robustness
+  - domain-adaptation
+  - representation-learning
+  - jacobian-regularization
+  - sigma-task
+preferred-citation:
+  type: article
+  title: "The Matching Principle: A Geometric Theory of Loss Functions for Nuisance-Robust Representation Learning"
+  authors:
+    - family-names: Rajput
+      given-names: Vishal
+  year: 2026
+  notes: "JMLR submission; update journal fields when accepted."

matching_pmh-0.6.0/GITHUB_SETUP.md

@@ -0,0 +1,61 @@
+# Publish `matching-pmh` on GitHub
+
+The library lives only in this folder (`Desktop/matching-pmh`), not inside the paper repo.
+
+## 1. Create the remote repository
+
+On GitHub: **New repository** → name `matching-pmh` → public → **no** README (this tree has one).
+
+Or install [GitHub CLI](https://cli.github.com/) and run:
+
+```powershell
+cd C:\Users\Eigenaar\Desktop\matching-pmh
+gh auth login
+gh repo create matching-pmh --public --source=. --remote=origin
+```
+
+## 2. Publish on PyPI (full package)
+
+See **`PUBLISHING.md`** for the complete guide. Summary:
+
+1. Build: `python -m build` && `twine check dist/*`
+2. Upload: `twine upload dist/*` (or tag `v0.6.0` + trusted publishing on GitHub)
+3. Users install: `pip install matching-pmh`
+
+The name `matching-pmh` is **not yet on PyPI** until you upload once.
+
+## 3. First commit and push
+
+```powershell
+cd C:\Users\Eigenaar\Desktop\matching-pmh
+git init
+git add .
+git commit -m "Initial release: estimate_sigma_task (D1-D7) and PMH penalties (v0.1.0)"
+git branch -M main
+git remote add origin https://github.com/YOUR_USERNAME/matching-pmh.git
+git push -u origin main
+```
+
+Replace `YOUR_USERNAME` with your GitHub account. Update `CITATION.cff` and `pyproject.toml` `[project.urls]` if the URL differs.
+
+## 4. Paper cross-link
+
+After the repo exists, set the URL in the manuscript macro (once):
+
+`submission_grand_unification/macros.tex` → `\MatchingPmhRepoUrl{https://github.com/YOUR_USERNAME/matching-pmh}`
+
+Then rebuild the PDF (`pdflatex` ×2 in `submission_grand_unification/`).
+
+## 4. Remove duplicate from paper tree
+
+Delete the old copy under `Paper2/pmh/` (only a stub README should remain there).
+
+## 5. Optional: PyPI
+
+When ready for `pip install matching-pmh`:
+
+```powershell
+pip install build twine
+python -m build
+twine upload dist/*
+```

matching_pmh-0.6.0/LICENSE

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

matching_pmh-0.6.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: matching-pmh
+Version: 0.6.0
+Summary: Reference library for the matching principle: estimate Sigma_task (D1-D7) and matched PMH penalties
+Project-URL: Homepage, https://github.com/matching-pmh/matching-pmh
+Project-URL: Documentation, https://github.com/matching-pmh/matching-pmh#readme
+Project-URL: Repository, https://github.com/matching-pmh/matching-pmh
+Project-URL: Issues, https://github.com/matching-pmh/matching-pmh/issues
+Project-URL: Changelog, https://github.com/matching-pmh/matching-pmh/blob/main/CHANGELOG.md
+Author: Vishal Rajput
+License-Expression: MIT
+License-File: LICENSE
+Keywords: domain-adaptation,jacobian,pmh,representation-learning,robustness
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: torch>=2.1
+Provides-Extra: all
+Requires-Dist: accelerate>=0.25; extra == 'all'
+Requires-Dist: datasets>=2.14; extra == 'all'
+Requires-Dist: lightning>=2.1; extra == 'all'
+Requires-Dist: mkdocs-material>=9.0; extra == 'all'
+Requires-Dist: mkdocs>=1.5; extra == 'all'
+Requires-Dist: peft>=0.7; extra == 'all'
+Requires-Dist: pytest>=8.0; extra == 'all'
+Requires-Dist: ruff>=0.4; extra == 'all'
+Requires-Dist: scikit-learn>=1.3; extra == 'all'
+Requires-Dist: torchvision>=0.16; extra == 'all'
+Requires-Dist: transformers>=4.36; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Provides-Extra: hf
+Requires-Dist: accelerate>=0.25; extra == 'hf'
+Requires-Dist: transformers>=4.36; extra == 'hf'
+Provides-Extra: hf-lora
+Requires-Dist: accelerate>=0.25; extra == 'hf-lora'
+Requires-Dist: datasets>=2.14; extra == 'hf-lora'
+Requires-Dist: peft>=0.7; extra == 'hf-lora'
+Requires-Dist: transformers>=4.36; extra == 'hf-lora'
+Provides-Extra: lightning
+Requires-Dist: lightning>=2.1; extra == 'lightning'
+Provides-Extra: sklearn
+Requires-Dist: scikit-learn>=1.3; extra == 'sklearn'
+Provides-Extra: vision
+Requires-Dist: torchvision>=0.16; extra == 'vision'
+Description-Content-Type: text/markdown
+
+# matching-pmh
+
+**Independent library** for the *matching principle*: estimate $\Sigma_{\mathrm{task}}$ (Lemmas D1–D7), run matched PMH penalties, save/load artifacts, and wire into training loops.
+
+Paper: *The Matching Principle* (separate repository). **v0.2** adds typed configs, artifacts, pre-flight eigengap, `PMHLoss`, and `collect_features`.
+
+## Install
+
+```bash
+cd matching-pmh
+pip install -e ".[dev]"
+pytest
+```
+
+## Quick start (v0.2)
+
+```python
+import torch
+from pmh import (
+    SigmaTaskConfig,
+    PMHConfig,
+    PMHLoss,
+    estimate_from_config,
+    collect_features,
+)
+
+# 1) Estimate + diagnostics
+cfg = SigmaTaskConfig.for_domain(rank=64)
+artifact = estimate_from_config(cfg, source_feats, target_feats)
+print(artifact.preflight, artifact.eigengap)  # pass | marginal | fail
+
+# 2) Save for another job / machine
+artifact.save("checkpoints/style_sigma")
+
+# 3) Train
+pmh = PMHLoss(artifact, PMHConfig(weight=0.3, cap_ratio=0.3, warmup_epochs=2))
+h = backbone(x)
+task_loss = ...
+total, pmh_term = pmh.capped_total(task_loss, h)
+```
+
+### Legacy one-liner (still supported)
+
+```python
+from pmh import estimate_sigma_task, pmh_penalty_on_rep
+
+sigma = estimate_sigma_task(src, tgt, method="D4", rank=64)
+pen = pmh_penalty_on_rep(h, sigma)
+```
+
+### Load a saved estimate
+
+```python
+from pmh import SigmaTaskEstimate, PMHLoss
+
+artifact = SigmaTaskEstimate.load("checkpoints/style_sigma.pt")
+pmh = PMHLoss(artifact)
+```
+
+## Examples
+
+| Script | What it shows |
+|--------|----------------|
+| `examples/01_domain_shift_d4.py` | `collect_features` + D4 + `PMHLoss` training |
+| `examples/02_save_load_artifact.py` | `.pt` + `.json` artifact I/O |
+| `examples/03_compositional_d5.py` | D5 coordinate-block $\Sigma$ |
+| `examples/04_falsification_controls.py` | matched / wrong-W / isotropic modes |
+| `examples/05_yaml_config.py` | JSON job dict → configs |
+| `examples/minimal_loop.py` | Short end-to-end loop |
+| `examples/06_office31_sklearn.py` | D1 + `MatchedSubspaceProjector` + logistic |
+| `examples/07_vision_multilayer.py` | `MultiLayerPMHLoss` + per-layer Gram noise |
+
+## API map
+
+| Goal | API |
+|------|-----|
+| Pick estimator | `SigmaTaskConfig.for_domain()`, `.for_isotropic()`, … |
+| Estimate | `estimate_from_config(cfg, ...)` → `SigmaTaskEstimate` |
+| Pre-flight | `artifact.preflight`, `preflight_eigengap(cov, rank)` |
+| Train | `PMHLoss(artifact, PMHConfig(...))` |
+| Controls | `PMHLoss(..., mode="wrong_w")`, `signal_W_projector` |
+| Data hook | `collect_features(encoder, loader)` |
+
+## Estimators (`method=`)
+
+| Method | Lemma | Config helper |
+|--------|-------|----------------|
+| D1 | Subspace SVD | `for_subspace(rank=)` |
+| D2 | Isotropic | `for_isotropic(dim, noise_level)` |
+| D3 | Aug modes | `for_augmentation()` |
+| D4 | Domain Gram | `for_domain(rank=)` |
+| D5 | Compositional | `for_compositional(indices)` |
+| D6 | Temporal | `for_temporal()` |
+| D7 | Style / alignment | `for_alignment(rank=)` |
+
+## Status
+
+**0.5.0** — `PMHTrainer` (HF), CORAL baseline, GitHub Actions CI + PyPI publish guide.
+
+| Extra | Install | Example |
+|-------|---------|---------|
+| HF Trainer | `pip install "matching-pmh[hf]"` | `examples/10_hf_trainer.py` |
+| CORAL baseline | `pmh.baselines.coral` | `examples/06_office31_sklearn.py` |
+| CI / PyPI | see `PUBLISHING.md` | tag `v0.5.0` |
+
+**0.4.0** — Hugging Face D7 (`estimate_style_sigma`), Lightning (`add_pmh_to_loss`), Office-31 features (`--office31-root`).
+
+| Extra | Install | Example |
+|-------|---------|---------|
+| HF | `pip install "matching-pmh[hf]"` | `examples/08_hf_style_d7.py` |
+| Lightning | `pip install "matching-pmh[lightning]"` | `examples/09_lightning_module.py` |
+| Vision / Office-31 | `pip install "matching-pmh[vision]"` | `examples/06_office31_sklearn.py --office31-root ...` |

matching_pmh-0.6.0/PUBLISHING.md

@@ -0,0 +1,143 @@
+# Publishing `matching-pmh` on PyPI (production)
+
+**PyPI name:** `matching-pmh` (available — not taken yet)  
+**Import:** `import pmh`  
+**CLI:** `pmh-train`
+
+After a successful release, anyone can install with:
+
+```bash
+pip install matching-pmh
+pip install "matching-pmh[hf]"      # Hugging Face D7 / Trainer
+pip install "matching-pmh[hf-lora]" # + PEFT for example 11
+```
+
+---
+
+## One-time setup (≈15 minutes)
+
+### 1. Accounts
+
+1. [pypi.org](https://pypi.org/account/register/) — production  
+2. [test.pypi.org](https://test.pypi.org/account/register/) — optional dry run  
+3. [github.com](https://github.com) — source + trusted publishing  
+
+### 2. Reserve the project name on PyPI
+
+On [pypi.org/manage/projects/](https://pypi.org/manage/projects/), the **first successful upload** of `matching-pmh` claims the name. Upload once manually or via CI (below).
+
+### 3. Trusted publishing (recommended — no long-lived API token in GitHub)
+
+**On PyPI** → Account settings → **Publishing** → Add pending publisher:
+
+| Field | Value |
+|--------|--------|
+| PyPI project name | `matching-pmh` |
+| Owner | your GitHub user or org |
+| Repository | `matching-pmh` |
+| Workflow name | `ci.yml` |
+| Environment name | *(leave empty unless you use one)* |
+
+Repeat for **TestPyPI** if you use `publish-testpypi.yml` (workflow name `publish-testpypi.yml`).
+
+### 4. GitHub repository
+
+```powershell
+cd C:\Users\Eigenaar\Desktop\matching-pmh
+gh auth login
+gh repo create matching-pmh --public --source=. --remote=origin
+git add .
+git commit -m "Release matching-pmh 0.6.0: D1-D7 estimators, PMH, pmh-train CLI"
+git branch -M main
+git push -u origin main
+```
+
+Update `pyproject.toml` and `CITATION.cff` `[project.urls]` / `repository-code` if your URL is not `github.com/matching-pmh/matching-pmh`.
+
+---
+
+## Path A — Publish from your machine (first time, fastest)
+
+```powershell
+cd C:\Users\Eigenaar\Desktop\matching-pmh
+pip install build twine
+python -m build
+twine check dist/*
+
+# Optional dry run on TestPyPI first:
+# twine upload --repository testpypi dist/*
+# pip install -i https://test.pypi.org/simple/ matching-pmh==0.6.0
+
+# Production PyPI (you will be prompted for API token; use scope "Entire account" or project-scoped):
+twine upload dist/*
+```
+
+Create an API token on your [account settings](https://pypi.org/manage/account/) page → **API tokens** → **Add API token** (scope: entire account for first upload, or project **matching-pmh** after it exists).
+
+Verify:
+
+```powershell
+pip install matching-pmh==0.6.0
+pmh-train list-methods
+python -c "import pmh; print(pmh.__version__)"
+```
+
+---
+
+## Path B — Publish via GitHub tag (after trusted publishing is configured)
+
+```powershell
+git tag v0.6.0
+git push origin v0.6.0
+```
+
+Workflow `.github/workflows/ci.yml` runs tests, builds, and publishes to **pypi.org** on tags `v*`.
+
+---
+
+## Version bump checklist (every release)
+
+1. `pyproject.toml` → `version`
+2. `src/pmh/__init__.py` → `__version__`
+3. `CITATION.cff` → `version`
+4. `CHANGELOG.md` → new section
+5. `git tag vX.Y.Z && git push origin vX.Y.Z`
+
+---
+
+## Fallback: API token in GitHub Actions
+
+If trusted publishing is not set up, add repo secret `PYPI_API_TOKEN` and the publish step still works with `pypa/gh-action-pypi-publish`.
+
+---
+
+## Paper cross-link
+
+Set in `submission_grand_unification/macros.tex`:
+
+```latex
+\MatchingPmhRepoUrl{https://github.com/YOUR_USER/matching-pmh}
+```
+
+Add to reproducibility text: `pip install matching-pmh` (PyPI).
+
+---
+
+## Local preflight (before any upload)
+
+```powershell
+pip install build twine
+python -m build
+twine check dist/*
+pip install dist\matching_pmh-0.6.0-py3-none-any.whl
+pmh-train list-methods
+pytest -q
+```
+
+---
+
+## Notes
+
+- **Torch** is a core dependency; wheels are large — that is normal for ML libraries on PyPI.
+- The name `pmh` on PyPI may be taken by unrelated projects; this package is **`matching-pmh`** only.
+- Do not commit `dist/`, `artifacts/`, or API tokens.

matching_pmh-0.6.0/README.md

@@ -0,0 +1,112 @@
+# matching-pmh
+
+**Independent library** for the *matching principle*: estimate $\Sigma_{\mathrm{task}}$ (Lemmas D1–D7), run matched PMH penalties, save/load artifacts, and wire into training loops.
+
+Paper: *The Matching Principle* (separate repository). **v0.2** adds typed configs, artifacts, pre-flight eigengap, `PMHLoss`, and `collect_features`.
+
+## Install
+
+```bash
+cd matching-pmh
+pip install -e ".[dev]"
+pytest
+```
+
+## Quick start (v0.2)
+
+```python
+import torch
+from pmh import (
+    SigmaTaskConfig,
+    PMHConfig,
+    PMHLoss,
+    estimate_from_config,
+    collect_features,
+)
+
+# 1) Estimate + diagnostics
+cfg = SigmaTaskConfig.for_domain(rank=64)
+artifact = estimate_from_config(cfg, source_feats, target_feats)
+print(artifact.preflight, artifact.eigengap)  # pass | marginal | fail
+
+# 2) Save for another job / machine
+artifact.save("checkpoints/style_sigma")
+
+# 3) Train
+pmh = PMHLoss(artifact, PMHConfig(weight=0.3, cap_ratio=0.3, warmup_epochs=2))
+h = backbone(x)
+task_loss = ...
+total, pmh_term = pmh.capped_total(task_loss, h)
+```
+
+### Legacy one-liner (still supported)
+
+```python
+from pmh import estimate_sigma_task, pmh_penalty_on_rep
+
+sigma = estimate_sigma_task(src, tgt, method="D4", rank=64)
+pen = pmh_penalty_on_rep(h, sigma)
+```
+
+### Load a saved estimate
+
+```python
+from pmh import SigmaTaskEstimate, PMHLoss
+
+artifact = SigmaTaskEstimate.load("checkpoints/style_sigma.pt")
+pmh = PMHLoss(artifact)
+```
+
+## Examples
+
+| Script | What it shows |
+|--------|----------------|
+| `examples/01_domain_shift_d4.py` | `collect_features` + D4 + `PMHLoss` training |
+| `examples/02_save_load_artifact.py` | `.pt` + `.json` artifact I/O |
+| `examples/03_compositional_d5.py` | D5 coordinate-block $\Sigma$ |
+| `examples/04_falsification_controls.py` | matched / wrong-W / isotropic modes |
+| `examples/05_yaml_config.py` | JSON job dict → configs |
+| `examples/minimal_loop.py` | Short end-to-end loop |
+| `examples/06_office31_sklearn.py` | D1 + `MatchedSubspaceProjector` + logistic |
+| `examples/07_vision_multilayer.py` | `MultiLayerPMHLoss` + per-layer Gram noise |
+
+## API map
+
+| Goal | API |
+|------|-----|
+| Pick estimator | `SigmaTaskConfig.for_domain()`, `.for_isotropic()`, … |
+| Estimate | `estimate_from_config(cfg, ...)` → `SigmaTaskEstimate` |
+| Pre-flight | `artifact.preflight`, `preflight_eigengap(cov, rank)` |
+| Train | `PMHLoss(artifact, PMHConfig(...))` |
+| Controls | `PMHLoss(..., mode="wrong_w")`, `signal_W_projector` |
+| Data hook | `collect_features(encoder, loader)` |
+
+## Estimators (`method=`)
+
+| Method | Lemma | Config helper |
+|--------|-------|----------------|
+| D1 | Subspace SVD | `for_subspace(rank=)` |
+| D2 | Isotropic | `for_isotropic(dim, noise_level)` |
+| D3 | Aug modes | `for_augmentation()` |
+| D4 | Domain Gram | `for_domain(rank=)` |
+| D5 | Compositional | `for_compositional(indices)` |
+| D6 | Temporal | `for_temporal()` |
+| D7 | Style / alignment | `for_alignment(rank=)` |
+
+## Status
+
+**0.5.0** — `PMHTrainer` (HF), CORAL baseline, GitHub Actions CI + PyPI publish guide.
+
+| Extra | Install | Example |
+|-------|---------|---------|
+| HF Trainer | `pip install "matching-pmh[hf]"` | `examples/10_hf_trainer.py` |
+| CORAL baseline | `pmh.baselines.coral` | `examples/06_office31_sklearn.py` |
+| CI / PyPI | see `PUBLISHING.md` | tag `v0.5.0` |
+
+**0.4.0** — Hugging Face D7 (`estimate_style_sigma`), Lightning (`add_pmh_to_loss`), Office-31 features (`--office31-root`).
+
+| Extra | Install | Example |
+|-------|---------|---------|
+| HF | `pip install "matching-pmh[hf]"` | `examples/08_hf_style_d7.py` |
+| Lightning | `pip install "matching-pmh[lightning]"` | `examples/09_lightning_module.py` |
+| Vision / Office-31 | `pip install "matching-pmh[vision]"` | `examples/06_office31_sklearn.py --office31-root ...` |

matching_pmh-0.6.0/SEPARATION.md

@@ -0,0 +1,24 @@
+# Repository separation
+
+This project **must** live in its own git repository, separate from the paper LaTeX / experiment codebase.
+
+## Do
+
+- Version, release, and license **here** only.
+- Keep dependencies minimal (`torch`, `numpy`).
+- Add integrations (Hugging Face, Lightning) in this repo or optional extras.
+
+## Do not
+
+- Import from `Paper2/T1`, `T7`, or `submission_grand_unification/`.
+- Copy frozen task JSON or appendix tables into this tree.
+- Block paper submission on library polish.
+
+## Paper ↔ library link
+
+In the manuscript: one sentence in the reproducibility paragraph, e.g.  
+*“Reference implementation: [matching-pmh](https://github.com/…).”*
+
+In this README: paper title + “cite when using the package.”
+
+No shared CI, no monorepo requirement.

matching_pmh-0.6.0/docs/cli.md

@@ -0,0 +1,31 @@
+# CLI: `pmh-train`
+
+Installed with the package:
+
+```bash
+pip install matching-pmh
+pmh-train list-methods
+```
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `list-methods` | Table of D1–D7 inputs |
+| `estimate --config job.json` | Run estimator, write `output.pt` + `.json` |
+| `preflight ARTIFACT.pt` | Eigengap $\gamma_r$ diagnostics |
+| `run --config job.json` | Validate training job (artifact + PMH weights) |
+
+## Example jobs
+
+- `examples/configs/d4_estimate.json` — domain Gram (numpy paths)
+- `examples/configs/d7_style_estimate.json` — HF style JSONL
+- `examples/configs/dpo_train_job.json` — training recipe after D7 estimate
+
+```bash
+pmh-train estimate --config examples/configs/d7_style_estimate.json
+pmh-train preflight artifacts/d7_style.pt
+pmh-train run --config examples/configs/dpo_train_job.json
+```
+
+Python equivalent: `python -m pmh.cli.main estimate --config ...`

matching_pmh-0.6.0/docs/datasets.md

@@ -0,0 +1,20 @@
+# Datasets
+
+## Office-31 features
+
+Install: `pip install "matching-pmh[vision]"` (torchvision).
+
+```python
+from pmh.datasets.office31 import extract_office31_features, list_office31_domains
+
+x_a, y_a = extract_office31_features("/data/office31", "amazon", max_samples=2000)
+x_d, y_d = extract_office31_features("/data/office31", "dslr", max_samples=2000)
+```
+
+CLI example:
+
+```bash
+python examples/06_office31_sklearn.py --office31-root /data/office31 --source amazon --target dslr
+```
+
+Expect layout: `root/amazon/<class>/...` (ImageFolder).

matching_pmh-0.6.0/docs/estimators/d1.md

@@ -0,0 +1,23 @@
+# D1 — Subspace nuisance (Lemma D1)
+
+**When:** a low-rank subspace $W$ explains cross-domain variation (digits, domains with class alignment).
+
+**Config:** `SigmaTaskConfig.for_subspace(rank=r)`
+
+**PyTorch:**
+
+```python
+artifact = estimate_from_config(cfg, h_src, h_tgt)  # [N, d] features
+```
+
+**NumPy / sklearn:**
+
+```python
+from pmh.sklearn_match import MatchedSubspaceProjector
+proj = MatchedSubspaceProjector(rank=16).fit(x_a, y_a, x_d, y_d)
+x_matched = proj.transform(x_a)
+```
+
+**Pre-flight:** check `artifact.preflight` — small eigengap $\Rightarrow$ Office-31-style failure.
+
+**Example:** `examples/06_office31_sklearn.py`