Router

Configurable model router for hybrid local/cloud routing.

Usage

Source

Router()

The router maintains a pool of candidate models and selects the best one for a given task based on the configured strategy, required capabilities, and cost constraints.

Parameters

strategy: RoutingStrategy = RoutingStrategy.BALANCED


Default routing strategy. Can be overridden per-call.

candidates: list[str] | None = None

List of model keys (e.g., "anthropic:claude-sonnet-4-6") to consider. If None, uses all models in the registry.

max_cost_tier: CostTier | None = None

Maximum cost tier to consider. Models above this tier are excluded.

prefer_local: bool = False

Whether to give bonus scoring to local (Ollama) models.

Examples

import talk_box as tb

router = tb.Router(
    strategy=tb.RoutingStrategy.LOCAL_FIRST,
    max_cost_tier=tb.CostTier.MEDIUM,
)

result = router.route("What is a decorator in Python?")
result.model.name       # e.g., "Llama 3.3 (Ollama)"
result.complexity       # TaskComplexity.SIMPLE
result.reason           # "Local model sufficient for simple task"

Attributes

Name	Description
candidates	The pool of candidate models.
strategy	The default routing strategy.

---

candidates

The pool of candidate models.

candidates: list[ModelProfile]

---

strategy

The default routing strategy.

strategy: RoutingStrategy

Methods

Name	Description
route()	Route a task to the best available model.

---

route()

Route a task to the best available model.

Usage

Source

route(
    prompt,
    *,
    strategy=None,
    requires=None,
    max_cost_tier=None,
    min_context_window=None
)

Parameters

prompt: str

The task or prompt text to route.

strategy: RoutingStrategy | None = None

Override the router’s default strategy for this call.

requires: list[str] | None = None

Required capabilities (e.g., ["tools", "vision"]).

max_cost_tier: CostTier | None = None

Override the router’s default max cost tier for this call.

min_context_window: int | None = None

Minimum context window size required.

Returns

RoutingResult

The selected model, reason, complexity, and alternatives.

Raises

ValueError

If no candidate models meet the requirements.

Examples

import talk_box as tb

router = tb.Router()

# Route a simple question cheaply
result = router.route("Define polymorphism")

# Route a complex task requiring tools
result = router.route(
    "Analyze this dataset and generate charts",
    requires=["tools", "vision"],
    strategy=tb.RoutingStrategy.QUALITY_OPTIMIZED,
)