cayu.artifacts.attachments

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.

`DEFAULT_MAX_FILE_ATTACHMENT_BYTES`

from cayu.artifacts import DEFAULT_MAX_FILE_ATTACHMENT_BYTES

DEFAULT_MAX_FILE_ATTACHMENT_BYTES = 8 * 1024 * 1024

Release source · Runtime guarantees · Capability guides

`DEFAULT_MAX_FILE_ATTACHMENTS_PER_REQUEST`

from cayu.artifacts import DEFAULT_MAX_FILE_ATTACHMENTS_PER_REQUEST

DEFAULT_MAX_FILE_ATTACHMENTS_PER_REQUEST = 20

Release source · Runtime guarantees · Capability guides

`DEFAULT_MAX_TOTAL_FILE_ATTACHMENT_BYTES`

from cayu.artifacts import DEFAULT_MAX_TOTAL_FILE_ATTACHMENT_BYTES

DEFAULT_MAX_TOTAL_FILE_ATTACHMENT_BYTES = 32 * 1024 * 1024

Release source · Runtime guarantees · Capability guides

`file_attachment`

from cayu.artifacts import file_attachment

file_attachment(*, artifact_id: str, kind: FileAttachmentKind | str, filename: str, content_type: str, size_bytes: int, metadata: dict[str, Any] | None=None) -> dict[str, Any]

Release source · Runtime guarantees · Capability guides

`FILE_ATTACHMENT_DOCUMENT_CONTENT_TYPES`

from cayu.artifacts import FILE_ATTACHMENT_DOCUMENT_CONTENT_TYPES

FILE_ATTACHMENT_DOCUMENT_CONTENT_TYPES = frozenset({'application/pdf'})

Release source · Runtime guarantees · Capability guides

`file_attachment_from_payload`

from cayu.artifacts import file_attachment_from_payload

file_attachment_from_payload(payload: object) -> FileAttachment | None

Release source · Runtime guarantees · Capability guides

`FILE_ATTACHMENT_IMAGE_CONTENT_TYPES`

from cayu.artifacts import FILE_ATTACHMENT_IMAGE_CONTENT_TYPES

FILE_ATTACHMENT_IMAGE_CONTENT_TYPES = frozenset({'image/jpeg', 'image/png', 'image/gif', 'image/webp'})

Release source · Runtime guarantees · Capability guides

`FILE_ATTACHMENT_TYPE`

from cayu.artifacts import FILE_ATTACHMENT_TYPE

FILE_ATTACHMENT_TYPE = 'cayu.file_attachment.v1'

Release source · Runtime guarantees · Capability guides

`FileAttachment`

from cayu.artifacts import FileAttachment

Provider-neutral model-facing artifact reference.

This record is JSON-safe and safe to persist in tool results. It does not contain file bytes. The runtime resolves it from the active ArtifactStore immediately before a provider request.

Repeated references to one artifact must agree on all fields except metadata.source_artifact_id, which describes the source snapshot for that read, not resolution authority. Native image/PDF derivations may reuse one artifact for identical source bytes. Each occurrence retains its metadata in the transcript; the request’s byte map uses the first occurrence.

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
`type`	`str`	`FILE_ATTACHMENT_TYPE`
`artifact_id`	`str`	`required`
`kind`	`FileAttachmentKind`	`required`
`filename`	`str`	`required`
`content_type`	`str`	`required`
`size_bytes`	`int`	`required`
`metadata`	`dict[str, Any]`	`Field(default_factory=dict)`

validate_type (method)

FileAttachment.validate_type(value: str) -> str

validate_clean_fields (method)

FileAttachment.validate_clean_fields(value: str, info) -> str

validate_filename (method)

FileAttachment.validate_filename(value: str, info) -> str

validate_size_bytes (method)

FileAttachment.validate_size_bytes(value: int, info) -> int

copy_metadata (method)

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

validate_kind_content_type (method)

FileAttachment.validate_kind_content_type() -> FileAttachment

Release source · Runtime guarantees · Capability guides

`FileAttachmentKind`

from cayu.artifacts import FileAttachmentKind

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`IMAGE`	`class attribute`	`'image'`
`DOCUMENT`	`class attribute`	`'document'`

Release source · Runtime guarantees · Capability guides

`resolved_file_attachment`

from cayu.artifacts import resolved_file_attachment

resolved_file_attachment(attachment: FileAttachment, result: ArtifactReadResult) -> dict[str, Any]

Release source · Runtime guarantees · Capability guides

`resolved_file_attachments_from_options`

from cayu.artifacts import resolved_file_attachments_from_options

resolved_file_attachments_from_options(options: dict[str, Any]) -> dict[str, dict[str, Any]]

Release source · Runtime guarantees · Capability guides

`RESOLVED_FILE_ATTACHMENTS_OPTION`

from cayu.artifacts import RESOLVED_FILE_ATTACHMENTS_OPTION

RESOLVED_FILE_ATTACHMENTS_OPTION = 'cayu_file_attachments'

Release source · Runtime guarantees · Capability guides

`ResolvedFileAttachment`

from cayu.artifacts import ResolvedFileAttachment

Provider-request-only attachment bytes encoded for JSON transport.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`artifact_id`	`str`	`required`
`kind`	`FileAttachmentKind`	`required`
`filename`	`str`	`required`
`content_type`	`str`	`required`
`data_base64`	`str`	`required`
`content_sha256`	`str \| None`	`None`
`metadata`	`dict[str, Any]`	`Field(default_factory=dict)`

validate_clean_fields (method)

ResolvedFileAttachment.validate_clean_fields(value: str, info) -> str

validate_nonblank_fields (method)

ResolvedFileAttachment.validate_nonblank_fields(value: str, info) -> str

validate_content_sha256 (method)

ResolvedFileAttachment.validate_content_sha256(value: str | None) -> str | None

copy_metadata (method)

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

validate_kind_content_type (method)

ResolvedFileAttachment.validate_kind_content_type() -> ResolvedFileAttachment

Release source · Runtime guarantees · Capability guides

`validate_file_attachment_bytes`

from cayu.artifacts import validate_file_attachment_bytes

Validate that content is a parseable image/PDF for kind, raising ValueError if not.

Parses the bytes with the optional file dependencies (cayu[files]): Pillow for images, pypdf for documents. Raises a clear ValueError when the bytes are not a valid image/PDF, or when the dependencies are not installed — so a caller cannot store a prompt attachment whose bytes a provider would later fail to serialize. When content_type is given for an image, the format detected from the bytes must match it (rejecting e.g. JPEG bytes labeled image/png). Optional host-owned image_decode_limits accepts positive integer max_frame_bytes, max_total_bytes and max_frames; omitted keys retain protective defaults.

validate_file_attachment_bytes(*, kind: FileAttachmentKind, content: bytes, content_type: str | None=None, image_decode_limits: Mapping[str, int] | None=None) -> None

Release source · Runtime guarantees · Capability guides

`validate_file_attachment_content_type`

from cayu.artifacts import validate_file_attachment_content_type

validate_file_attachment_content_type(*, kind: FileAttachmentKind, content_type: str) -> None

Release source · Runtime guarantees · Capability guides