chore: bump version to 0.4.2, update changelog

CUDA base image downgraded to 12.8.1 (driver 570 compatibility fix),
benchmark script added.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.env.example

@@ -23,13 +23,16 @@ STRATEGY=auto
 # YEARS_FILTER=10             # Only include images from the last N years (default: 10)
 
 # ── Image Quality ─────────────────────────────────────────────────────────────
-# MIN_FACE_WIDTH=50           # Minimum face width in pixels (default: 50)
+# MIN_FACE_WIDTH=90           # Minimum face width in pixels (default: 90, guarantees ≥8,100px crop)
 # FACE_MARGIN=0.15            # Padding around face crop as fraction (default: 0.15)
 # ENABLE_FACE_ALIGNMENT=true  # Align face before cropping (default: true)
 # USE_FULL_RESOLUTION=true    # Use full-res images vs thumbnails (default: true)
 # MIN_CONFIDENCE=0.7          # Minimum face detection confidence (default: 0.7)
-# BLUR_THRESHOLD=100.0        # Laplacian blur threshold; lower = accept more blur (default: 100.0)
+# BLUR_THRESHOLD=120.0        # Laplacian blur threshold; lower = accept more blur (default: 120.0)
 # MAX_AUTO_IMAGES=80          # Hard cap on auto-diversity selection (default: 80)
+# QUALITY_REPLACEMENT=true    # At cap, replace a weaker tracked image with a better candidate (default: true)
+# FRIGATE_SCORE_CEILING=0.0   # Skip uploads already well-covered (pre-upload score > ceiling = redundant; 0 = disabled; requires at least one prior run)
+# ENABLE_FRIGATE_SCORES=true  # Call Frigate's recognize endpoint pre-upload to store diversity scores (default: true; adds ~200ms per upload)
 
 # ── Caching & Models ──────────────────────────────────────────────────────────
 # FORCE_CPU=true              # Disable GPU, fall back to CPU

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,81 @@
+name: Bug Report
+description: Something isn't working as expected
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before filing, check the [Troubleshooting wiki](https://github.com/sudolulo/winnow/wiki/Troubleshooting) and [existing issues](https://github.com/sudolulo/winnow/issues).
+
+  - type: dropdown
+    id: image-tag
+    attributes:
+      label: Image tag
+      description: Which winnow image are you running?
+      options:
+        - ":latest (NVIDIA CUDA)"
+        - ":rocm (AMD)"
+        - ":intel (Intel Arc / iGPU)"
+        - ":cpu (CPU only)"
+        - "Local install (uv)"
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: winnow version
+      description: Output of `docker inspect ghcr.io/sudolulo/winnow:<tag> | grep org.opencontainers.image.version` or the version in `pyproject.toml`.
+      placeholder: "0.2.13"
+    validations:
+      required: true
+
+  - type: input
+    id: immich-version
+    attributes:
+      label: Immich version
+      placeholder: "v1.110.0"
+    validations:
+      required: false
+
+  - type: input
+    id: frigate-version
+    attributes:
+      label: Frigate version
+      placeholder: "0.16.0"
+    validations:
+      required: false
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: A clear description of the bug.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant log output
+      description: Paste logs from `docker logs winnow` or `winnow.log`. Set `VERBOSE=true` for more detail.
+      render: text
+    validations:
+      required: false
+
+  - type: textarea
+    id: compose
+    attributes:
+      label: Relevant compose / env config
+      description: Paste your `services.winnow` block. Redact your API key.
+      render: yaml
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question or help request
+    url: https://github.com/sudolulo/winnow/discussions
+    about: Ask questions and get help in GitHub Discussions
+  - name: Wiki / Documentation
+    url: https://github.com/sudolulo/winnow/wiki
+    about: Setup, troubleshooting, and FAQ

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,36 @@
+name: Feature Request
+description: Suggest an improvement or new capability
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe the use case or limitation you're running into.
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: What would you like winnow to do? New env var, different behaviour, etc.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any workarounds you've tried or other approaches you considered.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      options:
+        - label: I checked existing issues and this hasn't been requested before.
+          required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,26 @@
+## What does this PR do?
+
+<!-- One or two sentences. -->
+
+## Why?
+
+<!-- Link to the issue this addresses, or explain the motivation if there isn't one. -->
+
+Closes #
+
+## Changes
+
+<!-- Bullet list of the meaningful changes. -->
+
+-
+
+## Testing
+
+<!-- How did you verify this works? New tests added? Manual test steps? -->
+
+## Checklist
+
+- [ ] Targets the `dev` branch (not `main`)
+- [ ] `uv run pytest` passes
+- [ ] `uv run ruff check` passes
+- [ ] `CHANGELOG.md` `[Unreleased]` section updated

.github/workflows/docker-publish.yml

@@ -2,13 +2,33 @@ name: Publish Docker Image
 
 on:
   push:
-    branches: ["main", "dev"]
+    branches: ["dev"]
     paths-ignore:
       - "**.md"
       - "docs/**"
+      - ".github/ISSUE_TEMPLATE/**"
+      - ".github/PULL_REQUEST_TEMPLATE.md"
       - ".github/workflows/release.yml"
       - ".github/workflows/lint.yml"
       - ".github/dependabot.yml"
+      - "uv.lock"
+      - "uv-cpu.lock"
+      - "uv-rocm.lock"
+      - "uv-intel.lock"
+  workflow_call:
+    inputs:
+      tag:
+        type: string
+        required: false
+        description: "Release tag, e.g. v0.4.1 — triggers :latest + versioned image tags"
+      version:
+        type: string
+        required: false
+        description: "Version string without v prefix, e.g. 0.4.1"
+
+concurrency:
+  group: docker-${{ github.ref }}
+  cancel-in-progress: true
 
 env:
   REGISTRY: ghcr.io
@@ -32,18 +52,20 @@ jobs:
     steps:
       - name: Free up disk space
         run: |
-          sudo rm -rf /usr/share/dotnet
-          sudo rm -rf /opt/ghc
-          sudo rm -rf "/usr/local/share/boost"
-          sudo rm -rf "$AGENT_TOOLSDIRECTORY"
-          echo "Disk space freed."
+          sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc
+          sudo rm -rf /opt/hostedtoolcache/CodeQL /usr/share/swift
+          sudo rm -rf "/usr/local/share/boost" "$AGENT_TOOLSDIRECTORY"
+          docker system prune -af
+          df -h
 
       - name: Checkout repository
         uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.tag || github.ref }}
 
       - name: Set up QEMU
         if: matrix.platform == 'linux/arm64'
-        uses: docker/setup-qemu-action@v3
+        uses: docker/setup-qemu-action@v4
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
@@ -55,13 +77,23 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Compute build version
+        id: version
+        run: |
+          if [ -n "${{ inputs.version }}" ]; then
+            echo "value=${{ inputs.version }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "value=dev" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Build and push by digest
         id: build
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@v7
         with:
           context: .
           file: ./Dockerfile
           platforms: ${{ matrix.platform }}
+          build-args: VERSION=${{ steps.version.outputs.value }}
           cache-from: type=gha,scope=${{ matrix.platform }}
           cache-to: type=gha,mode=max,scope=${{ matrix.platform }}
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -110,25 +142,36 @@ jobs:
       - name: Determine image tags
         id: tags
         run: |
-          if [ "${{ github.ref_name }}" = "dev" ]; then
-            echo "tags=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:dev" >> "$GITHUB_OUTPUT"
+          IMAGE="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}"
+          INPUT_TAG="${{ inputs.tag }}"
+          if [ -n "$INPUT_TAG" ]; then
+            echo "tag_args=-t ${IMAGE}:latest -t ${IMAGE}:${INPUT_TAG}" >> "$GITHUB_OUTPUT"
+            echo "inspect_tag=${IMAGE}:latest" >> "$GITHUB_OUTPUT"
           else
-            echo "tags=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest" >> "$GITHUB_OUTPUT"
+            echo "tag_args=-t ${IMAGE}:dev" >> "$GITHUB_OUTPUT"
+            echo "inspect_tag=${IMAGE}:dev" >> "$GITHUB_OUTPUT"
           fi
 
       - name: Create and push multi-arch manifest
         working-directory: /tmp/digests
         run: |
           docker buildx imagetools create \
-            -t ${{ steps.tags.outputs.tags }} \
+            ${{ steps.tags.outputs.tag_args }} \
             $(printf '${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@sha256:%s ' *)
 
       - name: Inspect image
         run: |
-          docker buildx imagetools inspect ${{ steps.tags.outputs.tags }}
+          docker buildx imagetools inspect ${{ steps.tags.outputs.inspect_tag }}
+
+      - name: Ensure package is public
+        run: |
+          gh api -X PATCH /user/packages/container/winnow \
+            -f visibility=public || true
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
   build-cpu:
-    name: Build CPU-only (amd64)
+    name: Build CPU (amd64 + arm64)
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -137,14 +180,19 @@ jobs:
     steps:
       - name: Free up disk space
         run: |
-          sudo rm -rf /usr/share/dotnet
-          sudo rm -rf /opt/ghc
-          sudo rm -rf "/usr/local/share/boost"
-          sudo rm -rf "$AGENT_TOOLSDIRECTORY"
-          echo "Disk space freed."
+          sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc
+          sudo rm -rf /opt/hostedtoolcache/CodeQL /usr/share/swift
+          sudo rm -rf "/usr/local/share/boost" "$AGENT_TOOLSDIRECTORY"
+          docker system prune -af
+          df -h
 
       - name: Checkout repository
         uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.tag || github.ref }}
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
@@ -156,28 +204,220 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Determine CPU image tag
-        id: cpu-tag
+      - name: Determine CPU image tags
+        id: cpu-tags
         run: |
-          if [ "${{ github.ref_name }}" = "dev" ]; then
-            echo "tag=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:dev-cpu" >> "$GITHUB_OUTPUT"
+          IMAGE="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}"
+          INPUT_TAG="${{ inputs.tag }}"
+          if [ -n "$INPUT_TAG" ]; then
+            {
+              echo "tags<<EOF"
+              printf '%s\n' "${IMAGE}:cpu" "${IMAGE}:${INPUT_TAG}-cpu"
+              echo "EOF"
+            } >> "$GITHUB_OUTPUT"
+            echo "inspect_tag=${IMAGE}:cpu" >> "$GITHUB_OUTPUT"
           else
-            echo "tag=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:cpu" >> "$GITHUB_OUTPUT"
+            echo "tags=${IMAGE}:dev-cpu" >> "$GITHUB_OUTPUT"
+            echo "inspect_tag=${IMAGE}:dev-cpu" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Compute build version
+        id: version
+        run: |
+          if [ -n "${{ inputs.version }}" ]; then
+            echo "value=${{ inputs.version }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "value=dev" >> "$GITHUB_OUTPUT"
           fi
 
       - name: Build and push CPU image
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile
+          platforms: linux/amd64,linux/arm64
+          build-args: |
+            VARIANT=cpu
+            VERSION=${{ steps.version.outputs.value }}
+          cache-from: type=gha,scope=cpu
+          cache-to: type=gha,mode=max,scope=cpu
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          push: true
+          tags: ${{ steps.cpu-tags.outputs.tags }}
+
+      - name: Inspect CPU image
+        run: |
+          docker buildx imagetools inspect ${{ steps.cpu-tags.outputs.inspect_tag }}
+
+      - name: Ensure package is public
+        run: |
+          gh api -X PATCH /user/packages/container/winnow \
+            -f visibility=public || true
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  build-rocm:
+    name: Build ROCm / AMD GPU (amd64)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Free up disk space
+        run: |
+          sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc
+          sudo rm -rf /opt/hostedtoolcache/CodeQL /usr/share/swift
+          sudo rm -rf "/usr/local/share/boost" "$AGENT_TOOLSDIRECTORY"
+          docker system prune -af
+          df -h
+
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.tag || github.ref }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Determine ROCm image tags
+        id: rocm-tags
+        run: |
+          IMAGE="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}"
+          INPUT_TAG="${{ inputs.tag }}"
+          if [ -n "$INPUT_TAG" ]; then
+            {
+              echo "tags<<EOF"
+              printf '%s\n' "${IMAGE}:rocm" "${IMAGE}:${INPUT_TAG}-rocm"
+              echo "EOF"
+            } >> "$GITHUB_OUTPUT"
+            echo "inspect_tag=${IMAGE}:rocm" >> "$GITHUB_OUTPUT"
+          else
+            echo "tags=${IMAGE}:dev-rocm" >> "$GITHUB_OUTPUT"
+            echo "inspect_tag=${IMAGE}:dev-rocm" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Compute build version
+        id: version
+        run: |
+          if [ -n "${{ inputs.version }}" ]; then
+            echo "value=${{ inputs.version }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "value=dev" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build and push ROCm image
+        uses: docker/build-push-action@v7
         with:
           context: .
           file: ./Dockerfile
           platforms: linux/amd64
-          build-args: VARIANT=cpu
-          cache-from: type=gha,scope=linux/amd64-cpu
-          cache-to: type=gha,mode=max,scope=linux/amd64-cpu
+          build-args: |
+            VARIANT=rocm
+            VERSION=${{ steps.version.outputs.value }}
+          cache-from: type=gha,scope=linux/amd64-rocm
+          cache-to: type=gha,mode=max,scope=linux/amd64-rocm
           github-token: ${{ secrets.GITHUB_TOKEN }}
           push: true
-          tags: ${{ steps.cpu-tag.outputs.tag }}
+          tags: ${{ steps.rocm-tags.outputs.tags }}
 
-      - name: Inspect CPU image
+      - name: Inspect ROCm image
         run: |
-          docker buildx imagetools inspect ${{ steps.cpu-tag.outputs.tag }}
+          docker buildx imagetools inspect ${{ steps.rocm-tags.outputs.inspect_tag }}
+
+      - name: Ensure package is public
+        run: |
+          gh api -X PATCH /user/packages/container/winnow \
+            -f visibility=public || true
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  build-intel:
+    name: Build Intel GPU (amd64)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Free up disk space
+        run: |
+          sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc
+          sudo rm -rf /opt/hostedtoolcache/CodeQL /usr/share/swift
+          sudo rm -rf "/usr/local/share/boost" "$AGENT_TOOLSDIRECTORY"
+          docker system prune -af
+          df -h
+
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.tag || github.ref }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Determine Intel image tags
+        id: intel-tags
+        run: |
+          IMAGE="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}"
+          INPUT_TAG="${{ inputs.tag }}"
+          if [ -n "$INPUT_TAG" ]; then
+            {
+              echo "tags<<EOF"
+              printf '%s\n' "${IMAGE}:intel" "${IMAGE}:${INPUT_TAG}-intel"
+              echo "EOF"
+            } >> "$GITHUB_OUTPUT"
+            echo "inspect_tag=${IMAGE}:intel" >> "$GITHUB_OUTPUT"
+          else
+            echo "tags=${IMAGE}:dev-intel" >> "$GITHUB_OUTPUT"
+            echo "inspect_tag=${IMAGE}:dev-intel" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Compute build version
+        id: version
+        run: |
+          if [ -n "${{ inputs.version }}" ]; then
+            echo "value=${{ inputs.version }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "value=dev" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build and push Intel image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile
+          platforms: linux/amd64
+          build-args: |
+            VARIANT=intel
+            VERSION=${{ steps.version.outputs.value }}
+          cache-from: type=gha,scope=linux/amd64-intel
+          cache-to: type=gha,mode=max,scope=linux/amd64-intel
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          push: true
+          tags: ${{ steps.intel-tags.outputs.tags }}
+
+      - name: Inspect Intel image
+        run: |
+          docker buildx imagetools inspect ${{ steps.intel-tags.outputs.inspect_tag }}
+
+      - name: Ensure package is public
+        run: |
+          gh api -X PATCH /user/packages/container/winnow \
+            -f visibility=public || true
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -15,11 +15,13 @@ concurrency:
 
 jobs:
   release:
-    name: Create GitHub Release & Build Image
+    name: Create GitHub Release
     runs-on: ubuntu-latest
     permissions:
       contents: write
-      packages: write
+    outputs:
+      tag: ${{ steps.tag.outputs.TAG }}
+      version: ${{ steps.tag.outputs.VERSION }}
     steps:
       - name: Free up disk space
         run: |
@@ -37,14 +39,28 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@v7
 
-      - name: Ensure uv.lock is current
-        run: uv lock
+      - name: Set up Python
+        run: uv python install 3.13
 
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
+      - name: Verify release branch
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          if [ "${{ github.ref_name }}" != "main" ]; then
+            echo "::error::Releases must be dispatched from main (current: ${{ github.ref_name }})"
+            exit 1
+          fi
 
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4
+      - name: Ensure lockfiles are current
+        run: |
+          cp pyproject.toml _pyproject_orig.toml
+          for variant in cpu rocm intel; do
+            cp pyproject-${variant}.toml pyproject.toml
+            uv lock
+            cp uv.lock uv-${variant}.lock
+          done
+          cp _pyproject_orig.toml pyproject.toml
+          uv lock
+          rm _pyproject_orig.toml
 
       - name: Resolve tag name
         id: tag
@@ -111,22 +127,14 @@ jobs:
               prerelease: false,
             });
 
-      - name: Log in to GHCR
-        uses: docker/login-action@v4
-        with:
-          registry: ghcr.io
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Build and push Docker image
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          file: ./Dockerfile
-          platforms: linux/amd64,linux/arm64
-          push: true
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
-          tags: |
-            ghcr.io/sudolulo/winnow:latest
-            ghcr.io/sudolulo/winnow:${{ steps.tag.outputs.TAG }}
+  build-images:
+    name: Build and push Docker images
+    needs: release
+    uses: ./.github/workflows/docker-publish.yml
+    with:
+      tag: ${{ needs.release.outputs.tag }}
+      version: ${{ needs.release.outputs.version }}
+    secrets: inherit
+    permissions:
+      packages: write
+      contents: read

.github/workflows/update-lockfile.yml

@@ -1,10 +1,15 @@
 # .github/workflows/update-lockfile.yml
-name: Update uv.lock
+name: Update lockfiles
 
 on:
   push:
+    branches:
+      - '**'
     paths:
       - 'pyproject.toml'
+      - 'pyproject-cpu.toml'
+      - 'pyproject-rocm.toml'
+      - 'pyproject-intel.toml'
   workflow_dispatch:
 
 jobs:
@@ -30,24 +35,32 @@ jobs:
       - name: Set up Python
         run: uv python install 3.13
 
-      - name: Regenerate lockfile
-        run: uv lock
+      - name: Regenerate all lockfiles
+        run: |
+          cp pyproject.toml _pyproject_orig.toml
+          for variant in cpu rocm intel; do
+            cp pyproject-${variant}.toml pyproject.toml
+            uv lock
+            cp uv.lock uv-${variant}.lock
+          done
+          cp _pyproject_orig.toml pyproject.toml
+          uv lock
+          rm _pyproject_orig.toml
 
       - name: Check for changes
         id: diff
         run: |
-          if git diff --quiet uv.lock; then
+          if git diff --quiet uv.lock uv-cpu.lock uv-rocm.lock uv-intel.lock; then
             echo "changed=false" >> "$GITHUB_OUTPUT"
           else
             echo "changed=true" >> "$GITHUB_OUTPUT"
           fi
 
