model_router/routing.rs
1//! Task-class routing with fallback chains.
2
3#[cfg(feature = "serde")]
4use serde::{Deserialize, Serialize};
5use std::collections::{BTreeMap, HashMap};
6
7use crate::pricing::{default_pricing_table, merge_into, ModelPricing, PricingTable};
8
9/// Generic routing class for a unit of work.
10///
11/// This replaces clawdius's coding-workflow-shaped `TaskType`. The intended
12/// mapping (also enforced by [`TaskClass::for_phase_name`] and documented in
13/// the crate root):
14///
15/// - `Think`, `Test`, `Summarize` → [`TaskClass::Fast`]
16/// - `Plan`, `Review`, `Chat` → [`TaskClass::Balanced`]
17/// - `Build` → [`TaskClass::Power`]
18/// - embedding work → [`TaskClass::Embedding`]
19#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
20#[cfg_attr(
21 feature = "serde",
22 derive(Serialize, Deserialize),
23 serde(rename_all = "snake_case")
24)]
25pub enum TaskClass {
26 /// Low-stakes work that should use the cheapest acceptable model
27 /// (thinking, testing, summarization).
28 Fast,
29 /// Everyday work handled well by a mid-tier model (planning, review,
30 /// general chat).
31 Balanced,
32 /// High-stakes generation that needs the strongest available model
33 /// (code generation, architecture).
34 Power,
35 /// Embedding work; routed to an embedding model, never a chat model.
36 Embedding,
37}
38
39impl TaskClass {
40 /// Map a phase/step name to a task class.
41 ///
42 /// Accepts the clawdius phase vocabulary (`think`, `plan`, `build`,
43 /// `implement`, `code`, `test`, `verify`, `review`, `reflect`,
44 /// `summarize`) plus `embed`/`embedding(s)` and `chat`; matching is
45 /// case-insensitive. Unknown names map to [`TaskClass::Balanced`].
46 pub fn for_phase_name(phase: &str) -> Self {
47 match phase.to_lowercase().as_str() {
48 "think" | "test" | "verify" | "summarize" | "summarise" => Self::Fast,
49 "embed" | "embedding" | "embeddings" => Self::Embedding,
50 "build" | "implement" | "code" => Self::Power,
51 _ => Self::Balanced,
52 }
53 }
54}
55
56impl std::fmt::Display for TaskClass {
57 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
58 match self {
59 Self::Fast => write!(f, "fast"),
60 Self::Balanced => write!(f, "balanced"),
61 Self::Power => write!(f, "power"),
62 Self::Embedding => write!(f, "embedding"),
63 }
64 }
65}
66
67/// Task complexity levels for cost-aware routing.
68///
69/// Each level implies a minimum [`ModelPricing::quality_tier`] when
70/// selecting a model with [`Router::select_by_complexity`].
71#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
72pub enum TaskComplexity {
73 /// Simple tasks: formatting, renaming, simple refactors (tier >= 2).
74 Simple,
75 /// Medium tasks: bug fixes, small features, code review (tier >= 3).
76 Medium,
77 /// Complex tasks: architecture, multi-file refactors, complex
78 /// algorithms (tier >= 4).
79 Complex,
80 /// Critical tasks: security fixes, production issues, complex
81 /// debugging (tier >= 5).
82 Critical,
83}
84
85impl TaskComplexity {
86 /// Minimum [`ModelPricing::quality_tier`] required for this complexity.
87 pub fn min_quality_tier(self) -> u8 {
88 match self {
89 Self::Simple => 2,
90 Self::Medium => 3,
91 Self::Complex => 4,
92 Self::Critical => 5,
93 }
94 }
95}
96
97/// A routing rule: which model to use for a [`TaskClass`], with an optional
98/// fallback rule tried if the primary is unavailable.
99///
100/// The provider concept from clawdius was dropped from the core: a model key
101/// is an opaque string that must match an entry in the pricing table (or be
102/// estimated with placeholder pricing). Namespaced keys such as
103/// `openrouter/google/gemma-3-4b-it:free` work fine.
104#[derive(Debug, Clone, PartialEq, Eq)]
105#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
106pub struct RoutingRule {
107 /// Task class this rule applies to.
108 pub task: TaskClass,
109 /// Model key (e.g. `"claude-sonnet-4-20250514"`).
110 pub model: String,
111 /// Fallback rule tried if the primary model is unavailable.
112 pub fallback: Option<Box<RoutingRule>>,
113}
114
115impl RoutingRule {
116 /// Create a rule with no fallback.
117 pub fn new(task: TaskClass, model: impl Into<String>) -> Self {
118 Self {
119 task,
120 model: model.into(),
121 fallback: None,
122 }
123 }
124
125 /// Attach a fallback rule (builder style).
126 pub fn with_fallback(mut self, fallback: RoutingRule) -> Self {
127 self.fallback = Some(Box::new(fallback));
128 self
129 }
130
131 /// Iterate this rule followed by its fallback chain, in order.
132 pub fn chain(&self) -> impl Iterator<Item = &RoutingRule> {
133 let mut current = Some(self);
134 std::iter::from_fn(move || {
135 let rule = current?;
136 current = rule.fallback.as_deref();
137 Some(rule)
138 })
139 }
140}
141
142/// The result of routing a task: the primary model plus its fallback order.
143///
144/// `primary` is always `fallbacks[0]`'s model when a rule matched (i.e.
145/// [`RouteDecision::candidates`] yields the exact chain order); it is the
146/// router's default model when no rule matched.
147#[derive(Debug, Clone, PartialEq, Eq)]
148pub struct RouteDecision<'a> {
149 /// The task class that was routed.
150 pub task: TaskClass,
151 /// Selected primary model.
152 pub primary: &'a str,
153 /// Fallback chain in try order: primary first, then each fallback.
154 pub fallbacks: Vec<&'a str>,
155}
156
157impl<'a> RouteDecision<'a> {
158 /// All candidate models in try order (primary, then fallbacks).
159 pub fn candidates(&self) -> impl Iterator<Item = &'a str> + '_ {
160 std::iter::once(self.primary).chain(self.fallbacks.iter().copied().skip(1))
161 }
162}
163
164/// Cost-aware task router.
165///
166/// Pure decision logic: given a [`TaskClass`] it resolves the configured
167/// [`RoutingRule`] (or the default model) and returns the fallback chain;
168/// given a [`TaskComplexity`] it picks the most cost-efficient model whose
169/// quality tier meets the requirement. All selection is deterministic —
170/// the pricing table is a [`BTreeMap`] and sorting is stable, so ties are
171/// broken by model name.
172///
173/// # Example
174///
175/// ```
176/// use model_router::{Router, RoutingRule, TaskClass};
177///
178/// let mut router = Router::new("claude-sonnet-4-20250514");
179/// router.add_rule(
180/// RoutingRule::new(TaskClass::Fast, "claude-3-5-haiku-20241022")
181/// .with_fallback(RoutingRule::new(TaskClass::Fast, "gpt-4o-mini")),
182/// );
183///
184/// let decision = router.route(TaskClass::Fast);
185/// assert_eq!(decision.primary, "claude-3-5-haiku-20241022");
186/// assert_eq!(
187/// decision.candidates().collect::<Vec<_>>(),
188/// ["claude-3-5-haiku-20241022", "gpt-4o-mini"]
189/// );
190/// ```
191#[derive(Debug, Clone)]
192pub struct Router {
193 /// Routing rules keyed by task class.
194 rules: HashMap<TaskClass, RoutingRule>,
195 /// Default model when no rule matches.
196 default_model: String,
197 /// Pricing table (BTreeMap => deterministic iteration order).
198 pricing: BTreeMap<String, ModelPricing>,
199}
200
201impl Router {
202 /// Create a router with the built-in pricing table and the given default
203 /// model (used whenever a task class has no rule).
204 pub fn new(default_model: impl Into<String>) -> Self {
205 Self {
206 rules: HashMap::new(),
207 default_model: default_model.into(),
208 pricing: default_pricing_table(),
209 }
210 }
211
212 /// Set the default model (used when no rule matches a task class).
213 pub fn set_default_model(&mut self, model: impl Into<String>) {
214 self.default_model = model.into();
215 }
216
217 /// Add (or replace) the rule for a task class.
218 pub fn add_rule(&mut self, rule: RoutingRule) {
219 self.rules.insert(rule.task, rule);
220 }
221
222 /// Builder-style version of [`Router::add_rule`].
223 pub fn with_rule(mut self, rule: RoutingRule) -> Self {
224 self.add_rule(rule);
225 self
226 }
227
228 /// Add (or replace) pricing for a model key.
229 pub fn add_pricing(&mut self, model: impl Into<String>, pricing: ModelPricing) {
230 self.pricing.insert(model.into(), pricing);
231 }
232
233 /// Builder-style version of [`Router::add_pricing`].
234 pub fn with_pricing(mut self, model: impl Into<String>, pricing: ModelPricing) -> Self {
235 self.add_pricing(model, pricing);
236 self
237 }
238
239 /// Freshness-aware merge of a [`PricingTable`] into the router's table
240 /// (see [`PricingTable::merge`]): entries that are missing from the
241 /// router's table or stamped with a newer
242 /// [`ModelPricing::updated_at_unix`] replace the existing ones; every
243 /// other entry is left untouched. This is the refresh path for keeping
244 /// built-in rates current without a crate release.
245 pub fn merge_pricing(&mut self, table: &PricingTable) {
246 merge_into(&mut self.pricing, table);
247 }
248
249 /// The current default model.
250 pub fn default_model(&self) -> &str {
251 &self.default_model
252 }
253
254 /// Pricing for a model key, if present in the table.
255 pub fn pricing_for(&self, model: &str) -> Option<&ModelPricing> {
256 self.pricing.get(model)
257 }
258
259 /// The full pricing table.
260 pub fn pricing_table(&self) -> &BTreeMap<String, ModelPricing> {
261 &self.pricing
262 }
263
264 /// The rule configured for a task class, if any.
265 pub fn rule_for(&self, task: TaskClass) -> Option<&RoutingRule> {
266 self.rules.get(&task)
267 }
268
269 /// Route a task class: resolve its rule (or the default model) and
270 /// return the primary model plus the full fallback chain in try order.
271 ///
272 /// Deterministic: the same configuration always yields the same decision.
273 pub fn route(&self, task: TaskClass) -> RouteDecision<'_> {
274 match self.rules.get(&task) {
275 Some(rule) => {
276 let fallbacks = rule.chain().map(|r| r.model.as_str()).collect();
277 RouteDecision {
278 task,
279 primary: rule.model.as_str(),
280 fallbacks,
281 }
282 }
283 None => RouteDecision {
284 task,
285 primary: &self.default_model,
286 fallbacks: Vec::new(),
287 },
288 }
289 }
290
291 /// Select the most cost-efficient model whose quality tier meets the
292 /// complexity requirement.
293 ///
294 /// Returns `None` when no priced model meets the minimum tier (callers
295 /// can fall back to [`Router::default_model`] in that case).
296 pub fn select_by_complexity(&self, complexity: TaskComplexity) -> Option<&str> {
297 let min_quality = complexity.min_quality_tier();
298 let mut candidates: Vec<(&String, &ModelPricing)> = self
299 .pricing
300 .iter()
301 .filter(|(_, p)| p.quality_tier >= min_quality)
302 .collect();
303 // Stable sort on a deterministically ordered BTreeMap: ties resolve
304 // to the alphabetically first model name.
305 candidates.sort_by(|a, b| {
306 b.1.efficiency()
307 .partial_cmp(&a.1.efficiency())
308 .unwrap_or(std::cmp::Ordering::Equal)
309 });
310 candidates.first().map(|(name, _)| name.as_str())
311 }
312
313 /// Estimate the USD cost for a model and token counts.
314 ///
315 /// Models missing from the pricing table are estimated with the
316 /// documented placeholder pricing (see [`ModelPricing::default`]).
317 pub fn estimate_cost(&self, model: &str, input_tokens: usize, output_tokens: usize) -> f64 {
318 self.pricing
319 .get(model)
320 .unwrap_or(&ModelPricing::default())
321 .cost(input_tokens, output_tokens)
322 }
323
324 /// Build a default rule set for a typical setup: the given provider/model
325 /// as the strong "primary" model and a known cheaper model from the same
326 /// provider for low-stakes work.
327 ///
328 /// Produces: `Fast` → cheap model, `Balanced` → primary, `Power` →
329 /// primary. Embedding work is left unconfigured (add a rule explicitly).
330 ///
331 /// Provider names follow clawdius's: `anthropic`, `openai`, `google`,
332 /// `zai`, `openrouter`. Unknown providers fall back to using the primary
333 /// model for every class.
334 pub fn default_rules(provider: &str, primary_model: &str) -> Vec<RoutingRule> {
335 let cheap_model = match provider {
336 "anthropic" => "claude-3-5-haiku-20241022",
337 "openai" => "gpt-4o-mini",
338 "google" => "gemini-2.0-flash",
339 "zai" => "glm-4.6",
340 "openrouter" => "google/gemma-3-4b-it:free",
341 _ => primary_model,
342 };
343
344 vec![
345 RoutingRule::new(TaskClass::Fast, cheap_model),
346 RoutingRule::new(TaskClass::Balanced, primary_model),
347 RoutingRule::new(TaskClass::Power, primary_model),
348 ]
349 }
350
351 /// Create a router configured with [`Router::default_rules`] for the
352 /// given provider/model, plus the built-in pricing table.
353 pub fn with_default_rules(provider: &str, primary_model: impl Into<String>) -> Self {
354 let primary_model = primary_model.into();
355 let mut router = Router::new(primary_model.clone());
356 for rule in Router::default_rules(provider, &primary_model) {
357 router.add_rule(rule);
358 }
359 router
360 }
361}