feat(people-worker): confidence-aware target scoring for cluster_person_match #1071

Merged
chris merged 1 commit from feat/worker-confidence-target-uncertainty into main 2026-10-08 06:21:24 +02:00
Owner

Problem

cluster_person_match cards picked their suggested target by raw centroid distance d. That is a winner's-curse estimator: the target is the minimum over candidate identities, so noise pushing one competitor down is selected for — the winning raw distance systematically underestimates the true assignment distance, worst for small persons (both centroids are means over n faces; standard error σ·√(1/n_source + 1/n_target)). Leave-one-out on the owner library (Okt 2026) measured per-face scatter σ = 0.139; all 4 rejected assignments in that LOO run had min n ≤ 6 and were raw-distance wins whose pessimistic distance would have lost. confidence = clamp(1 - distance) inherits the overstatement.

Formel

d_pess  = d + Z · σ · √(1/n_source + 1/n_target)
score   = clamp(1 - round(d_pess, 6), 0, 1)
targetUncertainty = round(Z · σ · √(1/n_source + 1/n_target), 6)

Constants at the quality-score constants site: TARGET_DISTANCE_SIGMA = 0.14 (LOO σ = 0.139, Okt 2026, rounded up; same scale as API ASSIGNMENT_DISTANCE_SIGMA, PR #1070), TARGET_DISTANCE_Z = 1.645 (one-sided 95 %, same level as the API lcbScore).

Changed emission sites (exactly 3):

  1. clustering.py constrained identities loop (n_source = len(movable_vectors))
  2. _emit_group_candidates B outcome, semisupervised v1 + v2 (n_source = len(unlabeled_offsets))
  3. main.py weak single-face pass (n_source = 1, n_target = person's feed size)

Parity harness experiments/linkage_comparison/grouping.py mirrored in lockstep (harness == production tests stay green).

Felder

field semantics
distance unchanged — raw centroid distance
confidence unchanged — clamp(1 - distance) (Core contract)
score new, additive — clamp(1 - round(d_pess, 6)), always ≤ confidence, equal only as n → ∞
targetUncertainty new, additive — the penalty term itself

Unknown person sizes default to n = 1 (conservative; ordering-neutral when shared by all competitors). Envelope: optional fields, no contract version bump (ADR 0103 qualityScore precedent).

Nicht-Änderungen

  • No gate changes: no acceptance threshold, no auto-accept band, no grouping change — d_pess only ranks which target a card suggests, never whether it is emitted.
  • qualityScore / isolation / ambiguity unchanged: the scored shortlist stays RAW-sorted; these features describe the shortlist, not the target race (product decision, documented in ADR 0106).
  • No API DTO change beyond envelope permeability (unknown candidate keys already ignored; two Java tests pin score + targetUncertainty accepted / absent).
  • Out of scope, deliberately untouched: anchored-hybrid target picks (incl. margin-gated Phase A), constrained 0-anchor _cluster_centroid_distance branch, legacy DBSCAN fallback.
  • KNOWN_ISSUES.md: no entry (nothing broken).

Testbefund

  • cd workers/people && PYTHONPATH=src python3 -m pytest -q tests → 263 passed in 10.70s (249 baseline + 14 new in tests/test_target_uncertainty_scoring.py).
  • rtk ./gradlew :apps:api:test --tests '*WorkerResultSemisupervisedEnvelopeTest*' → BUILD SUCCESSFUL, 44 tests, failures=0 errors=0.
  • Existing-test adjustments (2, both intentional):
    • test_weak_single_face_suggestions.py field-set pin extended with score/targetUncertainty + value asserts.
    • test_linkage_comparison.py oracle fixture _ORACLE_ANGLES[1] 1.9696069505 → 1.85 — original Q won only raw; with N=1 the penalty (0.0554) exceeds the raw gap (0.036) and would erase the fixture's anchor-target-disagreement purpose. Same graph adjacency, same grouping; comment in fixture documents it.

ADR: docs/adr/0106-confidence-aware-target-scoring.json (0105 taken).

## Problem `cluster_person_match` cards picked their suggested target by raw centroid distance `d`. That is a winner's-curse estimator: the target is the **minimum** over candidate identities, so noise pushing one competitor down is selected for — the winning raw distance systematically underestimates the true assignment distance, worst for small persons (both centroids are means over n faces; standard error `σ·√(1/n_source + 1/n_target)`). Leave-one-out on the owner library (Okt 2026) measured per-face scatter **σ = 0.139**; all **4 rejected assignments in that LOO run had min n ≤ 6** and were raw-distance wins whose pessimistic distance would have lost. `confidence = clamp(1 - distance)` inherits the overstatement. ## Formel ``` d_pess = d + Z · σ · √(1/n_source + 1/n_target) score = clamp(1 - round(d_pess, 6), 0, 1) targetUncertainty = round(Z · σ · √(1/n_source + 1/n_target), 6) ``` Constants at the quality-score constants site: `TARGET_DISTANCE_SIGMA = 0.14` (LOO σ = 0.139, Okt 2026, rounded up; same scale as API `ASSIGNMENT_DISTANCE_SIGMA`, PR #1070), `TARGET_DISTANCE_Z = 1.645` (one-sided 95 %, same level as the API `lcbScore`). Changed emission sites (exactly 3): 1. `clustering.py` constrained identities loop (`n_source = len(movable_vectors)`) 2. `_emit_group_candidates` B outcome, semisupervised **v1 + v2** (`n_source = len(unlabeled_offsets)`) 3. `main.py` weak single-face pass (`n_source = 1`, `n_target` = person's feed size) Parity harness `experiments/linkage_comparison/grouping.py` mirrored in lockstep (`harness == production` tests stay green). ## Felder | field | semantics | |---|---| | `distance` | **unchanged** — raw centroid distance | | `confidence` | **unchanged** — `clamp(1 - distance)` (Core contract) | | `score` | new, additive — `clamp(1 - round(d_pess, 6))`, always ≤ confidence, equal only as n → ∞ | | `targetUncertainty` | new, additive — the penalty term itself | Unknown person sizes default to `n = 1` (conservative; ordering-neutral when shared by all competitors). Envelope: optional fields, no contract version bump (ADR 0103 `qualityScore` precedent). ## Nicht-Änderungen - **No gate changes**: no acceptance threshold, no auto-accept band, no grouping change — `d_pess` only ranks which target a card suggests, never whether it is emitted. - **`qualityScore` / isolation / ambiguity unchanged**: the scored shortlist stays RAW-sorted; these features describe the shortlist, not the target race (product decision, documented in ADR 0106). - No API DTO change beyond envelope permeability (unknown candidate keys already ignored; two Java tests pin `score` + `targetUncertainty` accepted / absent). - Out of scope, deliberately untouched: anchored-hybrid target picks (incl. margin-gated Phase A), constrained 0-anchor `_cluster_centroid_distance` branch, legacy DBSCAN fallback. - KNOWN_ISSUES.md: no entry (nothing broken). ## Testbefund - `cd workers/people && PYTHONPATH=src python3 -m pytest -q tests` → **263 passed in 10.70s** (249 baseline + 14 new in `tests/test_target_uncertainty_scoring.py`). - `rtk ./gradlew :apps:api:test --tests '*WorkerResultSemisupervisedEnvelopeTest*'` → **BUILD SUCCESSFUL**, 44 tests, failures=0 errors=0. - Existing-test adjustments (2, both intentional): - `test_weak_single_face_suggestions.py` field-set pin extended with `score`/`targetUncertainty` + value asserts. - `test_linkage_comparison.py` oracle fixture `_ORACLE_ANGLES[1]` `1.9696069505 → 1.85` — original Q won only raw; with N=1 the penalty (0.0554) exceeds the raw gap (0.036) and would erase the fixture's anchor-target-disagreement purpose. Same graph adjacency, same grouping; comment in fixture documents it. ADR: `docs/adr/0106-confidence-aware-target-scoring.json` (0105 taken).
feat(people-worker): confidence-aware target scoring for cluster_person_match
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 2s
Build and Deploy / Android unit tests and debug APK (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 / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (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 people 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
Build and Deploy / Run scoped PR tests (push) Successful in 4m58s
795a196624
ADR 0106: pick the target person by pessimistic distance
d_pess = d + Z*sigma*sqrt(1/n_source + 1/n_target) (TARGET_DISTANCE_SIGMA=0.14,
LOO sigma=0.139 Oct 2026 rounded up; TARGET_DISTANCE_Z=1.645) at the three
cluster_person_match emission sites: constrained identities loop,
semisupervised v1/v2 group B outcome, weak single-face pass (n_source=1).

distance stays RAW, confidence keeps clamp(1-distance); two additive optional
fields carry the correction: score = clamp(1 - round(d_pess,6)) and
targetUncertainty = round(Z*sigma*sqrt(...),6). No gate, grouping,
auto-accept or qualityScore changes; isolation/ambiguity stay on the raw
shortlist. Parity harness mirrored; envelope tests pin field permeability.
chris merged commit 3ab67ece42 into main 2026-10-08 06:21:24 +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!1071
No description provided.