cayu.budgets.base

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.

`BudgetAction`

from cayu.budgets import BudgetAction

BudgetAction = Literal['interrupt', 'notify']

Release source · Runtime guarantees · Capability guides

`BudgetBindingAllowanceExhausted`

from cayu.budgets import BudgetBindingAllowanceExhausted

A registered binding has no remaining dispatch allowance.

Bases: RuntimeError.

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

Release source · Runtime guarantees · Capability guides

`BudgetBindingRegistrationConflict`

from cayu.budgets import BudgetBindingRegistrationConflict

A binding id was already registered with different authority.

Bases: RuntimeError.

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

Release source · Runtime guarantees · Capability guides

`BudgetCheck`

from cayu.budgets import BudgetCheck

Result of evaluating one budget limit.

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
`budget_limit_id`	`str`	`required`
`scope`	`BudgetScope`	`required`
`key`	`str \| None`	`None`
`window`	`BudgetWindow`	`Field(default_factory=BudgetWindow.all_time)`
`currency`	`str`	`required`
`maximum`	`Decimal`	`Field(gt=0)`
`actual`	`Decimal`	`Field(ge=0)`
`action`	`BudgetAction`	`'interrupt'`
`model_steps`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`unpriced_model_steps`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`unpriced_auxiliary_attempts`	`StrictInt`	`Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`limit_reached`	`StrictBool`	`required`
`message`	`str`	`required`
`cost_summary`	`SessionCostTotals`	`required`

validate_key (method)

BudgetCheck.validate_key(value: str | None, info) -> str | None

validate_budget_limit_id (method)

BudgetCheck.validate_budget_limit_id(value: str) -> str

copy_window (method)

BudgetCheck.copy_window(value) -> BudgetWindow

validate_currency (method)

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

validate_decimal (method)

BudgetCheck.validate_decimal(value: Decimal, info) -> Decimal

copy_cost_summary (method)

BudgetCheck.copy_cost_summary(value: object) -> object

Release source · Runtime guarantees · Capability guides

`BudgetLedger`

from cayu.budgets import BudgetLedger

Atomic reservation ledger for strict budget enforcement.

Durable reservation lease decisions use time owned by the ledger. Callers supply durations and transition identities, never an authoritative current time or expiry cutoff. PostgreSQL implementations use database time in the mutation transaction; local implementations expose the same semantics via a store-owned injectable clock.

Bases: ABC.

reserve_batch (method)

async BudgetLedger.reserve_batch(*, members: tuple[BudgetBatchMember, ...], binding_id: str | None=None, binding_authority_digest: str | None=None, binding_allowance: int | None=None, binding_consumption_id: str | None=None) -> BudgetBatchResult

Reserve every ceiling atomically; unsupported ledger wrappers refuse.

Exact replay returns retained accounting evidence, never permission to redispatch. The runtime’s durable dispatch owner still grants execution.

register_budget_binding (method)

async BudgetLedger.register_budget_binding(*, binding_id: str, authority_digest: str, allowance: int) -> None

Durably claim a binding id for one exact trusted authority.

The ledger stores the exact authority digest and its bounded allowance; it never mints or resolves authority. Persistent backends override this with a transactional shared-store implementation. The default is the qualified in-process fallback.

durable_state_paths (method)

BudgetLedger.durable_state_paths() -> tuple[Path, ...]

Return local files that hold this ledger’s durable state.

claim_reservation_identity (method)

async BudgetLedger.claim_reservation_identity(*, reservation_id: str, publication_session_id: str, publication_id: str) -> None

Permanently bind one reservation id to its exact event publication.

The default protects all apps sharing this ledger instance in one process. Durable multi-worker ledgers must override this method and enforce the same idempotent claim in their shared storage.

reservation_ttl_seconds (property)

BudgetLedger.reservation_ttl_seconds() -> int | None

Active-reservation lease duration, or None for non-expiring ledgers.

Custom ledgers remain non-expiring by default. A ledger that advertises a finite TTL must also implement heartbeat so the runtime can keep live provider calls reserved.

heartbeat (method)

async BudgetLedger.heartbeat(*, reservation_id: str) -> bool

Renew one active reservation lease.

Return False when the reservation is terminal or its lease already expired. Unknown reservation ids raise KeyError. The default is intentionally unsupported because the base ledger advertises no TTL.

mark_dispatched (method)

async BudgetLedger.mark_dispatched(*, reservation_ids: tuple[str, ...], dispatch_id: str, dispatched_at: datetime | None=None) -> tuple[BudgetReservationRecord, ...]

Atomically fence one attempt’s reservations before provider code.

An identical retry is idempotent. Once this transition commits, TTL cleanup must retain every reservation because provider dispatch is no longer known not to have occurred. Implementations must update the complete set or none of it.

release_pre_provider_dispatch (method)

async BudgetLedger.release_pre_provider_dispatch(*, reservation_ids: tuple[str, ...], dispatch_id: str, reason: str, occurred_at: datetime | None=None) -> tuple[BudgetReconciliation, ...]

Atomically release one attempt proven not to have reached provider code.

Every reservation must either have no dispatch fence or carry the exact supplied dispatch identity. An identical retry is idempotent, while a conflicting dispatch or terminal outcome must fail the complete batch. This narrow transition is reserved for a runtime-owned provider barrier; ordinary callers must continue to use release, which rejects dispatch-fenced reservations.

reserve (method)

async BudgetLedger.reserve(*, reservation_id: str | None=None, limit: BudgetLimit, session_id: str, agent_name: str, provider_name: str, model: str, model_attempt_identity: ModelAttemptIdentity, environment_name: str | None=None, settlement_event_payload: dict[str, Any] | None=None, settlement_fallback: BudgetSettlementFallback | None=None, requested_amount: Decimal | None=None, billing_identity: BillingIdentity | None=None, effective_at: datetime | None=None) -> BudgetReservationResult

Reserve budget for one provider dispatch if capacity remains.

reservation_id lets the runtime validate durable authority before asking the ledger to mutate. Direct ledger callers may omit it and let the ledger allocate one. effective_at fixes the pricing instant selected by the runtime. Direct ledger callers may omit it to use the ledger’s current clock. settlement_fallback binds a publication-safe conservative outcome before provider dispatch. Direct callers may omit it when no workload secret publication policy applies. requested_amount lets the runtime supply the amount priced from transient request evidence before billing_identity is normalized for durable storage. Direct callers normally omit it and let the ledger price from billing_identity. Implementations must reject a generated reservation_id that is already owned by another record before mutating the existing record.

reconcile (method)

async BudgetLedger.reconcile(*, reservation_id: str, actual_amount: Decimal, settlement_kind: Literal['completed', 'conservative']='completed', reason: str | None=None, occurred_at: datetime | None=None, billing_identity: BillingIdentity | None=None, pricing: BudgetReconciliationPricing | None=None) -> BudgetReconciliation

Replace a reservation with the charged amount.

Implementations must return the existing result for an identical retry without changing its accounting timestamp, and reject a conflicting terminal outcome for the same reservation.

release (method)

async BudgetLedger.release(*, reservation_id: str, reason: str, occurred_at: datetime | None=None) -> BudgetReconciliation

Release an active reservation without charging it.

Implementations must return the existing result for an identical retry and reject a conflicting terminal outcome for the same reservation. A reservation with a committed dispatch fence is not releasable.

load_reservation (method)

async BudgetLedger.load_reservation(reservation_id: str) -> BudgetReservationRecord | None

Load one durable reservation for provider-operation reconstruction.

Custom ledgers that do not implement this optional recovery seam remain usable for synchronous provider calls, but cannot resume a budgeted provider-owned operation after worker loss.

load_settlement (method)

async BudgetLedger.load_settlement(settlement_id: str) -> BudgetSettlementRecord | None

Load one exact durable terminal transition by stable identity.

list_pending_settlements (method)

async BudgetLedger.list_pending_settlements(*, session_id: str | None=None, after: BudgetSettlementCursor | None=None, limit: int=100) -> list[BudgetSettlementRecord]

Return a bounded deterministic page of unpublished audit events.

Omitting session_id returns a ledger-wide page so a reservation in one session can publish releases created while another session reaps its expired capacity. after advances through unavailable publication domains without acknowledging or starving their pending records.

mark_settlement_event_published (method)

async BudgetLedger.mark_settlement_event_published(*, settlement_id: str, event_id: str) -> BudgetSettlementRecord

Acknowledge that the settlement’s exact audit event is durable.

Release source · Runtime guarantees · Capability guides

`BudgetLimit`

from cayu.budgets import BudgetLimit

Estimated-cost budget that applies across one durable runtime scope.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`scope`	`BudgetScope`	`'session'`
`max_estimated_cost`	`Decimal`	`Field(gt=0)`
`pricing`	`PriceBook`	`required`
`currency`	`str`	`'USD'`
`window`	`BudgetWindow`	`Field(default_factory=BudgetWindow.all_time)`
`key`	`str \| None`	`None`
`allow_unpriced`	`StrictBool`	`False`
`reservation`	`BudgetReservation \| None`	`None`
`action`	`BudgetAction`	`'interrupt'`

validate_currency (method)

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

validate_key (method)

BudgetLimit.validate_key(value: str | None, info) -> str | None

copy_window (method)

BudgetLimit.copy_window(value) -> BudgetWindow

copy_pricing (method)

BudgetLimit.copy_pricing(value: object) -> object

validate_cost (method)

BudgetLimit.validate_cost(value: Decimal, info) -> Decimal

validate_scope_key (method)

BudgetLimit.validate_scope_key() -> BudgetLimit

copy_reservation (method)

BudgetLimit.copy_reservation(value: BudgetReservation | None) -> BudgetReservation | None

Release source · Runtime guarantees · Capability guides

`BudgetPolicy`

from cayu.budgets import BudgetPolicy

App-level budget policy applied automatically by the runtime.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`limits`	`tuple[BudgetLimit, ...]`	`Field(default_factory=tuple)`

copy_limits (method)

BudgetPolicy.copy_limits(value: Iterable[BudgetLimit | Mapping[str, Any]] | None) -> tuple[BudgetLimit, ...]

validate_policy_scopes (method)

BudgetPolicy.validate_policy_scopes() -> BudgetPolicy

Release source · Runtime guarantees · Capability guides

`BudgetReconciliation`

from cayu.budgets import BudgetReconciliation

Result of reconciling a reservation after the model step completes.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`reservation_id`	`str`	`required`
`settlement_id`	`str`	`required`
`settlement_kind`	`BudgetSettlementKind`	`required`
`budget_limit_id`	`str`	`required`
`model_step_id`	`str`	`required`
`model_attempt_id`	`str`	`required`
`execution_profile_fingerprint`	`str \| None`	`None`
`status`	`BudgetReservationStatus`	`required`
`reserved_amount`	`Decimal`	`Field(ge=0)`
`actual_amount`	`Decimal \| None`	`Field(default=None, ge=0)`
`released_amount`	`Decimal`	`Field(ge=0)`
`reason`	`str \| None`	`None`
`settled_at`	`datetime`	`required`
`billing_identity`	`BillingIdentity \| None`	`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`	`Field(default=None, gt=0, le=MAX_DURABLE_JSON_INTEGER)`

copy_nested_contracts (method)

BudgetReconciliation.copy_nested_contracts(value: object) -> object

validate_reconciliation_id (method)

BudgetReconciliation.validate_reconciliation_id(value: str, info) -> str

validate_budget_limit_id (method)

BudgetReconciliation.validate_budget_limit_id(value: str) -> str

validate_execution_profile_fingerprint (method)

BudgetReconciliation.validate_execution_profile_fingerprint(value: str | None) -> str | None

validate_reconciliation_reason (method)

BudgetReconciliation.validate_reconciliation_reason(value: str | None, info) -> str | None

validate_pricing_evidence (method)

BudgetReconciliation.validate_pricing_evidence() -> BudgetReconciliation

validate_settled_at (method)

BudgetReconciliation.validate_settled_at(value: datetime) -> datetime

validate_reconciliation_decimal (method)

BudgetReconciliation.validate_reconciliation_decimal(value: Decimal | None, info) -> Decimal | None

Release source · Runtime guarantees · Capability guides

`BudgetReconciliationPricing`

from cayu.budgets import BudgetReconciliationPricing

Bounded pricing provenance committed with one budget settlement.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`provider_name`	`str`	`required`
`model`	`str`	`required`
`match`	`Literal['exact', 'prefix', 'resource_mapping']`	`required`
`provenance`	`Provenance`	`required`
`effective_from`	`date \| None`	`None`
`effective_through`	`date \| None`	`None`
`tier_max_input_tokens`	`StrictInt \| None`	`Field(default=None, gt=0, le=MAX_DURABLE_JSON_INTEGER)`
`billing_identity`	`BillingIdentity \| None`	`Field(default=None, exclude=True)`

copy_nested_contracts (method)

BudgetReconciliationPricing.copy_nested_contracts(value: object) -> object

validate_strings (method)

BudgetReconciliationPricing.validate_strings(value: str, info) -> str

validate_effective_window (method)

BudgetReconciliationPricing.validate_effective_window() -> BudgetReconciliationPricing

Release source · Runtime guarantees · Capability guides

`BudgetReservation`

from cayu.budgets import BudgetReservation

Conservative per-model-step reservation configured by the app.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`max_input_tokens`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`max_output_tokens`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`max_cache_read_input_tokens`	`StrictInt`	`Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`max_cache_write_input_tokens`	`StrictInt`	`Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)`

