cayu.messages

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.

`CitationPart`

from cayu.messages import CitationPart

Provider-neutral citation annotation over assistant text.

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`	`Literal['citation']`	`'citation'`
`citation_type`	`Literal['url_citation']`	`'url_citation'`
`url`	`str`	`Field(max_length=4096)`
`title`	`str \| None`	`Field(default=None, max_length=1024)`
`start_index`	`StrictInt \| None`	`Field(default=None, ge=0)`
`end_index`	`StrictInt \| None`	`Field(default=None, gt=0)`
`provenance`	`CitationProvenance`	`required`
`model_step_id`	`str`	`required`
`model_attempt_id`	`str`	`required`

validate_url (method)

CitationPart.validate_url(value: str) -> str

validate_title (method)

CitationPart.validate_title(value: str | None) -> str | None

validate_execution_identity (method)

CitationPart.validate_execution_identity(value: str, info) -> str

copy_provenance (method)

CitationPart.copy_provenance(value: object) -> CitationProvenance

validate_offsets (method)

CitationPart.validate_offsets() -> CitationPart

Release source · Runtime guarantees · Capability guides

`CitationProvenance`

from cayu.messages import CitationProvenance

Trust label for provider-hosted citation evidence.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`provider_name`	`str`	`Field(max_length=128)`
`hosted_tool`	`Literal['web_search']`	`'web_search'`
`untrusted_external_evidence`	`Literal[True]`	`True`

validate_provider_name (method)

CitationProvenance.validate_provider_name(value: str) -> str

Release source · Runtime guarantees · Capability guides

`FilePart`

from cayu.messages import FilePart

User-supplied file input (image or document) for a multimodal request.

attachment carries a JSON-safe cayu.file_attachment.v1 payload referencing a stored artifact — never file bytes. The runtime resolves the artifact from the active ArtifactStore immediately before each provider request, exactly like tool-result attachments.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`type`	`Literal['file']`	`'file'`
`attachment`	`dict[str, Any]`	`required`

validate_attachment (method)

FilePart.validate_attachment(value)

Release source · Runtime guarantees · Capability guides

`HostedToolCallPart`

from cayu.messages import HostedToolCallPart

Terminal provider-hosted execution evidence in an assistant transcript.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`type`	`Literal['hosted_tool_call']`	`'hosted_tool_call'`
`hosted_tool`	`Literal['web_search']`	`'web_search'`
`call_id`	`str`	`Field(max_length=512)`
`status`	`Literal['completed', 'incomplete', 'failed', 'outcome_unknown']`	`required`
`action`	`WebSearchAction \| None`	`None`
`provider_name`	`str`	`Field(max_length=128)`
`model`	`str`	`Field(max_length=512)`
`model_step_id`	`str`	`required`
`model_attempt_id`	`str`	`required`

validate_identity_text (method)

HostedToolCallPart.validate_identity_text(value: str, info) -> str

validate_execution_identity (method)

HostedToolCallPart.validate_execution_identity(value: str, info) -> str

copy_action (method)

HostedToolCallPart.copy_action(value: object) -> object

Release source · Runtime guarantees · Capability guides

`Message`

from cayu.messages import Message

Frozen transcript message.

Messages and their parts are immutable once constructed: attribute assignment is rejected, content is a tuple, and every part entering the message is copied so the message exclusively owns its JSON payloads. The freeze is shallow, though — nested payload dicts stay mutable — so sharing a validated instance is safe only while every holder treats payloads as read-only. Hot-path copy_message “copies” are no-ops under that contract; detach_message produces a genuinely isolated copy for storage/trust boundaries, and copy.deepcopy isolates as well.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`role`	`MessageRole`	`required`
`content`	`tuple[TextPart \| ToolCallPart \| ToolResultPart \| ProviderStatePart \| ThinkingPart \| FilePart \| HostedToolCallPart \| CitationPart \| PeerContentPart, ...]`	`()`

copy_content (method)

Message.copy_content(value)

validate_role_content (method)

Message.validate_role_content() -> Message

text (method)

Message.text(role: MessageRole | str, text: str) -> Message

tool_call (method)

Message.tool_call(*, tool_call_id: str | None=None, tool_name: str | None=None, arguments: dict[str, Any] | None=None, tool_round_id: str | None=None, model_step_id: str | None=None, model_attempt_id: str | None=None, calls: list[ToolCallPart] | None=None) -> Message

tool_result (method)

Message.tool_result(*, tool_call_id: str | None=None, tool_name: str | None=None, content: str='', structured: dict[str, Any] | None=None, artifacts: list[dict[str, Any]] | None=None, is_error: bool=False, tool_round_id: str | None=None, model_step_id: str | None=None, model_attempt_id: str | None=None, results: list[ToolResultPart] | None=None) -> Message

Release source · Runtime guarantees · Capability guides

`MessageRole`

from cayu.messages import MessageRole

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`USER`	`class attribute`	`'user'`
`ASSISTANT`	`class attribute`	`'assistant'`
`SYSTEM`	`class attribute`	`'system'`
`TOOL`	`class attribute`	`'tool'`

Release source · Runtime guarantees · Capability guides

`PeerContentPart`

from cayu.messages import PeerContentPart

Attributed, non-executable content delivered by another participant.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`type`	`Literal['peer_content']`	`'peer_content'`
`text`	`str`	`Field(max_length=131072)`
`sender_participant_id`	`str`	`Field(max_length=512)`
`sender_participant_incarnation`	`str`	`Field(max_length=512)`
`sender_session_id`	`str`	`Field(max_length=512)`
`sender_session_instance_id`	`str`	`Field(max_length=512)`
`occurrence_id`	`str`	`Field(max_length=512)`
`append_key_json`	`str`	`Field(max_length=16384)`
`operation_key`	`str`	`Field(max_length=512)`
`projection_id`	`str`	`Field(max_length=256)`
`provenance_sha256`	`str`	`Field(pattern='^[0-9a-f]{64}$')`
`executable`	`Literal[False]`	`False`

validate_identity (method)

PeerContentPart.validate_identity(value: str, info) -> str

validate_peer_text (method)

PeerContentPart.validate_peer_text(value: str) -> str

validate_append_key_json (method)

PeerContentPart.validate_append_key_json(value: str) -> str

Release source · Runtime guarantees · Capability guides

`ProviderStatePart`

from cayu.messages import ProviderStatePart

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`type`	`Literal['provider_state']`	`'provider_state'`
`provider`	`str`	`required`
`state`	`dict[str, Any]`	`Field(default_factory=dict)`

validate_provider (method)

ProviderStatePart.validate_provider(value: str) -> str

copy_state (method)

ProviderStatePart.copy_state(value: dict[str, Any]) -> dict[str, Any]

Release source · Runtime guarantees · Capability guides

`TextPart`

from cayu.messages import TextPart

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`type`	`Literal['text']`	`'text'`
`text`	`str`	`required`

validate_text (method)

TextPart.validate_text(value: str) -> str

Release source · Runtime guarantees · Capability guides

`ThinkingPart`

from cayu.messages import ThinkingPart

Model reasoning/thinking content from a single reasoning block.

text may be empty (the provider returned the reasoning in an omitted/redacted form). provider_state carries the opaque round-trip payload — the Anthropic signature or redacted_thinking data, or an OpenAI encrypted reasoning blob — needed to send the block back to the provider on a later turn. Built-in providers tag opaque reasoning state with its provider family, protocol, and protocol version; request adapters replay it only when all three match. Legacy untagged state remains readable in the durable transcript but is not authoritative for opaque replay.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`type`	`Literal['thinking']`	`'thinking'`
`text`	`str`	`''`
`provider_state`	`dict[str, Any] \| None`	`None`

copy_provider_state (method)

ThinkingPart.copy_provider_state(value)

validate_text (method)

ThinkingPart.validate_text(value: str) -> str

Release source · Runtime guarantees · Capability guides

`ToolCallPart`

from cayu.messages import ToolCallPart

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`type`	`Literal['tool_call']`	`'tool_call'`
`tool_call_id`	`str`	`required`
`tool_name`	`str`	`required`
`arguments`	`dict[str, Any]`	`Field(default_factory=dict)`
`arguments_state`	`Literal['finalized', 'unavailable']`	`'finalized'`
`tool_round_id`	`str \| None`	`None`
`model_step_id`	`str \| None`	`None`
`model_attempt_id`	`str \| None`	`None`

continuation_arguments (method)

ToolCallPart.continuation_arguments() -> dict[str, Any]

Return explicit non-executable evidence for suppressed historical input.

copy_arguments (method)

ToolCallPart.copy_arguments(value: dict[str, Any]) -> dict[str, Any]

validate_nonblank_fields (method)

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

validate_optional_identity (method)

ToolCallPart.validate_optional_identity(value: str | None, info) -> str | None

validate_complete_identity (method)

ToolCallPart.validate_complete_identity() -> ToolCallPart

Release source · Runtime guarantees · Capability guides

`ToolResultPart`

from cayu.messages import ToolResultPart

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`type`	`Literal['tool_result']`	`'tool_result'`
`tool_call_id`	`str`	`required`
`tool_name`	`str`	`required`
`content`	`str`	`''`
`structured`	`dict[str, Any] \| None`	`None`
`artifacts`	`list[dict[str, Any]]`	`Field(default_factory=list)`
`is_error`	`StrictBool`	`False`
`tool_round_id`	`str \| None`	`None`
`model_step_id`	`str \| None`	`None`
`model_attempt_id`	`str \| None`	`None`

copy_result_data (method)

ToolResultPart.copy_result_data(value, info)

validate_content (method)

ToolResultPart.validate_content(value: str) -> str

validate_nonblank_fields (method)

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

validate_optional_identity (method)

ToolResultPart.validate_optional_identity(value: str | None, info) -> str | None

validate_complete_identity (method)

ToolResultPart.validate_complete_identity() -> ToolResultPart

Release source · Runtime guarantees · Capability guides

`WebSearchAction`

from cayu.messages import WebSearchAction

Bounded terminal evidence; optional provider details may be absent.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`type`	`Literal['search', 'open_page', 'find_in_page']`	`required`
`query`	`str \| None`	`Field(default=None, max_length=4096)`
`queries`	`tuple[str, ...]`	`Field(default=(), max_length=100)`
`url`	`str \| None`	`Field(default=None, max_length=4096)`
`pattern`	`str \| None`	`Field(default=None, max_length=4096)`
`sources`	`tuple[WebSearchSource \| WebSearchAPISource, ...]`	`Field(default=(), max_length=100)`

validate_optional_text (method)

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

validate_optional_url (method)

WebSearchAction.validate_optional_url(value: str | None) -> str | None

copy_queries (method)

WebSearchAction.copy_queries(value: object) -> tuple[str, ...]

copy_sources (method)

WebSearchAction.copy_sources(value: object) -> tuple[WebSearchSource | WebSearchAPISource, ...]

validate_action_fields (method)

WebSearchAction.validate_action_fields() -> WebSearchAction

Release source · Runtime guarantees · Capability guides

`WebSearchAPISource`

from cayu.messages import WebSearchAPISource

Named API evidence returned by hosted search, without a fabricated URL.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`type`	`Literal['api']`	`'api'`
`name`	`str`	`Field(max_length=1024, strict=True)`

validate_name (method)

WebSearchAPISource.validate_name(value: str) -> str

Release source · Runtime guarantees · Capability guides

`WebSearchSource`

from cayu.messages import WebSearchSource

Bounded URL source returned by a provider-hosted web search.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`type`	`Literal['url']`	`'url'`
`url`	`str`	`Field(max_length=4096)`
`title`	`str \| None`	`Field(default=None, max_length=1024)`

validate_url (method)

WebSearchSource.validate_url(value: str) -> str

validate_title (method)

WebSearchSource.validate_title(value: str | None) -> str | None

Release source · Runtime guarantees · Capability guides