cayu.tools.exposure

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.

`ALL_REGISTERED_TOOLS_PROFILE_ID`

from cayu.tools import ALL_REGISTERED_TOOLS_PROFILE_ID

ALL_REGISTERED_TOOLS_PROFILE_ID = 'cayu:all-registered-tools:v1'

Release source · Runtime guarantees · Capability guides

`AllRegisteredToolsExposurePolicy`

from cayu.tools import AllRegisteredToolsExposurePolicy

Compatibility policy exposing every tool inside the effective ceiling.

Bases: ToolExposurePolicy.

execution_profile_identity (property)

AllRegisteredToolsExposurePolicy.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Return a stable application declaration, or None when non-portable.

select (method)

AllRegisteredToolsExposurePolicy.select(request: ToolExposurePolicyRequest) -> ToolExposureDecision

Release source · Runtime guarantees · Capability guides

`copy_resolved_tool_exposure`

from cayu.tools import copy_resolved_tool_exposure

Return a detached, fully revalidated exposure snapshot.

copy_resolved_tool_exposure(exposure: ResolvedToolExposure) -> ResolvedToolExposure

Release source · Runtime guarantees · Capability guides

`copy_tool_capability_ceiling`

from cayu.tools import copy_tool_capability_ceiling

Return a detached, fully revalidated durable ceiling.

copy_tool_capability_ceiling(ceiling: ToolCapabilityCeiling) -> ToolCapabilityCeiling

Release source · Runtime guarantees · Capability guides

`RegisteredToolCapability`

from cayu.tools import RegisteredToolCapability

Immutable, callable-free summary of one registered application tool.

The summary is safe to pass to an application-owned exposure policy: it contains the declared model contract and execution classifications, but no live tool, policy, runner, environment, credential, or secret handle.

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
`name`	`str`	`required`
`description`	`str`	`''`
`input_schema`	`Mapping[str, Any]`	`Field(default_factory=dict)`
`parallel_safe`	`StrictBool`	`True`
`effect`	`ToolEffect`	`ToolEffect.EXTERNAL`
`publishes_arguments`	`StrictBool`	`True`
`workspace_mutation`	`StrictBool`	`False`
`execution_contract`	`ToolExecutionContract`	`Field(default_factory=ToolExecutionContract)`
`execution_requirements`	`tuple[ToolExecutionRequirement, ...]`	`()`
`schema_fingerprint`	`str`	`''`
`definition_fingerprint`	`str`	`''`

copy_execution_requirements (method)

RegisteredToolCapability.copy_execution_requirements(value: object) -> tuple[ToolExecutionRequirement, ...]

validate_name (method)

RegisteredToolCapability.validate_name(value: str) -> str

validate_description (method)

RegisteredToolCapability.validate_description(value: str) -> str

copy_input_schema (method)

RegisteredToolCapability.copy_input_schema(value: object) -> dict[str, Any]

freeze_input_schema (method)

RegisteredToolCapability.freeze_input_schema(value: Mapping[str, Any]) -> Mapping[str, Any]

serialize_input_schema (method)

RegisteredToolCapability.serialize_input_schema(value: Mapping[str, Any]) -> dict[str, Any]

validate_and_bind_fingerprints (method)

RegisteredToolCapability.validate_and_bind_fingerprints() -> RegisteredToolCapability

input_schema_copy (method)

RegisteredToolCapability.input_schema_copy() -> dict[str, Any]

Return an owned ordinary-JSON copy for provider/profile projection.

Release source · Runtime guarantees · Capability guides

`resolve_tool_capability_ceiling`

from cayu.tools import resolve_tool_capability_ceiling

Canonicalize a new or narrowed ceiling against registered capabilities.

maximum is the durable parent/session ceiling. A requested ceiling may only preserve or narrow it. Maximum names absent from a reconstructed catalog are removed; no newly registered or child-only name can enter the result.

resolve_tool_capability_ceiling(requested: ToolCapabilityCeiling | None, registered_tools: tuple[RegisteredToolCapability, ...], *, maximum: ToolCapabilityCeiling | None=None) -> ToolCapabilityCeiling

Release source · Runtime guarantees · Capability guides

`resolve_tool_exposure`

from cayu.tools import resolve_tool_exposure

Run and validate a pure policy against registered and ceiling state.

resolve_tool_exposure(policy: ToolExposurePolicy, request: ToolExposurePolicyRequest) -> ResolvedToolExposure

Release source · Runtime guarantees · Capability guides

`ResolvedToolExposure`

from cayu.tools import ResolvedToolExposure