validate_nonzero_reservation (method)

BudgetReservation.validate_nonzero_reservation() -> BudgetReservation

Release source · Runtime guarantees · Capability guides

`BudgetReservationRecord`

from cayu.budgets import BudgetReservationRecord

One reserved budget amount for a model step.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`reservation_id`	`str`	`Field(default_factory=lambda: f'bres_{uuid4().hex}')`
`budget_limit_id`	`str`	`required`
`model_step_id`	`str`	`required`
`model_attempt_id`	`str`	`required`
`scope`	`BudgetScope`	`required`
`key`	`str \| None`	`None`
`window`	`BudgetWindow`	`Field(default_factory=BudgetWindow.all_time)`
`currency`	`str`	`required`
`session_id`	`str`	`required`
`agent_name`	`str`	`required`
`environment_name`	`str \| None`	`None`
`provider_name`	`str`	`required`
`model`	`str`	`required`
`billing_identity`	`BillingIdentity \| None`	`None`
`settlement_event_payload`	`dict[str, Any]`	`Field(default_factory=dict)`
`settlement_fallback`	`BudgetSettlementFallback`	`Field(default_factory=BudgetSettlementFallback)`
`dispatch_id`	`str \| None`	`None`
`dispatched_at`	`datetime \| None`	`None`
`reserved_amount`	`Decimal`	`Field(ge=0)`
`actual_amount`	`Decimal \| None`	`Field(default=None, ge=0)`
`status`	`BudgetReservationStatus`	`'active'`
`reason`	`str \| None`	`None`
`created_at`	`datetime`	`Field(default_factory=lambda: datetime.now(UTC))`
`updated_at`	`datetime`	`Field(default_factory=lambda: datetime.now(UTC))`

