metalgrow 0.1.0__tar.gz

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

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-test:
+    name: ${{ matrix.os }} / py${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-14]
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: pyproject.toml
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Create venv and install
+        run: |
+          uv venv --python ${{ matrix.python-version }}
+          uv pip install -e ".[dev]"
+
+      - name: Ruff check
+        run: .venv/bin/ruff check .
+
+      - name: Ruff format check
+        run: .venv/bin/ruff format --check .
+
+      - name: Pytest
+        run: .venv/bin/pytest -q

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

@@ -0,0 +1,106 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write  # attach artifacts to the GitHub Release
+  id-token: write  # OIDC exchange for PyPI trusted publishing
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Resolve version from tag
+        id: version
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          VERSION="${TAG#v}"
+          echo "tag=$TAG"         >> "$GITHUB_OUTPUT"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Verify tag matches pyproject version
+        run: |
+          PY_VERSION=$(python -c "import tomllib, pathlib; \
+            print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
+          if [ "$PY_VERSION" != "${{ steps.version.outputs.version }}" ]; then
+            echo "::error::tag ${{ steps.version.outputs.tag }} (version ${{ steps.version.outputs.version }}) does not match pyproject version $PY_VERSION"
+            exit 1
+          fi
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Build distributions
+        run: |
+          uv venv
+          uv pip install build
+          uv run python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # Scoped environment lets PyPI's trusted-publisher config pin this job.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/metalgrow
+    permissions:
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Attach artifacts to GitHub Release
+    needs: [build, publish-pypi]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create or update GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            gh release upload "$TAG" dist/* --clobber
+          else
+            gh release create "$TAG" dist/* \
+              --title "$TAG" \
+              --generate-notes
+          fi

metalgrow-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.DS_Store
+*.pt
+*.pth
+*.safetensors
+models/
+out/
+.claude

metalgrow-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

metalgrow-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

metalgrow-0.1.0/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[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-04-13
+
+First public release. Everything below is an introduction rather than a diff
+against a prior version.
+
+### Added
+
+- **Core pipeline.** `Upscaler` class (public API), a single `torch.device`
+  selector (`auto → mps → cuda → cpu`), and a `typer` CLI with `upscale`,
+  `info`, and `models {list,download,rm}` commands.
+- **Backbones.** Pluggable registry behind a `Backbone` ABC. Ships with
+  `bicubic` (analytical, weightless), Real-ESRGAN (`realesrgan-x2`,
+  `realesrgan-x4`), and SwinIR (`swinir-x2`, `swinir-x4`). Learned backbones
+  route through [spandrel](https://github.com/chaiNNer-org/spandrel).
+- **Tiled inference.** `Upscaler._tiled_forward` with feathered overlap
+  blending, auto-triggered when either image dimension exceeds the
+  backbone's `default_tile`. Backbones declare tile geometry; the control
+  flow is shared.
+- **Batch mode.** `metalgrow upscale SRC DST` accepts a directory or glob
+  and writes mirrored filenames into `DST` with `--skip-existing` and
+  parallel I/O workers. Inference stays serial on the device.
+- **Model registry.** `metalgrow.weights` caches weights under
+  `~/.cache/metalgrow/` (overridable via `METALGROW_CACHE_DIR`) with
+  sha256 verification on every call; corrupt files are removed so a retry
+  can re-download. `metalgrow models` inspects and manages the cache.
+- **Alpha handling.** `Upscaler` runs RGB-only backbones on the RGB plane
+  and bicubic-upscales the alpha channel in parallel, then recombines —
+  preserving transparency without corrupting it.
+- **MPS ergonomics.** Automatic `PYTORCH_ENABLE_MPS_FALLBACK=1` so missing
+  ops fall back to CPU silently instead of aborting; opt out with
+  `METALGROW_DISABLE_MPS_FALLBACK=1`.
+- **Benchmarks.** Reproducible harness at `benchmarks/run.py` driven by
+  seeded synthetic fixtures, with device-aware peak-memory reporting and
+  markdown / JSON output. Not part of CI.
+- **Release automation.** Tag-triggered workflow builds sdist + wheel,
+  publishes to PyPI via trusted publishing (OIDC), and attaches artifacts
+  to a GitHub Release. See [`docs/releasing.md`](docs/releasing.md).
+- **Docs.** Usage guide (CLI + library), model comparison with benchmark
+  numbers, full benchmark tables, architecture overview, and release
+  process. See [`docs/README.md`](docs/README.md).
+- **CI.** Lint (ruff) + test (pytest) matrix on macOS and Linux,
+  Python 3.11 + 3.12.
+
+### Known limitations
+
+- CUDA benchmark numbers are not yet populated — GitHub-hosted runners
+  don't expose GPUs. Run `benchmarks/run.py` on any CUDA-enabled machine
+  and append to [`docs/benchmarks.md`](docs/benchmarks.md).
+- SwinIR on MPS is only ~2× faster than CPU at these sizes: several
+  attention-adjacent ops fall back to CPU via the MPS fallback. Tracked
+  as a quality-of-life issue against upstream torch.
+- Peak memory on MPS is measured as the high-water mark of
+  `driver_allocated_memory`, which includes allocator pool reservations —
+  interpret it as "working set size", not a strict activation peak.
+
+[Unreleased]: https://github.com/joaodotwork/metalgrow/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/joaodotwork/metalgrow/releases/tag/v0.1.0

metalgrow-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,86 @@
+# Contributing to metalgrow
+
+Thanks for your interest in contributing! This guide covers the local setup
+and the conventions we follow.
+
+## Dev setup
+
+We use [`uv`](https://docs.astral.sh/uv/) but plain `pip` also works.
+
+```bash
+git clone https://github.com/joaodotwork/metalgrow.git
+cd metalgrow
+
+# uv
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+
+# or plain pip
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Install the pre-commit hooks once per clone:
+
+```bash
+pre-commit install
+```
+
+This runs `ruff` and `ruff-format` on every commit. The same checks run in
+CI, so installing the hook saves a round trip.
+
+## Running tests and lint
+
+```bash
+pytest               # full test suite (CPU only, no weights required)
+ruff check .         # lint
+ruff format .        # auto-format
+ruff format --check . # CI-equivalent format check
+```
+
+The test suite is intentionally CPU-only so it passes on any machine and on
+Linux CI runners without Apple Silicon.
+
+## Branch and PR conventions
+
+- Branch from `main`. Name branches by intent: `feat/...`, `fix/...`,
+  `chore/...`, `docs/...`, `test/...`.
+- Keep commits focused. Prefer one commit per issue when a branch closes
+  multiple issues; otherwise group related changes.
+- Commit subject line uses the same conventional prefix (`feat:`, `fix:`,
+  `chore:`, `docs:`, `test:`, `ci:`) followed by a short imperative summary.
+- Reference the issue in the commit body with `Closes #N`.
+- Before opening a PR: `ruff check .`, `ruff format --check .`, and
+  `pytest` must all pass. CI will re-run them on macOS and Linux.
+
+## Adding a new backbone
+
+The public API (`Upscaler`, CLI flags) is stable. New super-resolution
+models plug in behind it. See
+[`docs/architecture.md`](docs/architecture.md#plugging-in-a-learned-backbone)
+for the expected shape of that change — briefly:
+
+1. Add `src/metalgrow/backbones/<name>.py` exposing a `load_model(device)`
+   that returns an `nn.Module` in `eval()` mode.
+2. Load the backbone lazily in `Upscaler.__init__` so `metalgrow info` and
+   unit tests stay fast.
+3. Replace the `F.interpolate` call in `Upscaler.upscale` with the model
+   forward pass. Pre/post-processing belongs on the backbone, not on
+   `Upscaler`.
+
+Weights must not be committed; a model registry is planned (see the M3
+milestone).
+
+## Cutting a release
+
+Releases are fully automated: tag `vX.Y.Z` on `main`, push, and the
+`release.yml` workflow builds, publishes to PyPI (trusted publishing), and
+attaches the artifacts to a GitHub Release. See
+[`docs/releasing.md`](docs/releasing.md) for the full process — including
+the one-time PyPI publisher setup required before the first release.
+
+## Reporting issues
+
+Bugs, questions, and feature requests are all welcome on the
+[issue tracker](https://github.com/joaodotwork/metalgrow/issues). Include
+your OS, Python version, and the output of `metalgrow info` when relevant.

metalgrow-0.1.0/LICENSE

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

metalgrow-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: metalgrow
+Version: 0.1.0
+Summary: AI-powered image upscaler accelerated on Apple Metal (MPS).
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: pillow>=10.0
+Requires-Dist: spandrel>=0.4
+Requires-Dist: torch>=2.3
+Requires-Dist: torchvision>=0.18
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'

metalgrow-0.1.0/README.md

@@ -0,0 +1,163 @@
+# metalgrow
+
+> AI-powered image upscaler accelerated on Apple Metal (MPS).
+
+[![CI](https://github.com/joaodotwork/metalgrow/actions/workflows/ci.yml/badge.svg)](https://github.com/joaodotwork/metalgrow/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![PyTorch](https://img.shields.io/badge/PyTorch-2.3%2B-ee4c2c.svg?logo=pytorch&logoColor=white)](https://pytorch.org/)
+[![Apple Silicon](https://img.shields.io/badge/Apple%20Silicon-MPS-000000.svg?logo=apple&logoColor=white)](https://developer.apple.com/metal/pytorch/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Status](https://img.shields.io/badge/status-alpha-orange.svg)](#roadmap)
+[![Ruff](https://img.shields.io/badge/lint-ruff-261230.svg)](https://github.com/astral-sh/ruff)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#contributing)
+
+`metalgrow` runs super-resolution on Apple Silicon GPUs through PyTorch's MPS
+backend, with graceful fallbacks to CUDA and CPU. It ships with a bicubic
+baseline so the pipeline is runnable end-to-end, and exposes a clean seam for
+plugging in a learned backbone (Real-ESRGAN, SwinIR, etc.).
+
+---
+
+## Table of contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Install](#install)
+- [Usage](#usage)
+- [Project layout](#project-layout)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+- 🍎 **Apple Metal first** — PyTorch MPS backend, zero config on Apple Silicon
+- 🔁 **Portable** — automatic fallback to CUDA / CPU when MPS isn't available
+- 🧩 **Pluggable backbones** — bicubic, Real-ESRGAN (x2/x4), SwinIR (x2/x4)
+- 🧱 **Tiled inference** — process arbitrarily large images with feathered overlap blending
+- 📂 **Batch mode** — upscale whole directories or globs with a progress bar
+- 📦 **Model registry** — `metalgrow models` manages cached weights with sha256 verification
+- 🧪 **Tested** — pytest suite covering the CPU baseline, tiling, batch mode, and registry
+
+## Requirements
+
+- Python **3.11+**
+- macOS with Apple Silicon for MPS acceleration (optional — CPU/CUDA also work)
+
+## Install
+
+```bash
+git clone https://github.com/joaodotwork/metalgrow.git
+cd metalgrow
+uv venv && source .venv/bin/activate
+uv pip install -e .
+```
+
+Or with plain pip:
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+```
+
+## Usage
+
+### CLI
+
+Single file:
+
+```bash
+metalgrow info
+metalgrow upscale input.jpg out.png --scale 2
+metalgrow upscale input.jpg out.png --scale 4 --device mps --backbone realesrgan-x4
+```
+
+Whole directory or glob (writes to a target directory, mirroring filenames):
+
+```bash
+metalgrow upscale ./photos ./photos-upscaled --scale 2 --backbone realesrgan-x2
+metalgrow upscale "./photos/*.png" ./out --scale 2 --skip-existing
+```
+
+| Flag                  | Default       | Description                                                     |
+| --------------------- | ------------- | --------------------------------------------------------------- |
+| `--scale`, `-s`       | `2.0`         | Upscale factor (1.01–8.0)                                       |
+| `--device`, `-d`      | `auto`        | `auto` \| `mps` \| `cuda` \| `cpu`                              |
+| `--backbone`, `-b`    | `bicubic`     | `bicubic` \| `realesrgan-x{2,4}` \| `swinir-x{2,4}`             |
+| `--dtype`             | `fp32`        | `fp32` \| `fp16` (fp16 is MPS-only and noisier)                 |
+| `--tile`              | backbone hint | Tile size in input px for tiled inference (`0` disables)        |
+| `--tile-pad`          | backbone hint | Context padding per tile edge (covers backbone receptive field) |
+| `--skip-existing`     | off           | Batch mode: skip outputs that already exist                     |
+| `--workers`, `-j`     | `4`           | Batch mode: parallel I/O workers (inference stays serial)       |
+
+#### Manage cached model weights
+
+```bash
+metalgrow models list
+metalgrow models download realesrgan-x4
+metalgrow models rm realesrgan-x4
+```
+
+Weights cache to `~/.cache/metalgrow/` by default; override with the
+`METALGROW_CACHE_DIR` env var. Every download is sha256-verified.
+
+See [`docs/models.md`](./docs/models.md) for a quality / speed / memory
+comparison (with benchmark numbers) and guidance on which backbone to pick,
+or [`docs/usage.md`](./docs/usage.md) for the full CLI / library reference.
+
+### Library
+
+```python
+from PIL import Image
+from metalgrow import Upscaler
+
+upscaler = Upscaler(backbone="realesrgan-x2", device="auto")  # auto | mps | cuda | cpu
+result = upscaler.upscale(
+    Image.open("input.jpg").convert("RGB"),
+    scale=2.0,
+    tile=256,        # optional — backbone has sensible defaults
+    tile_pad=16,
+)
+result.save("out.png")
+```
+
+## Project layout
+
+```
+src/metalgrow/
+  device.py            # device auto-selection (MPS → CUDA → CPU)
+  upscaler.py          # Upscaler class + tiled inference with overlap blending
+  batch.py             # directory / glob batch mode
+  weights.py           # weight registry, sha256 verification, cache management
+  cli.py               # typer CLI (upscale, info, models)
+  backbones/           # bicubic, realesrgan, swinir; plugin registry
+tests/
+docs/
+  usage.md             # CLI recipes, library API, env vars, pitfalls
+  models.md            # backbone comparison, benchmark snapshot, tiling
+  benchmarks.md        # full (device × backbone × scale) tables
+  architecture.md      # module layout, data flow, extension points
+```
+
+## Roadmap
+
+- [x] Integrate a learned SR backbone (Real-ESRGAN default)
+- [x] Tiled inference for large images
+- [x] Batch / directory mode
+- [x] Model registry + weight download
+- [x] Second backbone family (SwinIR)
+- [x] GitHub Actions CI (lint + test on macOS + Linux)
+- [x] Benchmarks: MPS vs CPU (CUDA pending GPU runner)
+- [ ] v0.1.0 release
+
+## Contributing
+
+Issues and PRs are welcome. Please run `ruff` and `pytest` before opening a PR.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+<sub>Made with 🔩 on Apple Silicon.</sub>

metalgrow-0.1.0/benchmarks/README.md

@@ -0,0 +1,52 @@
+# Benchmarks
+
+Reproducible benchmark harness for metalgrow backbones.
+
+## Running locally
+
+```bash
+# All backbones × scales on the auto-selected device, skip uncached weights
+python -m benchmarks.run --skip-uncached
+
+# Pin to CPU (works everywhere, useful for contributor machines)
+python -m benchmarks.run --device cpu --backbones bicubic --scales 2,4
+
+# Write a markdown fragment into the docs
+python -m benchmarks.run --device auto --output docs/benchmarks.md
+```
+
+### Inputs
+
+The runner generates synthetic RGB noise with a fixed seed (`SEED = 0`). No
+fixtures are downloaded and the exact same pixel data is produced on every
+machine, so results are only shaped by device + backbone + scale + size —
+not by which image was handy.
+
+### Metrics
+
+- **Median (s)** — wall time of the median iteration, after `--warmup` iters.
+- **MP/s** — output megapixels per second = `out_w * out_h / median_s`.
+- **Peak (MiB)** — device-side peak allocation during the measured run:
+  - `cuda`: `torch.cuda.max_memory_allocated()` after `reset_peak_memory_stats()`
+  - `mps`: high-water of `torch.mps.driver_allocated_memory()` from before the
+    `Upscaler` is constructed, so the number covers weights + activations.
+    The MPS allocator pool does **not** shrink between cells inside one
+    process, so only the *first* cell per run reports a truthful peak —
+    later cells reuse the already-sized pool and can report 0. To get
+    per-backbone peaks, invoke the runner once per backbone (see
+    `docs/models.md` for the per-backbone numbers).
+  - `cpu`: not reported (no reliable device-side counter; RSS deltas are noisy).
+
+## CUDA numbers
+
+GitHub's hosted runners don't have GPUs, so CUDA rows are produced on a
+CUDA-enabled runner (cloud or self-hosted) via `workflow_dispatch`. The
+rendered markdown is committed under `docs/benchmarks.md`; JSON output can
+be combined across devices with any script that concatenates `results[]`.
+
+## Not part of CI
+
+This harness intentionally lives outside `tests/` — it is **not** executed
+on push/PR. A long-running benchmark in CI produces flaky numbers (noisy
+neighbours, runner variability) and blocks contributor workflows. Run it
+manually when weights, backbones, or kernels change.