feat(api): multi-representant assignment metric for person ranking (ADR 0109) #1083

Merged
chris merged 3 commits from feat/api-multi-representant-ranking into main 2026-10-10 07:51:45 +02:00
Owner

Problem

ADR 0108 switched the people worker (semisupervised-v2) to multi-representant person representation — per-person average-linkage split at representative_split_distance=0.50, unit-mean centroid per subcluster, per-representative pessimistic target choice. The three API read sites (personRanking, mergeTargetRankings, mergeSuggestion in ClassInstanceDiscoveryService) kept computing the pre-0108 single live centroid. On multi-modal persons that centroid decays away from every real visual mode.

Proven production bug (2026-10): a candidate whose faces sit 0.228 cosine from target "Rikke"'s winning mode ranked "Jutta" first at 0.362, with Rikke outside the top 6 — Rikke holds 435 accepted faces across 47 subclusters and her collapsed centroid resembles no real appearance. The UI title ranking lied against the very cards the worker mints from the same faces.

Solution: persist, don't recompute

No Java port of the linkage (permanent parity risk, O(n²) per request). The worker already computes the representatives per run — it now ships them on the result envelope and the API persists them:

  • Worker (main.py): additive top-level envelope field personRepresentatives ([{modelName, modelVersion, personId, reps: [{repIndex, clusterSize, embedding}]}], deterministic order, full precision). Per-candidate envelope contract untouched: distance stays raw, confidence == clamp(1 - round(distance, 6)), contract version unchanged. v1/legacy methods never attach it.
  • Envelope validation (WorkerResultService): fail-closed before any write — canonical person UUIDs, finite equal-length embeddings, clusterSize >= 1, unique (pair, person, repIndex); absent-legal for older workers.
  • V156 person_instance_representatives: JSONB embedding (source of truth) + V136-style trigger-maintained embedding_vec pgvector mirror; unique (owner, domain, class, model pair, person, rep_index); FK fail-closed to class_instances. Deliberately no speculative HNSW index (the unused V101 GIN placeholder, dropped in V136, is the precedent).
  • Ingestion (persistSemisupervisedCandidates): FULL-REPLACE per (owner_id, domain_key, class_key) inside the same transaction as candidate ingestion. Empty array = real replacement; absent field (older worker/v1) leaves prior rows untouched. Applied even for empty candidate lists (an empty run still declares the current representation). State/409-stale guards untouched.
  • Read path: one shared composer implements the exact worker choice rule — per representative d_pess = d + Z·σ·√(1/n_source + 1/cluster_size) with the representative's OWN cluster size as n_target (ADR 0106), person key = first-minimal over its representatives in rep_index order (worker convention), reported raw distance = the pessimistically chosen representative's raw distance. No "min over all reps" shortcut, no blending with the single-centroid value. Merge surfaces (unordered pairs) take the pessimistic min over the rep-ified directions; personRanking is exact worker parity (its candidate side is a pending card, never an instance). candidatesPaged, countCandidates, ADR 0107 named-target filters: untouched.

Design decisions

  • Fallback: person without persisted reps in the queried model pair (fresh instance, over-cap >2000-face person — the worker itself degrades them to a single centroid, owner before the first v2 run) → byte-identical pre-0108 live single-centroid metric.
  • Staleness: representatives are minutes-stale until the next completed worker run — by design, the same freshness the candidate cards themselves carry. Documented in ADR 0109 + [ISSUE-109]. A clustering reset converges on the next run's full replace.
  • Gate: merge-suggestion 0.35 gate formula unchanged but now reads rep distances, which shrink systematically (ADR 0108) — the operator's known post-0108 recalibration lever (~0.45 band) applies here too.
  • Non-goal: suggestSimilarInstances (operator dialog) keeps the live single-centroid metric.

Tests

  • Golden parity (personRankingGoldenVectorsFromWorkerReference): pins the Java ranking to vectors produced by the production Python path — clustering._person_representatives + _pessimistic_target_distance via workers/people/experiments/api_ranking_golden.py (committed, regenerable, verified reproducible). Chosen representative's raw distance, pessimistic score and full ranking order asserted per candidate/person.
  • Hand-traceable tests: rep metric replaces the collapsed-centroid metric (the Rikke/Jutta inversion shape), fallback for persons without reps / foreign-model rep sets, merge-target rep + fallback, merge-suggestion gate proves no mixing (rep distance replaces single-centroid outright).
  • Ingestion: store → full-replace → absent-field-preserved.
  • Envelope validation: 8 negative/positive cases.
  • V156 migration content assertions (table shape, unique key, checks, FKs, pgvector-mirror parity with V136).
  • Worker payload tests: v2 attaches the exact _person_representatives output deterministically (feed-order shuffled), singleton rep size 1, v1/legacy never attach, envelope contract invariant holds under multi-rep scoring.