validate_nonblank_strings (method)

BudgetReservationRecord.validate_nonblank_strings(value: str, info) -> str

validate_optional_strings (method)

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

copy_settlement_event_payload (method)

BudgetReservationRecord.copy_settlement_event_payload(value: dict[str, Any]) -> dict[str, Any]

copy_settlement_fallback (method)

BudgetReservationRecord.copy_settlement_fallback(value: BudgetSettlementFallback | Mapping[str, Any]) -> BudgetSettlementFallback

copy_window (method)

BudgetReservationRecord.copy_window(value) -> BudgetWindow

validate_record_currency (method)

BudgetReservationRecord.validate_record_currency(value: str, info) -> str

validate_record_decimal (method)

BudgetReservationRecord.validate_record_decimal(value: Decimal | None, info) -> Decimal | None

validate_record_timestamp (method)

BudgetReservationRecord.validate_record_timestamp(value: datetime | None, info) -> datetime | None

validate_model_attempt_identity (method)

BudgetReservationRecord.validate_model_attempt_identity() -> BudgetReservationRecord

Release source · Runtime guarantees · Capability guides

`BudgetReservationResult`

from cayu.budgets import BudgetReservationResult

Result of attempting to reserve budget before a model step.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`accepted`	`StrictBool`	`required`
`budget_limit_id`	`str`	`required`
`model_step_id`	`str`	`required`
`model_attempt_id`	`str`	`required`
`scope`	`BudgetScope`	`required`
`key`	`str \| None`	`None`
`window`	`BudgetWindow`	`Field(default_factory=BudgetWindow.all_time)`
`currency`	`str`	`required`
`maximum`	`Decimal`	`Field(gt=0)`
`action`	`BudgetAction`	`required`
`requested`	`Decimal`	`Field(ge=0)`
`actual`	`Decimal`	`Field(ge=0)`
`message`	`str`	`required`
`record`	`BudgetReservationRecord \| None`	`None`

