Struct EmbeddingRouter 

pub struct EmbeddingRouter { /* private fields */ }

The embedding-based NLU router.

Pre-computes tool embeddings at initialization, then routes queries by embedding the query and computing cosine similarity against all tool embeddings. OATS refinement adjusts tool embeddings based on observed outcomes.

Implementations

impl EmbeddingRouter

pub fn new(embedder: Box<dyn Embedder>) -> Option<Self>

Create a new embedding router, pre-computing tool embeddings.

Returns None if:

• The embedder is a stub (hash-based embeddings have no semantic meaning)
• Batch embedding fails

This allows the caller to gracefully fall back to the TF-IDF router.

pub fn with_descriptions( embedder: Box<dyn Embedder>, descriptions: Vec<(String, String)>, ) -> Option<Self>

Create a new embedding router from explicit (tool, description) pairs.

Unlike Self::new — which uses the static keyword profiles from nlu.rs (169 tools, keyword-mashup descriptions) — this accepts descriptions from the live tool registry (all 229 tools, prose descriptions). Sentence-style descriptions embed far better than bare keyword lists; the 2026-08-11 shadow run (42.6% disagreement) showed keyword-mashup top-1 selection collapsing onto arbitrary high-similarity tools.

pub fn route(&self, query: &str) -> (String, f64)

Route a natural language query to a tool name and confidence score.

Returns ("gnosis", 0.0) for empty input or when no tool scores above the minimum threshold.

pub fn route_with_margin(&self, query: &str) -> Option<(String, f64, f64)>

Route a query, returning (tool, confidence, margin).

margin is the score gap between the top-1 and top-2 tools. Small margins indicate the descriptions cannot separate intent — callers should defer to the TF-IDF router when margin < MIN_MARGIN.

pub fn route_with_margin_and_embedding( &self, query: &str, ) -> Option<(String, f64, f64, Vec<f32>)>

Route a query, also returning the query embedding.

The embedding is what record_outcome_with_embedding needs — returning it here lets callers embed each query once instead of twice (embedder HTTP round-trips dominate NLU latency).

pub fn record_outcome(&self, tool_name: &str, query: &str, success: bool)

Record a routing outcome for OATS refinement.

Call this after each tool dispatch to track whether the routing was correct. success = true means the tool was the right choice and executed successfully; false means it was wrong or failed.

pub fn record_outcome_with_embedding( &self, tool_name: &str, query: &str, success: bool, query_emb: &[f32], )

Record a routing outcome reusing a query embedding already computed by the router.

Callers that routed through route_with_margin should pass the embedding back here so the query is embedded only once instead of twice (HTTP embedder round-trips dominate NLU latency).

pub fn tool_count(&self) -> usize

Number of tool embeddings in the router.

pub const fn dimension(&self) -> usize

Embedding dimensionality.

pub fn backend_name(&self) -> &str

Embedder backend name.

pub fn outcome_counts(&self) -> Vec<(String, usize, usize)>

Get a snapshot of outcome stats counts for observability.

pub fn save_oats(&self) -> Option<String>

Serialize OATS outcome stats to JSON for persistence.

pub fn load_oats(&self, json: &str)

Load OATS outcome stats from JSON (previously saved by save_oats).