cayu.budgets.aggregates

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.

`AggregateAccuracy`

from cayu.budgets import AggregateAccuracy

Truthfulness metadata for a bounded aggregate or one of its sections.

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
`kind`	`AggregateAccuracyKind`	`required`
`reason`	`str \| None`	`None`
`limit`	`StrictInt \| None`	`Field(default=None, ge=1)`

validate_reason (method)

AggregateAccuracy.validate_reason(value: str | None) -> str | None

validate_details (method)

AggregateAccuracy.validate_details() -> AggregateAccuracy

Release source · Runtime guarantees · Capability guides

`AggregateAccuracyKind`

from cayu.budgets import AggregateAccuracyKind

How completely an aggregate projection represents its requested scope.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`EXACT`	`class attribute`	`'exact'`
`SAMPLED`	`class attribute`	`'sampled'`
`TRUNCATED`	`class attribute`	`'truncated'`

Release source · Runtime guarantees · Capability guides

`estimate_usage_rollup_cost`

from cayu.budgets import estimate_usage_rollup_cost

Price an exact bounded input projection without reporting partial totals.

estimate_usage_rollup_cost(result: UsageRollupStoreResult, pricing, *, billing_group_limit: int=20) -> UsageCostRollup

Release source · Runtime guarantees · Capability guides

`estimate_usage_session_cost_breakdown`

from cayu.budgets import estimate_usage_session_cost_breakdown

Price retained session groups without publishing partial session costs.

estimate_usage_session_cost_breakdown(result: UsageRollupStoreResult, pricing) -> UsageSessionCostBreakdown

Release source · Runtime guarantees · Capability guides

`UsageAggregateBreakdown`

from cayu.budgets import UsageAggregateBreakdown

Deterministic top groups plus an exact remainder when detail is bounded.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`groups`	`tuple[UsageAggregateGroup, ...]`	`Field(max_length=100)`
`remainder`	`UsageAggregateRemainder \| None`	`required`
`accuracy`	`AggregateAccuracy`	`required`

copy_groups (method)

UsageAggregateBreakdown.copy_groups(value: object) -> object

copy_nested_contracts (method)

UsageAggregateBreakdown.copy_nested_contracts(value: object) -> object

validate_accuracy (method)

UsageAggregateBreakdown.validate_accuracy() -> UsageAggregateBreakdown

Release source · Runtime guarantees · Capability guides

`UsageAggregateGroup`

from cayu.budgets import UsageAggregateGroup

One provider/model grouping inside a bounded usage breakdown.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`provider_name`	`str \| None`	`required`
`model`	`str \| None`	`required`
`totals`	`UsageAggregateTotals`	`required`

copy_totals (method)

UsageAggregateGroup.copy_totals(value: object) -> object

validate_optional_identity (method)

UsageAggregateGroup.validate_optional_identity(value: str | None, info) -> str | None

Release source · Runtime guarantees · Capability guides

`UsageAggregateRemainder`

from cayu.budgets import UsageAggregateRemainder

Exact totals represented by groups omitted from a bounded breakdown.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`group_count`	`PositiveAggregateCount`	`Field(ge=1)`
`totals`	`UsageAggregateTotals`	`required`

copy_totals (method)

UsageAggregateRemainder.copy_totals(value: object) -> object

Release source · Runtime guarantees · Capability guides

`UsageAggregateTotals`

from cayu.budgets import UsageAggregateTotals

Identity-free activity and token totals for one aggregate scope.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`session_count`	`AggregateCount`	`Field(ge=0)`
`model_steps`	`AggregateCount`	`Field(ge=0)`
`model_steps_with_usage`	`AggregateCount`	`Field(ge=0)`
`tool_calls`	`AggregateCount`	`Field(ge=0)`
`usage`	`AggregateUsageMetrics`	`required`

copy_usage (method)

UsageAggregateTotals.copy_usage(value: object) -> object

validate_reported_steps (method)

UsageAggregateTotals.validate_reported_steps() -> UsageAggregateTotals

