Function retrieve_candidates 

pub fn retrieve_candidates(
    query: &FaceEmbedding,
    galleries: &[(i64, Vec<(i64, FaceEmbedding)>)],
    top_k: usize,
    min_similarity: f32,
    exclude: &HashSet<i64>,
) -> Vec<RetrievalHit>

Retrieve ranked cluster candidates for a query embedding.

galleries is a slice of (cluster_id, Vec<(face_id, embedding)>). All embeddings are assumed L2-normalized (as produced by the embedder and stored in person_gallery_embeddings).

top_k is the number of best matches per cluster to average into that cluster’s score. 5 is a good default.

min_similarity filters individual gallery members below this cosine similarity before they contribute to the score.

Clusters in exclude are skipped entirely – used to honor cannot-merge constraints and same-photo conflict prevention.

Returns clusters sorted by descending score. Empty if no cluster scored above min_similarity.