Agentic.ModelRouter
(agentic v0.3.0)
Copy Markdown
Smart model routing for Agentic with two selection modes.
Modes
:manual— the caller picks a tier (:primary,:lightweight) and the router resolves the best route from the catalog. This is the legacy behaviour and the default.:auto— the router analyses the request using a fast/free model, determines complexity and required capabilities, then selects the best model based on user preference (:optimize_priceor:optimize_speed).
Auto mode flow
1. `Analyzer.analyze/2` classifies the request (complexity, capabilities)
2. `Selector.select/3` scores all catalog models using the analysis
and user preference
3. The best-scoring model is returned as a routeManual mode flow
1. Caller provides a `tier` (`:primary`, `:lightweight`, `:any`)
2. Router queries the catalog, sorts by priority, returns healthy routesSummary
Functions
Auto-select the best model for a request given a user preference.
Returns a specification to start this module under a supervisor.
Clear workspace tier overrides.
Report a failed call for a route.
Report a successful call for a route.
Resolve the best route for a tier (manual mode).
Get all available routes for a tier (manual mode).
Get all available routes for a tier, scored against the supplied
per-provider accounts (for cost_profile + quota_pressure + availability).
Pass nil to fall back to default :pay_per_token/:ready accounts —
matches the behaviour of resolve_all/1.
Like resolve_all_with_accounts/2, but also accepts a
canonical_id => preferred_provider_atom map and the user's price/
speed preference. Pathways whose provider is the user's preferred
pathway for their canonical group get a strong score bonus (acts
as a hard tie-breaker — within a canonical group, the user's pick
wins over the cost-derived ranking unless that pick is
:unavailable). The preference (:optimize_price |
:optimize_speed) is threaded into Preference.score_pathway/3 so
the canonical grouping reflects the user's real ranking criterion
rather than always defaulting to price.
Resolve routes for a context — dispatches to auto or manual based on
ctx.model_selection_mode.
Legacy compat: set routes for a tier (replaced by Catalog, kept for backward compat).
Configure workspace tier overrides.
Get current routing status.
Types
Functions
Auto-select the best model for a request given a user preference.
Returns {:ok, route, analysis} or {:error, reason}.
Returns a specification to start this module under a supervisor.
See Supervisor.
Clear workspace tier overrides.
Report a failed call for a route.
Report a successful call for a route.
Pass sticky: %{tier: tier, filter: filter} to mark this route as the
current sticky pick for that bucket; future resolve_for_context/1
calls with the same bucket will return this route directly without
re-running selection.
Resolve the best route for a tier (manual mode).
Get all available routes for a tier (manual mode).
Get all available routes for a tier, scored against the supplied
per-provider accounts (for cost_profile + quota_pressure + availability).
Pass nil to fall back to default :pay_per_token/:ready accounts —
matches the behaviour of resolve_all/1.
Like resolve_all_with_accounts/2, but also accepts a
canonical_id => preferred_provider_atom map and the user's price/
speed preference. Pathways whose provider is the user's preferred
pathway for their canonical group get a strong score bonus (acts
as a hard tie-breaker — within a canonical group, the user's pick
wins over the cost-derived ranking unless that pick is
:unavailable). The preference (:optimize_price |
:optimize_speed) is threaded into Preference.score_pathway/3 so
the canonical grouping reflects the user's real ranking criterion
rather than always defaulting to price.
Resolve routes for a context — dispatches to auto or manual based on
ctx.model_selection_mode.
Legacy compat: set routes for a tier (replaced by Catalog, kept for backward compat).
Configure workspace tier overrides.
Get current routing status.