cayu.observability.timing

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.

ModelStepPreparationTiming

from cayu.observability import ModelStepPreparationTiming

Observed gap to the next model start, split into exclusive preparation phases.

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
schema_version	Literal[1]	1
kind	Literal['model_step_preparation']	'model_step_preparation'
session_id	TimingIdentifier	required
model_step_id	TimingIdentifier	required
after_tool_round_id	TimingIdentifier | None	required
started_at	datetime	required
completed_at	datetime	required
duration_seconds	NonnegativeSeconds	required
incomplete	bool	required
phases	tuple[RuntimePhaseTiming, ...]	Field(max_length=5)

Release source · Runtime guarantees · Capability guides

RuntimePhaseTiming

from cayu.observability import RuntimePhaseTiming

Exclusive phase time; SQL execution includes database lock acquisition.

first_started_at and last_completed_at bound the observed entries; a phase can be entered more than once, so the window can exceed its duration.

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
name	TimingPhaseName	required
first_started_at	datetime | None	None
last_completed_at	datetime | None	None
duration_seconds	NonnegativeSeconds	0
store_transaction_count	StrictInt	Field(default=0, ge=0)
store_lock_wait_seconds	NonnegativeSeconds	0
store_execution_seconds	NonnegativeSeconds	0
store_commit_seconds	NonnegativeSeconds	0
store_bytes_written	StrictInt	Field(default=0, ge=0)

Release source · Runtime guarantees · Capability guides

RuntimeTimingConfig

from cayu.observability import RuntimeTimingConfig

Bounded recent records and best-effort delivery; disable for the cheapest path.

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
enabled	bool	True
recent_capacity	StrictInt	Field(default=64, ge=1, le=1024)
max_calls_per_round	StrictInt	Field(default=128, ge=1, le=1024)
sink_queue_capacity	StrictInt	Field(default=128, ge=1, le=1024)
sink_timeout_seconds	float	Field(default=1, ge=0.01, le=30, allow_inf_nan=False)

Release source · Runtime guarantees · Capability guides

RuntimeTimingRecord

from cayu.observability import RuntimeTimingRecord

RuntimeTimingRecord = ToolRoundTiming | ModelStepPreparationTiming

Release source · Runtime guarantees · Capability guides

RuntimeTimingSink

from cayu.observability import RuntimeTimingSink

Receive best-effort observations without durable sink receipts or retries.

Bases: Protocol.

emit_timing (method)

async RuntimeTimingSink.emit_timing(record: RuntimeTimingRecord) -> None

Release source · Runtime guarantees · Capability guides

RuntimeTimingStatus

from cayu.observability import RuntimeTimingStatus

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
recent_records	int	required
queued_records	int	required
dropped_records	int	required
failed_deliveries	int	required

Release source · Runtime guarantees · Capability guides

ToolCallTiming

from cayu.observability import ToolCallTiming

A call’s observed phases, without arguments, results, prompts or exceptions.

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
session_id	TimingIdentifier	required
tool_round_id	TimingIdentifier	required
tool_call_id	TimingIdentifier	required
tool_name	TimingIdentifier	required
phases	tuple[RuntimePhaseTiming, ...]	Field(max_length=12)
tool_effect_completed_at	datetime | None	None
tool_terminal_staged_at	datetime | None	None
tool_terminal_publication_started_at	datetime | None	None

Release source · Runtime guarantees · Capability guides

ToolRoundTiming

from cayu.observability import ToolRoundTiming

Round totals include call phases; parallel elapsed time is not additive wall time.

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
schema_version	Literal[1]	1
kind	Literal['tool_round']	'tool_round'
session_id	TimingIdentifier	required
tool_round_id	TimingIdentifier	required
model_step_id	TimingIdentifier	required
model_attempt_id	TimingIdentifier	required
started_at	datetime	required
completed_at	datetime	required
duration_seconds	NonnegativeSeconds	required
incomplete	bool	required
recovered	bool	False
calls_truncated	StrictInt	Field(default=0, ge=0)
phases	tuple[RuntimePhaseTiming, ...]	Field(max_length=12)
calls	tuple[ToolCallTiming, ...]	Field(max_length=1024)

Release source · Runtime guarantees · Capability guides