cayu definitions

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.

__version__

from cayu import __version__

__version__ = package_version()

Release source · Runtime guarantees · Capability guides

BrowserRecordingStore

from cayu import BrowserRecordingStore

Private local SQLite media store with bounded publication and retention.

Keep this database outside model-accessible workspaces. SQLite transactions commit metadata and media together: acknowledgement loss can never publish an orphan or require replaying an action. Applications supply retrieval authorization separately to the recording router. Expired data is denied on every read; call purge_expired periodically for physical reclamation.

init (method)

BrowserRecordingStore.__init__(path: str | Path, *, max_storage_bytes: int=512 * 1024 * 1024, max_recordings: int=128, ffmpeg: str='ffmpeg') -> None

authorize_capture (method)

async BrowserRecordingStore.authorize_capture(*, session_id: str, policy: BrowserRecordingPolicy, guest_endpoint: str) -> BrowserRecordingConfig

Application call before the run; never exposed as an HTTP/model mutation.

authenticate_capture (method)

async BrowserRecordingStore.authenticate_capture(token: str) -> tuple[BrowserRecordingPolicy, str]

begin (method)

async BrowserRecordingStore.begin(policy: BrowserRecordingPolicy, identity: dict[str, str]) -> str

claim (method)

async BrowserRecordingStore.claim(recording_id: str) -> str

heartbeat (method)

async BrowserRecordingStore.heartbeat(recording_id: str, *, owner: str, elapsed_ms: int) -> None

recordings_for_session (method)

async BrowserRecordingStore.recordings_for_session(session_id: str) -> list[str]

append (method)

async BrowserRecordingStore.append(recording_id: str, *, policy: BrowserRecordingPolicy, owner: str, sequence: int, page_id: str, elapsed_ms: int, png: bytes) -> None

finish (method)

async BrowserRecordingStore.finish(recording_id: str, *, reason: str='normal_close', gap: bool=False, owner: str | None=None, elapsed_ms: int=0) -> None

video (method)

async BrowserRecordingStore.video(recording_id: str) -> bytes

manifest (method)

async BrowserRecordingStore.manifest(recording_id: str) -> BrowserRecordingManifest

media (method)

async BrowserRecordingStore.media(recording_id: str, sequence: int) -> bytes

recover_abandoned (method)

async BrowserRecordingStore.recover_abandoned(*, inactive_seconds: int=30) -> None

Seal stale capture as partial/unavailable, never infer completion or replay.

delete (method)

async BrowserRecordingStore.delete(recording_id: str) -> None

purge_expired (method)

async BrowserRecordingStore.purge_expired() -> None

Release source · Runtime guarantees · Capability guides

BrowserRecordingUnavailable

from cayu import BrowserRecordingUnavailable

Bounded failure with no browser content or credentials.

Bases: RuntimeError.

init (method)

BrowserRecordingUnavailable.__init__(reason: str='storage_failure') -> None

Release source · Runtime guarantees · Capability guides

DurableValueError

from cayu import DurableValueError

A stable, backend-independent portable-value validation failure.

field_name is a caller-supplied boundary label and path is an input-value-independent location generated by the validator. Both are bounded and reduced to printable ASCII before entering the exception message, so malformed data cannot poison logs or durable error records.

Bases: ValueError.

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
code	str	required
field_name	str	required
path	str	required

init (method)

DurableValueError.__init__(code: str, field_name: str, *, path: str='$', limit: int | None=None, observed_lower_bound: int | None=None) -> None

Release source · Runtime guarantees · Capability guides

extract_durable_value_error

from cayu import extract_durable_value_error

Return a trusted direct or Pydantic-wrapped durable-value failure.

The helper reads Pydantic’s structured error context without rendering the exception or requesting its rejected input. Public subclasses are provider-controlled and may override attribute access, so they collapse to a fresh runtime-owned fallback without reading any subclass state.

extract_durable_value_error(exc: BaseException) -> DurableValueError | None

Release source · Runtime guarantees · Capability guides

ResourceAccessDenied

from cayu import ResourceAccessDenied

Bases: PermissionError.

init (method)

ResourceAccessDenied.__init__() -> None

Release source · Runtime guarantees · Capability guides