cayu.tools.catalogue

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_tool_catalog_snapshot

from cayu.tools import build_tool_catalog_snapshot

Copy and canonicalize an admitted descriptor collection.

build_tool_catalog_snapshot(descriptors: Iterable[ToolDescriptor]) -> ToolCatalogSnapshot

Release source · Runtime guarantees · Capability guides

build_tool_descriptor

from cayu.tools import build_tool_descriptor

Build one descriptor from copied runtime-admitted registration state.

build_tool_descriptor(*, name: str, description: str, input_schema: Mapping[str, Any], parallel_safe: bool, effect: ToolEffect, publishes_arguments: bool, workspace_mutation: bool, execution_contract: ToolExecutionContract | None=None, execution_requirements: tuple[ToolExecutionRequirement, ...]=(), auxiliary_inference: AuxiliaryInferencePolicy | None=None, provenance: ToolDescriptorProvenance | None=None) -> ToolDescriptor

Release source · Runtime guarantees · Capability guides

CALL_TOOL_NAME

from cayu.tools import CALL_TOOL_NAME

CALL_TOOL_NAME = 'call_tool'

Release source · Runtime guarantees · Capability guides

canonical_tool_id

from cayu.tools import canonical_tool_id

Return one stable collision-free ID from admitted tool provenance.

canonical_tool_id(*, name: str, provenance: ToolDescriptorProvenance) -> str

Release source · Runtime guarantees · Capability guides

copy_tool_catalog_snapshot

from cayu.tools import copy_tool_catalog_snapshot

Return a detached, fully revalidated catalogue snapshot.

copy_tool_catalog_snapshot(snapshot: ToolCatalogSnapshot) -> ToolCatalogSnapshot

Release source · Runtime guarantees · Capability guides

copy_tool_descriptor

from cayu.tools import copy_tool_descriptor

Return a detached, fully revalidated descriptor.

copy_tool_descriptor(descriptor: ToolDescriptor) -> ToolDescriptor

Release source · Runtime guarantees · Capability guides

copy_tool_descriptor_provenance

from cayu.tools import copy_tool_descriptor_provenance

Return a detached, fully revalidated provenance record.

copy_tool_descriptor_provenance(provenance: ToolDescriptorProvenance) -> ToolDescriptorProvenance

Release source · Runtime guarantees · Capability guides

FRAMEWORK_TOOL_NAMES

from cayu.tools import FRAMEWORK_TOOL_NAMES

FRAMEWORK_TOOL_NAMES = frozenset({CALL_TOOL_NAME, SEARCH_TOOLS_NAME, STRUCTURED_OUTPUT_TOOL_NAME})

Release source · Runtime guarantees · Capability guides

SEARCH_TOOLS_NAME

from cayu.tools import SEARCH_TOOLS_NAME

SEARCH_TOOLS_NAME = 'search_tools'

Release source · Runtime guarantees · Capability guides

STRUCTURED_OUTPUT_TOOL_NAME

from cayu.tools import STRUCTURED_OUTPUT_TOOL_NAME

STRUCTURED_OUTPUT_TOOL_NAME = '__cayu_submit_structured_output'

Release source · Runtime guarantees · Capability guides

tool_catalogue_descriptors_within_ceiling

from cayu.tools import tool_catalogue_descriptors_within_ceiling

Return the canonical catalogue view admitted by a durable name ceiling.

tool_catalogue_descriptors_within_ceiling(snapshot: ToolCatalogSnapshot, tool_names: Iterable[str]) -> tuple[ToolDescriptor, ...]

Release source · Runtime guarantees · Capability guides

TOOL_CATALOGUE_MAX_BYTES

from cayu.tools import TOOL_CATALOGUE_MAX_BYTES

TOOL_CATALOGUE_MAX_BYTES = 32 * 1024 * 1024

Release source · Runtime guarantees · Capability guides

TOOL_CATALOGUE_MAX_TOOLS

from cayu.tools import TOOL_CATALOGUE_MAX_TOOLS

TOOL_CATALOGUE_MAX_TOOLS = 10000

Release source · Runtime guarantees · Capability guides

TOOL_CATALOGUE_SCHEMA_VERSION

from cayu.tools import TOOL_CATALOGUE_SCHEMA_VERSION

TOOL_CATALOGUE_SCHEMA_VERSION = 1

Release source · Runtime guarantees · Capability guides

TOOL_DESCRIPTOR_SCHEMA_VERSION

from cayu.tools import TOOL_DESCRIPTOR_SCHEMA_VERSION

TOOL_DESCRIPTOR_SCHEMA_VERSION = 4

Release source · Runtime guarantees · Capability guides

TOOL_ID_MAX_CHARS

from cayu.tools import TOOL_ID_MAX_CHARS

TOOL_ID_MAX_CHARS = 512

Release source · Runtime guarantees · Capability guides

ToolCatalogSnapshot

from cayu.tools import ToolCatalogSnapshot