validate_result_key (method)

BudgetReservationResult.validate_result_key(value: str | None, info) -> str | None

validate_budget_limit_id (method)

BudgetReservationResult.validate_budget_limit_id(value: str) -> str

copy_window (method)

BudgetReservationResult.copy_window(value) -> BudgetWindow

validate_result_strings (method)

BudgetReservationResult.validate_result_strings(value: str, info) -> str

validate_result_decimal (method)

BudgetReservationResult.validate_result_decimal(value: Decimal, info) -> Decimal

validate_model_attempt_identity (method)

BudgetReservationResult.validate_model_attempt_identity() -> BudgetReservationResult

Release source · Runtime guarantees · Capability guides

`BudgetReservationStatus`

from cayu.budgets import BudgetReservationStatus

BudgetReservationStatus = Literal['active', 'reconciled', 'released']

Release source · Runtime guarantees · Capability guides

`BudgetScope`

from cayu.budgets import BudgetScope

BudgetScope = Literal['app', 'agent', 'causal', 'session', 'run']

Release source · Runtime guarantees · Capability guides

`BudgetSettlementCursor`

from cayu.budgets import BudgetSettlementCursor

Stable keyset position in the ledger settlement outbox.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`settled_at`	`datetime`	`required`
`settlement_id`	`str`	`required`

