tedornitier/immich-pet-tagger v1.7.0

on GitHub

Features

• Review tag: setting TAG_NAME makes the tagger apply that Immich tag to a photo every time it writes a face to it, giving you a single place in Immich to review everything it touched. The tag is created on first use, and applied inline with each face rather than batched, so a photo appears under the tag as soon as it is tagged. The tag is also removed again if a pet's face is removed from a photo, whether by removing a single ref or deleting the pet entirely, as long as no other pet's face remains on it, so the review queue doesn't accumulate photos the tool no longer has anything to say about. Only applies going forward: enabling it does not retroactively tag photos faced before it was turned on. Requires tag.create and tag.asset on the API key.
• Tagging accuracy (📊 icon in the sidebar, or /accuracy.html): dry-run classifies every photo and video in a date range and compares against your actual Immich tags, so you can measure real recall and false-positive rates instead of guessing. Breaks results down by pet, photo/video, and whether YOLO found a detection or fell back to the whole image, with a summary table plus thumbnail grids of only the mismatches. A threshold explorer sweeps every CLIP threshold from 0.30 to 0.99 using the scores already collected by the run (no re-scan) and plots recall vs. false-positive rate per bucket, click a chart to set that bucket's threshold. YOLO detection confidence can be overridden per run to test a different cutoff (thumbnails and raw detections are cached per asset, so re-running with a new value is fast); CLIP thresholds are picked entirely client-side and never trigger a re-run. Nothing is saved to live settings, only that one run. Results can be downloaded and re-imported later to skip re-running. Not part of the tagging pipeline, a diagnostic tool for tuning thresholds. Production THRESHOLD/YOLO_CONF are still configured via docker-compose.yml only.
• Low-confidence review filtered by predicted pet: with several pets enrolled, low-confidence results used to show as one mixed grid. Filter chips now group them by which pet the classifier guessed, so reassigning is faster (addresses #42).

Changed

• docker-compose.yml now ships YOLO_CONF=0.2 explicitly (was previously unset, falling back to the code default of 0.25). Measured to catch more real detections without a meaningful false-positive cost using the tagging accuracy tool.
• README documents a "Bigger models" opt-in upgrade (YOLO_MODEL_NAME=yolov8s.pt, CLIP_MODEL_NAME=ViT-L-14, CLIP_PRETRAINED=openai) for users with GPU headroom, measured ~40% fewer missed tags and ~13% fewer false positives than the defaults on a real library (96% tagging accuracy at a 1.4% false-positive rate in my own testing). Not the shipped default, since it needs more RAM/VRAM and a larger model download.

Fixed

• Low-confidence review could suggest a pet for a photo outside that pet's configured date range (e.g. a guess for a pet who wasn't even adopted yet). The date-range check now runs before the confidence check, so an out-of-range guess is dropped outright instead of surfacing in the review queue.