cayu.budgets.pricing

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.

`CausalBudgetCostSummary`

from cayu.budgets import CausalBudgetCostSummary

Estimated cost for all sessions sharing one causal budget id.

Bases: BaseModel.

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)`
`currency`	`str`	`required`
`model_steps`	`StrictInt`	`Field(ge=0)`
`priced_model_steps`	`StrictInt`	`Field(ge=0)`
`unpriced_model_steps`	`StrictInt`	`Field(ge=0)`
`auxiliary_attempts`	`StrictInt`	`Field(default=0, ge=0)`
`unpriced_auxiliary_attempts`	`StrictInt`	`Field(default=0, ge=0)`
`missing_usage_model_steps`	`StrictInt`	`Field(default=0, ge=0)`
`missing_pricing_model_steps`	`StrictInt`	`Field(default=0, ge=0)`
`unsupported_pricing_model_steps`	`StrictInt`	`Field(default=0, ge=0)`
`total_cost`	`Decimal`	`Field(ge=0)`
`line_items`	`tuple[CostLineItem, ...]`	`Field(default_factory=tuple)`
`session_costs`	`tuple[SessionCostSummary, ...]`	`Field(default_factory=tuple)`

copy_nested_contracts (method)

CausalBudgetCostSummary.copy_nested_contracts(value: object) -> object

validate_identity (method)

CausalBudgetCostSummary.validate_identity(value: str, info) -> str

copy_session_ids (method)

CausalBudgetCostSummary.copy_session_ids(value: list[str], info) -> list[str]

Release source · Runtime guarantees · Capability guides

`ContextualPricingRequirement`

from cayu.budgets import ContextualPricingRequirement

Commercial constraints every contextual price for one provider must declare.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`provider_name`	`str`	`required`
`dimensions`	`tuple[str, ...]`	`required`
`requires_cache_write_ttls`	`StrictBool`	`False`

validate_provider_name (method)

ContextualPricingRequirement.validate_provider_name(value: str, info) -> str

validate_requirement_dimensions (method)

ContextualPricingRequirement.validate_requirement_dimensions(value: tuple[str, ...], info) -> tuple[str, ...]

Release source · Runtime guarantees · Capability guides

`copy_price_book`

from cayu.budgets import copy_price_book

copy_price_book(price_book: PriceBook) -> PriceBook

Release source · Runtime guarantees · Capability guides

`CostLineItem`

from cayu.budgets import CostLineItem

Estimated cost for one model attempt or standalone hosted resource evidence.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`model_step`	`StrictInt`	`Field(ge=0)`
`auxiliary_attempt`	`StrictBool`	`False`
`execution_profile_fingerprint`	`str \| None`	`Field(default=None, max_length=64, exclude_if=lambda value: value is None)`
`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)`
`pricing_provider_name`	`str \| None`	`None`
`pricing_model`	`str \| None`	`None`
`pricing_match`	`Literal['exact', 'prefix', 'resource_mapping'] \| None`	`None`
`pricing_provenance`	`Provenance \| None`	`None`
`pricing_effective_from`	`date \| None`	`None`
`pricing_effective_through`	`date \| None`	`None`
`pricing_tier_max_input_tokens`	`StrictInt \| None`	`None`
`priced`	`StrictBool`	`required`
`currency`	`str`	`required`
`input_tokens`	`StrictInt`	`Field(ge=0)`
`output_tokens`	`StrictInt`	`Field(ge=0)`
`cache_read_input_tokens`	`StrictInt`	`Field(ge=0)`
`cache_write_input_tokens`	`StrictInt`	`Field(ge=0)`
`cache_write_5m_input_tokens`	`StrictInt`	`Field(default=0, ge=0, exclude_if=lambda value: value == 0)`
`cache_write_1h_input_tokens`	`StrictInt`	`Field(default=0, ge=0, exclude_if=lambda value: value == 0)`
`cache_write_unknown_ttl_input_tokens`	`StrictInt`	`Field(default=0, ge=0, exclude_if=lambda value: value == 0)`
`web_search_calls`	`StrictInt`	`Field(default=0, ge=0)`
`web_search_outcome_unknown`	`StrictInt`	`Field(default=0, ge=0)`
`uncached_input_tokens`	`StrictInt`	`Field(ge=0)`
`input_cost`	`Decimal`	`Field(ge=0)`
`output_cost`	`Decimal`	`Field(ge=0)`
`cache_read_input_cost`	`Decimal`	`Field(ge=0)`
`cache_write_input_cost`	`Decimal`	`Field(ge=0)`
`web_search_cost`	`Decimal`	`Field(default=Decimal('0'), ge=0)`
`total_cost`	`Decimal`	`Field(ge=0)`
`unpriced_reason`	`UnpricedReason \| None`	`None`
`missing_pricing_reason`	`str \| None`	`None`

copy_nested_contracts (method)

CostLineItem.copy_nested_contracts(value: object) -> object

validate_optional_strings (method)

CostLineItem.validate_optional_strings(value: str | None, info) -> str | None

Release source · Runtime guarantees · Capability guides

`default_model_catalog`

from cayu.budgets import default_model_catalog

Load Cayu’s bundled, dated model-catalog snapshot.

The resource is parsed and validated on every call so callers never share mutable ModelCatalog state. Loading is deterministic and performs no network access.

default_model_catalog() -> ModelCatalog

Release source · Runtime guarantees · Capability guides

`default_price_book`

from cayu.budgets import default_price_book

Load Cayu’s bundled, dated price book without network access.

default_price_book() -> PriceBook

Release source · Runtime guarantees · Capability guides

`dump_model_catalog`

from cayu.budgets import dump_model_catalog

Deterministic JSON: models sorted by (provider_name, model), sorted keys, trailing newline — stable enough to commit and diff.

dump_model_catalog(catalog: ModelCatalog) -> str

Release source · Runtime guarantees · Capability guides

`dump_price_book`

from cayu.budgets import dump_price_book

Serialize a price book deterministically for review and packaging.

dump_price_book(price_book: PriceBook) -> str

Release source · Runtime guarantees · Capability guides

`estimate_causal_budget_cost`

from cayu.budgets import estimate_causal_budget_cost

estimate_causal_budget_cost(*, causal_budget_id: str, session_ids: list[str], events: list[Event], pricing: PriceBook, currency: str='USD') -> CausalBudgetCostSummary

Release source · Runtime guarantees · Capability guides

`estimate_model_step_cost`

from cayu.budgets import estimate_model_step_cost

Estimate one normalized model step in its price-book-native currency.

estimate_model_step_cost(*, metrics: UsageMetrics, pricing: PriceBook, effective_on: date) -> ModelStepCostEstimate

Release source · Runtime guarantees · Capability guides

`estimate_session_cost`

from cayu.budgets import estimate_session_cost

estimate_session_cost(*, session_id: str, events: list[Event], pricing: PriceBook, currency: str='USD') -> SessionCostSummary

Release source · Runtime guarantees · Capability guides

`load_model_catalog`

from cayu.budgets import load_model_catalog

Load a catalog from a JSON file written by dump_model_catalog.

load_model_catalog(path: str | Path) -> ModelCatalog

Release source · Runtime guarantees · Capability guides

`load_price_book`

from cayu.budgets import load_price_book

Load a price book from a JSON file written by dump_price_book.

load_price_book(path: str | Path) -> PriceBook

Release source · Runtime guarantees · Capability guides

`ModelCatalog`

from cayu.budgets import ModelCatalog

A versioned metadata registry used for model discovery and routing.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`catalog_version`	`str`	`required`
`generated_at`	`str`	`required`
`models`	`tuple[ModelInfo, ...]`	`Field(min_length=1)`

validate_identity (method)

ModelCatalog.validate_identity(value: str, info) -> str

validate_unique_models (method)

ModelCatalog.validate_unique_models() -> ModelCatalog

resolve (method)

ModelCatalog.resolve(*, provider_name: str | None, model: str | None) -> ModelInfo | None

The most-specific metadata record whose declared identity matches the model.

match (method)

ModelCatalog.match(*, provider_name: str, model: str) -> ModelInfo | None

Exact (provider_name, model) record lookup (see resolve for declared prefix matching).

route (method)

ModelCatalog.route(*, provider_name: str | None=None, min_context: int=0, needs_vision: bool=False, needs_tools: bool=False, include_deprecated: bool=False) -> list[ModelInfo]

Non-deprecated models (by default) matching the capability filters.

Release source · Runtime guarantees · Capability guides

`ModelInfo`

from cayu.budgets import ModelInfo

A model’s identity, objective capabilities, lifecycle, and provenance.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`provider_name`	`str`	`required`
`model`	`str`	`required`
`family`	`str \| None`	`None`
`aliases`	`tuple[str, ...]`	`()`
`context_window`	`StrictInt \| None`	`Field(default=None, gt=0)`
`max_output_tokens`	`StrictInt \| None`	`Field(default=None, gt=0)`
`modalities_in`	`tuple[str, ...]`	`('text',)`
`modalities_out`	`tuple[str, ...]`	`('text',)`
`tool_calling`	`StrictBool`	`False`
`reasoning`	`StrictBool`	`False`
`structured_output`	`StrictBool`	`False`
`prompt_caching`	`StrictBool`	`False`
`hosted_web_search`	`StrictBool`	`False`
`release_date`	`date \| None`	`None`
`knowledge_cutoff`	`date \| None`	`None`
`deprecated`	`StrictBool`	`False`
`retirement_date`	`date \| None`	`None`
`match`	`Literal['exact', 'prefix']`	`'prefix'`
`match_prefixes`	`tuple[str, ...]`	`()`
`provenance`	`Provenance`	`required`

validate_identity (method)

ModelInfo.validate_identity(value: str, info) -> str

validate_optional_family (method)

ModelInfo.validate_optional_family(value: str | None, info) -> str | None

validate_string_members (method)

ModelInfo.validate_string_members(value: tuple[str, ...], info) -> tuple[str, ...]

Release source · Runtime guarantees · Capability guides

`ModelPrice`

from cayu.budgets import ModelPrice

Pricing identity and its non-overlapping effective schedules.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`provider_name`	`str`	`required`
`model`	`str`	`required`
`aliases`	`tuple[str, ...]`	`()`
`match`	`Literal['exact', 'prefix']`	`'prefix'`
`match_prefixes`	`tuple[str, ...]`	`()`
`pricing_context`	`PricingContextSelector \| None`	`None`
`cache_write_ttls`	`tuple[Literal['5m', '1h'], ...]`	`()`
`schedules`	`tuple[PriceSchedule, ...]`	`Field(min_length=1)`

fixed (method)

ModelPrice.fixed(*, provider_name: str, model: str, input_per_million: Decimal, output_per_million: Decimal, cache_read_input_per_million: Decimal | None=None, cache_write_input_per_million: Decimal | None=None, web_search_per_thousand: Decimal | None=None, currency: str='USD', aliases: tuple[str, ...]=(), match: Literal['exact', 'prefix']='prefix', match_prefixes: tuple[str, ...]=(), pricing_context: PricingContextSelector | Mapping[str, tuple[str, ...]] | None=None, cache_write_ttls: tuple[Literal['5m', '1h'], ...]=(), provenance: Provenance | None=None) -> ModelPrice

Build one application-owned price with no validity bound.

Use explicit PriceSchedule values when a rate has a known start or end.

validate_identity (method)

ModelPrice.validate_identity(value: str, info) -> str

validate_string_members (method)

ModelPrice.validate_string_members(value: tuple[str, ...], info) -> tuple[str, ...]

validate_schedules (method)

ModelPrice.validate_schedules() -> ModelPrice

schedule_on (method)

ModelPrice.schedule_on(effective_on: date) -> PriceSchedule | None

Release source · Runtime guarantees · Capability guides

`ModelStepCostEstimate`

from cayu.budgets import ModelStepCostEstimate

Currency-local cost outcome for one normalized model step.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`priced`	`StrictBool`	`required`
`currency`	`str \| None`	`None`
`total_cost`	`Decimal`	`Field(ge=0)`
`unpriced_reason`	`UnpricedReason \| None`	`None`
`missing_pricing_reason`	`str \| None`	`None`
`pricing_provider_name`	`str \| None`	`None`
`pricing_model`	`str \| None`	`None`

validate_optional_text (method)

ModelStepCostEstimate.validate_optional_text(value: str | None, info) -> str | None

validate_outcome (method)

ModelStepCostEstimate.validate_outcome() -> ModelStepCostEstimate

Release source · Runtime guarantees · Capability guides

`PriceBook`

from cayu.budgets import PriceBook

A versioned collection of application-owned commercial model prices.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`price_book_version`	`str`	`'application'`
`generated_at`	`str`	`'unspecified'`
`prices`	`tuple[ModelPrice, ...]`	`Field(min_length=1)`
`contextual_pricing_requirements`	`tuple[ContextualPricingRequirement, ...]`	`()`
`resource_mappings`	`tuple[PricingResourceMapping, ...]`	`()`

validate_identity (method)

PriceBook.validate_identity(value: str, info) -> str

validate_unique_matches (method)

PriceBook.validate_unique_matches() -> PriceBook

Release source · Runtime guarantees · Capability guides

`PriceSchedule`

from cayu.budgets import PriceSchedule

One price schedule, effective on inclusive UTC calendar dates.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`effective_from`	`date \| None`	`None`
`effective_through`	`date \| None`	`None`
`pricing`	`TieredPricing`	`required`
`provenance`	`Provenance`	`required`

validate_window (method)

PriceSchedule.validate_window() -> PriceSchedule

applies_on (method)

PriceSchedule.applies_on(effective_on: date) -> bool

Release source · Runtime guarantees · Capability guides

`PriceTier`

from cayu.budgets import PriceTier

One context band of tiered pricing.

Tiers are ordered ascending by max_input_tokens; the final tier may use None to mean “and above”.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`max_input_tokens`	`StrictInt \| None`	`Field(default=None, gt=0)`
`input_per_million`	`Decimal`	`Field(ge=0)`
`output_per_million`	`Decimal`	`Field(ge=0)`
`cache_read_input_per_million`	`Decimal \| None`	`Field(default=None, ge=0)`
`cache_write_input_per_million`	`Decimal \| None`	`Field(default=None, ge=0, exclude_if=lambda value: value is None)`

validate_decimal (method)

PriceTier.validate_decimal(value: Decimal | None, info) -> Decimal | None

Release source · Runtime guarantees · Capability guides

`PricingContextSelector`

from cayu.budgets import PricingContextSelector

Exact pricing dimensions accepted by one contextual price row.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`dimensions`	`Mapping[str, tuple[str, ...]]`	`required`

validate_dimensions (method)

PricingContextSelector.validate_dimensions(value: Any) -> dict[str, tuple[str, ...]]

freeze_dimensions (method)

PricingContextSelector.freeze_dimensions(value: Mapping[str, tuple[str, ...]]) -> Mapping[str, tuple[str, ...]]

serialize_dimensions (method)

PricingContextSelector.serialize_dimensions(value: Mapping[str, tuple[str, ...]]) -> dict[str, list[str]]

storage_key (method)

PricingContextSelector.storage_key() -> tuple[tuple[str, tuple[str, ...]], ...]

matches (method)

PricingContextSelector.matches(context: PricingContext) -> bool

Release source · Runtime guarantees · Capability guides

`PricingResourceMapping`

from cayu.budgets import PricingResourceMapping

Map one opaque provider resource to an explicit pricing model.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`provider_name`	`str`	`required`
`resource_id`	`str`	`required`
`pricing_model`	`str`	`required`

validate_mapping_identity (method)

PricingResourceMapping.validate_mapping_identity(value: str, info) -> str

Release source · Runtime guarantees · Capability guides

`Provenance`

from cayu.budgets import Provenance

Where model or pricing facts came from and when they were checked.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`source`	`str`	`required`
`url`	`str`	`required`
`as_of`	`str`	`required`

validate_identity (method)

Provenance.validate_identity(value: str, info) -> str

Release source · Runtime guarantees · Capability guides

`SessionCostSummary`

from cayu.budgets import SessionCostSummary

Detailed cost inspection, retaining one line item per completed step.

Bases: SessionCostTotals.

Fields and attributes

Name	Type	Default
`session_id`	`str`	`required`
`currency`	`str`	`required`
`model_steps`	`StrictInt`	`Field(ge=0)`
`priced_model_steps`	`StrictInt`	`Field(ge=0)`
`unpriced_model_steps`	`StrictInt`	`Field(ge=0)`
`auxiliary_attempts`	`StrictInt`	`Field(default=0, ge=0)`
`unpriced_auxiliary_attempts`	`StrictInt`	`Field(default=0, ge=0)`
`missing_usage_model_steps`	`StrictInt`	`Field(default=0, ge=0)`
`missing_pricing_model_steps`	`StrictInt`	`Field(default=0, ge=0)`
`unsupported_pricing_model_steps`	`StrictInt`	`Field(default=0, ge=0)`
`total_cost`	`Decimal`	`Field(ge=0)`
`line_items`	`tuple[CostLineItem, ...]`	`Field(default_factory=tuple)`

validate_identity (method)

SessionCostSummary.validate_identity(value: str, info) -> str

validate_step_totals (method)

SessionCostSummary.validate_step_totals() -> SessionCostTotals

copy_line_items (method)

SessionCostSummary.copy_line_items(value: object) -> object

validate_step_accounting (method)

SessionCostSummary.validate_step_accounting() -> SessionCostSummary

Release source · Runtime guarantees · Capability guides

`SessionCostTotals`

from cayu.budgets import SessionCostTotals

Exact cost counters for routine enforcement, without historical line items.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`session_id`	`str`	`required`
`currency`	`str`	`required`
`model_steps`	`StrictInt`	`Field(ge=0)`
`priced_model_steps`	`StrictInt`	`Field(ge=0)`
`unpriced_model_steps`	`StrictInt`	`Field(ge=0)`
`auxiliary_attempts`	`StrictInt`	`Field(default=0, ge=0)`
`unpriced_auxiliary_attempts`	`StrictInt`	`Field(default=0, ge=0)`
`missing_usage_model_steps`	`StrictInt`	`Field(default=0, ge=0)`
`missing_pricing_model_steps`	`StrictInt`	`Field(default=0, ge=0)`
`unsupported_pricing_model_steps`	`StrictInt`	`Field(default=0, ge=0)`
`total_cost`	`Decimal`	`Field(ge=0)`

validate_identity (method)

SessionCostTotals.validate_identity(value: str, info) -> str

validate_step_totals (method)

SessionCostTotals.validate_step_totals() -> SessionCostTotals

Release source · Runtime guarantees · Capability guides

`TieredPricing`

from cayu.budgets import TieredPricing

Full pricing for one model: context-band tiers plus optional batch and cache-write-duration rates.

Only the context-band standard tiers feed the cost engine today. A tier-local cache-write rate takes precedence over the model-wide cache_write_5m_per_million fallback. batch is carried for completeness and future use. Contextual pricing applies cache_write_1h_per_million only to usage explicitly attributed to a one-hour cache write.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`currency`	`str`	`'USD'`
`standard`	`tuple[PriceTier, ...]`	`Field(min_length=1)`
`batch`	`PriceTier \| None`	`None`
`cache_write_5m_per_million`	`Decimal \| None`	`Field(default=None, ge=0)`
`cache_write_1h_per_million`	`Decimal \| None`	`Field(default=None, ge=0)`
`web_search_per_thousand`	`Decimal \| None`	`Field(default=None, ge=0, exclude_if=lambda value: value is None)`

validate_currency (method)

TieredPricing.validate_currency(value: str, info) -> str

validate_decimal (method)

TieredPricing.validate_decimal(value: Decimal | None, info) -> Decimal | None

validate_tier_order (method)

TieredPricing.validate_tier_order() -> TieredPricing

base (method)

TieredPricing.base() -> PriceTier

The smallest-context (first) tier — the base price.

tier_for (method)

TieredPricing.tier_for(input_tokens: int) -> PriceTier

The tier whose band contains input_tokens (the open-ended tier, or the largest bounded tier if none is open-ended and the count overflows).

Release source · Runtime guarantees · Capability guides