cayu.collaboration.exports

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.

ExportLimits

from cayu.collaboration import ExportLimits

Bases: ContractValue.

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_exports	StrictInt	Field(ge=1, le=1024)
max_retained_bytes	StrictInt	Field(ge=1, le=64 * 1024 * 1024)
max_pending	StrictInt	Field(ge=1, le=64)

bounded_input (method)

ExportLimits.bounded_input(value: object) -> Any

immutable_fields (method)

ExportLimits.immutable_fields() -> ContractValue

Release source · Runtime guarantees · Capability guides

SessionExportAcceptance

from cayu.collaboration import SessionExportAcceptance

Evidence resolved by a registered receiving owner, not caller authority.

Bases: ContractValue.

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
export_receipt	SessionExportReceipt	required
receiving_owner	OwnerRef	required
receipt_id	Identifier	required

bounded_input (method)

SessionExportAcceptance.bounded_input(value: object) -> Any

immutable_fields (method)

SessionExportAcceptance.immutable_fields() -> ContractValue

Release source · Runtime guarantees · Capability guides

SessionExportAcceptanceReader

from cayu.collaboration import SessionExportAcceptanceReader

Bases: ABC.

owner (property)

SessionExportAcceptanceReader.owner() -> OwnerRef

Stable receiving owner whose evidence this reader authenticates.

lookup (method)

async SessionExportAcceptanceReader.lookup(receipt: SessionExportReceipt) -> ExactLookup[SessionExportAcceptance]

Resolve exact authenticated acceptance without disclosing payload.

settlement (method)

async SessionExportAcceptanceReader.settlement(receipt: SessionExportReceipt, expected: PermitCommand) -> ExactLookup[ReceivingSettlementReceipt]

Resolve exact receiving settlement; acceptance alone is insufficient.

Release source · Runtime guarantees · Capability guides

SessionExportAccessContext

from cayu.collaboration import SessionExportAccessContext

Authenticated host input passed separately; construction grants no trust.

Bases: ContractValue.

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
principal	Identifier	required
mandate	MandateAccessContext | None	None

bounded_input (method)

SessionExportAccessContext.bounded_input(value: object) -> Any

immutable_fields (method)

SessionExportAccessContext.immutable_fields() -> ContractValue

exact_principal (method)

SessionExportAccessContext.exact_principal() -> SessionExportAccessContext

Release source · Runtime guarantees · Capability guides

SessionExportAction

from cayu.collaboration import SessionExportAction

SessionExportAction = Literal['initialize', 'source', 'export', 'readback', 'expose', 'release', 'retire']

Release source · Runtime guarantees · Capability guides

SessionExportAuthorization

from cayu.collaboration import SessionExportAuthorization

Historical policy evidence; replay does not renew or authenticate it.

Bases: ContractValue.

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
issuer	OwnerRef	required
principal	Identifier	required
policy	ObjectRef	required
revision	Generation	required
expires_at_ms	Annotated[StrictInt, Field(ge=1, le=MAX_PORTABLE_JSON_INTEGER)]	required
mandate	MandateResolution | None	None
runtime	SessionExportRuntimeOrigin | None	None

bounded_input (method)

SessionExportAuthorization.bounded_input(value: object) -> Any

immutable_fields (method)

SessionExportAuthorization.immutable_fields() -> ContractValue

exact_mandate_principal (method)

SessionExportAuthorization.exact_mandate_principal() -> SessionExportAuthorization

initiating_identity (method)

SessionExportAuthorization.initiating_identity() -> InitiatorBinding

Release source · Runtime guarantees · Capability guides

SessionExportCapacityExceeded

from cayu.collaboration import SessionExportCapacityExceeded

Bases: RuntimeError.

init (method)

SessionExportCapacityExceeded.__init__() -> None

Release source · Runtime guarantees · Capability guides

SessionExportConflict

from cayu.collaboration import SessionExportConflict

Bases: CollaborationConflict.

init (method)

SessionExportConflict.__init__() -> None

Release source · Runtime guarantees · Capability guides

SessionExportDenied

from cayu.collaboration import SessionExportDenied

Bases: PermissionError.

init (method)

SessionExportDenied.__init__() -> None

Release source · Runtime guarantees · Capability guides

SessionExportIntent

from cayu.collaboration import SessionExportIntent

Complete frozen export inputs, including source rows and output digests.

