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

ArtifactStoreHandle

from cayu.tools import ArtifactStoreHandle

Structural contract for the artifact store handed to tools.

Mirrors cayu.artifacts.ArtifactStore.

Decorators: @runtime_checkable.

Bases: Protocol.

put_bytes (method)

async ArtifactStoreHandle.put_bytes(content: bytes, *, filename: str, **kwargs: Any) -> Any

read_bytes (method)

async ArtifactStoreHandle.read_bytes(artifact_id: str, *, max_bytes: int | None=None) -> Any

list (method)

async ArtifactStoreHandle.list(**kwargs: Any) -> Any

delete (method)

async ArtifactStoreHandle.delete(artifact_id: str) -> None

Release source · Runtime guarantees · Capability guides

CredentialProxyHandle

from cayu.tools import CredentialProxyHandle

Structural contract for the credential proxy handed to tools.

Mirrors cayu.proxies.CredentialProxy.

Decorators: @runtime_checkable.

Bases: Protocol.

resolve (method)

async CredentialProxyHandle.resolve(ref: Any, *, scope: dict[str, Any] | None=None) -> Any

authorize_request (method)

async CredentialProxyHandle.authorize_request(*, destination: str, credential: Any=None, action: str | None=None, metadata: dict[str, Any] | None=None) -> Any

Release source · Runtime guarantees · Capability guides

KnowledgeStoreHandle

from cayu.tools import KnowledgeStoreHandle

Structural contract for the knowledge store handed to tools.

Deliberately the minimal read surface (search/list/read) so read-only stores can back read-path knowledge tools. Full read/write stores such as cayu.storage.memory.KnowledgeStore are a superset and also satisfy it; write-path tools check for their extra methods at call time.

Decorators: @runtime_checkable.

Bases: Protocol.

search (method)

async KnowledgeStoreHandle.search(*args: Any, **kwargs: Any) -> Any

list_entries (method)

async KnowledgeStoreHandle.list_entries(*args: Any, **kwargs: Any) -> Any

read_chunks (method)

async KnowledgeStoreHandle.read_chunks(*args: Any, **kwargs: Any) -> Any

Release source · Runtime guarantees · Capability guides

RunnerHandle

from cayu.tools import RunnerHandle

Narrow invocation-aware command capability handed to tools.

Runtime-created contexts redact output with the invocation’s current secret scope before a runner capture limit can discard matching context. Lifecycle methods and raw runner identity are deliberately not part of this contract.

Decorators: @runtime_checkable.

Bases: Protocol.

exec (method)

async RunnerHandle.exec(command: ExecCommand, *, cwd: str | None=None, env: dict[str, str] | None=None, env_remove: tuple[str, ...]=(), timeout_s: int | None=None, stdin: str | None=None, output_limit_bytes: int | None=...) -> ExecResult

Release source · Runtime guarantees · Capability guides

Tool

from cayu.tools import Tool

Base class for Cayu’s native Python tools.

Subclasses declare a ToolSpec and implement run with async def. Registration validates both contracts before a session can execute the tool.

A native tool runs inside the trusted Cayu application process. Tool policy authorizes model-requested calls; it does not sandbox the Python implementation. Put model-authored or otherwise untrusted code behind an admitted runner or an independently governed external tool boundary.

Bases: ABC.

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
spec	ToolSpec	required

init (method)

Tool.__init__(spec: ToolSpec | None=None) -> None

name (property)

Tool.name() -> str

execution_profile_identity (property)

Tool.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Return the stable behavior declaration frozen with this tool’s spec.

retain_arguments_for_model (property)

Tool.retain_arguments_for_model() -> bool

Retain bounded redacted original inputs privately for the same profile.

Independent of audit publication; oversized and compacted-away inputs may be omitted. This does not grant knowledge read or activation rights.

description (property)

Tool.description() -> str

schema (property)

Tool.schema() -> dict[str, Any]

run (method)

async Tool.run(ctx: ToolContext, args: dict[str, Any]) -> ToolResult

Execute a tool call asynchronously and return a ToolResult.

Release source · Runtime guarantees · Capability guides

ToolContext

from cayu.tools import ToolContext

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
execution_deadline	ExecutionDeadline	Field(default_factory=current_execution_deadline, exclude_if=lambda boundary: boundary.expires_at is None)
image_decode_limits	dict[str, int] | None	Field(default=None, exclude_if=lambda value: value is None)
session_id	str	required
agent_name	str | None	None
environment_name	str | None	None
causal_budget_id	str | None	None
workspace_id	str | None	None
artifact_store_id	str | None	None
idempotency_key	str | None	None
workspace	WorkspaceHandle | None	Field(default=None, exclude=True)
artifact_store	ArtifactStoreHandle | None	Field(default=None, exclude=True)
runner	RunnerHandle | None	Field(default=None, exclude=True)
invocation_secret_redactor	Callable[[], Any] | None	Field(default=None, exclude=True)
invocation_secret_snapshot_provider	Callable[[], Any] | None	Field(default=None, exclude=True)
invocation_secret_capture_observer	Callable[[int], None] | None	Field(default=None, exclude=True)
vault	VaultHandle | None	Field(default=None, exclude=True)
proxy	CredentialProxyHandle | None	Field(default=None, exclude=True)
knowledge_store	KnowledgeStoreHandle | None	Field(default=None, exclude=True)
knowledge_access_scope	Any	Field(default=None, exclude=True)
mcp_servers	tuple[Any, ...]	Field(default_factory=tuple, exclude=True)
metadata	dict[str, Any]	Field(default_factory=dict)