validate_settled_at (method)

BudgetSettlementCursor.validate_settled_at(value: datetime) -> datetime

validate_settlement_id (method)

BudgetSettlementCursor.validate_settlement_id(value: str) -> str

Release source · Runtime guarantees · Capability guides

`BudgetSettlementFallback`

from cayu.budgets import BudgetSettlementFallback

Pre-dispatch authority for a publishable conservative terminal outcome.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`settled_at`	`datetime`	`Field(default_factory=lambda: datetime.now(UTC))`
`reconciliation_reason`	`str`	`PUBLICATION_FALLBACK_BUDGET_REASON`
`release_reason`	`str`	`'reservation released before provider dispatch'`
`expiration_reason`	`str \| None`	`None`

validate_settled_at (method)

BudgetSettlementFallback.validate_settled_at(value: datetime) -> datetime

validate_required_reason (method)

BudgetSettlementFallback.validate_required_reason(value: str, info) -> str

validate_expiration_reason (method)

BudgetSettlementFallback.validate_expiration_reason(value: str | None) -> str | None

Release source · Runtime guarantees · Capability guides

`BudgetSettlementKind`

from cayu.budgets import BudgetSettlementKind

BudgetSettlementKind = Literal['completed', 'conservative', 'released']

Release source · Runtime guarantees · Capability guides

`BudgetSettlementRecord`

from cayu.budgets import BudgetSettlementRecord

One ledger-committed terminal transition and its durable audit event.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`settlement_id`	`str`	`required`
`reservation_id`	`str`	`required`
`settlement_kind`	`BudgetSettlementKind`	`required`
`session_id`	`str`	`required`
`agent_name`	`str`	`required`
`environment_name`	`str \| None`	`None`
`reconciliation`	`BudgetReconciliation`	`required`
`event`	`Event`	`required`
`event_published`	`StrictBool`	`False`

copy_reconciliation (method)

BudgetSettlementRecord.copy_reconciliation(value: object) -> object

copy_audit_event (method)

BudgetSettlementRecord.copy_audit_event(value: object) -> object

validate_required_text (method)

BudgetSettlementRecord.validate_required_text(value: str, info) -> str

validate_optional_text (method)

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

validate_event_binding (method)

BudgetSettlementRecord.validate_event_binding() -> BudgetSettlementRecord

Release source · Runtime guarantees · Capability guides

`BudgetStore`

from cayu.budgets import BudgetStore

Durable source for cross-session budget accounting.

Bases: ABC.

append_event (method)

