fix(workers-people): weak single-face suggestions require kNN consensus (≥2 faces ≤ 0.5) #822

Merged
chris merged 2 commits from fix/quality-consensus-worker into main 2026-09-22 22:21:39 +02:00
Owner

Problem

The weak single-face pass emitted suggestions on min-pairwise distance alone — an extreme-value statistic: with 387 assigned faces, one odd/blurry face of the person matches almost anything (production: adults suggested for a child at 43-58% similarity; one person had 173 pending weak suggestions).

Change

New _weak_consensus_match gating: a weak suggestion requires ≥2 assigned faces of the target person within min(0.5, suggest_max_distance) of the candidate face; confidence = 1 − mean of the k best supporting distances (k = min(3, support)) instead of the inflated 1 − bestDistance. Strong path (≤0.35), cluster-centroid path, and the emitted payload contract are unchanged (verified against isWeakSingleFaceCandidate / auto-accept guard). All distances in one vectorized NumPy pass (ISSUE-035 style). Matches Immich's minFaces core-point philosophy; the new confidence is always ≥ 0.5 so it aligns with the V135 sub-floor sweep in the companion API PR.

Tests

19 weak-match tests (consensus gating, per-person support counting, band-edge narrowing, handler-level payload contract, William-style extreme-value regression, vectorized-vs-naive parity); golden clustering + cluster-match suites green (55/55 targeted, 59 combined). Pre-existing test_face_model.py failures (8, baseline-verified on pristine main) documented as ISSUE-064; missing people-worker CI test job documented as ISSUE-063.

Companion PR: V135 threshold floor 0.5 + sub-floor sweep + recognition re-arm debounce.

## Problem The weak single-face pass emitted suggestions on min-pairwise distance alone — an extreme-value statistic: with 387 assigned faces, one odd/blurry face of the person matches almost anything (production: adults suggested for a child at 43-58% similarity; one person had 173 pending weak suggestions). ## Change New `_weak_consensus_match` gating: a weak suggestion requires **≥2 assigned faces of the target person within min(0.5, suggest_max_distance)** of the candidate face; confidence = 1 − mean of the k best supporting distances (k = min(3, support)) instead of the inflated 1 − bestDistance. Strong path (≤0.35), cluster-centroid path, and the emitted payload contract are unchanged (verified against `isWeakSingleFaceCandidate` / auto-accept guard). All distances in one vectorized NumPy pass (ISSUE-035 style). Matches Immich's minFaces core-point philosophy; the new confidence is always ≥ 0.5 so it aligns with the V135 sub-floor sweep in the companion API PR. ## Tests 19 weak-match tests (consensus gating, per-person support counting, band-edge narrowing, handler-level payload contract, William-style extreme-value regression, vectorized-vs-naive parity); golden clustering + cluster-match suites green (55/55 targeted, 59 combined). Pre-existing `test_face_model.py` failures (8, baseline-verified on pristine main) documented as ISSUE-064; missing people-worker CI test job documented as ISSUE-063. Companion PR: V135 threshold floor 0.5 + sub-floor sweep + recognition re-arm debounce.
docs: record people-worker CI test gap (ISSUE-063) and pre-existing face_model test failures (ISSUE-064)
All checks were successful
Build and Deploy / Detect changed services and test scopes (push) Successful in 3s
Build and Deploy / Run scoped PR tests (push) Has been skipped
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
7d0bc91ab2
chris merged commit 6e55de6d03 into main 2026-09-22 22:21:39 +02:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
chris/memories!822
No description provided.