bulk-bg-remove 0.1.0__tar.gz

bulk_bg_remove-0.1.0/.agents/plugins/marketplace.json

@@ -0,0 +1,21 @@
+{
+  "name": "bulk-bg-remove",
+  "interface": {
+    "displayName": "Bulk BG Remove"
+  },
+  "plugins": [
+    {
+      "name": "bulk-bg-remove",
+      "source": {
+        "source": "url",
+        "url": "https://github.com/Btike/bulk-bg-remove.git",
+        "ref": "main"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

bulk_bg_remove-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "bulk-bg-remove",
+  "description": "Remove image backgrounds locally and in bulk. No uploads, no API keys.",
+  "owner": {
+    "name": "Btike",
+    "url": "https://github.com/Btike"
+  },
+  "plugins": [
+    {
+      "name": "bulk-bg-remove",
+      "description": "Cut out every photo in a folder with BiRefNet, on your own machine. Lossless transparent PNG/WebP, originals untouched.",
+      "source": "./",
+      "category": "productivity"
+    }
+  ]
+}

bulk_bg_remove-0.1.0/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "bulk-bg-remove",
+  "version": "0.1.0",
+  "description": "Remove image backgrounds locally and in bulk: one photo or whole folders, with BiRefNet. No uploads, no API keys, originals untouched.",
+  "author": {
+    "name": "Btike",
+    "url": "https://github.com/Btike"
+  },
+  "homepage": "https://github.com/Btike/bulk-bg-remove",
+  "repository": "https://github.com/Btike/bulk-bg-remove",
+  "license": "MIT",
+  "keywords": ["background-removal", "remove-background", "transparent-png", "birefnet", "bulk", "images"]
+}

bulk_bg_remove-0.1.0/.codex-plugin/plugin.json

@@ -0,0 +1,29 @@
+{
+  "name": "bulk-bg-remove",
+  "version": "0.1.0",
+  "description": "Remove image backgrounds locally and in bulk: one photo or whole folders, with BiRefNet. No uploads, no API keys, originals untouched.",
+  "author": {
+    "name": "Btike",
+    "url": "https://github.com/Btike"
+  },
+  "homepage": "https://github.com/Btike/bulk-bg-remove",
+  "repository": "https://github.com/Btike/bulk-bg-remove",
+  "license": "MIT",
+  "keywords": ["background-removal", "remove-background", "transparent-png", "birefnet", "bulk", "images"],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Bulk BG Remove",
+    "shortDescription": "Remove image backgrounds locally, in bulk",
+    "longDescription": "Cut out the subject of one photo or whole folders on your own machine with BiRefNet. Lossless transparent PNG or WebP in a new <name>-no-bg folder; originals are never touched.",
+    "developerName": "Btike",
+    "category": "Productivity",
+    "capabilities": ["Instructions"],
+    "websiteURL": "https://github.com/Btike/bulk-bg-remove",
+    "defaultPrompt": [
+      "Remove the background from every photo in this folder.",
+      "Make a transparent PNG of this product photo.",
+      "Cut out the people in these HEIC photos."
+    ],
+    "brandColor": "#0d1117"
+  }
+}

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

@@ -0,0 +1,32 @@
+# Hosted CI for when the repo is public (public repos get free Actions minutes).
+# While the repo is private every job is skipped, so it uses no minutes:
+# run scripts/ci.sh locally instead.
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:  # run it by hand from the Actions tab
+
+jobs:
+  test:
+    if: ${{ !github.event.repository.private }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv lock --check
+      - run: uv run --locked ruff check .
+      - run: uv run --locked ruff format --check .
+      - run: uv run --locked mypy
+      - run: uv run --locked pytest -q
+        env:
+          BULK_BG_REMOVE_REAL_MODEL: "1"  # also run the real-model smoke test

bulk_bg_remove-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Env / secrets — never commit
+.env
+.env.local
+*.key
+
+# Local runtime output and test images
+storage/
+*-no-bg/
+.playwright-mcp/
+
+# Downloaded model weights
+*.onnx
+.u2net/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local CI environments and builds
+.ci/

bulk_bg_remove-0.1.0/.python-version

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

bulk_bg_remove-0.1.0/AGENTS.md

@@ -0,0 +1,105 @@
+# AGENTS.md — bulk-bg-remove
+
+Remove image backgrounds in bulk, 100% locally, without touching a single subject
+pixel. One engine, two entry points: a CLI/agent mode and a local drag-and-drop UI.
+
+> Status: v0.1 under construction. Sections marked _(planned)_ do not exist yet.
+
+## Stack
+- **Python 3.11–3.13**, managed by **uv** (`.python-version` pins 3.12 for development)
+- **rembg** (ONNX Runtime) with **BiRefNet** (MIT) — default model `birefnet-general-lite`
+- **Pillow + numpy** — imaging; **pillow-heif** for HEIC/HEIF; **pymatting + scipy** — edge matting
+- **FastAPI + Uvicorn** — local UI server
+- **rich** — terminal logs · **psutil** — capacity probes
+- **pytest · ruff · mypy (strict)** — quality gates
+
+## Commands
+- Install / sync: `uv sync`
+- Tests: `uv run pytest`
+- Lint: `uv run ruff check . && uv run ruff format --check .`
+- Typecheck: `uv run mypy`
+- Run: `uv run bulk-bg-remove PATH [--profile KIND] [--yes] [--json] [--clean-edges|--fast-edges]`
+  (`--model` defaults to `auto`; `--sample-sheet` with `--dry-run` writes a contact sheet)
+- Check a machine: `uv run bulk-bg-remove doctor [--json]`
+- **CI runs locally**: `scripts/ci.sh` (lock, ruff, mypy, tests on Python 3.11–3.13, wheel
+  build, plugin manifests); `--quick` for lint, types and tests only; `--linux` adds the suite
+  on Linux x86_64 in Docker with the real-model smoke test (~10 min, emulated: run it before a
+  merge or release). Hosted CI (`.github/workflows/ci.yml`, Linux/macOS/Windows) is skipped
+  while the repo is private. Run the full script before every commit.
+- Linux arm64 VMs on Apple M4/M5 (Docker, UTM, Lima) advertise SVE the chip cannot run:
+  numba and ONNX Runtime die with SIGILL there. Test Linux as x86_64; the runner reports a
+  SIGILL crash in plain words (`crash_reason` in `bulk/runner.py`).
+
+## Structure
+- `src/bulk_bg_remove/core/` — pure image logic: `io.py`, `matting.py`, `compositing.py`,
+  `finish.py` (opt-in shop finishing), `pipeline.py`.
+  No CLI/UI/runner imports.
+- `src/bulk_bg_remove/engine/model.py` — rembg session wrapper (load once per worker, reuse).
+- `src/bulk_bg_remove/domain.py` — shared domain types.
+- `src/bulk_bg_remove/bulk/` — the four phases: scan → plan → run → verify, plus `session.py`
+  (shared by CLI and UI), `events.py` (the JSON event contract), `models.py` (`--model auto`:
+  per-profile scores from the blind-judged bench) and `sample.py` (contact sheet for agents)
+- `src/bulk_bg_remove/ui/` — local server + single-file page
+- `skills/bulk-bg-remove/` — the agent skill (`SKILL.md` + `references/`); plugin manifests in
+  `.claude-plugin/`, `.codex-plugin/` and `.agents/plugins/`. The `--json` event contract is
+  documented in `references/json-events.md`: update it with any event change.
+- `tests/` — unit tests for pure logic, integration tests with a fake model, and one
+  real-model smoke test (`test_real_model.py`, `silueta`, 43 MB download) that runs only with
+  `BULK_BG_REMOVE_REAL_MODEL=1` — set by `scripts/ci.sh --linux` and in hosted CI on
+  Linux, macOS and Windows.
+
+## Quality contract (do not break)
+- NEVER resample or re-encode the subject's RGB. Only the alpha mask is resized
+  (Lanczos); compositing copies RGB verbatim — see `core/compositing.py`. The one
+  opt-in exception is `--clean-edges`, which recolours semi-transparent edge pixels only.
+- Output keeps the exact input dimensions. PNG is always lossless; WebP uses
+  `lossless=True, exact=True`.
+- The other opt-in exception is finishing (`core/finish.py`: `--background`, `--square`,
+  `--pad`, `--size`, `--shop`): it blends edge pixels onto a colour, crops, resamples or
+  writes JPEG only when asked. Review sheets keep judging the transparent cut-out (a
+  preview saved before finishing), never the finished image.
+- Originals are never modified, moved or deleted. Output always goes to a new
+  `<name>-no-bg/` folder.
+
+## Conventions
+- Strict typing (mypy strict, no `Any` escape hatches), frozen dataclasses, named exports.
+- English only: code, comments, docs, UI copy, terminal output.
+- Minimal dependencies — justify every new one.
+- New logic ships with tests: unit for pure logic, integration for runner/CLI/UI.
+- Conventional Commits on feature branches; never commit to `main` directly.
+
+## Gotchas
+- `bulk/models.py` scores come from `scripts/bench.py` plus blind vision judging (see
+  `references/models.md`). Re-run both before changing a score or adding a model; every
+  ranked model needs a measured entry in `MODEL_PEAK_GB`.
+- rembg downloads model weights on first use to `~/.u2net/` (needs network once, ~224 MB).
+- RAM is the real limit. Measured peak per worker without matting (CPU, tuned session):
+  `birefnet-general-lite` 9.4 GB · other BiRefNet variants 11.6 · `isnet-general-use` 2.4 ·
+  `u2net` 1.8 · `silueta` 0.7 (all 11 in `bulk/plan.py`). Nearly constant per model: each
+  model infers at a fixed size whatever the photo size.
+- Edge matting adds ~0.35 GB per matted MP plus ~2.3 GB per million uncertain-band pixels
+  (a 4 MP wire chair: 4.9 GB; a product shot: 1.8 GB). `core/matting.py` shrinks the matting
+  resolution to fit a budget the worker sets from free RAM (0.6–3 GB), re-measuring after each
+  step (the eroded band shrinks slower than the area). Scaling the matte back to full
+  resolution costs ~0.03 GB/MP more (~0.065 with `--clean-edges`), outside that budget. The
+  start floor counts 0.6 GB of matting (lite: ~12 GB for 12 MP photos); parallel sizing, 3 GB.
+- A long-lived worker's RSS creeps to ~3x one image's peak (heap fragmentation from images
+  of different sizes; `gc` and malloc pressure relief do not help). Workers restart when RSS
+  ends an image more than 1 GB above the model's peak (`recycle_above_gb`). Measured on the
+  edge-heavy bench: lite 15.7 → 12.3 GB, silueta 9.1 → 3.9 GB. They only restart while free RAM
+  is below reserve + full matting + margin (~5.5 GB): a reload costs ~2 s per image.
+- Worker stdout goes to devnull: pymatting prints harmless "incomplete Cholesky" warnings there.
+- On CPU a second worker adds only ~25% throughput (ONNX already uses every core);
+  more workers are slower. `OMP_NUM_THREADS` sets intra-op threads per worker.
+- `rembg.remove(..., only_mask=True)` silently ignores `alpha_matting`. Edge matting is
+  done by `core/matting.py` instead — never pass matting flags to rembg.
+- Matting runs at ≤ 4 MP; sure foreground/background come from the full-resolution
+  mask. Keep the trimap erosion separable (row pass + column pass): a square
+  structure is ~40× slower on large photos.
+- CoreML is listed by onnxruntime on macOS but BiRefNet does not compile to it; treat
+  it as CPU.
+- 16-bit greyscale must be scaled, not converted: Pillow's `I;16 -> RGB` clips to white.
+- Bench: results in `BENCHMARK.md` + `benchmark/` (scores, image credits; photos stay out of
+  git). `scripts/bench.py INPUT RESULTS [--model M ...]` writes
+  before/after sheets, time per image and peak RAM; `scripts/bench_grids.py` makes blind
+  grids (models as letters) and close-ups for judging.

bulk_bg_remove-0.1.0/BENCHMARK.md

@@ -0,0 +1,202 @@
+# Benchmark
+
+How well each background-removal model works, how fast it is and how much RAM
+it needs, measured on 80 hard images and judged blind. These numbers drive
+`--model auto` and the skill's model guide.
+
+**In short**
+
+- The default, `birefnet-general-lite`, scores **7.9/10** overall, against 8.0 for
+  `birefnet-general`, at **3.2 s per product photo** against 5.6 s.
+- On 35 real product catalogue photos it scores **8.6/10**, the best of the 11
+  models, and never 3 or less.
+- With **3.4 GB of free RAM**, `silueta` still scores 8.1 on clean product shots.
+  On hair, fur and plants the light models drop to ~5 against 7.6, so the skill
+  asks before using one.
+- The cut-out reviewer flags **8 of 9** cut-outs the judges scored 5 or less.
+
+## Setup
+
+- **Machine:** Apple M5 (4 performance cores), 34 GB RAM, CPU only (ONNX Runtime).
+- **Engine:** `bulk-bg-remove` 0.1.0, one worker, edge matting on (the default),
+  everything else at defaults. Times are per image and include matting.
+- **Models:** the 11 local models rembg ships with permissive licences.
+  Excluded: `bria-rmbg` (non-commercial licence), `withoutbg` and `atlascloud`
+  (cloud APIs, not local), `birefnet-general-fp16` (needs extra packages),
+  `birefnet-cod` (camouflage research model), `sam` (needs prompts).
+
+## Images (80 judged)
+
+| Set | Images | What it tests |
+|---|---|---|
+| edges | 10 | hair, fur, wire, bristles, branches, a dandelion |
+| materials | 8 | glass, chrome, black on black, white on white, hard shadows |
+| composition | 9 | groups, crowds, a logo, a cartoon, a shelf, a landscape with no subject |
+| formats | 18 | HEIC, AVIF, WebP, TIFF, BMP, CMYK, 16-bit grey, palette PNG, ICC, EXIF rotation, a wrong extension, existing alpha, 180 px, 45 MP, a 5:1 panorama |
+| catalogue | 35 | real product catalogue photos (cleaning products, mostly on white) |
+
+The 27 photos in the first three sets, and the sources of the 45 MP,
+panorama and portrait format tests, are public (CC0, CC BY, CC BY-SA or public
+domain, from Wikimedia Commons); authors, licences and links are in
+[`benchmark/images.csv`](benchmark/images.csv). The catalogue photos belong to
+a company and are not redistributed; they appear as `catalogue-NN`, and the
+other 14 format tests were made from them.
+
+## Judging
+
+Each image got one comparison grid: the original plus the 11 cut-outs on a
+checkerboard, labelled A–K in a fixed shuffled order, so the judge could not
+tell which model made which cut-out. The judge, a vision model (Claude), also
+looked at full-resolution crops of the hardest regions, on black, white and
+checkerboard. Every image was zoomed into.
+
+Scores are 0–10 for how usable the cut-out is as a professional product or
+portrait asset: **10** clean, complete subject, fine edges kept, no background
+left · **7** small fixable flaws · **4** visible flaws (halo, chunks of
+background, missing parts) · **1** unusable · **0** empty.
+
+Every score, with the image's content tags, is in
+[`benchmark/scores.csv`](benchmark/scores.csv).
+
+## Results
+
+Mean score per set (0–10), images scored 3 or less, speed and RAM. RAM is the
+model alone and the free RAM the planner asks for before a run on 12 MP photos
+(model, image buffers, edge matting and a 1.5 GB reserve).
+
+| Model | All (80) | edges (10) | materials (8) | composition (9) | formats (18) | catalogue (35) | ≤ 3 | s/img catalogue | s/img edges | Model RAM | Free RAM needed |
+|---|---|---|---|---|---|---|---|---|---|---|---|
+| `birefnet-general` | **8.0** | 7.0 | 7.8 | 6.8 | 8.4 | 8.4 | 1 | 5.6 | 9.6 | 11.6 GB | 14.3 GB |
+| `birefnet-general-lite` (default) | **7.9** | 6.2 | 7.6 | 6.6 | 8.3 | 8.6 | 2 | 3.2 | 6.5 | 9.4 GB | 12.1 GB |
+| `birefnet-hrsod` | **7.7** | 6.4 | 7.4 | 6.6 | 8.1 | 8.3 | 3 | 5.6 | 9.7 | 11.6 GB | 14.3 GB |
+| `birefnet-massive` | **7.6** | 5.3 | 7.0 | 6.0 | 8.3 | 8.5 | 4 | 5.6 | 9.0 | 11.6 GB | 14.3 GB |
+| `birefnet-dis` | **7.5** | 5.5 | 7.2 | 5.7 | 7.9 | 8.4 | 4 | 5.5 | 7.9 | 11.6 GB | 14.3 GB |
+| `isnet-general-use` | **6.7** | 5.2 | 5.4 | 3.6 | 7.9 | 7.6 | 11 | 1.3 | 7.8 | 2.4 GB | 5.1 GB |
+| `silueta` | **6.6** | 4.5 | 5.1 | 4.1 | 7.8 | 7.5 | 11 | 0.4 | 6.1 | 0.7 GB | 3.4 GB |
+| `u2net` | **6.5** | 4.4 | 5.6 | 4.2 | 7.8 | 7.3 | 8 | 0.5 | 3.3 | 1.8 GB | 4.5 GB |
+| `birefnet-portrait` | **6.5** | 5.6 | 3.5 | 4.0 | 7.7 | 7.4 | 15 | 5.5 | 12.4 | 11.6 GB | 14.3 GB |
+| `u2net_human_seg` | **4.6** | 3.2 | 2.8 | 3.1 | 7.0 | 4.5 | 37 | 0.8 | 3.2 | 1.8 GB | 4.5 GB |
+| `isnet-anime` | **2.2** | 0.5 | 2.0 | 2.2 | 1.4 | 3.1 | 64 | 1.2 | 1.3 | 2.2 GB | 4.9 GB |
+
+All 11 models processed all 82 files with no failures (two catalogue files
+sharing a name were timed but not judged).
+
+### By kind of image (what `--model auto` uses)
+
+Images grouped by their content tags into the profiles an agent picks from.
+`auto` takes the highest score that fits in free RAM, and asks before using a
+model more than 0.5 points below the best.
+
+| Profile | n | Best | Next | Light models (~3.5–5 GB free) |
+|---|---|---|---|---|
+| `uniform` — products, objects | 39 | lite 8.6 · general 8.6 | hrsod 8.5 · massive 8.5 | u2net 8.1 · silueta 8.1 · isnet 7.7 |
+| `complex` — hair, fur, plants, thin parts | 32 | general 7.6 | lite 7.4 · hrsod 7.3 | isnet 6.0 · silueta 5.2 · u2net 5.2 |
+| `people` | 8 | general 7.8 | dis 7.4 · massive 7.2 | u2net 6.0 · silueta 5.8 · isnet 5.2 |
+| `scene` — cluttered | 6 | general 6.3 | hrsod 5.7 | u2net 4.0 · silueta 4.0 · isnet 3.7 |
+| `drawing` | 1 | isnet-anime 9.0 | lite 8.0 | — |
+
+## RAM
+
+Peak resident memory of a worker on the edge-heavy set, before and after
+bounding edge matting and restarting workers whose heap had grown (both in
+v0.1.0):
+
+| Model | Before | After | Planner's figure |
+|---|---|---|---|
+| `birefnet-general-lite` | 15.7 GB | 12.3 GB | 12.6 GB |
+| `birefnet-general` | 17.5 GB | 14.4 GB | 14.8 GB |
+| `silueta` | 9.1 GB | 3.9 GB | 3.9 GB |
+| `u2net` | 9.3 GB | 5.1 GB | 5.0 GB |
+
+Edge matting costs ~0.35 GB per matted megapixel plus ~2.3 GB per million
+pixels in the uncertain band, so a wire chair needs far more than a bottle.
+18 of the 20 re-checked cut-outs came out pixel-identical after the change.
+
+## The cut-out reviewer
+
+Three reviewers (the skill's `bg-reviewer` guide, nothing else) looked at the
+62 default-model cut-outs of the edges, materials, composition and catalogue
+sets, without the judges' scores.
+
+| | |
+|---|---|
+| Bad cut-outs (judge score ≤ 5) flagged | **8 of 9** |
+| Good cut-outs (≥ 8) flagged | 5 of 45 (2 only for `--clean-edges`) |
+| Proposed fixes that the judges score higher | 5 of 11 measurable (e.g. 5 → 8 on long fur, plants, curly hair) |
+| …the same | 3 |
+| …1 point lower | 3, all on cut-outs already ≥ 7 |
+
+Because a second pass can make a good cut-out worse, the skill runs fixes into
+a separate folder and keeps the new cut-out only when the reviewer judges it
+better.
+
+## End-to-end: a fresh agent, no context
+
+A new Claude Code session, with only the plugin installed and no other
+context, got one request: *"use the bulk-bg-remove skill to remove the
+background from every photo in this folder"*, on a 248-image test folder (the
+benchmark sets plus 151 catalogue photos and a deliberately messy folder). It
+was allowed to run the engine and to copy files, nothing else.
+
+- It installed the engine, looked at the sample sheet, picked `uniform` for the
+  folder and ran it in the background: **247 of 248 done**; the one failure was
+  a truncated file, reported as damaged. Non-images, a GIF, a hidden file and an
+  earlier output folder were listed as skipped, each with its reason.
+- It split 21 review sheets across **4 `bg-reviewer` subagents** in parallel,
+  redid the flagged images in a side folder, had a fresh reviewer compare old
+  and new, and kept the new version for 4 of them (a handler's arm gone from a
+  dog, a wine glass stem recovered, a cutter tip and a jug shoulder restored).
+- It reported what it could not fix (a colour tint on a dandelion and a plant,
+  two see-through metal handles) and what the user should decide (placeholder
+  "no photo" images, scenes with no clear subject, a 180 px original).
+
+What it surfaced, and what changed since: agent file readers ignore
+transparency and show the original background in the output PNG, so
+reviewers now get flattened close-ups on black and white (`zoom`); and fixes
+now go to a `<name>-retry-no-bg` folder next to the output instead of `/tmp`,
+which needed extra approval to copy from.
+
+A second fresh session with those fixes, from a clean install, did the same
+job with close-ups: **5 reviewers**, 214 cut-outs fine, 20 redone in one
+round with four different fixes (`--profile complex`, `--model
+birefnet-general`, `--clean-edges`, `--model birefnet-portrait`), **8 kept**
+because they were clearly better (long fur, curly and loose hair, a cat, a
+wine glass, three catalogue products), 12 kept as they were and reported.
+Every redone file differed from the first pass; none was copied over without
+a reviewer's `keep: new`.
+
+A third fresh session tested the shop flow from a clean install. The only
+request was *"use the bulk-bg-remove skill to remove the background from every
+photo in this folder; they are for my online store"*. It picked `--shop` on its
+own and processed **247 of 248**: every output was a 2000×2000 white JPEG
+carrying the `--shop` finish in its metadata. Five reviewers found 17 to
+redo. The agent redid them with the same finishing flags and kept **9** that
+were clearly better. In its report it listed the 5 that a second pass did not
+fix, the placeholders and scenes that do not belong in a shop, and the small
+originals that `--size 2000` had to enlarge, offering `--size 1000` as an
+option. The whole session cost about $5.70 in model usage, most of it for
+looking at review close-ups.
+
+## Caveats
+
+- One judge (a vision model) per image, no second opinion: read gaps under
+  ~0.5 points as ties.
+- Small samples behind some rows: `drawing` has 1 image, `scene` 6, `people` 8.
+- The catalogue set is one product line (cleaning products, mostly on white);
+  fashion, food or jewellery may differ.
+- One machine, CPU only, one worker. No GPU timings.
+- `--clean-edges` and `--fast-edges` were not scored.
+
+## Reproduce
+
+```bash
+uv sync
+# 1. Run every model on a folder of photos (times, peak RAM, before/after sheets)
+uv run python scripts/bench.py PHOTOS RESULTS --model birefnet-general-lite --model silueta ...
+# 2. Blind grids for judging (models shown as letters; GRIDS/index.json maps them back)
+uv run python scripts/bench_grids.py PHOTOS RESULTS GRIDS
+# 3. Close-ups of one region while judging
+uv run python scripts/bench_grids.py --zoom GRIDS wine-glass ORIGINAL,A,B 0.2 0.1 0.8 0.6
+```
+
+The public photos can be downloaded from the links in `benchmark/images.csv`.

bulk_bg_remove-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

bulk_bg_remove-0.1.0/LICENSE

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

bulk_bg_remove-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.5
+Name: bulk-bg-remove
+Version: 0.1.0
+Summary: Remove image backgrounds locally and in bulk: an agent skill for Claude Code, Codex and any agent, plus the engine behind it.
+Project-URL: Homepage, https://github.com/Btike/bulk-bg-remove
+Project-URL: Repository, https://github.com/Btike/bulk-bg-remove
+Project-URL: Issues, https://github.com/Btike/bulk-bg-remove/issues
+Project-URL: Benchmark, https://github.com/Btike/bulk-bg-remove/blob/main/BENCHMARK.md
+Author: Btike
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-skill,background-removal,birefnet,bulk,claude-code,codex,image-processing,rembg,remove-background,transparent-png
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: <3.14,>=3.11
+Requires-Dist: fastapi>=0.110
+Requires-Dist: numpy>=1.26
+Requires-Dist: pillow-heif>=0.18
+Requires-Dist: pillow>=11.3
+Requires-Dist: psutil>=5.9
+Requires-Dist: pymatting>=1.1
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: rembg[cpu]>=2.0.86
+Requires-Dist: rich>=13.7
+Requires-Dist: scipy>=1.11
+Requires-Dist: uvicorn>=0.29
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Btike/bulk-bg-remove/main/assets/logo-dark.svg">
+    <img src="https://raw.githubusercontent.com/Btike/bulk-bg-remove/main/assets/logo-light.svg" width="200" alt="bulk-bg-remove logo: a pixel-art monitor showing a green vase with a pink tulip on a transparency checkerboard">
+  </picture>
+</p>
+
+<h1 align="center">bulk-bg-remove</h1>
+
+<p align="center"><em>Every photo in the folder. No background. Nothing leaves your machine.</em></p>
+
+<p align="center">
+  <img alt="works with" src="https://img.shields.io/badge/works%20with-Claude%20Code%20·%20Codex%20·%20any%20agent-0d1117?style=flat-square">
+  <img alt="license" src="https://img.shields.io/badge/license-MIT-0d1117?style=flat-square">
+  <a href="https://pypi.org/project/bulk-bg-remove/"><img alt="PyPI" src="https://img.shields.io/pypi/v/bulk-bg-remove?style=flat-square&color=0d1117&label=pypi"></a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Btike/bulk-bg-remove/main/assets/demo.webp" width="880" alt="Demo: an agent is asked to remove the background from every photo in a folder; a bottle of olive oil loses its background, a reviewer catches background left by a cat's ear and keeps the redone cut-out, the products switch between white, mint and rose backgrounds and land in an online store">
+</p>
+
+<p align="center"><strong>Other skills run a model. This one checks every cut-out and redoes the bad ones.</strong></p>
+
+<p align="center">
+  <strong>11 models benchmarked on 80 hard images, judged blind at zoom.</strong><br>
+  The default scored <strong>8.6/10 on real product catalogue photos</strong>, the best of the 11, at <strong>3.2 s per photo</strong> on a laptop CPU.<br>
+  <sub>Apple M5, CPU only, one worker. Method, every score and the RAM numbers: <a href="https://github.com/Btike/bulk-bg-remove/blob/main/BENCHMARK.md">BENCHMARK.md</a>.</sub>
+</p>
+
+## What it is
+
+An agent skill plus the engine behind it. Ask your coding agent to *"remove the
+background from every photo in this folder"* and it:
+
+1. installs the engine (one `uv tool install`, ~500 MB with Python),
+2. checks your machine (free RAM, formats) and plans the run,
+3. looks at a sample, picks the best model that fits your free RAM (BiRefNet when there is
+   room), and cuts out every image in a queue or in parallel depending on RAM and CPU,
+4. has a second agent, with fresh eyes, review every cut-out on black and on white,
+   redo the bad ones with a better setting and keep whichever version is better,
+5. tells you what worked, what failed and why.
+
+Output goes to a new `<name>-no-bg/` folder next to the input. Originals are never
+touched, and the subject's pixels are copied bit for bit: only the alpha channel is new.
+
+Selling online? `--shop` puts every product on white, square, 2000 px and ready to
+upload; `--background "#E6F6EA"` uses your brand colour instead.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Btike/bulk-bg-remove/main/assets/showcase.webp" width="880" alt="Four before-and-after pairs: three friends by train tracks, a black camera on black, a bottle of olive oil, and a white bicycle against a wall, each cut out onto a transparency checkerboard">
+</p>
+
+Reads JPG, PNG, HEIC, WebP, AVIF, TIFF and BMP (by content, not extension), follows
+EXIF rotation, and handles CMYK, 16-bit and 45 MP photos.
+
+## Install
+
+Any agent ([skills CLI](https://github.com/vercel-labs/skills), needs Node.js 22.20 or newer):
+
+```bash
+npx skills add Btike/bulk-bg-remove
+```
+
+<details>
+<summary>Claude Code</summary>
+
+```
+/plugin marketplace add Btike/bulk-bg-remove
+```
+```
+/plugin install bulk-bg-remove@bulk-bg-remove
+```
+</details>
+
+<details>
+<summary>Codex</summary>
+
+```bash
+codex plugin marketplace add Btike/bulk-bg-remove
+codex plugin add bulk-bg-remove@bulk-bg-remove
+```
+</details>
+
+<details>
+<summary>Just the command, no agent</summary>
+
+```bash
+uv tool install bulk-bg-remove
+bulk-bg-remove ~/Pictures/products          # → ~/Pictures/products-no-bg/
+bulk-bg-remove                              # opens a drag-and-drop page in your browser
+```
+</details>
+
+## Which model it picks
+
+You do not choose: the agent looks at a few of your photos, tells the engine
+what kind they are, and the engine takes the best model for that kind that
+fits in your free RAM. Scores are from a [blind-judged benchmark](https://github.com/Btike/bulk-bg-remove/blob/main/BENCHMARK.md) (0–10):
+
+| Your photos | Best model | With little RAM (~4 GB free) |
+|---|---|---|
+| Products, objects | `birefnet-general-lite` 8.6 | `silueta` 8.1, used on its own |
+| Hair, fur, plants, wires | `birefnet-general` 7.6 | `silueta` 5.2, only if you say yes |
+| People | `birefnet-general` 7.8 | `silueta` 5.8, only if you say yes |
+| Busy scenes | `birefnet-general` 6.3 | `silueta` 4.0, only if you say yes |
+| Drawings, anime | `isnet-anime` 9.0 | needs ~5 GB free |
+
+## Options
+
+| Flag | What it does |
+|---|---|
+| `--profile uniform\|complex\|people\|scene\|drawing` | what the photos are; the model follows |
+| `--model NAME` | force a model instead of `auto` |
+| `--format webp\|jpg` | smaller lossless files (PNG by default); JPEG only with a background |
+| `--shop` | ready for a shop: white, square, product filling ~85%, 2000 px, JPEG |
+| `--background white\|#RRGGBB` | a solid colour behind the subject |
+| `--square` · `--pad PCT` · `--size PX` | square canvas · margin around the subject · longest side |
+| `--clean-edges` | remove the old background's colour halo from hair and fur edges |
+| `--fast-edges` | skip edge matting: faster, coarser hair |
+| `--review-sheets` | sheets and close-ups for reviewing the cut-outs |
+| `--only FILE` | redo just some images, keeping their output names |
+| `--dry-run --json` | scan and plan only; one JSON event per line for agents |
+| `doctor` | check the machine, and what `auto` would pick right now |
+
+## Requirements
+
+- Tested on macOS (Apple silicon), Linux and Windows, with a real-model run on each in CI
+  (Python 3.11–3.13). CPU by default; CUDA with `onnxruntime-gpu`.
+- **3.5 GB of free RAM** is enough for product photos: the engine picks the best
+  model that fits (about 12 GB gets the best ones). For hair, fur and plants a
+  light model is clearly worse, so the agent asks before using one.
+- The model downloads once (~220 MB). After that everything runs offline.
+
+## Credits
+
+Built on [rembg](https://github.com/danielgatis/rembg) and
+[BiRefNet](https://github.com/ZhengPeng7/BiRefNet). Showcase and demo photos (CC0, via
+Wikimedia Commons): Priscilla Du Preez, Dennis Klein, margenauer, Natasza Remesz,
+Mona Magnussen, Tiko Giorgadze, Dmitry Ratushny. The demo film is drawn in code (GSAP, rendered frame by
+frame in headless Chromium) from the engine's real output.
+
+## License
+
+MIT — see [LICENSE](https://github.com/Btike/bulk-bg-remove/blob/main/LICENSE).