Skip to main content

model_router/
lib.rs

1//! Cost-aware LLM routing: pricing tables, USD budgets, task-class routing.
2//!
3//! `model-router` is the extracted, dependency-light core of the router built
4//! for [clawdius](https://github.com/WyattAu/clawdius). It contains only pure
5//! types and math:
6//!
7//! - [`ModelPricing`] — per-model input/output rates in USD per 1M tokens.
8//! - [`PricingTable`] — a refreshable set of [`ModelPricing`] entries with
9//!   freshness stamps, newer-wins [`PricingTable::merge`], and JSON loading
10//!   (`PricingTable::from_json`, feature `json`) so rates can be updated
11//!   at runtime without a crate release.
12//! - [`CostTracker`] — thread-safe accumulation of spend against an optional
13//!   USD budget; rejects any single record that would push spend over budget.
14//! - [`TaskClass`] — a small generic routing class (`Fast` / `Balanced` /
15//!   `Power` / `Embedding`).
16//! - [`RoutingRule`] + [`Router`] — task class to model selection with a
17//!   linked fallback chain, plus quality-tier-aware selection by
18//!   [`TaskComplexity`].
19//!
20//! # Design
21//!
22//! The crate is deliberately free of any HTTP client, provider SDK, async
23//! runtime, or tool-execution concerns. It answers exactly one question:
24//!
25//! > given a task class (and optionally a complexity requirement), which
26//! > model should I call, what is the fallback order, and what did it cost?
27//!
28//! Wiring the selected model to an actual API is the caller's job (see the
29//! optional `genai` feature for a thin companion adapter to the
30//! [`genai`](https://crates.io/crates/genai) crate).
31//!
32//! # Task-class mapping
33//!
34//! clawdius used coding-workflow-shaped task types. [`TaskClass`] generalizes
35//! them; the suggested mapping is:
36//!
37//! | clawdius task type | [`TaskClass`] | typical model tier     |
38//! |--------------------|---------------|------------------------|
39//! | `Think`            | [`TaskClass::Fast`]    | cheap / fast  |
40//! | `Summarize`        | [`TaskClass::Fast`]    | cheap / fast  |
41//! | `Test`             | [`TaskClass::Fast`]    | cheap / fast  |
42//! | `Plan`             | [`TaskClass::Balanced`]| mid tier      |
43//! | `Review`           | [`TaskClass::Balanced`]| mid tier      |
44//! | `Chat`             | [`TaskClass::Balanced`]| mid tier      |
45//! | `Build`            | [`TaskClass::Power`]   | strongest     |
46//! | *(embeddings)*     | [`TaskClass::Embedding`]| embedding models |
47//!
48//! # Feature flags
49//!
50//! - `serde` — `Serialize`/`Deserialize` on the public data types.
51//! - `json` — `PricingTable::from_json` / `PricingTable::to_json` for
52//!   the price-refresh workflow (implies `serde`).
53//! - `genai` — companion adapter from `genai::chat::ModelIden` to pricing
54//!   entries (pulls in the `genai` crate; core stays genai-free).
55//!
56//! # Guarantees
57//!
58//! - `#![forbid(unsafe_code)]` — no unsafe anywhere in the crate.
59//! - `#![deny(missing_docs)]` — the entire public API is documented.
60//! - [`CostTracker::record`] checks the budget *before* mutating, so an
61//!   over-budget request never lands: tracked spend can never exceed the
62//!   limit (checked-then-added semantics).
63
64#![forbid(unsafe_code)]
65#![deny(missing_docs)]
66
67mod cost;
68mod error;
69mod pricing;
70mod routing;
71
72#[cfg(feature = "genai")]
73pub mod genai_compat;
74
75pub use cost::{CostReport, CostTracker, ModelCostBreakdown};
76pub use error::RouterError;
77pub use pricing::{default_pricing_table, ModelPricing, PricingTable};
78pub use routing::{RouteDecision, Router, RoutingRule, TaskClass, TaskComplexity};