feat(people-worker): ship medoid member face id per representative (ADR 0114) #1276

Merged
chris merged 1 commit from feat/rep-thumb-worker into main 2026-10-17 01:18:01 +02:00
Owner

Additive medoidFaceAnnotationId per rep, computed in the same decomposition pass, deterministic tie-breaks, no contract bump; feeds ADR 0114 representative-thumbnail selection; API lane persists it in parallel.

Worker half of ADR 0114:

  • _decompose_person_rows computes each cluster's medoid MEMBER face (min sum of cosine distances to the other members; singleton = itself; ties -> smallest faceAnnotationId) in the same pass as the ADR 0108 centroids. Linkage path reuses the already-computed pairwise cosine distance matrix; the degraded singleton/over-cap single-centroid path picks its medoid over all usable faces via an O(n·d) similarity-sum matvec (never an n×n matrix — the split cap exists to avoid one). Clustering behavior, cluster order, centroids, cluster_size and all degradation paths are byte-identical.
  • Rep objects extend additively to (centroid, cluster_size, medoid_face_annotation_id); the personRepresentatives envelope gains medoidFaceAnnotationId (UUID string) per rep — no contract-version bump, existing fields unchanged.
  • ADR 0113 V6 cache: the wire parser requires a non-empty medoid id per persisted rep; pre-medoid rows are dropped as cache misses and recomputed once, so every shipped rep always carries its medoid. NOTE for the API lane: persist/round-trip medoidFaceAnnotationId or the fingerprint cache degrades to recompute-every-run.
  • Tests: medoid-not-first/last member, singleton, tie -> smallest faceAnnotationId, degraded over-cap medoid, UUID payload shape, legacy-row miss, round-trip parity. PYTHONPATH=src python -m pytest -q tests: 384 passed.
Additive medoidFaceAnnotationId per rep, computed in the same decomposition pass, deterministic tie-breaks, no contract bump; feeds ADR 0114 representative-thumbnail selection; API lane persists it in parallel. Worker half of ADR 0114: - `_decompose_person_rows` computes each cluster's medoid MEMBER face (min sum of cosine distances to the other members; singleton = itself; ties -> smallest faceAnnotationId) in the same pass as the ADR 0108 centroids. Linkage path reuses the already-computed pairwise cosine distance matrix; the degraded singleton/over-cap single-centroid path picks its medoid over all usable faces via an O(n·d) similarity-sum matvec (never an n×n matrix — the split cap exists to avoid one). Clustering behavior, cluster order, centroids, cluster_size and all degradation paths are byte-identical. - Rep objects extend additively to `(centroid, cluster_size, medoid_face_annotation_id)`; the `personRepresentatives` envelope gains `medoidFaceAnnotationId` (UUID string) per rep — no contract-version bump, existing fields unchanged. - ADR 0113 V6 cache: the wire parser requires a non-empty medoid id per persisted rep; pre-medoid rows are dropped as cache misses and recomputed once, so every shipped rep always carries its medoid. NOTE for the API lane: persist/round-trip `medoidFaceAnnotationId` or the fingerprint cache degrades to recompute-every-run. - Tests: medoid-not-first/last member, singleton, tie -> smallest faceAnnotationId, degraded over-cap medoid, UUID payload shape, legacy-row miss, round-trip parity. `PYTHONPATH=src python -m pytest -q tests`: 384 passed.
docs(adr): 0114 representative thumbnail = manual pin or medoid of largest cluster
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 / Build postgres image (push) Has been skipped
Build and Deploy / Build Android CI image (push) Has been skipped
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 / Smoke people worker (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 / Android unit tests and debug APK (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
5df46e40dc
feat(people-worker): ship medoid member face id per representative (ADR 0114)
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 / 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 / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build Android CI 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 / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Build media 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 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
193168d179
Compute each cluster's medoid MEMBER face (min sum of cosine distances
to the other members, ties -> smallest faceAnnotationId) in the same
_decompose_person_rows pass that builds the ADR 0108 centroids:

* linkage path reuses the already-computed pairwise cosine distance
  matrix (no extra O(n^2) work, no behavior change to clustering,
  cluster order, centroids, cluster_size or the degradation paths);
* the degraded single-centroid path (singleton / over-cap) selects its
  medoid over all usable faces with an O(n*d) similarity-sum matvec --
  never materializing the (n x n) matrix the split cap exists to avoid;
* rep objects extend additively to (centroid, cluster_size,
  medoid_face_annotation_id); the personRepresentatives envelope gains
  an additive medoidFaceAnnotationId per rep (UUID string), no
  contract-version bump, existing fields byte-identical;
* the ADR 0113 V6 cache parser requires a non-empty medoid id per
  persisted rep -- pre-ADR-0114 rows are dropped as cache misses and
  recomputed once, so every shipped rep always carries its medoid;
* consumers of the rep tuple (graph builder, medoid-pess scoring, CV
  experiment harness, prototype alias tests) updated mechanically.

Tests: new RepresentativeMedoidTest + MedoidPayloadShapeTest (middle-
member medoid, tie -> smallest id, UUID payload shape, feed-order
determinism), over-cap/threshold-2.0/singleton medoid assertions, and a
legacy-no-medoid cache-miss test. Full suite: 384 passed.
chris force-pushed feat/rep-thumb-worker from 193168d179
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 / 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 / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build Android CI 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 / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Build media 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 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
to a9f9230900
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 / 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 / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build Android CI 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 / Build API image (push) Has been skipped
Build and Deploy / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Deploy postgres (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
2026-10-17 01:16:58 +02:00
Compare
chris merged commit ac3165eb95 into main 2026-10-17 01:18:01 +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!1276
No description provided.