cayu.tools.isolated

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.

ProcessIsolatedTool

from cayu.tools import ProcessIsolatedTool

Explicit host-side tool executed by Cayu in a disposable POSIX process.

Decorators: @final.

Bases: Tool.

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)

ProcessIsolatedTool.__init__(spec: ToolSpec, *, factory: ProcessIsolatedToolFactoryRef, limits: ProcessIsolatedToolLimits, factory_config: dict[str, Any] | None=None, context_projection: ProcessIsolatedToolContextProjection | None=None, environment: dict[str, str] | None=None) -> None

name (property)

ProcessIsolatedTool.name() -> str

execution_profile_identity (property)

ProcessIsolatedTool.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

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

retain_arguments_for_model (property)

ProcessIsolatedTool.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)

ProcessIsolatedTool.description() -> str

schema (property)

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

run (method)

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

factory (property)

ProcessIsolatedTool.factory() -> ProcessIsolatedToolFactoryRef

limits (property)

ProcessIsolatedTool.limits() -> ProcessIsolatedToolLimits

context_projection (property)

ProcessIsolatedTool.context_projection() -> ProcessIsolatedToolContextProjection

factory_config_copy (method)

ProcessIsolatedTool.factory_config_copy() -> dict[str, Any]

environment_copy (method)

ProcessIsolatedTool.environment_copy() -> dict[str, str]

Release source · Runtime guarantees · Capability guides

ProcessIsolatedToolContext

from cayu.tools import ProcessIsolatedToolContext

Portable context received by an isolated tool handler.

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=ExecutionDeadline, exclude_if=lambda boundary: boundary.expires_at is None)
session_id	str | None	None
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
metadata	dict[str, Any]	Field(default_factory=dict)

validate_optional_text (method)

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

copy_metadata (method)

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

Release source · Runtime guarantees · Capability guides

ProcessIsolatedToolContextProjection

from cayu.tools import ProcessIsolatedToolContextProjection

Explicit JSON-only projection of runtime context exposed to the child.

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
fields	tuple[IsolatedToolContextField, ...]	()
metadata_keys	tuple[str, ...]	()

normalize_fields (method)

ProcessIsolatedToolContextProjection.normalize_fields(value: object) -> tuple[object, ...]

normalize_metadata_keys (method)

ProcessIsolatedToolContextProjection.normalize_metadata_keys(value: object) -> tuple[str, ...]

Release source · Runtime guarantees · Capability guides

ProcessIsolatedToolFactoryRef

from cayu.tools import ProcessIsolatedToolFactoryRef

Stable import reference for a child-only isolated-tool factory.

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
module	str	Field(max_length=512)
qualname	str	Field(max_length=512)
identity	ExecutionProfileBehaviorIdentity	required

validate_import_reference (method)

ProcessIsolatedToolFactoryRef.validate_import_reference(value: str, info) -> str

copy_identity (method)

ProcessIsolatedToolFactoryRef.copy_identity(value: object) -> object

Release source · Runtime guarantees · Capability guides

ProcessIsolatedToolLimits

from cayu.tools import ProcessIsolatedToolLimits

Hard deadline and bounded transport limits for one isolated 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
deadline_seconds	float	required
term_grace_seconds	float	1.0
kill_grace_seconds	float	1.0
max_request_bytes	StrictInt	Field(default=DEFAULT_ISOLATED_TOOL_MAX_REQUEST_BYTES, ge=1024, le=MAX_ISOLATED_TOOL_MESSAGE_BYTES)
max_response_bytes	StrictInt	Field(default=DEFAULT_ISOLATED_TOOL_MAX_RESPONSE_BYTES, ge=1024, le=MAX_ISOLATED_TOOL_MESSAGE_BYTES)
max_stdout_bytes	StrictInt	Field(default=DEFAULT_ISOLATED_TOOL_MAX_STDOUT_BYTES, ge=0, le=MAX_ISOLATED_TOOL_DIAGNOSTIC_STREAM_BYTES)
max_stderr_bytes	StrictInt	Field(default=DEFAULT_ISOLATED_TOOL_MAX_STDERR_BYTES, ge=0, le=MAX_ISOLATED_TOOL_DIAGNOSTIC_STREAM_BYTES)

validate_deadline (method)

ProcessIsolatedToolLimits.validate_deadline(value: object) -> float

validate_term_grace (method)

ProcessIsolatedToolLimits.validate_term_grace(value: object) -> float

validate_kill_grace (method)

ProcessIsolatedToolLimits.validate_kill_grace(value: object) -> float

Release source · Runtime guarantees · Capability guides

ToolExecutionBoundary

from cayu.tools import ToolExecutionBoundary

Runtime boundary that owns one tool implementation.

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
IN_PROCESS	class attribute	'in_process'
POSIX_PROCESS	class attribute	'posix_process'

Release source · Runtime guarantees · Capability guides

ToolTimeoutStrength

from cayu.tools import ToolTimeoutStrength

Truthful strength of one configured tool deadline.

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'
COOPERATIVE_IN_PROCESS	class attribute	'cooperative_in_process'
HARD_PROCESS_DEADLINE	class attribute	'hard_process_deadline'

Release source · Runtime guarantees · Capability guides