Struct WarpIndex 

pub struct WarpIndex { /* private fields */ }

WARP index for efficient multi-vector retrieval.

The index organizes token embeddings by centroid assignment (IVF structure) for cache-efficient access during search. Each token embedding is stored as:

• Centroid assignment
• Quantized residual (2-4 bits per dimension)

Lifecycle

1. Create index with new(config)
2. Train codec with train(samples)
3. Insert documents with insert(chunk, embedding)
4. Build index with build() (compacts for efficient search)
5. Search with search(query, config)

Memory Layout

After build(), data is organized by centroid:

Centroid 0: [chunk_ids...] [token_indices...] [residuals...]
Centroid 1: [chunk_ids...] [token_indices...] [residuals...]
...

Implementations

impl WarpIndex

pub fn new(config: WarpIndexConfig) -> Self

Create a new WARP index with the given configuration.

pub fn config(&self) -> &WarpIndexConfig

Get the index configuration.

pub fn codec(&self) -> Option<&ResidualCodec>

Get the trained codec (if any).

pub fn is_trained(&self) -> bool

Check if the codec has been trained.

pub fn is_built(&self) -> bool

Check if the index has been built.

pub fn num_chunks(&self) -> usize

Get the number of indexed chunks.

pub fn num_tokens(&self) -> usize

Get the number of indexed tokens.

pub fn is_empty(&self) -> bool

Check if the index is empty.

pub fn get_chunk(&self, id: &ChunkId) -> Option<&Chunk>

Get a chunk by ID.

pub fn memory_usage(&self) -> usize

Get memory usage in bytes (approximate).

pub fn train(&mut self, samples: &[MultiVectorEmbedding]) -> Result<()>

Train the codec from sample embeddings.

Arguments

• samples - Sample multi-vector embeddings for training

Errors

Returns an error if:

• Not enough samples for training
• Configuration is invalid

pub fn insert( &mut self, chunk: Chunk, embedding: MultiVectorEmbedding, ) -> Result<()>

Insert a chunk with its token embeddings.

The chunk will be stored in pending state until build() is called.

Errors

Returns an error if:

• Codec has not been trained
• Index has already been built (call rebuild() first)

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

Build the index for efficient search.

This compacts all pending embeddings into a centroid-organized IVF structure optimized for cache-efficient search.

Errors

Returns an error if the codec has not been trained.

pub fn clear_index(&mut self)

Clear the built index to allow new insertions.

Chunks are preserved, but the IVF structure is cleared. Call build() again after inserting new chunks.

pub fn search( &self, query: &MultiVectorEmbedding, search_config: &WarpSearchConfig, ) -> Result<Vec<(ChunkId, f32)>>

Search for relevant chunks using MaxSim scoring.

Arguments

• query - Query multi-vector embedding
• search_config - Search parameters

Returns

Vector of (ChunkId, score) pairs sorted by score descending.

Errors

Returns an error if the index has not been built.

pub fn centroid_size(&self, centroid_id: usize) -> usize

Get centroid size (number of tokens assigned).

pub fn centroid_offset(&self, centroid_id: usize) -> usize

Get centroid offset in the compacted arrays.

Trait Implementations

impl Clone for WarpIndex

fn clone(&self) -> WarpIndex

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for WarpIndex

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for WarpIndex

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for WarpIndex

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.