Skip to content

cayu.budgets.usage

Public Cayu API. Definitions are grouped by their public source module, and definitions from private implementation modules appear on their package’s page; adding a symbol does not move existing links. The import shown at each entry is a supported public namespace. Read the Python API overview and install the required extra.

AggregateCacheUsageMetrics

Section titled “AggregateCacheUsageMetrics”
from cayu.budgets import AggregateCacheUsageMetrics

Lossless JSON projection of identity-free aggregate cache counters.

Bases: BaseModel.

Fields and attributes

Section titled “Fields and attributes”

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name Type Default
read_tokens AggregateCount Field(ge=0)
write_tokens AggregateCount Field(ge=0)
write_5m_tokens AggregateCount Field(ge=0)
write_1h_tokens AggregateCount Field(ge=0)
write_unknown_ttl_tokens AggregateCount Field(ge=0)
cached_input_tokens AggregateCount Field(ge=0)
uncached_input_tokens AggregateCount Field(ge=0)

Release source · Runtime guarantees · Capability guides

AggregateHostedToolUsageMetrics

Section titled “AggregateHostedToolUsageMetrics”
from cayu.budgets import AggregateHostedToolUsageMetrics

Lossless aggregate provider-hosted resource counters.

Bases: BaseModel.

Fields and attributes

Section titled “Fields and attributes”

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name Type Default
web_search_calls AggregateCount Field(default=0, ge=0)
web_search_outcome_unknown AggregateCount Field(default=0, ge=0)

Release source · Runtime guarantees · Capability guides

AggregateUsageMetrics

Section titled “AggregateUsageMetrics”
from cayu.budgets import AggregateUsageMetrics

Lossless JSON projection of identity-free aggregate token counters.

Bases: BaseModel.

Fields and attributes

Section titled “Fields and attributes”

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name Type Default
input_tokens AggregateCount Field(ge=0)
output_tokens AggregateCount Field(ge=0)
total_tokens AggregateCount Field(ge=0)
reasoning_output_tokens AggregateCount Field(ge=0)
cache AggregateCacheUsageMetrics required
hosted_tools AggregateHostedToolUsageMetrics Field(default_factory=AggregateHostedToolUsageMetrics, exclude_if=lambda value: value.web_search_calls == 0 and value.web_search_outcome_unknown == 0)

copy_cache (method)

Section titled “copy_cache (method)”
AggregateUsageMetrics.copy_cache(value: object) -> object

Release source · Runtime guarantees · Capability guides

CacheUsageMetrics

Section titled “CacheUsageMetrics”
from cayu.budgets import CacheUsageMetrics

Provider-neutral cache token counters for one model step.

Bases: BaseModel.

Fields and attributes

Section titled “Fields and attributes”

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name Type Default
read_tokens StrictInt Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)
write_tokens StrictInt Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)
write_5m_tokens StrictInt Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER, exclude_if=lambda value: value == 0)
write_1h_tokens StrictInt Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER, exclude_if=lambda value: value == 0)
write_unknown_ttl_tokens StrictInt Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER, exclude_if=lambda value: value == 0)
cached_input_tokens StrictInt Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)
uncached_input_tokens StrictInt Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)

Release source · Runtime guarantees · Capability guides

causal_budget_usage_summary

Section titled “causal_budget_usage_summary”
from cayu.budgets import causal_budget_usage_summary
causal_budget_usage_summary(*, causal_budget_id: str, session_ids: list[str], events: list[Event]) -> CausalBudgetUsageSummary

Release source · Runtime guarantees · Capability guides

CausalBudgetUsageSummary

Section titled “CausalBudgetUsageSummary”
from cayu.budgets import CausalBudgetUsageSummary

Usage totals for all sessions sharing one causal budget id.

Bases: BaseModel.

Fields and attributes

Section titled “Fields and attributes”

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name Type Default
causal_budget_id str required
session_ids list[str] Field(default_factory=list)
session_count StrictInt Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)
model_steps StrictInt Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)
unmeasured_model_attempts StrictInt Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)
tool_calls StrictInt Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)
provider_names list[str] Field(default_factory=list)
models list[str] Field(default_factory=list)
usage AggregateUsageMetrics Field(default_factory=build_aggregate_usage_metrics)
session_summaries tuple[SessionUsageSummary, ...] Field(default_factory=tuple)

