Struct CascadeRetriever 

pub struct CascadeRetriever { /* private fields */ }

Cascading retrieval orchestrator.

Coordinates the 4-tier retrieval pipeline, falling back to API only when CPU-local tiers cannot satisfy the query.

Implementations

impl CascadeRetriever

pub fn new(config: CascadeConfig) -> Self

Create a new cascade retriever with given configuration.

pub fn default_config() -> Self

Create a new cascade retriever with default configuration.

pub fn add_episode(&mut self, id: &str, text: &str)

Add an episode to the retrieval index.

This indexes the episode in BM25 and encodes it for HDC similarity search. When the csm feature is not enabled, this just stores the episode data for later retrieval.

pub fn clear(&mut self)

Clear all indexed episodes.

pub fn len(&self) -> usize

Get the number of indexed episodes.

pub fn is_empty(&self) -> bool

Check if the index is empty.

pub fn retrieve(&self, query: &str) -> CascadeResult

Execute the cascading retrieval pipeline.

When the csm feature is enabled, this implements a 4-tier cascade:

1. BM25 keyword search (CPU-local, 0 API calls)
2. HDC similarity search (CPU-local, 0 API calls)
3. ConceptGraph expansion (CPU-local, 0 API calls)
4. API fallback (requires external embedding call)

Without csm, returns empty results (placeholder behavior).

pub fn config(&self) -> &CascadeConfig

Get the configuration for this retriever.

pub fn estimate_api_call_probability(&self, query: &str) -> f32

Estimate the probability that a query would require an API call.

Returns a value in [0.0, 1.0] where:

• 0.0 means CPU-local tiers (BM25/HDC/ConceptGraph) are very likely to suffice
• 1.0 means an API embedding call is almost certainly needed

Heuristic: short keyword-rich queries resolve via BM25 (low probability); long abstract queries with few known terms need semantic embedding (high probability).