cayu.context.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.

`CheckpointCompactionContextPolicy`

from cayu.context import CheckpointCompactionContextPolicy

Checkpoint-backed context policy for long-running sessions.

It keeps the durable transcript intact, stores a compact summary in the session checkpoint, and sends system messages + summary + recent turns to the model. In size-based mode, reserved_summary_tokens optionally leaves growth headroom beyond the existing summary when selecting recent context. It is not a cap on generated summaries: the actual projection must still pass the original size checks. Zero preserves the previous selection behavior. max_compaction_passes bounds automatic continuation of partially covered prefixes in size-based mode. It does not retry failed provider calls or expand the selected source range; explicit compaction remains one pass. enforce_recent_context_target=False makes the retained-size target best-effort. The estimated window trigger (including output reservation) remains a strict bound after size-triggered compaction; no evidence is dropped to meet the target. The default retains strict target enforcement.

Bases: RuntimeManagedContextPolicy.

execution_profile_identity (property)

CheckpointCompactionContextPolicy.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Optional application-versioned identity for opaque policy behavior.

build (method)

async CheckpointCompactionContextPolicy.build(request: ContextRequest) -> list[Message]

build_with_checkpoint (method)

async CheckpointCompactionContextPolicy.build_with_checkpoint(request: ContextRequest, *, checkpoint: dict[str, Any] | None) -> ContextBuildResult

init (method)

CheckpointCompactionContextPolicy.__init__(*, compactor: ContextCompactor | None=None, max_user_turns: int=10, compact_after_messages: int=40, compact_after_estimated_context_tokens: int | None=None, max_recent_context_tokens: int | None=None, reserved_output_tokens: int=0, reserved_summary_tokens: int=0, enforce_recent_context_target: bool=True, max_compaction_passes: int=8, summary_prefix: str=_DEFAULT_CHECKPOINT_COMPACTION_SUMMARY_PREFIX, max_attachment_results: int=1) -> None

Release source · Runtime guarantees · Capability guides

`CompactionPrompt`

from cayu.context import CompactionPrompt

A custom compaction prompt with explicit source coverage.

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
`prompt`	`str`	`required`
`covered_message_count`	`StrictInt`	`Field(ge=1, le=MAX_DURABLE_JSON_INTEGER)`

validate_prompt (method)

CompactionPrompt.validate_prompt(value: str) -> str

Release source · Runtime guarantees · Capability guides

`CompactionRequest`

from cayu.context import CompactionRequest

Input passed to a compactor when older context needs summarizing.

messages is only the newly compactable transcript delta. context_messages is the current full provider-facing projection for compatibility with custom compactors. cache_prefix_request is the exact runtime request shape available to cache-aware compactors.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`session`	`Session`	`required`
`agent`	`AgentSpec`	`required`
`messages`	`list[Message]`	`required`
`existing_summary`	`str \| None`	`None`
`metadata`	`dict[str, Any]`	`Field(default_factory=dict)`
`context_messages`	`list[Message]`	`Field(default_factory=list)`
`cache_prefix_request`	`ModelRequest \| None`	`None`
`force_bounded_compaction`	`StrictBool`	`False`
`instructions`	`str \| None`	`Field(default=None, max_length=COMPACTION_INSTRUCTIONS_MAX_CHARS)`

copy_messages (method)

CompactionRequest.copy_messages(value)

copy_session_contract (method)

CompactionRequest.copy_session_contract(value: Session) -> Session

copy_agent_contract (method)

CompactionRequest.copy_agent_contract(value: AgentSpec) -> AgentSpec

copy_context_messages (method)

CompactionRequest.copy_context_messages(value)

copy_cache_prefix_request (method)

CompactionRequest.copy_cache_prefix_request(value: ModelRequest | None) -> ModelRequest | None

copy_metadata (method)

CompactionRequest.copy_metadata(value: dict[str, Any]) -> dict[str, Any]

validate_optional_summary (method)

