cayu.providers.operations

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.

`copy_provider_operation_connection`

from cayu.providers import copy_provider_operation_connection

Validate a provider-owned connection without consuming its event stream.

copy_provider_operation_connection(connection: ProviderOperationConnection) -> ProviderOperationConnection

Release source · Runtime guarantees · Capability guides

`copy_provider_operation_snapshot`

from cayu.providers import copy_provider_operation_snapshot

Detach one provider-owned inspection or cancellation result.

copy_provider_operation_snapshot(snapshot: ProviderOperationSnapshot) -> ProviderOperationSnapshot

Release source · Runtime guarantees · Capability guides

`copy_provider_operation_state`

from cayu.providers import copy_provider_operation_state

Detach one provider-owned operation identity at the runtime boundary.

copy_provider_operation_state(state: ProviderOperationState) -> ProviderOperationState

Release source · Runtime guarantees · Capability guides

`PROVIDER_OPERATION_RECOVERY_OPAQUE_MAX_BYTES`

from cayu.providers import PROVIDER_OPERATION_RECOVERY_OPAQUE_MAX_BYTES

PROVIDER_OPERATION_RECOVERY_OPAQUE_MAX_BYTES = 4096

Release source · Runtime guarantees · Capability guides

`ProviderOperationAdapter`

from cayu.providers import ProviderOperationAdapter

Optional provider-owned background-operation capability.

Keeping this adapter separate from ModelProvider.stream makes the capability explicit while preserving the synchronous provider contract.

Bases: ABC.

start (method)

async ProviderOperationAdapter.start(request: ProviderOperationStartRequest) -> ProviderOperationConnection

Submit one request and return its reconnectable identity and stream.

retrieve (method)

async ProviderOperationAdapter.retrieve(state: ProviderOperationState) -> ProviderOperationSnapshot

Inspect an operation without opening a stream.

reconnect (method)

async ProviderOperationAdapter.reconnect(state: ProviderOperationState) -> ProviderOperationConnection

Reconnect to an existing provider-owned stream.

start_idempotency_support (property)

ProviderOperationAdapter.start_idempotency_support() -> ProviderOperationStartIdempotencySupport

Advertise exact key-only start recovery only when the provider proves it.

EXACT means recover_start can recover the accepted operation from the idempotency key without receiving or durably retaining the raw provider request. Providers that require the request to be submitted again must leave this as UNSUPPORTED.

recover_start (method)

async ProviderOperationAdapter.recover_start(request: ProviderOperationStartRecoveryRequest) -> ProviderOperationConnection

Recover an accepted start by its exact provider idempotency identity.

Adapters advertising EXACT must override this method. The default is intentionally unavailable so adding the recovery seam remains compatible with adapters that do not advertise exact start recovery. Implementations must only look up work already accepted under the key; this method must not create or resubmit provider work.

cancellation_support (property)

ProviderOperationAdapter.cancellation_support() -> ProviderOperationCancellationSupport

Advertise exact-operation cancellation without implying universal support.

cancel (method)

async ProviderOperationAdapter.cancel(state: ProviderOperationState) -> ProviderOperationSnapshot

Request cancellation and return the resulting provider state.

Non-cancellable adapters inherit a truthful bounded UNAVAILABLE snapshot. Adapters advertising SUPPORTED must override this method.

Release source · Runtime guarantees · Capability guides

`ProviderOperationCancellationSupport`

from cayu.providers import ProviderOperationCancellationSupport

Whether an adapter can target an existing durable operation.

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
`UNSUPPORTED`	`class attribute`	`'unsupported'`
`SUPPORTED`	`class attribute`	`'supported'`

Release source · Runtime guarantees · Capability guides

`ProviderOperationConnection`

from cayu.providers import ProviderOperationConnection

A started, recovered, or reconnected operation and its normalized event stream.

Decorators: @dataclass(frozen=True).

Fields and attributes

Name	Type	Default
`state`	`ProviderOperationState`	`required`
`status`	`ProviderOperationStatus`	`required`
`events`	`AsyncIterator[ModelStreamEvent]`	`required`

Release source · Runtime guarantees · Capability guides

`ProviderOperationMalformedError`

from cayu.providers import ProviderOperationMalformedError

A provider operation returned invalid protocol data during recovery.

Bases: ValueError.

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

Release source · Runtime guarantees · Capability guides

`ProviderOperationMode`

