Selector

Overview

The Selector trait defines how the final set of candidates is chosen from the scored pool. Selectors typically sort candidates by their scores and truncate to a desired size.

Trait Definition

pub trait Selector<Q, C>: Send + Sync
where
    Q: Clone + Send + Sync + 'static,
    C: Clone + Send + Sync + 'static,
{
    fn select(&self, query: &Q, candidates: Vec<C>) -> Vec<C>;
    fn enable(&self, query: &Q) -> bool;
    fn score(&self, candidate: &C) -> f64;
    fn sort(&self, candidates: Vec<C>) -> Vec<C>;
    fn size(&self) -> Option<usize>;
    fn name(&self) -> &'static str;
}

Type Parameters

generic

The query type that contains request context and parametersConstraints: Clone + Send + Sync + 'static

generic

The candidate type to select fromConstraints: Clone + Send + Sync + 'static

Methods

select

Main selection method that sorts and truncates candidates

fn select(&self, query: &Q, candidates: Vec<C>) -> Vec<C>

Reference to the query object

Vec<C>

Vector of candidates to select from (takes ownership)

Vec<C>

Selected and sorted candidates, truncated to size() if specified

The default implementation calls sort() and then truncates to size() if provided.

enable

Determines whether this selector should run for the given query

fn enable(&self, query: &Q) -> bool

Reference to the query object

bool

Returns true if this selector should run, false to skip. Default implementation returns true.

score

required

Extracts the score to use for sorting from a candidate

fn score(&self, candidate: &C) -> f64

Reference to a candidate

f64

The numeric score to use for ranking. Higher scores rank higher.

This method must be implemented by the selector. Use f64::NEG_INFINITY for candidates that should rank lowest.

sort

Sorts candidates by their scores in descending order

fn sort(&self, candidates: Vec<C>) -> Vec<C>

Vec<C>

Vector of candidates to sort

Vec<C>

Sorted candidates with highest scores first

The default implementation sorts by calling score() for each candidate and comparing in descending order.

size

Optionally specifies how many candidates to select

fn size(&self) -> Option<usize>

Option<usize>

The number of top candidates to select, or None for no truncation. Default implementation returns None.

name

Returns a stable name for logging and metrics

fn name(&self) -> &'static str

&'static str

A short type name derived from the implementing struct

Example Implementation

Here’s a real example that selects the top K candidates by score:

use xai_candidate_pipeline::selector::Selector;

pub struct TopKScoreSelector;

impl Selector<ScoredPostsQuery, PostCandidate> for TopKScoreSelector {
    fn score(&self, candidate: &PostCandidate) -> f64 {
        // Use the candidate's final score, or negative infinity if missing
        candidate.score.unwrap_or(f64::NEG_INFINITY)
    }
    
    fn size(&self) -> Option<usize> {
        // Return top 100 candidates
        Some(100)
    }
}

With the default implementations, this selector will:

Sort all candidates by their score field in descending order
Truncate to the top 100 candidates
Return the selected candidates

Advanced Example

Here’s a more complex selector that implements custom selection logic:

pub struct DiversitySelector {
    pub target_size: usize,
    pub max_per_author: usize,
}

impl Selector<ScoredPostsQuery, PostCandidate> for DiversitySelector {
    fn select(&self, _query: &ScoredPostsQuery, candidates: Vec<PostCandidate>) -> Vec<PostCandidate> {
        let mut sorted = self.sort(candidates);
        let mut selected = Vec::new();
        let mut author_counts = HashMap::new();
        
        // Select candidates while enforcing diversity constraints
        for candidate in sorted {
            let author_count = author_counts.entry(candidate.author_id).or_insert(0);
            
            if *author_count < self.max_per_author && selected.len() < self.target_size {
                selected.push(candidate);
                *author_count += 1;
            }
        }
        
        selected
    }
    
    fn score(&self, candidate: &PostCandidate) -> f64 {
        candidate.score.unwrap_or(f64::NEG_INFINITY)
    }
    
    fn size(&self) -> Option<usize> {
        Some(self.target_size)
    }
}

Usage Notes

Selectors typically run once at the end of the pipeline
The select method can be overridden for complex selection logic
The default select implementation handles most simple cases (sort + truncate)
The sort method can be overridden for custom sorting algorithms
Use enable() to conditionally apply different selectors based on query parameters

Common Selector Types

Score-Based Selectors

Top-K by final score
Top-K by specific score field (e.g., engagement score)
Threshold-based selection

Diversity Selectors

Limit candidates per author
Ensure content type diversity
Balance different candidate sources

Context-Aware Selectors

Time-of-day dependent selection
User preference-based selection
A/B test variant selection

Best Practices

Score Extraction: Implement score() to extract the appropriate score field
Handle Missing Scores: Use f64::NEG_INFINITY for candidates without scores
Efficient Sorting: The default sort() is efficient for most cases
Overflow Safety: Use Vec::truncate() which handles cases where size > length
Deterministic Ordering: Ensure stable sorting for reproducible results
Override Selectively: Override select() only when you need custom logic beyond sort+truncate

Performance Considerations

Sorting is O(n log n) where n is the candidate count
Consider using partial sorting (like select_nth_unstable) for large candidate pools
Truncation after sorting is O(1) using Vec::truncate()
The selector is typically not on the critical path since it runs on already-reduced candidate sets

Candidate Pipeline Traits

Phoenix Models

Home Mixer Components

Overview

Trait Definition

Type Parameters

Methods

select

enable

score

sort

size

name

Example Implementation

Advanced Example

Usage Notes

Common Selector Types

Score-Based Selectors

Diversity Selectors

Context-Aware Selectors

Best Practices

Performance Considerations

See Also

​Overview

​Trait Definition

​Type Parameters

​Methods

​select

​enable

​score

​sort

​size

​name

​Example Implementation

​Advanced Example

​Usage Notes

​Common Selector Types

​Score-Based Selectors

​Diversity Selectors

​Context-Aware Selectors

​Best Practices

​Performance Considerations

​See Also

Overview

Trait Definition

Type Parameters

Methods

select

enable

score

sort

size

name

Example Implementation

Advanced Example

Usage Notes

Common Selector Types

Score-Based Selectors

Diversity Selectors

Context-Aware Selectors

Best Practices

Performance Considerations

See Also