cayu.tools.files

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.

ArtifactReader

from cayu.tools import ArtifactReader

Extension point for artifact-specific read behavior.

Bases: Protocol.

can_read (method)

ArtifactReader.can_read(artifact: ArtifactMetadata) -> bool

Return true when this reader handles the artifact.

read (method)

async ArtifactReader.read(request: ArtifactReadRequest) -> ToolResult

Read the artifact and return a model-facing tool result.

Release source · Runtime guarantees · Capability guides

ArtifactReadRequest

from cayu.tools import ArtifactReadRequest

Decorators: @dataclass(frozen=True).

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
ctx	ToolContext	required
artifact_store	ArtifactStore	required
artifact	ArtifactMetadata	required
initial_read	ArtifactReadResult	required
options	ReadFileOptions	required
structured	dict	required

Release source · Runtime guarantees · Capability guides

default_artifact_readers

from cayu.tools import default_artifact_readers

default_artifact_readers() -> tuple[ArtifactReader, ...]

Release source · Runtime guarantees · Capability guides

DeleteFileTool

from cayu.tools import DeleteFileTool

Delete one workspace file only when its content precondition matches.

Bases: Tool.

init (method)

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

name (property)

DeleteFileTool.name() -> str

execution_profile_identity (property)

DeleteFileTool.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

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

retain_arguments_for_model (property)

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

DeleteFileTool.description() -> str

schema (property)

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

run (method)

async DeleteFileTool.run(ctx: ToolContext, args: dict) -> ToolResult

Release source · Runtime guarantees · Capability guides

EditFileTool

from cayu.tools import EditFileTool

Apply exact text replacements to one existing workspace file.

Bases: Tool.

init (method)

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

name (property)

EditFileTool.name() -> str

execution_profile_identity (property)

EditFileTool.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

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

retain_arguments_for_model (property)

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

EditFileTool.description() -> str

schema (property)

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

run (method)

async EditFileTool.run(ctx: ToolContext, args: dict) -> ToolResult

Release source · Runtime guarantees · Capability guides

ImageArtifactReader

from cayu.tools import ImageArtifactReader

can_read (method)

ImageArtifactReader.can_read(artifact: ArtifactMetadata) -> bool

read (method)

async ImageArtifactReader.read(request: ArtifactReadRequest) -> ToolResult

Release source · Runtime guarantees · Capability guides

ListArtifactsTool

from cayu.tools import ListArtifactsTool

Bases: Tool.

init (method)

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

name (property)

ListArtifactsTool.name() -> str

execution_profile_identity (property)

ListArtifactsTool.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

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

retain_arguments_for_model (property)

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

ListArtifactsTool.description() -> str

schema (property)

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

run (method)

async ListArtifactsTool.run(ctx: ToolContext, args: dict) -> ToolResult

Release source · Runtime guarantees · Capability guides

ListFilesTool

from cayu.tools import ListFilesTool

Bases: Tool.

init (method)

ListFilesTool.__init__(*, exclude_directories: Iterable[str]=(), max_scan_entries: int=DEFAULT_LIST_SCAN_LIMIT) -> None

name (property)

ListFilesTool.name() -> str

execution_profile_identity (property)

ListFilesTool.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

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

retain_arguments_for_model (property)

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

ListFilesTool.description() -> str

schema (property)

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

run (method)

async ListFilesTool.run(ctx: ToolContext, args: dict) -> ToolResult

Release source · Runtime guarantees · Capability guides

PdfArtifactReader

from cayu.tools import PdfArtifactReader

can_read (method)

PdfArtifactReader.can_read(artifact: ArtifactMetadata) -> bool

read (method)

async PdfArtifactReader.read(request: ArtifactReadRequest) -> ToolResult

Release source · Runtime guarantees · Capability guides

ReadFileOptions

from cayu.tools import ReadFileOptions

Decorators: @dataclass(frozen=True).

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
max_bytes	int	DEFAULT_READ_LIMIT_BYTES
max_attachment_bytes	int	DEFAULT_ATTACHMENT_LIMIT_BYTES
max_attachment_validation_bytes	int	DEFAULT_MAX_ATTACHMENT_LIMIT_BYTES
pages	str | None	None
image_region	tuple[int, int, int, int] | None	None
offset	int	0

Release source · Runtime guarantees · Capability guides

ReadFileTool

from cayu.tools import ReadFileTool

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	class attribute	_read_file_tool_spec(default_attachment_limit_bytes=DEFAULT_ATTACHMENT_LIMIT_BYTES, max_attachment_limit_bytes=DEFAULT_MAX_ATTACHMENT_LIMIT_BYTES)

init (method)

ReadFileTool.__init__(*, extra_artifact_readers: Iterable[ArtifactReader] | None=None, artifact_readers: Iterable[ArtifactReader] | None=None, default_attachment_limit_bytes: int=DEFAULT_ATTACHMENT_LIMIT_BYTES, max_attachment_limit_bytes: int=DEFAULT_MAX_ATTACHMENT_LIMIT_BYTES, spec: ToolSpec | None=None) -> None

name (property)

ReadFileTool.name() -> str

execution_profile_identity (property)

ReadFileTool.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

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

retain_arguments_for_model (property)

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

ReadFileTool.description() -> str

schema (property)

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

run (method)

async ReadFileTool.run(ctx: ToolContext, args: dict) -> ToolResult

Release source · Runtime guarantees · Capability guides

TextArtifactReader

from cayu.tools import TextArtifactReader

can_read (method)

TextArtifactReader.can_read(artifact: ArtifactMetadata) -> bool

read (method)

async TextArtifactReader.read(request: ArtifactReadRequest) -> ToolResult

Release source · Runtime guarantees · Capability guides

WriteFileTool

from cayu.tools import WriteFileTool

Bases: Tool.

init (method)

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

name (property)

WriteFileTool.name() -> str

execution_profile_identity (property)

WriteFileTool.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

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

retain_arguments_for_model (property)

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

WriteFileTool.description() -> str

schema (property)

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

run (method)

async WriteFileTool.run(ctx: ToolContext, args: dict) -> ToolResult

Release source · Runtime guarantees · Capability guides