feat(people): surface single-face weak matches as suggestions (spec 040) #772

Merged
chris merged 1 commit from feat/single-face-suggestions into main 2026-09-19 17:47:44 +02:00
Owner

Spec 040 T001. Based on origin/main f4795e0d.

What / why

Many owner_tentative single faces never surfaced anywhere: the worker only emitted (a) strong existing-person matches (distance ≤ 0.35) and (b) DBSCAN clusters (≥ 2 faces). A single face whose best person match is in the WEAK band (0.35 < distance ≤ 0.5, similarity ≥ 50%) now surfaces in the suggestions carousel with the full Similar-card action set: merge into the suggested person, create a new person instead, or stash/disband. All auto-assign thresholds unchanged (recognition 0.35, embedding auto-match 0.3, classInstanceAutoMerge 0.3) — weak matches are SUGGESTIONS ONLY, never auto-accepted.

Changes

  • Worker (main.py): new weak-band pass after strong matching + clustering. Leftover unassigned faces with best per-model-space person distance in (maxDistance, suggestMaxDistance] emit a single-face cluster_person_match (existingInstanceId = best person, weakMatch: true, distance + confidence). Band from job settings suggestMaxDistance (default 0.5); band disabled when suggestMaxDistance ≤ maxDistance. No double-emission (clustered/strong-matched faces skipped); model-space guard mirrors _best_existing_person_match.
  • Settings plumbing: suggest_max_distance column on discovery_domains (V129, V103/V104 precedent, 0.5 seeded for people) → recognition job payload settings.suggestMaxDistance.
  • Persistence (persistWorkerCandidates): policy auto-accept guarded against weak candidates (embedding-match path already naturally closed at 0.3); shadow auto-accept (stashed target) explicitly absorbs weak candidates too (stash promise: collects future good matches quietly); pending feed ordering ranks matched candidate types by confidence DESC (= similarity DESC) with recency for the rest, portable SQL (no jsonb_extract_path — H2 compatible); rejected AND disbanded weak candidates stamp review details with rejectedWeakPair {faceAnnotationId, personRecordId} and persistWorkerCandidates suppresses identical (face, person) re-emission — the face can still be proposed for a DIFFERENT person or clustered. V123/V124/V125 superseding verified working for single-ref candidates unchanged.
  • Frontend (DomainSuggestionsCarousel): singular copy for 1-photo cards ("This photo looks like X" / "It probably belongs to X"), singular dialog heading + weak explainer variant, singular merge aria-label, muted neutral badge for weakMatch candidates (strong stays indigo). No client-side candidate sorting (API-ordered).

Test plan

  • Worker: 6 new pytest cases in test_weak_single_face_suggestions.py (band emission with exact distance/confidence/weakMatch, beyond-band silence, strong path unchanged, disabled band, no double-emission when clustered, model-space guard); full workers/people pytest: 77 passed / 8 pre-existing failures (known, unrelated)
  • API: 5 new tests (weak stays pending with auto-accept policy ON, shadow absorbs weak candidate, rejected-pair suppression + different-person still proposes, disbanded-pair suppression, similarity-DESC ordering); rtk ./gradlew :apps:api:compileJava green; full rtk ./gradlew :apps:api:test green
  • Web: npm run check 0 errors; npm run build + Playwright discovery-review + discovery-stashed-people: 66 passed (incl. 2 new weak single-face tests)
  • workers/people dispatch, KNOWN_ISSUES.md, specs/ untouched