Release source · Runtime guarantees · Capability guides

`UsageBillingCostBreakdown`

from cayu.budgets import UsageBillingCostBreakdown

Bounded identity detail for evaluated cost inputs, with an exact remainder.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`identified_model_steps`	`AggregateCount`	`Field(ge=0)`
`identified_auxiliary_attempts`	`AggregateCount`	`Field(default=0, ge=0)`
`groups`	`tuple[UsageBillingCostGroup, ...]`	`Field(max_length=100)`
`remainder`	`UsageBillingCostRemainder \| None`	`required`
`accuracy`	`AggregateAccuracy`	`required`

copy_groups (method)

UsageBillingCostBreakdown.copy_groups(value: object) -> object

copy_nested_contracts (method)

UsageBillingCostBreakdown.copy_nested_contracts(value: object) -> object

validate_scope (method)

UsageBillingCostBreakdown.validate_scope() -> UsageBillingCostBreakdown

Release source · Runtime guarantees · Capability guides

`UsageBillingCostGroup`

from cayu.budgets import UsageBillingCostGroup

One bounded, identity-bearing group of equivalent pricing outcomes.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`billing_identity`	`UsageBillingIdentity`	`required`
`pricing_provider_name`	`str \| None`	`None`
`pricing_model`	`str \| None`	`None`
`priced`	`StrictBool`	`required`
`model_steps`	`AggregateCount`	`Field(ge=0)`
`auxiliary_attempts`	`AggregateCount`	`Field(default=0, ge=0)`
`currency`	`str \| None`	`None`
`total_cost`	`Decimal`	`Field(ge=0)`
`missing_pricing_reason`	`str \| None`	`None`

copy_billing_identity (method)

UsageBillingCostGroup.copy_billing_identity(value: object) -> object

validate_optional_text (method)

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

validate_outcome (method)

UsageBillingCostGroup.validate_outcome() -> UsageBillingCostGroup

Release source · Runtime guarantees · Capability guides

`UsageBillingCostRemainder`

from cayu.budgets import UsageBillingCostRemainder

Exact counts for identity-bearing pricing groups omitted from bounded detail.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`group_count`	`PositiveAggregateCount`	`Field(ge=1)`
`model_steps`	`AggregateCount`	`Field(ge=0)`
`auxiliary_attempts`	`AggregateCount`	`Field(default=0, ge=0)`
`priced_auxiliary_attempts`	`AggregateCount`	`Field(default=0, ge=0)`
`unpriced_auxiliary_attempts`	`AggregateCount`	`Field(default=0, ge=0)`
`priced_model_steps`	`AggregateCount`	`Field(ge=0)`
`unpriced_model_steps`	`AggregateCount`	`Field(ge=0)`

validate_step_accounting (method)

UsageBillingCostRemainder.validate_step_accounting() -> UsageBillingCostRemainder

Release source · Runtime guarantees · Capability guides

`UsageBillingIdentity`

from cayu.budgets import UsageBillingIdentity

Bounded commercial identity safe to return in an aggregate response.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`provider_name`	`str`	`required`
`resource_id`	`str`	`required`
`request_evidence`	`dict[str, str]`	`Field(default_factory=dict, max_length=4)`
`completion_evidence`	`dict[str, str]`	`Field(default_factory=dict, max_length=1)`

validate_identity (method)

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

copy_evidence (method)

UsageBillingIdentity.copy_evidence(value: dict[str, str], info) -> dict[str, str]

validate_display_contract (method)

UsageBillingIdentity.validate_display_contract() -> UsageBillingIdentity

Release source · Runtime guarantees · Capability guides

`UsageCostRollup`

from cayu.budgets import UsageCostRollup

