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

@@ -4,7 +4,10 @@ API_KEY=your-immich-api-key
 FRIGATE_URL=http://192.168.1.10:5000
 
 # ── Mode & Strategy ───────────────────────────────────────────────────────────
-AUTO_MODE=true
+# Auto mode is active by default when no TTY is present (Docker/cron).
+# Set AUTO_MODE=true to force auto mode even in an interactive terminal.
+# AUTO_MODE=true
+# VERBOSE=true                # Enable DEBUG-level console output (log file is always DEBUG)
 # TRAINING_MODE: face = upload to Frigate face recognition API
 #                object = save crops to output dir for manual Frigate placement
 TRAINING_MODE=face
@@ -20,20 +23,23 @@ 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=false
-ENABLE_CACHE=true
+# FORCE_CPU=true              # Disable GPU, fall back to CPU
+# ENABLE_CACHE=false          # Disable embedding cache (default: true)
 CACHE_DIR=/app/.if_cache
 HF_HOME=/models/huggingface
-INSIGHTFACE_HOME=/models
+INSIGHTFACE_HOME=/models/.insightface
 
 # ── Tracker overrides (one-shot — remove after use) ───────────────────────────
 # DRY_RUN=true                # Preview selection without downloading/uploading
@@ -41,5 +47,10 @@ INSIGHTFACE_HOME=/models
 # RESET_PERSON=John           # Clear uploaded+rejected history for one person
 
 # ── Scheduling ────────────────────────────────────────────────────────────────
-# Cron expression (unset = run once and exit)
-CRON_SCHEDULE=0 3 * * 0     # Every Sunday at 3 AM
+# CRON_SCHEDULE controls container lifetime:
+#   unset          — run once on startup, then exit
+#   empty string   — stay alive, run nothing (trigger manually: docker exec -it winnow winnow)
+#   cron expression — run on startup, then on schedule
+# CRON_SCHEDULE=              # Manual mode (keep alive, no auto-run)
+# CRON_SCHEDULE=0 3 * * 0    # Every Sunday at 3 AM
+# CRON_SCHEDULE=0 3 1 * *    # First of every month

.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,35 +2,41 @@ 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
   IMAGE_NAME: sudolulo/winnow
 
 jobs:
-  verify-lockfile:
-    name: Verify uv.lock is current
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v4
-
-      - name: Check lockfile is up to date
-        run: uv lock --check
-
   build:
     name: Build (${{ matrix.platform }})
-    needs: verify-lockfile
     runs-on: ${{ matrix.runner }}
     strategy:
       matrix:
@@ -46,36 +52,48 @@ 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@v4
+        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@v3
+        uses: docker/setup-buildx-action@v4
 
       - name: Log in to GHCR
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           registry: ${{ env.REGISTRY }}
           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 }}
@@ -112,10 +130,10 @@ jobs:
           merge-multiple: true
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4
 
       - name: Log in to GHCR
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
@@ -124,20 +142,282 @@ 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 (amd64 + arm64)
+    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 QEMU
+        uses: docker/setup-qemu-action@v4
+
+      - 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 CPU image tags
+        id: cpu-tags
+        run: |
+          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 "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@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=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.rocm-tags.outputs.tags }}
+
+      - name: Inspect ROCm image
+        run: |
+          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/lint.yml

@@ -9,6 +9,8 @@ on:
 jobs:
   lint:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     env:
       FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
     steps:
@@ -21,7 +23,7 @@ jobs:
           echo "Disk space freed."
 
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Run Ruff
         uses: astral-sh/ruff-action@v3

.github/workflows/release.yml

@@ -14,26 +14,14 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  verify-lockfile:
-    name: Verify uv.lock is current
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v4
-
-      - name: Check lockfile is up to date
-        run: uv lock --check
-
   release:
-    name: Create GitHub Release & Build Image
-    needs: verify-lockfile
+    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: |
@@ -44,15 +32,35 @@ jobs:
           echo "Disk space freed."
 
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
 
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - 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: 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
@@ -101,7 +109,7 @@ jobs:
           fi
 
       - name: Create GitHub Release
-        uses: actions/github-script@v7
+        uses: actions/github-script@v9
         env:
           RELEASE_TAG: ${{ steps.tag.outputs.TAG }}
           RELEASE_NOTES: ${{ steps.changelog.outputs.NOTES }}
@@ -119,23 +127,14 @@ jobs:
               prerelease: false,
             });
 
-      - name: Log in to GHCR
-        uses: docker/login-action@v3
-        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/test.yml

@@ -9,15 +9,17 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v7
 
       - name: Set up Python
-        run: uv python install 3.12
+        run: uv python install 3.13
 
       - name: Install dependencies
         run: uv sync --all-extras

.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:
@@ -22,32 +27,40 @@ jobs:
           echo "Disk space freed."
 
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v7
 
       - name: Set up Python
-        run: uv python install 3.12
+        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
-

.gitignore

@@ -1,238 +1,36 @@
-# Custom
+# Output and runtime artefacts
 frigate_train/
 *.log
 runs/
+
+# Model and cache files
 yolov9c.pt
 .insightface/
 .huggingface/
-.cache/huggingface
 .if_cache/
-
 .immich_config.json
-# Python-generated files
-__pycache__/
-*.py[oc]
-build/
-dist/
-wheels/
-*.egg-info
 
-# Virtual environments
-.venv
-
-# Byte-compiled / optimized / DLL files
-__pycache__/
-*.py[codz]
-*$py.class
-
-# C extensions
-*.so
-
-# Distribution / packaging
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-share/python-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-MANIFEST
-
-# PyInstaller
-#   Usually these files are written by a python script from a template
-#   before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-*.spec
-
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.nox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-*.cover
-*.py.cover
-.hypothesis/
-.pytest_cache/
-cover/
-
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
-local_settings.py
-db.sqlite3
-db.sqlite3-journal
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
-docs/_build/
-
-# PyBuilder
-.pybuilder/
-target/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# IPython
-profile_default/
-ipython_config.py
-
-# pyenv
-#   For a library or package, you might want to ignore these files since the code is
-#   intended to run in multiple environments; otherwise, check them in:
-# .python-version
-
-# pipenv
-#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
-#   However, in case of collaboration, if having platform-specific dependencies or dependencies
-#   having no cross-platform support, pipenv may install dependencies that don't work, or not
-#   install all needed dependencies.
-# Pipfile.lock
-
-# UV
-#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-# uv.lock
-
-# poetry
-#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
-# poetry.lock
-# poetry.toml
-
-# pdm
-#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
-#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
-#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
-# pdm.lock
-# pdm.toml
-.pdm-python
-.pdm-build/
-
-# pixi
-#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
-# pixi.lock
-#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
-#   in the .venv directory. It is recommended not to include this directory in version control.
-.pixi
-
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
-__pypackages__/
-
-# Celery stuff
-celerybeat-schedule
-celerybeat.pid
-
-# Redis
-*.rdb
-*.aof
-*.pid
-
-# RabbitMQ
-mnesia/
-rabbitmq/
-rabbitmq-data/
-
-# ActiveMQ
-activemq-data/
-
-# SageMath parsed files
-*.sage.py
-
-# Environments
+# Secrets
 .env
 .envrc
-.venv
-env/
-venv/
-ENV/
-env.bak/
-venv.bak/
 
-# Spyder project settings
-.spyderproject
-.spyproject
+# Python
+__pycache__/
+*.py[oc]
+*.so
+.Python
 
-# Rope project settings
-.ropeproject
+# Packaging
+build/
+dist/
+*.egg-info/
+wheels/
 
-# mkdocs documentation
-/site
+# Virtual environments
+.venv/
 
-# mypy
-.mypy_cache/
-.dmypy.json
-dmypy.json
-
-# Pyre type checker
-.pyre/
-
-# pytype static type analyzer
-.pytype/
-
-# Cython debug symbols
-cython_debug/
-
-# PyCharm
-#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
-#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
-#   and can be added to the global gitignore or merged into this file.  For a more nuclear
-#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
-# .idea/
-
-# Abstra
-#   Abstra is an AI-powered process automation framework.
-#   Ignore directories containing user credentials, local state, and settings.
-#   Learn more at https://abstra.io/docs
-.abstra/
-
-# Visual Studio Code
-#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
-#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
-#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
-#   you could uncomment the following to ignore the entire vscode folder
-# .vscode/
-
-# Ruff stuff:
+# Tools
 .ruff_cache/
-
-# PyPI configuration file
-.pypirc
-
-# Marimo
-marimo/_static/
-marimo/_lsp/
-__marimo__/
-
-# Streamlit
-.streamlit/secrets.toml
+.pytest_cache/
+.mypy_cache/
+.python-version

.python-version

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

CHANGELOG.md