Results: rtk ./gradlew :apps:api:test — all green (full suite, 4 min). pytest in workers/people (PYTHONPATH=src, CI convention) — 316 passed. Version 1.21.74.

ADR: docs/adr/0109-api-read-path-multi-representant-ranking.json (replaces 0103's single-centroid ranking-metric statement for the three sites; references 0106/0107/0108).

## Problem ADR 0108 switched the people worker (semisupervised-v2) to multi-representant person representation — per-person average-linkage split at representative_split_distance=0.50, unit-mean centroid per subcluster, per-representative pessimistic target choice. The three API read sites (`personRanking`, `mergeTargetRankings`, `mergeSuggestion` in `ClassInstanceDiscoveryService`) kept computing the **pre-0108 single live centroid**. On multi-modal persons that centroid decays away from every real visual mode. **Proven production bug (2026-10):** a candidate whose faces sit 0.228 cosine from target "Rikke"'s winning mode ranked "Jutta" first at 0.362, with Rikke **outside the top 6** — Rikke holds 435 accepted faces across 47 subclusters and her collapsed centroid resembles no real appearance. The UI title ranking lied against the very cards the worker mints from the same faces. ## Solution: persist, don't recompute No Java port of the linkage (permanent parity risk, O(n²) per request). The worker already computes the representatives per run — it now **ships them on the result envelope** and the API **persists** them: - **Worker** (`main.py`): additive top-level envelope field `personRepresentatives` (`[{modelName, modelVersion, personId, reps: [{repIndex, clusterSize, embedding}]}]`, deterministic order, full precision). Per-candidate envelope contract **untouched**: `distance` stays raw, `confidence == clamp(1 - round(distance, 6))`, contract version unchanged. v1/legacy methods never attach it. - **Envelope validation** (`WorkerResultService`): fail-closed before any write — canonical person UUIDs, finite equal-length embeddings, `clusterSize >= 1`, unique `(pair, person, repIndex)`; absent-legal for older workers. - **V156** `person_instance_representatives`: JSONB `embedding` (source of truth) + V136-style trigger-maintained `embedding_vec` pgvector mirror; unique `(owner, domain, class, model pair, person, rep_index)`; FK fail-closed to `class_instances`. Deliberately **no speculative HNSW index** (the unused V101 GIN placeholder, dropped in V136, is the precedent). - **Ingestion** (`persistSemisupervisedCandidates`): FULL-REPLACE per `(owner_id, domain_key, class_key)` **inside the same transaction** as candidate ingestion. Empty array = real replacement; absent field (older worker/v1) leaves prior rows untouched. Applied even for empty candidate lists (an empty run still declares the current representation). State/409-stale guards untouched. - **Read path**: one shared composer implements the **exact worker choice rule** — per representative `d_pess = d + Z·σ·√(1/n_source + 1/cluster_size)` with the representative's OWN cluster size as `n_target` (ADR 0106), person key = first-minimal over its representatives in rep_index order (worker convention), reported raw distance = the **pessimistically chosen** representative's raw distance. No "min over all reps" shortcut, no blending with the single-centroid value. Merge surfaces (unordered pairs) take the pessimistic min over the rep-ified directions; `personRanking` is exact worker parity (its candidate side is a pending card, never an instance). `candidatesPaged`, `countCandidates`, ADR 0107 named-target filters: untouched. ### Design decisions - **Fallback**: person without persisted reps in the queried model pair (fresh instance, over-cap >2000-face person — the worker itself degrades them to a single centroid, owner before the first v2 run) → byte-identical pre-0108 live single-centroid metric. - **Staleness**: representatives are minutes-stale until the next completed worker run — by design, the same freshness the candidate cards themselves carry. Documented in ADR 0109 + [ISSUE-109]. A clustering reset converges on the next run's full replace. - **Gate**: merge-suggestion 0.35 gate formula unchanged but now reads rep distances, which shrink systematically (ADR 0108) — the operator's known post-0108 recalibration lever (~0.45 band) applies here too. - **Non-goal**: `suggestSimilarInstances` (operator dialog) keeps the live single-centroid metric. ## Tests - **Golden parity** (`personRankingGoldenVectorsFromWorkerReference`): pins the Java ranking to vectors produced by the production Python path — `clustering._person_representatives` + `_pessimistic_target_distance` via `workers/people/experiments/api_ranking_golden.py` (committed, regenerable, verified reproducible). Chosen representative's raw distance, pessimistic score and full ranking order asserted per candidate/person. - Hand-traceable tests: rep metric replaces the collapsed-centroid metric (the Rikke/Jutta inversion shape), fallback for persons without reps / foreign-model rep sets, merge-target rep + fallback, merge-suggestion gate proves **no mixing** (rep distance replaces single-centroid outright). - Ingestion: store → full-replace → absent-field-preserved. - Envelope validation: 8 negative/positive cases. - V156 migration content assertions (table shape, unique key, checks, FKs, pgvector-mirror parity with V136). - Worker payload tests: v2 attaches the exact `_person_representatives` output deterministically (feed-order shuffled), singleton rep size 1, v1/legacy never attach, envelope contract invariant holds under multi-rep scoring. **Results:** `rtk ./gradlew :apps:api:test` — all green (full suite, 4 min). `pytest` in `workers/people` (PYTHONPATH=src, CI convention) — **316 passed**. Version 1.21.74. ADR: `docs/adr/0109-api-read-path-multi-representant-ranking.json` (replaces 0103's single-centroid ranking-metric statement for the three sites; references 0106/0107/0108).
The people worker scores identities since ADR 0108 with multi-
representants (per-person average-linkage split, unit-mean centroids,
per-representative pessimistic choice), but personRanking /
mergeTargetRankings / mergeSuggestion still computed the pre-0108 single
live centroid. On multi-modal persons that centroid decays — proven
2026-10: a candidate 0.228 from target 'Rikke''s winning mode ranked
'Jutta' first at 0.362, Rikke outside the top 6 (435-face person, 47
subclusters). The UI title ranking lied against the worker's own cards.

PERSIST, don't recompute (no Java linkage port — parity risk, per-request
cost):