inference (property)

ToolContext.inference() -> InferenceInvoker | None

Optional runtime-owned inference handle, valid only during this tool call.

workspace_reference_binding (method)

ToolContext.workspace_reference_binding() -> WorkspaceReferenceBinding

Observe the admitted workspace after factory materialization and binding.

A detached/deserialized context has no live authority and fails closed. Public workspace_id and application metadata cannot supply this authority.

require_workspace_binding (method)

ToolContext.require_workspace_binding(binding: WorkspaceReferenceBinding) -> None

Reject a foreign or unavailable binding before consuming its claims.

copy_metadata (method)

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

validate_nonblank_session_id (method)

ToolContext.validate_nonblank_session_id(value: str, info) -> str

validate_optional_nonblank_ids (method)

ToolContext.validate_optional_nonblank_ids(value: str | None, info) -> str | None

copy_mcp_servers (method)

ToolContext.copy_mcp_servers(value)

Release source · Runtime guarantees · Capability guides

ToolEffect

from cayu.tools import ToolEffect

Declared side-effect semantics for a tool execution.

Classify what replay can do to externally meaningful durable state. NONE does not mutate it, IDEMPOTENT may mutate it but a stable downstream identity or equivalent contract collapses replay, and EXTERNAL has a non-idempotent or outcome-ambiguous durable mutation. Transport, billing, observability, and names such as “read” do not determine the value.

The runtime uses this as execution metadata, not as an authorization decision: policy still decides whether a call may run. Run cayu guide tool-effects for the canonical decision table.

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
NONE	class attribute	'none'
IDEMPOTENT	class attribute	'idempotent'
EXTERNAL	class attribute	'external'

Release source · Runtime guarantees · Capability guides

ToolExecutableRequirement

from cayu import ToolExecutableRequirement

An exact executable dependency, with an optional bounded process probe.

probe_arguments=None asks for executable availability without invoking the workload. Explicit arguments select a process-form probe and become part of its evidence identity; no shell command string is accepted.

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['executable']	'executable'
executable	str	Field(max_length=4096)
probe_arguments	tuple[str, ...] | None	Field(default=None, max_length=MAX_TOOL_EXECUTABLE_PROBE_ARGUMENTS)
accepted_exit_codes	tuple[StrictInt, ...]	Field(default=(0,), min_length=1, max_length=MAX_TOOL_EXECUTABLE_PROBE_EXIT_CODES)

validate_executable (method)

ToolExecutableRequirement.validate_executable(value: str) -> str

fingerprint (property)

ToolExecutableRequirement.fingerprint() -> str

Bind executable availability to the exact bounded probe contract.

copy_probe_arguments (method)

ToolExecutableRequirement.copy_probe_arguments(value: object) -> tuple[Any, ...] | None

validate_probe_arguments (method)

ToolExecutableRequirement.validate_probe_arguments(value: tuple[str, ...] | None) -> tuple[str, ...] | None

copy_accepted_exit_codes (method)

ToolExecutableRequirement.copy_accepted_exit_codes(value: object) -> tuple[Any, ...]

validate_accepted_exit_codes (method)

ToolExecutableRequirement.validate_accepted_exit_codes(value: tuple[int, ...]) -> tuple[int, ...]

validate_availability_probe (method)

ToolExecutableRequirement.validate_availability_probe()

Release source · Runtime guarantees · Capability guides

ToolExecutionRequirement

from cayu import ToolExecutionRequirement

One required tool facility represented by ordered compatible alternatives.

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	Field(max_length=96, pattern='^[a-z][a-z0-9_]{0,95}$')
alternatives	tuple[ToolExecutionRequirementAlternative, ...]	Field(min_length=1, max_length=MAX_TOOL_EXECUTION_ALTERNATIVES)

copy_alternatives (method)

ToolExecutionRequirement.copy_alternatives(value: object) -> tuple[Any, ...]

validate_unique_alternatives (method)

ToolExecutionRequirement.validate_unique_alternatives() -> ToolExecutionRequirement

Release source · Runtime guarantees · Capability guides

ToolResult

from cayu.tools import ToolResult

Result returned from a tool call.

content is the model-facing summary. structured and artifacts are for dashboards, workflows, storage, and downstream tools.