Bases: ContractValue.

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
request	SessionExportRequest	required
limits	ExportLimits	required
source_commitment	ExportDigest	required
output_commitment	ExportDigest	required
authorization	SessionExportAuthorization	required
release_receipt	ContentReleaseReceipt | None	None

bounded_input (method)

SessionExportIntent.bounded_input(value: object) -> Any

immutable_fields (method)

SessionExportIntent.immutable_fields() -> ContractValue

consistent_policy (method)

SessionExportIntent.consistent_policy() -> SessionExportIntent

Release source · Runtime guarantees · Capability guides

SessionExportNamespace

from cayu.collaboration import SessionExportNamespace

Stable owner namespace chosen once by the session store transaction.

Bases: ContractValue.

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
owner	OwnerRef	required
session_id	Identifier	required
session_instance_id	Identifier	required
namespace_incarnation	Identifier	required
generation	Literal[1]	required
limits	ExportLimits	required

bounded_input (method)

SessionExportNamespace.bounded_input(value: object) -> Any

immutable_fields (method)

SessionExportNamespace.immutable_fields() -> ContractValue

strict_generation (method)

SessionExportNamespace.strict_generation(value: object) -> object

Release source · Runtime guarantees · Capability guides

SessionExportPolicy

from cayu.collaboration import SessionExportPolicy

Bases: ABC.

ref (property)

SessionExportPolicy.ref() -> ObjectRef

Stable registered implementation/configuration identity.

acquire (method)

SessionExportPolicy.acquire(context: SessionExportAccessContext, *, session_id: str, session_instance_id: str, actions: tuple[SessionExportAction, ...], audience: OwnerRef | None=None) -> AbstractAsyncContextManager[SessionExportAuthorization]

Acquire all requested permissions or raise SessionExportDenied.

This synchronous factory returns one async guard that independently verifies every requested permission without nested guard acquisition. Export uses (“readback”, “source”, “export”); settlement uses (“readback”, “release”) or (“readback”, “retire”). These combined guards cover concurrent historical reconciliation without nested acquisition. Payload reads use (“readback”, “expose”). Initialization uses (“initialize”,) with the exact session IDs, before an operation reference exists. Empty or unknown actions must be denied. Host registration is trusted to supply the guard’s serialization guarantee; these value types do not establish that guarantee themselves. Implementations must serialize revocation with the yielded permission for the entire guarded operation. Runtime must validate expiry against the authoritative store clock at commit and check expiry again at exposure. Runtime owners must hold the guard through owned publication/exposure and drain in-flight work before releasing it. Historical authorization values cannot replace a fresh acquisition.

acquire_runtime (method)

SessionExportPolicy.acquire_runtime(context: SessionExportAccessContext, *, origin: SessionExportRuntimeOrigin, session_id: str, session_instance_id: str, actions: tuple[SessionExportAction, ...], audience: OwnerRef | None=None) -> AbstractAsyncContextManager[SessionExportAuthorization]

Explicit runtime adapter, denied unless the application implements it.

Cayu derives origin from a live privately bound tool context and checks its exact requester session. Implementations authenticate the requested principal against that origin and independently authorize the selected source and actions. They return policy evidence without runtime fields; Cayu attaches the authenticated origin itself. Source-session ownership is not implied by this caller attribution.

acquire_peer_exposures (method)

async SessionExportPolicy.acquire_peer_exposures(context, *, items: tuple[PeerContentExposureItem, ...])

Hold one revocation guard for a complete model-attempt batch.

Policies supporting multiple occurrences must override this hook and authenticate every item under a shared guard, yielding projections in item order. The default supports exactly one item through the single hook; it never nests potentially non-reentrant guards.

acquire_peer_exposure (method)

SessionExportPolicy.acquire_peer_exposure(context: SessionExportAccessContext | None, *, origin: PeerModelAttemptOrigin, append_key: PeerAppendKey, occurrence: PeerContentOccurrence, audience: OwnerRef, provider_name: Identifier, model: Identifier, model_attempt_id: Identifier, capability_version: Generation) -> AbstractAsyncContextManager[PeerContentPayload]

Authorize one trusted model-attempt peer disclosure.

The default is deliberately fail-closed. A production policy may override this method to serialize its current revocation and mandate checks while yielding the bounded projection sent to the provider.

acquire_peer_exclusion (method)

SessionExportPolicy.acquire_peer_exclusion(context: CollaborationAccessContext, *, request: PeerContentAppendRequest, receipt: PeerContentReceipt | ClarificationDeliveryRecord | ProducerDeliveryRecord, reason: str) -> AbstractAsyncContextManager[None]

