cayu.context.footprints

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.

`build_prompt_contribution_manifest`

from cayu.context import build_prompt_contribution_manifest

Build content-free creation evidence from exact rendered prompt fragments.

build_prompt_contribution_manifest(*, rendered_system_prompt: str | None, contributions: dict[PromptContributionKind | str, tuple[str, ...]], config: RequestFootprintConfig | None=None) -> PromptContributionManifest | None

Release source · Runtime guarantees · Capability guides

`build_request_footprint`

from cayu.context import build_request_footprint

Analyze one final provider-neutral request without retaining its content.

build_request_footprint(model_request: ModelRequest, *, provider_name: str, step: int | None, attempt: int, max_attempts: int, request_variant: RequestVariant | str, observation_id: str, model_step_id: str, model_attempt_id: str, config: RequestFootprintConfig | None=None, context_pressure_profile: ModelContextPressureProfile | None=None, cache_policy: CachePolicy | None=None, provider_conversation_prefix: tuple[dict[str, Any], ...] | None=None, measured_provider_options: dict[str, Any] | None=None, fingerprint_provider_options: dict[str, Any] | None=None, prompt_contribution_manifest: PromptContributionManifest | None=None, structured_output_instruction: str | None=None, operation_id: str | None=None, operation_attempt_id: str | None=None, execution_profile_fingerprint: str | None=None, tool_exposure: ToolExposure | None=None, targeted_tool_grants: TargetedToolGrantFootprint | None=None, tool_discovery_view: ToolDiscoveryViewFootprint | None=None) -> RequestFootprint

Release source · Runtime guarantees · Capability guides

`copy_request_footprint_config`

from cayu.context import copy_request_footprint_config

copy_request_footprint_config(config: RequestFootprintConfig | None) -> RequestFootprintConfig

Release source · Runtime guarantees · Capability guides

`PromptContributionAvailability`

from cayu.context import PromptContributionAvailability

Bases: StrEnum.

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
`AVAILABLE`	`class attribute`	`'available'`
`UNAVAILABLE`	`class attribute`	`'unavailable'`

Release source · Runtime guarantees · Capability guides

`PromptContributionFootprint`

from cayu.context import PromptContributionFootprint

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`kind`	`PromptContributionKind`	`required`
`size`	`RequestSize`	`required`
`fingerprint`	`RequestFingerprint`	`required`

Release source · Runtime guarantees · Capability guides

`PromptContributionKind`

from cayu.context import PromptContributionKind

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`AGENT_INSTRUCTIONS`	`class attribute`	`'agent_instructions'`
`WORKSPACE_INSTRUCTIONS`	`class attribute`	`'workspace_instructions'`
`CAYU_FRAMING`	`class attribute`	`'cayu_framing'`

Release source · Runtime guarantees · Capability guides

`PromptContributionManifest`

from cayu.context import PromptContributionManifest

Content-free creation-time evidence for the rendered initial system prompt.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal[1]`	`required`
`system`	`RequestComponentFootprint`	`required`
`system_fingerprint`	`RequestFingerprint`	`required`
`contributions`	`tuple[PromptContributionFootprint, ...]`	`required`

validate_schema_version (method)

PromptContributionManifest.validate_schema_version(value: object) -> object

validate_contributions (method)

PromptContributionManifest.validate_contributions(value: tuple[PromptContributionFootprint, ...]) -> tuple[PromptContributionFootprint, ...]

Release source · Runtime guarantees · Capability guides

`REQUEST_FOOTPRINT_CANONICALIZATION_VERSION`

from cayu.context import REQUEST_FOOTPRINT_CANONICALIZATION_VERSION

REQUEST_FOOTPRINT_CANONICALIZATION_VERSION = 1

Release source · Runtime guarantees · Capability guides

`REQUEST_FOOTPRINT_SCHEMA_VERSION`

from cayu.context import REQUEST_FOOTPRINT_SCHEMA_VERSION

REQUEST_FOOTPRINT_SCHEMA_VERSION = 7

Release source · Runtime guarantees · Capability guides

`RequestAttachmentGroupFootprint`

from cayu.context import RequestAttachmentGroupFootprint

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`kind`	`FileAttachmentKind`	`required`
`count`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`source_bytes`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`

Release source · Runtime guarantees · Capability guides

`RequestAttachmentsFootprint`

from cayu.context import RequestAttachmentsFootprint

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`count`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`source_bytes`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`groups`	`tuple[RequestAttachmentGroupFootprint, ...]`	`()`

Release source · Runtime guarantees · Capability guides

`RequestCacheBreakpointFootprint`

from cayu.context import RequestCacheBreakpointFootprint

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`kind`	`CacheBreakpoint`	`required`
`ttl`	`Literal['standard', 'extended']`	`required`
`fingerprint`	`RequestFingerprint`	`required`

