# `Agentic.ModelRouter`

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_price` or
    `: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 route

## Manual mode flow

    1. Caller provides a `tier` (`:primary`, `:lightweight`, `:any`)
    2. Router queries the catalog, sorts by priority, returns healthy routes

# `selection_mode`

```elixir
@type selection_mode() :: :manual | :auto
```

# `auto_select`

Auto-select the best model for a request given a user preference.

Returns `{:ok, route, analysis}` or `{:error, reason}`.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `clear_tier_overrides`

Clear workspace tier overrides.

# `report_error`

Report a failed call for a route.

# `report_success`

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`

Resolve the best route for a tier (manual mode).

# `resolve_all`

Get all available routes for a tier (manual mode).

# `resolve_all_with_accounts`

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`.

# `resolve_all_with_context`

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_for_context`

Resolve routes for a context — dispatches to auto or manual based on
`ctx.model_selection_mode`.

# `set_routes`

Legacy compat: set routes for a tier (replaced by Catalog, kept for backward compat).

# `set_tier_overrides`

Configure workspace tier overrides.

# `start_link`

# `status`

Get current routing status.

---

*Consult [api-reference.md](api-reference.md) for complete listing*