patchcraft 0.2.0__tar.gz → 0.2.1__tar.gz

{patchcraft-0.2.0 → patchcraft-0.2.1}/.github/workflows/release.yml

@@ -25,13 +25,24 @@ jobs:
   validate:
     name: re-run tests at tag ref
     runs-on: ubuntu-latest
+    env:
+      UV_PYTHON: "3.13"
     steps:
       - uses: actions/checkout@v4
       - uses: astral-sh/setup-uv@v3
         with:
           enable-cache: true
-      - run: uv python install 3.13
-      - run: uv sync --extra cache --extra dev --python 3.13
+      - run: uv python install
+      - run: uv sync --locked --extra cache --extra dev
+      - name: Tag must match __version__
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg="$(uv run python -c 'import patchcraft; print(patchcraft.__version__)')"
+          if [ "$tag" != "$pkg" ]; then
+            echo "::error::tag ${GITHUB_REF_NAME} implies version '${tag}' but patchcraft.__version__ is '${pkg}'"
+            exit 1
+          fi
+          echo "tag ${GITHUB_REF_NAME} matches __version__ ${pkg}"
       - run: uv run ruff check src tests
       - run: uv run mypy --strict src
       - run: uv run pytest -m "not gpu"
@@ -69,6 +80,12 @@ jobs:
           path: dist/
       - name: Publish via Trusted Publishing
         uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # A version already on PyPI is a no-op instead of a hard failure.
+          # Without this, re-running the pipeline (or tagging a version that
+          # was uploaded by hand) fails here, and `github-release` never runs
+          # because it is `needs: publish-pypi`.
+          skip-existing: true
         # No `password` field -- OIDC handles authentication.
         # The pypi.org "Pending publisher" config must match:
         #   PyPI project name: patchcraft

{patchcraft-0.2.0 → patchcraft-0.2.1}/.github/workflows/test.yml

@@ -19,6 +19,12 @@ jobs:
       matrix:
         os: [ubuntu-latest, windows-latest]
         python: ["3.12", "3.13"]
+    env:
+      # Force uv to use the matrix Python in every uv* invocation
+      # (otherwise `uv run` re-resolves to its default, which is the
+      # newest installed interpreter -- masking the matrix and leaking
+      # the dev deps installed under a different version).
+      UV_PYTHON: ${{ matrix.python }}
     steps:
       - uses: actions/checkout@v4
 
@@ -28,10 +34,12 @@ jobs:
           enable-cache: true
 
       - name: Set up Python ${{ matrix.python }}
-        run: uv python install ${{ matrix.python }}
+        run: uv python install
 
       - name: Install project with dev + cache extras
-        run: uv sync --extra cache --extra dev --python ${{ matrix.python }}
+        # --locked: fail if uv.lock is stale or absent rather than silently
+        # re-resolving, so the committed lock is what CI actually validates.
+        run: uv sync --locked --extra cache --extra dev
 
       - name: Ruff
         run: uv run ruff check src tests

patchcraft-0.2.1/CHANGELOG.md