Release source · Runtime guarantees · Capability guides

`RequestComponentFootprint`

from cayu.context import RequestComponentFootprint

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`count`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`size`	`RequestSize`	`required`

Release source · Runtime guarantees · Capability guides

`RequestComponentTokenEstimates`

from cayu.context import RequestComponentTokenEstimates

Labeled local token estimates for the final request’s major components.

Structured-output contribution can overlap the system/tool/options component in which the provider-neutral request carries it. These fields are evidence about component pressure, not additive billing facts.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`method`	`str`	`required`
`confidence`	`str`	`required`
`total_input_tokens`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`system_message_input_tokens`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`non_system_message_input_tokens`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`tool_schema_input_tokens`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`structured_output_input_tokens`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`attachment_input_tokens`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`request_options_input_tokens`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`

validate_labels (method)

RequestComponentTokenEstimates.validate_labels(value: str, info) -> str

Release source · Runtime guarantees · Capability guides

`RequestContentGroupFootprint`

from cayu.context import RequestContentGroupFootprint

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`role`	`MessageRole`	`required`
`part_type`	`str`	`required`
`count`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`size`	`RequestSize`	`required`

validate_part_type (method)

RequestContentGroupFootprint.validate_part_type(value: str) -> str

Release source · Runtime guarantees · Capability guides

`RequestFingerprint`

from cayu.context import RequestFingerprint

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`availability`	`RequestFingerprintAvailability`	`required`
`value`	`str \| None`	`None`
`algorithm`	`Literal['hmac-sha256'] \| None`	`None`
`key_id`	`str \| None`	`None`
`canonicalization_version`	`Literal[1]`	`required`
`unavailable_reason`	`str \| None`	`None`

validate_canonicalization_version (method)

RequestFingerprint.validate_canonicalization_version(value: object) -> object

validate_value (method)

RequestFingerprint.validate_value(value: str | None) -> str | None

validate_key_id (method)

RequestFingerprint.validate_key_id(value: str | None) -> str | None

validate_unavailable_reason (method)

RequestFingerprint.validate_unavailable_reason(value: str | None) -> str | None

validate_availability (method)

RequestFingerprint.validate_availability() -> RequestFingerprint

Release source · Runtime guarantees · Capability guides

`RequestFingerprintAvailability`

from cayu.context import RequestFingerprintAvailability

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`AVAILABLE`	`class attribute`	`'available'`
`UNAVAILABLE`	`class attribute`	`'unavailable'`

Release source · Runtime guarantees · Capability guides

`RequestFingerprintSet`

from cayu.context import RequestFingerprintSet

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`provider_neutral_request`	`RequestFingerprint`	`required`
`provider_wire_request`	`RequestFingerprint`	`required`
`system`	`RequestFingerprint`	`required`
`tool_manifest`	`RequestFingerprint`	`required`
`conversation_prefix`	`RequestFingerprint`	`required`

Release source · Runtime guarantees · Capability guides

`RequestFootprint`

from cayu.context import RequestFootprint

Versioned, content-minimized evidence about one prepared provider request.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal[1, 2, 3, 4, 5, 6, 7]`	`required`
`execution_profile_fingerprint`	`str \| None`	`None`
`tool_exposure`	`ToolExposureFootprint \| None`	`None`
`targeted_tool_grants`	`TargetedToolGrantFootprint \| None`	`None`
`targeted_native_item_active`	`StrictBool \| None`	`None`
`targeted_native_item_message_index`	`StrictInt \| None`	`Field(default=None, ge=0)`
`tool_discovery_view`	`ToolDiscoveryViewFootprint \| None`	`None`
`tool_discovery_projection`	`ToolDiscoveryProjectionFootprint \| None`	`Field(default=None, exclude_if=lambda value: value is None)`
`observation_id`	`str`	`required`
`provider_name`	`str`	`required`
`model`	`str`	`required`
`step`	`StrictInt \| None`	`Field(default=None, ge=1, le=MAX_DURABLE_JSON_INTEGER)`
`attempt`	`StrictInt`	`Field(ge=1, le=MAX_DURABLE_JSON_INTEGER)`
`max_attempts`	`StrictInt`	`Field(ge=1, le=MAX_DURABLE_JSON_INTEGER)`
`request_variant`	`RequestVariant`	`required`
`model_step_id`	`str`	`required`
`model_attempt_id`	`str`	`required`
`operation_id`	`str \| None`	`None`
`attempt_id`	`str \| None`	`None`
`total`	`RequestComponentFootprint`	`required`
`messages`	`RequestMessagesFootprint`	`required`
`tools`	`RequestComponentFootprint`	`required`
`attachments`	`RequestAttachmentsFootprint`	`required`
`options`	`RequestOptionsFootprint`	`required`
`structured_output`	`RequestComponentFootprint`	`required`
`context_pressure`	`ContextPressureEstimate`	`required`
`component_tokens`	`RequestComponentTokenEstimates`	`required`
`prompt_contributions`	`RequestPromptContributionAttribution`	`required`
`fingerprints`	`RequestFingerprintSet`	`required`
`cache_breakpoints`	`tuple[RequestCacheBreakpointFootprint, ...]`	`()`