Immutable, deterministically ordered canonical tool catalogue.

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
schema_version	Literal[1]	TOOL_CATALOGUE_SCHEMA_VERSION
descriptors	tuple[ToolDescriptor, ...]	()
descriptor_count	StrictInt	Field(ge=0, le=TOOL_CATALOGUE_MAX_TOOLS)
revision	str	Field(default='', pattern='^(?:|sha256:[0-9a-f]{64})$')

validate_schema_version (method)

ToolCatalogSnapshot.validate_schema_version(value: object) -> object

copy_descriptors (method)

ToolCatalogSnapshot.copy_descriptors(value: object) -> tuple[ToolDescriptor, ...]

validate_and_bind_revision (method)

ToolCatalogSnapshot.validate_and_bind_revision() -> ToolCatalogSnapshot

descriptor_for_name (method)

ToolCatalogSnapshot.descriptor_for_name(name: str) -> ToolDescriptor

Return one copied descriptor by its model-visible registered name.

descriptor_for_id (method)

ToolCatalogSnapshot.descriptor_for_id(tool_id: str) -> ToolDescriptor

Return one copied descriptor by its canonical tool identity.

Release source · Runtime guarantees · Capability guides

ToolDescriptor

from cayu.tools import ToolDescriptor

Immutable canonical contract for one runtime-admitted tool.

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
schema_version	Literal[4]	TOOL_DESCRIPTOR_SCHEMA_VERSION
tool_id	str	''
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, ...]	()
auxiliary_inference	AuxiliaryInferencePolicy | None	None
provenance	ToolDescriptorProvenance	Field(default_factory=ToolDescriptorProvenance)
schema_fingerprint	str	Field(default='', pattern='^(?:|sha256:[0-9a-f]{64})$')
version	str	Field(default='', pattern='^(?:|sha256:[0-9a-f]{64})$')

copy_execution_requirements (method)

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

copy_auxiliary_inference (method)

ToolDescriptor.copy_auxiliary_inference(value: object) -> AuxiliaryInferencePolicy | None

validate_schema_version (method)

ToolDescriptor.validate_schema_version(value: object) -> object

validate_name (method)

ToolDescriptor.validate_name(value: str) -> str

validate_description (method)

ToolDescriptor.validate_description(value: str) -> str

copy_input_schema (method)

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

freeze_input_schema (method)

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

serialize_input_schema (method)

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

copy_provenance (method)

ToolDescriptor.copy_provenance(value: object) -> object

validate_and_bind_identity (method)

ToolDescriptor.validate_and_bind_identity() -> ToolDescriptor

input_schema_copy (method)

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

Return an owned ordinary-JSON schema copy.

exposure_capability_material (method)

ToolDescriptor.exposure_capability_material() -> dict[str, Any]

Return the existing callable-free exposure-policy projection.

execution_profile_material (method)

ToolDescriptor.execution_profile_material() -> dict[str, Any]

Return compact material for the durable ordered direct-tools component.

Release source · Runtime guarantees · Capability guides

ToolDescriptorProvenance

from cayu.tools import ToolDescriptorProvenance

Callable-free origin evidence for one canonical descriptor.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
kind	Literal['cayu', 'mcp']	'cayu'
source_id	str | None	None
source_tool_fingerprint	str | None	Field(default=None, pattern=_SHA256_IDENTIFIER_PATTERN)
source_contract_fingerprint	str | None	Field(default=None, pattern=_SHA256_IDENTIFIER_PATTERN)

validate_optional_text (method)

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

validate_shape (method)

ToolDescriptorProvenance.validate_shape() -> ToolDescriptorProvenance

Release source · Runtime guarantees · Capability guides

ToolExecutionContract

from cayu.tools import ToolExecutionContract

Callable-free evidence for the boundary that executes one tool.

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
boundary	Literal['in_process', 'posix_process']	'in_process'
timeout_strength	Literal['none', 'cooperative_in_process', 'hard_process_deadline']	'none'
sandboxed	StrictBool	False
adapter_identity	ExecutionProfileBehaviorIdentity | None	None
adapter_configuration_sha256	str | None	Field(default=None, pattern=_SHA256_IDENTIFIER_PATTERN)
hard_deadline_seconds	float | None	None
protocol	str | None	None
protocol_version	StrictInt | None	None
max_terminal_payload_bytes	StrictInt | None	Field(default=None, ge=64 * 1024, le=MAX_DURABLE_JSON_INTEGER)

copy_adapter_identity (method)

ToolExecutionContract.copy_adapter_identity(value: object) -> object

validate_optional_protocol (method)

ToolExecutionContract.validate_optional_protocol(value: str | None) -> str | None

validate_optional_deadline (method)

ToolExecutionContract.validate_optional_deadline(value: object) -> object

validate_shape (method)

ToolExecutionContract.validate_shape() -> ToolExecutionContract

Release source · Runtime guarantees · Capability guides

validate_application_tool_name

from cayu.tools import validate_application_tool_name

Validate one registered application name against Cayu’s framework namespace.

validate_application_tool_name(value: str) -> str

Release source · Runtime guarantees · Capability guides