pyagent-router API Reference

pyagent_router.scorer.DifficultyScorer

Heuristic-based task difficulty scorer.

Scores tasks on a 1-10 scale using multiple signals: - Token length - Keyword complexity - Question structure - Required reasoning depth

Parameters:

Name	Type	Description	Default
custom_signals	dict[str, Any] | None	Optional dict of custom signal functions. Each function takes a task string and returns a float 0-1.	None

score(task)

Score the difficulty of a task string.

pyagent_router.scorer.DifficultyScore dataclass

Result of difficulty scoring.

Attributes:

Name	Type	Description
score	int	Difficulty score from 1 (trivial) to 10 (extremely hard).
signals	dict[str, float]	Dictionary of individual signal scores that contributed.
category	str	Human-readable difficulty category.

pyagent_router.estimator.CostEstimator

Estimate LLM call costs based on model pricing registry.

Parameters:

Name	Type	Description	Default
pricing	dict[str, ModelPricing] | None	Optional custom pricing dict. Defaults to built-in pricing table.	None
default_output_ratio	float	Estimated output/input token ratio when output length unknown.	0.5

compare(text, models=None)

Compare costs across multiple models for the same input.

Parameters:

Name	Type	Description	Default
text	str	The input text.	required
models	list[str] | None	Models to compare. Defaults to all registered models.	None

Returns:

Type	Description
list[CostEstimate]	List of CostEstimates sorted by total_cost ascending.

estimate(model, input_tokens, output_tokens=None)

Estimate cost for a single LLM call.

Parameters:

Name	Type	Description	Default
model	str	Model name (must be in pricing registry).	required
input_tokens	int	Number of input tokens.	required
output_tokens	int | None	Number of output tokens. If None, estimated from input.	None

Returns:

Type	Description
CostEstimate	CostEstimate with breakdown.

Raises:

Type	Description
KeyError	If model not found in pricing registry.

estimate_from_text(model, text)

Estimate cost from raw text (approximates 4 chars per token).

pyagent_router.estimator.CostEstimate dataclass

Estimated cost for a single LLM call.

Attributes:

Name	Type	Description
model	str	Model name.
input_tokens	int	Estimated input tokens.
output_tokens	int	Estimated output tokens.
input_cost	float	Cost for input tokens in USD.
output_cost	float	Cost for output tokens in USD.
total_cost	float	Total estimated cost in USD.

pyagent_router.estimator.ModelPricing dataclass

Pricing for a model per 1M tokens.

pyagent_router.selector.ModelSelector

Select the optimal model based on task difficulty and cost.

Strategy: find the cheapest model whose difficulty range covers the task and whose capabilities match the required capability (if specified).

Parameters:

Name	Type	Description	Default
specs	list[ModelSpec] | None	List of ModelSpec definitions. Defaults to built-in specs.	None
cost_estimator	CostEstimator | None	CostEstimator instance. Created automatically if None.	None
scorer	DifficultyScorer | None	DifficultyScorer instance. Created automatically if None.	None

select(task, required_capability=None)

Select the best model for a given task.

Parameters:

Name	Type	Description	Default
task	str	The task text to analyze.	required
required_capability	Capability | None	Optional capability filter.	None

Returns:

Type	Description
SelectionResult	SelectionResult with chosen model and reasoning.

pyagent_router.selector.ModelSpec dataclass

Specification of a model's capabilities and constraints.

Attributes:

Name	Type	Description
name	str	Model identifier (must match pricing registry).
min_difficulty	int	Minimum difficulty score this model should handle.
max_difficulty	int	Maximum difficulty score this model should handle.
capabilities	set[Capability]	Set of capabilities this model excels at.
max_context	int	Maximum context window in tokens.

pyagent_router.selector.SelectionResult dataclass

Result of model selection.

Attributes:

Name	Type	Description
model	str	Selected model name.
difficulty	DifficultyScore	The difficulty assessment.
cost_estimate	CostEstimate	Estimated cost for this model.
reason	str	Human-readable explanation of why this model was chosen.
alternatives	list[str]	Other models that were considered.

pyagent_router.selector.Capability

Bases: StrEnum

Model capabilities for filtering.

pyagent_router.middleware.RouterMiddleware

Middleware that wraps agents with automatic model routing.

Usage

middleware = RouterMiddleware(model_registry={"gpt-4o": my_gpt4o, "gpt-4o-mini": my_mini}) routed_agent = middleware.wrap(my_agent)

routed_agent now auto-selects model per call

Parameters:

Name	Type	Description	Default
model_registry	dict[str, LLMCallable]	Mapping of model names to LLM callables.	required
selector	ModelSelector | None	Optional ModelSelector. Created with defaults if None.	None
required_capability	Capability | None	Optional default capability filter.	None

wrap(agent)

Wrap an agent with routing capabilities.

wrap_all(agents)

Wrap multiple agents.

pyagent_router.middleware.RoutedAgent

Bases: Agent

An agent wrapper that routes each call through ModelSelector.

The routing decision is recorded in metadata for tracing.

Parameters:

Name	Type	Description	Default
agent	Agent	The original agent.	required
selector	ModelSelector	ModelSelector to use for routing decisions.	required
model_registry	dict[str, LLMCallable]	Mapping of model names to LLM callables.	required
required_capability	Capability | None	Optional capability filter for model selection.	None

run(messages) async

Route the call to the optimal model, then execute.