@@ -0,0 +1,271 @@
+# Changelog
+
+All notable changes to PatchCraft will be documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.1] 2026-08-04
+
+Bugfix release. Closes the full correctness backlog found by the 0.2.0 audit
+(2026-08-03). Every fix below was first reproduced as a failing regression
+test measuring the same quantities quoted from the audit, then fixed, then
+verified by round-trip lab scripts under `lab/2026-08-04-*.py` (reports in
+`Z:\outputs\patchcraft\2026-08-04-*\`). Test suite: 309 → 345 passed. No new
+features; the only namespace change is `WeightKind` becoming reachable, which
+was itself an audit defect.
+
+### Fixed: the four audit defects
+
+- **`reconstruct` and `stitch` silently zeroed every pixel the patch grid did
+  not cover.** Both validated only the patch *count*
+  (`n_patches == num_h * num_w`) and never the *coverage*
+  (`(num_h - 1) * sh + ph == h`). A truncated grid returned a partly-black
+  image instead of raising, contradicting the bit-exact round-trip guarantee
+  in `docs/THEORY.md` §9.2. Measured on 0.2.0: `10×10` with `patch_size=4,
+  stride=4` returned 36 of 100 pixels zeroed; `13×13` with `patch_size=5,
+  stride=5` returned 69 of 169. Both functions now reject any grid whose last
+  patch does not end exactly on the image edge, with a `ValueError` naming the
+  covered vs. requested extents and pointing at `patchcraft.tilings`.
+- **`stitch(..., weight="hann")` zeroed most of the image, not the four
+  corners.** The old `_hann_1d(n)` was the symmetric window
+  `0.5·(1 − cos(2πi/(n−1)))`, exactly zero at both endpoints. Measured on
+  0.2.0: `12×12, patch 4, stride 4` came back with 108 of 144 pixels zeroed;
+  `patch_size=2` degenerated to an all-zero window and returned an all-black
+  image with no error. The window is now the interior of a longer symmetric
+  Hann window, `hann_window(n + 2, periodic=False)[1:-1]`, strictly positive
+  on every sample (THEORY §2.5). Output values of `stitch(hann)` change for
+  every geometry; round-trip of unmodified patches remains exact.
+- **`resize` corrupted integer dtypes on the torch backend.** `_resize_torch`
+  cast back with a bare `out[0].to(original_dtype)`, with no clamp and no
+  round. Bicubic legitimately overshoots the input range, so the cast wrapped:
+  `-9.0 → 247`, `281.9 → 25`. Measured on 0.2.0: an 8×8 uint8 hard edge
+  resized to 32×32 had 256 of 1024 pixels wrong, black pixels becoming 254
+  and white pixels becoming 1. The cast back now rounds and clamps to the
+  `torch.iinfo` range of the integer dtype. Separately, the `pil` backend's
+  clamp of out-of-range floats to `[0, 1]` (the uint8 hop) is now documented
+  behavior in the docstring and THEORY §9.4 instead of a silent surprise.
+- **`per_patch_mse` / `per_patch_psnr` did not promote to `float64`** the way
+  `patch_metrics` does. On 0.2.0, `uint8` input raised a raw torch
+  `RuntimeError` with no mention of PatchCraft, and `float16` input silently
+  returned `inf`. Both now compute in `float64` for any input dtype and always
+  return `float64` (contract change recorded in THEORY §9.8).
+
+### Fixed: secondary defects recorded by the audit
+
+- **`reconstruct` and `stitch` overflowed to `inf` on `float16`/`bfloat16`.**
+  `F.fold` accumulates the sum of all overlapping patches before the count-map
+  division, and the numerator exceeds the fp16 finite max (65504) well before
+  the division happens. Measured on 0.2.0: fp16 constant image of `10000.0`,
+  `patch 3, stride 1`, returned `inf` in 144 of 256 pixels. Half-precision
+  inputs now accumulate internally in `float32` (fold, count map, division)
+  and are cast back to the original dtype on return.
+- **`reconstruct` rejected integer dtypes with a raw torch
+  `NotImplementedError`** (`col2im_out_cpu` not implemented for
+  `Byte`/`Int`/`Long`). It now raises a clear `ValueError` up front, matching
+  the `stitch` guard.
+- **`WeightKind` was unreachable from the public namespace** despite appearing
+  in `stitch`'s signature. It is now exported by `patchcraft.stitch` and
+  re-exported by `patchcraft` (public API: 18 → 19 symbols).
+
+### Fixed: CI and packaging (carried over from the audit pass)
+
+- The sdist no longer ships `lab/` or `.vscode/`. The published
+  `patchcraft-0.2.0.tar.gz` contains `lab/usage_demo.py`,
+  `lab/usage_demo.out` and `lab/2026-05-16-roundtrip-mnist.py`, three files
+  that `lab/.gitignore` excludes from version control, which made that sdist
+  impossible to reproduce from any commit. The wheel was never affected.
+- `.github/workflows/release.yml` passes `skip-existing: true` to
+  `gh-action-pypi-publish`, so re-running the pipeline on an already-published
+  version is a no-op instead of a hard failure that also skips the
+  GitHub Release job. The `validate` job now refuses to proceed when the tag
+  does not match `patchcraft.__version__`.
+- Both workflows run `uv sync --locked`, so `uv.lock` is now actually enforced
+  in CI rather than being advisory.
+
+## [0.2.0] 2026-05-17
+
+Second public release. Adds three feature groups motivated by the QPatchSR
+super-resolution consumer plus internal ergonomics. No breaking changes vs
+v0.1.0, so all v0.1.0 imports keep working.
+
+### Changed: package name (twice, both on 2026-05-17)
+
+The project shipped v0.1.0 to GitHub under the name **PatchKit** and was
+renamed twice in the run-up to the first PyPI upload, each time because the
+name was already taken:
+
+1. `patchkit` → `patchforge` (commit `f761834`), because `pypi.org/project/patchkit/`
+   belongs to an unrelated model-patching utility.
+2. `patchforge` → `patchcraft` (commit `627a9c8`, final), because
+   `pypi.org/project/patchforge/` was also taken, by a llama-server CLI.
+
+Both renames were done by string substitution across the tree, which rewrote
+the historical entries below: the v0.1.0 section of this file says
+`patchcraft`, but `git show v0.1.0:pyproject.toml` says `name = "patchkit"`
+and `git ls-tree v0.1.0 src/` says `src/patchkit`. **v0.1.0 was never
+published to PyPI under any name**: `patchcraft` 0.2.0 is the first and only
+PyPI release, so no import path that ever existed on PyPI has changed, and no
+migration shim is needed. Read the v0.1.0 section as a record of *what the API
+was*, not of *what the package was called*.
+
+### Added: cross-resolution geometry (THEORY §1.5, §9.7)
+
+Motivated by the QPatchSR consumer's question: "given two image shapes
+(LR and HR of the same source), what `(patch_size, stride)` on each
+side yields the same number of patches with corresponding regions?"
+Three new helpers in `patchcraft.geometry`:
+
+- **`scale_factor(lr_shape, hr_shape) -> int | None`** returns the
+  integer `k` such that `hr.shape[-2:] == (k * lr.shape[-2], k *
+  lr.shape[-1])`, or `None`. Accepts `(H, W)` or `(C, H, W)`. Pre-
+  flight check for `pair`.
+- **`paired_tilings(lr_shape, hr_shape, *, allow_overlap=False, ...)`**
+  enumerates every `(lr_spec, hr_spec)` pair where both fully cover
+  their respective image and produce identical patch counts. Patch
+  `k` on each side covers the same image region.
+  Example: `paired_tilings((14, 14), (28, 28))` returns three pairs:
+  `(p_lr=2, p_hr=4, total=49)`, `(p_lr=7, p_hr=14, total=4)`,
+  `(p_lr=14, p_hr=28, total=1)`.
+- **`PairedTilingSpec(lr, hr, scale_factor)`** is a `NamedTuple` carrying
+  both sides and the discovered scale factor.
+
+### Added: patch-level pixel metrics (THEORY §1.6, §9.8)
+
+Canonical reductions so consumers don't reinvent slightly-divergent
+versions in every project. New module `patchcraft.metrics`:
+
+- **`patch_metrics(a, b, *, max_value=1.0) -> dict[str, float]`**:
+  scalar `mae`, `mse`, `max_abs`, `psnr_db` over the full tensor
+  (any matching shape works). Internal accumulation in `float64`
+  for stability; PSNR returns `+inf` for identical inputs.
+- **`per_patch_mse(a, b) -> Tensor[L]`** gives one MSE per patch in a
+  `(L, C, h, w)` stack.
+- **`per_patch_psnr(a, b, *, max_value=1.0) -> Tensor[L]`** gives one
+  PSNR per patch. Identical patches yield `+inf` via `torch.where`
+  (no clamp tricks).
+
+Explicitly **not** included: SSIM, MS-SSIM, LPIPS, FID, any windowed
+or learned metric. Use `pytorch-msssim`, `lpips`, `clean-fid` on the
+caller side ([SCOPE.md](docs/SCOPE.md) §4.3 explains the boundary).
+
+### Added: patch stitching for modified patches (THEORY §2.5, §9.9)
+
+`reconstruct` is the bit-exact inverse of `extract`. When patches have
+been modified (model output, denoised, super-resolved), averaging them
+back uniformly shows visible seams at patch boundaries. `stitch` is the
+seam-aware counterpart: it folds patches weighted by a 2-D window
+kernel so each pixel "trusts" patches closer to its center more.
+
+- **`stitch(patches, image_shape, stride, *, weight="uniform"|"hann"|"gaussian", dilation=1)`**
+  keeps the same `F.fold` geometry and rejections as `reconstruct`; adds a
+  weighted-blend numerator over a weighted-sum denominator. With
+  `weight="uniform"` it is mathematically equivalent to `reconstruct`
+  (covered by a bit-exact equality test on no-overlap and `allclose`
+  on overlap). With `"hann"` it strongly suppresses seams at the
+  cost of zeroing image corners that fall on Hann's edge-weight-zero
+  region (documented artifact). With `"gaussian"`
+  (`sigma = max(1, min(ph, pw) / 4)`) it blends smoothly with no
+  corner artifact.
+
+Floating-point patches only, because window kernels are float-valued and we
+refuse to silently quantize or implicitly promote. Caller converts to
+`float` first.
+
+### Changed
+
+- Public API surface: 11 → 18 symbols.
+- [`docs/SCOPE.md`](docs/SCOPE.md) gains rows for paired tilings,
+  pixel metrics, and stitch; §4.3 discusses why pixel metrics stayed
+  core while windowed/learned metrics did not, §4.4 explains why
+  `stitch` is a separate function from `reconstruct` rather than a
+  kwarg.
+- [`docs/THEORY.md`](docs/THEORY.md) gains §1.5 expansion (cross-
+  resolution paragraphs), §1.6 (patch comparison metrics), §2.5
+  (stitch: math, kernels, why it is separate), §9.7
+  (paired tilings contract), §9.8 (metrics contract), §9.9 (stitch
+  contract).
+
+## [0.1.0] 2026-05-16
+
+First public release. Public API stable; signatures will only change in 1.x.
+
+### Added: core (one image at a time)
+
+- **`extract(image, patch_size, stride, dilation=1)`** gives patches from a
+  `(C, H, W)` tensor via `torch.nn.functional.unfold`. Truncation-only
+  boundary; returns `Tensor[0, C, ph, pw]` when geometry fits no patch.
+  Per [ADR 0001](docs/ADR/0001-patch-extraction-api.md).
+- **`Patchify(patch_size, stride, dilation=1)`** is the callable wrapper for
+  `torchvision.transforms.Compose([...])`. Eager geometry validation in
+  `__init__`; `__slots__`-bound (no state beyond config). Per
+  [ADR 0002](docs/ADR/0002-patchify-transform.md).
+- **`reconstruct(patches, image_shape, stride, dilation=1)`** is the inverse
+  of `extract` via `F.fold` plus a fold-of-ones count map. Bit-exact
+  round-trip for `stride == patch_size`; weighted-exact for overlap.
+  Rejects `dilation != 1` and `stride > patch_size` (partial coverage
+  is forbidden by design, because synthesizing pixel values is not PatchCraft's
+  job).
+- **`pair(lr_image, hr_image, lr_patch_size, scale_factor, stride, *, image_id=None)`**
+  gives LR/HR patch correspondences. Returns a frozen `PatchPair`
+  dataclass with `lr_patches`, `hr_patches`, `metas`. Integer
+  `scale_factor` only. LR and HR must share `C`, dtype, and device.
+- **`PatchPair`**, **`PatchMeta`** are frozen `@dataclass(slots=True)`.
+  `PatchMeta` carries `patch_index`, `row`, `col` (LR coords),
+  `lr_patch_size`, `hr_patch_size`, `image_id`. CPU-only metadata.
+- **`resize(image, target_size, backend="pil", resample=None)`**:
+  single-image resize. Output type matches input
+  (PIL → PIL, Tensor → Tensor). Cross-backend conversions go through
+  a float32 [0, 1] / uint8 hop (numpy intermediate; no torchvision in
+  the core). CUDA tensors accepted only with `backend="torch"`.
+- **`Cache(root, namespace, version=1)`** is a content-addressed disk
+  cache. `key_for(*parts) → str`, `put(key, bytes)`, `get(key) → bytes | None`.
+  Atomic write via `*.tmp` + `os.replace` with retry on transient
+  `PermissionError` (5 attempts on put with exponential backoff
+  `0.25/0.5/1/2/4` s, which handles OneDrive, antivirus, Windows Search
+  races). Optional zstandard compression at level 3 (`[cache]` extra);
+  uncompressed fallback when not installed. Sidecar JSON carries
+  SHA-256 checksum; corruption surfaces as `OSError`.
+- **`num_patches(image_shape, patch_size, stride, dilation=1)`** is the
+  patch count formula, exposed as a function. No allocation, no
+  tensor. Accepts `(H, W)` or `(C, H, W)`.
+- **`tilings(image_shape, *, allow_overlap=False, min_patch_size=2, max_patch_size=None)`**
+  enumerates every square, full-coverage `(patch_size, stride)`
+  geometry. Always emits `dilation=(1, 1)`. With default flags returns
+  exact tilings only (`patch_size == stride`, divisibility); with
+  `allow_overlap=True` adds clean-edge overlap geometries. Truncated
+  geometries are deliberately excluded, because the function answers "what is
+  sound by construction?", not "what will `extract` accept?".
+- **`TilingSpec`** is a `NamedTuple(patch_size, stride, dilation,
+  num_patches, total_patches, overlap)`.
+
+### Added: packaging
+
+- `py.typed` marker (PEP 561): downstream `mypy` now honors PatchCraft's
+  type hints.
+- `[cache]` extra: pulls `zstandard>=0.22` for compressed cache
+  entries. Core works without it.
+
+### Out of scope (v0.1.x)
+
+- Multi-image batched API: use a `for` loop, `torch.vmap`, or a
+  `DataLoader`. See `Patchify` for `transforms.Compose` integration.
+- Dataset orchestration (download, batching, sampling): the auxiliary
+  framework in [`tests/_datasets.py`](tests/_datasets.py) handles this
+  for the test suite and `lab/` scripts; it is not shipped in the wheel.
+- Channels-last layout, quantization, `nn.Module` integration:
+  documented in [`docs/THEORY.md`](docs/THEORY.md) §6 and §8 (open
+  questions).
+
+### Documentation
+
+- [`docs/THEORY.md`](docs/THEORY.md) has §0 binding scope, §§1–6 design
+  decisions per primitive, §7 resolved questions, §8 open questions,
+  §9 the per-API condition contract (Accepts / Rejects / Out of scope)
+  that the test suite mirrors.
+- [`docs/ADR/0001-patch-extraction-api.md`](docs/ADR/0001-patch-extraction-api.md)
+  and [`docs/ADR/0002-patchify-transform.md`](docs/ADR/0002-patchify-transform.md).
+- [`README.md`](README.md) covers installation, the car-vs-track metaphor,
+  validation lab.
+
+[0.2.0]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.2.0
+[0.1.0]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.1.0

patchcraft-0.2.1/CONTRIBUTING.md

@@ -0,0 +1,98 @@
+# Contributing to PatchCraft
+
+If you've cloned this repo and want to run the test suite, understand how the project is laid out, or follow the validation conventions, this is the page. For installation and usage, see the [README](README.md).
+
+---
+
+## Run tests
+
+```
+pytest
+pytest -m "not gpu"        # skip GPU-requiring tests
+```
+
+CI runs the full suite on every push and PR. See [`.github/workflows/test.yml`](.github/workflows/test.yml). Matrix is `{ubuntu-latest, windows-latest} × {python 3.12, 3.13}`. To run the same checks locally before pushing:
+
+```
+ruff check src tests
+mypy --strict src
+pytest -m "not gpu"
+```
+
+---
+
+## Layout
+
+```
+PatchCraft/
+├── pyproject.toml                  package metadata, build backend (hatchling)
+├── README.md                       public-facing (also goes to PyPI as long_description)
+├── CONTRIBUTING.md                 this file
+├── CHANGELOG.md                    Keep-a-Changelog format
+├── LICENSE                         MIT
+├── .python-version                 3.13
+├── .gitignore                      ignores archive/, venvs, caches, outputs
+├── .github/workflows/
+│   ├── test.yml                    matrix CI on PRs/main
+│   └── release.yml                 publishes to PyPI on vX.Y.Z tag push (Trusted Publishing)
+├── src/patchcraft/                 library core, one-image-at-a-time primitives
+│   ├── __init__.py                 re-exports the full public API
+│   ├── extract.py                  patches via F.unfold; Patchify wrapper (ADR 0002)
+│   ├── reconstruct.py              inverse via F.fold + count map
+│   ├── stitch.py                   weighted reassembly for modified patches
+│   ├── geometry.py                 pre-flight: num_patches, tilings, scale_factor, paired_tilings
+│   ├── metrics.py                  patch_metrics, per_patch_mse, per_patch_psnr
+│   ├── pair.py                     LR↔HR pairing; PatchPair, PatchMeta
+│   ├── resize.py                   resize with PIL or torch backends
+│   └── cache.py                    content-addressed disk cache
+├── tests/                          pytest suite (contract tests for src/)
+│   ├── test_extract.py             extract + Patchify
+│   ├── test_reconstruct.py
+│   ├── test_stitch.py
+│   ├── test_geometry.py            num_patches + tilings + scale_factor + paired_tilings
+│   ├── test_metrics.py
+│   ├── test_pair.py
+│   ├── test_resize.py
+│   ├── test_cache.py
+│   ├── test_datasets_helper.py     label_subset
+│   ├── test_import.py
+│   └── _datasets.py                dev-only fixtures (MNIST, etc), NOT public API
+├── lab/                            ephemeral experiments; see lab/README.md
+│   ├── README.md                   bench rules (tracked)
+│   ├── usage_demo.py               regenerates the live REPL outputs in docs/USAGE.md
+│   └── .gitignore                  ignores everything else (tracked)
+├── docs/
+│   ├── USAGE.md                    live REPL walkthrough of every public API
+│   ├── SCOPE.md                    responsibilities matrix + parallelization analysis
+│   ├── AUXILIARY.md                tests/_datasets, lab/, Z:\ conventions (NOT part of the wheel)
+│   ├── THEORY.md                   distilled design + §9 condition contract; §0 binding scope
+│   ├── ROADMAP.md                  milestone plan
+│   └── ADR/
+│       ├── 0001-patch-extraction-api.md   pure function `extract`
+│       └── 0002-patchify-transform.md     callable wrapper for Compose pipelines
+└── archive/                        reference-only; gitignored (pruned 2026-05-17, only HISTORY.md kept)
+```
+
+---
+
+## Validation lab
+
+The library is "one image in, one tensor out" by design, but you only know it works once you run it end-to-end on real images. That happens in two places, neither of which is part of the shipped package:
+
+- [`tests/`](tests/) holds the formal pytest suite that defines the contract from [`docs/THEORY.md`](docs/THEORY.md) §9.
+- [`lab/`](lab/) holds ephemeral scripts and notebooks for fast hypothesis-checking. See [`lab/README.md`](lab/README.md) for the bench rules; outputs go to `Z:\outputs\patchcraft\` (off-tree).
+
+Datasets used by tests/lab are downloaded lazily into `Z:\caches\datasets\<name>\` on first use; they do not ship with the package and are never bundled into the wheel.
+
+The dev framework that makes this all work (fixtures, dataset helpers, `Z:\` conventions) is documented in [`docs/AUXILIARY.md`](docs/AUXILIARY.md).
+
+---
+
+## Releasing (maintainer only)
+
+1. Bump `__version__` in [`src/patchcraft/__init__.py`](src/patchcraft/__init__.py).
+2. Close the `[Unreleased]` section in [`CHANGELOG.md`](CHANGELOG.md) as `[X.Y.Z] YYYY-MM-DD`.
+3. Update [`docs/ROADMAP.md`](docs/ROADMAP.md) milestone checkboxes.
+4. Commit: `release: vX.Y.Z`.
+5. Tag + push: `git tag -a vX.Y.Z -m "..."` then `git push origin vX.Y.Z`.
+6. `release.yml` fires automatically: validates → builds → publishes to PyPI via Trusted Publishing → creates GitHub Release with `.whl` + `.tar.gz`.

{patchcraft-0.2.0 → patchcraft-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchcraft
-Version: 0.2.0
+Version: 0.2.1
 Summary: Image patch extraction, reconstruction, pairing and seam-aware stitching for super-resolution and dataset pipelines.
 Project-URL: Homepage, https://github.com/LeoPR/PatchCraft
 Project-URL: Repository, https://github.com/LeoPR/PatchCraft
@@ -40,18 +40,18 @@ Description-Content-Type: text/markdown
 
 # PatchCraft
 
-A small library for **encoding an image into patches and decoding it back**. Built to slot into other people's `torch` pipelines as one transform among many — like a `GaussianBlur` step in a `Compose([...])`.
+A small library for **encoding an image into patches and decoding it back**. Built to slot into other people's `torch` pipelines as one transform among many, like a `GaussianBlur` step in a `Compose([...])`.
 
-> **Status (2026-05-17):** v0.1.0 released; v0.2.0-track is on `main` (not yet tagged). Public API: `extract`, `Patchify`, `reconstruct`, `stitch`, `pair`, `resize`, `Cache`, plus geometry helpers (`num_patches`, `tilings`, `TilingSpec`, `scale_factor`, `paired_tilings`, `PairedTilingSpec`), pixel metrics (`patch_metrics`, `per_patch_mse`, `per_patch_psnr`), and `PatchPair`/`PatchMeta`.
+> **Status:** v0.2.1 on PyPI, installable with `pip install patchcraft`. Public API (19 symbols): `extract`, `Patchify`, `reconstruct`, `stitch` (+ its `WeightKind`), `pair`, `resize`, `Cache`, plus geometry helpers (`num_patches`, `tilings`, `TilingSpec`, `scale_factor`, `paired_tilings`, `PairedTilingSpec`), pixel metrics (`patch_metrics`, `per_patch_mse`, `per_patch_psnr`), and `PatchPair`/`PatchMeta`.
 
 ## The lib vs. this repo
 
 Think of the lib as a **car** and this repo as the **car plus its test track**.
 
-- **The car** — [`src/patchcraft/`](src/patchcraft/) — is what gets installed by `pip install patchcraft`. It is a single library with one job: take one image (`Tensor[C, H, W]`), encode it into patches, decode patches back into the image, optionally pair LR/HR, resize, cache. **One image at a time, every time.** No datasets, no training, no orchestration, no batching across images. Multi-image is the caller's `for` loop, or `torch.vmap`, or a `DataLoader`.
-- **The track** — [`tests/`](tests/), [`lab/`](lab/), [`tests/_datasets.py`](tests/_datasets.py), and the dev extras (`torchvision`, etc.) — is the pit crew, telemetry, driver and stopwatch that **prove the car works** on real images (MNIST today; more later). It downloads datasets, drives the lib through varied geometries, measures correctness. It never ships in the wheel.
+- **The car** is the [`patchcraft`](https://github.com/LeoPR/PatchCraft/tree/main/src/patchcraft) package, what gets installed by `pip install patchcraft`. It is a single library with one job: take one image (`Tensor[C, H, W]`), encode it into patches, decode patches back into the image, optionally pair LR/HR, resize, cache. **One image at a time, every time.** No datasets, no training, no orchestration, no batching across images. Multi-image is the caller's `for` loop, or `torch.vmap`, or a `DataLoader`.
+- **The track** is `tests/`, `lab/`, `tests/_datasets.py` and the dev extras (`torchvision`, etc.) in the repo. It is the pit crew, telemetry, driver and stopwatch that **prove the car works** on real images. It downloads datasets, drives the lib through varied geometries, measures correctness. It never ships in the wheel. See [CONTRIBUTING.md](https://github.com/LeoPR/PatchCraft/blob/main/CONTRIBUTING.md) if you're contributing.
 
-The car is also **acoplável** — designed to drop into someone else's pipeline:
+The car is also **acoplável**, designed to drop into someone else's pipeline:
 
 ```python
 from patchcraft import Patchify
@@ -70,7 +70,7 @@ transform = transforms.Compose([
 
 The five core operations, one diagram each. Letters mark which patch each cell came from / goes to.
 
-### `extract` — image → patch stack
+### `extract`: image → patch stack
 
 `patch_size=4`, `stride=4` (no overlap) on an 8×8 image:
 
@@ -89,7 +89,7 @@ The five core operations, one diagram each. Letters mark which patch each cell c
    +-----------------+
 ```
 
-### `reconstruct` — patch stack → image (bit-exact when `stride == patch_size`)
+### `reconstruct`: patch stack → image (bit-exact when `stride == patch_size`)
 
 Each output pixel = sum of patch contributions / `count` map (= how many patches covered it). When `stride == patch_size`, `count` is all-ones and the divide is a no-op.
 
@@ -105,7 +105,7 @@ Each output pixel = sum of patch contributions / `count` map (= how many patches
      count:  1  1  2  2  2  2  1  1   <- divide sum by this
 ```
 
-### `pair` — LR <-> HR, same image region, different resolution
+### `pair`: LR <-> HR, same image region, different resolution
 
 `scale_factor=2`: every k-th LR patch corresponds to the k-th HR patch; HR coords are LR coords times the integer scale.
 
@@ -125,21 +125,22 @@ Each output pixel = sum of patch contributions / `count` map (= how many patches
    LR patch at (row=1, col=1)  <-->  HR patch at (row=2, col=2)
 ```
 
-### `stitch` — same fold geometry as `reconstruct`, but each patch weighted by a window kernel
+### `stitch`: same fold geometry as `reconstruct`, with each patch weighted by a window kernel
 
 Use when patches were modified by a model and uniform averaging shows boundary seams. Window kernels for `patch_size=4`:
 
 ```
    weight="uniform"     weight="hann"        weight="gaussian"
-   (== reconstruct)     centers > edges      centers >> edges (never 0)
+   (== reconstruct)     centers > edges      centers >> edges
+                        (never 0)            (never 0)
 
-   + + + +              . . . .              . o o .
-   + + + +              . X X .              o X X o
-   + + + +              . X X .              o X X o
-   + + + +              . . . .              . o o .
+   + + + +              . X X .              . o o .
+   + + + +              X X X X              o X X o
+   + + + +              X X X X              o X X o
+   + + + +              . X X .              . o o .
 
    no seam attenuation  strong attenuation,  smooth attenuation,
-                        image corners -> 0   corners preserved
+                        corners preserved    corners preserved
 ```
 
 ### Everything stays one-image-at-a-time
@@ -151,25 +152,25 @@ Use when patches were modified by a model and uniform averaging shows boundary s
        out     = stitch(result, ...)       # PatchCraft primitive
 ```
 
-Multi-image parallelism is the caller's pipeline (`torch.vmap`, `DataLoader` workers, etc.) — see [`SCOPE.md`](docs/SCOPE.md) §2.
+Multi-image parallelism is the caller's pipeline (`torch.vmap`, `DataLoader` workers, etc.). See [SCOPE.md](https://github.com/LeoPR/PatchCraft/blob/main/docs/SCOPE.md) §2.
 
 ## Scope (what the car does)
 
 - **Extract** patches from a single image with configurable size, stride and dilation (`extract`, `Patchify`).
-- **Reconstruct** an image from its patches — exact and weighted-overlap (`reconstruct`).
+- **Reconstruct** an image from its patches, exact and weighted-overlap (`reconstruct`).
 - **Stitch** *modified* patches (model output, denoised, super-resolved) back into one image with a window kernel that attenuates boundary seams (`stitch`, with `weight="uniform"|"hann"|"gaussian"`).
-- **Plan** the geometry ahead of time: `num_patches((H, W), ...)` for the count, `tilings((H, W), allow_overlap=...)` for every full-coverage `(patch_size, stride)` combo (no image, no allocation — just arithmetic). For LR↔HR setups: `scale_factor(...)` and `paired_tilings(...)`.
+- **Plan** the geometry ahead of time: `num_patches((H, W), ...)` for the count, `tilings((H, W), allow_overlap=...)` for every full-coverage `(patch_size, stride)` combo (no image, no allocation, just arithmetic). For LR↔HR setups: `scale_factor(...)` and `paired_tilings(...)`.
 - **Pair** LR and HR patches with metadata sufficient to reconstruct either (`pair`, `PatchPair`, `PatchMeta`).
 - **Measure** pixel-level error between two patch stacks: `patch_metrics`, `per_patch_mse`, `per_patch_psnr`.
-- **Resize** with pluggable backends — PIL or torch (`resize`).
+- **Resize** with pluggable backends, either PIL or torch (`resize`).
 - **Cache** results on disk with content-addressed keys, OneDrive-race retry, optional zstd (`Cache`).
 
 ## Scope (what the car does NOT do)
 
-- **Not a dataset manager.** PatchCraft does not load, download, batch, shuffle, or stream datasets. That's the track's job — `tests/_datasets.py` has `mnist_subset(...)` for dev fixtures, and `torchvision` is in the `[dev]` extra (never a runtime dep of the car).
+- **Not a dataset manager.** PatchCraft does not load, download, batch, shuffle, or stream datasets. That's the track's job: `tests/_datasets.py` has `mnist_subset(...)` for dev fixtures, and `torchvision` is in the `[dev]` extra (never a runtime dep of the car).
 - **Not a multi-image API.** Every primitive takes one image. Use `vmap` or a Python loop if you need to apply it to many.
-- No SVMs, no kernels, no quantum circuits — those belong to other projects.
-- No neural network training — PatchCraft is infrastructure, not a model.
+- No SVMs, no kernels, no quantum circuits: those belong to other projects.
+- No neural network training. PatchCraft is infrastructure, not a model.
 
 ## Install
 
@@ -191,75 +192,16 @@ pip install -e ".[dev,cache]"
 For GPU support, install a matching torch wheel before PatchCraft
 (e.g. `pip install torch --index-url https://download.pytorch.org/whl/cu124`).
 
-## Run tests
-
-```
-pytest
-pytest -m "not gpu"        # skip GPU-requiring tests
-```
-
-## Layout
-
-```
-PatchCraft/
-├── pyproject.toml                  package metadata, build backend (hatchling)
-├── README.md                       this file
-├── LICENSE                         MIT
-├── .python-version                 3.13
-├── .gitignore                      ignores archive/, venvs, caches, outputs
-├── src/patchcraft/                   library core — one-image-at-a-time primitives
-│   ├── __init__.py                 re-exports the full public API
-│   ├── extract.py                  patches via F.unfold; Patchify wrapper (ADR 0002)
-│   ├── reconstruct.py              inverse via F.fold + count map
-│   ├── geometry.py                 pre-flight: num_patches, tilings, TilingSpec
-│   ├── pair.py                     LR↔HR pairing; PatchPair, PatchMeta
-│   ├── resize.py                   resize with PIL or torch backends
-│   └── cache.py                    content-addressed disk cache
-├── tests/                          pytest suite (contract tests for src/)
-│   ├── test_extract.py             extract + Patchify
-│   ├── test_reconstruct.py
-│   ├── test_geometry.py            num_patches + tilings
-│   ├── test_pair.py
-│   ├── test_resize.py
-│   ├── test_cache.py
-│   ├── test_datasets_helper.py     label_subset
-│   ├── test_import.py
-│   └── _datasets.py                dev-only fixtures (MNIST, etc) — NOT public API
-├── lab/                            ephemeral experiments; see lab/README.md
-│   ├── README.md                   bench rules (tracked)
-│   └── .gitignore                  ignores everything else (tracked)
-├── docs/
-│   ├── USAGE.md                    live REPL walkthrough of every public API
-│   ├── SCOPE.md                    responsibilities matrix + parallelization analysis
-│   ├── AUXILIARY.md                tests/_datasets, lab/, Z:\ conventions (NOT part of the wheel)
-│   ├── THEORY.md                   distilled design + §9 condition contract; §0 binding scope
-│   ├── ROADMAP.md                  milestone plan
-│   └── ADR/
-│       ├── 0001-patch-extraction-api.md   pure function `extract`
-│       └── 0002-patchify-transform.md     callable wrapper for Compose pipelines
-└── archive/                        reference-only; gitignored (pruned 2026-05-17 — only HISTORY.md kept)
-```
-
-## Validation lab
-
-The library is "one image in, one tensor out" by design — but you only know it works once you run it end-to-end on real images. That happens in two places, neither of which is part of the shipped package:
-
-- [`tests/`](tests/) — formal pytest suite that defines the contract from [`docs/THEORY.md`](docs/THEORY.md) §9.
-- [`lab/`](lab/) — ephemeral scripts and notebooks for fast hypothesis-checking. See [`lab/README.md`](lab/README.md) for the bench rules; outputs go to `Z:\outputs\patchcraft\` (off-tree).
-
-Datasets used by tests/lab are downloaded lazily into `Z:\caches\datasets\<name>\` on first use; they do not ship with the package and are never bundled into the wheel.
-
 ## Where to read next
 
 | If you want… | Open |
 |---|---|
-| A hands-on tour with real REPL outputs for every public API | [`docs/USAGE.md`](docs/USAGE.md) |
-| The line between "PatchCraft's job" and "your pipeline's job", plus the parallelization story | [`docs/SCOPE.md`](docs/SCOPE.md) |
-| The auxiliary test fixtures and lab conventions (not shipped) | [`docs/AUXILIARY.md`](docs/AUXILIARY.md) |
-| Design decisions, math, the per-API contract | [`docs/THEORY.md`](docs/THEORY.md) |
-| Architecture Decision Records | [`docs/ADR/`](docs/ADR/) |
-| Milestone plan | [`docs/ROADMAP.md`](docs/ROADMAP.md) |
-| Per-release changes | [`CHANGELOG.md`](CHANGELOG.md) |
+| A hands-on tour with real REPL outputs for every public API | [USAGE.md](https://github.com/LeoPR/PatchCraft/blob/main/docs/USAGE.md) |
+| The line between "PatchCraft's job" and "your pipeline's job", plus the parallelization story | [SCOPE.md](https://github.com/LeoPR/PatchCraft/blob/main/docs/SCOPE.md) |
+| Design decisions, math, the per-API contract | [THEORY.md](https://github.com/LeoPR/PatchCraft/blob/main/docs/THEORY.md) |
+| Architecture Decision Records | [ADR/](https://github.com/LeoPR/PatchCraft/tree/main/docs/ADR) |
+| Per-release changes | [CHANGELOG.md](https://github.com/LeoPR/PatchCraft/blob/main/CHANGELOG.md) |
+| Cloning and contributing (run tests, layout, validation conventions) | [CONTRIBUTING.md](https://github.com/LeoPR/PatchCraft/blob/main/CONTRIBUTING.md) |
 
 ## Author