Skip to main content

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}