Spec 040 T001. Based on origin/main f4795e0d. ## What / why Many owner_tentative single faces never surfaced anywhere: the worker only emitted (a) strong existing-person matches (distance ≤ 0.35) and (b) DBSCAN clusters (≥ 2 faces). A single face whose best person match is in the WEAK band (0.35 < distance ≤ 0.5, similarity ≥ 50%) now surfaces in the suggestions carousel with the full Similar-card action set: merge into the suggested person, create a new person instead, or stash/disband. **All auto-assign thresholds unchanged** (recognition 0.35, embedding auto-match 0.3, classInstanceAutoMerge 0.3) — weak matches are SUGGESTIONS ONLY, never auto-accepted. ## Changes - **Worker** (`main.py`): new weak-band pass after strong matching + clustering. Leftover unassigned faces with best per-model-space person distance in `(maxDistance, suggestMaxDistance]` emit a single-face `cluster_person_match` (existingInstanceId = best person, weakMatch: true, distance + confidence). Band from job settings `suggestMaxDistance` (default 0.5); band disabled when suggestMaxDistance ≤ maxDistance. No double-emission (clustered/strong-matched faces skipped); model-space guard mirrors `_best_existing_person_match`. - **Settings plumbing**: `suggest_max_distance` column on discovery_domains (V129, V103/V104 precedent, 0.5 seeded for people) → recognition job payload `settings.suggestMaxDistance`. - **Persistence** (`persistWorkerCandidates`): policy auto-accept guarded against weak candidates (embedding-match path already naturally closed at 0.3); shadow auto-accept (stashed target) explicitly absorbs weak candidates too (stash promise: collects future good matches quietly); pending feed ordering ranks matched candidate types by confidence DESC (= similarity DESC) with recency for the rest, portable SQL (no jsonb_extract_path — H2 compatible); rejected AND disbanded weak candidates stamp review details with `rejectedWeakPair` {faceAnnotationId, personRecordId} and persistWorkerCandidates suppresses identical (face, person) re-emission — the face can still be proposed for a DIFFERENT person or clustered. V123/V124/V125 superseding verified working for single-ref candidates unchanged. - **Frontend** (`DomainSuggestionsCarousel`): singular copy for 1-photo cards ("This photo looks like X" / "It probably belongs to X"), singular dialog heading + weak explainer variant, singular merge aria-label, muted neutral badge for weakMatch candidates (strong stays indigo). No client-side candidate sorting (API-ordered). ## Test plan - [x] Worker: 6 new pytest cases in `test_weak_single_face_suggestions.py` (band emission with exact distance/confidence/weakMatch, beyond-band silence, strong path unchanged, disabled band, no double-emission when clustered, model-space guard); full workers/people pytest: 77 passed / 8 pre-existing failures (known, unrelated) - [x] API: 5 new tests (weak stays pending with auto-accept policy ON, shadow absorbs weak candidate, rejected-pair suppression + different-person still proposes, disbanded-pair suppression, similarity-DESC ordering); `rtk ./gradlew :apps:api:compileJava` green; full `rtk ./gradlew :apps:api:test` green - [x] Web: `npm run check` 0 errors; `npm run build` + Playwright `discovery-review` + `discovery-stashed-people`: 66 passed (incl. 2 new weak single-face tests) - [x] workers/people dispatch, KNOWN_ISSUES.md, specs/ untouched
feat(people): surface single-face weak matches as suggestions (spec 040)
All checks were successful
Build and Deploy / Detect changed services and test scopes (push) Successful in 3s
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 / 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 media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build API 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
Build and Deploy / Run scoped PR tests (push) Successful in 1m5s
1d8bab8baf
Many owner_tentative single faces never surfaced: the worker only emitted
(a) strong existing-person matches (distance <= 0.35) and (b) DBSCAN
clusters (>= 2 faces). A single face whose best person match is WEAK
(0.35 < distance <= 0.5, similarity >= 50%) is now suggested explicitly.

Worker (main.py): after the strong-match pass and DBSCAN clustering, every
leftover unassigned face is checked once more against the same
per-model-space person anchors (single face = its own embedding, no
centroid). A best distance in (maxDistance, suggestMaxDistance] emits ONE
single-face cluster_person_match candidate — existingInstanceId of the
best-matching person, full Similar-card action set (merge / new-person-
instead / stash / disband), payload carrying distance + confidence +
weakMatch: true. suggestMaxDistance comes from job settings (default 0.5);
suggestMaxDistance <= maxDistance disables the band. No double-emission:
faces already clustered/strong-matched are skipped; model-space guard
mirrors _best_existing_person_match. EXPLICIT: all auto-assign thresholds
unchanged — weak matches are suggestions only.

API settings (WorkerJobEnqueueService): recognition job payload settings
gain suggestMaxDistance, read from discovery_domains.suggest_max_distance
(V129, V103/V104 precedent, default 0.5 seeded for people).

API persistence (ClassInstanceDiscoveryService):
- Default pending listing now ranks matched candidate types
  (cluster_person_match / existing_person_match) first by confidence DESC
  (= similarity DESC; confidence = 1 - distance), recency for the rest —
  portable plain columns (H2 has no jsonb_extract_path). The carousel's
  sort=confidence ordering already grouped cluster matches first.
- Policy auto-accept guard: weak candidates (weakMatch=true) are never
  policy-auto-accepted; the embedding-match path is naturally closed
  (distance gate 0.3 << weak band lower bound 0.35). Shadow auto-accept
  (stashed target) explicitly absorbs weak candidates too — the stash
  product promise: collects future good matches quietly.
- Re-emission spam (d)/(e): rejected AND disbanded weak single-face
  candidates stamp review-decision details with rejectedWeakPair =
  {faceAnnotationId, personRecordId}; persistWorkerCandidates skips
  re-inserting a weak candidate for the same (face, person) pair (logged).
  The face can still be proposed for a DIFFERENT person or clustered.
  Disbanded weak candidates write the same keys, so one check covers
  both outcomes.
- Superseding (V123/V124/V125) keys on occurrence refs — verified working
  for single-ref weak candidates without changes.

Frontend (DomainSuggestionsCarousel): singular copy for 1-photo cards
('This photo looks like X' / 'It probably belongs to X...'), singular
dialog heading + weak explainer variant, singular merge aria-label,
muted neutral badge for weakMatch candidates (was indigo), full action
set already present via cluster_person_match rendering.

Tests: 6 worker pytest cases (band emission, beyond-band silence, strong
path unchanged, disabled band, no double-emission when clustered,
model-space guard); 5 API tests (weak candidate stays pending with
policy on, shadow absorbs weak candidate, rejected-pair suppression +
different-person still proposes, disbanded pair suppression, similarity
ordering); 2 Playwright tests (weak card: singular text, 1-photo chip,
muted badge, merge posts accepted+existingInstanceId; dialog: weak
explainer, new-person + stash/disband intact).
chris merged commit 6dae8e71c9 into main 2026-09-19 17:47:44 +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!772
No description provided.