Bounded cost result derived from grouped price-relevant inputs.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`price_book_version`	`str`	`required`
`price_book_generated_at`	`str`	`required`
`accuracy`	`AggregateAccuracy`	`required`
`evaluated_model_steps`	`AggregateCount`	`Field(ge=0)`
`evaluated_auxiliary_attempts`	`AggregateCount`	`Field(default=0, ge=0)`
`priced_auxiliary_attempts`	`AggregateCount`	`Field(default=0, ge=0)`
`unpriced_auxiliary_attempts`	`AggregateCount`	`Field(default=0, ge=0)`
`priced_model_steps`	`AggregateCount`	`Field(ge=0)`
`unpriced_model_steps`	`AggregateCount`	`Field(ge=0)`
`unevaluated_model_steps`	`AggregateCount`	`Field(ge=0)`
`currencies`	`tuple[UsageCurrencyCost, ...]`	`Field(max_length=5000)`
`unpriced_reasons`	`tuple[UsageUnpricedReason, ...]`	`Field(max_length=5000)`
`billing_breakdown`	`UsageBillingCostBreakdown`	`required`

copy_detail (method)

UsageCostRollup.copy_detail(value: object) -> object

copy_nested_contracts (method)

UsageCostRollup.copy_nested_contracts(value: object) -> object

validate_price_book_identity (method)

UsageCostRollup.validate_price_book_identity(value: str, info) -> str

validate_step_accounting (method)

UsageCostRollup.validate_step_accounting() -> UsageCostRollup

Release source · Runtime guarantees · Capability guides

`UsageCurrencyCost`

from cayu.budgets import UsageCurrencyCost

Exact estimated model-step and hosted-resource cost for one currency.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`currency`	`str`	`required`
`model_steps`	`AggregateCount`	`Field(ge=0)`
`auxiliary_attempts`	`AggregateCount`	`Field(default=0, ge=0)`
`hosted_resources`	`AggregateCount`	`Field(default=0, ge=0, exclude_if=lambda value: value == 0)`
`total_cost`	`Decimal`	`Field(ge=0)`

validate_currency (method)

UsageCurrencyCost.validate_currency(value: str) -> str

validate_evidence_count (method)

UsageCurrencyCost.validate_evidence_count() -> UsageCurrencyCost

Release source · Runtime guarantees · Capability guides

`UsagePricingInput`

from cayu.budgets import UsagePricingInput

One bounded group of identical, price-relevant event inputs.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`session_id`	`str \| None`	`Field(default=None, exclude_if=lambda value: value is None)`
`effective_on`	`date`	`required`
`occurrences`	`StrictInt`	`Field(ge=1)`
`event_type`	`UsagePricingEventType`	`'model.completed'`
`metrics`	`UsageMetrics \| None`	`None`

validate_session_id (method)

UsagePricingInput.validate_session_id(value: str | None) -> str | None

copy_metrics (method)

UsagePricingInput.copy_metrics(value: object) -> object

Release source · Runtime guarantees · Capability guides

`UsageRollupInconsistent`

from cayu.budgets import UsageRollupInconsistent

A store returned a usage projection that does not honor its query.

Bases: ValueError.

This type’s implementation and inherited behavior are available in the linked release source.

Release source · Runtime guarantees · Capability guides

`UsageRollupResultTooLarge`

from cayu.budgets import UsageRollupResultTooLarge

A usage projection cannot cross its bounded public contract safely.

Bases: ValueError.

This type’s implementation and inherited behavior are available in the linked release source.

Release source · Runtime guarantees · Capability guides

`UsageRollupStoreResult`

from cayu.budgets import UsageRollupStoreResult