- Worker attaches the run's representatives as an ADDITIVE envelope field
  personRepresentatives (deterministic pair/person/repIndex order, full
  precision, cluster_size bookkeeping); per-candidate contract untouched
  (distance raw, confidence == clamp(1 - round(distance,6))).
- WorkerResultService validates the field fail-closed before any write
  (canonical person UUIDs, finite equal-length embeddings, unique
  rep keys); absent-legal for older workers / v1 / legacy.
- V156 person_instance_representatives: JSONB embedding (source of
  truth) + V136-style trigger-maintained embedding_vec pgvector mirror,
  unique (owner, domain, class, model pair, person, rep_index), FK
  fail-closed; deliberately no speculative HNSW index yet.
- persistSemisupervisedCandidates FULL-REPLACES the set per
  (owner, domain, class) inside the same transaction as candidate
  ingestion; absent field keeps prior rows.
- Read sites share one composer implementing the exact worker choice
  rule (d_pess = d + Z*sigma*sqrt(1/n_source + 1/cluster_size) per
  representative, first-minimal wins, raw distance of the CHOSEN rep;
  no min-over-reps shortcut, no blending). Merge surfaces take the
  pessimistic min over rep-ified directions. Persons without a
  persisted set (fresh, over-cap, pre-first-run) fall back to the
  pre-0108 live single-centroid metric. candidatesPaged /
  countCandidates / named-target filters untouched.

Tests: golden parity test against vectors produced by the production
Python path (workers/people/experiments/api_ranking_golden.py),
hand-traceable ranking/fallback tests, ingestion full-replace test,
envelope validation tests, V156 content assertions, worker payload
tests (v2 attaches, v1/legacy never do). Version 1.21.74.
docs(known-issues): ISSUE-109 — ADR 0109 representatives are minutes-stale until the next worker run
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 3s
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 1m54s
390a79dea7
Merge main (PR #1082) into api-multi-rep-ranking; renumber lane-2 issue to ISSUE-110
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 1m50s
61c65166ce
chris merged commit fbb1a343d8 into main 2026-10-10 07:51:45 +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!1083
No description provided.