Authorize discharge of an exact retained delivery, not new disclosure.

The receiver verifies current withdrawal/cleanup authority and binds the complete request and reason. Revoking source disclosure must not itself revoke an independently authorized cleanup obligation. The store-owned receipt is evidence of that obligation, never permission by itself. For a clarification not yet received by SessionStore, its registered owner supplies the exact durable ClarificationDeliveryRecord instead. Policies must authenticate that preparation independently; it grants cleanup only, never source read, append, or provider exposure authority. A producer owner supplies its exact durable ProducerDeliveryRecord by the same rule; its registration and export tuple must be authenticated, not inferred from a matching payload or a caller-supplied receipt. The default denies; no unregistered cleanup authority is inferred.

acquire_peer_read (method)

SessionExportPolicy.acquire_peer_read(context: CollaborationAccessContext, *, append_key: PeerAppendKey, receipt: PeerContentReceipt) -> AbstractAsyncContextManager[None]

Hold current source/read authority; historical receipts are not grants.

acquire_peer_append (method)

SessionExportPolicy.acquire_peer_append(context: CollaborationAccessContext, *, request: PeerContentAppendRequest, append_key: PeerAppendKey, occurrence: PeerContentOccurrence) -> AbstractAsyncContextManager[PeerContentAppendAuthorization]

Hold producing authorization through queue admission.

A caller-supplied payload and provenance digest are not evidence that a source produced or authorized the occurrence. Implementations must resolve the exact source/export receipt and current disclosure grant, yield typed evidence matching the occurrence, and serialize revocation with the yielded append operation.

Release source · Runtime guarantees · Capability guides

SessionExportProjector

from cayu.collaboration import SessionExportProjector

Bases: ABC.

ref (property)

SessionExportProjector.ref() -> ObjectRef

Stable registered implementation/configuration identity.

project (method)

SessionExportProjector.project(source: tuple[TranscriptRecord, ...]) -> dict[str, Any]

Deterministically project approved source fields, without model calls.

validate (method)

SessionExportProjector.validate(source: tuple[TranscriptRecord, ...], output: dict[str, Any], audience: OwnerRef) -> bool

Positively approve exact output for source and audience.

JSON validity alone is insufficient. Runtime must require literal True from this registered validator before publication, and independently enforce output bounds. Implementations must not make implicit model calls.

Release source · Runtime guarantees · Capability guides

SessionExportReceipt

from cayu.collaboration import SessionExportReceipt

Exact historical evidence without payload or current disclosure authority.

Bases: ContractValue.

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
expected	ExpectedOperation[SessionExportIntent]	required
event_id	Identifier	required

bounded_input (method)

SessionExportReceipt.bounded_input(value: object) -> Any

immutable_fields (method)

SessionExportReceipt.immutable_fields() -> ContractValue

consistent_operation (method)

SessionExportReceipt.consistent_operation() -> SessionExportReceipt

Release source · Runtime guarantees · Capability guides

SessionExportReconciliation

from cayu.collaboration import SessionExportReconciliation

A published result or positively excluded participant preparation.

Exclusion is not a published export and cannot authorize payload exposure. The original operation key remains occupied after either outcome.

Bases: ContractValue.

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
request	SessionExportRequest	required
state	Literal['published', 'excluded']	required
receipt	SessionExportReceipt | None	required

bounded_input (method)

SessionExportReconciliation.bounded_input(value: object) -> Any

immutable_fields (method)

SessionExportReconciliation.immutable_fields() -> ContractValue

exact_result (method)

SessionExportReconciliation.exact_result() -> SessionExportReconciliation

Release source · Runtime guarantees · Capability guides

SessionExportRef

from cayu.collaboration import SessionExportRef

Bases: ContractValue.

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	Identifier	required
session_instance_id	Identifier	required
operation	OperationRef	required

bounded_input (method)

SessionExportRef.bounded_input(value: object) -> Any

immutable_fields (method)

SessionExportRef.immutable_fields() -> ContractValue

Release source · Runtime guarantees · Capability guides

SessionExportRegistration

from cayu.collaboration import SessionExportRegistration