Bounded store projection used to construct the public usage rollup.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`reported_costs`	`ReportedCostPage \| None`	`None`
`as_of`	`datetime`	`required`
`start_at`	`datetime`	`required`
`end_at`	`datetime`	`required`
`totals`	`UsageAggregateTotals`	`required`
`totals_accuracy`	`AggregateAccuracy`	`Field(default_factory=lambda: EXACT_AGGREGATE.model_copy())`
`provider_breakdown`	`UsageAggregateBreakdown`	`required`
`model_breakdown`	`UsageAggregateBreakdown`	`required`
`session_breakdown`	`UsageSessionAggregateBreakdown \| None`	`None`
`pricing_inputs`	`tuple[UsagePricingInput, ...]`	`Field(default=(), max_length=5000)`
`pricing_inputs_included`	`StrictBool`	`False`
`pricing_input_group_count`	`StrictInt`	`Field(default=0, ge=0, description='Exact canonical group count when pricing_inputs_accuracy is exact; the number observed before bounded collection stopped when truncated.')`
`pricing_inputs_accuracy`	`AggregateAccuracy`	`Field(default_factory=lambda: EXACT_AGGREGATE.model_copy())`
`session_pricing_inputs`	`tuple[UsagePricingInput, ...]`	`Field(default=(), max_length=5000)`
`session_pricing_inputs_included`	`StrictBool`	`False`
`session_pricing_input_group_count`	`StrictInt`	`Field(default=0, ge=0)`
`session_pricing_inputs_accuracy`	`AggregateAccuracy`	`Field(default_factory=lambda: EXACT_AGGREGATE.model_copy())`
`active_session_count`	`StrictInt`	`Field(default=0, ge=0)`
`matching_session_count`	`StrictInt`	`Field(default=0, ge=0)`
`includes_active_sessions`	`StrictBool`	`True`

copy_nested_contracts (method)

UsageRollupStoreResult.copy_nested_contracts(value: object) -> object

copy_pricing_inputs (method)

UsageRollupStoreResult.copy_pricing_inputs(value: object) -> object

normalize_timestamp (method)

UsageRollupStoreResult.normalize_timestamp(value: datetime, info) -> datetime

validate_scope (method)

UsageRollupStoreResult.validate_scope() -> UsageRollupStoreResult

validate_for_query (method)

UsageRollupStoreResult.validate_for_query(query: UsageRollupQuery) -> UsageRollupStoreResult

Return a bounded, canonically revalidated result for one query.

Release source · Runtime guarantees · Capability guides

`UsageSessionAggregateBreakdown`

from cayu.budgets import UsageSessionAggregateBreakdown

Deterministic session groups plus an exact aggregate remainder.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`groups`	`tuple[UsageSessionAggregateGroup, ...]`	`Field(max_length=100)`
`remainder`	`UsageSessionAggregateRemainder \| None`	`required`
`accuracy`	`AggregateAccuracy`	`required`

copy_groups (method)

UsageSessionAggregateBreakdown.copy_groups(value: object) -> object

copy_nested_contracts (method)

UsageSessionAggregateBreakdown.copy_nested_contracts(value: object) -> object

validate_breakdown (method)

UsageSessionAggregateBreakdown.validate_breakdown() -> UsageSessionAggregateBreakdown

Release source · Runtime guarantees · Capability guides

`UsageSessionAggregateGroup`

from cayu.budgets import UsageSessionAggregateGroup

Exact usage for one retained current session inside a bounded breakdown.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`session_id`	`str`	`required`
`status`	`UsageSessionStatus`	`required`
`active`	`StrictBool`	`required`
`totals`	`UsageAggregateTotals`	`required`

copy_totals (method)

UsageSessionAggregateGroup.copy_totals(value: object) -> object

validate_session_id (method)

UsageSessionAggregateGroup.validate_session_id(value: str) -> str

validate_active_state (method)

UsageSessionAggregateGroup.validate_active_state() -> UsageSessionAggregateGroup

Release source · Runtime guarantees · Capability guides

`UsageSessionAggregateRemainder`

from cayu.budgets import UsageSessionAggregateRemainder

Exact usage represented by current sessions omitted from bounded detail.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`group_count`	`PositiveAggregateCount`	`Field(ge=1)`
`active_session_count`	`AggregateCount`	`Field(ge=0)`
`totals`	`UsageAggregateTotals`	`required`

copy_totals (method)

UsageSessionAggregateRemainder.copy_totals(value: object) -> object

validate_counts (method)

UsageSessionAggregateRemainder.validate_counts() -> UsageSessionAggregateRemainder

Release source · Runtime guarantees · Capability guides