validate_schema_version (method)

RequestFootprint.validate_schema_version(value: object) -> object

validate_execution_profile_fingerprint (method)

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

validate_nonblank (method)

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

validate_optional_causal_identity (method)

RequestFootprint.validate_optional_causal_identity(value: str | None, info) -> str | None

validate_execution_identity (method)

RequestFootprint.validate_execution_identity(value: str, info) -> str

validate_attempt (method)

RequestFootprint.validate_attempt() -> RequestFootprint

Release source · Runtime guarantees · Capability guides

`RequestFootprintConfig`

from cayu.context import RequestFootprintConfig

Controls local, content-minimized request-footprint observation.

Footprints omit provider-request content but may contain bounded public application labels, including a schema-v3 tool-exposure profile_id. They are enabled by default. Keyed request identities remain disabled until both a key ID and secret key are supplied. This configuration never enables provider-backed token counting.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`enabled`	`StrictBool`	`True`
`fingerprint_key_id`	`str \| None`	`None`
`fingerprint_key`	`SecretStr \| None`	`Field(default=None, repr=False)`

validate_fingerprint_key_id (method)

RequestFootprintConfig.validate_fingerprint_key_id(value: str | None) -> str | None

validate_fingerprint_key_pair (method)

RequestFootprintConfig.validate_fingerprint_key_pair() -> RequestFootprintConfig

Release source · Runtime guarantees · Capability guides

`RequestMessagesFootprint`

from cayu.context import RequestMessagesFootprint

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`count`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`system`	`RequestComponentFootprint`	`required`
`groups`	`tuple[RequestContentGroupFootprint, ...]`	`()`
`size`	`RequestSize`	`required`

Release source · Runtime guarantees · Capability guides

`RequestOptionsFootprint`

from cayu.context import RequestOptionsFootprint

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`known_categories`	`tuple[str, ...]`	`()`
`unknown_count`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`size`	`RequestSize`	`required`

validate_known_categories (method)

RequestOptionsFootprint.validate_known_categories(value: tuple[str, ...]) -> tuple[str, ...]

Release source · Runtime guarantees · Capability guides

`RequestPromptContributionAttribution`

from cayu.context import RequestPromptContributionAttribution

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`availability`	`PromptContributionAvailability`	`required`
`contributions`	`tuple[PromptContributionFootprint, ...]`	`()`
`unavailable_reason`	`str \| None`	`None`

validate_availability (method)

RequestPromptContributionAttribution.validate_availability() -> RequestPromptContributionAttribution

Release source · Runtime guarantees · Capability guides

`RequestSize`

from cayu.context import RequestSize

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`characters`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`utf8_bytes`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`canonical_json_bytes`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`

Release source · Runtime guarantees · Capability guides

`RequestVariant`

from cayu.context import RequestVariant

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`INITIAL`	`class attribute`	`'initial'`
`STRUCTURED_OUTPUT_REPAIR`	`class attribute`	`'structured_output_repair'`
`CONTEXT_OVERFLOW_RECOVERY`	`class attribute`	`'context_overflow_recovery'`
`CONTEXT_COMPACTION`	`class attribute`	`'context_compaction'`

Release source · Runtime guarantees · Capability guides

`targeted_tool_grant_footprint`

from cayu.context import targeted_tool_grant_footprint

Build one stable footprint without projecting refs, schemas, or policy state.

targeted_tool_grant_footprint(records: tuple[TargetedToolGrantRecord, ...], *, projection: TargetedToolProjectionKind | None) -> TargetedToolGrantFootprint | None

Release source · Runtime guarantees · Capability guides

`TargetedToolGrantFootprint`

from cayu.context import TargetedToolGrantFootprint

Bounded content-free identity for grants adjacent to a provider request.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal[2]`	`2`
`projection`	`TargetedToolProjectionKind`	`required`
`native_marker_id`	`str \| None`	`Field(default=None, pattern='^sha256:[0-9a-f]{64}$')`
`generation_id`	`str`	`Field(pattern='^sha256:[0-9a-f]{64}$')`
`catalogue_revision`	`str`	`Field(pattern='^sha256:[0-9a-f]{64}$')`
`grant_count`	`StrictInt`	`Field(ge=1, le=TARGETED_TOOL_GRANT_MAX_REQUESTS)`
`grant_ids`	`tuple[str, ...]`	`required`
`tool_ids`	`tuple[str, ...]`	`required`
`max_calls`	`StrictInt`	`Field(ge=1, le=TARGETED_TOOL_GRANT_MAX_REQUESTS * TARGETED_TOOL_GRANT_MAX_CALLS)`
`used_calls`	`StrictInt`	`Field(ge=0, le=TARGETED_TOOL_GRANT_MAX_REQUESTS * TARGETED_TOOL_GRANT_MAX_CALLS)`
`remaining_calls`	`StrictInt`	`Field(ge=0, le=TARGETED_TOOL_GRANT_MAX_REQUESTS * TARGETED_TOOL_GRANT_MAX_CALLS)`
`direct_tool_prefix_changed`	`Literal[False]`	`False`