project_step_usage (method)

Section titled “project_step_usage (method)”
CausalBudgetUsageSummary.project_step_usage(value: object) -> object

copy_session_summaries (method)

Section titled “copy_session_summaries (method)”
CausalBudgetUsageSummary.copy_session_summaries(value: object) -> object

validate_causal_budget_id (method)

Section titled “validate_causal_budget_id (method)”
CausalBudgetUsageSummary.validate_causal_budget_id(value: str, info) -> str

copy_string_lists (method)

Section titled “copy_string_lists (method)”
CausalBudgetUsageSummary.copy_string_lists(value: list[str], info) -> list[str]

Release source · Runtime guarantees · Capability guides

HostedToolUsageMetrics

Section titled “HostedToolUsageMetrics”
from cayu.budgets import HostedToolUsageMetrics

Provider-neutral hosted-resource counters for one model attempt.

Bases: BaseModel.

Fields and attributes

Section titled “Fields and attributes”

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name Type Default
web_search_calls StrictInt Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)
web_search_outcome_unknown StrictInt Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)

Release source · Runtime guarantees · Capability guides

normalize_usage_metrics

Section titled “normalize_usage_metrics”
from cayu.budgets import normalize_usage_metrics

Normalize provider usage, returning None for malformed or oversized counters.

normalize_usage_metrics(*, provider_name: str | None, model: str | None, raw_usage: Any, usage_dialect: str | None=None, requested_model: str | None=None, billing_identity: BillingIdentity | None=None) -> UsageMetrics | None

Release source · Runtime guarantees · Capability guides

session_usage_summary

Section titled “session_usage_summary”
from cayu.budgets import session_usage_summary
session_usage_summary(session_id: str, events: list[Event]) -> SessionUsageSummary

Release source · Runtime guarantees · Capability guides

SessionUsageSummary

Section titled “SessionUsageSummary”
from cayu.budgets import SessionUsageSummary

Usage totals derived from durable session events.

Bases: BaseModel.

Fields and attributes

Section titled “Fields and attributes”

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name Type Default
session_id str required
model_steps StrictInt Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)
unmeasured_model_attempts StrictInt Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)
tool_calls StrictInt Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)
provider_names list[str] Field(default_factory=list)
models list[str] Field(default_factory=list)
usage AggregateUsageMetrics Field(default_factory=build_aggregate_usage_metrics)

project_step_usage (method)

Section titled “project_step_usage (method)”
SessionUsageSummary.project_step_usage(value: object) -> object

validate_session_id (method)

Section titled “validate_session_id (method)”
SessionUsageSummary.validate_session_id(value: str, info) -> str

copy_string_lists (method)

Section titled “copy_string_lists (method)”
SessionUsageSummary.copy_string_lists(value: list[str], info) -> list[str]

Release source · Runtime guarantees · Capability guides

usage_metrics_from_event_payload

Section titled “usage_metrics_from_event_payload”
from cayu.budgets import usage_metrics_from_event_payload
usage_metrics_from_event_payload(payload: dict[str, Any]) -> UsageMetrics | None

Release source · Runtime guarantees · Capability guides

UsageMetrics

Section titled “UsageMetrics”
from cayu.budgets import UsageMetrics

Provider-neutral token counters for one model step.

Bases: BaseModel.

Fields and attributes

Section titled “Fields and attributes”

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name Type Default
provider_name str | None None
requested_model str | None None
model str | None None
billing_identity BillingIdentity | None Field(default=None, exclude_if=lambda value: value is None)
input_tokens StrictInt Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)
output_tokens StrictInt Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)
total_tokens StrictInt Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)
reasoning_output_tokens StrictInt Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)
cache CacheUsageMetrics Field(default_factory=CacheUsageMetrics)
hosted_tools HostedToolUsageMetrics Field(default_factory=HostedToolUsageMetrics, exclude_if=lambda value: value.web_search_calls == 0 and value.web_search_outcome_unknown == 0)

validate_optional_nonblank (method)

Section titled “validate_optional_nonblank (method)”
UsageMetrics.validate_optional_nonblank(value: str | None, info) -> str | None

copy_nested_contracts (method)

Section titled “copy_nested_contracts (method)”
UsageMetrics.copy_nested_contracts(value: object) -> object

Release source · Runtime guarantees · Capability guides