Skip to content

cayu.runtime.evidence_spool

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.

EvidenceSpool

Section titled “EvidenceSpool”
from cayu.evals import EvidenceSpool

Owned snapshot with one-record reads and a bounded SQLite page cache.

Use only as a context manager. The database transaction ends before returning the sealed snapshot. No producer queue or source cursor survives capture.

init (method)

Section titled “init (method)”
EvidenceSpool.__init__(limits: IncrementalEvidenceLimits) -> None

check (method)

Section titled “check (method)”
EvidenceSpool.check() -> None

should_interrupt (method)

Section titled “should_interrupt (method)”
EvidenceSpool.should_interrupt() -> bool

cancel (method)

Section titled “cancel (method)”
EvidenceSpool.cancel() -> None

observe_page (method)

Section titled “observe_page (method)”
EvidenceSpool.observe_page(*, records: int, transport_bytes: int) -> None

append (method)

Section titled “append (method)”
EvidenceSpool.append(kind: str, record: EventRecord | TranscriptRecord) -> None

events (property)

Section titled “events (property)”
EvidenceSpool.events() -> Sequence[EventRecord]

transcript (property)

Section titled “transcript (property)”
EvidenceSpool.transcript() -> Sequence[TranscriptRecord]

stage (method)

Section titled “stage (method)”
EvidenceSpool.stage(session: Session, marker: TerminalPublicationMarker | None, terminal_record: EventRecord, event_count: int, transcript_count: int) -> None

seal (method)

Section titled “seal (method)”
EvidenceSpool.seal() -> None

seal_async (method)

Section titled “seal_async (method)”
async EvidenceSpool.seal_async() -> None

run_owned (method)

Section titled “run_owned (method)”
async EvidenceSpool.run_owned(operation: Awaitable[object]) -> None

Do not release the backing while a cancelled worker still owns it.

close (method)

Section titled “close (method)”
EvidenceSpool.close() -> None

Release source · Runtime guarantees · Capability guides

IncrementalEvidenceAdmission

Section titled “IncrementalEvidenceAdmission”
from cayu.evals import IncrementalEvidenceAdmission

Explicit shared fail-fast admission; no hidden queue or retry scheduler.

Share one instance across all captures on a worker. The payload envelope is serialized bytes, not an assertion about Python allocator overhead or RSS.

init (method)

Section titled “init (method)”
IncrementalEvidenceAdmission.__init__(*, max_captures: int=8, max_buffer_bytes: int=512 * 1024 * 1024, max_spill_bytes: int=4 * 1024 * 1024 * 1024) -> None

buffer_envelope (method)

Section titled “buffer_envelope (method)”
IncrementalEvidenceAdmission.buffer_envelope(limits: IncrementalEvidenceLimits) -> int

reserve (method)

Section titled “reserve (method)”
IncrementalEvidenceAdmission.reserve(limits: IncrementalEvidenceLimits) -> _EvidenceReservation

Release source · Runtime guarantees · Capability guides

IncrementalEvidenceError

Section titled “IncrementalEvidenceError”
from cayu.evals import IncrementalEvidenceError

Payload-free resource or capability failure.

Bases: RuntimeError.

init (method)

Section titled “init (method)”
IncrementalEvidenceError.__init__(code: str) -> None

Release source · Runtime guarantees · Capability guides

IncrementalEvidenceLimits

Section titled “IncrementalEvidenceLimits”
from cayu.evals import IncrementalEvidenceLimits

Work and disk limits, independent of the eager materialization ceiling.

Bases: BaseModel.

Fields and attributes

Section titled “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_root_bytes StrictInt Field(default=4194304, ge=1, le=16777216)
max_root_events StrictInt Field(default=10000, ge=1, le=10000)
max_sessions StrictInt Field(default=100, ge=1, le=500)
max_depth StrictInt Field(default=32, ge=1, le=32)
max_events StrictInt Field(default=1000000, ge=1, le=100000000)
max_transcript_records StrictInt Field(default=100000, ge=0, le=10000000)
max_record_bytes StrictInt Field(default=1048576, ge=1, le=TERMINAL_SESSION_EVIDENCE_HARD_MAX_RECORD_BYTES)
max_total_bytes StrictInt Field(default=268435456, ge=1, le=4294967296)
max_spill_bytes StrictInt Field(default=536870912, ge=12288, le=8589934592)
batch_records StrictInt Field(default=4, ge=1, le=256)
max_lifecycle_bytes StrictInt Field(default=2097152, ge=1, le=16777216)
max_lifecycle_records StrictInt Field(default=10000, ge=1, le=100000)
max_seconds StrictInt Field(default=300, ge=1, le=3600)

Release source · Runtime guarantees · Capability guides