validate_schema_version (method)

TargetedToolGrantFootprint.validate_schema_version(value: object) -> object

validate_projection (method)

TargetedToolGrantFootprint.validate_projection(value: object) -> TargetedToolProjectionKind

validate_direct_tool_prefix_changed (method)

TargetedToolGrantFootprint.validate_direct_tool_prefix_changed(value: object) -> object

validate_grant_ids (method)

TargetedToolGrantFootprint.validate_grant_ids(value: object) -> object

validate_grant_identities (method)

TargetedToolGrantFootprint.validate_grant_identities(value: tuple[str, ...]) -> tuple[str, ...]

bound_tool_ids (method)

TargetedToolGrantFootprint.bound_tool_ids(value: object) -> object

validate_tool_ids (method)

TargetedToolGrantFootprint.validate_tool_ids(value: tuple[str, ...]) -> tuple[str, ...]

validate_shape (method)

TargetedToolGrantFootprint.validate_shape() -> TargetedToolGrantFootprint

Release source · Runtime guarantees · Capability guides

`tool_discovery_view_footprint`

from cayu.context import tool_discovery_view_footprint

Project durable discovery state without refs, schemas, or query evidence.

tool_discovery_view_footprint(state: ToolDiscoveryViewState) -> ToolDiscoveryViewFootprint

Release source · Runtime guarantees · Capability guides

`ToolDiscoveryProjectionFootprint`

from cayu.context import ToolDiscoveryProjectionFootprint

Content-free summary of one provider-native discovery projection.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`protocol`	`Literal['openai.tool_search.client.v1', 'openai.tool_search.hosted.v1']`	`required`
`candidate_count`	`StrictInt`	`Field(ge=0, le=TOOL_DISCOVERY_PROJECTION_MAX_TOOLS)`
`loaded_count`	`StrictInt`	`Field(ge=0, le=TOOL_DISCOVERY_PROJECTION_MAX_TOOLS)`
`generation_id`	`str \| None`	`Field(default=None, pattern='^sha256:[0-9a-f]{64}$')`

validate_shape (method)

ToolDiscoveryProjectionFootprint.validate_shape() -> ToolDiscoveryProjectionFootprint

Release source · Runtime guarantees · Capability guides

`ToolDiscoveryViewFootprint`

from cayu.context import ToolDiscoveryViewFootprint

Content-free authority summary for one current discovery view.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`generation_id`	`str`	`Field(pattern='^sha256:[0-9a-f]{64}$')`
`revision`	`StrictInt`	`Field(ge=0, le=TOOL_DISCOVERY_MAX_GRANTS)`
`catalogue_revision`	`str`	`required`
`ceiling_fingerprint`	`str`	`Field(pattern='^sha256:[0-9a-f]{64}$')`
`grant_count`	`StrictInt`	`Field(ge=0, le=TOOL_DISCOVERY_MAX_GRANTS)`

validate_catalogue_revision (method)

ToolDiscoveryViewFootprint.validate_catalogue_revision(value: str) -> str

validate_revision (method)

ToolDiscoveryViewFootprint.validate_revision() -> ToolDiscoveryViewFootprint

Release source · Runtime guarantees · Capability guides

`ToolExposureFootprint`

from cayu.context import ToolExposureFootprint

Content-minimized exposure summary containing one public profile label.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`profile_id`	`str`	`required`
`exposure_fingerprint`	`str`	`Field(min_length=64, max_length=64, pattern='^[0-9a-f]{64}$')`
`registered_count`	`StrictInt`	`Field(ge=0, le=TOOL_EXPOSURE_MAX_REGISTERED_TOOLS)`
`ceiling_count`	`StrictInt`	`Field(ge=0, le=TOOL_EXPOSURE_MAX_REGISTERED_TOOLS)`
`exposed_count`	`StrictInt`	`Field(ge=0, le=TOOL_EXPOSURE_MAX_REGISTERED_TOOLS)`
`profile_changed`	`StrictBool`	`required`

validate_profile_id (method)

ToolExposureFootprint.validate_profile_id(value: str) -> str

validate_counts (method)

ToolExposureFootprint.validate_counts() -> ToolExposureFootprint

Release source · Runtime guarantees · Capability guides