Canonical, descriptor-bound result of validating one policy decision.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal[2]`	`TOOL_EXPOSURE_SCHEMA_VERSION`
`profile_id`	`str`	`required`
`catalogue_revision`	`str`	`required`
`tools`	`tuple[RegisteredToolCapability, ...]`	`required`
`registered_count`	`StrictInt`	`Field(ge=0, le=TOOL_EXPOSURE_MAX_REGISTERED_TOOLS)`
`ceiling_count`	`StrictInt`	`Field(ge=0, le=TOOL_EXPOSURE_MAX_REGISTERED_TOOLS)`
`metadata`	`Mapping[str, Any]`	`Field(default_factory=dict)`
`fingerprint`	`str`	`''`

validate_profile_id (method)

ResolvedToolExposure.validate_profile_id(value: str) -> str

validate_catalogue_revision (method)

ResolvedToolExposure.validate_catalogue_revision(value: str) -> str

copy_tools (method)

ResolvedToolExposure.copy_tools(value: object) -> tuple[RegisteredToolCapability, ...]

copy_metadata (method)

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

freeze_metadata (method)

ResolvedToolExposure.freeze_metadata(value: Mapping[str, Any]) -> Mapping[str, Any]

serialize_metadata (method)

ResolvedToolExposure.serialize_metadata(value: Mapping[str, Any]) -> dict[str, Any]

validate_and_bind_fingerprint (method)

ResolvedToolExposure.validate_and_bind_fingerprint() -> ResolvedToolExposure

tool_names (property)

ResolvedToolExposure.tool_names() -> tuple[str, ...]

Release source · Runtime guarantees · Capability guides

`StaticToolExposurePolicy`

from cayu.tools import StaticToolExposurePolicy

Expose one deterministic named allow-list, including an empty list.

Bases: ToolExposurePolicy.

execution_profile_identity (property)

StaticToolExposurePolicy.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Return a stable application declaration, or None when non-portable.

select (method)

StaticToolExposurePolicy.select(request: ToolExposurePolicyRequest) -> ToolExposureDecision

init (method)

StaticToolExposurePolicy.__init__(*, profile_id: str, tools: Iterable[str]) -> None

profile_id (property)

StaticToolExposurePolicy.profile_id() -> str

tools (property)

StaticToolExposurePolicy.tools() -> tuple[str, ...]

Release source · Runtime guarantees · Capability guides

`TOOL_CAPABILITY_CEILING_SCHEMA_VERSION`

from cayu.tools import TOOL_CAPABILITY_CEILING_SCHEMA_VERSION

TOOL_CAPABILITY_CEILING_SCHEMA_VERSION = 1

Release source · Runtime guarantees · Capability guides

`TOOL_EXPOSURE_MAX_CATALOG_BYTES`

from cayu.tools import TOOL_EXPOSURE_MAX_CATALOG_BYTES

TOOL_EXPOSURE_MAX_CATALOG_BYTES = TOOL_CATALOGUE_MAX_BYTES

Release source · Runtime guarantees · Capability guides

`TOOL_EXPOSURE_MAX_REGISTERED_TOOLS`

from cayu.tools import TOOL_EXPOSURE_MAX_REGISTERED_TOOLS

TOOL_EXPOSURE_MAX_REGISTERED_TOOLS = TOOL_CATALOGUE_MAX_TOOLS

Release source · Runtime guarantees · Capability guides

`TOOL_EXPOSURE_METADATA_MAX_BYTES`

from cayu.tools import TOOL_EXPOSURE_METADATA_MAX_BYTES

TOOL_EXPOSURE_METADATA_MAX_BYTES = 4 * 1024

Release source · Runtime guarantees · Capability guides

`TOOL_EXPOSURE_METADATA_MAX_ENTRIES`

from cayu.tools import TOOL_EXPOSURE_METADATA_MAX_ENTRIES

TOOL_EXPOSURE_METADATA_MAX_ENTRIES = 64

Release source · Runtime guarantees · Capability guides

`TOOL_EXPOSURE_PROFILE_ID_MAX_CHARS`

from cayu.tools import TOOL_EXPOSURE_PROFILE_ID_MAX_CHARS

TOOL_EXPOSURE_PROFILE_ID_MAX_CHARS = 256

Release source · Runtime guarantees · Capability guides

`TOOL_EXPOSURE_SCHEMA_VERSION`

from cayu.tools import TOOL_EXPOSURE_SCHEMA_VERSION

TOOL_EXPOSURE_SCHEMA_VERSION = 2

Release source · Runtime guarantees · Capability guides

`ToolCapabilityCeiling`

from cayu.tools import ToolCapabilityCeiling

Immutable maximum application-tool set for one durable session.

Callers name already registered tools. The runtime canonicalizes those names to registration order before the ceiling becomes session authority. Its fingerprint is safe identity evidence; it does not contain schemas, tool implementations, policy bodies, credentials, or arguments.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal[1]`	`TOOL_CAPABILITY_CEILING_SCHEMA_VERSION`
`tool_names`	`tuple[str, ...]`	`()`
`fingerprint`	`str`	`''`

copy_tool_names (method)

ToolCapabilityCeiling.copy_tool_names(value: object) -> tuple[Any, ...]

validate_tool_names (method)

ToolCapabilityCeiling.validate_tool_names(value: tuple[str, ...]) -> tuple[str, ...]

validate_and_bind_fingerprint (method)

ToolCapabilityCeiling.validate_and_bind_fingerprint() -> ToolCapabilityCeiling

Release source · Runtime guarantees · Capability guides

`ToolExposure`

from cayu.tools import ToolExposure

Content-minimized public evidence for one prepared model-step tool projection.

