cayu.tools.discovery

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.

TOOL_DISCOVERY_INSPECTION_MAX_GRANTS

from cayu.tools import TOOL_DISCOVERY_INSPECTION_MAX_GRANTS

TOOL_DISCOVERY_INSPECTION_MAX_GRANTS = TOOL_DISCOVERY_MAX_GRANTS

Release source · Runtime guarantees · Capability guides

ToolDiscoveryGrantInspection

from cayu.tools import ToolDiscoveryGrantInspection

Content-minimized discovery grant state safe for control-plane reads.

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_DISCOVERY_SCHEMA_VERSION
tool_id	str	required
tool_name	str	required
descriptor_version	str	required
schema_fingerprint	str	Field(pattern=TARGETED_TOOL_DIGEST_PATTERN)
created_at	datetime	required
discovered_revision	StrictInt	Field(ge=1, le=TOOL_DISCOVERY_MAX_GRANTS)

validate_schema_version (method)

ToolDiscoveryGrantInspection.validate_schema_version(value: object) -> object

validate_tool_id (method)

ToolDiscoveryGrantInspection.validate_tool_id(value: str) -> str

validate_tool_name (method)

ToolDiscoveryGrantInspection.validate_tool_name(value: str) -> str

validate_descriptor_version (method)

ToolDiscoveryGrantInspection.validate_descriptor_version(value: str) -> str

normalize_created_at (method)

ToolDiscoveryGrantInspection.normalize_created_at(value: datetime) -> datetime

Release source · Runtime guarantees · Capability guides

ToolDiscoveryGrantRecord

from cayu.tools import ToolDiscoveryGrantRecord

One persistent, branch-local addressability grant created by search.

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_DISCOVERY_SCHEMA_VERSION
grant_id	str	Field(pattern=TARGETED_TOOL_DIGEST_PATTERN)
tool_ref	str	Field(pattern=TOOL_DISCOVERY_REFERENCE_PATTERN)
tool_id	str	required
tool_name	str	required
catalogue_revision	str	required
descriptor_version	str	required
schema_fingerprint	str	Field(pattern=TARGETED_TOOL_DIGEST_PATTERN)
origin_query_sha256	str	Field(pattern=TARGETED_TOOL_DIGEST_PATTERN)
origin_model_step_id	str	required
created_at	datetime	required
discovered_revision	StrictInt	Field(ge=1, le=TOOL_DISCOVERY_MAX_GRANTS)

validate_schema_version (method)

ToolDiscoveryGrantRecord.validate_schema_version(value: object) -> object

validate_tool_ref (method)

ToolDiscoveryGrantRecord.validate_tool_ref(value: str) -> str

validate_bounded_text (method)

ToolDiscoveryGrantRecord.validate_bounded_text(value: str, info) -> str

validate_tool_id (method)

ToolDiscoveryGrantRecord.validate_tool_id(value: str) -> str

validate_catalogue_revision (method)

ToolDiscoveryGrantRecord.validate_catalogue_revision(value: str) -> str

validate_descriptor_version (method)

ToolDiscoveryGrantRecord.validate_descriptor_version(value: str) -> str

normalize_created_at (method)

ToolDiscoveryGrantRecord.normalize_created_at(value: datetime) -> datetime

Release source · Runtime guarantees · Capability guides

ToolDiscoveryMode

from cayu.tools import ToolDiscoveryMode

Application-selected tool-discovery delivery policy.

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
SEARCH_TOOLS	class attribute	SEARCH_TOOLS_NAME
OPENAI_TOOL_SEARCH_CLIENT	class attribute	'openai_tool_search_client'
OPENAI_TOOL_SEARCH_CLIENT_OR_SEARCH_TOOLS	class attribute	'openai_tool_search_client_or_search_tools'
OPENAI_TOOL_SEARCH_HOSTED	class attribute	'openai_tool_search_hosted'
OPENAI_TOOL_SEARCH_HOSTED_OR_SEARCH_TOOLS	class attribute	'openai_tool_search_hosted_or_search_tools'

Release source · Runtime guarantees · Capability guides

ToolDiscoveryProjectionKind

from cayu.tools import ToolDiscoveryProjectionKind

One concrete provider projection selected for an invocation.

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
SEARCH_TOOLS	class attribute	SEARCH_TOOLS_NAME
OPENAI_TOOL_SEARCH_CLIENT	class attribute	'openai_tool_search_client'
OPENAI_TOOL_SEARCH_HOSTED	class attribute	'openai_tool_search_hosted'

Release source · Runtime guarantees · Capability guides

ToolDiscoverySearchMatch

from cayu.tools import ToolDiscoverySearchMatch

Bounded model-facing descriptor returned by search_tools.

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
tool_ref	str	Field(pattern=TOOL_DISCOVERY_REFERENCE_PATTERN)
tool_id	str	required
name	str	required
description	str	required
input_schema	Mapping[str, Any]	required
descriptor_version	str	required
schema_fingerprint	str	Field(pattern=TARGETED_TOOL_DIGEST_PATTERN)
readiness	Literal['registered']	'registered'

validate_tool_ref (method)

ToolDiscoverySearchMatch.validate_tool_ref(value: str) -> str

validate_tool_id (method)

ToolDiscoverySearchMatch.validate_tool_id(value: str) -> str

validate_name (method)

