patchcraft 0.2.0__tar.gz

patchcraft-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,111 @@
+name: release
+
+# Triggered when a version tag is pushed (vX.Y.Z[.aN, .bN, .rcN]).
+# Steps:
+#   1. Re-run the test job that test.yml uses (sanity check on the
+#      exact ref being released).
+#   2. Build the wheel + sdist with `uv build`.
+#   3. Publish to PyPI via Trusted Publishing (OIDC) -- no token,
+#      no secret. The pypi.org side must have a configured publisher
+#      pointing at THIS repo + THIS workflow + the `pypi` environment.
+#   4. Create / update the GitHub Release page and attach the
+#      `dist/*.whl` and `dist/*.tar.gz` files.
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+.[ab][0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+.rc[0-9]+"
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    name: re-run tests at tag ref
+    runs-on: ubuntu-latest
+    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 run ruff check src tests
+      - run: uv run mypy --strict src
+      - run: uv run pytest -m "not gpu"
+
+  build:
+    name: build wheel + sdist
+    runs-on: ubuntu-latest
+    needs: validate
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv build
+      - name: Inspect dist metadata
+        run: |
+          uv run --with twine twine check dist/*
+          ls -la dist/
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: publish to PyPI (Trusted Publishing)
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: pypi
+      url: https://pypi.org/project/patchcraft/
+    permissions:
+      id-token: write  # required for OIDC token exchange with PyPI
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish via Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # No `password` field -- OIDC handles authentication.
+        # The pypi.org "Pending publisher" config must match:
+        #   PyPI project name: patchcraft
+        #   Owner:             LeoPR
+        #   Repository:        PatchCraft
+        #   Workflow:          release.yml
+        #   Environment:       pypi
+
+  github-release:
+    name: create GitHub Release with assets
+    runs-on: ubuntu-latest
+    needs: publish-pypi
+    permissions:
+      contents: write  # required to create a Release
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Extract version from tag
+        id: ver
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+      - name: Create Release + attach assets
+        uses: softprops/action-gh-release@v2
+        with:
+          name: "PatchCraft ${{ github.ref_name }}"
+          body: |
+            See [`CHANGELOG.md`](https://github.com/LeoPR/PatchCraft/blob/main/CHANGELOG.md) for the full notes.
+
+            Install:
+            ```
+            pip install patchcraft==${{ steps.ver.outputs.version }}
+            ```
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+          fail_on_unmatched_files: true
+          draft: false
+          prerelease: false

patchcraft-0.2.0/.github/workflows/test.yml

@@ -0,0 +1,43 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: test-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / py${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python }}
+        run: uv python install ${{ matrix.python }}
+
+      - name: Install project with dev + cache extras
+        run: uv sync --extra cache --extra dev --python ${{ matrix.python }}
+
+      - name: Ruff
+        run: uv run ruff check src tests
+
+      - name: Mypy (strict, src only)
+        run: uv run mypy --strict src
+
+      - name: Pytest (skip GPU markers)
+        run: uv run pytest -m "not gpu"

patchcraft-0.2.0/.gitignore

@@ -0,0 +1,55 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual envs (lives on Z:, but guard anyway)
+.venv/
+venv/
+env/
+
+# Test and coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+
+# Type checkers / linters
+.mypy_cache/
+.ruff_cache/
+.pyre/
+.pytype/
+
+# IDE
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+.idea/
+
+# OS
+Thumbs.db
+.DS_Store
+*.lnk
+
+# Env vars
+.env
+.env.local
+
+# Experiment outputs
+outputs/
+runs/
+
+# Archive (reference material, not part of the package)
+/archive/
+
+# Datasets and caches live on Z:
+data/

patchcraft-0.2.0/.python-version

@@ -0,0 +1 @@
+3.13

patchcraft-0.2.0/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/Scripts/python.exe"
+}

patchcraft-0.2.0/CHANGELOG.md

@@ -0,0 +1,175 @@
+# 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).
+
+## [Unreleased]
+
+## [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 — all v0.1.0 imports keep working.
+
+### 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)`** — `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]`** — one MSE per patch in a
+  `(L, C, h, w)` stack.
+- **`per_patch_psnr(a, b, *, max_value=1.0) -> Tensor[L]`** — 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)`**
+  — 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 — 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)`** — 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)`** — 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)`** — 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 — synthesizing pixel values is not PatchCraft's
+  job).
+- **`pair(lr_image, hr_image, lr_patch_size, scale_factor, stride, *, image_id=None)`**
+  — 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`** — 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)`** — 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 — 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)`** — 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)`**
+  — enumerate 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 — the function answers "what is
+  sound by construction?", not "what will `extract` accept?".
+- **`TilingSpec`** — `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) — §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) — 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.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leonardo Marques de Souza
+
+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.

patchcraft-0.2.0/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: patchcraft
+Version: 0.2.0
+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
+Project-URL: Issues, https://github.com/LeoPR/PatchCraft/issues
+Project-URL: Changelog, https://github.com/LeoPR/PatchCraft/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/LeoPR/PatchCraft/blob/main/docs/USAGE.md
+Author: Leonardo Marques de Souza
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dataset,image,patches,super-resolution,torch
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: numpy>=1.26
+Requires-Dist: pillow>=10
+Requires-Dist: torch>=2.6
+Provides-Extra: cache
+Requires-Dist: zstandard>=0.22; extra == 'cache'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: torchvision>=0.20; extra == 'dev'
+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([...])`.
+
+> **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`.
+
+## 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 also **acoplável** — designed to drop into someone else's pipeline:
+
+```python
+from patchcraft import Patchify
+from torchvision import transforms
+
+transform = transforms.Compose([
+    transforms.ToTensor(),
+    transforms.GaussianBlur(kernel_size=3),
+    Patchify(patch_size=4, stride=2),   # ← PatchCraft as one step
+])
+```
+
+`Patchify` is a callable; chain it inside a `Compose`, let `DataLoader` parallelize over workers. PatchCraft gives you the primitive; the surrounding pipeline stays your code.
+
+## Visual cheat sheet
+
+The five core operations, one diagram each. Letters mark which patch each cell came from / goes to.
+
+### `extract` — image → patch stack
+
+`patch_size=4`, `stride=4` (no overlap) on an 8×8 image:
+
+```
+   image (1, 8, 8)                  patches (4, 1, 4, 4)
+   +-----------------+              +-----+  +-----+
+   | . . . . | . . . . |             |  A  |  |  B  |
+   | . A . . | . B . . |  extract    +-----+  +-----+
+   | . . . . | . . . . |  -------->   patch0   patch1
+   | . . . . | . . . . |
+   |---------+---------|             +-----+  +-----+
+   | . . . . | . . . . |             |  C  |  |  D  |
+   | . C . . | . D . . |             +-----+  +-----+
+   | . . . . | . . . . |              patch2   patch3
+   | . . . . | . . . . |             (row-major order)
+   +-----------------+
+```
+
+### `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.
+
+```
+   stride == patch  -->  count map all 1   -->  trivial copy
+   stride <  patch  -->  count map > 1     -->  weighted average
+
+   patch=4, stride=2, image cols 0..7:
+     col:    0  1  2  3  4  5  6  7
+     patch0: x  x  x  x
+     patch1:       x  x  x  x
+     patch2:             x  x  x  x
+     count:  1  1  2  2  2  2  1  1   <- divide sum by this
+```
+
+### `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.
+
+```
+   LR (1, 4, 4)               HR (1, 8, 8)
+   +---------+                +-------------+
+   | . . . . |                | . . . . . . . . |
+   | .[A]. . |   k = 1  -->   | . .[A A]. . . . |
+   | . . . . |                | . .[A A]. . . . |
+   | . . . . |                | . . . . . . . . |
+   +---------+                | . . . . . . . . |
+                              | . . . . . . . . |
+                              | . . . . . . . . |
+                              | . . . . . . . . |
+                              +-------------+
+
+   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
+
+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)
+
+   + + + +              . . . .              . o o .
+   + + + +              . X X .              o X X o
+   + + + +              . X X .              o X X o
+   + + + +              . . . .              . o o .
+
+   no seam attenuation  strong attenuation,  smooth attenuation,
+                        image corners -> 0   corners preserved
+```
+
+### Everything stays one-image-at-a-time
+
+```
+   for image in images:
+       patches = extract(image, ...)       # PatchCraft primitive
+       result  = model(patches)            # caller's work
+       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.
+
+## 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`).
+- **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(...)`.
+- **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`).
+- **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 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.
+
+## Install
+
+### From PyPI
+
+```
+pip install patchcraft            # core only
+pip install patchcraft[cache]     # adds zstandard for compressed Cache entries
+```
+
+### From source (development)
+
+```
+git clone https://github.com/LeoPR/PatchCraft.git
+cd patchcraft
+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) |
+
+## Author
+
+Leonardo Marques de Souza