The record intentionally contains no separate tool-name list, definitions, policy metadata, arguments, or policy reasoning. profile_id is a public, application-selected non-secret label. The fingerprint binds the record to the exact ordered definitions retained privately by the runtime.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal[2]`	`TOOL_EXPOSURE_SCHEMA_VERSION`
`execution_profile_fingerprint`	`str`	`Field(min_length=64, max_length=64, pattern='^[0-9a-f]{64}$')`
`profile_id`	`str`	`required`
`catalogue_revision`	`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`
`step`	`StrictInt`	`Field(ge=1, le=MAX_DURABLE_JSON_INTEGER)`
`provider_name`	`str`	`required`
`model`	`str`	`required`
`model_step_id`	`str`	`required`

validate_schema_version (method)

ToolExposure.validate_schema_version(value: object) -> object

validate_profile_id (method)

ToolExposure.validate_profile_id(value: str) -> str

validate_catalogue_revision (method)

ToolExposure.validate_catalogue_revision(value: str) -> str

validate_identity (method)

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

validate_model_step_id (method)

ToolExposure.validate_model_step_id(value: str) -> str

validate_counts (method)

ToolExposure.validate_counts() -> ToolExposure

Release source · Runtime guarantees · Capability guides

`ToolExposureDecision`

from cayu.tools import ToolExposureDecision

A policy decision naming registered tools, never tool implementations.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`profile_id`	`str`	`required`
`tool_names`	`tuple[str, ...]`	`()`
`metadata`	`Mapping[str, Any]`	`Field(default_factory=dict)`

validate_profile_id (method)

ToolExposureDecision.validate_profile_id(value: str) -> str

copy_tool_names (method)

ToolExposureDecision.copy_tool_names(value: object) -> tuple[Any, ...]

validate_tool_names (method)

ToolExposureDecision.validate_tool_names(value: tuple[str, ...]) -> tuple[str, ...]

copy_metadata (method)

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

freeze_metadata (method)

ToolExposureDecision.freeze_metadata(value: Mapping[str, Any]) -> Mapping[str, Any]

serialize_metadata (method)

ToolExposureDecision.serialize_metadata(value: Mapping[str, Any]) -> dict[str, Any]

Release source · Runtime guarantees · Capability guides

`ToolExposurePolicy`

from cayu.tools import ToolExposurePolicy

Pure application policy selecting a subset of registered tools.

Implementations receive only copied immutable records. They must be local, deterministic, and side-effect-free: selection is part of preparing one model request, not an authorization or model-routing hook.

Bases: ABC.

execution_profile_identity (property)

ToolExposurePolicy.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Return a stable application declaration, or None when non-portable.

select (method)

ToolExposurePolicy.select(request: ToolExposurePolicyRequest) -> ToolExposureDecision

Select registered tool names for one model step.

Release source · Runtime guarantees · Capability guides

`ToolExposurePolicyRequest`

from cayu.tools import ToolExposurePolicyRequest

Immutable, bounded input supplied to a tool-exposure policy.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`session_id`	`str`	`required`
`agent_name`	`str`	`required`
`provider_name`	`str`	`required`
`model`	`str`	`required`
`step`	`StrictInt`	`Field(ge=1, le=MAX_DURABLE_JSON_INTEGER)`
`transcript_cursor`	`StrictInt`	`Field(default=0, ge=0)`
`catalogue_revision`	`str`	`required`
`registered_tools`	`tuple[RegisteredToolCapability, ...]`	`required`
`capability_ceiling`	`tuple[str, ...]`	`required`
`previous_profile_id`	`str \| None`	`None`
`metadata`	`Mapping[str, Any]`	`Field(default_factory=dict)`

validate_identity_text (method)

ToolExposurePolicyRequest.validate_identity_text(value: str, info) -> str

validate_previous_profile_id (method)

ToolExposurePolicyRequest.validate_previous_profile_id(value: str | None) -> str | None

validate_catalogue_revision (method)

ToolExposurePolicyRequest.validate_catalogue_revision(value: str) -> str

copy_registered_tools (method)

ToolExposurePolicyRequest.copy_registered_tools(value: object) -> tuple[RegisteredToolCapability, ...]

copy_capability_ceiling (method)

ToolExposurePolicyRequest.copy_capability_ceiling(value: object) -> tuple[Any, ...]

validate_capability_ceiling (method)

ToolExposurePolicyRequest.validate_capability_ceiling(value: tuple[str, ...]) -> tuple[str, ...]

copy_metadata (method)

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

freeze_metadata (method)

ToolExposurePolicyRequest.freeze_metadata(value: Mapping[str, Any]) -> Mapping[str, Any]

serialize_metadata (method)

ToolExposurePolicyRequest.serialize_metadata(value: Mapping[str, Any]) -> dict[str, Any]

validate_catalog (method)

ToolExposurePolicyRequest.validate_catalog() -> ToolExposurePolicyRequest

eligible_tools (property)

ToolExposurePolicyRequest.eligible_tools() -> tuple[RegisteredToolCapability, ...]

Return ceiling-constrained capabilities in canonical registration order.

Release source · Runtime guarantees · Capability guides