cayu.sessions.invocation

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.

InvocationOrigin

from cayu.sessions import InvocationOrigin

Immutable root identity retained across a complete session tree.

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
trust	InvocationOriginTrust	required
subject	str | None	Field(default=None, max_length=INVOCATION_IDENTITY_MAX_CHARS)
tenant	str | None	Field(default=None, max_length=INVOCATION_IDENTITY_MAX_CHARS)

validate_identity (method)

InvocationOrigin.validate_identity(value: str | None, info) -> str | None

validate_trust_shape (method)

InvocationOrigin.validate_trust_shape() -> InvocationOrigin

Release source · Runtime guarantees · Capability guides

InvocationOriginClaim

from cayu.sessions import InvocationOriginClaim

Bounded identity asserted by a trusted direct-SDK host application.

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
subject	str	Field(max_length=INVOCATION_IDENTITY_MAX_CHARS)
tenant	str | None	Field(default=None, max_length=INVOCATION_IDENTITY_MAX_CHARS)

validate_identity (method)

InvocationOriginClaim.validate_identity(value: str | None, info) -> str | None

Release source · Runtime guarantees · Capability guides

InvocationOriginTrust

from cayu.sessions import InvocationOriginTrust

How Cayu obtained the root invocation identity.

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
SERVER_VERIFIED	class attribute	'server_verified'
HOST_ASSERTED	class attribute	'host_asserted'
UNATTRIBUTED	class attribute	'unattributed'

Release source · Runtime guarantees · Capability guides

session_invocation_from_task

from cayu.sessions import session_invocation_from_task

Create the session-side root snapshot for task-backed execution.

session_invocation_from_task(task: TaskInvocation, *, session_id: str, source: SessionExecutionSource=SessionExecutionSource.TASK) -> SessionInvocation

Release source · Runtime guarantees · Capability guides

SessionExecutionSource

from cayu.sessions import SessionExecutionSource

The runtime boundary that created one session.

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
HTTP_RUN	class attribute	'http_run'
SDK_RUN	class attribute	'sdk_run'
FORK	class attribute	'fork'
SUBAGENT	class attribute	'subagent'
TASK	class attribute	'task'
WORKFLOW_STEP	class attribute	'workflow_step'

Release source · Runtime guarantees · Capability guides

SessionInvocation

from cayu.sessions import SessionInvocation

Versioned provenance attached atomically to one durable session.

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
schema_version	Literal[1]	INVOCATION_PROVENANCE_SCHEMA_VERSION
origin	InvocationOrigin	required
root_invocation_id	str	Field(min_length=36, max_length=36, pattern=_CANONICAL_UUID4_PATTERN, json_schema_extra={'format': 'uuid4'})
root_session_id	str	required
source	SessionExecutionSource	required
resource_access	ResourceExecutionBinding | None	Field(default=None, exclude_if=lambda v: v is None)

validate_root_invocation_id (method)

SessionInvocation.validate_root_invocation_id(value: str) -> str

validate_root_session_id (method)

SessionInvocation.validate_root_session_id(value: str) -> str

Release source · Runtime guarantees · Capability guides

SessionInvocationBinding

from cayu.sessions import SessionInvocationBinding

One immediate session identity bound to its immutable provenance.

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
id	str	required
session_instance_id	str	Field(min_length=36, max_length=36, pattern=_CANONICAL_UUID4_PATTERN, json_schema_extra={'format': 'uuid4'})
invocation	SessionInvocation	required

validate_id (method)

SessionInvocationBinding.validate_id(value: str) -> str

validate_session_instance_id (method)

SessionInvocationBinding.validate_session_instance_id(value: str) -> str

copy_invocation (method)

SessionInvocationBinding.copy_invocation(value: SessionInvocation) -> SessionInvocation

Release source · Runtime guarantees · Capability guides

TaskExecutionSource

from cayu.sessions import TaskExecutionSource

The trusted boundary that created one durable task.

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
HTTP_RUN	class attribute	'http_run'
PRODUCT_OPERATION	class attribute	'product_operation'
SCHEDULED	class attribute	'scheduled'
SDK_TASK	class attribute	'sdk_task'
TASK_DISPATCH	class attribute	'task_dispatch'
WEBHOOK	class attribute	'webhook'

Release source · Runtime guarantees · Capability guides

TaskInvocation

from cayu.sessions import TaskInvocation

Versioned root provenance attached atomically to one durable task.

root_session_id is absent when the invocation began as task-only work. A later task/session attachment remains structural state on Task and cannot rewrite this immutable root record.

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
schema_version	Literal[1]	INVOCATION_PROVENANCE_SCHEMA_VERSION
origin	InvocationOrigin	required
root_invocation_id	str	Field(min_length=36, max_length=36, pattern=_CANONICAL_UUID4_PATTERN, json_schema_extra={'format': 'uuid4'})
root_session_id	str | None	None
source	TaskExecutionSource	required
resource_access	ResourceExecutionBinding | None	Field(default=None, exclude_if=lambda v: v is None)
access_labels	Mapping[str, str]	Field(default_factory=dict, exclude_if=lambda v: not v)

validate_access_labels (method)

TaskInvocation.validate_access_labels(value)

freeze_access_labels (method)

TaskInvocation.freeze_access_labels(value)

serialize_access_labels (method)

TaskInvocation.serialize_access_labels(value)

validate_root_invocation_id (method)

TaskInvocation.validate_root_invocation_id(value: str) -> str

validate_root_session_id (method)

TaskInvocation.validate_root_session_id(value: str | None) -> str | None

Release source · Runtime guarantees · Capability guides