Trusted host registration; callbacks are not serialized contract values.

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
owner	OwnerRef	required
policy	SessionExportPolicy	required
projectors	tuple[SessionExportProjector, ...]	required
limits	ExportLimits	required
readers	tuple[SessionExportAcceptanceReader, ...]	()
release_readers	tuple[ContentReleaseReader, ...]	()
mandates	MandateResolver | None	None
resource_owners	tuple[ResourceSelectorOwner, ...]	()
peer_exposure_receiver	PeerContentExposureReceiver | None	None

Release source · Runtime guarantees · Capability guides

SessionExportRequest

from cayu.collaboration import SessionExportRequest

Bases: ContractValue.

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
ref	SessionExportRef	required
source_indices	tuple[SourceIndex, ...]	Field(max_length=16)
source_selection	Literal['whole_records', 'assistant_visible_text_v1']	'whole_records'
audience	OwnerRef	required
projector	ObjectRef	required
policy	ObjectRef	required
mode	Literal['deterministic', 'reviewed_prose']	'deterministic'
release	ContentReleaseRequest | None	None

bounded_input (method)

SessionExportRequest.bounded_input(value: object) -> Any

immutable_fields (method)

SessionExportRequest.immutable_fields() -> ContractValue

qualified_mode (method)

SessionExportRequest.qualified_mode() -> SessionExportRequest

canonical_indices (method)

SessionExportRequest.canonical_indices(value: tuple[int, ...]) -> tuple[int, ...]

Release source · Runtime guarantees · Capability guides

SessionExportRuntimeOrigin

from cayu.collaboration import SessionExportRuntimeOrigin

Historical runtime attribution, never a caller-constructible execution grant.

Bases: ContractValue.

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	Identifier	required
session_instance_id	Identifier	required
run_epoch	Annotated[StrictInt, Field(ge=0, le=MAX_PORTABLE_JSON_INTEGER)]	required
invocation_schema_version	Literal[1]	1
invocation_trust	Literal['server_verified', 'host_asserted', 'unattributed']	required
invocation_subject	Identifier | None	None
invocation_tenant	Identifier | None	None
root_invocation_id	Identifier	required
root_session_id	Identifier	required
invocation_source	Literal['http_run', 'sdk_run', 'fork', 'subagent', 'task', 'workflow_step']	required
interaction_id	Identifier	required
model_step_id	Identifier	required
model_attempt_id	Identifier	required
tool_round_id	Identifier	required
tool_call_id	Identifier	required
tool_name	Identifier	required
idempotency_key	Identifier	required
effective_arguments_sha256	ExportDigest	required
execution_profile_fingerprint	ExportDigest	required

bounded_input (method)

SessionExportRuntimeOrigin.bounded_input(value: object) -> Any

immutable_fields (method)

SessionExportRuntimeOrigin.immutable_fields() -> ContractValue

invocation (property)

SessionExportRuntimeOrigin.invocation() -> SessionInvocation

valid_invocation (method)

SessionExportRuntimeOrigin.valid_invocation() -> SessionExportRuntimeOrigin

Release source · Runtime guarantees · Capability guides

SessionExportSettlementReceipt

from cayu.collaboration import SessionExportSettlementReceipt

Historical settlement bound to its own complete initiating identity.

Bases: ContractValue.

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
request	SessionExportSettlementRequest	required
initiator	InitiatorBinding	required
mandate_commitment	ExportDigest | None	None
acceptance	SessionExportAcceptance | None	required
event_id	Identifier	required

bounded_input (method)

SessionExportSettlementReceipt.bounded_input(value: object) -> Any

immutable_fields (method)

SessionExportSettlementReceipt.immutable_fields() -> ContractValue

consistent_acceptance (method)

SessionExportSettlementReceipt.consistent_acceptance() -> SessionExportSettlementReceipt

Release source · Runtime guarantees · Capability guides

SessionExportSettlementRequest

from cayu.collaboration import SessionExportSettlementRequest

Public settlement intent, never a caller-supplied acceptance receipt.

Bases: ContractValue.

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
request	SessionExportRequest	required
operation	OperationRef	required
mode	Literal['release', 'retire']	required

bounded_input (method)

SessionExportSettlementRequest.bounded_input(value: object) -> Any

immutable_fields (method)

SessionExportSettlementRequest.immutable_fields() -> ContractValue

Release source · Runtime guarantees · Capability guides

SessionExportUnavailable

from cayu.collaboration import SessionExportUnavailable

Bases: RuntimeError.

init (method)

SessionExportUnavailable.__init__() -> None

Release source · Runtime guarantees · Capability guides