cayu.observability.watchers

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.

EventWatcher

from cayu.observability import EventWatcher

Trusted app-code handler for durable runtime events.

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
name	str	required
query	EventQuery	required
handler	EventWatcherHandler	required
max_attempts	int	3
batch_size	int	100
lease_seconds	float	300.0

Release source · Runtime guarantees · Capability guides

EventWatcherClaim

from cayu.observability import EventWatcherClaim

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
watcher_name	str	required
event_id	str	required
event_sequence	StrictInt	Field(ge=1, le=MAX_DURABLE_JSON_INTEGER)
attempt	StrictInt	Field(ge=1, le=MAX_DURABLE_JSON_INTEGER)
claim_id	str	Field(default_factory=lambda: str(uuid4()))
lease_expires_at	datetime	required

validate_clean_strings (method)

EventWatcherClaim.validate_clean_strings(value: str, info) -> str

normalize_lease_expires_at (method)

EventWatcherClaim.normalize_lease_expires_at(value: datetime) -> datetime

Release source · Runtime guarantees · Capability guides

EventWatcherContext

from cayu.observability import EventWatcherContext

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
watcher_name	str	required
record	EventRecord	required
attempt	StrictInt	Field(ge=1, le=MAX_DURABLE_JSON_INTEGER)

validate_watcher_name (method)

EventWatcherContext.validate_watcher_name(value: str) -> str

copy_record (method)

EventWatcherContext.copy_record(value: EventRecord) -> EventRecord

Release source · Runtime guarantees · Capability guides

EventWatcherDeadLetter

from cayu.observability import EventWatcherDeadLetter

A durable record of one event that exhausted its delivery attempts.

Persisting these (rather than only bumping a counter and overwriting a single last_error on the watcher state) keeps every dead-lettered event individually inspectable and replayable: the durable event log remains the source of truth, and event_sequence + event_id point back at the exact event a handler can be re-dispatched against.

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
watcher_name	str	required
event_id	str	required
event_sequence	StrictInt	Field(ge=1, le=MAX_DURABLE_JSON_INTEGER)
attempts	StrictInt	Field(ge=1, le=MAX_DURABLE_JSON_INTEGER)
error	str	required
dead_lettered_at	datetime	required
resolved_at	datetime | None	None

validate_clean_strings (method)

EventWatcherDeadLetter.validate_clean_strings(value: str, info) -> str

validate_error (method)

EventWatcherDeadLetter.validate_error(value: str) -> str

normalize_timestamp (method)

EventWatcherDeadLetter.normalize_timestamp(value: datetime | None, info) -> datetime | None

Release source · Runtime guarantees · Capability guides

EventWatcherDelivery

from cayu.observability import EventWatcherDelivery

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
watcher_name	str	required
event_id	str	required
event_sequence	StrictInt	Field(ge=1, le=MAX_DURABLE_JSON_INTEGER)
status	EventWatcherDeliveryStatus	required
attempt	StrictInt	Field(ge=1, le=MAX_DURABLE_JSON_INTEGER)
cursor_sequence	StrictInt	Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)
error	str | None	None

validate_optional_clean_strings (method)

EventWatcherDelivery.validate_optional_clean_strings(value: str | None, info) -> str | None

Release source · Runtime guarantees · Capability guides

EventWatcherDeliveryStatus

from cayu.observability import EventWatcherDeliveryStatus

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
SUCCEEDED	class attribute	'succeeded'
FAILED	class attribute	'failed'
DEAD_LETTERED	class attribute	'dead_lettered'
LEASED	class attribute	'leased'
LEASE_LOST	class attribute	'lease_lost'
PUBLICATION_FAILED	class attribute	'publication_failed'

Release source · Runtime guarantees · Capability guides

EventWatcherLeaseLost

from cayu.observability import EventWatcherLeaseLost

The store can no longer authorize this watcher delivery claim.

Bases: ValueError.

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

Release source · Runtime guarantees · Capability guides

EventWatcherRunResult

from cayu.observability import EventWatcherRunResult

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
watcher_name	str	required
deliveries	list[EventWatcherDelivery]	Field(default_factory=list)
blocked_by_active_lease	bool	False
error	str | None	None

validate_watcher_name (method)

EventWatcherRunResult.validate_watcher_name(value: str) -> str

copy_deliveries (method)

EventWatcherRunResult.copy_deliveries(value: list[EventWatcherDelivery]) -> list[EventWatcherDelivery]

Release source · Runtime guarantees · Capability guides

EventWatcherState

