feat(people): surface single-face weak matches as suggestions (spec 040) #772
Loading…
Reference in a new issue
No description provided.
Delete branch "feat/single-face-suggestions"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
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
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-facecluster_person_match(existingInstanceId = best person, weakMatch: true, distance + confidence). Band from job settingssuggestMaxDistance(default 0.5); band disabled when suggestMaxDistance ≤ maxDistance. No double-emission (clustered/strong-matched faces skipped); model-space guard mirrors_best_existing_person_match.suggest_max_distancecolumn on discovery_domains (V129, V103/V104 precedent, 0.5 seeded for people) → recognition job payloadsettings.suggestMaxDistance.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 withrejectedWeakPair{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.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
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)rtk ./gradlew :apps:api:compileJavagreen; fullrtk ./gradlew :apps:api:testgreennpm run check0 errors;npm run build+ Playwrightdiscovery-review+discovery-stashed-people: 66 passed (incl. 2 new weak single-face tests)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).