Skip to main content

Router

Struct Router 

Source
pub struct Router { /* private fields */ }
Expand description

Cost-aware task router.

Pure decision logic: given a TaskClass it resolves the configured RoutingRule (or the default model) and returns the fallback chain; given a TaskComplexity it picks the most cost-efficient model whose quality tier meets the requirement. All selection is deterministic — the pricing table is a BTreeMap and sorting is stable, so ties are broken by model name.

§Example

use model_router::{Router, RoutingRule, TaskClass};

let mut router = Router::new("claude-sonnet-4-20250514");
router.add_rule(
    RoutingRule::new(TaskClass::Fast, "claude-3-5-haiku-20241022")
        .with_fallback(RoutingRule::new(TaskClass::Fast, "gpt-4o-mini")),
);

let decision = router.route(TaskClass::Fast);
assert_eq!(decision.primary, "claude-3-5-haiku-20241022");
assert_eq!(
    decision.candidates().collect::<Vec<_>>(),
    ["claude-3-5-haiku-20241022", "gpt-4o-mini"]
);

Implementations§

Source§

impl Router

Source

pub fn new(default_model: impl Into<String>) -> Self

Create a router with the built-in pricing table and the given default model (used whenever a task class has no rule).

Source

pub fn set_default_model(&mut self, model: impl Into<String>)

Set the default model (used when no rule matches a task class).

Source

pub fn add_rule(&mut self, rule: RoutingRule)

Add (or replace) the rule for a task class.

Source

pub fn with_rule(self, rule: RoutingRule) -> Self

Builder-style version of Router::add_rule.

Source

pub fn add_pricing(&mut self, model: impl Into<String>, pricing: ModelPricing)

Add (or replace) pricing for a model key.

Source

pub fn with_pricing( self, model: impl Into<String>, pricing: ModelPricing, ) -> Self

Builder-style version of Router::add_pricing.

Source

pub fn merge_pricing(&mut self, table: &PricingTable)

Freshness-aware merge of a PricingTable into the router’s table (see PricingTable::merge): entries that are missing from the router’s table or stamped with a newer ModelPricing::updated_at_unix replace the existing ones; every other entry is left untouched. This is the refresh path for keeping built-in rates current without a crate release.

Source

pub fn default_model(&self) -> &str

The current default model.

Source

pub fn pricing_for(&self, model: &str) -> Option<&ModelPricing>

Pricing for a model key, if present in the table.

Source

pub fn pricing_table(&self) -> &BTreeMap<String, ModelPricing>

The full pricing table.

Source

pub fn rule_for(&self, task: TaskClass) -> Option<&RoutingRule>

The rule configured for a task class, if any.

Source

pub fn route(&self, task: TaskClass) -> RouteDecision<'_>

Route a task class: resolve its rule (or the default model) and return the primary model plus the full fallback chain in try order.

Deterministic: the same configuration always yields the same decision.

Source

pub fn select_by_complexity(&self, complexity: TaskComplexity) -> Option<&str>

Select the most cost-efficient model whose quality tier meets the complexity requirement.

Returns None when no priced model meets the minimum tier (callers can fall back to Router::default_model in that case).

Source

pub fn estimate_cost( &self, model: &str, input_tokens: usize, output_tokens: usize, ) -> f64

Estimate the USD cost for a model and token counts.

Models missing from the pricing table are estimated with the documented placeholder pricing (see ModelPricing::default).

Source

pub fn default_rules(provider: &str, primary_model: &str) -> Vec<RoutingRule>

Build a default rule set for a typical setup: the given provider/model as the strong “primary” model and a known cheaper model from the same provider for low-stakes work.

Produces: Fast → cheap model, Balanced → primary, Power → primary. Embedding work is left unconfigured (add a rule explicitly).

Provider names follow clawdius’s: anthropic, openai, google, zai, openrouter. Unknown providers fall back to using the primary model for every class.

Source

pub fn with_default_rules( provider: &str, primary_model: impl Into<String>, ) -> Self

Create a router configured with Router::default_rules for the given provider/model, plus the built-in pricing table.

Trait Implementations§

Source§

impl Clone for Router

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for Router

Source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.