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
impl Router
Sourcepub fn new(default_model: impl Into<String>) -> Self
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).
Sourcepub fn set_default_model(&mut self, model: impl Into<String>)
pub fn set_default_model(&mut self, model: impl Into<String>)
Set the default model (used when no rule matches a task class).
Sourcepub fn add_rule(&mut self, rule: RoutingRule)
pub fn add_rule(&mut self, rule: RoutingRule)
Add (or replace) the rule for a task class.
Sourcepub fn with_rule(self, rule: RoutingRule) -> Self
pub fn with_rule(self, rule: RoutingRule) -> Self
Builder-style version of Router::add_rule.
Sourcepub fn add_pricing(&mut self, model: impl Into<String>, pricing: ModelPricing)
pub fn add_pricing(&mut self, model: impl Into<String>, pricing: ModelPricing)
Add (or replace) pricing for a model key.
Sourcepub fn with_pricing(
self,
model: impl Into<String>,
pricing: ModelPricing,
) -> Self
pub fn with_pricing( self, model: impl Into<String>, pricing: ModelPricing, ) -> Self
Builder-style version of Router::add_pricing.
Sourcepub fn merge_pricing(&mut self, table: &PricingTable)
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.
Sourcepub fn default_model(&self) -> &str
pub fn default_model(&self) -> &str
The current default model.
Sourcepub fn pricing_for(&self, model: &str) -> Option<&ModelPricing>
pub fn pricing_for(&self, model: &str) -> Option<&ModelPricing>
Pricing for a model key, if present in the table.
Sourcepub fn pricing_table(&self) -> &BTreeMap<String, ModelPricing>
pub fn pricing_table(&self) -> &BTreeMap<String, ModelPricing>
The full pricing table.
Sourcepub fn rule_for(&self, task: TaskClass) -> Option<&RoutingRule>
pub fn rule_for(&self, task: TaskClass) -> Option<&RoutingRule>
The rule configured for a task class, if any.
Sourcepub fn route(&self, task: TaskClass) -> RouteDecision<'_>
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.
Sourcepub fn select_by_complexity(&self, complexity: TaskComplexity) -> Option<&str>
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).
Sourcepub fn estimate_cost(
&self,
model: &str,
input_tokens: usize,
output_tokens: usize,
) -> f64
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).
Sourcepub fn default_rules(provider: &str, primary_model: &str) -> Vec<RoutingRule>
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.
Sourcepub fn with_default_rules(
provider: &str,
primary_model: impl Into<String>,
) -> Self
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.