@@ -7,6 +7,246 @@ 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
+
+- **`VERBOSE` env var**: set `VERBOSE=true` to enable DEBUG-level console output. The log file always captures DEBUG; this flag controls what appears on the terminal. Useful when diagnosing issues without a full shell into the container.
+- **`:cpu` Docker image tag**: a separate CPU-only image (`ghcr.io/sudolulo/winnow:cpu`) is now built and pushed alongside `:latest`. Uses `onnxruntime` instead of `onnxruntime-gpu`; ~2 GB smaller. Suitable for systems without an NVIDIA GPU.
+- **Empty `CRON_SCHEDULE` keeps container alive**: setting `CRON_SCHEDULE=` (empty string) starts the container without running immediately and without exiting — useful for `docker exec` ad-hoc runs on a long-lived container. Previously, an empty value was treated the same as unset (run once, then exit).
+
+### Changed
+
+- **TTY auto-detection replaces `AUTO_MODE`**: winnow now detects whether a TTY is attached (`sys.stdin.isatty()`) and switches between interactive and auto mode automatically. `AUTO_MODE=true` becomes an explicit override for forcing auto mode in a terminal session. No config change needed for normal Docker deployments.
+- **Logging levels audited**: internal algorithmic detail (clustering steps, asset fetch progress, per-page pagination) demoted from INFO to DEBUG. INFO now reflects meaningful pipeline milestones only (model ready, selection complete, quality filtered). Reduces noise in production logs without losing information.
+- **Model load logging improved**: SigLIP and InsightFace loading now reports cache hit/miss, download size estimate, device used, and load time.
+
+### Fixed
+
+- **GPU OOM crash loop (production)**: `CUDAExecutionProvider` was silently absent even with a GPU attached, causing InsightFace to run on CPU and exhaust RAM processing large person libraries. Root cause: CUDA/cuDNN libraries in nvidia pip packages were invisible to onnxruntime. Fixed by running `ldconfig` over all `nvidia-*/lib/` directories in the venv at image build time.
+- **ldconfig path now Python-version-agnostic**: the `find` command used to register nvidia pip libraries hardcoded `python3.13`; replaced with `python3.*` glob so the path survives a Python upgrade without silently producing an empty ldconfig config.
+- **`PYTHONPATH=/app` added to Dockerfile**: the entry point script sets `sys.path[0]` to the script directory, not `/app`. Since `uv sync` runs before `COPY winnow/`, the wheel has only dist-info in site-packages. `PYTHONPATH=/app` makes the `winnow` package importable without reverting to `python -m`.
+- **CPU fallback retrying broken GPU provider**: InsightFace CPU fallback omitted `providers=["CPUExecutionProvider"]`, causing onnxruntime to retry `CUDAExecutionProvider` on every inference call. Now explicitly sets the CPU provider and suppresses C-extension noise via fd-level redirect.
+- **`_suppress_output` stderr loss on fd exhaustion**: if the first `os.dup2` in the finally block raised `OSError`, the second call was skipped, permanently redirecting stderr to `/dev/null` for the process lifetime. Wrapped in nested `try/finally` so both restores are always attempted.
+- **Frigate `/api/faces` response parsing**: the response is `{person_name: [files], "train": [...]}` — `"train"` is a flat pending list, not a person. Previous code called `.items()` on the `"train"` value (a list), crashing with `AttributeError`. Now skips the `"train"` key explicitly.
+- **Immich 401 detection**: a stale or invalid API key now logs a clear error message (`Immich API key is invalid or expired (401 Unauthorized)`) instead of raising an unhandled exception.
+- **Falsy-zero detection confidence**: `face.get("score") or face.get("confidence")` treated a valid `score=0.0` as falsy, falling through to the `confidence` field (often `None`). Replaced with an explicit `None` check. Affected both quality filtering and hard-example weighting in diversity selection.
+- **Face crop using wrong person's image dimensions**: in multi-person assets, `_crop_face_from_thumbnail`'s scale-factor loop matched the first person with any face regardless of `person_id`, producing incorrectly scaled bounding box coordinates for the target person. Loop now applies the same `person_id` filter as `_get_face_bbox`.
+- **Adaptive stopping bypassed for partially-trained people**: in auto mode with `already_uploaded > 0`, `limit` was converted from `"auto"` to an integer, disabling the FPS adaptive threshold and early-stop check. Now keeps `limit="auto"` through selection and trims the result to the remaining capacity afterward.
+- **Embedding cache key mismatch**: HuggingFace cache path check hardcoded the model slug string; replaced with a derivation from `model_name` using `"models--" + model_name.replace("/", "--")` so the check stays correct if the model name changes.
+- **Scheduler: sleep until next run**: the loop slept a fixed 60 seconds regardless of schedule interval, causing runs to fire up to 59 seconds late and waking the process unnecessarily on long schedules (e.g. weekly). Now sleeps exactly until `next_run`.
+- **Scheduler swallowing `SystemExit`**: `except BaseException` in the run wrapper was replaced with `except Exception` (with `KeyboardInterrupt` re-raised above), so `sys.exit()` calls propagate correctly.
+- **Log handler leak**: `setup_logging` now closes and removes existing handlers before adding new ones, preventing file handle accumulation across repeated calls.
+- **`RETRY_REJECTED` silently applied in interactive mode**: the env var was applied unconditionally even in interactive sessions. Now used only as the default for the interactive prompt so users can override it per-run.
+- **`compose.yml` comment inverted**: a comment stated `-it` forces non-interactive mode; corrected to reflect that `-it` allocates a TTY (interactive mode).
+
+### Security
+
+- API key is no longer stored in any config file. All authentication uses environment variables or `.env` only.
+
+## [0.2.9] - 2026-06-12
+
+### Fixed
+
+- **arm64: `onnxruntime-gpu` has no arm64 wheels**: `onnxruntime-gpu` only publishes `manylinux_2_27_x86_64` and `manylinux_2_28_x86_64` wheels — `uv sync` on arm64 failed with exit code 2. Gated `onnxruntime-gpu` behind `sys_platform == 'linux' and platform_machine == 'x86_64'`; arm64 and non-Linux installs now get the CPU `onnxruntime` package instead.
+- **uv lockfile now covers arm64**: Added `required-environments` to `[tool.uv]` so the lockfile is solved for both `linux/x86_64` and `linux/aarch64`, preventing silent resolution gaps for the non-build platform.
+
+## [0.2.8] - 2026-06-12
+
+### Fixed
+
+- **Dockerfile: use `add-apt-repository` with isolated GNUPGHOME**: the `curl | gpg --dearmor` approach was silently failing — gpg exits 0 on bad/empty input, leaving an invalid keyring and causing apt to skip the deadsnakes PPA entirely. Reverted to `add-apt-repository ppa:deadsnakes/ppa` with `GNUPGHOME=$(mktemp -d)` to prevent gpg from touching any pre-existing agent socket (the original QEMU crash cause).
+- **arm64 base: removed `--platform=$BUILDPLATFORM`**: the Ubuntu 24.04 base for arm64 is now pulled for the target platform, so the arm64 image contains real arm64 binaries rather than amd64 binaries in an arm64 manifest.
+
+### Changed
+
+- **License changed from MIT to AGPLv3+**: source and network use of winnow now require derivative works to be open-sourced under the same terms.
+
+## [0.2.7] - 2026-06-12
+
+### Fixed
+
+- **arm64 base reverted to Ubuntu 24.04**: Ubuntu 26.04 ships Python 3.14, not 3.13 — `python3.13` was not locatable in its repos. Reverted arm64 base to `ubuntu:24.04`.
+- **Deadsnakes PPA now uses curl+gpg instead of `add-apt-repository`**: `add-apt-repository` spawns a gpg-agent which crashes under QEMU (arm64 CI). The PPA is now added by fetching the key via `curl` and piping through `gpg --dearmor` — no agent, works on both architectures.
+- **PPA conditional removed**: both amd64 (Ubuntu 22.04 CUDA) and arm64 (Ubuntu 24.04) now go through the same deadsnakes install path, eliminating the per-arch branching and the `ARG TARGETARCH` dependency in RUN commands.
+
+## [0.2.6] - 2026-06-12
+
+### Fixed
+
+- **Dockerfile: `ARG TARGETARCH` re-declared in each stage**: Docker's automatic platform ARGs are only in scope for `FROM` instructions, not `RUN` commands. The `$TARGETARCH` variable in the deadsnakes PPA conditional was silently empty, so the PPA was never added and `python3.13` could not be located on the Ubuntu 22.04 CUDA base. Adding `ARG TARGETARCH` at the top of both the `build` and `runtime` stage bodies fixes the amd64 build.
+
+## [0.2.5] - 2026-06-12
+
+### Changed
+
+- **CUDA base upgraded to 13.3.0**: amd64 base image bumped from `nvidia/cuda:12.9.2-cudnn-runtime-ubuntu22.04` to `nvidia/cuda:13.3.0-cudnn-runtime-ubuntu22.04`. Python packages (torch, onnxruntime-gpu) still target CUDA 12.6 via pip-installed libraries; the base image upgrade requires a host GPU driver that supports CUDA 13+.
+- **`torchvision>=0.27.0` added as explicit dependency**: routed through the `pytorch-cu126` index for linux/x86_64, ensuring it resolves to `0.27.0+cu126` (paired with `torch 2.12.0+cu126`) rather than being pulled from PyPI where the older `0.21.0` wheel would downgrade torch to 2.6.0.
+- **`torch>=2.12.0`** floor raised from 2.6.0 to prevent silent downgrade.
+- **`nvidia-cudnn-cu12>=9.0.0`** floor kept intentionally loose — torch pins an exact cuDNN ABI version (`9.10.2.21`) and must own that constraint.
+
+## [0.2.4] - 2026-06-12
+
+### Changed
+
+- **Python 3.13 across all platforms**: bumped from 3.12 to 3.13. amd64 installs Python 3.13 from the deadsnakes PPA on the Ubuntu 22.04 CUDA base; arm64 uses the Python 3.13 package available natively in Ubuntu 26.04. All confirmed dependencies (`insightface 1.0.1`, `onnxruntime-gpu 1.26.0`, `torch 2.12.0+cu126`) have Python 3.13 wheels.
+- **arm64 base: Ubuntu 26.04**: Python 3.12 was removed from Ubuntu 26.04's default repos; upgrading the base pulls Python 3.13 without a PPA.
+- **`requires-python = ">=3.13"`** and `target-version = "py313"` updated in `pyproject.toml`.
+- **CI updated to Python 3.13**: `test.yml` and `update-lockfile.yml` now install Python 3.13.
+- **`uv.lock` regenerated** for Python 3.13.5.
+
+## [0.2.3] - 2026-06-12
+
+### Fixed
+
+- **Clear-text API key storage**: `config.py` no longer writes `API_KEY` to `.immich_config.json`. The key must come from an environment variable or `.env` file. Interactive mode now prints a tip directing users to `.env`. Resolves CodeQL `py/clear-text-storage-sensitive-data`.
+
+### Changed
+
+- **CI workflow permissions**: `test.yml` and `lint.yml` now declare `permissions: contents: read`, following least-privilege principle and resolving `actions/missing-workflow-permissions` scanner alerts.
+- **CI lockfile race condition**: removed the `verify-lockfile` pre-job from `docker-publish.yml` and `release.yml`. The `update-lockfile.yml` bot maintains the lockfile; the verify step raced against it on the same push event and caused false failures. `release.yml` now runs `uv lock` inline so tag-triggered builds are always self-consistent.
+- **Docs moved to wiki**: `docs/` folder removed from the repository. Setup, Troubleshooting, and FAQ pages are now at the [GitHub wiki](https://github.com/sudolulo/winnow/wiki).
+
+## [0.2.2] - 2026-06-12
+
+### Added
+
+- **Confidence scores in upload tracker**: Immich face confidence scores are now stored per asset in `frigate_uploaded_ids.json` under `by_person[name].scores`. Lays the groundwork for future replacement logic (remove low-confidence uploads when better images are found).
+- **Frigate-authoritative capacity tracking**: At startup, `GET /api/faces` is queried on the Frigate host to retrieve the actual number of trained images per person from the `train` directory (pending/unclassified queue is excluded). This count is stored as `frigate_count` in the tracker JSON so it survives Frigate downtime.
+- **Lifetime cap uses Frigate count**: `MAX_AUTO_IMAGES` is now enforced against Frigate's live training image count rather than the local uploaded-asset tally. Fallback priority: live Frigate API → last cached `frigate_count` in JSON → local uploaded count.
+- **Startup summary shows Frigate count**: Tracker summary at startup now includes the last known Frigate training count per person (e.g. `78 uploaded, 2 rejected, 42 in Frigate`).
+- **`winnow/frigate_api.py`**: new module encapsulating Frigate API helpers; currently exposes `get_frigate_face_counts()`.
+
+### Changed
+
+- `upload_tracker.py`: `by_person` entries migrated from flat list to `{asset_ids, scores, frigate_count}` dict. Old list format is read and migrated transparently on first write.
+- `mark_uploaded()` now accepts an optional `score` keyword argument.
+- `get_person_summary()` now returns `frigate_count` and `scores` fields alongside `uploaded` and `rejected`.
+
+## [0.2.1] - 2026-06-12
+
+### Fixed
+
+- **Container startup reinstalling packages**: `entrypoint.sh` used `uv run`, which performs a sync check on every startup and re-downloaded `ruff` and rebuilt the package each time. Replaced with direct `.venv/bin/python` calls to skip the sync entirely.
+- **InsightFace double `models/` path**: `INSIGHTFACE_HOME=/models` caused InsightFace to download Buffalo_L to `/models/models/buffalo_l` (InsightFace always appends `models/` to the root). Updated default in `compose.yml` and `.env.example` to `/models/.insightface`.
+- **Lint errors in CI**: unused imports in `tests/test_config.py` and `tests/test_upload_tracker.py`, unsorted imports in `scheduler.py` — all would have failed the ruff CI check.
+
 ## [0.2.0] - 2026-06-12
 
 First release of winnow. Forked from [if-curator](https://github.com/ds-sebastian/if_curator) by Sebastian and rewritten for headless Docker deployment.
@@ -21,14 +261,14 @@ First release of winnow. Forked from [if-curator](https://github.com/ds-sebastia
 
 **Docker and scheduling**
 - `Dockerfile` — multi-stage build (CUDA 12.9 on amd64, plain Ubuntu on arm64); runtime stage excludes build tools (g++, python3.12-dev, curl, gnupg)
-- `compose.yml` — fully annotated with inline comments grouped by concern; TrueNAS volume paths in the example
+- `compose.yml` — fully annotated with inline comments grouped by concern
 - `entrypoint.sh` — runs the tool once on startup, then hands off to the scheduler if `CRON_SCHEDULE` is set
 - `scheduler.py` — in-process cron scheduler that keeps the container (and loaded models) alive between runs
 - `CRON_SCHEDULE` env var — standard cron expression for recurring runs; unset exits after first run
 - `.dockerignore` — keeps `.venv`, `__pycache__`, test files, and logs out of the image context
 - Multi-arch image: `linux/amd64` and `linux/arm64` built and merged into a single manifest on GHCR
 - `tini` as PID 1 init process for correct signal handling
-- Non-root container user (`appuser`, uid 568) matching TrueNAS default app UID
+- Non-root container user (`appuser`, uid 568)
 - `HEALTHCHECK` in Dockerfile
 
 **Object mode**
@@ -73,7 +313,7 @@ First release of winnow. Forked from [if-curator](https://github.com/ds-sebastia
 - 24 unit tests across four modules: `test_config`, `test_immich_api`, `test_jobs`, `test_upload_tracker`
 
 **Documentation**
-- `docs/setup.md` — step-by-step install guide with TrueNAS and bare-Docker sections
+- `docs/setup.md` — step-by-step install and GPU passthrough guide
 - `docs/troubleshooting.md` — common failure modes with fixes
 - `docs/faq.md` — answers to questions new users will ask
 - `.env.example` — copy-paste starting point with every env var and inline comments

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,75 +1,130 @@
-# ── Platform-conditional base ─────────────────────────────────────────────
-#   amd64:  NVIDIA CUDA 12.6 (GPU acceleration when available, CPU fallback)
-#   arm64:  Plain Ubuntu (CPU-only, no CUDA on ARM)
+# ── Base images ───────────────────────────────────────────────────────────────
+#   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)
 
-FROM --platform=$BUILDPLATFORM nvidia/cuda:12.9.2-cudnn-runtime-ubuntu22.04 AS base-amd64
-FROM --platform=$BUILDPLATFORM ubuntu:22.04 AS base-arm64
+ARG VARIANT=gpu
 
-# ── Build stage ───────────────────────────────────────────────────────────
+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 ───────────────────────────────────────────────────────────────
 ARG TARGETARCH
 
-FROM base-${TARGETARCH} AS build
+FROM base-${TARGETARCH}-${VARIANT} AS build
 
+ARG VARIANT=gpu
 ENV DEBIAN_FRONTEND=noninteractive
 
+# Both Ubuntu 22.04 and 24.04 get Python 3.13 from the deadsnakes PPA.
+# GNUPGHOME is isolated so gpg never contacts an agent socket under QEMU.
 RUN apt-get update && apt-get install -y --no-install-recommends \
-    ca-certificates \
-    curl \
-    gnupg \
-    software-properties-common \
-    && add-apt-repository ppa:deadsnakes/ppa -y \
-    && apt-get update && apt-get install -y --no-install-recommends \
-    python3.12 python3.12-venv python3.12-dev \
+    ca-certificates curl gnupg software-properties-common \
+    && GNUPGHOME=$(mktemp -d) add-apt-repository ppa:deadsnakes/ppa -y \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends \
+    python3.13 python3.13-venv python3.13-dev \
     libgl1 libglib2.0-0 libxext6 g++ \
     && rm -rf /var/lib/apt/lists/* \
-    && ln -sf /usr/bin/python3.12 /usr/bin/python3
+    && ln -sf /usr/bin/python3.13 /usr/bin/python3
 
 RUN curl -LsSf https://astral.sh/uv/install.sh | sh \
     && cp /root/.local/bin/uv /usr/local/bin/uv
 
 WORKDIR /app
 
-COPY pyproject.toml uv.lock ./
-RUN uv sync --frozen --no-dev \
+# 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; \
+    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
 
 COPY winnow/ winnow/
 COPY entrypoint.sh scheduler.py ./
 RUN chmod +x /app/entrypoint.sh
 
-# ── Runtime stage ─────────────────────────────────────────────────────────
+# ── Runtime stage ─────────────────────────────────────────────────────────────
 #   Starts fresh from the base image — excludes build tools (g++,
-#   python3.12-dev, curl, gnupg) that are not needed at runtime.
+#   python3.13-dev, gnupg, software-properties-common) not needed at runtime.
 
-FROM base-${TARGETARCH} AS runtime
+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 \
-    ca-certificates \
-    software-properties-common \
-    tini \
-    && add-apt-repository ppa:deadsnakes/ppa -y \
-    && apt-get update && apt-get install -y --no-install-recommends \
-    python3.12 python3.12-venv \
+    ca-certificates curl gnupg software-properties-common tini \
+    && GNUPGHOME=$(mktemp -d) add-apt-repository ppa:deadsnakes/ppa -y \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends \
+    python3.13 python3.13-venv \
     libgl1 libglib2.0-0 libxext6 \
+    && apt-get purge -y --auto-remove curl gnupg software-properties-common \
     && rm -rf /var/lib/apt/lists/* \
-    && ln -sf /usr/bin/python3.12 /usr/bin/python3
+    && ln -sf /usr/bin/python3.13 /usr/bin/python3
 
 # Copy app (with .venv) and uv from build stage
 COPY --from=build /app /app
 COPY --from=build /usr/local/bin/uv /usr/local/bin/uv
 
-# Expose CUDA/cuDNN libraries from pip packages so onnxruntime-gpu
-# can find libcublasLt.so.12 and libcudnn.so.9 at runtime
-ENV LD_LIBRARY_PATH="/app/.venv/lib/python3.12/site-packages/nvidia/cudnn/lib:/app/.venv/lib/python3.12/site-packages/nvidia/cuda_runtime/lib:${LD_LIBRARY_PATH}"
+# 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 \
     && chown -R appuser:apps /app /models
 
+WORKDIR /app
 USER appuser
-ENV HF_HOME=/models/huggingface INSIGHTFACE_HOME=/models
+# PYTHONPATH=/app makes the winnow package importable from the entry point script.
+# uv sync builds the wheel before winnow/ is COPY'd, so site-packages has only
+# the dist-info. Explicitly adding /app lets Python find winnow/__init__.py there.
+ENV HF_HOME=/models/huggingface INSIGHTFACE_HOME=/models/.insightface PYTHONPATH=/app
 
 HEALTHCHECK CMD test -f /app/entrypoint.sh || exit 1
 ENTRYPOINT ["tini", "--", "/app/entrypoint.sh"]

LICENSE

@@ -1,22 +1,661 @@
-MIT License
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
 
-Copyright (c) 2026 Holden Salomon
-Copyright (c) 2026 Sebastian
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
 
-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:
+                            Preamble
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server 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.
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.

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,29 +1,22 @@
-[![Publish Docker Image](https://github.com/sudolulo/winnow/actions/workflows/docker-publish.yml/badge.svg)](https://github.com/sudolulo/winnow/actions/workflows/docker-publish.yml) [![Release](https://github.com/sudolulo/winnow/actions/workflows/release.yml/badge.svg)](https://github.com/sudolulo/winnow/actions/workflows/release.yml) [![Lint](https://github.com/sudolulo/winnow/actions/workflows/lint.yml/badge.svg)](https://github.com/sudolulo/winnow/actions/workflows/lint.yml) [![Test](https://github.com/sudolulo/winnow/actions/workflows/test.yml/badge.svg)](https://github.com/sudolulo/winnow/actions/workflows/test.yml)
-
-**Docs:** [Setup Guide](docs/setup.md) · [Troubleshooting](docs/troubleshooting.md) · [FAQ](docs/faq.md)
-
 # winnow
 
-`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.
+[![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)
 
-It runs fully headless in Docker, is configured entirely through environment variables, and can run on a schedule — no interactive prompts, no manual steps.
+> **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)
 
-## The Problem
+`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.
 
-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**.
+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.
 
-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.
-
-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
       │
@@ -31,78 +24,78 @@ 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.
+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.
 
 ---
 
 ## Running in Docker
 
+### Image Tags
+
+| 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:
@@ -111,8 +104,7 @@ services:
       - IMMICH_URL=http://192.168.1.10:2283
       - API_KEY=your-immich-api-key
       - FRIGATE_URL=http://192.168.1.10:5000
-      - AUTO_MODE=true
-      - 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
@@ -126,80 +118,119 @@ services:
               capabilities: [gpu]
 ```
 
-See [compose.yml](compose.yml) for the full annotated example including TrueNAS volume paths.
+**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
+```
 
-### Scheduling Behaviour
+**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)
+```
 
-On startup the container always runs once immediately. If `CRON_SCHEDULE` is set, it then starts a scheduler that fires on the defined interval, keeping the process (and loaded models) alive between runs. Without `CRON_SCHEDULE` the container exits after the first run.
+**CPU (`:cpu`):** use `image: ghcr.io/sudolulo/winnow:cpu`, remove the `deploy:` block, and add `mem_limit: 2g` to prevent OOM on large libraries.
 
-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.
+See [compose.yml](compose.yml) for the full annotated example with all options.
+
+### Scheduling
+
+`CRON_SCHEDULE` controls container lifetime:
+
+| `CRON_SCHEDULE` value | Behaviour |
+| :-- | :-- |
+| *(unset)* | Run once on startup, then exit |
+| *(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. 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` | `false` | Run without interactive prompts — required for Docker/cron use |
-| `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 |
-| `ENABLE_CACHE` | `false` | Cache computed embeddings to disk (speeds up re-runs on the same library) |
+| `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)* | Cron expression for recurring runs — unset exits after first run |
+| `CRON_SCHEDULE` | *(unset)* | Unset = run once and exit; empty = stay alive; cron expression = scheduled |
 
 ---
 
@@ -212,19 +243,29 @@ uv sync
 uv run winnow
 ```
 
-Requires Python 3.12+ 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.12+**
+- **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
 
 ---
 
 ## Attribution
 
-Based on [winnow](https://github.com/ds-sebastian/if_curator) by Sebastian, licensed MIT.
+Based on [if_curator](https://github.com/ds-sebastian/if_curator) by Sebastian, licensed MIT.

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.override.yml

@@ -1,8 +0,0 @@
-services:
-  winnow:
-    build: .
-    network_mode: host
-    volumes:
-      - /code/winnow/models:/models
-      - /code/winnow/embeddings:/app/.if_cache
-      - /code/winnow/output:/app/frigate_train

compose.yml

@@ -9,7 +9,10 @@ services:
       - FRIGATE_URL=${FRIGATE_URL}
 
       # ── Mode & Strategy ───────────────────────────────────────────────────
-      - AUTO_MODE=true
+      # Auto mode is active by default when no TTY is present (Docker/cron).
+      # Set AUTO_MODE=true to force auto mode in an interactive terminal.
+      # To run interactively: docker exec -it winnow winnow
+      # - VERBOSE=true                # Enable DEBUG-level console output
       # TRAINING_MODE: face = upload to Frigate face recognition API
       #                object = save crops to output dir for manual Frigate placement
       - TRAINING_MODE=face
@@ -34,11 +37,12 @@ services:
       # - MAX_AUTO_IMAGES=80          # Hard cap on auto-diversity selection (default: 80)
 
       # ── Caching & Models ──────────────────────────────────────────────────
-      - FORCE_CPU=false
-      - ENABLE_CACHE=true
+      # - 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
-      - INSIGHTFACE_HOME=/models
+      - INSIGHTFACE_HOME=/models/.insightface
 
       # ── Tracker overrides (one-shot, remove after use) ────────────────────
       # - DRY_RUN=true                # Preview selection without downloading/uploading
@@ -46,19 +50,23 @@ services:
       # - RESET_PERSON=John           # Clear uploaded+rejected history for one person
 
       # ── Scheduling ────────────────────────────────────────────────────────
-      # Cron expression (unset = run once and exit)
-      # Every Sunday at 3 AM:
-      - CRON_SCHEDULE=0 3 * * 0
-      # - CRON_SCHEDULE=0 3 1 * *
-      # - CRON_SCHEDULE=*/30 * * * *
+      # CRON_SCHEDULE controls container lifetime:
+      #   unset          — run once on startup, then exit
+      #   empty string   — stay alive, run nothing; trigger manually with:
+      #                    docker exec -it winnow winnow
+      #   cron expression — run on startup, then on schedule
+      # - CRON_SCHEDULE=                # Manual mode (keep alive, no auto-run)
+      # - CRON_SCHEDULE=0 3 * * 0      # Every Sunday at 3 AM
+      # - CRON_SCHEDULE=0 3 1 * *      # First of every month
     volumes:
-      # Replace <pool> with your TrueNAS pool name, e.g. /mnt/tank/winnow/...
-      - /mnt/<pool>/winnow/models:/models
-      - /mnt/<pool>/winnow/embeddings:/app/.if_cache
-      - /mnt/<pool>/winnow/output:/app/frigate_train
-    stdin_open: true
-    tty: true
+      # Replace with absolute paths on your host, e.g. /opt/winnow/models
+      - /path/to/winnow/models:/models
+      - /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:
@@ -66,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.

docs/faq.md

@@ -1,63 +0,0 @@
-# FAQ
-
-## Does winnow modify my Immich library?
-
-No. winnow only reads from Immich (assets, people, face bounding boxes). It never writes back to Immich or deletes anything.
-
----
-
-## How many images should I upload to Frigate?
-
-The `auto` strategy decides this for you — it keeps selecting until adding more images would be redundant. In practice this is usually 20–60 per person. You can cap it with `MAX_AUTO_IMAGES` (default 80).
-
-Quality and diversity matter far more than volume. 30 well-spread images outperform 200 from the same week.
-
----
-
-## What's the difference between face mode and object mode?
-
-- **Face mode**: Extracts and aligns face crops, uploads them directly to Frigate's face training API. This is for teaching Frigate to recognize specific people.
-- **Object mode**: Runs YOLO detection on full images and saves crops of a target class (dog, cat, car, etc.) to disk. Frigate has no API for object training data, so you place them manually.
-
----
-
-## Can I run it without Frigate?
-
-Yes — in object mode, `FRIGATE_URL` is not used and crops are saved to the output volume. In face mode you need Frigate to receive the uploads, but you can use `DRY_RUN=true` to preview selection without uploading.
-
----
-
-## How does auto-diversity mode work?
-
-winnow computes a vector embedding for each candidate image (what the face/object actually looks like — angle, lighting, expression). It then clusters those embeddings and picks representatives that are maximally spread across the embedding space. It stops when the next-most-different image is already close to something already selected. See the README for the full pipeline.
-
----
-
-## Does it support multiple people in one run?
-
-Yes. By default it processes every named person in your Immich library. Use `ONLY_PEOPLE` to whitelist specific names or `SKIP_PEOPLE` to exclude them.
-
----
-
-## What GPU is needed?
-
-Any NVIDIA GPU with CUDA 12.x support. The models (InsightFace Buffalo_L + SigLIP) fit comfortably in 4 GB VRAM. CPU mode works but is significantly slower.
-
-ARM builds (linux/arm64) use CPU-only — CUDA is not available on ARM.
-
----
-
-## Does it work on Unraid / Proxmox / bare Docker?
-
-Yes — the `compose.yml` uses standard Docker volume mounts. The TrueNAS paths in the example (`/mnt/<pool>/...`) are just an example; replace them with whatever paths suit your setup.
-
----
-
-## How do I update winnow?
-
-```bash
-docker compose pull
-docker compose up -d
-```
-
-The `latest` tag on GHCR tracks the `main` branch. Pinning to a version tag (e.g. `ghcr.io/sudolulo/winnow:v0.2.0`) is recommended for stability.

docs/setup.md

@@ -1,88 +0,0 @@
-# Setup Guide
-
-## Prerequisites
-
-- [Immich](https://immich.app) v1.106+ with face recognition enabled and people tagged
-- [Frigate](https://frigate.video) v0.16+ (face mode only)
-- Docker with the NVIDIA container toolkit (optional but strongly recommended)
-
----
-
-## 1. Get your Immich API key
-
-1. Open Immich → **Account Settings** → **API Keys**
-2. Click **New API Key**, give it a name (e.g. `winnow`), copy the key
-
----
-
-## 2. Get your Frigate URL
-
-This is the base URL of your Frigate instance, e.g. `http://192.168.1.10:5000`. Only needed for face mode — omit it entirely if you're using object mode.
-
----
-
-## 3. Deploy with Docker Compose
-
-Copy [`compose.yml`](../compose.yml) and [`.env.example`](../.env.example) to a directory on your host:
-
-```bash
-mkdir winnow && cd winnow
-curl -O https://raw.githubusercontent.com/sudolulo/winnow/main/compose.yml
-curl -O https://raw.githubusercontent.com/sudolulo/winnow/main/.env.example
-cp .env.example .env
-```
-
-Edit `.env` with your values:
-
-```bash
-IMMICH_URL=http://192.168.1.10:2283
-API_KEY=your-immich-api-key
-FRIGATE_URL=http://192.168.1.10:5000
-```
-
-Edit the volume paths in `compose.yml` to match your storage layout (replace `/mnt/<pool>` with your actual path).
-
-Start it:
-
-```bash
-docker compose up -d
-```
-
-Logs:
-
-```bash
-docker compose logs -f winnow
-```
-
----
-
-## 4. First run
-
-On the first run, winnow downloads the embedding models (~1–2 GB) from HuggingFace and InsightFace. This happens once — subsequent runs use the cached models from your mounted volume and start immediately.
-
----
-
-## 5. Scheduling
-
-Set `CRON_SCHEDULE` in your `.env` to keep winnow running on a schedule:
-
-```
-CRON_SCHEDULE=0 3 * * 0   # Every Sunday at 3 AM
-```
-
-Without `CRON_SCHEDULE`, the container runs once and exits.
-
----
-
-## TrueNAS Scale
-
-The included `compose.yml` uses TrueNAS-style volume paths. Replace `<pool>` with your pool name:
-
-```yaml
-volumes:
-  - /mnt/tank/winnow/models:/models
-  - /mnt/tank/winnow/embeddings:/app/.if_cache
-  - /mnt/tank/winnow/output:/app/frigate_train
-```
-
-GPU passthrough on TrueNAS requires the NVIDIA app to be installed from the TrueNAS catalog and the `deploy.resources.reservations.devices` block in `compose.yml` (already included).

docs/troubleshooting.md

@@ -1,77 +0,0 @@
-# Troubleshooting
-
-## Container exits immediately
-
-Check logs:
-```bash
-docker compose logs winnow
-```
-
-Common causes:
-- **Missing required env var** — `IMMICH_URL` or `API_KEY` not set
-- **Cannot reach Immich** — check the URL and that Immich is running; use `http://` not `https://` unless you have TLS set up
-
----
-
-## "No people found" / nothing processed
-
-- Make sure Immich has completed face recognition and you have named people in your library
-- `YEARS_FILTER` defaults to 10 years — increase it if your tagged photos are older
-- `MIN_FACE_COUNT` skips people with few photos — lower or remove it
-
----
-
-## Frigate upload fails
-
-- Confirm `FRIGATE_URL` is reachable from inside the container: `docker exec winnow curl $FRIGATE_URL/api/stats`
-- Check Frigate v0.16+ — older versions don't have the face training API
-- Set `DRY_RUN=true` to verify selection without uploading
-
----
-
-## Models fail to download
-
-winnow downloads InsightFace and HuggingFace (SigLIP) models on first run.
-
-- Ensure the container has internet access
-- Confirm the model volume is mounted and writable
-- If behind a proxy, set `HTTP_PROXY` / `HTTPS_PROXY` env vars
-
----
-
-## Running on CPU (no GPU)
-
-Set `FORCE_CPU=true`. Everything works but embedding computation is slower — expect several minutes per person instead of seconds.
-
-If you have a GPU but it's not being used:
-- Confirm the NVIDIA container toolkit is installed: `docker run --rm --gpus all nvidia/cuda:12.9.2-base-ubuntu22.04 nvidia-smi`
-- Confirm the `deploy.resources.reservations.devices` block is present in `compose.yml`
-
----
-
-## Same images uploaded every run
-
-The upload tracker is stored in `CACHE_DIR` (`/app/.if_cache` by default). If this volume isn't persisted between runs, the tracker resets and images are re-uploaded.
-
-Make sure `/app/.if_cache` is mounted to a persistent host path.
-
----
-
-## Re-uploading a specific person
-
-To clear the upload history for one person and start fresh:
-
-```env
-RESET_PERSON=John
-```
-
-Remove this after one run — it clears the history and then processes normally.
-
----
-
-## Image quality issues
-
-- **Too blurry**: Lower `BLUR_THRESHOLD` (default 100) — e.g. `50` accepts more blur
-- **Face too small**: Lower `MIN_FACE_WIDTH` (default 50px)
-- **Low confidence detections included**: Raise `MIN_CONFIDENCE` (default 0.7)
-- **Rejected images being re-tried**: Set `RETRY_REJECTED=true` for one run

entrypoint.sh

@@ -2,16 +2,23 @@
 set -e
 export PYTHONUNBUFFERED=1
 
-# 1. Run the job immediately on startup
+# CRON_SCHEDULE controls container lifetime:
+#   unset          — run once and exit
+#   empty string   — stay alive, run nothing (use: docker exec -it winnow winnow)
+#   cron expression — run immediately, then on schedule
+
+if [ "${CRON_SCHEDULE+isset}" = "isset" ] && [ -z "$CRON_SCHEDULE" ]; then
+    echo "▶ CRON_SCHEDULE is empty — manual mode. Use 'docker exec -it winnow winnow' to run."
+    exec sleep infinity
+fi
+
 echo "▶ Running on startup..."
-uv run python -m winnow.cli
+/app/.venv/bin/winnow
 
-# 2. If a schedule exists, start the scheduler
 if [ -n "${CRON_SCHEDULE:-}" ]; then
     echo "▶ CRON_SCHEDULE set to: $CRON_SCHEDULE"
     echo "▶ Switching to scheduled mode..."
-    exec uv run python3 /app/scheduler.py
+    exec /app/.venv/bin/python /app/scheduler.py
 else
     echo "▶ No schedule set, exiting."
 fi
-

pyproject-cpu.toml

@@ -0,0 +1,93 @@
+[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>=1.23.2",
+    "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]
+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 = "onnxruntime"
+requests = "requests"
+rich = "rich"
+torch = "torch"
+transformers = "transformers"
+ultralytics = "ultralytics"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

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,16 +1,17 @@
 [project]
 name = "winnow"
-version = "0.2.0"
-description = "Immich to Frigate training sets"
-license = "MIT"
-requires-python = ">=3.12"
+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" }]
 keywords = ["immich", "frigate", "face-recognition", "training-data", "arcface", "insightface"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
-    "Programming Language :: Python :: 3.12",
+    "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",
 ]
 dependencies = [
@@ -18,15 +19,18 @@ dependencies = [
     "insightface>=0.7.3",
     "nvidia-cudnn-cu12>=9.0.0",
     "numpy>=2.2.6",
-    "onnxruntime-gpu>=1.23.2",
+    "onnxruntime-gpu>=1.23.2; sys_platform == 'linux' and platform_machine == 'x86_64'",
+    "onnxruntime>=1.23.2; sys_platform == 'linux' and platform_machine != 'x86_64'",
+    "onnxruntime>=1.23.2; sys_platform != 'linux'",
     "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.6.0",
-    "transformers>=4.57.6",
-    "ultralytics>=8.3.252",
+    "torch>=2.12.0",
+    "torchvision>=0.27.0",
+    "transformers>=5.12.0",
+    "ultralytics>=8.4.66",
 ]
 
 [project.scripts]
@@ -34,9 +38,20 @@ 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-gpu>=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'",
+]
 
 [tool.uv.sources]
 torch = [
@@ -44,6 +59,11 @@ torch = [
     { index = "pytorch-cpu", marker = "sys_platform == 'linux' and platform_machine == 'aarch64'" },
     { index = "pytorch-cpu", marker = "sys_platform != 'linux'" },
 ]
+torchvision = [
+    { index = "pytorch-cu126", marker = "sys_platform == 'linux' and platform_machine == 'x86_64'" },
+    { index = "pytorch-cpu", marker = "sys_platform == 'linux' and platform_machine == 'aarch64'" },
+    { index = "pytorch-cpu", marker = "sys_platform != 'linux'" },
+]
 
 [[tool.uv.index]]
 name = "pytorch-cu126"
@@ -58,7 +78,7 @@ explicit = true
 [dependency-groups]
 dev = [
     "pytest>=8.0",
-    "ruff>=0.9.2",
+    "ruff>=0.15.17",
 ]
 
 [tool.hatch.build.targets.wheel]
@@ -66,7 +86,7 @@ packages = ["winnow"]
 
 [tool.ruff]
 line-length = 120
-target-version = "py312"
+target-version = "py313"
 
 [tool.ruff.lint]
 select = ["E", "F", "I"]

scheduler.py

@@ -1,41 +1,34 @@
 #!/usr/bin/env python3
+import logging
 import os
 import sys
-import subprocess
 import time
-import logging
 from pathlib import Path
 
 try:
     from croniter import croniter
 except ImportError:
-    print("❌ croniter not installed. Run: uv add croniter")
+    print("croniter not installed. Run: uv add croniter")
     sys.exit(1)
 
+# Imported at module level so models loaded during the first run stay
+# resident in memory across all subsequent scheduled runs.
+from winnow.cli import main
+
 SCHEDULE = os.environ["CRON_SCHEDULE"]
 MODELS_DIR = os.environ.get("HF_HOME", "/models/huggingface")
-INSIGHTFACE_BASE = os.environ.get("INSIGHTFACE_HOME", "/models")
-
-RUN_ENV = {**os.environ, "PYTHONUNBUFFERED": "1"}
+INSIGHTFACE_HOME = os.environ.get("INSIGHTFACE_HOME", "/models/.insightface")
 
 logger = logging.getLogger(__name__)
 
 
-def check_models():
-    """Log model status before each run."""
-    print("📦 Checking models...", flush=True)
-    buffalo = Path(INSIGHTFACE_BASE) / ".insightface" / "models" / "buffalo_l"
-    if buffalo.exists():
-        print("  ✅ InsightFace Buffalo_L: present", flush=True)
-    else:
-        print("  ⬇️  InsightFace Buffalo_L: not found — will download", flush=True)
-
+def check_models() -> None:
+    buffalo = Path(INSIGHTFACE_HOME) / "models" / "buffalo_l"
     hf_hub = Path(MODELS_DIR) / "hub"
-    if hf_hub.exists() and any(hf_hub.iterdir()):
-        print("  ✅ HuggingFace models: present", flush=True)
-    else:
-        print("  ⬇️  HuggingFace models: not found — will download", flush=True)
-    print("🚀 Starting winnow...", flush=True)
+    if not buffalo.exists():
+        print("  InsightFace Buffalo_L not found — will download on first run", flush=True)
+    if not (hf_hub.exists() and any(hf_hub.iterdir())):
+        print("  HuggingFace models not found — will download on first run", flush=True)
 
 
 NOW = time.time()
@@ -45,14 +38,15 @@ next_run = cron.get_next(float)
 while True:
     now = time.time()
     if now >= next_run:
-        print(f"\n▶ [{time.strftime('%Y-%m-%d %H:%M:%S')}] Starting winnow...", flush=True)
+        print(f"\n[{time.strftime('%Y-%m-%d %H:%M:%S')}] Starting winnow run...", flush=True)
         check_models()
-        result = subprocess.run(["uv", "run", "winnow"], env=RUN_ENV)
-        if result.returncode != 0:
-            logger.error(f"winnow exited with code {result.returncode}")
-            print(f"❌ winnow failed with exit code {result.returncode}", flush=True)
-        else:
-            print("✅ winnow completed successfully", flush=True)
+        try:
+            main()
+            print("winnow run complete", flush=True)
+        except KeyboardInterrupt:
+            raise
+        except Exception as e:
+            logger.error(f"winnow run failed: {e}", exc_info=True)
+            print(f"winnow run failed: {e}", flush=True)
         next_run = cron.get_next(float)
-    time.sleep(60)
-
+    time.sleep(max(1, next_run - time.time()))

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

@@ -1,8 +1,6 @@
 """Smoke tests for configuration loading."""
 
-import os
 
-import pytest
 
 
 def test_config_loads_defaults(monkeypatch):
@@ -19,15 +17,16 @@ 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
-    assert cfg.ENABLE_CACHE is False
+    assert cfg.ENABLE_CACHE is True
 
     _Config.reset()
 
@@ -41,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")
@@ -56,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

@@ -0,0 +1,161 @@
+"""Tests for image quality filtering functions."""
+
+import numpy as np
+from PIL import Image
+
+
+def _rgb_image(r, g, b, size=(100, 100)) -> Image.Image:
+    arr = np.full((*size, 3), [r, g, b], dtype=np.uint8)
+    return Image.fromarray(arr, "RGB")
+
+
+def _noisy_color_image(size=(100, 100)) -> Image.Image:
+    """Noisy image with a strong red channel so grayscale check passes."""
+    rng = np.random.default_rng(0)
+    arr = rng.integers(0, 256, (*size, 3), dtype=np.uint8)
+    arr[:, :, 0] = np.clip(arr[:, :, 0].astype(int) + 80, 0, 255).astype(np.uint8)
+    arr[:, :, 2] = np.clip(arr[:, :, 2].astype(int) - 80, 0, 255).astype(np.uint8)
+    return Image.fromarray(arr, "RGB")
+
+
+# ── check_blur ────────────────────────────────────────────────────────────────
+
+def test_blur_rejects_flat_image():
+    from winnow.quality import check_blur
+    flat = np.full((100, 100, 3), 128, dtype=np.uint8)
+    passed, reason = check_blur(flat, threshold=100.0)
+    assert not passed
+    assert "Blurry" in reason
+
+
+def test_blur_passes_noisy_color_image():
+    from winnow.quality import check_blur
+    img = _noisy_color_image()
+    passed, _ = check_blur(np.asarray(img), threshold=100.0)
+    assert passed
+
+
+# ── check_grayscale ───────────────────────────────────────────────────────────
+
+def test_grayscale_rejects_ir_image():
+    from winnow.quality import check_grayscale
+    gray = np.full((100, 100, 3), 128, dtype=np.uint8)
+    passed, reason = check_grayscale(gray)
+    assert not passed
+    assert "Grayscale" in reason
+
+
+def test_grayscale_passes_color_image():
+    from winnow.quality import check_grayscale
+    color = np.zeros((100, 100, 3), dtype=np.uint8)
+    color[:, :, 0] = 200  # strong red channel
+    passed, _ = check_grayscale(color)
+    assert passed
+
+
+def test_grayscale_rejects_single_channel():
+    from winnow.quality import check_grayscale
+    single = np.full((100, 100, 1), 128, dtype=np.uint8)
+    passed, reason = check_grayscale(single)
+    assert not passed
+
+
+# ── check_exposure ────────────────────────────────────────────────────────────
+
+def test_exposure_rejects_black_image():
+    from winnow.quality import check_exposure
+    black = np.zeros((100, 100, 3), dtype=np.uint8)
+    passed, reason = check_exposure(black)
+    assert not passed
+    assert "Underexposed" in reason
+
+
+def test_exposure_rejects_white_image():
+    from winnow.quality import check_exposure
+    white = np.full((100, 100, 3), 255, dtype=np.uint8)
+    passed, reason = check_exposure(white)
+    assert not passed
+    assert "Overexposed" in reason
+
+
+def test_exposure_passes_normal_image():
+    from winnow.quality import check_exposure
+    mid = np.full((100, 100, 3), 128, dtype=np.uint8)
+    passed, _ = check_exposure(mid)
+    assert passed
+
+
+# ── check_face_size ───────────────────────────────────────────────────────────
+
+def test_face_size_rejects_small_face():
+    from winnow.quality import check_face_size
+    passed, reason = check_face_size(30, 30, min_px=50)
+    assert not passed
+    assert "small" in reason
+
+
+def test_face_size_passes_adequate_face():
+    from winnow.quality import check_face_size
+    passed, _ = check_face_size(100, 100, min_px=50)
+    assert passed
+
+
+def test_face_size_rejects_if_either_dimension_small():
+    from winnow.quality import check_face_size
+    passed, _ = check_face_size(100, 30, min_px=50)
+    assert not passed
+
+
+# ── check_confidence ──────────────────────────────────────────────────────────
+
+def test_confidence_rejects_low_score():
+    from winnow.quality import check_confidence
+    passed, reason = check_confidence(0.5, min_conf=0.7)
+    assert not passed
+    assert "confidence" in reason.lower()
+
+
+def test_confidence_passes_high_score():
+    from winnow.quality import check_confidence
+    passed, _ = check_confidence(0.95, min_conf=0.7)
+    assert passed
+
+
+def test_confidence_passes_none_score():
+    from winnow.quality import check_confidence
+    passed, _ = check_confidence(None, min_conf=0.7)
+    assert passed
+
+
+# ── assess_quality (integration) ─────────────────────────────────────────────
+
+def test_assess_quality_passes_good_image():
+    from winnow.quality import assess_quality
+    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():
+    from winnow.quality import assess_quality
+    black = _rgb_image(0, 0, 0)
+    result = assess_quality(black, face_bbox=(0, 0, 10, 10), confidence=0.3)
+    assert not result.passed
+    assert len(result.reasons) >= 2
+
+
+def test_assess_quality_skips_face_size_without_bbox():
+    from winnow.quality import assess_quality
+    img = _noisy_color_image()
+    result = assess_quality(img, face_bbox=None, confidence=0.9)
+    assert result.passed

tests/test_upload_tracker.py

@@ -1,8 +1,5 @@
 """Tests for upload tracker — mark, filter, reset, and summary logic."""
 
-import json
-import os
-import tempfile
 
 import pytest
 
@@ -72,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

winnow/__init__.py

@@ -5,4 +5,9 @@ Immich library for Frigate's Face Recognition (ArcFace) and Object/State
 Classification models.
 """
 
-__version__ = "0.1.0"
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("winnow")
+except PackageNotFoundError:
+    __version__ = "unknown"

winnow/cli.py

@@ -2,6 +2,7 @@
 
 import logging
 import os
+import sys
 
 from rich import print as rprint
 from rich.prompt import Confirm
@@ -10,16 +11,55 @@ from .config import Config, ConfigManager
 from .executor import execute_jobs, upload_to_frigate
 from .immich_api import get_people
 from .jobs import _show_preview, auto_configure, interactive_configure
-from .logging import console, setup_logging
-from .upload_tracker import get_person_summary, reset_person
+from .log_config import console, setup_logging
+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:
-        setup_logging(verbose=False)
+        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]
@@ -48,24 +88,33 @@ def main() -> None:
         if summary:
             rprint("\n[dim]Tracker summary:[/dim]")
             for person_name, counts in summary.items():
-                rprint(f"  [dim]{person_name}: {counts['uploaded']} uploaded, {counts['rejected']} rejected[/dim]")
+                frigate_part = (
+                    f", {counts['frigate_count']} in Frigate"
+                    if counts.get("frigate_count") is not None
+                    else ""
+                )
+                rprint(
+                    f"  [dim]{person_name}: {counts['uploaded']} uploaded,"
+                    f" {counts['rejected']} rejected{frigate_part}[/dim]"
+                )
 
         people = get_people()
         if not people:
             rprint("[bold red]Could not fetch people from Immich. Check URL/Key.[/bold red]")
             return
 
-        # Check for non-interactive mode
-        auto_mode = os.environ.get("AUTO_MODE", "false").lower() == "true"
+        # Auto mode when no TTY (Docker, cron, pipes) — the primary use case.
+        # A TTY means local interactive use; AUTO_MODE=true overrides that for scripting.
+        auto_mode = not sys.stdin.isatty() or os.environ.get("AUTO_MODE", "").lower() in ("true", "1", "yes")
         dry_run = os.environ.get("DRY_RUN", "false").lower() in ("true", "1", "yes")
 
         if dry_run:
             rprint("[bold yellow]DRY RUN — no images will be downloaded or uploaded[/bold yellow]")
 
         if auto_mode:
-            rprint("[bold cyan]Running in AUTO mode (non-interactive)[/bold cyan]")
             jobs = auto_configure(people)
         else:
+            rprint("[bold cyan]Interactive mode — set AUTO_MODE=true to skip prompts[/bold cyan]")
             jobs = interactive_configure(people)
 
         if jobs:

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
@@ -39,8 +42,7 @@ class _Config:
     USE_FULL_RESOLUTION: bool = True
     ENABLE_FACE_ALIGNMENT: bool = True
 
-    # Caching (opt-in to avoid unexpected files)
-    ENABLE_CACHE: bool = False
+    ENABLE_CACHE: bool = True
     CACHE_DIR: str = ".if_cache"
 
     def __new__(cls) -> "_Config":
@@ -56,23 +58,25 @@ 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")
-        self.ENABLE_CACHE = os.getenv("ENABLE_CACHE", "false").lower() in ("true", "1", "yes")
+        self.ENABLE_CACHE = os.getenv("ENABLE_CACHE", "true").lower() in ("true", "1", "yes")
         self.CACHE_DIR = os.getenv("CACHE_DIR", ".if_cache")
 
-        # Fall back to config file for missing values
+        # Fall back to config file for non-sensitive values (API_KEY not stored here)
         if CONFIG_FILE.exists():
             try:
                 data = json.loads(CONFIG_FILE.read_text())
                 self.IMMICH_URL = self.IMMICH_URL or data.get("IMMICH_URL")
-                self.API_KEY = self.API_KEY or data.get("API_KEY")
                 if not os.getenv("OUTPUT_DIR"):
                     self.OUTPUT_DIR = data.get("OUTPUT_DIR", self.OUTPUT_DIR)
             except (json.JSONDecodeError, OSError) as e:
@@ -84,13 +88,16 @@ class _Config:
         cls._instance = None
 
     def save(self) -> None:
-        """Persist configuration to file."""
+        """Persist non-sensitive configuration to file.
+
+        API_KEY is intentionally excluded — store it in .env or as an
+        environment variable instead of a plain-text config file.
+        """
         try:
             CONFIG_FILE.write_text(
                 json.dumps(
                     {
                         "IMMICH_URL": self.IMMICH_URL,
-                        "API_KEY": self.API_KEY,
                         "OUTPUT_DIR": self.OUTPUT_DIR,
                     },
                     indent=2,
@@ -113,8 +120,8 @@ class _Config:
 
         if not self.API_KEY:
             console.print("[yellow]Immich API Key not found.[/yellow]")
+            console.print("[dim]Tip: set API_KEY in your .env file to avoid re-entering it.[/dim]")
             self.API_KEY = Prompt.ask("Enter Immich API Key", password=True)
-            self.save()
 
     def validate(self) -> None:
         """Raise ValueError if required config is missing."""
@@ -159,7 +166,12 @@ class _ConfigAccessor:
 
 
 Config = _ConfigAccessor()
-ConfigManager = type("ConfigManager", (), {"get": staticmethod(lambda: _Config())})
+
+
+class ConfigManager:
+    @staticmethod
+    def get() -> _Config:
+        return _Config()
 
 
 def get_headers() -> dict[str, str]:

winnow/diversity.py

@@ -29,6 +29,7 @@ def select_diverse_assets(
     entity_name: str,
     selection_mode: str = "smart",
     entity_type: str = "face",
+    person_id: str | None = None,
     progress_callback=None,
 ) -> list:
     """
@@ -59,7 +60,7 @@ def select_diverse_assets(
         return _select_time_spread(assets, limit)
 
     try:
-        return _select_by_embedding(assets, limit, entity_type, progress_callback)
+        return _select_by_embedding(assets, limit, entity_type, person_id, progress_callback)
     except Exception as e:
         logger.error(f"Smart Diversity failed: {e}. Falling back to time spread.")
         return _select_time_spread(assets, limit)
@@ -80,9 +81,11 @@ def _fetch_thumbnail(asset_id: str, timeout: int = 10) -> Image.Image | None:
         return None
 
 
-def _get_face_bbox(asset: dict) -> tuple[float, float, float, float] | None:
-    """Extract face bounding box from asset metadata if available."""
+def _get_face_bbox(asset: dict, person_id: str | None = None) -> tuple[float, float, float, float] | None:
+    """Extract face bounding box from asset metadata for the given person."""
     for person in asset.get("people", []):
+        if person_id and person.get("id") != person_id:
+            continue
         faces = person.get("faces", [])
         if faces:
             f = faces[0]
@@ -95,12 +98,16 @@ def _get_face_bbox(asset: dict) -> tuple[float, float, float, float] | None:
     return None
 
 
-def _get_face_confidence(asset: dict) -> float | None:
-    """Extract face detection confidence from asset metadata if available."""
+def _get_face_confidence(asset: dict, person_id: str | None = None) -> float | None:
+    """Extract face detection confidence from asset metadata for the given person."""
     for person in asset.get("people", []):
+        if person_id and person.get("id") != person_id:
+            continue
         faces = person.get("faces", [])
         if faces:
-            return faces[0].get("score") or faces[0].get("confidence")
+            f = faces[0]
+            score = f.get("score")
+            return score if score is not None else f.get("confidence")
     return None
 
 
@@ -108,6 +115,7 @@ def _crop_face_from_thumbnail(
     img: Image.Image,
     asset: dict,
     margin: float = 0.25,
+    person_id: str | None = None,
 ) -> Image.Image | None:
     """Crop the face region from a thumbnail using Immich bbox metadata.
 
@@ -118,19 +126,22 @@ def _crop_face_from_thumbnail(
         img: Full preview thumbnail
         asset: Asset dict with people/faces metadata
         margin: Extra margin around the bbox (fraction, default 25%)
+        person_id: If provided, only crop from this person's face data.
 
     Returns:
         Cropped face PIL image, or None if no face metadata available
     """
-    bbox = _get_face_bbox(asset)
+    bbox = _get_face_bbox(asset, person_id=person_id)
     if bbox is None:
         return None
 
     x1, y1, x2, y2 = bbox
     img_w, img_h = img.size
 
-    # Get metadata dimensions to scale bbox
+    # Get metadata dimensions to scale bbox — must match the same person as _get_face_bbox
     for person in asset.get("people", []):
+        if person_id and person.get("id") != person_id:
+            continue
         faces = person.get("faces", [])
         if faces:
             meta_w = faces[0].get("imageWidth") or img_w
@@ -169,6 +180,7 @@ def _select_by_embedding(
     assets: list,
     limit: int | str,
     entity_type: str,
+    person_id: str | None = None,
     progress_callback=None,
 ) -> list:
     """Select assets using embedding-based cluster-aware FPS.
@@ -191,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)
+        # 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)
-            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)
-            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.")
@@ -360,7 +380,7 @@ def _compute_adaptive_threshold(emb_normed: np.ndarray, entity_type: str) -> flo
     fraction = 0.20 if entity_type == "face" else 0.10
     threshold = max(0.05, median_dist * fraction)
 
-    logger.info(
+    logger.debug(
         f"Adaptive threshold: {threshold:.4f} "
         f"(median_dist={median_dist:.4f}, fraction={fraction}, type={entity_type})"
     )
@@ -402,7 +422,7 @@ def _cluster_aware_selection(
 
     # --- Stage 1: K-Medoids clustering ---
     k = min(max(5, target // 4), n // 3, n)  # e.g., 5-20 clusters
-    logger.info(f"Clustering {n} embeddings into {k} groups (K-Medoids)...")
+    logger.debug(f"Clustering {n} embeddings into {k} groups (K-Medoids)...")
 
     # Compute full cosine distance matrix
     dist_matrix = 1 - emb_normed @ emb_normed.T
@@ -411,7 +431,7 @@ def _cluster_aware_selection(
     selected = list(medoid_indices)
     selected_set = set(selected)
 
-    logger.info(f"Selected {len(selected)} cluster medoids as initial picks.")
+    logger.debug(f"Selected {len(selected)} cluster medoids as initial picks.")
 
     # --- Stage 2: FPS with hard example weighting ---
     min_dists = np.full(n, np.inf)
@@ -436,8 +456,8 @@ def _cluster_aware_selection(
             break  # All points selected
 
         if limit == "auto" and best_dist < auto_threshold:
-            logger.info(
-                f"Auto-stop: Next best image {best_dist:.3f} away " f"(adaptive threshold {auto_threshold:.4f})."
+            logger.debug(
+                f"Auto-stop: next best image {best_dist:.3f} away (adaptive threshold {auto_threshold:.4f})."
             )
             break
 

winnow/embeddings.py

@@ -6,11 +6,13 @@ Unified embedding interface for faces and objects.
 - Caching: Disk-based cache avoids recomputation on reruns
 """
 
-import contextlib
 import importlib
 import logging
 import os
+import time
 import warnings
+from contextlib import contextmanager
+from pathlib import Path
 
 import cv2
 import numpy as np
@@ -20,6 +22,26 @@ from .cache import get_cache
 
 logger = logging.getLogger(__name__)
 
+
+@contextmanager
+def _suppress_output():
+    """Suppress stdout/stderr at the file-descriptor level, silencing C extension noise."""
+    devnull_fd = os.open(os.devnull, os.O_WRONLY)
+    saved_out, saved_err = os.dup(1), os.dup(2)
+    try:
+        os.dup2(devnull_fd, 1)
+        os.dup2(devnull_fd, 2)
+        yield
+    finally:
+        try:
+            os.dup2(saved_out, 1)
+        finally:
+            os.dup2(saved_err, 2)
+        os.close(devnull_fd)
+        os.close(saved_out)
+        os.close(saved_err)
+
+
 # Lazy-loaded singletons
 _insightface_app = None
 _insightface_loaded = False
@@ -37,18 +59,14 @@ def _preload_cuda_libs() -> None:
     """Preload CUDA/cuDNN DLLs so onnxruntime-gpu registers CUDAExecutionProvider.
 
     Starting with onnxruntime-gpu 1.19+, CUDA/cuDNN libraries are no longer
-    bundled inside the ORT package. They must be loaded from the nvidia-*
-    pip packages (nvidia-cuda-runtime-cu12, nvidia-cudnn-cu12) before any
-    InferenceSession is created.
-
-    Calling preload_dlls() with directory="" searches NVIDIA site-packages
-    directories automatically.
+    bundled inside the ORT package — they come from the nvidia-* pip packages.
+    preload_dlls() locates them automatically via site-packages discovery.
     """
     try:
         import onnxruntime
         if hasattr(onnxruntime, "preload_dlls"):
-            onnxruntime.preload_dlls(cuda=True, cudnn=True, directory="")
-            logger.info("Preloaded CUDA/cuDNN DLLs for onnxruntime-gpu")
+            onnxruntime.preload_dlls(cuda=True, cudnn=True)
+            logger.debug("Preloaded CUDA/cuDNN DLLs for onnxruntime-gpu")
         else:
             logger.debug("onnxruntime.preload_dlls() not available (ORT < 1.21)")
     except Exception as e:
@@ -67,35 +85,69 @@ 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()):
+            logger.info("InsightFace Buffalo_L: found in model cache")
+        else:
+            logger.info("InsightFace Buffalo_L: not cached — downloading now (~300 MB)")
+
         # Get providers, excluding TensorRT to avoid noisy errors
         providers = [p for p in ort.get_available_providers() if p != "TensorrtExecutionProvider"]
-        logger.info(f"Available ONNX providers: {providers}")
+        logger.debug(f"ONNX providers available: {providers}")
 
-        # Determine device: 0 for GPU, -1 for CPU
         gpu_providers = {
             "CUDAExecutionProvider",
             "ROCmExecutionProvider",
             "MPSExecutionProvider",
             "CoreMLExecutionProvider",
+            "OpenVINOExecutionProvider",
         }
-        ctx_id = -1 if _is_force_cpu() else (0 if gpu_providers & set(providers) else -1)
+        has_gpu_provider = bool(gpu_providers & set(providers))
+        ctx_id = -1 if _is_force_cpu() else (0 if has_gpu_provider else -1)
 
-        device_str = "GPU" if ctx_id >= 0 else "CPU"
-        logger.info(f"Loading InsightFace Buffalo_L on {device_str} (ctx_id={ctx_id})...")
+        # 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}")
 
-        # Suppress C-level output during model loading
-        with open(os.devnull, "w") as devnull, contextlib.redirect_stdout(devnull), contextlib.redirect_stderr(devnull):
-            insightface_home = os.environ.get("INSIGHTFACE_HOME", os.path.expanduser("~/.insightface"))
+        if not has_gpu_provider and not _is_force_cpu():
+            logger.warning(
+                "No GPU execution provider found — running InsightFace on CPU. "
+                "Ensure the container has GPU access and the correct variant image is used "
+                "(gpu for NVIDIA, rocm for AMD, intel for Intel Arc/iGPU)."
+            )
+
+        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()
+        with _suppress_output():
             _insightface_app = FaceAnalysis(name="buffalo_l", root=insightface_home, providers=providers)
             _insightface_app.prepare(ctx_id=ctx_id, det_size=(640, 640))
 
+        logger.info(f"InsightFace Buffalo_L: ready on {device_str} ({time.time() - t0:.1f}s)")
         return _insightface_app
 
     except ImportError:
@@ -103,17 +155,23 @@ def get_insightface_app():
         return None
     except Exception as e:
         logger.error(f"Failed to load InsightFace: {e}")
-        # Retry on CPU if GPU failed
         if ctx_id == 0:
-            logger.warning("Retrying InsightFace on CPU...")
+            logger.warning("InsightFace GPU load failed — retrying on CPU...")
             try:
                 from insightface.app import FaceAnalysis
 
-                _insightface_app = FaceAnalysis(name="buffalo_l", root=insightface_home)
-                _insightface_app.prepare(ctx_id=-1, det_size=(640, 640))
+                t0 = time.time()
+                with _suppress_output():
+                    _insightface_app = FaceAnalysis(
+                        name="buffalo_l",
+                        root=insightface_home,
+                        providers=["CPUExecutionProvider"],
+                    )
+                    _insightface_app.prepare(ctx_id=-1, det_size=(640, 640))
+                logger.info(f"InsightFace Buffalo_L: ready on CPU (fallback, {time.time() - t0:.1f}s)")
                 return _insightface_app
             except Exception as ex:
-                logger.error(f"CPU fallback failed: {ex}")
+                logger.error(f"InsightFace CPU fallback failed: {ex}")
         return None
 
 
@@ -162,7 +220,18 @@ def get_siglip_model():
         from transformers import AutoImageProcessor, SiglipVisionModel
 
         model_name = "google/siglip-base-patch16-224"
-        logger.info(f"Loading SigLIP model ({model_name})...")
+
+        # Disk cache check — path derived from model_name using HuggingFace's slug convention
+        hf_home = os.environ.get("HF_HOME", os.path.join(os.path.expanduser("~"), ".cache", "huggingface"))
+        cache_slug = "models--" + model_name.replace("/", "--")
+        model_cache = Path(hf_home) / "hub" / cache_slug
+        if model_cache.exists() and any(model_cache.iterdir()):
+            logger.info(f"SigLIP {model_name}: found in model cache")
+        else:
+            logger.info(f"SigLIP {model_name}: not cached — downloading now (~380 MB)")
+
+        logger.info(f"SigLIP {model_name}: loading into memory...")
+        t0 = time.time()
 
         with warnings.catch_warnings():
             warnings.filterwarnings("ignore", category=FutureWarning)
@@ -172,19 +241,23 @@ 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()
-                logger.info("SigLIP running on CUDA GPU")
+                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")
-                logger.info("SigLIP running on Apple MPS")
+                device_name = "Apple MPS"
             else:
-                logger.info("SigLIP running on CPU")
+                device_name = "CPU"
         else:
-            logger.info("FORCE_CPU set. SigLIP running on CPU")
+            device_name = "CPU (FORCE_CPU)"
 
+        logger.info(f"SigLIP {model_name}: ready on {device_name} ({time.time() - t0:.1f}s)")
         return _siglip_model, _siglip_processor
 
     except ImportError as e:
@@ -267,30 +340,31 @@ def get_embedding(
 
     use_cache = Config.ENABLE_CACHE and asset_id is not None
     cache = get_cache(Config.CACHE_DIR) if use_cache else None
-    model_key = "immich" if entity_type == "face" else "siglip"
+    # Use a single consistent cache key per model so lookups and stores always match.
+    # "immich" was previously used as the face key on the lookup path but "insightface"
+    # on the store path — meaning the cache was never hit for locally-computed embeddings.
+    cache_key = "insightface" if entity_type == "face" else "siglip"
 
     # 1. Use Immich embedding if provided
     if immich_embedding is not None:
         if cache:
-            cache.put(asset_id, immich_embedding, model_key)
+            cache.put(asset_id, immich_embedding, cache_key)
         return immich_embedding
 
     # 2. Check disk cache
     if cache:
-        cached = cache.get(asset_id, model_key)
+        cached = cache.get(asset_id, cache_key)
         if cached is not None:
             return cached
 
     # 3. Compute locally
     if entity_type == "face":
         emb = get_face_embedding(img_pil)
-        model_key = "insightface"
     else:
         emb = get_object_embedding(img_pil)
 
-    # Cache the result
     if emb is not None and cache:
-        cache.put(asset_id, emb, model_key)
+        cache.put(asset_id, emb, cache_key)
 
     return emb
 

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 .logging import console
-from .upload_tracker import mark_rejected, mark_uploaded
+from .log_config import console
+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.
 
@@ -58,6 +138,7 @@ def _enrich_asset_with_face_data(asset: dict, person: dict) -> dict:
 
     # Inject into asset so process_face_mode can find it via asset["people"]
     asset["people"] = [{"id": person_id, "faces": [face_info]}]
+    asset["face_confidence"] = face_data.confidence
     return asset
 
 
@@ -96,8 +177,10 @@ def execute_jobs(jobs: list[dict]) -> None:
                 shutil.rmtree(person_dir)
             os.makedirs(person_dir, exist_ok=True)
 
-            # Track filename → asset_id mapping for upload dedup
+            # 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:
@@ -106,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:
@@ -132,11 +226,30 @@ 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("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)):
                                     if f.startswith(f"{count}_") and f not in asset_map:
                                         asset_map[f] = asset["id"]
+                                        score_map[f] = asset.get("face_confidence")
 
                             count += 1
                         else:
@@ -149,8 +262,10 @@ def execute_jobs(jobs: list[dict]) -> None:
                 progress.advance(job_task)
                 progress.advance(overall_task)
 
-            # Store asset_map on the job so upload_to_frigate can use it
+            # 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)
 
@@ -208,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}"),
@@ -230,6 +349,8 @@ def upload_to_frigate(jobs: list[dict]) -> None:
                 continue
 
             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:
@@ -240,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:
@@ -253,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)
+                                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:
@@ -314,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

@@ -0,0 +1,129 @@
+"""Frigate API helpers for querying face training state."""
+
+import logging
+import os
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+
+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()
+        return resp.json()
+    except Exception as 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/immich_api.py

@@ -35,10 +35,13 @@ def get_people() -> list[dict]:
             headers=get_headers(),
             timeout=10,
         )
+        if resp.status_code == 401:
+            logger.error("Immich API key is invalid or expired (401 Unauthorized). Update API_KEY.")
+            return []
         resp.raise_for_status()
         return resp.json().get("people", [])
     except (requests.RequestException, ValueError) as e:
-        logger.error(f"Failed to fetch people: {e}")
+        logger.error(f"Failed to fetch people from Immich: {e}")
         return []
 
 
@@ -49,7 +52,7 @@ def fetch_all_assets(person: dict) -> list[dict]:
     url = f"{Config.IMMICH_URL}/api/search/metadata"
     page_size = 1000
 
-    logger.info(f"Fetching assets for {name}...")
+    logger.debug(f"Fetching assets for {name}...")
 
     assets = []
     for page in range(1, MAX_PAGES + 1):
@@ -137,10 +140,11 @@ def fetch_face_data(asset_id: str, person_id: str | None = None) -> FaceData | N
             face.get("boundingBoxY2", 0),
         )
 
+        score = face.get("score")
         return FaceData(
             embedding=embedding,
             bbox=bbox,
-            confidence=face.get("score") or face.get("confidence"),
+            confidence=score if score is not None else face.get("confidence"),
             image_width=face.get("imageWidth", 0),
             image_height=face.get("imageHeight", 0),
         )
@@ -212,6 +216,6 @@ def filter_recent_assets(assets: list[dict], years: int | None = None) -> list[d
         except ValueError:
             continue
 
-    logger.info(f"Retained {len(recent)} assets (filtered {skipped} old assets).")
+    logger.debug(f"Retained {len(recent)} assets (filtered {skipped} old assets).")
     return recent
 

winnow/jobs.py

@@ -11,9 +11,10 @@ from rich.table import Table
 from .config import Config
 from .diversity import select_diverse_assets
 from .embeddings import is_embedding_available, load_embedding_model
+from .frigate_api import get_frigate_face_counts
 from .immich_api import fetch_all_assets, filter_recent_assets
-from .logging import console
-from .upload_tracker import filter_already_uploaded
+from .log_config import console
+from .upload_tracker import filter_already_uploaded, get_person_summary, update_frigate_count
 
 logger = logging.getLogger(__name__)
 
@@ -57,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]:
@@ -80,7 +84,9 @@ def _resolve_strategy(strategy: str, has_embedding: bool) -> tuple[int | str, st
     return strategy_map.get(strategy, ("auto", "smart"))
 
 
-def _perform_selection(assets: list, limit: int | str, name: str, selection_mode: str, entity_type: str) -> list:
+def _perform_selection(
+    assets: list, limit: int | str, name: str, selection_mode: str, entity_type: str, person_id: str | None = None
+) -> list:
     """Run diversity selection with progress display."""
     if selection_mode == "smart":
         model_display = "InsightFace (face embeddings)" if entity_type == "face" else "SigLIP (visual embeddings)"
@@ -103,6 +109,7 @@ def _perform_selection(assets: list, limit: int | str, name: str, selection_mode
                 name,
                 selection_mode=selection_mode,
                 entity_type=entity_type,
+                person_id=person_id,
                 progress_callback=lambda c, t: progress.update(task, completed=c, total=t),
             )
 
@@ -112,7 +119,9 @@ def _perform_selection(assets: list, limit: int | str, name: str, selection_mode
 
     rprint(f"\n[cyan]Using time-spread selection for {limit} images...[/cyan]")
     with console.status(f"[bold]Selecting {limit} images evenly distributed over time...[/bold]"):
-        selected = select_diverse_assets(assets, limit, name, selection_mode="time", entity_type=entity_type)
+        selected = select_diverse_assets(
+            assets, limit, name, selection_mode="time", entity_type=entity_type, person_id=person_id
+        )
     rprint(f"  [green]Selected {len(selected)} images using time spread.[/green]")
     return selected
 
@@ -130,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")
 
@@ -144,8 +153,11 @@ def _configure_person(person: dict, people: list[dict]) -> dict | None:
 
     rprint(f"  Found [bold]{len(all_assets)}[/bold] total, [bold]{len(recent_assets)}[/bold] in range ({years} years).")
 
-    # Filter out assets already uploaded to Frigate
-    retry_rejected = os.environ.get("RETRY_REJECTED", "false").lower() in ("true", "1", "yes")
+    # Filter out assets already uploaded to Frigate.
+    # In interactive mode, ask — use the env var only as the default so it can
+    # still be pre-set (e.g. RETRY_REJECTED=true) without forcing the answer.
+    retry_env = os.environ.get("RETRY_REJECTED", "false").lower() in ("true", "1", "yes")
+    retry_rejected = Confirm.ask("Include previously rejected images?", default=retry_env)
     before_dedup = len(recent_assets)
     new_asset_ids = set(filter_already_uploaded([a["id"] for a in recent_assets], retry_rejected=retry_rejected))
     recent_assets = [a for a in recent_assets if a["id"] in new_asset_ids]
@@ -166,7 +178,9 @@ def _configure_person(person: dict, people: list[dict]) -> dict | None:
         return None
 
     # Perform selection
-    selected_assets = _perform_selection(recent_assets, limit, name, selection_mode, entity_type)
+    selected_assets = _perform_selection(
+        recent_assets, limit, name, selection_mode, entity_type, person_id=person["id"]
+    )
 
     rprint(f"  [green]Queued {len(selected_assets)} images for {name}.[/green]")
     return {"person": person, "assets": selected_assets, "limit": len(selected_assets), "config": config}
@@ -236,6 +250,12 @@ def auto_configure(people: list[dict]) -> list[dict]:
                 f" ≥{min_face_count} assets (MIN_FACE_COUNT={min_face_count})"
             )
 
+    frigate_counts = get_frigate_face_counts()
+    # Persist each count to tracker so the last known value survives Frigate downtime
+    if frigate_counts is not None:
+        for pname, count in frigate_counts.items():
+            update_frigate_count(pname, count)
+    upload_summary = get_person_summary()
     jobs = []
     for person in valid_people:
         name = person["name"]
@@ -263,13 +283,50 @@ def auto_configure(people: list[dict]) -> list[dict]:
             rprint(f"  [dim]Skipping {name} (0 new images after dedup).[/dim]")
             continue
 
+        # 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, {})
+        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"  [cyan]{name}: at cap ({already_uploaded}/{Config.MAX_AUTO_IMAGES}),"
+                f" checking for quality improvements...[/cyan]"
+            )
+            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 (no cap when replacement-only — executor
+        # decides per-image whether to swap; any candidate could be an improvement).
+        auto_cap = None
+        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
 
-        selected_assets = _perform_selection(recent_assets, limit, name, selection_mode, entity_type)
+        selected_assets = _perform_selection(
+            recent_assets, limit, name, selection_mode, entity_type, person_id=person["id"]
+        )
+        if auto_cap is not None:
+            selected_assets = selected_assets[:auto_cap]
 
         if selected_assets:
             rprint(f"  [green]Queued {len(selected_assets)} images for {name}.[/green]")

winnow/log_config.py

@@ -26,10 +26,12 @@ def setup_logging(verbose: bool = False) -> logging.Logger:
     """Configure logging with Rich console and file output."""
     level = logging.DEBUG if verbose else logging.INFO
 
-    # Configure root logger
+    # Configure root logger; close existing handlers before replacing them
     root = logging.getLogger()
     root.setLevel(level)
-    root.handlers.clear()
+    for h in root.handlers[:]:
+        h.close()
+        root.removeHandler(h)
 
     # Rich console handler - uses shared console to avoid breaking progress bars
     root.addHandler(RichHandler(rich_tracebacks=True, markup=True, console=console))
@@ -37,7 +39,7 @@ def setup_logging(verbose: bool = False) -> logging.Logger:
     # File handler (always debug level) — log file respects OUTPUT_DIR if set
     log_dir = os.environ.get("OUTPUT_DIR", ".")
     os.makedirs(log_dir, exist_ok=True)
-    log_path = os.path.join(log_dir, "immich_export.log")
+    log_path = os.path.join(log_dir, "winnow.log")
     file_handler = logging.FileHandler(log_path)
     file_handler.setLevel(logging.DEBUG)
     file_handler.setFormatter(logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s"))

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

@@ -8,12 +8,32 @@ Both are excluded from future candidate pools. To reset:
   - All:           delete both files
   - One person:    call reset_person("Name") or set RESET_PERSON=Name
   - Rejects only:  delete frigate_rejected_ids.json, or set RETRY_REJECTED=true
+
+by_person schema (frigate_uploaded_ids.json):
+  {
+    "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"
@@ -55,7 +75,33 @@ def _load_flat(filename: str) -> set[str]:
     return set(_load(filename).get(_flat_key(filename), []))
 
 
-def _mark(filename: str, asset_id: str, person_name: str | None) -> None:
+def _get_ids(entry: list | dict) -> list[str]:
+    """Extract asset_ids from either the old list format or the new dict format."""
+    if isinstance(entry, list):
+        return entry
+    return entry.get("asset_ids", [])
+
+
+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": {}, "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,
+    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, []))
@@ -63,9 +109,17 @@ def _mark(filename: str, asset_id: str, person_name: str | None) -> None:
     data[flat_key] = sorted(flat)
     if person_name:
         by_person = data.setdefault("by_person", {})
-        person_ids = set(by_person.get(person_name, []))
-        person_ids.add(asset_id)
-        by_person[person_name] = sorted(person_ids)
+        entry = _migrate_entry(by_person.get(person_name, {}))
+        ids = set(entry["asset_ids"])
+        ids.add(asset_id)
+        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)
 
 
@@ -79,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) -> None:
-    _mark(UPLOAD_TRACKER_FILE, asset_id, person_name)
+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})")
 
 
@@ -89,33 +149,211 @@ 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)
+    by_person = data.setdefault("by_person", {})
+    entry = _migrate_entry(by_person.get(person_name, {}))
+    entry["frigate_count"] = count
+    by_person[person_name] = entry
+    _save(UPLOAD_TRACKER_FILE, data)
+
+
 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", {})
-        person_ids = set(by_person.pop(person_name, []))
-        if person_ids:
+        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[str, int]]:
-    """Return {person_name: {uploaded: N, rejected: N}} for display."""
-    uploaded_by = _load(UPLOAD_TRACKER_FILE).get("by_person", {})
-    rejected_by = _load(REJECT_TRACKER_FILE).get("by_person", {})
-    names = set(uploaded_by) | set(rejected_by)
-    return {
-        name: {
-            "uploaded": len(uploaded_by.get(name, [])),
-            "rejected": len(rejected_by.get(name, [])),
+def get_person_summary() -> dict[str, dict]:
+    """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)
+    result = {}
+    for name in sorted(names):
+        u_entry = uploaded_data.get(name, {})
+        r_entry = rejected_data.get(name, {})
+        result[name] = {
+            "uploaded": len(_get_ids(u_entry)),
+            "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 {},
         }
-        for name in sorted(names)
-    }
+    return result
 
 
 def filter_already_uploaded(