Method ReadNearestCandidatesAsync

Namespace

MailFathom.Application.Emails.Search

Assembly

MailFathom.Application.dll

ReadNearestCandidatesAsync(MailboxEmailSelection, RegisteredEmbeddingProfile, EmbeddingVector, int, CancellationToken)

Reads the emails whose nearest passage sits closest to a query vector, among those the filters select.

Task<IReadOnlyList<RankedEmailCandidate>> ReadNearestCandidatesAsync(MailboxEmailSelection selection, RegisteredEmbeddingProfile profile, EmbeddingVector queryVector, int limit, CancellationToken cancellationToken)

Parameters

selection MailboxEmailSelection

Which emails are eligible before any distance is measured.

profile RegisteredEmbeddingProfile

The vector space both the stored vectors and the query vector belong to.

queryVector EmbeddingVector

Where the query itself lands in that space.

limit int

The greatest number of candidates to return, at least one.

cancellationToken CancellationToken

Propagates caller cancellation.

Returns

Task<IReadOnlyList<RankedEmailCandidate>>

At most limit candidates, nearest first, empty when no eligible message is embedded.

Remarks

A message appears once however many of its passages are near, scored by its nearest one. Ranking passages would let one long message fill a window with its own paragraphs while a shorter message that answers the query better never appears.

The order is deterministic, on the same terms the lexical ranking is: distance ties are broken by the newest-first timeline order, which is total. A message with no vector under this profile is absent rather than distant — mail that synchronization has stored and generation has not yet reached is not near anything.

Exceptions

ArgumentNullException

Thrown when any reference argument is null.

ArgumentOutOfRangeException

Thrown when limit is below one.