Struct FibSidecarIndex 

pub struct FibSidecarIndex<Id>
where
    Id: Clone + Eq + Debug,
{ /* private fields */ }

Generic ID-typed sidecar search index.

Wraps a FibScorer and stores a list of (Id, FibCodeV1) entries. Search uses the Gram-table estimator for each stored code and returns candidates sorted by descending approximate inner product.

The index is cheap to clone (via Clone on the scorer and entries) but in typical usage a single instance is shared by reference across queries.

Generics

Id must be Clone + Eq + Debug. Common choices are u64, String, or a newtype key. The index does not enforce uniqueness — adding the same ID twice will produce two entries.

Implementations

impl<Id> FibSidecarIndex<Id>

where Id: Clone + Eq + Debug,

pub fn new(scorer: FibScorer) -> Self

Construct a new sidecar index from a FibScorer.

The scorer’s profile is cloned for validation of incoming codes. The index starts empty.

pub fn scorer(&self) -> &FibScorer

Return a reference to the underlying scorer.

pub fn profile(&self) -> &FibQuantProfileV1

Return a reference to the profile used for validation.

pub fn add(&mut self, id: Id, code: FibCodeV1)

Add a single encoded vector with a caller-owned ID.

The code’s ambient_dim and block_dim are checked against the scorer’s profile to catch mismatches early.

pub fn add_batch(&mut self, entries: Vec<(Id, FibCodeV1)>)

Add many encoded vectors at once.

Equivalent to calling add in a loop but avoids repeated capacity growth.

pub fn len(&self) -> usize

Number of encoded entries currently stored.

pub fn entries(&self) -> &[(Id, FibCodeV1)]

Return a slice of all (Id, FibCodeV1) entries.

Used by persistence to serialize the index to disk. The slice borrows from the index.

pub fn is_empty(&self) -> bool

Whether the index is empty.

pub fn search( &self, query: &[f32], top_k: usize, oversample: usize, ) -> Result<Vec<ScoredCandidate<Id>>>

Approximate search returning sorted candidates.

Scores every stored code against the query, sorts by descending approximate inner product, and returns the top top_k * oversample candidates (or fewer if the index has fewer entries).

The returned candidates have rank assigned starting from 0. Callers must rerank these candidates with an exact inner product against the original (un-encoded) vectors before acting on results.

pub fn search_with_receipt( &self, query: &[f32], top_k: usize, oversample: usize, ) -> Result<(Vec<ScoredCandidate<Id>>, SearchReceiptV1)>

Approximate search returning both candidates and a SearchReceiptV1.

See search for search semantics. The receipt documents the operational parameters and timing of the search.

pub fn ivf(&self) -> Option<&IvfCoarseQuantizer>

Return a reference to the IVF coarse quantizer, if built.

pub fn ivf_is_built(&self) -> bool

Whether the IVF coarse quantizer has been built.

pub fn build_ivf(&mut self, num_centroids: usize) -> Result<()>

Build the IVF coarse quantizer by running k-means on decoded vectors.

Decodes all stored FibCodeV1 entries to their approximate vectors using the scorer’s quantizer, runs k-means with num_centroids centroids (default: sqrt(N)), and stores the centroids and assignments. After this call, search_ivf will use the IVF path instead of falling back to linear scan.

Arguments

• num_centroids — number of k-means centroids (k). Pass (self.len() as f64).sqrt() as usize or let build_ivf_default compute it.

pub fn build_ivf_default(&mut self) -> Result<()>

Build IVF with default k = sqrt(N) centroids.

pub fn search_ivf( &self, query: &[f32], top_k: usize, oversample: usize, nprobe: usize, ) -> Result<Vec<ScoredCandidate<Id>>>

IVF-accelerated search.

Finds the nprobe nearest centroids to the query, gathers all entries assigned to those centroids, scores them using the prepared query (Gram table), and returns the top top_k * oversample candidates sorted by descending approximate inner product.

If IVF is not built (centroids empty or ivf is None), falls back to a full linear scan via search.

pub fn search_with_receipt_ivf( &self, query: &[f32], top_k: usize, oversample: usize, nprobe: usize, ) -> Result<(Vec<ScoredCandidate<Id>>, SearchReceiptIvfV1)>

IVF-accelerated search with receipt.

Like search_ivf but returns a SearchReceiptIvfV1 documenting the IVF parameters used.