-      - name: Commit and push updated lockfile
+      - name: Commit and push updated lockfiles
         if: steps.diff.outputs.changed == 'true'
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git add uv.lock
-          git commit -m "chore: update uv.lock"
+          git add uv.lock uv-cpu.lock uv-rocm.lock uv-intel.lock
+          git commit -m "chore: update lockfiles"
           git push
-

CHANGELOG.md

@@ -7,6 +7,122 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.2] - 2026-06-13
+
+### Changed
+
+- **GPU image now uses CUDA 12.8.1** (was 13.3): CUDA 13.3 requires driver ≥ 575; driver 570 (the current stable release) was incorrectly rejected with "CUDA driver version is insufficient" at startup. The `:latest` image now works with any NVIDIA driver ≥ 570.
+
+### Added
+
+- **`scripts/benchmark.py`**: measures InsightFace and SigLIP inference latency and throughput across GPU and CPU modes. Run inside the container with `python /app/scripts/benchmark.py`. RTX 2070 SUPER results: InsightFace 12.8 ms / 78 img/s (8× CPU), SigLIP batch 32 at 5.4 ms/img / 187 img/s (33× CPU).
+
+## [0.4.1] - 2026-06-13
+
+### Fixed
+
+- **`RESET_PERSON` no longer creates duplicate Frigate files**: previously, resetting a person only wiped the local tracker — existing Frigate training files were left as unmanaged orphans, causing the next run to upload a full new batch on top of them. `reset_person` now deletes all winnow-managed files for that person from Frigate before clearing the tracker. Manually-added Frigate files are unaffected.
+- **No spurious warning when `FRIGATE_URL` is unset and `RESET_PERSON` is used**: the deletion step is now skipped silently at info level rather than logging a misleading "could not delete" warning.
+
+## [0.4.0] - 2026-06-13
+
+### Added
+
+- **Pre-upload Frigate recognition scores**: `recognize_face` is now called before each upload to measure how novel the candidate is relative to the existing training set. The score is stored in the tracker (`frigate_scores` field) and drives quality replacement in subsequent runs. Adds ~200 ms per upload.
+- **`ENABLE_FRIGATE_SCORES`** (default `true`): controls all pre-upload Frigate recognize calls. Set `false` to use blur-score replacement only and skip the Frigate round-trip entirely.
+- **`FRIGATE_SCORE_CEILING`** (default `0.0`): skip uploads whose pre-upload recognize score already exceeds this value — those face conditions are already well-covered by the training set. `0` disables (no ceiling); requires at least one prior run to have stored scores.
+- **`get_most_redundant_mapped_file()`**: new upload-tracker function that returns the mapped file with the highest Frigate pre-upload score. High score = the training set already covers that face condition well = the best deletion target for quality replacement.
+- **Cold-start notice**: first run (no existing Frigate model) now logs a clear message explaining why Frigate scores are unavailable and that they will populate on subsequent runs.
+- **4 new tests** for `get_most_redundant_mapped_file` covering score ordering, ties, excludes, and no-score cases.
+
+### Changed
+
+- **Quality replacement now uses Frigate scores**: when Frigate scores are available, at-cap replacement targets the _most redundant_ mapped file (highest pre-upload score) and replaces it only when the candidate is _more novel_ (lower score). Falls back to blur-score comparison when no Frigate scores have been stored yet.
+- **`recognize_face` returns `(face_name, score) | None`** instead of `float | None`: the caller now validates that the recognized person matches the expected person before using the score. Wrong-person scores no longer drive ceiling skips or replacement decisions.
+- **Bootstrap fix**: recognize was previously called below-cap only when `FRIGATE_SCORE_CEILING > 0`, so `frigate_scores` was never populated with default settings and the Frigate replacement path never activated. Recognize is now called for all below-cap uploads when `ENABLE_FRIGATE_SCORES=true`, seeding scores for future at-cap runs regardless of ceiling setting.
+- **Batch GET `/api/faces`**: Frigate file-count lookups are now batched to reduce round-trip overhead on runs with many people.
+- **Skip candidate download on low Frigate confidence**: candidates where the Immich detection confidence is below threshold are now filtered before the full-resolution download, saving bandwidth.
+
+### Removed
+
+- **Post-upload quality gate (`FRIGATE_SCORE_THRESHOLD`)**: enforcement of a Frigate score threshold after upload has been removed. Post-upload scores are taken after the image is already in the training set, so the model has already retrained on it — deleting it at that point is wasteful and disrupts the model for the next Frigate run. Pre-upload scoring (`FRIGATE_SCORE_CEILING`) provides a cleaner signal at the right moment.
+
+### Fixed
+
+- **Frigate replacement path never activated with default settings**: with `FRIGATE_SCORE_CEILING=0.0` (default), the bootstrap call to `recognize_face` was gated behind `CEILING > 0`, so `frigate_scores` stayed empty, `has_frigate_scores` was always False, and the Frigate replacement branch was permanently unreachable. Removing the ceiling guard from the below-cap recognize call breaks the circular dependency.
+- **Schema comment contradiction**: `upload_tracker.py` line-16 comment described `frigate_scores` as "post-upload" while the block comment on lines 22–24 said "pre-upload". Corrected to "pre-upload" throughout.
+- **README default values**: `MIN_FACE_WIDTH` was documented as `50` (actual default: `90`); `BLUR_THRESHOLD` was documented as `100.0` (actual default: `120.0`). Both corrected.
+- **README missing env vars**: `FRIGATE_SCORE_CEILING` and `ENABLE_FRIGATE_SCORES` were present in `config.py` and `.env.example` but absent from the README env var table. Both added.
+- **README quality-replacement description**: Step 8 and the `QUALITY_REPLACEMENT` row now document the dual-mode behaviour (Frigate-score path and blur-score fallback) instead of describing only the original blur-score path.
+
+## [0.3.3] - 2026-06-13
+
+### Fixed
+
+- **`MIN_FACE_WIDTH` default raised from 50 → 90px**: 50px crops produce 2,500–4,225 total pixels, well below Frigate's own camera capture range of 16k–50k px. 90px guarantees ≥8,100 total pixels even when face margins are fully clipped by image edges, keeping winnow training crops above the floor Frigate considers useful.
+
+## [0.3.2] - 2026-06-13
+
+### Added
+
+- **Crop dimension tracing**: winnow now records the pixel dimensions (width × height) of each face crop at upload time in the tracker (`crop_dims` field). Run `TRACE_CROP_SIZE=3848 winnow` to look up which Immich asset produced a crop with that pixel dimension — output includes person name, asset ID, Immich URL, blur score, and the Frigate filename. Useful for tracing low-quality or unexpected images visible in Frigate back to their source.
+
+## [0.3.1] - 2026-06-13
+
+### Fixed
+
+- **Lint**: split overly long line in `quality.py` (`E501`, 146 → ≤120 chars).
+- **CI — lockfile update workflow**: added `branches: ['**']` filter to `on.push` so tag pushes no longer trigger the job; tag checkouts land in detached HEAD and the subsequent `git push` had no branch target.
+- **CI — release workflow**: split four Docker image builds into parallel jobs (`build-gpu`, `build-cpu`, `build-rocm`, `build-intel`), each with its own runner. Previously all four ran in a single job; building the GPU and CPU multi-platform images exhausted disk, causing ROCm and Intel builds to be cancelled.
+
+## [0.3.0] - 2026-06-13
+
+### Added
+
+- **`get_tracked_frigate_filenames()`** — new upload-tracker function that returns the set of Frigate filenames currently mapped for a person. Used internally as a reconciliation baseline when the Frigate GET endpoint is unreachable; also available to callers that need the mapped filename set without a count.
+- **Community scaffolding**: `CONTRIBUTING.md`, `SECURITY.md`, GitHub issue templates (bug report, feature request), and pull request template.
+- **OCI image labels**: `org.opencontainers.image.*` labels added to the runtime stage of the Dockerfile so image metadata is surfaced by container registries.
+- **Additional tracker tests**: coverage added for `get_tracked_frigate_filenames` and for `get_lowest_quality_mapped_file` with the `exclude` parameter.
+
+### Fixed
+
+- **Quality score scale mismatch (USE_FULL_RESOLUTION=true)**: the time-spread quality-score fallback called `assess_quality` on the full-resolution download, while the embedding path always scores on preview thumbnails. Laplacian variance scales with image resolution, so the two paths produced incomparable scores for people with mixed-mode files. The fallback now caps the image at 1440 px before scoring to match the thumbnail scale.
+- **assess_quality failure left file permanently unreplaceable**: if `assess_quality` raised an exception (e.g. an RGBA image with an unsupported channel count), `score_map` kept `None` and `mark_uploaded(score=None)` skipped writing the score. The uploaded file was then permanently invisible to `get_lowest_quality_mapped_file` because it had no entry in `scores{}`. The fallback now converts the image to RGB before scoring and stores `0.0` on any exception, so every uploaded file is eligible for future quality replacement.
+- **Uploads during Frigate GET outage never mapped**: when `GET /api/faces` failed at upload start, the reconciliation guard (`_snapshot is not None`) correctly skipped the post-upload diff — but uploads that succeeded during the outage were never recorded in `frigate_files`, causing `get_tracked_frigate_file_count` to permanently under-report and Frigate to eventually exceed `MAX_AUTO_IMAGES`. The code now uses the tracker's mapped filenames as a pre-upload baseline when the live snapshot is unavailable, so reconciliation proceeds normally (the `>target` guard handles concurrent external uploads as before).
+- **Freed quality-replacement slot could be filled by a worse image**: when a replacement delete succeeded but the subsequent upload failed all retries, `effective_count` stayed decremented and the next file in the iteration uploaded unconditionally — it could have a lower quality score than the file that was deleted. A `min_quality_score_for_slot` variable now records the deleted file's score on a successful delete; any candidate that doesn't beat that floor is skipped until the slot is filled by a qualifying image or the run ends.
+- **CI multi-arch and lockfile bot**: hardened the build workflow — lockfile-update bot no longer races against Docker publish on the same push event; CPU image now builds for both `linux/amd64` and `linux/arm64`; `paths-ignore` prevents documentation-only pushes from triggering image builds.
+- **README pipeline diagram updated**: step 8 now explicitly documents the quality-replacement decision tree (`below cap → upload`, `at cap + enabled → swap if better`, `at cap + disabled → skip`).
+
+## [0.2.13] - 2026-06-13
+
+### Added
+
+- **Quality replacement**: when a person is at `MAX_AUTO_IMAGES`, winnow now checks each new candidate against the lowest-quality image already in Frigate and swaps it in if the new image scores higher. Only images winnow uploaded (tracked in `frigate_files`) are ever replaced — files added manually through Frigate's UI are left untouched permanently. Enabled by default; set `QUALITY_REPLACEMENT=false` to revert to the previous behaviour of skipping people at cap.
+- **Frigate filename mapping**: each successful upload now records the mapping from Frigate's assigned filename to the originating Immich asset ID and face confidence score in the tracker (`frigate_files` field). This is the foundation for quality replacement and future management of the Frigate training set.
+- **`QUALITY_REPLACEMENT` env var** (default `true`): controls whether at-cap people are eligible for quality replacement. When disabled, people at `MAX_AUTO_IMAGES` are skipped as before.
+- **NOTICES file**: third-party attribution for if_curator (MIT, Copyright © 2026 Sebastian) added to satisfy upstream license requirements.
+
+## [0.2.12] - 2026-06-13
+
+### Added
+
+- **ROCm (AMD GPU) support**: new `:rocm` image tag. InsightFace runs via `ROCmExecutionProvider`; SigLIP runs via PyTorch ROCm 6.3 (ROCm builds expose `torch.cuda.is_available() == True`, so the existing CUDA path is reused automatically). Requires `/dev/kfd` and `/dev/dri` device passthrough plus `video` and `render` group membership — see `compose.yml` for the snippet.
+- **Intel GPU support**: new `:intel` image tag. InsightFace runs via `OpenVINOExecutionProvider` from `onnxruntime-openvino`. By default OpenVINO targets CPU (no device passthrough needed); set `OPENVINO_DEVICE=GPU` to target Intel Arc discrete or integrated graphics. Intel's GPU compute runtime (Level Zero + OpenCL ICD) is installed automatically from Intel's official graphics repo in the image — no manual package installation required. SigLIP uses CPU inference for now (Intel Extension for PyTorch has no Python 3.13 wheels yet; the `torch.xpu` path is wired and will activate automatically when they ship).
+- **`OPENVINO_DEVICE` env var**: controls the OpenVINO execution provider device for the `:intel` variant. `CPU` (default) requires no device passthrough. `GPU` targets Intel Arc discrete and integrated graphics via Level Zero.
+- **AMD and Intel device passthrough snippets in `compose.yml`**: documented as commented-out alternatives to the NVIDIA `deploy:` block.
+- **`:rocm` and `:intel` CI jobs**: `docker-publish.yml` now builds and pushes `:rocm` / `:dev-rocm` and `:intel` / `:dev-intel` alongside `:latest` and `:cpu`. `release.yml` builds all four variants on tag push.
+
+### Fixed
+
+- **Interactive custom-count prompt firing for all choices**: in the no-embedding fallback path of the strategy selector, `IntPrompt.ask` was inside a dict literal and evaluated eagerly — users selecting Standard (30) or Broad (100) were still prompted to enter a custom image count. Each choice is now handled in a dedicated branch.
+
+## [0.2.11] - 2026-06-12
+
+### Fixed
+
+- **GPU broken on x86_64 Linux**: `insightface` 1.0.1 (pulled in by the 0.2.10 lock update) added a hard dependency on the CPU `onnxruntime` package. Combined with an incorrect `override-dependencies` entry introduced in 0.2.10, both `onnxruntime` (CPU) and `onnxruntime-gpu` were being installed into the same venv. The CPU package landed last and overwrote the GPU one, causing `CUDAExecutionProvider` to disappear from the provider list even when a GPU was present. Fixed by declaring `onnxruntime` and `onnxruntime-gpu` as conflicting packages in uv's resolver, ensuring only the correct one is installed per platform.
+- **OOM crash on large person libraries (CPU mode)**: All candidate thumbnails were downloaded into a single in-memory dict before any processing began. At ~5 MB per decoded preview image, a person with 472 candidates would accumulate ~2.4 GB of thumbnail data alone, exhausting a 4 GB container memory limit. Thumbnails are now downloaded and processed in batches of 32, with each image released immediately after embedding. Peak in-flight thumbnail memory is now bounded to ~256 MB regardless of candidate pool size. GPU users also benefit from lower host RAM pressure and faster time-to-first-result on large libraries.
+
 ## [0.2.10] - 2026-06-12
 
 ### Added

CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing to winnow
+
+Bug reports, feature requests, and pull requests are all welcome.
+
+## Before You Start
+
+- Check [existing issues](https://github.com/sudolulo/winnow/issues) to avoid duplicates.
+- For large changes, open an issue first to discuss the approach.
+- All PRs target the `dev` branch — never `main` directly.
+
+## Development Setup
+
+Requires Python 3.13+ and [uv](https://astral.sh/uv).
+
+```bash
+git clone https://github.com/sudolulo/winnow.git
+cd winnow
+git checkout dev
+uv sync
+```
+
+## Running Tests and Lint
+
+```bash
+uv run pytest          # run the test suite
+uv run ruff check      # lint
+uv run ruff check --fix  # auto-fix lint issues
+```
+
+CI runs both on every push and PR to `main` and `dev`. PRs must pass before merging.
+
+## Pull Request Guidelines
+
+- One logical change per PR.
+- If you add behaviour, add a test for it.
+- Keep the `CHANGELOG.md` entry in the `[Unreleased]` section updated.
+- Commit messages should be plain English describing what changed and why.
+
+## License
+
+By submitting a contribution you agree that your work will be released under the project's [AGPLv3+ license](LICENSE).

Dockerfile

@@ -1,13 +1,19 @@
 # ── Base images ───────────────────────────────────────────────────────────────
-#   amd64 + gpu:  NVIDIA CUDA 13.3 + cuDNN (GPU acceleration when available)
-#   amd64 + cpu:  Ubuntu 22.04 (CPU-only, ~2 GB smaller image)
-#   arm64:        Ubuntu 24.04 (CPU-only; no CUDA wheels on ARM)
+#   amd64 + gpu:   NVIDIA CUDA 12.8 + cuDNN (GPU acceleration via NVIDIA Container Toolkit)
+#   amd64 + rocm:  Ubuntu 22.04 (AMD GPU via ROCm — pass /dev/kfd and /dev/dri)
+#   amd64 + intel: Ubuntu 22.04 (Intel Arc / iGPU via OpenVINO — pass /dev/dri)
+#   amd64 + cpu:   Ubuntu 22.04 (CPU-only, ~2 GB smaller image)
+#   arm64:         Ubuntu 24.04 (CPU-only; no CUDA/ROCm wheels on ARM)
 
 ARG VARIANT=gpu
 
-FROM --platform=$BUILDPLATFORM nvidia/cuda:13.3.0-cudnn-runtime-ubuntu22.04 AS base-amd64-gpu
+FROM --platform=$BUILDPLATFORM nvidia/cuda:12.8.1-cudnn-runtime-ubuntu22.04 AS base-amd64-gpu
+FROM ubuntu:22.04 AS base-amd64-rocm
+FROM ubuntu:22.04 AS base-amd64-intel
 FROM ubuntu:22.04 AS base-amd64-cpu
 FROM ubuntu:24.04 AS base-arm64-gpu
+FROM ubuntu:24.04 AS base-arm64-rocm
+FROM ubuntu:24.04 AS base-arm64-intel
 FROM ubuntu:24.04 AS base-arm64-cpu
 
 # ── Build stage ───────────────────────────────────────────────────────────────
@@ -35,11 +41,15 @@ RUN curl -LsSf https://astral.sh/uv/install.sh | sh \
 
 WORKDIR /app
 
-# For cpu variant, swap in the CPU-only pyproject and lockfile before syncing.
-COPY pyproject.toml uv.lock pyproject-cpu.toml uv-cpu.lock ./
+# Swap in the variant-specific pyproject and lockfile before syncing.
+COPY pyproject.toml uv.lock pyproject-cpu.toml uv-cpu.lock \
+     pyproject-rocm.toml uv-rocm.lock pyproject-intel.toml uv-intel.lock ./
 RUN if [ "$VARIANT" = "cpu" ]; then \
-        cp pyproject-cpu.toml pyproject.toml && \
-        cp uv-cpu.lock uv.lock; \
+        cp pyproject-cpu.toml pyproject.toml && cp uv-cpu.lock uv.lock; \
+    elif [ "$VARIANT" = "rocm" ]; then \
+        cp pyproject-rocm.toml pyproject.toml && cp uv-rocm.lock uv.lock; \
+    elif [ "$VARIANT" = "intel" ]; then \
+        cp pyproject-intel.toml pyproject.toml && cp uv-intel.lock uv.lock; \
     fi && \
     uv sync --frozen --no-dev \
     && uv cache clean
@@ -55,6 +65,12 @@ RUN chmod +x /app/entrypoint.sh
 FROM base-${TARGETARCH}-${VARIANT} AS runtime
 
 ARG VARIANT=gpu
+ARG VERSION=dev
+LABEL org.opencontainers.image.title="winnow" \
+      org.opencontainers.image.description="Selects diverse, high-quality photos from Immich as training data for Frigate face recognition and object classification." \
+      org.opencontainers.image.source="https://github.com/sudolulo/winnow" \
+      org.opencontainers.image.licenses="AGPL-3.0-or-later" \
+      org.opencontainers.image.version="${VERSION}"
 ENV DEBIAN_FRONTEND=noninteractive
 
 RUN apt-get update && apt-get install -y --no-install-recommends \
@@ -72,11 +88,32 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 COPY --from=build /app /app
 COPY --from=build /usr/local/bin/uv /usr/local/bin/uv
 
-# Register every nvidia pip-package lib/ directory with ldconfig so that
-# onnxruntime-gpu and torch can find libcudnn, libcublas, libcufft, etc.
-# without a hand-maintained LD_LIBRARY_PATH. Skipped silently on cpu builds.
-RUN find /app/.venv/lib/python3.*/site-packages/nvidia -type d -name "lib" \
-        2>/dev/null > /etc/ld.so.conf.d/nvidia-pip.conf && ldconfig || true
+# NVIDIA: register pip-installed nvidia lib/ dirs with ldconfig so onnxruntime-gpu
+# and torch can find libcudnn, libcublas, etc. Skipped silently on other variants.
+RUN if [ "$VARIANT" = "gpu" ]; then \
+        find /app/.venv/lib/python3.*/site-packages/nvidia -type d -name "lib" \
+            2>/dev/null > /etc/ld.so.conf.d/nvidia-pip.conf && ldconfig || true; \
+    fi
+# Intel: install GPU compute runtime so OpenVINO EP can target Intel Arc / iGPU.
+# onnxruntime-openvino bundles OpenVINO itself; only the userspace GPU driver
+# (OpenCL ICD + Level Zero) is needed from the OS.
+# These packages aren't in Ubuntu 22.04 main, so this block adds Intel's
+# official GPU repo first, then installs. libze-intel-gpu1 was renamed to
+# level-zero in Intel's repo.
+RUN if [ "$VARIANT" = "intel" ]; then \
+        apt-get update \
+        && apt-get install -y --no-install-recommends curl gnupg \
+        && curl -fsSL https://repositories.intel.com/graphics/intel-graphics.key \
+           | gpg --dearmor > /usr/share/keyrings/intel-graphics.gpg \
+        && echo "deb [arch=amd64 signed-by=/usr/share/keyrings/intel-graphics.gpg] \
+https://repositories.intel.com/graphics/ubuntu jammy flex" \
+           > /etc/apt/sources.list.d/intel-graphics.list \
+        && apt-get update \
+        && apt-get install -y --no-install-recommends \
+               intel-opencl-icd intel-level-zero-gpu level-zero \
+        && apt-get remove -y --autoremove curl gnupg \
+        && rm -rf /var/lib/apt/lists/*; \
+    fi
 
 RUN groupadd -g 568 apps && useradd -u 568 -g apps -m -s /bin/bash appuser \
     && mkdir -p /models/.insightface /models/huggingface \

NOTICES

@@ -0,0 +1,23 @@
+winnow incorporates portions of if_curator (https://github.com/ds-sebastian/if_curator).
+
+    MIT License
+
+    Copyright (c) 2026 Sebastian
+
+    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.

README.md

@@ -1,31 +1,22 @@
 # winnow
 
-[![Docker](https://github.com/sudolulo/winnow/actions/workflows/docker-publish.yml/badge.svg)](https://github.com/sudolulo/winnow/actions/workflows/docker-publish.yml) [![Test](https://github.com/sudolulo/winnow/actions/workflows/test.yml/badge.svg)](https://github.com/sudolulo/winnow/actions/workflows/test.yml) [![Immich](https://img.shields.io/badge/Immich-v1.106%2B-blueviolet)](https://immich.app) [![Frigate](https://img.shields.io/badge/Frigate-Ready-brightgreen)](https://frigate.video)
+[![Docker](https://github.com/sudolulo/winnow/actions/workflows/docker-publish.yml/badge.svg)](https://github.com/sudolulo/winnow/actions/workflows/docker-publish.yml) [![Test](https://github.com/sudolulo/winnow/actions/workflows/test.yml/badge.svg)](https://github.com/sudolulo/winnow/actions/workflows/test.yml) [![GitHub release](https://img.shields.io/github/v/release/sudolulo/winnow)](https://github.com/sudolulo/winnow/releases/latest) [![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE) [![Immich](https://img.shields.io/badge/Immich-v1.106%2B-blueviolet)](https://immich.app) [![Frigate](https://img.shields.io/badge/Frigate-Ready-brightgreen)](https://frigate.video)
+
+> **Early Development — Use With Caution**
+> winnow is functional but still maturing. Features that modify your Frigate training data — quality replacement, stale mapping cleanup — can remove images from your dataset and are not yet battle-tested at scale. Review the logs after each run and keep backups of your Frigate face training directory until you are confident in the results.
 
 **Docs:** [Setup](https://github.com/sudolulo/winnow/wiki/Setup) · [Troubleshooting](https://github.com/sudolulo/winnow/wiki/Troubleshooting) · [FAQ](https://github.com/sudolulo/winnow/wiki/FAQ)
 
-`winnow` pulls photos of people and objects from your [Immich](https://immich.app) library, selects the most diverse and highest-quality subset using AI embeddings, and delivers them as training data for [Frigate](https://frigate.video)'s face recognition and object classification models.
+`winnow` pulls photos from your [Immich](https://immich.app) library, selects the most diverse and highest-quality subset using AI embeddings, and delivers them as training data for [Frigate](https://frigate.video)'s face recognition and object classification models.
 
-It runs fully headless in Docker, is configured entirely through environment variables, and can run on a schedule — no interactive prompts, no manual steps.
+Frigate's face recognition is only as good as its training data — and the key quality metric is **diversity**, not volume. A hundred photos from the same week teach the model one lighting condition. What you need is a spread: different years, different angles, different lighting, different contexts. Your photo library already has that data. winnow finds and delivers the right subset automatically.
 
----
-
-## The Problem
-
-Frigate's face recognition model (ArcFace) and object classifier are only as good as the training data you give them. The instinct is to feed them as many photos as possible, but volume is not what matters — **diversity is**.
-
-If you upload 100 photos from the same week, the model learns the lighting in your living room and the jacket you wore that month. It struggles the moment anything changes. What you actually want is a spread: different years, different lighting conditions, different angles, different contexts.
-
-This is especially true for people who have never been to your property, or who visit rarely — family members, friends, anyone Frigate has never seen in person. Live detections alone will never build a reliable model for these people. Your photo library already has the data; winnow finds and delivers the right subset of it.
-
-Finding that spread manually across a library of thousands of photos is not practical. `winnow` does it automatically.
+> **winnow only touches files it uploaded.** Faces added to Frigate manually through its UI are never deleted, replaced, or modified — not by quality replacement, not by `RESET_PERSON`, not by stale cleanup. If you have a curated training set you want to keep, it is safe.
 
 ---
 
 ## How It Works
 
-For each person (or object) you configure, the tool runs this pipeline:
-
 ```
 Immich library
       │
@@ -33,79 +24,61 @@ Immich library
 1. Fetch all assets tagged with this person
       │
       ▼
-2. Filter by recency (configurable years window)
+2. Filter by recency (YEARS_FILTER) and skip already-uploaded
+   and rejected assets (persistent tracker in CACHE_DIR)
       │
       ▼
-3. Skip already-uploaded assets (persistent tracker)
-      │
-      ▼
-4. Quality filter — reject:
+3. Quality filter — download preview thumbnails and reject:
    • Blurry images (Laplacian variance)
-   • Grayscale / infrared (channel similarity check)
+   • Grayscale / infrared (channel similarity)
    • Over- or underexposed
    • Low detection confidence
    • Face crops below minimum pixel size
       │
       ▼
-5. Compute embeddings for remaining candidates
-   • Faces   → InsightFace (ArcFace / Buffalo_L)
-   • Objects → SigLIP (Vision Transformer)
+4. Compute embeddings from the same preview thumbnails
+   • Faces   → InsightFace (ArcFace / Buffalo_L)  → 512-dim vector
+   • Objects → SigLIP (Vision Transformer)         → 768-dim vector
       │
       ▼
-6. Diversity selection
-   • K-Medoids clustering to find natural groupings
-   • Farthest Point Sampling (FPS) to pick maximally spread representatives
-   • Hard example weighting — unusual angles, partial occlusions,
-     and low-confidence detections are biased toward selection
-   • Auto mode: keeps selecting until marginal diversity drops off
+5. Diversity selection
+   • K-Medoids clustering → one representative per natural group
+   • Farthest Point Sampling → fill remaining slots with maximally spread picks
+   • Hard example weighting — unusual angles and low-confidence detections
+     are biased toward selection, since those are where models tend to fail
+   • Auto mode: stops when similarity to the existing set exceeds a threshold
+     (20 % of median pairwise distance for faces, 10 % for objects)
       │
       ▼
-7. Crop and export
-   • Face mode: aligned 112×112 crops (ArcFace standard input),
-     uploaded directly to Frigate's face training API
-   • Object mode: YOLO-detected crops saved to disk
+6. Download full-resolution originals from Immich
+      │
+      ▼
+7. Crop and process
+   • Face mode: EXIF-corrected, landmark-aligned 112×112 crop (ArcFace format)
+   • Object mode: YOLOv9c detection → one crop per matched instance
+      │
+      ▼
+8. Deliver
+   • Face mode: upload crops to Frigate's face registration API
+     ↳ below MAX_AUTO_IMAGES — upload freely
+     ↳ at cap + QUALITY_REPLACEMENT=true — with Frigate scoring active,
+       swap the most redundant tracked image (highest pre-upload recognize
+       score) if the candidate is more novel (lower score); falling back to
+       blur-score comparison when no Frigate scores are available; manually
+       added files are never touched
+     ↳ at cap + QUALITY_REPLACEMENT=false — skip this person
+   • Object mode: save crops to disk → place into your Frigate data directory
 ```
 
-Uploaded asset IDs are recorded so the same image is never uploaded twice, even across runs weeks apart.
-
----
-
-## Note on Crop Quality
-
-winnow works well, but no automated pipeline is perfect. Occasionally a bad crop will slip through quality filtering — a partial face, someone in the background, a blurry frame. After a run it's worth a quick review in Frigate's face management UI to remove anything that doesn't belong.
-
-Issues and feedback welcome via [GitHub Issues](https://github.com/sudolulo/winnow/issues).
+Uploaded and rejected asset IDs are persisted across runs. The same image is never processed twice; Frigate rejections are permanently skipped unless `RETRY_REJECTED=true`.
 
 ---
 
 ## Modes
 
-### Face Mode (default)
+**Face mode** (default) — extracts face crops using Immich's bounding box metadata, applies EXIF orientation correction, and aligns them to ArcFace's standard 112×112 format using 5-point facial landmarks. Crops are uploaded directly to Frigate's face registration API.
 
-Extracts face crops using Immich's bounding box metadata, scales them to the source image resolution, applies EXIF orientation correction, then either aligns them to the standard ArcFace 112×112 format using 5-point facial landmarks or falls back to a margin-padded bounding box crop.
-
-Crops are uploaded directly to Frigate's face registration API (`POST /api/faces/{name}/register`). After each successful upload the asset ID is marked in the tracker so future runs skip it.
-
-### Object Mode
-
-Runs each full image through YOLOv9c to detect instances of a target class (dog, cat, car, etc.), then crops each detection and saves it to the output directory. Frigate has no API for uploading object training images, so the crops are saved for you to place into your Frigate data directory manually.
-
----
-
-## Diversity Selection in Detail
-
-The core of the tool is the embedding-based selection. Rather than picking images at random or evenly across time, it computes a vector embedding for each candidate image that encodes what the face or object actually looks like — the angle, lighting, expression, background context.
-
-It then:
-
-1. **Clusters** those embeddings using K-Medoids to find natural groups (e.g. "holiday photos", "outdoor summer shots", "indoor low light")
-2. **Selects one representative** from each cluster — the most central image in each group
-3. **Fills remaining slots** using Farthest Point Sampling, iteratively picking whichever image is most different from everything already selected
-4. **Weights toward hard examples** — images with unusual angles, partial occlusions, or borderline detection confidence are more likely to be picked, because those edge cases are where models fail
-
-In **Auto mode**, there is no fixed limit. The tool keeps selecting until the most-different remaining image is already close to something already in the set — at that point adding more would be redundant. This is capped at `MAX_AUTO_IMAGES` (default 80) as a safety limit.
-
-If the embedding model is unavailable, the tool falls back to **time spread**: evenly distributing picks across the date range of your photos.
+**Object mode** — runs each full-resolution image through YOLOv9c to detect instances of a target class (dog, cat, car, etc.), crops each detection, and saves it to the output directory. Frigate has no API for uploading object training data; place the crops into your Frigate data directory manually.
 
 ---
 
@@ -113,22 +86,25 @@ If the embedding model is unavailable, the tool falls back to **time spread**: e
 
 ### Image Tags
 
-| Tag | Arch | GPU | Notes |
-| :-- | :-- | :-- | :-- |
-| `:latest` | amd64 + arm64 | CUDA 13.3 (amd64) | Requires NVIDIA Container Toolkit on amd64 |
-| `:cpu` | amd64 | None | ~2 GB smaller; use if you have no NVIDIA GPU |
+| Tag | Arch | Acceleration |
+| :-- | :-- | :-- |
+| `:latest` | amd64 + arm64 | NVIDIA CUDA 13.3 (amd64) · requires [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) |
+| `:rocm` | amd64 | AMD ROCm · pass `/dev/kfd` + `/dev/dri` |
+| `:intel` | amd64 | Intel Arc / iGPU via OpenVINO · pass `/dev/dri`, set `OPENVINO_DEVICE=GPU` |
+| `:cpu` | amd64 + arm64 | CPU only · ~2 GB smaller · no GPU required |
 
 ### Quick Start
 
+**NVIDIA:**
 ```yaml
 services:
   winnow:
-    image: ghcr.io/sudolulo/winnow:latest   # or :cpu for CPU-only amd64
+    image: ghcr.io/sudolulo/winnow:latest
     environment:
       - IMMICH_URL=http://192.168.1.10:2283
       - API_KEY=your-immich-api-key
       - FRIGATE_URL=http://192.168.1.10:5000
-      - CRON_SCHEDULE=0 3 * * 0   # Every Sunday at 3 AM
+      - CRON_SCHEDULE=0 3 * * 0
     volumes:
       - /path/to/models:/models
       - /path/to/cache:/app/.if_cache
@@ -142,11 +118,31 @@ services:
               capabilities: [gpu]
 ```
 
-> **CPU users (`:cpu` tag):** remove the `deploy.resources` block — no NVIDIA runtime needed.
+**AMD (`:rocm`):** use `image: ghcr.io/sudolulo/winnow:rocm` and replace the `deploy:` block with:
+```yaml
+    devices:
+      - /dev/kfd
+      - /dev/dri
+    group_add:
+      - video
+      - render
+```
 
-See [compose.yml](compose.yml) for the full annotated example.
+**Intel (`:intel`):** use `image: ghcr.io/sudolulo/winnow:intel` and replace the `deploy:` block with:
+```yaml
+    devices:
+      - /dev/dri
+    group_add:
+      - render
+    environment:
+      - OPENVINO_DEVICE=GPU   # omit to run OpenVINO inference on CPU (default)
+```
 
-### Scheduling Behaviour
+**CPU (`:cpu`):** use `image: ghcr.io/sudolulo/winnow:cpu`, remove the `deploy:` block, and add `mem_limit: 2g` to prevent OOM on large libraries.
+
+See [compose.yml](compose.yml) for the full annotated example with all options.
+
+### Scheduling
 
 `CRON_SCHEDULE` controls container lifetime:
 
@@ -156,77 +152,85 @@ See [compose.yml](compose.yml) for the full annotated example.
 | *(empty string)* | Stay alive, run nothing — trigger manually with `docker exec -it winnow winnow` |
 | Cron expression | Run on startup, then repeat on schedule |
 
-In scheduled mode the process (and loaded models) stays resident between runs. In manual mode the container idles indefinitely with `sleep infinity` — useful when you want to trigger runs interactively on demand without pulling a new container each time.
-
-The first run after a fresh install downloads the embedding models (~1-2 GB). Subsequent runs use the cached models from the mounted volume and start immediately.
+In scheduled mode the process (and loaded models) stays resident between runs. The first run after a fresh install downloads the embedding models (~1–2 GB); subsequent runs use the cached models from the mounted volume.
 
 ---
 
 ## Environment Variables
 
-### Mode & Strategy
-
-| Variable | Default | Description |
-| :--- | :--- | :--- |
-| `AUTO_MODE` | *(auto)* | Force non-interactive mode even in a terminal; auto-detected otherwise (no TTY = auto) |
-| `VERBOSE` | `false` | Set to `true` to enable DEBUG-level console output (the log file is always DEBUG) |
-| `TRAINING_MODE` | `face` | `face` — upload crops to Frigate API; `object` — save crops to disk |
-| `STRATEGY` | `auto` | `auto` (adaptive), `standard` (30 images), `broad` (100 images) |
-| `LIMIT` | *(unset)* | Exact image count — overrides `STRATEGY` |
-| `OBJECT_CLASS` | `dog` | Target class for object mode (any YOLO class: `dog`, `cat`, `car`, etc.) |
-
-### People Filtering
-
-| Variable | Default | Description |
-| :--- | :--- | :--- |
-| `ONLY_PEOPLE` | *(unset)* | Comma-separated whitelist — only these people are processed |
-| `SKIP_PEOPLE` | *(unset)* | Comma-separated list of people to skip |
-| `MIN_FACE_COUNT` | `0` | Skip people with fewer than N tagged assets in Immich |
-| `YEARS_FILTER` | `10` | Ignore images older than N years |
-
 ### Connection
 
 | Variable | Default | Description |
 | :--- | :--- | :--- |
 | `IMMICH_URL` | *(required)* | Full URL to your Immich instance |
 | `API_KEY` | *(required)* | Immich API key |
-| `FRIGATE_URL` | *(unset)* | Frigate URL — required for face upload; omit to skip upload |
+| `FRIGATE_URL` | *(unset)* | Frigate URL — required for face upload; omit to skip |
+
+### Mode & Strategy
+
+| Variable | Default | Description |
+| :--- | :--- | :--- |
+| `TRAINING_MODE` | `face` | `face` — upload crops to Frigate; `object` — save crops to disk |
+| `STRATEGY` | `auto` | `auto` (embedding-based adaptive), `standard` (30 images), `broad` (100 images) |
+| `LIMIT` | *(unset)* | Exact image count — overrides `STRATEGY` |
+| `OBJECT_CLASS` | `dog` | Target class for object mode (any YOLO class: `dog`, `cat`, `car`, etc.) |
+| `AUTO_MODE` | *(auto)* | Force non-interactive mode in a terminal; auto-detected otherwise |
+| `VERBOSE` | `false` | Enable DEBUG-level console output (log file is always DEBUG) |
+
+### People Filtering
+
+| Variable | Default | Description |
+| :--- | :--- | :--- |
+| `ONLY_PEOPLE` | *(unset)* | Comma-separated whitelist — process only these people |
+| `SKIP_PEOPLE` | *(unset)* | Comma-separated list — skip these people |
+| `MIN_FACE_COUNT` | `0` | Skip people with fewer than N tagged assets in Immich |
+| `YEARS_FILTER` | `10` | Ignore images older than N years |
 
 ### Image Quality
 
 | Variable | Default | Description |
 | :--- | :--- | :--- |
-| `MIN_FACE_WIDTH` | `50` | Minimum face crop width in pixels |
-| `FACE_MARGIN` | `0.15` | Padding added around the bounding box crop (fraction of face size) |
+| `MIN_FACE_WIDTH` | `90` | Minimum face crop width in pixels |
+| `FACE_MARGIN` | `0.15` | Padding around bounding box crop (fraction of face size) |
 | `ENABLE_FACE_ALIGNMENT` | `true` | Align to ArcFace 112×112 format using facial landmarks |
 | `USE_FULL_RESOLUTION` | `true` | Download full-resolution originals rather than preview thumbnails |
 | `MIN_CONFIDENCE` | `0.7` | Minimum Immich face detection confidence |
-| `BLUR_THRESHOLD` | `100.0` | Laplacian variance threshold — lower accepts more blur |
-| `MAX_AUTO_IMAGES` | `80` | Maximum images in auto-diversity mode |
+| `BLUR_THRESHOLD` | `120.0` | Laplacian variance threshold — lower accepts more blur |
+| `MAX_AUTO_IMAGES` | `80` | Maximum training images per person in Frigate |
+| `QUALITY_REPLACEMENT` | `true` | When at cap, swap a weaker tracked image for a better candidate. With Frigate scoring active, targets the most redundant image (highest pre-upload recognize score); otherwise uses blur score. Never touches manually added Frigate files. Set `false` to skip people at cap |
+| `FRIGATE_SCORE_CEILING` | `0.0` | Skip uploads whose pre-upload Frigate recognize score exceeds this value — they are already well-covered. `0` disables; requires at least one prior run to have scores |
+| `ENABLE_FRIGATE_SCORES` | `true` | Call Frigate's recognize endpoint pre-upload to store diversity scores used for quality replacement. Adds ~200 ms per upload. Disable to use blur-score replacement only |
 
-### Caching & Models
+### GPU & Models
 
 | Variable | Default | Description |
 | :--- | :--- | :--- |
-| `FORCE_CPU` | `false` | Disable GPU — fall back to CPU for embedding computation |
+| `FORCE_CPU` | `false` | Disable GPU — fall back to CPU for all inference |
+| `OPENVINO_DEVICE` | `CPU` | Intel variant only: set `GPU` to use Arc or iGPU; default runs on CPU |
 | `ENABLE_CACHE` | `true` | Cache computed embeddings to disk (speeds up re-runs on the same library) |
 | `CACHE_DIR` | `.if_cache` | Path for embedding cache and upload tracker files |
-| `HF_HOME` | *(system)* | HuggingFace model cache location (SigLIP) |
-| `INSIGHTFACE_HOME` | *(system)* | InsightFace model cache location (Buffalo_L) |
+| `HF_HOME` | *(system)* | HuggingFace model cache path (SigLIP) |
+| `INSIGHTFACE_HOME` | *(system)* | InsightFace model cache path (Buffalo_L) |
+
+### Output
+
+| Variable | Default | Description |
+| :--- | :--- | :--- |
+| `OUTPUT_DIR` | `./frigate_train` | Directory for object-mode crops and the `winnow.log` file. In Docker, set this via the volume mount instead. |
 
 ### Tracker Overrides *(one-shot — remove after use)*
 
 | Variable | Default | Description |
 | :--- | :--- | :--- |
-| `DRY_RUN` | `false` | Show what would be selected and uploaded without doing it |
+| `DRY_RUN` | `false` | Preview selection without downloading or uploading |
 | `RETRY_REJECTED` | `false` | Re-attempt assets previously rejected by Frigate |
-| `RESET_PERSON` | *(unset)* | Clear upload and rejection history for one person by name |
+| `RESET_PERSON` | *(unset)* | Clear upload history for one person and delete their winnow-managed Frigate training files so the next run starts fresh. Manually added Frigate files are never touched |
 
 ### Scheduling
 
 | Variable | Default | Description |
 | :--- | :--- | :--- |
-| `CRON_SCHEDULE` | *(unset)* | Unset = run once and exit; empty = stay alive for manual `docker exec`; cron expression = scheduled |
+| `CRON_SCHEDULE` | *(unset)* | Unset = run once and exit; empty = stay alive; cron expression = scheduled |
 
 ---
 
@@ -239,16 +243,26 @@ uv sync
 uv run winnow
 ```
 
-Requires Python 3.13+ and [uv](https://astral.sh/uv/). An NVIDIA GPU is strongly recommended — CPU mode works but embedding computation is significantly slower.
+Requires Python 3.13+ and [uv](https://astral.sh/uv). An NVIDIA, AMD, or Intel GPU is recommended — CPU mode works but embedding computation is slower.
+
+When run with a terminal attached, winnow starts an interactive session: select which people to process and choose a strategy (auto, standard, broad, or a custom count) per person. Without a TTY — Docker, cron, or `AUTO_MODE=true` — it processes all people automatically using the configured defaults.
 
 ---
 
 ## Requirements
 
 - **Immich** v1.106+
-- **Frigate** v0.16+ (face mode only — object mode has no Frigate API dependency)
-- **NVIDIA GPU** recommended (CUDA 12.x)
-- **Python 3.13+**
+- **Frigate** v0.16+ (face mode only — object mode has no Frigate dependency)
+- **GPU** recommended: NVIDIA (CUDA), AMD (ROCm), or Intel (Arc / iGPU via OpenVINO)
+- **Python** 3.13+
+
+---
+
+## Getting Help
+
+- **[GitHub Discussions](https://github.com/sudolulo/winnow/discussions)** — questions, setup help, and general discussion
+- **[Wiki](https://github.com/sudolulo/winnow/wiki)** — setup guide, troubleshooting, and FAQ
+- **[Issues](https://github.com/sudolulo/winnow/issues)** — bugs and feature requests only
 
 ---
 

SECURITY.md

@@ -0,0 +1,17 @@
+# Security Policy
+
+## Supported Versions
+
+Only the latest release is supported with security fixes.
+
+## Reporting a Vulnerability
+
+Please do **not** open a public GitHub issue for security vulnerabilities.
+
+Email **holden@arch.fyi** with:
+
+- A description of the vulnerability and its potential impact
+- Steps to reproduce or a proof of concept
+- Any suggested fix, if you have one
+
+You will receive an acknowledgement within 48 hours. If the vulnerability is confirmed, a fix will be released as soon as possible and you will be credited in the changelog unless you prefer otherwise.

compose.yml

@@ -38,6 +38,7 @@ services:
 
       # ── Caching & Models ──────────────────────────────────────────────────
       # - FORCE_CPU=true              # Disable GPU, fall back to CPU
+      # - OPENVINO_DEVICE=GPU         # Intel variant only: use Arc/iGPU instead of CPU (default: CPU)
       # - ENABLE_CACHE=false          # Disable embedding cache (default: true)
       - CACHE_DIR=/app/.if_cache
       - HF_HOME=/models/huggingface
@@ -63,6 +64,9 @@ services:
       - /path/to/winnow/cache:/app/.if_cache
       - /path/to/winnow/output:/app/frigate_train
     restart: unless-stopped
+
+    # ── GPU device passthrough ─────────────────────────────────────────────────
+    # NVIDIA (default — requires nvidia-container-toolkit):
     deploy:
       resources:
         reservations:
@@ -70,3 +74,18 @@ services:
             - driver: nvidia
               count: all
               capabilities: [gpu]
+    #
+    # AMD ROCm — replace the deploy block above with:
+    #   devices:
+    #     - /dev/kfd
+    #     - /dev/dri
+    #   group_add:
+    #     - video
+    #     - render
+    #
+    # Intel Arc / iGPU — replace the deploy block above with:
+    #   devices:
+    #     - /dev/dri
+    #   group_add:
+    #     - render
+    #   Also set: OPENVINO_DEVICE=GPU in the environment section above.

pyproject-cpu.toml

@@ -1,6 +1,6 @@
 [project]
 name = "winnow"
-version = "0.2.10"
+version = "0.2.13"
 description = "Immich to Frigate training sets"
 license = "AGPL-3.0-or-later"
 requires-python = ">=3.13"
@@ -25,7 +25,7 @@ dependencies = [
     "rich>=14.2.0",
     "torch>=2.12.0",
     "torchvision>=0.27.0",
-    "transformers>=4.57.6",
+    "transformers>=5.12.0",
     "ultralytics>=8.4.66",
 ]
 

pyproject-intel.toml

@@ -0,0 +1,103 @@
+[project]
+name = "winnow"
+version = "0.2.13"
+description = "Immich to Frigate training sets"
+license = "AGPL-3.0-or-later"
+requires-python = ">=3.13"
+authors = [{ name = "Holden Salomon", email = "holden@arch.fyi" }]
+keywords = ["immich", "frigate", "face-recognition", "training-data", "arcface", "insightface"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+]
+dependencies = [
+    "croniter>=5.0.2",
+    "insightface>=0.7.3",
+    "numpy>=2.2.6",
+    "onnxruntime-openvino>=1.20.0",
+    "opencv-python-headless>=4.12.0.88",
+    "pillow>=12.1.0",
+    "python-dotenv>=1.2.1",
+    "requests>=2.32.5",
+    "rich>=14.2.0",
+    "torch>=2.12.0",
+    "torchvision>=0.27.0",
+    "transformers>=5.12.0",
+    "ultralytics>=8.4.66",
+]
+
+[project.scripts]
+winnow = "winnow.cli:main"
+
+[project.urls]
+Repository = "https://github.com/sudolulo/winnow"
+
+[tool.uv]
+conflicts = [
+    [
+        { package = "onnxruntime" },
+        { package = "onnxruntime-gpu" },
+        { package = "onnxruntime-openvino" },
+    ],
+]
+required-environments = [
+    "sys_platform == 'linux' and platform_machine == 'x86_64'",
+]
+
+[tool.uv.sources]
+torch = [
+    { index = "pytorch-cpu", marker = "sys_platform == 'linux' and platform_machine == 'x86_64'" },
+]
+torchvision = [
+    { index = "pytorch-cpu", marker = "sys_platform == 'linux' and platform_machine == 'x86_64'" },
+]
+
+[[tool.uv.index]]
+name = "pytorch-cpu"
+url = "https://download.pytorch.org/whl/cpu"
+explicit = true
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.15.17",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["winnow"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[tool.deptry]
+pep621_dev_dependency_groups = ["dev"]
+
+[tool.deptry.package_module_name_map]
+pillow = "PIL"
+opencv-python-headless = "cv2"
+python-dotenv = "dotenv"
+insightface = "insightface"
+numpy = "numpy"
+onnxruntime-openvino = "onnxruntime"
+requests = "requests"
+rich = "rich"
+torch = "torch"
+transformers = "transformers"
+ultralytics = "ultralytics"
+
+[tool.deptry.per_rule_ignores]
+DEP002 = ["onnxruntime-openvino"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

pyproject-rocm.toml

@@ -0,0 +1,103 @@
+[project]
+name = "winnow"
+version = "0.2.13"
+description = "Immich to Frigate training sets"
+license = "AGPL-3.0-or-later"
+requires-python = ">=3.13"
+authors = [{ name = "Holden Salomon", email = "holden@arch.fyi" }]
+keywords = ["immich", "frigate", "face-recognition", "training-data", "arcface", "insightface"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+]
+dependencies = [
+    "croniter>=5.0.2",
+    "insightface>=0.7.3",
+    "numpy>=2.2.6",
+    "onnxruntime-rocm>=1.16.0",
+    "opencv-python-headless>=4.12.0.88",
+    "pillow>=12.1.0",
+    "python-dotenv>=1.2.1",
+    "requests>=2.32.5",
+    "rich>=14.2.0",
+    "torch>=2.5.0",
+    "torchvision>=0.20.0",
+    "transformers>=5.12.0",
+    "ultralytics>=8.4.66",
+]
+
+[project.scripts]
+winnow = "winnow.cli:main"
+
+[project.urls]
+Repository = "https://github.com/sudolulo/winnow"
+
+[tool.uv]
+index-strategy = "unsafe-best-match"
+conflicts = [
+    [
+        { package = "onnxruntime" },
+        { package = "onnxruntime-gpu" },
+        { package = "onnxruntime-rocm" },
+    ],
+]
+required-environments = [
+    "sys_platform == 'linux' and platform_machine == 'x86_64'",
+]
+
+[tool.uv.sources]
+torch = [
+    { index = "pytorch-rocm63", marker = "sys_platform == 'linux' and platform_machine == 'x86_64'" },
+]
+torchvision = [
+    { index = "pytorch-rocm63", marker = "sys_platform == 'linux' and platform_machine == 'x86_64'" },
+]
+
+[[tool.uv.index]]
+name = "pytorch-rocm63"
+url = "https://download.pytorch.org/whl/rocm6.3"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.15.17",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["winnow"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[tool.deptry]
+pep621_dev_dependency_groups = ["dev"]
+
+[tool.deptry.package_module_name_map]
+pillow = "PIL"
+opencv-python-headless = "cv2"
+python-dotenv = "dotenv"
+insightface = "insightface"
+numpy = "numpy"
+onnxruntime-rocm = "onnxruntime"
+requests = "requests"
+rich = "rich"
+torch = "torch"
+transformers = "transformers"
+ultralytics = "ultralytics"
+
+[tool.deptry.per_rule_ignores]
+DEP002 = ["onnxruntime-rocm"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "winnow"
-version = "0.2.10"
-description = "Immich to Frigate training sets"
+version = "0.4.2"
+description = "Selects diverse, high-quality photos from Immich as training data for Frigate face recognition and object classification."
 license = "AGPL-3.0-or-later"
 requires-python = ">=3.13"
 authors = [{ name = "Holden Salomon", email = "holden@arch.fyi" }]
@@ -9,6 +9,7 @@ keywords = ["immich", "frigate", "face-recognition", "training-data", "arcface",
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
     "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
     "Programming Language :: Python :: 3.13",
     "Topic :: Scientific/Engineering :: Image Recognition",
@@ -28,7 +29,7 @@ dependencies = [
     "rich>=14.2.0",
     "torch>=2.12.0",
     "torchvision>=0.27.0",
-    "transformers>=4.57.6",
+    "transformers>=5.12.0",
     "ultralytics>=8.4.66",
 ]
 
@@ -37,9 +38,16 @@ winnow = "winnow.cli:main"
 
 [project.urls]
 Repository = "https://github.com/sudolulo/winnow"
+Changelog = "https://github.com/sudolulo/winnow/blob/main/CHANGELOG.md"
+Documentation = "https://github.com/sudolulo/winnow/wiki"
 
 [tool.uv]
-override-dependencies = ["onnxruntime>=1.23.2"]
+conflicts = [
+    [
+        { package = "onnxruntime" },
+        { package = "onnxruntime-gpu" },
+    ],
+]
 required-environments = [
     "sys_platform == 'linux' and platform_machine == 'x86_64'",
     "sys_platform == 'linux' and platform_machine == 'aarch64'",

scripts/benchmark.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""
+winnow inference benchmark: GPU vs CPU throughput.
+
+Measures InsightFace (face mode) and SigLIP (object mode) latency and
+throughput. Run with FORCE_CPU=true for CPU-only baseline.
+
+Usage inside container:
+    # GPU mode:
+    docker exec winnow python /app/scripts/benchmark.py
+
+    # CPU mode:
+    docker exec -e FORCE_CPU=true winnow python /app/scripts/benchmark.py
+"""
+
+import os
+import sys
+import time
+
+import numpy as np
+from PIL import Image, ImageDraw
+
+
+def _mode_label() -> str:
+    if os.getenv("FORCE_CPU", "").lower() in ("true", "1", "yes"):
+        return "CPU (FORCE_CPU=true)"
+    return "GPU (auto)"
+
+
+def make_face_image(size: int = 640) -> Image.Image:
+    """Synthetic face-like image: skin-tone rectangle with landmark blobs."""
+    img = Image.new("RGB", (size, size), (200, 170, 140))
+    draw = ImageDraw.Draw(img)
+    # Head oval
+    cx, cy = size // 2, size // 2
+    hw, hh = int(size * 0.3), int(size * 0.38)
+    draw.ellipse([cx - hw, cy - hh, cx + hw, cy + hh], fill=(220, 185, 155))
+    # Eyes
+    for ex in [cx - int(size * 0.1), cx + int(size * 0.1)]:
+        ey = cy - int(size * 0.05)
+        r = max(4, size // 40)
+        draw.ellipse([ex - r, ey - r, ex + r, ey + r], fill=(40, 30, 20))
+    # Nose
+    draw.ellipse([cx - 5, cy + 5, cx + 5, cy + 15], fill=(180, 140, 110))
+    # Mouth
+    draw.arc([cx - 20, cy + 25, cx + 20, cy + 45], start=0, end=180, fill=(160, 80, 80), width=3)
+    return img
+
+
+def make_random_image(width: int = 224, height: int = 224) -> Image.Image:
+    rng = np.random.default_rng(42)
+    return Image.fromarray(rng.integers(0, 256, (height, width, 3), dtype=np.uint8), "RGB")
+
+
+def _stats(times_s: list[float]) -> dict:
+    arr = np.array(times_s) * 1000  # ms
+    return {
+        "median_ms": float(np.median(arr)),
+        "mean_ms": float(np.mean(arr)),
+        "min_ms": float(np.min(arr)),
+        "p95_ms": float(np.percentile(arr, 95)),
+        "ips": 1000.0 / float(np.median(arr)),
+    }
+
+
+def bench_insightface(n_warmup: int = 5, n_runs: int = 30) -> None:
+    import cv2
+
+    import winnow.embeddings as emb_mod
+    from winnow.embeddings import get_insightface_app
+
+    # Reset singleton so we get a fresh load
+    emb_mod._insightface_app = None
+    emb_mod._insightface_loaded = False
+
+    print("  Loading model...")
+    t_load = time.perf_counter()
+    app = get_insightface_app()
+    load_s = time.perf_counter() - t_load
+
+    if app is None:
+        print("  SKIP: InsightFace failed to load")
+        return
+
+    img_pil = make_face_image(640)
+    img_bgr = cv2.cvtColor(np.asarray(img_pil), cv2.COLOR_RGB2BGR)
+
+    # Warmup
+    for _ in range(n_warmup):
+        app.get(img_bgr)
+
+    # Timed — single image 640×640
+    times: list[float] = []
+    for _ in range(n_runs):
+        t0 = time.perf_counter()
+        app.get(img_bgr)
+        times.append(time.perf_counter() - t0)
+
+    s = _stats(times)
+    print(f"  Model load time : {load_s:.2f} s")
+    print("  Input size      : 640×640")
+    print(f"  Runs            : {n_runs} (after {n_warmup} warmup)")
+    print(f"  Median latency  : {s['median_ms']:.1f} ms")
+    print(f"  Mean / p95      : {s['mean_ms']:.1f} ms / {s['p95_ms']:.1f} ms")
+    print(f"  Min latency     : {s['min_ms']:.1f} ms")
+    print(f"  Throughput      : {s['ips']:.1f} images/s")
+
+    # Also test at 320×320
+    img_sm = make_face_image(320)
+    img_sm_bgr = cv2.cvtColor(np.asarray(img_sm), cv2.COLOR_RGB2BGR)
+    for _ in range(n_warmup):
+        app.get(img_sm_bgr)
+    times_sm: list[float] = []
+    for _ in range(n_runs):
+        t0 = time.perf_counter()
+        app.get(img_sm_bgr)
+        times_sm.append(time.perf_counter() - t0)
+    s2 = _stats(times_sm)
+    print(f"  320×320 median  : {s2['median_ms']:.1f} ms  ({s2['ips']:.1f} img/s)")
+
+
+def bench_siglip(
+    n_warmup: int = 3,
+    n_runs: int = 20,
+    batch_sizes: tuple = (1, 4, 8, 16, 32),
+) -> None:
+    import torch
+
+    import winnow.embeddings as emb_mod
+    emb_mod._siglip_model = None
+    emb_mod._siglip_processor = None
+    emb_mod._siglip_loaded = False
+
+    print("  Loading model...")
+    t_load = time.perf_counter()
+    model, processor = emb_mod.get_siglip_model()
+    load_s = time.perf_counter() - t_load
+
+    if model is None:
+        print("  SKIP: SigLIP failed to load")
+        return
+
+    device = next(model.parameters()).device
+    print(f"  Model load time : {load_s:.2f} s  (device: {device})")
+
+    print(f"  {'Batch':>5}  {'ms/batch':>10}  {'ms/img':>8}  {'img/s':>8}  {'p95/img':>9}")
+    for bs in batch_sizes:
+        imgs = [make_random_image(224, 224) for _ in range(bs)]
+        inputs = processor(images=imgs, return_tensors="pt")
+        inputs = {k: v.to(device) for k, v in inputs.items()}
+
+        # Warmup
+        for _ in range(n_warmup):
+            with torch.no_grad():
+                model(**inputs)
+        if str(device) != "cpu":
+            torch.cuda.synchronize()
+
+        times: list[float] = []
+        for _ in range(n_runs):
+            if str(device) != "cpu":
+                torch.cuda.synchronize()
+            t0 = time.perf_counter()
+            with torch.no_grad():
+                model(**inputs)
+            if str(device) != "cpu":
+                torch.cuda.synchronize()
+            times.append(time.perf_counter() - t0)
+
+        s = _stats(times)
+        print(
+            f"  {bs:>5}  {s['median_ms']:>10.1f}  {s['median_ms']/bs:>8.2f}"
+            f"  {bs * 1000 / s['median_ms']:>8.1f}  {s['p95_ms']/bs:>9.2f}"
+        )
+
+
+def main() -> None:
+    print("=" * 56)
+    print("  winnow inference benchmark")
+    print(f"  Mode: {_mode_label()}")
+    print("=" * 56)
+    print()
+
+    print("── InsightFace Buffalo_L  (face detection + ArcFace) ──")
+    bench_insightface()
+    print()
+
+    print("── SigLIP google/siglip-base-patch16-224  (objects) ───")
+    bench_siglip()
+    print()
+
+
+if __name__ == "__main__":
+    # Add winnow to path when run directly inside container
+    sys.path.insert(0, "/app")
+    main()

tests/test_config.py

@@ -17,11 +17,12 @@ def test_config_loads_defaults(monkeypatch):
     assert cfg.API_KEY == "test-key"
     assert cfg.OUTPUT_DIR == "./frigate_train"
     assert cfg.YEARS_FILTER == 10
-    assert cfg.MIN_FACE_WIDTH == 50
+    assert cfg.MIN_FACE_WIDTH == 90
     assert cfg.MIN_FACE_COUNT == 0
-    assert cfg.BLUR_THRESHOLD == 100.0
+    assert cfg.BLUR_THRESHOLD == 120.0
     assert cfg.MIN_CONFIDENCE == 0.7
     assert cfg.MAX_AUTO_IMAGES == 80
+    assert cfg.QUALITY_REPLACEMENT is True
     assert cfg.FACE_MARGIN == 0.15
     assert cfg.USE_FULL_RESOLUTION is True
     assert cfg.ENABLE_FACE_ALIGNMENT is True
@@ -39,6 +40,7 @@ def test_config_env_overrides(monkeypatch):
     monkeypatch.setenv("BLUR_THRESHOLD", "50.0")
     monkeypatch.setenv("MIN_CONFIDENCE", "0.9")
     monkeypatch.setenv("MAX_AUTO_IMAGES", "40")
+    monkeypatch.setenv("QUALITY_REPLACEMENT", "false")
     monkeypatch.setenv("FACE_MARGIN", "0.2")
     monkeypatch.setenv("USE_FULL_RESOLUTION", "false")
     monkeypatch.setenv("ENABLE_FACE_ALIGNMENT", "false")
@@ -54,6 +56,7 @@ def test_config_env_overrides(monkeypatch):
     assert cfg.BLUR_THRESHOLD == 50.0
     assert cfg.MIN_CONFIDENCE == 0.9
     assert cfg.MAX_AUTO_IMAGES == 40
+    assert cfg.QUALITY_REPLACEMENT is False
     assert cfg.FACE_MARGIN == 0.2
     assert cfg.USE_FULL_RESOLUTION is False
     assert cfg.ENABLE_FACE_ALIGNMENT is False

tests/test_quality.py

@@ -134,6 +134,16 @@ def test_assess_quality_passes_good_image():
     img = _noisy_color_image()
     result = assess_quality(img, face_bbox=(10, 10, 110, 110), confidence=0.9)
     assert result.passed
+    assert result.blur_score is not None
+    assert result.blur_score > 0
+
+
+def test_assess_quality_blur_score_is_low_for_flat_image():
+    from winnow.quality import assess_quality
+    flat = _rgb_image(128, 128, 128)
+    result = assess_quality(flat)
+    assert result.blur_score is not None
+    assert result.blur_score < 1.0
 
 
 def test_assess_quality_collects_multiple_failures():

tests/test_upload_tracker.py

@@ -69,3 +69,194 @@ def test_duplicate_marks_are_idempotent():
     mark_uploaded("dup", person_name="Alice")
     mark_uploaded("dup", person_name="Alice")
     assert filter_already_uploaded(["dup", "new"]) == ["new"]
+
+
+# ── frigate_files mapping ─────────────────────────────────────────────────────
+
+def test_record_and_remove_frigate_file():
+    from winnow.upload_tracker import get_person_summary, record_frigate_file, remove_frigate_file
+    record_frigate_file("Alice", "Alice-1000.webp", "asset-a1")
+    assert "Alice-1000.webp" in get_person_summary()["Alice"]["frigate_files"]
+    remove_frigate_file("Alice", "Alice-1000.webp")
+    assert "Alice-1000.webp" not in get_person_summary()["Alice"]["frigate_files"]
+
+
+def test_remove_nonexistent_frigate_file_is_safe():
+    from winnow.upload_tracker import remove_frigate_file
+    # Should not raise even if the file was never recorded
+    remove_frigate_file("Alice", "Alice-ghost.webp")
+
+
+def test_remove_frigate_file_does_not_unmark_asset():
+    """Deleting a Frigate file should not re-expose the source asset for upload."""
+    from winnow.upload_tracker import (
+        filter_already_uploaded,
+        mark_uploaded,
+        record_frigate_file,
+        remove_frigate_file,
+    )
+    mark_uploaded("asset-a1", person_name="Alice")
+    record_frigate_file("Alice", "Alice-1000.webp", "asset-a1")
+    remove_frigate_file("Alice", "Alice-1000.webp")
+    # Asset must still be excluded — it was deliberately replaced, not lost
+    assert filter_already_uploaded(["asset-a1"]) == []
+
+
+def test_get_tracked_frigate_file_count_zero_when_empty():
+    from winnow.upload_tracker import get_tracked_frigate_file_count
+    assert get_tracked_frigate_file_count("Alice") == 0
+
+
+def test_get_tracked_frigate_file_count_counts_only_mapped():
+    """Only files explicitly recorded via record_frigate_file count toward the cap."""
+    from winnow.upload_tracker import get_tracked_frigate_file_count, mark_uploaded, record_frigate_file
+    mark_uploaded("asset-a", person_name="Alice")
+    mark_uploaded("asset-b", person_name="Alice")
+    record_frigate_file("Alice", "Alice-1000.webp", "asset-a")
+    # asset-b is uploaded but not yet mapped — does not count
+    assert get_tracked_frigate_file_count("Alice") == 1
+    record_frigate_file("Alice", "Alice-1001.webp", "asset-b")
+    assert get_tracked_frigate_file_count("Alice") == 2
+
+
+def test_get_lowest_quality_mapped_file_none_when_empty():
+    from winnow.upload_tracker import get_lowest_quality_mapped_file
+    assert get_lowest_quality_mapped_file("Alice") is None
+
+
+def test_get_lowest_quality_mapped_file_returns_lowest():
+    from winnow.upload_tracker import (
+        get_lowest_quality_mapped_file,
+        mark_uploaded,
+        record_frigate_file,
+    )
+    mark_uploaded("asset-hi", person_name="Alice", score=0.95)
+    mark_uploaded("asset-lo", person_name="Alice", score=0.71)
+    record_frigate_file("Alice", "Alice-1000.webp", "asset-hi")
+    record_frigate_file("Alice", "Alice-1001.webp", "asset-lo")
+    result = get_lowest_quality_mapped_file("Alice")
+    assert result is not None
+    frigate_filename, asset_id, score = result
+    assert frigate_filename == "Alice-1001.webp"
+    assert asset_id == "asset-lo"
+    assert score == pytest.approx(0.71, abs=0.001)
+
+
+def test_get_lowest_quality_mapped_file_skips_unscored():
+    """Files mapped without a score should not be returned as candidates."""
+    from winnow.upload_tracker import (
+        get_lowest_quality_mapped_file,
+        mark_uploaded,
+        record_frigate_file,
+    )
+    mark_uploaded("asset-scored", person_name="Alice", score=0.85)
+    mark_uploaded("asset-noscr", person_name="Alice")
+    record_frigate_file("Alice", "Alice-1000.webp", "asset-scored")
+    record_frigate_file("Alice", "Alice-1001.webp", "asset-noscr")
+    result = get_lowest_quality_mapped_file("Alice")
+    assert result is not None
+    assert result[1] == "asset-scored"  # only scored file is a candidate
+
+
+# ── get_tracked_frigate_filenames ─────────────────────────────────────────────
+
+def test_get_tracked_frigate_filenames_empty():
+    from winnow.upload_tracker import get_tracked_frigate_filenames
+    assert get_tracked_frigate_filenames("Alice") == set()
+
+
+def test_get_tracked_frigate_filenames_returns_mapped():
+    from winnow.upload_tracker import get_tracked_frigate_filenames, record_frigate_file
+    record_frigate_file("Alice", "Alice-1000.webp", "asset-a")
+    record_frigate_file("Alice", "Alice-1001.webp", "asset-b")
+    assert get_tracked_frigate_filenames("Alice") == {"Alice-1000.webp", "Alice-1001.webp"}
+
+
+def test_get_tracked_frigate_filenames_excludes_removed():
+    from winnow.upload_tracker import (
+        get_tracked_frigate_filenames,
+        record_frigate_file,
+        remove_frigate_file,
+    )
+    record_frigate_file("Alice", "Alice-1000.webp", "asset-a")
+    record_frigate_file("Alice", "Alice-1001.webp", "asset-b")
+    remove_frigate_file("Alice", "Alice-1000.webp")
+    assert get_tracked_frigate_filenames("Alice") == {"Alice-1001.webp"}
+
+
+def test_get_tracked_frigate_filenames_isolated_by_person():
+    from winnow.upload_tracker import get_tracked_frigate_filenames, record_frigate_file
+    record_frigate_file("Alice", "Alice-1000.webp", "asset-a")
+    record_frigate_file("Bob", "Bob-2000.webp", "asset-b")
+    assert get_tracked_frigate_filenames("Alice") == {"Alice-1000.webp"}
+    assert get_tracked_frigate_filenames("Bob") == {"Bob-2000.webp"}
+
+
+# ── get_lowest_quality_mapped_file with exclude ───────────────────────────────
+
+def test_get_lowest_quality_exclude_skips_specified_file():
+    from winnow.upload_tracker import (
+        get_lowest_quality_mapped_file,
+        mark_uploaded,
+        record_frigate_file,
+    )
+    mark_uploaded("asset-lo", person_name="Alice", score=0.10)
+    mark_uploaded("asset-hi", person_name="Alice", score=0.90)
+    record_frigate_file("Alice", "Alice-lo.webp", "asset-lo")
+    record_frigate_file("Alice", "Alice-hi.webp", "asset-hi")
+    result = get_lowest_quality_mapped_file("Alice", exclude={"Alice-lo.webp"})
+    assert result is not None
+    assert result[1] == "asset-hi"  # lo was excluded; hi is returned
+
+
+def test_get_lowest_quality_exclude_all_returns_none():
+    from winnow.upload_tracker import (
+        get_lowest_quality_mapped_file,
+        mark_uploaded,
+        record_frigate_file,
+    )
+    mark_uploaded("asset-a", person_name="Alice", score=0.50)
+    record_frigate_file("Alice", "Alice-a.webp", "asset-a")
+    assert get_lowest_quality_mapped_file("Alice", exclude={"Alice-a.webp"}) is None
+
+
+# ── get_most_redundant_mapped_file ────────────────────────────────────────────
+
+def test_get_most_redundant_none_when_no_frigate_scores():
+    from winnow.upload_tracker import get_most_redundant_mapped_file, mark_uploaded, record_frigate_file
+    mark_uploaded("asset-a", person_name="Alice", score=0.80)
+    record_frigate_file("Alice", "Alice-a.webp", "asset-a")
+    # blur score only, no frigate_score → no candidates
+    assert get_most_redundant_mapped_file("Alice") is None
+
+
+def test_get_most_redundant_returns_highest_frigate_score():
+    from winnow.upload_tracker import get_most_redundant_mapped_file, mark_uploaded, record_frigate_file
+    mark_uploaded("asset-novel", person_name="Alice", score=0.50, frigate_score=0.31)
+    mark_uploaded("asset-redundant", person_name="Alice", score=0.90, frigate_score=0.88)
+    record_frigate_file("Alice", "Alice-novel.webp", "asset-novel")
+    record_frigate_file("Alice", "Alice-redundant.webp", "asset-redundant")
+    result = get_most_redundant_mapped_file("Alice")
+    assert result is not None
+    frigate_filename, asset_id, score = result
+    assert frigate_filename == "Alice-redundant.webp"
+    assert asset_id == "asset-redundant"
+    assert score == pytest.approx(0.88, abs=0.001)
+
+
+def test_get_most_redundant_exclude_skips_file():
+    from winnow.upload_tracker import get_most_redundant_mapped_file, mark_uploaded, record_frigate_file
+    mark_uploaded("asset-hi", person_name="Alice", score=0.9, frigate_score=0.85)
+    mark_uploaded("asset-lo", person_name="Alice", score=0.5, frigate_score=0.40)
+    record_frigate_file("Alice", "Alice-hi.webp", "asset-hi")
+    record_frigate_file("Alice", "Alice-lo.webp", "asset-lo")
+    result = get_most_redundant_mapped_file("Alice", exclude={"Alice-hi.webp"})
+    assert result is not None
+    assert result[1] == "asset-lo"  # hi excluded; lo is next highest
+
+
+def test_get_most_redundant_exclude_all_returns_none():
+    from winnow.upload_tracker import get_most_redundant_mapped_file, mark_uploaded, record_frigate_file
+    mark_uploaded("asset-a", person_name="Alice", score=0.5, frigate_score=0.70)
+    record_frigate_file("Alice", "Alice-a.webp", "asset-a")
+    assert get_most_redundant_mapped_file("Alice", exclude={"Alice-a.webp"}) is None

uv-cpu.lock

@@ -1724,7 +1724,7 @@ wheels = [
 
 [[package]]
 name = "transformers"
-version = "5.11.0"
+version = "5.12.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "huggingface-hub" },
@@ -1737,9 +1737,9 @@ dependencies = [
     { name = "tqdm" },
     { name = "typer" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/7d/4a/2ee05f9a06bb2dd34cac951548553738a826762fb7adfa7ce256daeaeac8/transformers-5.11.0.tar.gz", hash = "sha256:1dbecade5b8a09bdf3e9e8fdfc9d312cb9eccf5a201080dc894b373f0f3eb5f4", size = 8874363, upload-time = "2026-06-10T16:31:52.441Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/0c/f9/4552e2ba55db1c943aea0d4c09a32e9cbe5445b9eabe9856900de503dc8f/transformers-5.12.0.tar.gz", hash = "sha256:f0cf42ae1464c2eb41e7e0e66d7fd4b66145f48af17093b4cc0b2e9781faa7f4", size = 8923020, upload-time = "2026-06-12T14:39:20.43Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/9b/40/30fdefda9b8aff8d36054dbb37d8e1464cc1130c29623403c3c2147bdee1/transformers-5.11.0-py3-none-any.whl", hash = "sha256:06d0a34eab529955f8e704b530663c7d6bd6f9c7a9e47a05cddb4a44e7b6566b", size = 11094597, upload-time = "2026-06-10T16:31:49.08Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/1f/d385913c38e900d23b728a4188fee625f2fccb306aeebc59be9d91404a5a/transformers-5.12.0-py3-none-any.whl", hash = "sha256:500be9eb644ede81c3103eee7687fc36d05dd75d1c76686c3820b26396fe7c7c", size = 11150246, upload-time = "2026-06-12T14:39:17.009Z" },
 ]
 
 [[package]]
@@ -1832,7 +1832,7 @@ wheels = [
 
 [[package]]
 name = "winnow"
-version = "0.2.9"
+version = "0.2.13"
 source = { editable = "." }
 dependencies = [
     { name = "croniter" },
@@ -1873,7 +1873,7 @@ requires-dist = [
     { name = "torch", marker = "platform_machine == 'x86_64' and sys_platform == 'linux'", specifier = ">=2.12.0", index = "https://download.pytorch.org/whl/cpu" },
     { name = "torchvision", marker = "platform_machine != 'x86_64' or sys_platform != 'linux'", specifier = ">=0.27.0" },
     { name = "torchvision", marker = "platform_machine == 'x86_64' and sys_platform == 'linux'", specifier = ">=0.27.0", index = "https://download.pytorch.org/whl/cpu" },
-    { name = "transformers", specifier = ">=4.57.6" },
+    { name = "transformers", specifier = ">=5.12.0" },
     { name = "ultralytics", specifier = ">=8.4.66" },
 ]
 

winnow/cli.py

@@ -12,17 +12,55 @@ from .executor import execute_jobs, upload_to_frigate
 from .immich_api import get_people
 from .jobs import _show_preview, auto_configure, interactive_configure
 from .log_config import console, setup_logging
-from .upload_tracker import get_person_summary, reset_person
+from .upload_tracker import find_by_crop_dimension, get_person_summary, reset_person
 
 logger = logging.getLogger(__name__)
 
 
+def _handle_trace_crop(size_str: str) -> None:
+    """Print tracker records whose crop dimension matches the given pixel size and exit."""
+    try:
+        size = int(size_str)
+    except ValueError:
+        rprint(f"[bold red]TRACE_CROP_SIZE must be an integer, got: {size_str!r}[/bold red]")
+        sys.exit(1)
+
+    immich_url = os.environ.get("IMMICH_URL", "").rstrip("/")
+    matches = find_by_crop_dimension(size)
+    if not matches:
+        rprint(f"[yellow]No crops with dimension {size}px found in tracker.[/yellow]")
+        rprint("[dim]Note: crop dimensions are only recorded for uploads made after this feature was added.[/dim]")
+        sys.exit(0)
+
+    rprint(f"\n[bold]Crops matching dimension {size}px:[/bold] ({len(matches)} found)\n")
+    for m in matches:
+        rprint(f"  [bold cyan]{m['person']}[/bold cyan]")
+        rprint(f"    Dimensions:   {m['width']}×{m['height']}px")
+        rprint(f"    Asset ID:     {m['asset_id']}")
+        if immich_url:
+            rprint(f"    Immich URL:   {immich_url}/photos/{m['asset_id']}")
+        blur = m.get("blur_score")
+        rprint(f"    Blur score:   {blur:.1f}" if blur is not None else "    Blur score:   unknown")
+        fscore = m.get("frigate_score")
+        rprint(f"    Frigate score: {fscore:.2f}" if fscore is not None else "    Frigate score: unknown")
+        if m.get("frigate_filename"):
+            rprint(f"    Frigate file: {m['frigate_filename']}")
+        else:
+            rprint("    Frigate file: [dim]unmapped (reconciliation race)[/dim]")
+        rprint()
+    sys.exit(0)
+
+
 def main() -> None:
     """Entry point for winnow CLI."""
     try:
         verbose = os.environ.get("VERBOSE", "").lower() in ("true", "1", "yes")
         setup_logging(verbose=verbose)
 
+        trace_size = os.environ.get("TRACE_CROP_SIZE", "").strip()
+        if trace_size:
+            _handle_trace_crop(trace_size)
+
         console.print(r"""
     [bold blue]winnow[/bold blue]
     [dim]Immich -> Frigate Training Data Curator[/dim]

winnow/config.py

@@ -26,10 +26,13 @@ class _Config:
     YEARS_FILTER: int = 10
 
     # Quality filtering
-    MIN_FACE_WIDTH: int = 50
-    BLUR_THRESHOLD: float = 100.0
+    MIN_FACE_WIDTH: int = 90
+    BLUR_THRESHOLD: float = 120.0
     MIN_CONFIDENCE: float = 0.7
     MAX_AUTO_IMAGES: int = 80
+    QUALITY_REPLACEMENT: bool = True
+    FRIGATE_SCORE_CEILING: float = 0.0
+    ENABLE_FRIGATE_SCORES: bool = True
 
     # People filtering
     MIN_FACE_COUNT: int = 0
@@ -55,11 +58,14 @@ class _Config:
         self.API_KEY = os.getenv("API_KEY")
         self.OUTPUT_DIR = os.getenv("OUTPUT_DIR", "./frigate_train")
         self.YEARS_FILTER = int(os.getenv("YEARS_FILTER", "10"))
-        self.MIN_FACE_WIDTH = int(os.getenv("MIN_FACE_WIDTH", "50"))
+        self.MIN_FACE_WIDTH = int(os.getenv("MIN_FACE_WIDTH", "90"))
         self.MIN_FACE_COUNT = int(os.getenv("MIN_FACE_COUNT", "0"))
-        self.BLUR_THRESHOLD = float(os.getenv("BLUR_THRESHOLD", "100.0"))
+        self.BLUR_THRESHOLD = float(os.getenv("BLUR_THRESHOLD", "120.0"))
         self.MIN_CONFIDENCE = float(os.getenv("MIN_CONFIDENCE", "0.7"))
         self.MAX_AUTO_IMAGES = int(os.getenv("MAX_AUTO_IMAGES", "80"))
+        self.QUALITY_REPLACEMENT = os.getenv("QUALITY_REPLACEMENT", "true").lower() in ("true", "1", "yes")
+        self.FRIGATE_SCORE_CEILING = float(os.getenv("FRIGATE_SCORE_CEILING", "0.0"))
+        self.ENABLE_FRIGATE_SCORES = os.getenv("ENABLE_FRIGATE_SCORES", "true").lower() in ("true", "1", "yes")
         self.FACE_MARGIN = float(os.getenv("FACE_MARGIN", "0.15"))
         self.USE_FULL_RESOLUTION = os.getenv("USE_FULL_RESOLUTION", "true").lower() in ("true", "1", "yes")
         self.ENABLE_FACE_ALIGNMENT = os.getenv("ENABLE_FACE_ALIGNMENT", "true").lower() in ("true", "1", "yes")

winnow/diversity.py

@@ -203,64 +203,72 @@ def _select_by_embedding(
     else:
         candidates = assets
 
-    # --- Phase 1: Concurrent thumbnail download ---
+    # --- Phases 1-4: Batched download → quality filter → crop → embed ---
+    # Process in bounded batches so at most _BATCH decoded images live in RAM
+    # at once. With 472 candidates each thumbnail is ~3-8 MB decoded; loading
+    # all at once easily exhausts a 4 GB container limit on CPU.
     from concurrent.futures import ThreadPoolExecutor, as_completed
 
-    thumbnail_map: dict[str, Image.Image] = {}
-    with ThreadPoolExecutor(max_workers=8) as pool:
-        futures = {pool.submit(_fetch_thumbnail, a["id"]): a for a in candidates}
-        for i, future in enumerate(as_completed(futures)):
-            if progress_callback:
-                progress_callback(i, len(candidates))
-            asset = futures[future]
-            try:
-                img = future.result()
-                if img is not None:
-                    thumbnail_map[asset["id"]] = img
-            except Exception:
-                continue
-
-    # --- Phase 2-4: Quality filter → Crop → Embed ---
+    _BATCH = 32
     embeddings, valid_candidates, confidence_scores = [], [], []
     quality_filtered = 0
+    processed = 0
 
-    for asset in candidates:
-        img = thumbnail_map.get(asset["id"])
-        if img is None:
-            continue
+    for batch_start in range(0, len(candidates), _BATCH):
+        batch = candidates[batch_start : batch_start + _BATCH]
 
-        confidence = _get_face_confidence(asset, person_id=person_id)
+        # Download this batch concurrently
+        batch_images: dict[str, Image.Image] = {}
+        with ThreadPoolExecutor(max_workers=min(8, len(batch))) as pool:
+            futures = {pool.submit(_fetch_thumbnail, a["id"]): a for a in batch}
+            for future in as_completed(futures):
+                asset = futures[future]
+                try:
+                    img = future.result()
+                    if img is not None:
+                        batch_images[asset["id"]] = img
+                except Exception as e:
+                    logger.debug(f"Failed to fetch thumbnail for {asset['id']}: {e}")
+                    continue
 
-        # Quality gate: filter before expensive embedding computation
-        if entity_type == "face":
-            face_bbox = _get_face_bbox(asset, person_id=person_id)
-            quality = assess_quality(
-                img,
-                face_bbox=face_bbox,
-                confidence=confidence,
-                blur_threshold=Config.BLUR_THRESHOLD,
-                min_face_px=Config.MIN_FACE_WIDTH,
-                min_confidence=Config.MIN_CONFIDENCE,
-            )
-            if not quality.passed:
-                quality_filtered += 1
-                logger.debug(f"Quality filtered {asset['id']}: {quality.reason}")
+        # Process each image; batch_images goes out of scope after this loop,
+        # bounding peak thumbnail memory to _BATCH images per iteration.
+        for asset in batch:
+            img = batch_images.get(asset["id"])
+            processed += 1
+            if progress_callback:
+                progress_callback(processed, len(candidates))
+            if img is None:
                 continue
 
-            # Crop the target person's face before embedding
-            face_crop = _crop_face_from_thumbnail(img, asset, person_id=person_id)
-            embed_img = face_crop if face_crop is not None else img
-        else:
-            embed_img = img
+            confidence = _get_face_confidence(asset, person_id=person_id)
 
-        emb = get_embedding(embed_img, entity_type, asset_id=asset["id"])
-        if emb is not None:
-            embeddings.append(emb)
-            valid_candidates.append(asset)
-            confidence_scores.append(confidence)
+            if entity_type == "face":
+                face_bbox = _get_face_bbox(asset, person_id=person_id)
+                quality = assess_quality(
+                    img,
+                    face_bbox=face_bbox,
+                    confidence=confidence,
+                    blur_threshold=Config.BLUR_THRESHOLD,
+                    min_face_px=Config.MIN_FACE_WIDTH,
+                    min_confidence=Config.MIN_CONFIDENCE,
+                )
+                if not quality.passed:
+                    quality_filtered += 1
+                    logger.debug(f"Quality filtered {asset['id']}: {quality.reason}")
+                    continue
 
-    if progress_callback:
-        progress_callback(len(candidates), len(candidates))
+                asset["quality_score"] = quality.blur_score
+                face_crop = _crop_face_from_thumbnail(img, asset, person_id=person_id)
+                embed_img = face_crop if face_crop is not None else img
+            else:
+                embed_img = img
+
+            emb = get_embedding(embed_img, entity_type, asset_id=asset["id"])
+            if emb is not None:
+                embeddings.append(emb)
+                valid_candidates.append(asset)
+                confidence_scores.append(confidence)
 
     if quality_filtered > 0:
         logger.info(f"Quality filtering removed {quality_filtered} images.")

winnow/embeddings.py

@@ -85,15 +85,16 @@ def get_insightface_app():
         return _insightface_app
     _insightface_loaded = True
 
-    # Preload CUDA/cuDNN DLLs BEFORE any ORT InferenceSession is created
-    _preload_cuda_libs()
-
     ctx_id = -1
     insightface_home = os.environ.get("INSIGHTFACE_HOME", os.path.expanduser("~/.insightface"))
     try:
         import onnxruntime as ort
         from insightface.app import FaceAnalysis
 
+        # Preload CUDA/cuDNN DLLs before any ORT InferenceSession is created.
+        # Silently no-ops on ROCm/Intel builds where preload_dlls() is absent.
+        _preload_cuda_libs()
+
         # Disk cache check — lets the user know whether a download is coming
         buffalo_path = Path(insightface_home) / "models" / "buffalo_l"
         if buffalo_path.exists() and any(buffalo_path.iterdir()):
@@ -110,18 +111,35 @@ def get_insightface_app():
             "ROCmExecutionProvider",
             "MPSExecutionProvider",
             "CoreMLExecutionProvider",
+            "OpenVINOExecutionProvider",
         }
         has_gpu_provider = bool(gpu_providers & set(providers))
         ctx_id = -1 if _is_force_cpu() else (0 if has_gpu_provider else -1)
 
+        # For OpenVINO EP, inject device_type from env var (default CPU; set GPU for Intel Arc/iGPU)
+        has_openvino = "OpenVINOExecutionProvider" in providers
+        if has_openvino:
+            openvino_device = os.getenv("OPENVINO_DEVICE", "CPU")
+            providers = [
+                ("OpenVINOExecutionProvider", {"device_type": openvino_device})
+                if p == "OpenVINOExecutionProvider" else p
+                for p in providers
+            ]
+            logger.debug(f"OpenVINO EP: device_type={openvino_device}")
+
         if not has_gpu_provider and not _is_force_cpu():
             logger.warning(
                 "No GPU execution provider found — running InsightFace on CPU. "
-                "If you have an NVIDIA GPU, ensure the NVIDIA Container Toolkit is "
-                "installed and the container has GPU access (deploy.resources in compose)."
+                "Ensure the container has GPU access and the correct variant image is used "
+                "(gpu for NVIDIA, rocm for AMD, intel for Intel Arc/iGPU)."
             )
 
-        device_str = "GPU" if ctx_id >= 0 else "CPU"
+        if ctx_id < 0:
+            device_str = "CPU"
+        elif has_openvino:
+            device_str = f"OpenVINO ({os.getenv('OPENVINO_DEVICE', 'CPU')})"
+        else:
+            device_str = "GPU"
         logger.info(f"InsightFace Buffalo_L: loading into memory on {device_str}...")
 
         t0 = time.time()
@@ -223,11 +241,14 @@ def get_siglip_model():
 
         _siglip_model.eval()
 
-        # Move to GPU if available
+        # Move to GPU if available (ROCm builds expose torch.cuda.is_available() == True)
         if not _is_force_cpu():
             if torch.cuda.is_available():
                 _siglip_model = _siglip_model.cuda()
                 device_name = "CUDA GPU"
+            elif hasattr(torch, "xpu") and torch.xpu.is_available():
+                _siglip_model = _siglip_model.to("xpu")
+                device_name = "Intel XPU"
             elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
                 _siglip_model = _siglip_model.to("mps")
                 device_name = "Apple MPS"

winnow/executor.py

@@ -3,6 +3,7 @@
 import logging
 import os
 import shutil
+import time
 from io import BytesIO
 from urllib.parse import quote
 
@@ -12,14 +13,93 @@ from rich import print as rprint
 from rich.progress import BarColumn, Progress, SpinnerColumn, TaskProgressColumn, TextColumn
 
 from .config import Config, get_headers
+from .frigate_api import (
+    delete_frigate_person_files,
+    get_all_frigate_person_files,
+    get_frigate_person_files,
+    recognize_face,
+)
 from .image_processing import process_face_mode, process_full_mode, process_object_mode
 from .immich_api import fetch_face_data, fetch_full_image
 from .log_config import console
-from .upload_tracker import mark_rejected, mark_uploaded
+from .quality import assess_quality
+from .upload_tracker import (
+    get_lowest_quality_mapped_file,
+    get_most_redundant_mapped_file,
+    get_tracked_frigate_file_count,
+    get_tracked_frigate_filenames,
+    has_frigate_scores,
+    mark_rejected,
+    mark_uploaded,
+    record_frigate_file,
+    remove_frigate_file,
+)
 
 logger = logging.getLogger(__name__)
 
 
+def _reconcile_frigate_mappings(
+    person_name: str,
+    known_files_before: set[str],
+    uploaded: list[tuple[str, str | None]],
+) -> None:
+    """Map Frigate filenames to asset IDs after a batch of uploads.
+
+    Polls until all expected new files appear in the Frigate API, then maps
+    them to asset IDs by filename timestamp order (Frigate processes the
+    upload queue in FIFO order, so earlier uploads get earlier timestamps).
+
+    KNOWN LIMITATION — race condition with external uploads:
+    If another client uploads a face file for this person concurrently, the
+    count of new files will exceed `len(uploaded)` and we bail out entirely
+    (the "> target" branch). That's safe — we never record a wrong mapping —
+    but those uploads become permanently unmapped (they won't be eligible for
+    quality replacement). The right fix is a Frigate API that returns the
+    filename in the upload response, removing the need for any post-upload
+    diffing. Until then, the external-upload guard keeps mappings correct at
+    the cost of occasionally missing them when another client is active.
+    """
+    target = len(uploaded)
+    current_files: set[str] = set()
+
+    for delay in (1, 2, 4, 8):
+        time.sleep(delay)
+        fresh = get_frigate_person_files(person_name)
+        if fresh is None:
+            logger.warning(
+                f"{person_name}: Frigate API unreachable during mapping reconciliation"
+                " — quality replacement won't target these files"
+            )
+            return
+        current_files = set(fresh)
+        if len(current_files - known_files_before) >= target:
+            break
+
+    new_files = current_files - known_files_before
+
+    if len(new_files) == target:
+        def _ts(fname: str) -> float:
+            try:
+                return float(fname.rsplit("_", 1)[-1].replace(".webp", ""))
+            except (ValueError, IndexError):
+                return 0.0
+
+        for (fname, asset_id), frigate_file in zip(uploaded, sorted(new_files, key=_ts)):
+            if asset_id:
+                record_frigate_file(person_name, frigate_file, asset_id)
+        logger.debug(f"{person_name}: batch-mapped {target} Frigate file(s)")
+    elif len(new_files) > target:
+        logger.info(
+            f"{person_name}: {len(new_files)} new Frigate files for {target} uploads"
+            " (external upload detected) — skipping file mapping"
+        )
+    else:
+        logger.warning(
+            f"{person_name}: only {len(new_files)} of {target} expected Frigate files"
+            " appeared after reconciliation — mapping skipped"
+        )
+
+
 def _enrich_asset_with_face_data(asset: dict, person: dict) -> dict:
     """Enrich an asset dict with face bounding box data from the Immich faces API.
 
@@ -97,9 +177,10 @@ def execute_jobs(jobs: list[dict]) -> None:
                 shutil.rmtree(person_dir)
             os.makedirs(person_dir, exist_ok=True)
 
-            # Track filename → asset_id and filename → confidence score
+            # Track filename → asset_id, filename → confidence score, filename → crop dims
             asset_map: dict[str, str] = {}
             score_map: dict[str, float | None] = {}
+            dims_map: dict[str, tuple[int, int]] = {}
 
             count = 0
             for asset in assets:
@@ -108,6 +189,17 @@ def execute_jobs(jobs: list[dict]) -> None:
                     # from the Immich faces API (not included in search/metadata results)
                     if mode == "face":
                         asset = _enrich_asset_with_face_data(asset, person)
+                        # Skip download if detection confidence already disqualifies
+                        # the asset — avoids fetching a large image we'll discard.
+                        conf = asset.get("face_confidence")
+                        if conf is not None and conf < Config.MIN_CONFIDENCE:
+                            progress.console.print(
+                                f"[yellow]Skipped {asset['id']}"
+                                f" (detection confidence {conf:.2f} < {Config.MIN_CONFIDENCE})[/yellow]"
+                            )
+                            progress.advance(job_task)
+                            progress.advance(overall_task)
+                            continue
 
                     # Use full-resolution for final output when configured
                     if use_full_res:
@@ -134,7 +226,24 @@ def execute_jobs(jobs: list[dict]) -> None:
                             # Record which asset produced which output file
                             filename = f"{count}.jpg"
                             asset_map[filename] = asset["id"]
-                            score_map[filename] = asset.get("face_confidence")
+                            score_map[filename] = asset.get("quality_score")
+                            if mode == "face" and isinstance(saved, tuple):
+                                dims_map[filename] = saved
+                            # Time-spread path: compute blur score from the downloaded
+                            # image. Cap at 1440px so the scale matches the preview
+                            # thumbnails the embedding path uses for scoring — Laplacian
+                            # variance grows with resolution, making full-res and
+                            # thumbnail scores incomparable if left uncapped.
+                            if mode == "face" and score_map[filename] is None:
+                                try:
+                                    score_img = img.convert("RGB") if img.mode != "RGB" else img
+                                    if score_img.width > 1440 or score_img.height > 1440:
+                                        score_img = score_img.copy()
+                                        score_img.thumbnail((1440, 1440), Image.LANCZOS)
+                                    score_map[filename] = assess_quality(score_img).blur_score
+                                except Exception as exc:
+                                    logger.debug(f"Quality score fallback for {asset['id']}: {exc}")
+                                    score_map[filename] = 0.0  # unknown quality — treat as lowest
                             # Also record object-mode variant filenames
                             if mode == "object":
                                 for f in sorted(os.listdir(person_dir)):
@@ -156,6 +265,7 @@ def execute_jobs(jobs: list[dict]) -> None:
             # Store maps on the job so upload_to_frigate can use them
             job["asset_map"] = asset_map
             job["score_map"] = score_map
+            job["dims_map"] = dims_map
 
             progress.remove_task(job_task)
 
@@ -213,6 +323,10 @@ def upload_to_frigate(jobs: list[dict]) -> None:
     uploaded, failed = 0, 0
     max_retries = 2
 
+    # Fetch all Frigate training files once — avoids one GET /api/faces per person.
+    # Falls back to per-person calls inside the loop if this fetch fails.
+    all_frigate_files = get_all_frigate_person_files()
+
     with Progress(
         SpinnerColumn(),
         TextColumn("[progress.description]{task.description}"),
@@ -236,6 +350,7 @@ def upload_to_frigate(jobs: list[dict]) -> None:
 
             asset_map = filename_to_asset_id.get(name, {})
             score_map = job.get("score_map", {})
+            dims_map = job.get("dims_map", {})
             person_files = sorted(asset_map.keys())
 
             if not person_files:
@@ -246,8 +361,169 @@ def upload_to_frigate(jobs: list[dict]) -> None:
             person_uploaded = 0
             person_failed = 0
 
+            # Snapshot live Frigate files for post-upload reconciliation diff only.
+            # effective_count is sourced from the tracker (mapped files) so that
+            # manually-added Frigate files don't consume winnow's managed quota.
+            _snapshot = (
+                all_frigate_files.get(name, []) if all_frigate_files is not None
+                else get_frigate_person_files(name)
+            )
+            if _snapshot is None:
+                # Frigate GET is down; fall back to the tracker's mapped filenames
+                # as the pre-upload baseline. reconciliation will still work unless
+                # there are concurrent manual uploads (handled by >target guard).
+                logger.warning(
+                    f"{name}: Frigate API unreachable at upload start"
+                    " — using tracker baseline for post-upload reconciliation"
+                )
+                known_frigate_files_at_start: set[str] = get_tracked_frigate_filenames(name)
+            else:
+                known_frigate_files_at_start: set[str] = set(_snapshot)
+                # Remove tracker mappings for files that no longer exist in Frigate
+                # (manually deleted, or cleaned up outside winnow). This corrects the
+                # effective_count so those slots are available for new uploads.
+                stale = get_tracked_frigate_filenames(name) - known_frigate_files_at_start
+                for stale_fn in stale:
+                    remove_frigate_file(name, stale_fn)
+                if stale:
+                    progress.console.print(
+                        f"  [dim]{name}: cleared {len(stale)} stale mapping(s)"
+                        " (file(s) no longer in Frigate)[/dim]"
+                    )
+            effective_count = get_tracked_frigate_file_count(name)
+            pre_run_count = effective_count
+            quality_replacement = job.get("config", {}).get("quality_replacement", False)
+            if Config.ENABLE_FRIGATE_SCORES and pre_run_count == 0:
+                progress.console.print(
+                    f"  [dim]{name}: first run — Frigate diversity scoring will apply from the next run[/dim]"
+                )
+            actually_uploaded: list[tuple[str, str | None]] = []
+            failed_deletes: set[str] = set()
+            min_quality_score_for_slot: float | None = None
+            person_has_fscores: bool = has_frigate_scores(name)
+
             for fname in person_files:
                 fpath = os.path.join(person_dir, fname)
+
+                # If a previous replacement delete succeeded but that upload failed,
+                # require the next candidate to beat the deleted file's score so the
+                # freed slot isn't filled with something worse than what we removed.
+                if min_quality_score_for_slot is not None:
+                    file_score = score_map.get(fname)
+                    if file_score is None or file_score <= min_quality_score_for_slot:
+                        score_str = f"{file_score:.3f}" if file_score is not None else "N/A"
+                        progress.console.print(
+                            f"    [dim]⏭  {fname}: score {score_str} ≤ freed slot floor"
+                            f" {min_quality_score_for_slot:.3f}, skipping[/dim]"
+                        )
+                        progress.advance(upload_task)
+                        continue
+
+                at_cap = effective_count >= Config.MAX_AUTO_IMAGES
+
+                # Pre-upload Frigate score — clean measurement (image not yet in training set).
+                # Called for all below-cap uploads (seeds frigate_scores for future at-cap
+                # replacement) and for at-cap uploads when scores already exist. Skipped on
+                # the first run (pre_run_count == 0) since Frigate has no model yet.
+                # recognize_face returns (face_name, score); we only use the score when the
+                # best match is for the correct person. Mismatches (or "unknown") are treated
+                # as None so a wrong-person score never drives a ceiling skip or replacement.
+                # Frigate rebuilds its model asynchronously after any delete (clear + background
+                # thread), so the first recognize call after a deletion returns None — our code
+                # handles this conservatively by skipping that candidate until the next run.
+                pre_fscore: float | None = None
+                if Config.ENABLE_FRIGATE_SCORES and pre_run_count > 0:
+                    if not at_cap or person_has_fscores:
+                        _result = recognize_face(fpath)
+                        if _result is not None and (_result[0] or "").casefold() == name.casefold():
+                            pre_fscore = _result[1]
+
+                # Ceiling check: skip if the existing training set already covers this
+                # face condition well. Applies below cap only — at cap, replacement logic
+                # drives the decision.
+                if not at_cap and Config.FRIGATE_SCORE_CEILING > 0 and pre_run_count > 0:
+                    if pre_fscore is not None and pre_fscore > Config.FRIGATE_SCORE_CEILING:
+                        progress.console.print(
+                            f"    [dim]⏭  {fname}: Frigate score {pre_fscore:.2f}"
+                            f" > ceiling {Config.FRIGATE_SCORE_CEILING:.2f}, already covered[/dim]"
+                        )
+                        progress.advance(upload_task)
+                        continue
+
+                if at_cap:
+                    if not quality_replacement:
+                        progress.console.print(f"    [dim]⏭  {fname}: at cap, quality replacement disabled[/dim]")
+                        progress.advance(upload_task)
+                        continue
+
+                    using_fscore = person_has_fscores and Config.ENABLE_FRIGATE_SCORES
+                    if using_fscore:
+                        candidate_score = pre_fscore
+                        if candidate_score is None:
+                            progress.console.print(
+                                f"    [dim]⏭  {fname}: Frigate recognize unavailable, skipping replacement[/dim]"
+                            )
+                            progress.advance(upload_task)
+                            continue
+                        # Low score = more novel than the most redundant mapped file = replace
+                        target = get_most_redundant_mapped_file(name, exclude=failed_deletes)
+                        if target is None or candidate_score >= target[2]:
+                            target_score_str = f"{target[2]:.3f}" if target is not None else "N/A"
+                            progress.console.print(
+                                f"    [dim]⏭  {fname}: frigate {candidate_score:.3f} ≥ most redundant"
+                                f" {target_score_str}, not more novel[/dim]"
+                            )
+                            progress.advance(upload_task)
+                            continue
+                        target_frigate_file, _target_asset_id, target_score = target
+                        progress.console.print(
+                            f"    🔄 {fname}: frigate {candidate_score:.3f} < {target_score:.3f},"
+                            f" replacing {target_frigate_file} (more novel)"
+                        )
+                        if delete_frigate_person_files(name, [target_frigate_file]):
+                            remove_frigate_file(name, target_frigate_file)
+                            person_has_fscores = has_frigate_scores(name)
+                            effective_count -= 1
+                            # clear any blur-mode slot floor — Frigate uses a different score metric
+                            min_quality_score_for_slot = None
+                        else:
+                            logger.warning(f"Failed to delete {target_frigate_file} for {name}, skipping replacement")
+                            failed_deletes.add(target_frigate_file)
+                            progress.advance(upload_task)
+                            continue
+                    else:
+                        candidate_score = score_map.get(fname)
+                        if candidate_score is None:
+                            progress.console.print(
+                                f"    [dim]⏭  {fname}: no quality score, skipping replacement[/dim]"
+                            )
+                            progress.advance(upload_task)
+                            continue
+                        target = get_lowest_quality_mapped_file(name, exclude=failed_deletes)
+                        if target is None or candidate_score <= target[2]:
+                            target_score_str = f"{target[2]:.3f}" if target is not None else "N/A"
+                            progress.console.print(
+                                f"    [dim]⏭  {fname}: blur {candidate_score:.3f} ≤ worst"
+                                f" {target_score_str}, skipping[/dim]"
+                            )
+                            progress.advance(upload_task)
+                            continue
+                        target_frigate_file, _target_asset_id, target_score = target
+                        progress.console.print(
+                            f"    🔄 {fname}: blur {candidate_score:.3f} > {target_score:.3f},"
+                            f" replacing {target_frigate_file}"
+                        )
+                        if delete_frigate_person_files(name, [target_frigate_file]):
+                            remove_frigate_file(name, target_frigate_file)
+                            person_has_fscores = has_frigate_scores(name)
+                            effective_count -= 1
+                            min_quality_score_for_slot = score_map.get(fname)
+                        else:
+                            logger.warning(f"Failed to delete {target_frigate_file} for {name}, skipping replacement")
+                            failed_deletes.add(target_frigate_file)
+                            progress.advance(upload_task)
+                            continue
+
                 for attempt in range(1, max_retries + 1):
                     try:
                         with open(fpath, "rb") as f:
@@ -259,11 +535,21 @@ def upload_to_frigate(jobs: list[dict]) -> None:
                         if resp.status_code == 200:
                             uploaded += 1
                             person_uploaded += 1
+                            effective_count += 1
+                            min_quality_score_for_slot = None
 
-                            # Mark this asset as uploaded so it's skipped on future runs
                             asset_id = asset_map.get(fname)
                             if asset_id:
-                                mark_uploaded(asset_id, person_name=name, score=score_map.get(fname))
+                                mark_uploaded(
+                                    asset_id,
+                                    person_name=name,
+                                    score=score_map.get(fname),
+                                    crop_dims=dims_map.get(fname),
+                                    frigate_score=pre_fscore,
+                                )
+                                if pre_fscore is not None:
+                                    person_has_fscores = True
+                                actually_uploaded.append((fname, asset_id))
 
                             break
                         else:
@@ -320,6 +606,16 @@ def upload_to_frigate(jobs: list[dict]) -> None:
 
                 progress.advance(upload_task)
 
+            if min_quality_score_for_slot is not None:
+                logger.warning(
+                    f"{name}: freed replacement slot (floor {min_quality_score_for_slot:.3f})"
+                    " was not filled this run — will be available next run"
+                )
+
+            # Batch-map Frigate filenames to asset IDs now that all uploads are done.
+            if actually_uploaded:
+                _reconcile_frigate_mappings(name, known_frigate_files_at_start, actually_uploaded)
+
             # Per-person summary
             if person_failed == 0:
                 progress.console.print(

winnow/frigate_api.py

@@ -8,26 +8,122 @@ import requests
 logger = logging.getLogger(__name__)
 
 
-def get_frigate_face_counts() -> dict[str, int] | None:
-    """Return {person_name: training_image_count} from Frigate's train directory.
-
-    Returns None if FRIGATE_URL is not set or the API is unreachable, so callers
-    can distinguish "API unavailable" from "person has 0 images."
-    """
+def _get_faces_data() -> dict | None:
+    """Fetch raw GET /api/faces response. Returns None if unavailable."""
     frigate_url = os.environ.get("FRIGATE_URL", "").rstrip("/")
     if not frigate_url:
         return None
     try:
         resp = requests.get(f"{frigate_url}/api/faces", timeout=10)
         resp.raise_for_status()
-        data = resp.json()
-        # Response: {person_name: [file, ...], "train": [...], ...}
-        # "train" is a flat pending list, not a person — skip it.
-        return {
-            name: len(files)
-            for name, files in data.items()
-            if name != "train" and isinstance(files, list)
-        }
+        return resp.json()
     except Exception as e:
-        logger.warning(f"Could not query Frigate face counts: {e}")
+        logger.warning(f"Could not query Frigate faces API: {e}")
         return None
+
+
+def get_all_frigate_person_files() -> dict[str, list[str]] | None:
+    """Return {person_name: [filename, ...]} for every person in Frigate.
+
+    Single call used to build per-person snapshots before the upload loop,
+    avoiding one GET /api/faces per person.  Returns None if unavailable.
+    """
+    data = _get_faces_data()
+    if data is None:
+        return None
+    # Response: {person_name: [file, ...], "train": [...], ...}
+    # "train" is a flat pending list, not a person — skip it.
+    return {
+        name: files
+        for name, files in data.items()
+        if name != "train" and isinstance(files, list)
+    }
+
+
+def get_frigate_face_counts() -> dict[str, int] | None:
+    """Return {person_name: training_image_count} from Frigate's train directory.
+
+    Returns None if FRIGATE_URL is not set or the API is unreachable, so callers
+    can distinguish "API unavailable" from "person has 0 images."
+    """
+    all_files = get_all_frigate_person_files()
+    if all_files is None:
+        return None
+    return {name: len(files) for name, files in all_files.items()}
+
+
+def get_frigate_person_files(person_name: str) -> list[str] | None:
+    """Return the list of training filenames for a person in Frigate.
+
+    Returns None if the API is unreachable. Returns an empty list if the
+    person exists but has no training images yet.
+    """
+    data = _get_faces_data()
+    if data is None:
+        return None
+    files = data.get(person_name)
+    return files if isinstance(files, list) else []
+
+
+def recognize_face(file_path: str) -> tuple[str | None, float] | None:
+    """Submit an image to Frigate's recognize endpoint.
+
+    Returns (face_name, score) where face_name is the best-matching person
+    (may be "unknown" if below Frigate's confidence threshold) and score is
+    the sigmoid-mapped cosine similarity (0-1) against that person's mean
+    embedding.
+
+    Returns None if FRIGATE_URL is unset, the API is unreachable, no face is
+    detected, or face recognition is not enabled in Frigate.
+    """
+    frigate_url = os.environ.get("FRIGATE_URL", "").rstrip("/")
+    if not frigate_url:
+        return None
+    try:
+        with open(file_path, "rb") as f:
+            resp = requests.post(
+                f"{frigate_url}/api/faces/recognize",
+                files={"file": (os.path.basename(file_path), f, "image/jpeg")},
+                timeout=15,
+            )
+        if not resp.ok:
+            return None
+        data = resp.json()
+        if data.get("success") and "score" in data:
+            return (data.get("face_name"), round(float(data["score"]), 4))
+        return None
+    except Exception as e:
+        logger.debug(f"Frigate recognize failed for {file_path}: {e}")
+        return None
+
+
+def delete_frigate_person_files(person_name: str, filenames: list[str]) -> bool:
+    """Delete specific training files for a person from Frigate.
+
+    Uses POST /api/faces/{name}/delete with body {"ids": [filename, ...]}.
+    Returns True on success, False if unreachable or the request fails.
+    """
+    frigate_url = os.environ.get("FRIGATE_URL", "").rstrip("/")
+    if not frigate_url or not filenames:
+        return False
+    from urllib.parse import quote
+    encoded = quote(person_name, safe="")
+    try:
+        resp = requests.post(
+            f"{frigate_url}/api/faces/{encoded}/delete",
+            json={"ids": filenames},
+            timeout=10,
+        )
+        if resp.ok:
+            logger.debug(f"Deleted {len(filenames)} Frigate file(s) for {person_name}")
+            return True
+        if resp.status_code == 404:
+            # File already absent — stale tracker entry. Return True so the caller
+            # removes it from the tracker and frees the slot cleanly.
+            logger.warning(f"Frigate file(s) not found for {person_name} (stale tracker entry?): {filenames}")
+            return True
+        logger.warning(f"Frigate delete returned {resp.status_code} for {person_name}")
+        return False
+    except Exception as e:
+        logger.warning(f"Failed to delete Frigate files for {person_name}: {e}")
+        return False

winnow/image_processing.py

@@ -69,9 +69,10 @@ def process_face_mode(
     output_dir: str,
     count: int,
     min_width: int | None = None,
-) -> bool:
+) -> tuple[int, int] | None:
     """Crop face based on Immich metadata and save to output directory.
 
+    Returns (width, height) of the saved crop, or None if no crop was saved.
     If face alignment is enabled and landmarks are available, produces
     an aligned 112x112 crop. Otherwise falls back to bounding box crop
     with configurable margin.
@@ -90,7 +91,7 @@ def process_face_mode(
 
     if not face_info:
         logger.debug(f"No face info for {person.get('name')} in asset {asset.get('id')}")
-        return False
+        return None
 
     img_w, img_h = img.size
     meta_w = face_info.get("imageWidth") or img_w
@@ -106,7 +107,7 @@ def process_face_mode(
     face_w, face_h = x2 - x1, y2 - y1
     if face_w < min_width or face_h < min_width:
         logger.debug(f"Face too small ({face_w:.1f}x{face_h:.1f})")
-        return False
+        return None
 
     # Try face alignment if enabled and landmarks available
     if Config.ENABLE_FACE_ALIGNMENT:
@@ -117,7 +118,7 @@ def process_face_mode(
             aligned = align_face(img, scaled_landmarks)
             if aligned is not None:
                 _save_jpeg(aligned, os.path.join(output_dir, f"{count}.jpg"))
-                return True
+                return aligned.size
 
     # Fall back to bounding box crop with configurable margin
     margin = Config.FACE_MARGIN
@@ -131,7 +132,7 @@ def process_face_mode(
 
     face_crop = img.crop(crop_box)
     _save_jpeg(face_crop, os.path.join(output_dir, f"{count}.jpg"))
-    return True
+    return face_crop.size
 
 
 def process_object_mode(
@@ -144,7 +145,14 @@ def process_object_mode(
     try:
         model = get_yolo_model()
         target_class = config.get("object_class", "dog")
-        device = "cpu" if os.getenv("FORCE_CPU", "").lower() in ("true", "1", "yes") else None
+        import torch
+
+        if os.getenv("FORCE_CPU", "").lower() in ("true", "1", "yes"):
+            device = "cpu"
+        elif hasattr(torch, "xpu") and torch.xpu.is_available():
+            device = "xpu"
+        else:
+            device = None  # YOLO auto-selects (CUDA/ROCm/CPU)
 
         results = model(img, verbose=False, device=device)
 

winnow/jobs.py

@@ -58,8 +58,11 @@ def _get_strategy_choice(has_embedding: bool, entity_type: str) -> tuple[int | s
     rprint("  [bold]4.[/bold] Skip")
 
     choice = Prompt.ask("Choice", choices=["1", "2", "3", "4"], default="1")
-    limits = {"1": 30, "2": 100, "3": IntPrompt.ask("Enter number of images", default=30)}
-    return limits.get(choice, 0), "time" if choice != "4" else "skip"
+    if choice == "4":
+        return 0, "skip"
+    if choice == "3":
+        return IntPrompt.ask("Enter number of images", default=30), "time"
+    return {"1": 30, "2": 100}.get(choice, 30), "time"
 
 
 def _resolve_strategy(strategy: str, has_embedding: bool) -> tuple[int | str, str]:
@@ -136,7 +139,7 @@ def _configure_person(person: dict, people: list[dict]) -> dict | None:
     mode_choice = Prompt.ask("Choice", choices=["1", "2"], default="1")
     entity_type = "face" if mode_choice == "1" else "object"
 
-    config = {"name": name, "mode": entity_type}
+    config = {"name": name, "mode": entity_type, "quality_replacement": Config.QUALITY_REPLACEMENT}
     if entity_type == "object":
         config["object_class"] = Prompt.ask("Enter Object Class (e.g. dog, cat, car)", default="dog")
 
@@ -280,34 +283,41 @@ def auto_configure(people: list[dict]) -> list[dict]:
             rprint(f"  [dim]Skipping {name} (0 new images after dedup).[/dim]")
             continue
 
-        # Enforce MAX_AUTO_IMAGES as a lifetime cap per person.
-        # Priority: live Frigate count → last cached Frigate count → local uploaded count.
+        # Enforce MAX_AUTO_IMAGES against the tracked file count only.
+        # Manually-added Frigate files are invisible to this cap so users can
+        # curate their own files without shrinking winnow's managed quota.
         person_summary = upload_summary.get(name, {})
-        if frigate_counts is not None:
-            already_uploaded = frigate_counts.get(name, 0)
-        else:
-            fc = person_summary.get("frigate_count")
-            already_uploaded = fc if fc is not None else person_summary.get("uploaded", 0)
+        already_uploaded = len(person_summary.get("frigate_files", {}))
         capacity = Config.MAX_AUTO_IMAGES - already_uploaded
         if capacity <= 0:
+            if not Config.QUALITY_REPLACEMENT:
+                rprint(
+                    f"  [dim]Skipping {name} (at cap:"
+                    f" {already_uploaded}/{Config.MAX_AUTO_IMAGES}, quality replacement disabled).[/dim]"
+                )
+                continue
             rprint(
-                f"  [dim]Skipping {name} (at lifetime cap:"
-                f" {already_uploaded}/{Config.MAX_AUTO_IMAGES} trained).[/dim]"
+                f"  [cyan]{name}: at cap ({already_uploaded}/{Config.MAX_AUTO_IMAGES}),"
+                f" checking for quality improvements...[/cyan]"
             )
-            continue
+            quality_replacement_only = True
+        else:
+            quality_replacement_only = False
+
+        config["quality_replacement"] = quality_replacement_only or Config.QUALITY_REPLACEMENT
 
         has_embedding = is_embedding_available(entity_type)
         limit, selection_mode = _resolve_strategy(strategy, has_embedding)
 
-        # Cap selection to remaining capacity.
-        # For auto mode with partial training, keep "auto" so adaptive stopping
-        # still runs — just trim the result to the remaining capacity afterward.
+        # Cap selection to remaining capacity (no cap when replacement-only — executor
+        # decides per-image whether to swap; any candidate could be an improvement).
         auto_cap = None
-        if limit == "auto":
-            if already_uploaded > 0:
-                auto_cap = capacity
-        else:
-            limit = min(limit, capacity)
+        if not quality_replacement_only:
+            if limit == "auto":
+                if already_uploaded > 0:
+                    auto_cap = capacity
+            else:
+                limit = min(limit, capacity)
 
         if selection_mode == "skip":
             continue

winnow/quality.py

@@ -20,6 +20,7 @@ class QualityResult:
 
     passed: bool
     reasons: list[str] = field(default_factory=list)
+    blur_score: float | None = None
 
     @property
     def reason(self) -> str:
@@ -113,9 +114,15 @@ def assess_quality(
     img_np = np.asarray(img)
     reasons = []
 
-    # Run all checks, collect failures
+    # Compute laplacian variance once (used by check_blur and stored as blur_score)
+    gray = cv2.cvtColor(img_np, cv2.COLOR_RGB2GRAY) if img_np.ndim == 3 else img_np
+    blur_score = float(cv2.Laplacian(gray, cv2.CV_64F).var())
+
     checks = [
-        check_blur(img_np, blur_threshold),
+        (
+            blur_score >= blur_threshold,
+            f"Blurry (laplacian={blur_score:.1f}, threshold={blur_threshold})" if blur_score < blur_threshold else "",
+        ),
         check_grayscale(img_np),
         check_exposure(img_np),
         check_confidence(confidence, min_confidence),
@@ -129,5 +136,5 @@ def assess_quality(
         if not passed:
             reasons.append(reason)
 
-    return QualityResult(passed=len(reasons) == 0, reasons=reasons)
+    return QualityResult(passed=len(reasons) == 0, reasons=reasons, blur_score=blur_score)
 

winnow/upload_tracker.py

@@ -11,16 +11,29 @@ Both are excluded from future candidate pools. To reset:
 
 by_person schema (frigate_uploaded_ids.json):
   {
-    "asset_ids":    ["immich-id-1", ...],   # all assets we attempted to upload
-    "scores":       {"immich-id-1": 0.953}, # Immich face confidence at upload time
-    "frigate_count": 42                     # last known Frigate training image count
+    "asset_ids":      ["immich-id-1", ...],                    # all assets we attempted to upload
+    "scores":         {"immich-id-1": 450.3},                  # Laplacian blur variance at upload time
+    "frigate_scores": {"immich-id-1": 0.87},                   # Frigate recognition confidence (0-1) pre-upload
+    "frigate_files":  {"PersonName-123.webp": "immich-id-1"},  # Frigate filename → asset ID
+    "crop_dims":      {"immich-id-1": [640, 480]},             # crop pixel dimensions at upload time
+    "frigate_count":  42                                       # last known Frigate training image count
   }
+
+frigate_scores stores pre-upload recognize scores (0-1 sigmoid-mapped cosine
+similarity). High score = the existing training set already covers this face
+condition well. Low score = a gap — novel/diverse for the training set.
+
+frigate_files only contains files winnow uploaded — files added manually through
+Frigate's UI are never mapped here and are never touched by quality replacement.
 """
 
 import json
 import logging
+import os
 from pathlib import Path
 
+from .frigate_api import delete_frigate_person_files
+
 logger = logging.getLogger(__name__)
 
 UPLOAD_TRACKER_FILE = "frigate_uploaded_ids.json"
@@ -72,13 +85,23 @@ def _get_ids(entry: list | dict) -> list[str]:
 def _migrate_entry(entry: list | dict) -> dict:
     """Ensure by_person entry is in the current dict format."""
     if isinstance(entry, list):
-        return {"asset_ids": sorted(entry), "scores": {}}
+        return {"asset_ids": sorted(entry), "scores": {}, "frigate_scores": {}, "frigate_files": {}, "crop_dims": {}}
     entry.setdefault("asset_ids", [])
     entry.setdefault("scores", {})
+    entry.setdefault("frigate_scores", {})
+    entry.setdefault("frigate_files", {})
+    entry.setdefault("crop_dims", {})
     return entry
 
 
-def _mark(filename: str, asset_id: str, person_name: str | None, score: float | None = None) -> None:
+def _mark(
+    filename: str,
+    asset_id: str,
+    person_name: str | None,
+    score: float | None = None,
+    crop_dims: tuple[int, int] | None = None,
+    frigate_score: float | None = None,
+) -> None:
     data = _load(filename)
     flat_key = _flat_key(filename)
     flat = set(data.get(flat_key, []))
@@ -92,6 +115,10 @@ def _mark(filename: str, asset_id: str, person_name: str | None, score: float |
         entry["asset_ids"] = sorted(ids)
         if score is not None:
             entry["scores"][asset_id] = round(score, 4)
+        if crop_dims is not None:
+            entry["crop_dims"][asset_id] = [crop_dims[0], crop_dims[1]]
+        if frigate_score is not None:
+            entry["frigate_scores"][asset_id] = round(frigate_score, 4)
         by_person[person_name] = entry
     _save(filename, data)
 
@@ -106,8 +133,14 @@ def load_rejected_ids() -> set[str]:
     return _load_flat(REJECT_TRACKER_FILE)
 
 
-def mark_uploaded(asset_id: str, person_name: str | None = None, score: float | None = None) -> None:
-    _mark(UPLOAD_TRACKER_FILE, asset_id, person_name, score=score)
+def mark_uploaded(
+    asset_id: str,
+    person_name: str | None = None,
+    score: float | None = None,
+    crop_dims: tuple[int, int] | None = None,
+    frigate_score: float | None = None,
+) -> None:
+    _mark(UPLOAD_TRACKER_FILE, asset_id, person_name, score=score, crop_dims=crop_dims, frigate_score=frigate_score)
     logger.debug(f"Marked {asset_id} as uploaded ({person_name})")
 
 
@@ -116,6 +149,146 @@ def mark_rejected(asset_id: str, person_name: str | None = None) -> None:
     logger.debug(f"Marked {asset_id} as rejected ({person_name})")
 
 
+
+def record_frigate_file(person_name: str, frigate_filename: str, asset_id: str) -> None:
+    """Record the mapping from a Frigate training filename to an Immich asset ID."""
+    data = _load(UPLOAD_TRACKER_FILE)
+    by_person = data.setdefault("by_person", {})
+    entry = _migrate_entry(by_person.get(person_name, {}))
+    entry["frigate_files"][frigate_filename] = asset_id
+    by_person[person_name] = entry
+    _save(UPLOAD_TRACKER_FILE, data)
+    logger.debug(f"Mapped Frigate file {frigate_filename} → {asset_id} ({person_name})")
+
+
+def remove_frigate_file(person_name: str, frigate_filename: str) -> None:
+    """Remove a Frigate filename from the mapping after it has been deleted.
+
+    Does NOT unmark the source asset_id — the deletion was deliberate and
+    we don't want to re-upload the inferior image on the next run.
+    """
+    data = _load(UPLOAD_TRACKER_FILE)
+    by_person = data.get("by_person", {})
+    entry = _migrate_entry(by_person.get(person_name, {}))
+    asset_id = entry["frigate_files"].pop(frigate_filename, None)
+    if asset_id:
+        entry["frigate_scores"].pop(asset_id, None)
+    by_person[person_name] = entry
+    _save(UPLOAD_TRACKER_FILE, data)
+    logger.debug(f"Removed Frigate file mapping {frigate_filename} ({person_name})")
+
+
+def get_tracked_frigate_file_count(person_name: str) -> int:
+    """Return the number of Frigate training files winnow has mapped for this person.
+
+    Used as the cap baseline so that manually-added Frigate files do not
+    consume slots from winnow's managed quota.
+    """
+    data = _load(UPLOAD_TRACKER_FILE)
+    entry = _migrate_entry(data.get("by_person", {}).get(person_name, {}))
+    return len(entry["frigate_files"])
+
+
+def get_tracked_frigate_filenames(person_name: str) -> set[str]:
+    """Return the set of Frigate filenames currently mapped in the tracker for a person.
+
+    Used as a pre-upload baseline when the Frigate GET API is unreachable at
+    upload start, so reconciliation can still identify newly uploaded files.
+    """
+    data = _load(UPLOAD_TRACKER_FILE)
+    entry = _migrate_entry(data.get("by_person", {}).get(person_name, {}))
+    return set(entry["frigate_files"].keys())
+
+
+def has_frigate_scores(person_name: str) -> bool:
+    """Return True if any mapped file for this person has a stored Frigate recognition score."""
+    data = _load(UPLOAD_TRACKER_FILE)
+    entry = _migrate_entry(data.get("by_person", {}).get(person_name, {}))
+    frigate_files = entry.get("frigate_files", {})
+    frigate_scores = entry.get("frigate_scores", {})
+    return any(asset_id in frigate_scores for asset_id in frigate_files.values())
+
+
+def _pick_mapped_file(
+    person_name: str, score_key: str, *, highest: bool, exclude: set[str] | None = None
+) -> tuple[str, str, float] | None:
+    data = _load(UPLOAD_TRACKER_FILE)
+    entry = _migrate_entry(data.get("by_person", {}).get(person_name, {}))
+    scores = entry.get(score_key, {})
+    candidates = [
+        (ff, asset_id, scores[asset_id])
+        for ff, asset_id in entry.get("frigate_files", {}).items()
+        if (exclude is None or ff not in exclude) and asset_id in scores
+    ]
+    if not candidates:
+        return None
+    return max(candidates, key=lambda x: x[2]) if highest else min(candidates, key=lambda x: x[2])
+
+
+def get_lowest_quality_mapped_file(
+    person_name: str, exclude: set[str] | None = None
+) -> tuple[str, str, float] | None:
+    """Return (frigate_filename, asset_id, score) for the mapped file with the lowest
+    blur score, or None if no mapped files with known scores exist.
+
+    Used for quality replacement when no Frigate scores are available.
+    Pass `exclude` to skip files that failed to delete this run.
+    """
+    return _pick_mapped_file(person_name, "scores", highest=False, exclude=exclude)
+
+
+def get_most_redundant_mapped_file(
+    person_name: str, exclude: set[str] | None = None
+) -> tuple[str, str, float] | None:
+    """Return (frigate_filename, asset_id, score) for the mapped file with the highest
+    Frigate recognition score, or None if no mapped files with Frigate scores exist.
+
+    High Frigate score = the training set already covers this face condition well
+    = the most redundant file and therefore the best replacement target.
+    Pass `exclude` to skip files that failed to delete this run.
+    """
+    return _pick_mapped_file(person_name, "frigate_scores", highest=True, exclude=exclude)
+
+
+def get_frigate_filename_for_asset(person_name: str, asset_id: str) -> str | None:
+    """Return the Frigate training filename mapped to this asset ID, or None."""
+    data = _load(UPLOAD_TRACKER_FILE)
+    entry = _migrate_entry(data.get("by_person", {}).get(person_name, {}))
+    for frigate_filename, aid in entry["frigate_files"].items():
+        if aid == asset_id:
+            return frigate_filename
+    return None
+
+
+def find_by_crop_dimension(size: int) -> list[dict]:
+    """Return all tracked crops whose width or height matches `size` pixels.
+
+    Returns a list of dicts: {person, asset_id, width, height, blur_score, frigate_filename}.
+    frigate_filename is None when the Frigate mapping was lost to a reconciliation race.
+    """
+    data = _load(UPLOAD_TRACKER_FILE)
+    results = []
+    for person_name, raw_entry in data.get("by_person", {}).items():
+        entry = _migrate_entry(raw_entry)
+        scores = entry.get("scores", {})
+        frigate_files = entry.get("frigate_files", {})
+        asset_to_frigate = {v: k for k, v in frigate_files.items()}
+        frigate_scores = entry.get("frigate_scores", {})
+        for asset_id, dims in entry.get("crop_dims", {}).items():
+            w, h = dims[0], dims[1]
+            if w == size or h == size:
+                results.append({
+                    "person": person_name,
+                    "asset_id": asset_id,
+                    "width": w,
+                    "height": h,
+                    "blur_score": scores.get(asset_id),
+                    "frigate_score": frigate_scores.get(asset_id),
+                    "frigate_filename": asset_to_frigate.get(asset_id),
+                })
+    return results
+
+
 def update_frigate_count(person_name: str, count: int) -> None:
     """Record Frigate's authoritative training image count for a person."""
     data = _load(UPLOAD_TRACKER_FILE)
@@ -127,23 +300,45 @@ def update_frigate_count(person_name: str, count: int) -> None:
 
 
 def reset_person(person_name: str) -> None:
-    """Remove all uploaded and rejected records for a given person."""
-    for filename in (UPLOAD_TRACKER_FILE, REJECT_TRACKER_FILE):
-        data = _load(filename)
+    """Remove all uploaded and rejected records for a given person.
+
+    Also deletes winnow-managed Frigate training files so the next run starts
+    clean rather than uploading on top of orphaned files. Manually-added Frigate
+    files (not in frigate_files) are never touched. Proceeds with tracker reset
+    even if Frigate is unreachable.
+    """
+    upload_data = _load(UPLOAD_TRACKER_FILE)
+    entry = _migrate_entry(upload_data.get("by_person", {}).get(person_name, {}))
+    frigate_filenames = list(entry.get("frigate_files", {}).keys())
+    if frigate_filenames:
+        if not os.environ.get("FRIGATE_URL", "").strip():
+            logger.info(f"FRIGATE_URL not set — skipping Frigate file deletion for {person_name}")
+        elif delete_frigate_person_files(person_name, frigate_filenames):
+            logger.info(f"Deleted {len(frigate_filenames)} Frigate file(s) for {person_name}")
+        else:
+            logger.warning(f"Could not delete Frigate files for {person_name} — tracker reset proceeding anyway")
+
+    changed = False
+    tracker_files = ((UPLOAD_TRACKER_FILE, upload_data), (REJECT_TRACKER_FILE, _load(REJECT_TRACKER_FILE)))
+    for filename, data in tracker_files:
         flat_key = _flat_key(filename)
         by_person = data.get("by_person", {})
-        entry = by_person.pop(person_name, None)
-        if entry is not None:
-            person_ids = set(_get_ids(entry))
+        tracker_entry = by_person.pop(person_name, None)
+        if tracker_entry is not None:
+            person_ids = set(_get_ids(tracker_entry))
             flat = set(data.get(flat_key, [])) - person_ids
             data[flat_key] = sorted(flat)
             data["by_person"] = by_person
             _save(filename, data)
-    logger.info(f"Reset tracking data for {person_name}")
+            changed = True
+    if changed:
+        logger.info(f"Reset tracking data for {person_name}")
+    else:
+        logger.debug(f"reset_person: no tracking data found for {person_name}")
 
 
 def get_person_summary() -> dict[str, dict]:
-    """Return {person_name: {uploaded, rejected, frigate_count, scores}} for display/capacity."""
+    """Return {person_name: {uploaded, rejected, frigate_count, scores, frigate_files}} for display/capacity."""
     uploaded_data = _load(UPLOAD_TRACKER_FILE).get("by_person", {})
     rejected_data = _load(REJECT_TRACKER_FILE).get("by_person", {})
     names = set(uploaded_data) | set(rejected_data)
@@ -156,6 +351,7 @@ def get_person_summary() -> dict[str, dict]:
             "rejected": len(_get_ids(r_entry)),
             "frigate_count": u_entry.get("frigate_count") if isinstance(u_entry, dict) else None,
             "scores": u_entry.get("scores", {}) if isinstance(u_entry, dict) else {},
+            "frigate_files": u_entry.get("frigate_files", {}) if isinstance(u_entry, dict) else {},
         }
     return result