from cayu.observability import EventWatcherState

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
watcher_name	str	required
cursor_sequence	StrictInt	Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)
pending_event_id	str | None	None
pending_event_sequence	StrictInt | None	Field(default=None, ge=1, le=MAX_DURABLE_JSON_INTEGER)
pending_attempt	StrictInt	Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)
pending_claim_id	str | None	None
delivery_status	EventWatcherDeliveryStatus | None	None
lease_expires_at	datetime | None	None
last_error	str | None	None
dead_lettered_count	StrictInt	Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)
updated_at	datetime	Field(default_factory=lambda: datetime.now(UTC))

validate_optional_clean_strings (method)

EventWatcherState.validate_optional_clean_strings(value: str | None, info) -> str | None

normalize_timestamp (method)

EventWatcherState.normalize_timestamp(value: datetime | None, info) -> datetime | None

Release source · Runtime guarantees · Capability guides

EventWatcherStore

from cayu.observability import EventWatcherStore

Durable delivery state for event watchers.

Bases: ABC.

load_state (method)

async EventWatcherStore.load_state(watcher_name: str) -> EventWatcherState

Load watcher cursor and pending attempt state.

claim_event (method)

async EventWatcherStore.claim_event(*, watcher_name: str, record: EventRecord, lease_seconds: float, max_attempts: int=3) -> EventWatcherClaim | EventWatcherDelivery | None

Claim one event for at-least-once processing.

Returns None when another live claim owns the watcher or the cursor already passed the event. Returns a dead-letter delivery when reclaim exhausts the maximum; no handler may run for that result.

renew_claim (method)

async EventWatcherStore.renew_claim(claim: EventWatcherClaim, *, lease_seconds: float) -> EventWatcherClaim

Renew a live exact claim under authoritative store time.

Custom stores must implement this before Runtime dispatches a handler. Expired or replaced claims raise EventWatcherLeaseLost.

mark_success (method)

async EventWatcherStore.mark_success(claim: EventWatcherClaim) -> EventWatcherDelivery

Mark a claimed event handled and advance the watcher cursor.

mark_failure (method)

async EventWatcherStore.mark_failure(claim: EventWatcherClaim, *, error: str, max_attempts: int) -> EventWatcherDelivery

Mark a claimed event failed or dead-lettered.

When the final attempt is exhausted the store also persists a durable EventWatcherDeadLetter record for the event (see list_dead_letters) so it can be inspected and replayed later.

list_dead_letters (method)

async EventWatcherStore.list_dead_letters(watcher_name: str, *, include_resolved: bool=False, limit: int=100) -> list[EventWatcherDeadLetter]

Return persisted dead-letter records for a watcher, oldest first.

Unresolved records are returned by default; pass include_resolved to also surface ones already marked handled via resolve_dead_letter.

resolve_dead_letter (method)

async EventWatcherStore.resolve_dead_letter(watcher_name: str, event_sequence: int) -> EventWatcherDeadLetter

Mark a dead-letter record handled (e.g. after a successful replay).

Raises ValueError when no such record exists for the watcher.

Release source · Runtime guarantees · Capability guides

InMemoryEventWatcherStore

from cayu.observability import InMemoryEventWatcherStore

In-process watcher state for tests, examples, and single-process apps.

Bases: EventWatcherStore.

load_state (method)

async InMemoryEventWatcherStore.load_state(watcher_name: str) -> EventWatcherState

claim_event (method)

async InMemoryEventWatcherStore.claim_event(*, watcher_name: str, record: EventRecord, lease_seconds: float, max_attempts: int=3) -> EventWatcherClaim | EventWatcherDelivery | None

renew_claim (method)

async InMemoryEventWatcherStore.renew_claim(claim: EventWatcherClaim, *, lease_seconds: float) -> EventWatcherClaim

mark_success (method)

async InMemoryEventWatcherStore.mark_success(claim: EventWatcherClaim) -> EventWatcherDelivery

mark_failure (method)

async InMemoryEventWatcherStore.mark_failure(claim: EventWatcherClaim, *, error: str, max_attempts: int) -> EventWatcherDelivery

list_dead_letters (method)

async InMemoryEventWatcherStore.list_dead_letters(watcher_name: str, *, include_resolved: bool=False, limit: int=100) -> list[EventWatcherDeadLetter]

resolve_dead_letter (method)

async InMemoryEventWatcherStore.resolve_dead_letter(watcher_name: str, event_sequence: int) -> EventWatcherDeadLetter

init (method)

InMemoryEventWatcherStore.__init__(*, clock: Callable[[], datetime] | None=None) -> None

Release source · Runtime guarantees · Capability guides