Frozen: results own their payloads (copied at construction) and are treated as read-only once returned from a 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
content	str	''
structured	Mapping[str, Any] | None	None
artifacts	Sequence[Mapping[str, Any]]	Field(default_factory=list)
is_error	StrictBool	False

copy_result_data (method)

ToolResult.copy_result_data(value, info)

freeze_result_data (method)

ToolResult.freeze_result_data(value: Any) -> Any

serialize_structured (method)

ToolResult.serialize_structured(value: Mapping[str, Any] | None, handler: SerializerFunctionWrapHandler) -> dict[str, Any] | None

serialize_artifacts (method)

ToolResult.serialize_artifacts(value: Sequence[Mapping[str, Any]], handler: SerializerFunctionWrapHandler) -> list[dict[str, Any]]

validate_content (method)

ToolResult.validate_content(value: str) -> str

model_copy (method)

ToolResult.model_copy(*, update: Mapping[str, Any] | None=None, deep: bool=False) -> ToolResult

Release source · Runtime guarantees · Capability guides

ToolRunnerCapabilityRequirement

from cayu import ToolRunnerCapabilityRequirement

One typed runner-native alternative owned by a tool contract.

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['runner_capability']	'runner_capability'
capability	str	Field(max_length=96, pattern='^[a-z][a-z0-9_]{0,95}$')
minimum_evidence	Literal['available', 'live_verified']	'live_verified'

Release source · Runtime guarantees · Capability guides

ToolSpec

from cayu.tools import ToolSpec

Immutable public declaration for a native Python tool.

input_schema is the default JSON Schema exposed through Tool.schema. Tool subclasses may override that property when the runtime schema is derived; registration treats the public property as authoritative.

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	''
parallel_safe	StrictBool	True
effect	ToolEffect	ToolEffect.EXTERNAL
workspace_mutation	StrictBool	False
max_terminal_payload_bytes	StrictInt | None	Field(default=None, ge=64 * 1024, le=MAX_DURABLE_JSON_INTEGER)
execution_profile_identity	ExecutionProfileBehaviorIdentity | None	None
auxiliary_inference	AuxiliaryInferencePolicy | None	None
execution_requirements	tuple[ToolExecutionRequirement, ...]	()

init (method)

ToolSpec.__init__(*, name: str, description: str='', input_schema: dict[str, Any] | None=None, parallel_safe: bool=True, effect: ToolEffect=ToolEffect.EXTERNAL, workspace_mutation: bool=False, max_terminal_payload_bytes: int | None=None, execution_profile_identity: ExecutionProfileBehaviorIdentity | None=None, auxiliary_inference: AuxiliaryInferencePolicy | None=None, execution_requirements: Iterable[ToolExecutionRequirement]=(), **data: Any) -> None

input_schema (property)

ToolSpec.input_schema() -> dict[str, Any]

serialize_effect (method)

ToolSpec.serialize_effect(value: ToolEffect) -> str

model_copy (method)

ToolSpec.model_copy(*, update: Mapping[str, Any] | None=None, deep: bool=False) -> ToolSpec

model_json_schema (method)

ToolSpec.model_json_schema(*args: Any, **kwargs: Any) -> dict[str, Any]

Release source · Runtime guarantees · Capability guides

VaultHandle

from cayu.tools import VaultHandle

Structural contract for the vault handed to tools.

Mirrors cayu.vaults.Vault.

Decorators: @runtime_checkable.

Bases: Protocol.

get (method)

async VaultHandle.get(name: str, *, scope: dict[str, Any] | None=None) -> Any

resolve (method)

async VaultHandle.resolve(ref: Any, *, scope: dict[str, Any] | None=None) -> Any

Release source · Runtime guarantees · Capability guides

WorkspaceHandle

from cayu.tools import WorkspaceHandle

Structural contract for the workspace handed to tools.

Mirrors cayu.workspaces.Workspace without importing it, so custom workspaces only need to implement the file operations tools rely on.

Decorators: @runtime_checkable.

Bases: Protocol.

read_bytes (method)

async WorkspaceHandle.read_bytes(path: str, *, offset: int=0, max_bytes: int | None=None) -> Any

write_bytes (method)

async WorkspaceHandle.write_bytes(path: str, content: bytes) -> None

delete (method)

async WorkspaceHandle.delete(path: str) -> None

create_bytes (method)

async WorkspaceHandle.create_bytes(path: str, content: bytes) -> Any

replace_bytes (method)

async WorkspaceHandle.replace_bytes(path: str, content: bytes, *, expected_revision: str) -> Any

delete_if_revision (method)

async WorkspaceHandle.delete_if_revision(path: str, *, expected_revision: str) -> Any

list (method)

async WorkspaceHandle.list(pattern: str='**/*', *, limit: int | None=None) -> Any

Release source · Runtime guarantees · Capability guides