ToolDiscoverySearchMatch.validate_name(value: str) -> str

validate_description (method)

ToolDiscoverySearchMatch.validate_description(value: str) -> str

copy_schema (method)

ToolDiscoverySearchMatch.copy_schema(value: object) -> dict[str, Any]

freeze_schema (method)

ToolDiscoverySearchMatch.freeze_schema(value: Mapping[str, Any]) -> Mapping[str, Any]

serialize_schema (method)

ToolDiscoverySearchMatch.serialize_schema(value: Mapping[str, Any]) -> dict[str, Any]

validate_descriptor_version (method)

ToolDiscoverySearchMatch.validate_descriptor_version(value: str) -> str

validate_schema_fingerprint (method)

ToolDiscoverySearchMatch.validate_schema_fingerprint() -> ToolDiscoverySearchMatch

Release source · Runtime guarantees · Capability guides

ToolDiscoverySearchResult

from cayu.tools import ToolDiscoverySearchResult

Deterministic result and durable view revision from one catalogue search.

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_DISCOVERY_SCHEMA_VERSION
query	str	required
matches	tuple[ToolDiscoverySearchMatch, ...]	required
view_revision	StrictInt	Field(ge=0)
truncated	StrictBool	False

validate_schema_version (method)

ToolDiscoverySearchResult.validate_schema_version(value: object) -> object

validate_query (method)

ToolDiscoverySearchResult.validate_query(value: str) -> str

bound_matches (method)

ToolDiscoverySearchResult.bound_matches(value: object) -> object

bound_serialized_result (method)

ToolDiscoverySearchResult.bound_serialized_result() -> ToolDiscoverySearchResult

Release source · Runtime guarantees · Capability guides

ToolDiscoveryViewInconsistentError

from cayu.tools import ToolDiscoveryViewInconsistentError

Raised when durable view state conflicts with current session authority.

Bases: RuntimeError.

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

Release source · Runtime guarantees · Capability guides

ToolDiscoveryViewInitialization

from cayu.tools import ToolDiscoveryViewInitialization

Typed authority needed to initialize one session-local discovery view.

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
session_id	str	required
agent_name	str	required
catalogue_revision	str	required
ceiling_fingerprint	str	Field(pattern=TARGETED_TOOL_DIGEST_PATTERN)

validate_required_text (method)

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

validate_catalogue_revision (method)

ToolDiscoveryViewInitialization.validate_catalogue_revision(value: str) -> str

Release source · Runtime guarantees · Capability guides

ToolDiscoveryViewInspection

from cayu.tools import ToolDiscoveryViewInspection

Bounded current-view projection without schemas or callable references.

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_DISCOVERY_SCHEMA_VERSION
session_id	str	required
generation_id	str	Field(pattern=TARGETED_TOOL_DIGEST_PATTERN)
agent_name	str	required
catalogue_revision	str	required
ceiling_fingerprint	str	Field(pattern=TARGETED_TOOL_DIGEST_PATTERN)
revision	StrictInt	Field(ge=0, le=TOOL_DISCOVERY_MAX_GRANTS)
grant_count	StrictInt	Field(ge=0, le=TOOL_DISCOVERY_MAX_GRANTS)
grants	tuple[ToolDiscoveryGrantInspection, ...]	()
grants_truncated	StrictBool	required

validate_schema_version (method)

ToolDiscoveryViewInspection.validate_schema_version(value: object) -> object

validate_required_text (method)

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

validate_catalogue_revision (method)

ToolDiscoveryViewInspection.validate_catalogue_revision(value: str) -> str

bound_grants (method)

ToolDiscoveryViewInspection.bound_grants(value: object) -> object

validate_projection (method)

ToolDiscoveryViewInspection.validate_projection() -> ToolDiscoveryViewInspection

Release source · Runtime guarantees · Capability guides

ToolDiscoveryViewNotEnabledError

from cayu.tools import ToolDiscoveryViewNotEnabledError

Raised when a session has no configured discovery view.

Bases: RuntimeError.

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

Release source · Runtime guarantees · Capability guides

ToolDiscoveryViewState

from cayu.tools import ToolDiscoveryViewState

Versioned durable tool view for one session branch.

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_DISCOVERY_SCHEMA_VERSION
session_id	str	required
generation_id	str	Field(pattern=TARGETED_TOOL_DIGEST_PATTERN)
agent_name	str	required
catalogue_revision	str	required
ceiling_fingerprint	str	Field(pattern=TARGETED_TOOL_DIGEST_PATTERN)
revision	StrictInt	Field(ge=0, le=TOOL_DISCOVERY_MAX_GRANTS)
grants	tuple[ToolDiscoveryGrantRecord, ...]	()

validate_schema_version (method)

ToolDiscoveryViewState.validate_schema_version(value: object) -> object

validate_required_text (method)

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

validate_catalogue_revision (method)

ToolDiscoveryViewState.validate_catalogue_revision(value: str) -> str

bound_grants (method)

ToolDiscoveryViewState.bound_grants(value: object) -> object

validate_grants (method)

ToolDiscoveryViewState.validate_grants() -> ToolDiscoveryViewState

record_for_reference (method)

ToolDiscoveryViewState.record_for_reference(tool_ref: str) -> ToolDiscoveryGrantRecord | None

Resolve an exact opaque reference inside this view.

Release source · Runtime guarantees · Capability guides