`UsageSessionCostBreakdown`

from cayu.budgets import UsageSessionCostBreakdown

Bounded per-session costs plus an aggregate remainder.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`price_book_version`	`str`	`required`
`price_book_generated_at`	`str`	`required`
`groups`	`tuple[UsageSessionCostGroup, ...]`	`Field(max_length=100)`
`remainder`	`UsageSessionCostRemainder \| None`	`required`
`accuracy`	`AggregateAccuracy`	`required`

copy_groups (method)

UsageSessionCostBreakdown.copy_groups(value: object) -> object

copy_nested_contracts (method)

UsageSessionCostBreakdown.copy_nested_contracts(value: object) -> object

validate_price_book_identity (method)

UsageSessionCostBreakdown.validate_price_book_identity(value: str, info) -> str

validate_breakdown (method)

UsageSessionCostBreakdown.validate_breakdown() -> UsageSessionCostBreakdown

Release source · Runtime guarantees · Capability guides

`UsageSessionCostGroup`

from cayu.budgets import UsageSessionCostGroup

Cost accounting for one retained session.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`session_id`	`str`	`required`
`cost`	`UsageSessionCostSummary`	`required`

copy_cost (method)

UsageSessionCostGroup.copy_cost(value: object) -> object

validate_session_id (method)

UsageSessionCostGroup.validate_session_id(value: str) -> str

Release source · Runtime guarantees · Capability guides

`UsageSessionCostRemainder`

from cayu.budgets import UsageSessionCostRemainder

Exact aggregate cost for sessions omitted from bounded detail.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`group_count`	`PositiveAggregateCount`	`Field(ge=1)`
`cost`	`UsageSessionCostSummary`	`required`

copy_cost (method)

UsageSessionCostRemainder.copy_cost(value: object) -> object

Release source · Runtime guarantees · Capability guides

`UsageSessionCostSummary`

from cayu.budgets import UsageSessionCostSummary

Cost accounting for one session group or the exact omitted remainder.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`accuracy`	`AggregateAccuracy`	`required`
`evaluated_model_steps`	`AggregateCount`	`Field(ge=0)`
`evaluated_auxiliary_attempts`	`AggregateCount`	`Field(default=0, ge=0)`
`priced_auxiliary_attempts`	`AggregateCount`	`Field(default=0, ge=0)`
`unpriced_auxiliary_attempts`	`AggregateCount`	`Field(default=0, ge=0)`
`priced_model_steps`	`AggregateCount`	`Field(ge=0)`
`unpriced_model_steps`	`AggregateCount`	`Field(ge=0)`
`unevaluated_model_steps`	`AggregateCount`	`Field(ge=0)`
`currencies`	`tuple[UsageCurrencyCost, ...]`	`Field(max_length=5000)`
`unpriced_reasons`	`tuple[UsageUnpricedReason, ...]`	`Field(max_length=5000)`

copy_detail (method)

UsageSessionCostSummary.copy_detail(value: object) -> object

copy_accuracy (method)

UsageSessionCostSummary.copy_accuracy(value: object) -> object

validate_step_accounting (method)

UsageSessionCostSummary.validate_step_accounting() -> UsageSessionCostSummary

Release source · Runtime guarantees · Capability guides

`UsageUnpricedReason`

from cayu.budgets import UsageUnpricedReason

Model-step and hosted-resource counts unpriced for one explicit reason.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`unpriced_reason`	`UnpricedReason \| None`	`None`
`reason`	`str`	`required`
`model_steps`	`AggregateCount`	`Field(ge=0)`
`auxiliary_attempts`	`AggregateCount`	`Field(default=0, ge=0)`
`hosted_resources`	`AggregateCount`	`Field(default=0, ge=0, exclude_if=lambda value: value == 0)`

validate_reason (method)

UsageUnpricedReason.validate_reason(value: str) -> str

validate_evidence_count (method)

UsageUnpricedReason.validate_evidence_count() -> UsageUnpricedReason

Release source · Runtime guarantees · Capability guides