cayu.runtime.tool_effects

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.

ToolEffectConflict

from cayu import ToolEffectConflict

Exact effect identity or state conflicts with the requested operation.

Bases: RuntimeError.

This type’s implementation and inherited behavior are available in the linked release source.

Release source · Runtime guarantees · Capability guides

ToolEffectReceipt

from cayu import ToolEffectReceipt

Untrusted, versioned evidence submitted to an application receipt validator.

Neither this type nor its digest proves that an external effect happened. The registered application validator must authenticate and normalize the receipt for the exact durable call before runtime settlement. The runtime additionally validates its registered result schema and redacts publication.

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]	1
receipt_id	StrictStr	required
receipt_schema	StrictStr	required
receipt_schema_version	StrictInt	Field(ge=1, le=2 ** 31 - 1)
tool_call_id	StrictStr	required
idempotency_key	StrictStr	required
tool_name	StrictStr	required
external_system	StrictStr | None	None
outcome	Literal['completed', 'failed']	required
message	StrictStr	required
structured	dict[str, Any] | None	None
artifacts	list[dict[str, Any]]	Field(default_factory=list)
resource_versions	dict[str, str]	Field(default_factory=dict)
observed_at	AwareDatetime	required
source	Literal['adapter', 'reconciler', 'operator']	required
integrity	dict[str, str]	Field(default_factory=dict)

validate_version (method)

ToolEffectReceipt.validate_version(value: object) -> int

validate_identity (method)

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

validate_system (method)

ToolEffectReceipt.validate_system(value: str | None) -> str | None

validate_message (method)

ToolEffectReceipt.validate_message(value: str) -> str

copy_structured (method)

ToolEffectReceipt.copy_structured(value: object) -> dict[str, Any] | None

copy_evidence (method)

ToolEffectReceipt.copy_evidence(value: object, info) -> dict[str, str]

copy_artifacts (method)

ToolEffectReceipt.copy_artifacts(value: object) -> list[dict[str, Any]]

normalize_observation (method)

ToolEffectReceipt.normalize_observation(value: AwareDatetime)

validate_envelope_bound (method)

ToolEffectReceipt.validate_envelope_bound() -> ToolEffectReceipt

Release source · Runtime guarantees · Capability guides

ToolEffectReconciler

from cayu import ToolEffectReconciler

Application-owned authenticity/lookup boundary; must never dispatch the tool.

Bases: Protocol.

reconcile (method)

async ToolEffectReconciler.reconcile(*, context: ToolEffectReconciliationContext, receipt: ToolEffectReceipt | None) -> ToolEffectReconciliationResult

Release source · Runtime guarantees · Capability guides

ToolEffectReconcilerSpec

from cayu import ToolEffectReconcilerSpec

Registration-time, profile-bound contract for one external receipt schema.

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_profile_identity	ExecutionProfileBehaviorIdentity	required
effect	Literal['external']	'external'
receipt_schema	StrictStr	required
receipt_schema_version	StrictInt	Field(ge=1, le=2 ** 31 - 1)
required	StrictBool	False
supports_lookup	StrictBool	False
timeout_seconds	StrictFloat	Field(default=30.0, gt=0, le=300)
result_schema	dict[str, Any]	required
integrity_fields	tuple[StrictStr, ...]	()
resource_version_fields	tuple[StrictStr, ...]	()

copy_identity (method)

ToolEffectReconcilerSpec.copy_identity(value)

validate_schema_id (method)

ToolEffectReconcilerSpec.validate_schema_id(value: str) -> str

copy_result_schema (method)

ToolEffectReconcilerSpec.copy_result_schema(value)

validate_evidence_fields (method)

ToolEffectReconcilerSpec.validate_evidence_fields(value, info)

Release source · Runtime guarantees · Capability guides

ToolEffectReconciliationContext

from cayu import ToolEffectReconciliationContext

