cost-tracking.md

Cost Tracking

pydantic-deep tracks token usage and USD costs automatically using CostTrackingMiddleware from pydantic-ai-middleware. Cost tracking is enabled by default.

!!! tip "Requires middleware" Cost tracking uses pydantic-ai-middleware with genai-prices for pricing data. Install with: bash pip install pydantic-deep[middleware]

Quick Start

from pydantic_deep import create_deep_agent

# Cost tracking is ON by default
agent = create_deep_agent()

# Disable cost tracking
agent = create_deep_agent(cost_tracking=False)

Budget Limits

Set a maximum cumulative cost. When exceeded, the next run raises BudgetExceededError:

agent = create_deep_agent(
    cost_budget_usd=5.00,  # $5 budget
)

Cost Update Callback

Monitor costs in real-time:

from pydantic_ai_middleware import CostInfo

def on_cost(info: CostInfo):
    print(f"Run cost: ${info.run_cost_usd:.4f}")
    print(f"Total: ${info.cumulative_cost_usd:.4f}")
    print(f"Tokens: {info.run_input_tokens} in / {info.run_output_tokens} out")

agent = create_deep_agent(
    on_cost_update=on_cost,
    cost_budget_usd=10.00,
)

Configuration

Parameter	Type	Default	Description
cost_tracking	bool	True	Enable automatic cost tracking
cost_budget_usd	float | None	None	Maximum cumulative cost in USD
on_cost_update	Callable | None	None	Callback after each run with CostInfo

CostInfo Fields

The CostInfo dataclass provides both per-run and cumulative metrics:

Field	Type	Description
run_input_tokens	int	Input tokens for this run
run_output_tokens	int	Output tokens for this run
run_cost_usd	float	USD cost for this run
cumulative_input_tokens	int	Total input tokens across all runs
cumulative_output_tokens	int	Total output tokens across all runs
cumulative_cost_usd	float	Total USD cost across all runs

How It Works

1. CostTrackingMiddleware wraps the agent via MiddlewareAgent
2. After each run, it reads result.usage() for token counts
3. Token costs are calculated using genai-prices (model-specific pricing)
4. CostInfo is passed to the on_cost_update callback
5. If cumulative_cost_usd exceeds cost_budget_usd, subsequent runs raise BudgetExceededError

Next Steps

• Middleware — Middleware system and permissions
• Context Manager — Token tracking and auto-compression
• Agents — Full agent configuration