CompactionRequest.validate_optional_summary(value: str | None) -> str | None

validate_optional_instructions (method)

CompactionRequest.validate_optional_instructions(value: str | None) -> str | None

Release source · Runtime guarantees · Capability guides

`CompactionResult`

from cayu.context import CompactionResult

Compacted representation of older model-facing context.

covered_message_count declares the contiguous new-source prefix represented by summary. When a request carries existing_summary, a positive-coverage result must bind that exact prior representation through represented_existing_summary_sha256. A zero-coverage result must return the existing summary unchanged. source_chunk_count and source_chunk_mode describe the bounded source work used to produce the result; they never substitute for either explicit coverage claim.

model_completed_payloads carries one event-ready model.completed payload per provider call the compactor made, so the runtime can account for summarization spend in usage, cost, budget, and run-limit tracking. Runtime-created payloads may temporarily carry compaction_attempt_id; wrapping compactors must preserve it so Cayu can correlate recovered calls. Cayu removes the correlation field before emitting public events.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`summary`	`str`	`required`
`covered_message_count`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`represented_existing_summary_sha256`	`str \| None`	`None`
`source_chunk_count`	`StrictInt`	`Field(default=1, ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`source_chunk_mode`	`str`	`'single_request'`
`bounded_input`	`StrictBool`	`False`
`progress_exhausted`	`StrictBool`	`False`
`progress_key`	`str \| None`	`None`
`metadata`	`dict[str, Any]`	`Field(default_factory=dict)`
`model_completed_payloads`	`list[dict[str, Any]]`	`Field(default_factory=list)`

validate_summary (method)

CompactionResult.validate_summary(value: str) -> str

validate_represented_existing_summary_sha256 (method)

CompactionResult.validate_represented_existing_summary_sha256(value: str | None) -> str | None

validate_source_chunk_mode (method)

CompactionResult.validate_source_chunk_mode(value: str) -> str

validate_progress_key (method)

CompactionResult.validate_progress_key(value: str | None) -> str | None

validate_progress_exhaustion (method)

CompactionResult.validate_progress_exhaustion() -> CompactionResult

copy_metadata (method)

CompactionResult.copy_metadata(value: dict[str, Any]) -> dict[str, Any]

copy_model_completed_payloads (method)

CompactionResult.copy_model_completed_payloads(value: list[dict[str, Any]]) -> list[dict[str, Any]]

Release source · Runtime guarantees · Capability guides

`context_input_coverage`

from cayu.context import context_input_coverage

Capture a content-free identity for one actual model-input projection.

context_input_coverage(messages: list[Message], *, transcript_cursor: int) -> ContextInputCoverage

Release source · Runtime guarantees · Capability guides

`ContextCompactor`

from cayu.context import ContextCompactor

Summarizes older context into durable checkpoint data.

Bases: ABC.

execution_profile_identity (property)

ContextCompactor.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Optional application-versioned identity for opaque compaction behavior.

provider_budget_identity (method)

ContextCompactor.provider_budget_identity(session: Session) -> tuple[str, str] | None

Declare the provider/model charged by one compaction invocation.

Return None only for a compactor that never performs provider work. This identity supplies pricing attribution; it does not declare how many provider calls an opaque compactor may make. Automatic compaction under run or cost limits therefore also requires Cayu’s built-in per-dispatch instrumentation.

compact (method)

async ContextCompactor.compact(request: CompactionRequest) -> CompactionResult

Return a compact summary for older transcript messages.

Release source · Runtime guarantees · Capability guides

`ContextInputCoverage`

from cayu.context import ContextInputCoverage

The transcript boundary and exact message prefix measured by provider usage.

Message count is separate from the absolute transcript cursor because retention and context projection can change the number of messages sent to the provider.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`transcript_cursor`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`message_count`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`messages_sha256`	`str`	`Field(pattern='^[0-9a-f]{64}$')`

Release source · Runtime guarantees · Capability guides

`ContextPolicy`

from cayu.context import ContextPolicy

Builds the model-facing context for a runtime step.

Policies may trim, summarize, replace tool results, or inject retrieved context. They must not be used as durable transcript storage.

Bases: ABC.

execution_profile_identity (property)

ContextPolicy.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Optional application-versioned identity for opaque policy behavior.

build (method)

async ContextPolicy.build(request: ContextRequest) -> list[Message]

Return provider-neutral messages for one model request.

Release source · Runtime guarantees · Capability guides

`ContextPressureEstimate`

from cayu.context import ContextPressureEstimate

Estimated current context pressure.

This is a local pressure signal, not provider-authoritative token counting and not billing data. Estimates may use previous actual usage plus a transcript delta or a full local estimate of the model-facing request shape.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`method`	`str`	`'observed_plus_estimated_delta'`
`confidence`	`str`	`'estimated'`
`observed_context_input_tokens`	`StrictInt`	`Field(ge=0)`
`estimated_delta_input_tokens`	`StrictInt`	`Field(ge=0)`
`estimated_message_input_tokens`	`StrictInt`	`Field(ge=0)`
`estimated_tool_schema_input_tokens`	`StrictInt`	`Field(ge=0)`
`estimated_structured_output_input_tokens`	`StrictInt`	`Field(ge=0)`
`estimated_request_options_input_tokens`	`StrictInt`	`Field(ge=0)`
`estimated_request_overhead_input_tokens`	`StrictInt`	`Field(default=0, ge=0)`
`previous_request_overhead_input_tokens`	`StrictInt \| None`	`Field(default=None, ge=0)`
`estimated_request_overhead_delta_tokens`	`StrictInt`	`0`
`estimated_attachment_input_tokens`	`StrictInt`	`Field(ge=0)`
`estimated_context_input_tokens`	`StrictInt`	`Field(ge=0)`
`reserved_output_tokens`	`StrictInt`	`Field(default=0, ge=0)`
`estimated_context_window_tokens`	`StrictInt`	`Field(ge=0)`
`provider_count_input_tokens`	`StrictInt \| None`	`Field(default=None, ge=0)`
`provider_count_context_window_tokens`	`StrictInt \| None`	`Field(default=None, ge=0)`
`anchor_transcript_cursor`	`StrictInt`	`Field(ge=0)`
`current_transcript_cursor`	`StrictInt`	`Field(ge=0)`
`estimated_message_count`	`StrictInt`	`Field(ge=0)`
`chars_per_token`	`StrictInt`	`Field(ge=1)`
`json_chars_per_token`	`StrictInt`	`Field(ge=1)`
`binary_bytes_per_token`	`StrictInt`	`Field(ge=1)`

validate_nonblank (method)

ContextPressureEstimate.validate_nonblank(value: str, info) -> str

Release source · Runtime guarantees · Capability guides

`ContextPressureOverhead`

from cayu.context import ContextPressureOverhead

Known provider-request overhead included in local context pressure estimates.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`tools`	`list[dict[str, Any]]`	`Field(default_factory=list)`
`structured_output_instruction`	`str \| None`	`None`
`request_options`	`dict[str, Any]`	`Field(default_factory=dict)`
`image_min_tokens`	`StrictInt`	`Field(default=_DEFAULT_ESTIMATE_IMAGE_MIN_TOKENS, ge=0)`
`document_min_tokens`	`StrictInt`	`Field(default=_DEFAULT_ESTIMATE_DOCUMENT_MIN_TOKENS, ge=0)`
`document_bytes_per_token`	`StrictInt`	`Field(default=_DEFAULT_ESTIMATE_BINARY_BYTES_PER_TOKEN, ge=1)`
`tool_schema_chars_per_token`	`StrictInt`	`Field(default=_DEFAULT_ESTIMATE_TOOL_SCHEMA_CHARS_PER_TOKEN, ge=1)`

copy_json_data (method)

ContextPressureOverhead.copy_json_data(value, info)

validate_optional_instruction (method)

ContextPressureOverhead.validate_optional_instruction(value: str | None) -> str | None

Release source · Runtime guarantees · Capability guides

`ContextRecallTelemetry`

from cayu.context import ContextRecallTelemetry

Automatic recall telemetry that the runtime converts into events.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`event_type`	`EventType`	`required`
`payload`	`dict[str, Any]`	`Field(default_factory=dict)`

validate_context_event_type (method)

ContextRecallTelemetry.validate_context_event_type(value: EventType) -> EventType

copy_payload (method)

ContextRecallTelemetry.copy_payload(value: dict[str, Any]) -> dict[str, Any]

Release source · Runtime guarantees · Capability guides

`ContextRequest`

from cayu.context import ContextRequest

Input passed to an agent context policy before each model request.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`session`	`Session`	`required`
`agent`	`AgentSpec`	`required`
`messages`	`list[Message]`	`required`
`step`	`StrictInt`	`Field(ge=1)`
`interaction_id`	`str \| None`	`Field(default=None, exclude=True)`
`model_step_id`	`str \| None`	`Field(default=None, exclude=True)`
`environment_name`	`str \| None`	`None`
`session_store`	`Any`	`Field(default=None, exclude=True)`
`knowledge_store`	`Any`	`Field(default=None, exclude=True)`
`knowledge_access_scope`	`Any`	`Field(default=None, exclude=True)`
`metadata`	`dict[str, Any]`	`Field(default_factory=dict)`
`context_usage`	`ContextUsageState`	`Field(default_factory=ContextUsageState)`
`pressure_overhead`	`ContextPressureOverhead`	`Field(default_factory=ContextPressureOverhead)`
`count_input_tokens`	`Callable[[list[Message]], Awaitable[int \| None]] \| None`	`Field(default=None, exclude=True)`
`build_cache_prefix_request`	`Callable[[list[Message]], Awaitable[ModelRequest]] \| None`	`Field(default=None, exclude=True)`
`force_compaction`	`StrictBool`	`False`
`force_bounded_compaction`	`StrictBool`	`False`
`compaction_instructions`	`str \| None`	`Field(default=None, max_length=COMPACTION_INSTRUCTIONS_MAX_CHARS)`

copy_messages (method)

ContextRequest.copy_messages(value)

copy_session_contract (method)

ContextRequest.copy_session_contract(value: Session) -> Session

copy_agent_contract (method)

ContextRequest.copy_agent_contract(value: AgentSpec) -> AgentSpec

copy_metadata (method)

ContextRequest.copy_metadata(value: dict[str, Any]) -> dict[str, Any]

copy_context_usage (method)

ContextRequest.copy_context_usage(value: ContextUsageState) -> ContextUsageState

copy_pressure_overhead (method)

ContextRequest.copy_pressure_overhead(value: ContextPressureOverhead) -> ContextPressureOverhead

validate_optional_environment_name (method)

ContextRequest.validate_optional_environment_name(value: str | None) -> str | None

validate_optional_runtime_identity (method)

ContextRequest.validate_optional_runtime_identity(value: str | None, info) -> str | None

validate_optional_compaction_instructions (method)

ContextRequest.validate_optional_compaction_instructions(value: str | None) -> str | None

Release source · Runtime guarantees · Capability guides

`ContextUsageState`

from cayu.context import ContextUsageState

Actual provider usage from the previous completed model request.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`last_input_tokens`	`StrictInt \| None`	`Field(default=None, ge=0)`
`last_output_tokens`	`StrictInt \| None`	`Field(default=None, ge=0)`
`last_total_tokens`	`StrictInt \| None`	`Field(default=None, ge=0)`
`last_transcript_cursor`	`StrictInt \| None`	`Field(default=None, ge=0)`
`input_coverage`	`ContextInputCoverage \| None`	`None`
`last_context_overhead_input_tokens`	`StrictInt \| None`	`Field(default=None, ge=0)`
`last_provider_name`	`str \| None`	`None`
`last_requested_model`	`str \| None`	`None`
`last_model`	`str \| None`	`None`
`input_pressure`	`ContextPressureEstimate \| None`	`None`

validate_optional_nonblank (method)

ContextUsageState.validate_optional_nonblank(value: str | None, info) -> str | None

copy_input_pressure (method)

ContextUsageState.copy_input_pressure(value: ContextPressureEstimate | None) -> ContextPressureEstimate | None

Release source · Runtime guarantees · Capability guides

`default_compaction_prompt`

from cayu.context import default_compaction_prompt

Build the default user prompt for model-backed context compaction.

default_compaction_prompt(request: CompactionRequest) -> CompactionPrompt

Release source · Runtime guarantees · Capability guides

`DefaultContextPolicy`

from cayu.context import DefaultContextPolicy

Default policy that sends transcript context with bounded file attachments.

Bases: ContextPolicy.

execution_profile_identity (property)

DefaultContextPolicy.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Optional application-versioned identity for opaque policy behavior.

build (method)

async DefaultContextPolicy.build(request: ContextRequest) -> list[Message]

init (method)

DefaultContextPolicy.__init__(*, max_attachment_results: int=1) -> None

Release source · Runtime guarantees · Capability guides

`estimate_model_request_context_pressure`

from cayu.context import estimate_model_request_context_pressure

estimate_model_request_context_pressure(*, model_request: ModelRequest, image_min_tokens: int=_DEFAULT_ESTIMATE_IMAGE_MIN_TOKENS, document_min_tokens: int=_DEFAULT_ESTIMATE_DOCUMENT_MIN_TOKENS, document_bytes_per_token: int=_DEFAULT_ESTIMATE_BINARY_BYTES_PER_TOKEN, tool_schema_chars_per_token: int=_DEFAULT_ESTIMATE_TOOL_SCHEMA_CHARS_PER_TOKEN, reserved_output_tokens: int=0, estimator: ObservedDeltaContextEstimator | None=None) -> ContextPressureEstimate

Release source · Runtime guarantees · Capability guides

`MessageWindowContextPolicy`

from cayu.context import MessageWindowContextPolicy

Built-in policy that keeps a valid recent message window.

Bases: ContextPolicy.

execution_profile_identity (property)

MessageWindowContextPolicy.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Optional application-versioned identity for opaque policy behavior.

build (method)

async MessageWindowContextPolicy.build(request: ContextRequest) -> list[Message]

init (method)

MessageWindowContextPolicy.__init__(*, max_messages: int, preserve_system: bool=True, max_attachment_results: int=1) -> None

Release source · Runtime guarantees · Capability guides

`ModelCompactor`

from cayu.context import ModelCompactor

Provider-backed compactor that asks a model to summarize older context.

Bases: ContextCompactor.

execution_profile_identity (property)

ModelCompactor.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Optional application-versioned identity for opaque compaction behavior.

provider_budget_identity (method)

ModelCompactor.provider_budget_identity(session: Session) -> tuple[str, str]

compact (method)

async ModelCompactor.compact(request: CompactionRequest) -> CompactionResult

init (method)

ModelCompactor.__init__(*, provider: ModelProvider, model: str, system_prompt: str='You summarize prior agent session context for a future model call. Return only the compact summary. Do not call tools.', options: dict[str, Any] | None=None, max_input_chars: int | None=120000, max_hierarchy_calls: int=64, retry_policy: RetryPolicy | None=None, retry_empty_summaries: bool=False, _usage_dialect: UsageDialect | None=None, _provider_snapshot: _CompactionProviderSnapshot | None=None) -> None

Release source · Runtime guarantees · Capability guides

`ObservedDeltaContextEstimator`

from cayu.context import ObservedDeltaContextEstimator

Estimates context pressure from actual usage plus a local tail estimate.

init (method)

ObservedDeltaContextEstimator.__init__(*, chars_per_token: int=_DEFAULT_ESTIMATE_CHARS_PER_TOKEN, json_chars_per_token: int=_DEFAULT_ESTIMATE_JSON_CHARS_PER_TOKEN, binary_bytes_per_token: int=_DEFAULT_ESTIMATE_BINARY_BYTES_PER_TOKEN) -> None

estimate (method)

ObservedDeltaContextEstimator.estimate(*, usage: ContextUsageState, messages: list[Message], image_min_tokens: int=_DEFAULT_ESTIMATE_IMAGE_MIN_TOKENS, document_min_tokens: int=_DEFAULT_ESTIMATE_DOCUMENT_MIN_TOKENS, document_bytes_per_token: int=_DEFAULT_ESTIMATE_BINARY_BYTES_PER_TOKEN) -> ContextPressureEstimate | None

estimate_full_request (method)

ObservedDeltaContextEstimator.estimate_full_request(*, usage: ContextUsageState, messages: list[Message], overhead: ContextPressureOverhead | None=None, reserved_output_tokens: int=0) -> ContextPressureEstimate

estimate_anchored_request (method)

ObservedDeltaContextEstimator.estimate_anchored_request(*, usage: ContextUsageState, messages: list[Message], overhead: ContextPressureOverhead | None=None, reserved_output_tokens: int=0) -> ContextPressureEstimate

estimate_message_tokens (method)

ObservedDeltaContextEstimator.estimate_message_tokens(message: Message) -> int

estimate_message_attachment_tokens (method)

ObservedDeltaContextEstimator.estimate_message_attachment_tokens(message: Message, *, image_min_tokens: int=_DEFAULT_ESTIMATE_IMAGE_MIN_TOKENS, document_min_tokens: int=_DEFAULT_ESTIMATE_DOCUMENT_MIN_TOKENS, document_bytes_per_token: int=_DEFAULT_ESTIMATE_BINARY_BYTES_PER_TOKEN) -> int

estimate_tool_schema_tokens (method)

ObservedDeltaContextEstimator.estimate_tool_schema_tokens(tools: list[dict[str, Any]] | list[ToolSpec], *, chars_per_token: int=_DEFAULT_ESTIMATE_TOOL_SCHEMA_CHARS_PER_TOKEN) -> int

Release source · Runtime guarantees · Capability guides

`PromptCacheCompactor`

from cayu.context import PromptCacheCompactor

Compactor that reuses the first provider prompt-cache prefix.

On the first compaction, extends the runtime’s exact ModelRequest with a compaction instruction. This preserves model, messages, tool definitions, thinking configuration, provider options, and resolved file attachments at the cache boundary. Compactor options recursively override the copied request options; native structured-output enforcement is disabled because the compactor must return summary text and must not call tools. A configured model override that differs from the cached request uses bounded ModelCompactor input because provider caches are model-bound. Provider identity mismatches and tool-based structured-output requests also use the bounded path so the exact transcript, tools, synthetic instruction, and resolved attachment bytes cannot cross an incompatible request boundary. Cross-provider compaction requires an explicit provider-compatible model; Cayu never forwards the session provider’s model name to another provider.

Later compactions use bounded ModelCompactor input containing only the previous checkpoint summary and newly compactable messages. This avoids rebuilding an unbounded raw-transcript prefix after the cache checkpoint.

Falls back to the configured fallback compactor when no completed-request cursor plus matching durable provider/requested-model identity is available to reconstruct the exact runtime request.

Bases: ContextCompactor.

execution_profile_identity (property)

PromptCacheCompactor.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Optional application-versioned identity for opaque compaction behavior.

provider_budget_identity (method)

PromptCacheCompactor.provider_budget_identity(session: Session) -> tuple[str, str]

compact (method)

async PromptCacheCompactor.compact(request: CompactionRequest) -> CompactionResult

init (method)

PromptCacheCompactor.__init__(*, provider: ModelProvider, model: str | None=None, compaction_instruction: str | None=None, options: dict[str, Any] | None=None, fallback_compactor: ContextCompactor | None=None, retry_policy: RetryPolicy | None=None) -> None

Release source · Runtime guarantees · Capability guides

`RecentTurnsContextPolicy`

from cayu.context import RecentTurnsContextPolicy

Built-in policy that keeps recent user turns and complete tool rounds.

Bases: ContextPolicy.

execution_profile_identity (property)

RecentTurnsContextPolicy.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Optional application-versioned identity for opaque policy behavior.

build (method)

async RecentTurnsContextPolicy.build(request: ContextRequest) -> list[Message]

init (method)

RecentTurnsContextPolicy.__init__(*, max_user_turns: int, preserve_system: bool=True, max_attachment_results: int=1) -> None

Release source · Runtime guarantees · Capability guides

`strip_old_file_attachments`

from cayu.context import strip_old_file_attachments

Remove old native file attachment refs from provider-facing context.

Durable transcript messages keep their original artifacts. This helper only projects model-facing context so providers do not receive the same native file bytes on every subsequent model request.

strip_old_file_attachments(messages: list[Message], *, max_attachment_results: int=1) -> list[Message]

Release source · Runtime guarantees · Capability guides

`TranscriptDigestCompactor`

from cayu.context import TranscriptDigestCompactor

Deterministic fallback compactor that represents an atomic message prefix.

Bases: ContextCompactor.

execution_profile_identity (property)

TranscriptDigestCompactor.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Optional application-versioned identity for opaque compaction behavior.

provider_budget_identity (method)

TranscriptDigestCompactor.provider_budget_identity(session: Session) -> None

compact (method)

async TranscriptDigestCompactor.compact(request: CompactionRequest) -> CompactionResult

init (method)

TranscriptDigestCompactor.__init__(*, max_summary_chars: int=8000) -> None

Release source · Runtime guarantees · Capability guides

`trim_context_messages`

from cayu.context import trim_context_messages

Return a recent valid suffix without cutting through a tool round.

trim_context_messages(messages: list[Message], *, max_messages: int, preserve_system: bool=True) -> list[Message]

Release source · Runtime guarantees · Capability guides

`trim_context_turns`

from cayu.context import trim_context_turns

Return the latest user turns with complete assistant/tool follow-up.

trim_context_turns(messages: list[Message], *, max_user_turns: int, preserve_system: bool=True) -> list[Message]

Release source · Runtime guarantees · Capability guides

`UsageTriggeredContextPolicy`

from cayu.context import UsageTriggeredContextPolicy

Switch context policy after previous actual provider usage crosses a threshold.

The runtime populates ContextRequest.context_usage from the previous completed model call in the same session. This wrapper keeps normal context behavior below the configured thresholds and delegates to triggered_policy on the next call once a threshold is reached. By default the trigger is sticky and stored in the session checkpoint so later low-usage calls continue using triggered_policy.

Bases: RuntimeManagedContextPolicy.

execution_profile_identity (property)

UsageTriggeredContextPolicy.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Optional application-versioned identity for opaque policy behavior.

build (method)

async UsageTriggeredContextPolicy.build(request: ContextRequest) -> list[Message]

build_with_checkpoint (method)

async UsageTriggeredContextPolicy.build_with_checkpoint(request: ContextRequest, *, checkpoint: dict[str, Any] | None) -> ContextBuildResult

init (method)

UsageTriggeredContextPolicy.__init__(*, triggered_policy: ContextPolicy, base_policy: ContextPolicy | None=None, min_input_tokens: int | None=None, trigger_estimated_context_tokens: int | None=None, reserved_output_tokens: int=0, verify_estimate_with_provider_count: bool=False, provider_count_threshold_ratio: float=0.9, provider_count_min_delta_tokens: int | None=None, min_total_tokens: int | None=None, sticky: bool=True) -> None

Release source · Runtime guarantees · Capability guides