feat(api): person embedding cluster map endpoint (PCA diagnostic view, spec 042) #816

Merged
chris merged 2 commits from feat/embedding-map-api into main 2026-09-22 20:39:24 +02:00
Owner

Summary

  • New read-only diagnostic endpoint GET /api/discovery/domains/{domainKey}/class-instances/{instanceId}/embedding-map returning a deterministic 2D PCA projection of a person's face-embedding cluster: confirmed faces, tentative candidate faces (with suggesting candidateId), and the 5 nearest neighbor persons ranked by min pairwise cosine distance.
  • New EmbeddingMapService (ClassInstanceDiscoveryService untouched) + Pca2D (commons-math3 EigenDecomposition; lexicographically sorted accumulation, deterministic sign convention, per-axis [-1,1] scaling; permutation-invariance covered by test).
  • Privacy: raw 512-d vectors are never returned (contract test scans response recursively for vector fields). 4000-point cap; target+tentative always kept, farthest neighbor persons dropped first with truncated flag.
  • Auth: session auth via PrincipalHelper, owner-scoped, 400 for non-people domainKey, 404 for foreign/missing instances.

Tests

  • Pca2DTest (3): two-cluster separation on PC1, exact determinism under permuted input order, range/edge cases.
  • EmbeddingMapServiceTest (5): tentative points carry candidateId, neighbor ranking + 5-limit, cross-model-space skip, cap+truncated, access rejection.
  • EmbeddingMapEndpointTest (3): controller delegation, JSON contract field names, no-raw-vector scan.
  • Scoped suite green: 458 tests, 0 failures (discovery package + RetrospectiveMatchingFallbackTest for CosineDistance change).

Spec: specs/042-person-embedding-cluster-map-(pca-diagnostic-view)/

## Summary - New read-only diagnostic endpoint `GET /api/discovery/domains/{domainKey}/class-instances/{instanceId}/embedding-map` returning a deterministic 2D PCA projection of a person's face-embedding cluster: confirmed faces, tentative candidate faces (with suggesting candidateId), and the 5 nearest neighbor persons ranked by min pairwise cosine distance. - New `EmbeddingMapService` (ClassInstanceDiscoveryService untouched) + `Pca2D` (commons-math3 EigenDecomposition; lexicographically sorted accumulation, deterministic sign convention, per-axis [-1,1] scaling; permutation-invariance covered by test). - Privacy: raw 512-d vectors are never returned (contract test scans response recursively for vector fields). 4000-point cap; target+tentative always kept, farthest neighbor persons dropped first with `truncated` flag. - Auth: session auth via PrincipalHelper, owner-scoped, 400 for non-people domainKey, 404 for foreign/missing instances. ## Tests - `Pca2DTest` (3): two-cluster separation on PC1, exact determinism under permuted input order, range/edge cases. - `EmbeddingMapServiceTest` (5): tentative points carry candidateId, neighbor ranking + 5-limit, cross-model-space skip, cap+truncated, access rejection. - `EmbeddingMapEndpointTest` (3): controller delegation, JSON contract field names, no-raw-vector scan. - Scoped suite green: 458 tests, 0 failures (discovery package + RetrospectiveMatchingFallbackTest for CosineDistance change). Spec: specs/042-person-embedding-cluster-map-(pca-diagnostic-view)/
feat(api): person embedding cluster map endpoint (PCA diagnostic view, spec 042)
Some checks failed
Build and Deploy / Detect changed services and test scopes (push) Successful in 3s
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 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 / 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 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) Has been cancelled
ec0e9f368b
Merge main (PR #817) into feat/embedding-map-api to re-trigger CI after runner OOM
All checks were successful
Build and Deploy / Detect changed services and test scopes (push) Successful in 4s
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 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 / 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 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 3m29s
cdc2a0f86d
chris merged commit 02fc6cc2ef into main 2026-09-22 20:39: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!816
No description provided.