Detached exact-call identity supplied by runtime, without executable arguments.

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
session_id	StrictStr	required
session_instance_id	StrictStr	required
tool_round_id	StrictStr	required
tool_call_id	StrictStr	required
tool_name	StrictStr	required
idempotency_key	StrictStr	required
intent_digest	StrictStr	Field(pattern='^[0-9a-f]{64}$')
arguments_digest	StrictStr	Field(pattern='^[0-9a-f]{64}$')
record_revision	StrictInt	Field(ge=0)

validate_identity (method)

ToolEffectReconciliationContext.validate_identity(value, info)

Release source · Runtime guarantees · Capability guides

ToolEffectReconciliationRegistration

from cayu import ToolEffectReconciliationRegistration

Pair application logic with its executable, versioned declaration.

init (method)

ToolEffectReconciliationRegistration.__init__(*, reconciler: ToolEffectReconciler, spec: ToolEffectReconcilerSpec) -> None

Release source · Runtime guarantees · Capability guides

ToolEffectReconciliationRequest

from cayu import ToolEffectReconciliationRequest

An explicit receipt or lookup for one existing uncertain external call.

Version fields are required optimistic-concurrency evidence, not optional hints. Continuation retains the existing invocation’s limits unless a smaller step bound is supplied. Worker/handoff identities remain subject to the runtime’s existing task-continuation admission.

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
review_reference	HumanReviewReference | None	Field(default=None, repr=False)
session_id	StrictStr	required
session_instance_id	StrictStr	required
tool_round_id	StrictStr	required
tool_call_id	StrictStr	required
tool_name	StrictStr	required
idempotency_key	StrictStr	required
expected_run_epoch	StrictInt	Field(ge=0)
expected_revision	StrictInt	Field(ge=0)
receipt	ToolEffectReceipt | None	None
lookup	StrictBool	False
max_steps	StrictInt | None	Field(default=None, ge=1, le=MAX_STEPS)
task_worker_id	StrictStr | None	None
task_handoff_id	StrictStr | None	None
user_input_response	UserInputResponse | None	Field(default=None, repr=False)

detach_user_input_response (method)

ToolEffectReconciliationRequest.detach_user_input_response(value)

detach_review_reference (method)

ToolEffectReconciliationRequest.detach_review_reference(value)

validate_identity (method)

ToolEffectReconciliationRequest.validate_identity(value, info)

detach_receipt (method)

ToolEffectReconciliationRequest.detach_receipt(value)

validate_request (method)

ToolEffectReconciliationRequest.validate_request() -> ToolEffectReconciliationRequest

Release source · Runtime guarantees · Capability guides

ToolEffectReconciliationResult

from cayu import ToolEffectReconciliationResult

Application observation, subject to runtime binding/schema validation.

Retryability refers only to a new explicit reconciliation lookup, never to another tool invocation. Partial observations cannot authorize replay.

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
outcome	Literal['completed', 'failed', 'not_found', 'conflict', 'unsupported']	required
receipt	ToolEffectReceipt | None	None
observation	Literal['sent', 'not_sent', 'outcome_unknown', 'partial']	required
retryable	StrictBool	False
resource_versions	dict[str, str]	Field(default_factory=dict)

copy_receipt (method)

ToolEffectReconciliationResult.copy_receipt(value)

copy_resources (method)

ToolEffectReconciliationResult.copy_resources(value)

validate_outcome (method)

ToolEffectReconciliationResult.validate_outcome() -> ToolEffectReconciliationResult

Release source · Runtime guarantees · Capability guides

ToolEffectReconciliationTarget

from cayu import ToolEffectReconciliationTarget

Read-only call identity/version snapshot, not permission to reconcile.

Public inspection aliases private key/incarnation fields. Copy these fields into a reconciliation request with a receipt or lookup instruction. The runtime still validates current state, authority and external evidence.

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
session_id	StrictStr	required
session_instance_id	StrictStr	required
tool_round_id	StrictStr	required
tool_call_id	StrictStr	required
tool_name	StrictStr	required
idempotency_key	StrictStr	required
expected_run_epoch	StrictInt	Field(ge=0)
expected_revision	StrictInt	Field(ge=0)

validate_identity (method)

ToolEffectReconciliationTarget.validate_identity(value, info)

Release source · Runtime guarantees · Capability guides