route()

Route a task to the best available model.

Usage

Source

route(
    prompt,
    *,
    strategy=RoutingStrategy.BALANCED,
    requires=None,
    max_cost_tier=None,
    prefer_local=False,
    candidates=None,
    min_context_window=None
)

This is a convenience function that creates a temporary Router instance. For repeated routing, create a Router directly to avoid re-filtering the candidate pool each time.

Parameters

prompt: str

The task or prompt text to route.

strategy: RoutingStrategy = RoutingStrategy.BALANCED


Routing strategy to use.

requires: list[str] | None = None

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

max_cost_tier: CostTier | None = None

Maximum cost tier to consider.

prefer_local: bool = False

Whether to prefer local (Ollama) models.

candidates: list[str] | None = None

Specific model keys to consider. None uses all registered models.

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

# Simple routing with defaults
result = tb.route("Summarize this paragraph")
result.model.name  # e.g., "GPT-4o Mini"

# Prefer local models, cap cost at MEDIUM
result = tb.route(
    "Explain decorators in Python",
    strategy=tb.RoutingStrategy.LOCAL_FIRST,
    max_cost_tier=tb.CostTier.MEDIUM,
)

# Require specific capabilities
result = tb.route(
    "Analyze this image and describe what you see",
    requires=["vision"],
    strategy=tb.RoutingStrategy.QUALITY_OPTIMIZED,
)