async BudgetStore.append_event(event: Event) -> None

Observe one cost-bearing event, idempotently by session and event id.

Runtime delivery is at-least-once across crashes. Implementations must return without adding a second charge when the same immutable event is retried, and reject a conflicting event with the same identity.

load_events_for_budget (method)

async BudgetStore.load_events_for_budget(*, scope: BudgetScope, key: str | None, window: BudgetWindow) -> list[Event]

Return events that contribute to the given budget scope.

read_cost_for_budget (method)

async BudgetStore.read_cost_for_budget(*, scope: BudgetScope, key: str | None, window: BudgetWindow, pricing: PriceBook, currency: str='USD', now: datetime | None=None, additional_events: tuple[Event, ...]=(), previous: CostAccountingSnapshot | None=None) -> CostAccountingSnapshot

Read exact budget totals with bounded memory; unsupported stores fail closed.

Release source · Runtime guarantees · Capability guides

`BudgetWindow`

from cayu.budgets import BudgetWindow

Time window used when selecting events for budget accounting.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`kind`	`BudgetWindowKind`	`'all_time'`
`duration_seconds`	`StrictInt \| None`	`Field(default=None, ge=1, le=MAX_DURABLE_JSON_INTEGER)`
`period`	`BudgetCalendarPeriod \| None`	`None`
`timezone`	`str \| None`	`None`

all_time (method)

BudgetWindow.all_time() -> BudgetWindow

rolling (method)

BudgetWindow.rolling(*, seconds: int) -> BudgetWindow

calendar (method)

BudgetWindow.calendar(*, period: BudgetCalendarPeriod, timezone: str='UTC') -> BudgetWindow

validate_timezone (method)

BudgetWindow.validate_timezone(value: str | None, info) -> str | None

validate_window_fields (method)

BudgetWindow.validate_window_fields() -> BudgetWindow

storage_key (property)

BudgetWindow.storage_key() -> str

since (method)

BudgetWindow.since(now: datetime | None=None) -> datetime | None

until (method)

BudgetWindow.until(now: datetime | None=None) -> datetime | None

bounds (method)

BudgetWindow.bounds(now: datetime | None=None) -> tuple[datetime | None, datetime | None]

Release source · Runtime guarantees · Capability guides

`InMemoryBudgetLedger`

from cayu.budgets import InMemoryBudgetLedger

In-memory reservation ledger for single-process apps and tests.

Bases: BudgetLedger.

reserve_batch (method)

async InMemoryBudgetLedger.reserve_batch(*, members: tuple[BudgetBatchMember, ...], binding_id: str | None=None, binding_authority_digest: str | None=None, binding_allowance: int | None=None, binding_consumption_id: str | None=None) -> BudgetBatchResult

register_budget_binding (method)

async InMemoryBudgetLedger.register_budget_binding(*, binding_id: str, authority_digest: str, allowance: int) -> None

Durably claim a binding id for one exact trusted authority.

durable_state_paths (method)

InMemoryBudgetLedger.durable_state_paths() -> tuple[Path, ...]

Return local files that hold this ledger’s durable state.

claim_reservation_identity (method)

async InMemoryBudgetLedger.claim_reservation_identity(*, reservation_id: str, publication_session_id: str, publication_id: str) -> None

Permanently bind one reservation id to its exact event publication.

The default protects all apps sharing this ledger instance in one process. Durable multi-worker ledgers must override this method and enforce the same idempotent claim in their shared storage.

reservation_ttl_seconds (property)

InMemoryBudgetLedger.reservation_ttl_seconds() -> int | None

heartbeat (method)

async InMemoryBudgetLedger.heartbeat(*, reservation_id: str) -> bool

mark_dispatched (method)

async InMemoryBudgetLedger.mark_dispatched(*, reservation_ids: tuple[str, ...], dispatch_id: str, dispatched_at: datetime | None=None) -> tuple[BudgetReservationRecord, ...]

release_pre_provider_dispatch (method)

async InMemoryBudgetLedger.release_pre_provider_dispatch(*, reservation_ids: tuple[str, ...], dispatch_id: str, reason: str, occurred_at: datetime | None=None) -> tuple[BudgetReconciliation, ...]

reserve (method)