from cayu.providers import ProviderOperationMode

Whether one configured provider uses its optional operation adapter.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`SYNCHRONOUS`	`class attribute`	`'synchronous'`
`BACKGROUND`	`class attribute`	`'background'`

Release source · Runtime guarantees · Capability guides

`ProviderOperationRecoveryMetadata`

from cayu.providers import ProviderOperationRecoveryMetadata

Small provider-neutral continuation state, never request or response data.

cursor is the runtime-owned monotonic boundary number. opaque is a bounded adapter-owned continuation value: Cayu copies and stores it without interpreting provider-specific field names, and gives it back only to the same operation adapter. Provider adapters must not put credentials, raw request or response bodies, or model reasoning in it.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`cursor`	`Annotated[StrictInt, Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)] \| None`	`None`
`opaque`	`dict[str, object]`	`Field(default_factory=dict, exclude_if=lambda value: not value)`

validate_opaque (method)

ProviderOperationRecoveryMetadata.validate_opaque(value: object) -> dict[str, object]

Release source · Runtime guarantees · Capability guides

`ProviderOperationSnapshot`

from cayu.providers import ProviderOperationSnapshot

The provider’s current interpretation of one durable operation identity.

Decorators: @dataclass(frozen=True).

Fields and attributes

Name	Type	Default
`state`	`ProviderOperationState`	`required`
`status`	`ProviderOperationStatus`	`required`
`events`	`tuple[ModelStreamEvent, ...]`	`()`

Release source · Runtime guarantees · Capability guides

`ProviderOperationStartIdempotencySupport`

from cayu.providers import ProviderOperationStartIdempotencySupport

Whether recovering an accepted start from its key alone is proven exact.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`UNSUPPORTED`	`class attribute`	`'unsupported'`
`EXACT`	`class attribute`	`'exact'`

Release source · Runtime guarantees · Capability guides

`ProviderOperationStartRecoveryRequest`

from cayu.providers import ProviderOperationStartRecoveryRequest

Recover one accepted start from provider-owned idempotency authority alone.

Decorators: @dataclass(frozen=True).

Fields and attributes

Name	Type	Default
`idempotency_key`	`str`	`required`

Release source · Runtime guarantees · Capability guides

`ProviderOperationStartRequest`

from cayu.providers import ProviderOperationStartRequest

One explicitly enabled dispatch with stable provider idempotency authority.

Decorators: @dataclass(frozen=True).

Fields and attributes

Name	Type	Default
`request`	`ModelRequest`	`required`
`idempotency_key`	`str`	`required`

Release source · Runtime guarantees · Capability guides

`ProviderOperationState`

from cayu.providers import ProviderOperationState

Bounded durable state needed to inspect or reconnect provider-owned work.

Provider adapters must never put credentials, raw request bodies, or model reasoning in recovery_metadata. Cayu enforces portable durable JSON and a small byte bound; the metadata remains runtime-private when operation evidence is projected to public events.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`version`	`Literal[1]`	`1`
`operation_id`	`str`	`Field(max_length=PROVIDER_OPERATION_ID_MAX_CHARS)`
`stream_protocol`	`str`	`Field(max_length=PROVIDER_OPERATION_STREAM_PROTOCOL_MAX_CHARS)`
`recovery_metadata`	`ProviderOperationRecoveryMetadata`	`Field(default_factory=ProviderOperationRecoveryMetadata)`

validate_bounded_identity (method)

ProviderOperationState.validate_bounded_identity(value: str, info) -> str

validate_recovery_metadata (method)

ProviderOperationState.validate_recovery_metadata(value: object) -> ProviderOperationRecoveryMetadata

Release source · Runtime guarantees · Capability guides

`ProviderOperationStatus`

from cayu.providers import ProviderOperationStatus

Provider-neutral lifecycle states for reconnectable model work.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`QUEUED`	`class attribute`	`'queued'`
`IN_PROGRESS`	`class attribute`	`'in_progress'`
`COMPLETED`	`class attribute`	`'completed'`
`FAILED`	`class attribute`	`'failed'`
`CANCELLED`	`class attribute`	`'cancelled'`
`EXPIRED`	`class attribute`	`'expired'`
`UNAVAILABLE`	`class attribute`	`'unavailable'`

terminal (property)

ProviderOperationStatus.terminal() -> bool

Release source · Runtime guarantees · Capability guides