Module retrieval 

Gallery-based face retrieval.

Given a query embedding and a set of per-cluster galleries (N diverse exemplars per cluster), find the best-matching clusters via k-NN. Each cluster’s score is the mean of the top-k cosine similarities among its gallery members. This is strictly stronger than centroid matching: a cluster is “close” if multiple of its real members are close, not just its mean.

The result drives confidence-banded assignment: HIGH -> auto-assign, LOW -> leave unassigned, AMBIGUOUS -> queue for user review.

Structs

BandingConfig

Thresholds for banding. Tuned for ArcFace / GLinTR L2-normalized embeddings.

RetrievalHit

A cluster candidate ranked against the query face.

Enums

ConfidenceBand

Assignment recommendation for a query face.

Functions

classify

Classify the retrieval result into a confidence band.

retrieve_candidates

Retrieve ranked cluster candidates for a query embedding.