async InMemoryBudgetLedger.reserve(*, reservation_id: str | None=None, limit: BudgetLimit, session_id: str, agent_name: str, provider_name: str, model: str, model_attempt_identity: ModelAttemptIdentity, environment_name: str | None=None, settlement_event_payload: dict[str, Any] | None=None, settlement_fallback: BudgetSettlementFallback | None=None, requested_amount: Decimal | None=None, billing_identity: BillingIdentity | None=None, effective_at: datetime | None=None) -> BudgetReservationResult

reconcile (method)

async InMemoryBudgetLedger.reconcile(*, reservation_id: str, actual_amount: Decimal, settlement_kind: Literal['completed', 'conservative']='completed', reason: str | None=None, occurred_at: datetime | None=None, billing_identity: BillingIdentity | None=None, pricing: BudgetReconciliationPricing | None=None) -> BudgetReconciliation

release (method)

async InMemoryBudgetLedger.release(*, reservation_id: str, reason: str, occurred_at: datetime | None=None) -> BudgetReconciliation

load_reservation (method)

async InMemoryBudgetLedger.load_reservation(reservation_id: str) -> BudgetReservationRecord | None

load_settlement (method)

async InMemoryBudgetLedger.load_settlement(settlement_id: str) -> BudgetSettlementRecord | None

list_pending_settlements (method)

async InMemoryBudgetLedger.list_pending_settlements(*, session_id: str | None=None, after: BudgetSettlementCursor | None=None, limit: int=100) -> list[BudgetSettlementRecord]

mark_settlement_event_published (method)

async InMemoryBudgetLedger.mark_settlement_event_published(*, settlement_id: str, event_id: str) -> BudgetSettlementRecord

init (method)

InMemoryBudgetLedger.__init__(*, clock: Callable[[], datetime] | None=None, reservation_ttl_seconds: int | None=DEFAULT_RESERVATION_TTL_SECONDS) -> None

Release source · Runtime guarantees · Capability guides

`InMemoryBudgetStore`

from cayu.budgets import InMemoryBudgetStore

In-memory budget store for tests and local apps.

Bases: BudgetStore.

append_event (method)

async InMemoryBudgetStore.append_event(event: Event) -> None

load_events_for_budget (method)

async InMemoryBudgetStore.load_events_for_budget(*, scope: BudgetScope, key: str | None, window: BudgetWindow) -> list[Event]

read_cost_for_budget (method)

async InMemoryBudgetStore.read_cost_for_budget(*, scope: BudgetScope, key: str | None, window: BudgetWindow, pricing: PriceBook, currency: str='USD', now: datetime | None=None, additional_events: tuple[Event, ...]=(), previous: CostAccountingSnapshot | None=None) -> CostAccountingSnapshot

init (method)

InMemoryBudgetStore.__init__() -> None

Release source · Runtime guarantees · Capability guides

`SessionBudgetInspection`

from cayu import SessionBudgetInspection

Availability of durable budget and price-ledger evidence.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`event_count`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`reservation_count`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`reconciliation_count`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`pending_reservation_count`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`completed_unsettled_reservation_count`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`reconciled_reservation_count`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`conservative_reconciliation_count`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`released_reservation_count`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`cost_state`	`Literal['unknown', 'unpriced', 'partial', 'mixed_currency', 'priced']`	`required`
`amount`	`str \| None`	`None`
`currency`	`str \| None`	`None`

Release source · Runtime guarantees · Capability guides

`SessionBudgetStore`

from cayu.budgets import SessionBudgetStore

Budget store backed by the existing durable session event stream.

Bases: BudgetStore.

append_event (method)

async SessionBudgetStore.append_event(event: Event) -> None

load_events_for_budget (method)

async SessionBudgetStore.load_events_for_budget(*, scope: BudgetScope, key: str | None, window: BudgetWindow) -> list[Event]

read_cost_for_budget (method)

async SessionBudgetStore.read_cost_for_budget(*, scope: BudgetScope, key: str | None, window: BudgetWindow, pricing: PriceBook, currency: str='USD', now: datetime | None=None, additional_events: tuple[Event, ...]=(), previous: CostAccountingSnapshot | None=None) -> CostAccountingSnapshot

init (method)

SessionBudgetStore.__init__(session_store: Any) -> None

Release source · Runtime guarantees · Capability guides