Cost Tracking¶

Per-capability cost tracking and per-principal budget enforcement.

Auto-generated docs

When trails is installed, run ENABLE_MKDOCSTRINGS=true ./scripts/docs-build for full docstring-extracted reference.

CostTracker¶

Symbol	Signature	Description
`CostTracker`	`CostTracker()`	Python-side cost tracking with per-principal budget enforcement
`.track`	`.track(capability_id: str, tokens: int, usd: float, latency_ms: int, *, principal: str \\| None = None, call_id: str \\| None = None, parent_call_id: str \\| None = None) -> _CostEntry`	Record a cost observation for a capability invocation
`.records`	`.records() -> list[_CostEntry]`	Return all recorded entries (dedupe children included)
`.total_usd`	`.total_usd() -> float`	Sum of `usd` across non-child entries
`.total_tokens`	`.total_tokens() -> int`	Sum of `tokens` across non-child entries
`.get_total`	`.get_total() -> dict`	Aggregate totals (tokens, usd, latency, invocations) excluding dedupe children
`.get_by_capability`	`.get_by_capability() -> dict`	Per-capability breakdown of costs (non-child entries only)
`.set_budget`	`.set_budget(principal: str, usd: float, tokens: int) -> None`	Set (or replace) the budget for a principal
`.check_budget`	`.check_budget(principal: str) -> bool`	Return `True` if principal is within budget (`True` if no budget set)
`.record_spend`	`.record_spend(principal: str, usd: float, tokens: int) -> None`	Record spending against a principal's budget
`.get_budget`	`.get_budget(principal: str) -> dict \\| None`	Return the current budget state for a principal, or `None`

CostScope¶

Context manager that marks an outer cost envelope (ADR-0012a). While active, inner CostTracker.track calls inherit the scope's call_id as their parent, preventing double-counting in nested planner + capability + LLM envelopes.

Symbol	Signature	Description
`CostScope`	`CostScope(tracker: CostTracker, *, capability_id: str = "cost:scope", call_id: str \\| None = None)`	Create a cost scope bound to a tracker
`.call_id`	`str`	The scope's stable call identifier
`.capability_id`	`str`	The capability this scope is tracking