Skip to content

cayu.runtime.evidence

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.

runtime_evidence

Section titled “runtime_evidence”
from cayu import runtime_evidence

Reconstruct one bounded, deterministic runtime-evidence report.

async runtime_evidence(app: CayuApp, request: RuntimeEvidenceRequest) -> RuntimeEvidenceReport

Release source · Runtime guarantees · Capability guides

RUNTIME_EVIDENCE_SCHEMA_VERSION

Section titled “RUNTIME_EVIDENCE_SCHEMA_VERSION”
from cayu import RUNTIME_EVIDENCE_SCHEMA_VERSION
RUNTIME_EVIDENCE_SCHEMA_VERSION = 6

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceApproval

Section titled “RuntimeEvidenceApproval”
from cayu import RuntimeEvidenceApproval

Secret-free approval identity and terminal decision.

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
approval_id str Field(max_length=_MAX_IDENTITY_CHARS)
tool_call_id str Field(max_length=_MAX_IDENTITY_CHARS)
tool_round_id str Field(max_length=_MAX_IDENTITY_CHARS)
policy_decision _PolicyDecision | None None
decision _ApprovalDecision required
source_refs tuple[RuntimeEvidenceSourceRef, ...] required

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceAttempt

Section titled “RuntimeEvidenceAttempt”
from cayu import RuntimeEvidenceAttempt

One durable provider dispatch and its allowlisted accounting evidence.

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
attempt_id str Field(max_length=_MAX_IDENTITY_CHARS)
model_step_id str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
execution_profile_fingerprint str | None Field(default=None, max_length=64, exclude_if=lambda value: value is None)
operation RuntimeEvidenceOperation required
auxiliary_inference RuntimeEvidenceAuxiliaryInference | None Field(default=None, exclude_if=lambda value: value is None)
attempt_ordinal StrictInt Field(ge=1, le=MAX_DURABLE_JSON_INTEGER)
provider_name str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
requested_model str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
model str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
status RuntimeEvidenceAttemptStatus required
usage_status RuntimeEvidenceUsageStatus required
usage RuntimeEvidenceUsage | None required
cost RuntimeEvidenceCost required
source_refs tuple[RuntimeEvidenceSourceRef, ...] required

validate_execution_profile_fingerprint (method)

Section titled “validate_execution_profile_fingerprint (method)”
RuntimeEvidenceAttempt.validate_execution_profile_fingerprint(value: str | None) -> str | None

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceAttemptStatus

Section titled “RuntimeEvidenceAttemptStatus”
from cayu import RuntimeEvidenceAttemptStatus

Strongest terminal state observed for one provider attempt.

Bases: StrEnum.

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
STARTED class attribute 'started'
RETRY_SCHEDULED class attribute 'retry_scheduled'
DISCARDED class attribute 'discarded'
FAILED class attribute 'failed'
COMPLETED class attribute 'completed'
CANCELLED class attribute 'cancelled'
TIMED_OUT class attribute 'timed_out'
OUTCOME_UNKNOWN class attribute 'outcome_unknown'

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceAuxiliaryInference

Section titled “RuntimeEvidenceAuxiliaryInference”
from cayu import RuntimeEvidenceAuxiliaryInference

Content-free auxiliary purpose and exact enclosing operation links.

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
operation_id StrictStr Field(min_length=1, max_length=_MAX_IDENTITY_CHARS)
purpose StrictStr Field(min_length=1, max_length=128)
parent_model_step_id StrictStr Field(min_length=1, max_length=_MAX_IDENTITY_CHARS)
parent_model_attempt_id StrictStr Field(min_length=1, max_length=_MAX_IDENTITY_CHARS)
parent_tool_round_id StrictStr Field(min_length=1, max_length=_MAX_IDENTITY_CHARS)
parent_tool_call_id StrictStr Field(min_length=1, max_length=_MAX_IDENTITY_CHARS)

validate_purpose (method)

Section titled “validate_purpose (method)”
RuntimeEvidenceAuxiliaryInference.validate_purpose(value: str) -> str

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceBranchTotals

Section titled “RuntimeEvidenceBranchTotals”
from cayu import RuntimeEvidenceBranchTotals

Totals for one direct child subtree of the requested root.

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
branch_root_session_id str Field(max_length=_MAX_IDENTITY_CHARS)
session_ids tuple[str, ...] Field(max_length=_HARD_MAX_SESSIONS)
totals RuntimeEvidenceTotals required

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceCacheUsage

Section titled “RuntimeEvidenceCacheUsage”
from cayu import RuntimeEvidenceCacheUsage

Identity-free cache counters safe for report serialization.

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
read_tokens AggregateCount Field(ge=0)
write_tokens AggregateCount Field(ge=0)
write_5m_tokens AggregateCount Field(ge=0)
write_1h_tokens AggregateCount Field(ge=0)
write_unknown_ttl_tokens AggregateCount Field(ge=0)
cached_input_tokens AggregateCount Field(ge=0)
uncached_input_tokens AggregateCount Field(ge=0)

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceCheckpoint

Section titled “RuntimeEvidenceCheckpoint”
from cayu import RuntimeEvidenceCheckpoint

Checkpoint publication identity without checkpoint contents.

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
checkpoint_id str Field(max_length=_MAX_IDENTITY_CHARS)
kind Literal['context_compaction', 'pending_tool_approval', 'pending_user_input', 'manual_recovery', 'custom', 'unknown'] required
compacted_transcript_cursor StrictInt | None Field(default=None, ge=0)
source_ref RuntimeEvidenceSourceRef required

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceCompaction

Section titled “RuntimeEvidenceCompaction”
from cayu import RuntimeEvidenceCompaction

Payload-free compaction identity, outcome, and durable provenance.

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
compaction_id str Field(max_length=_MAX_IDENTITY_CHARS)
status Literal['started', 'completed', 'failed'] required
source_refs tuple[RuntimeEvidenceSourceRef, ...] required

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceCost

Section titled “RuntimeEvidenceCost”
from cayu import RuntimeEvidenceCost

Bounded optional pricing result for one provider attempt.

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
status RuntimeEvidenceCostStatus required
currency str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
total_cost Decimal | None Field(default=None, ge=0)
pricing_provider_name str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
pricing_model str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)

validate_total_cost (method)

Section titled “validate_total_cost (method)”
RuntimeEvidenceCost.validate_total_cost(value: Decimal | None) -> Decimal | None

validate_status (method)

Section titled “validate_status (method)”
RuntimeEvidenceCost.validate_status() -> RuntimeEvidenceCost

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceCostStatus

Section titled “RuntimeEvidenceCostStatus”
from cayu import RuntimeEvidenceCostStatus

Availability of optional application-priced cost for one attempt.

Bases: StrEnum.

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
NOT_REQUESTED class attribute 'not_requested'
MISSING_USAGE class attribute 'missing_usage'
PRICED class attribute 'priced'
UNPRICED class attribute 'unpriced'

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceCurrencyCost

Section titled “RuntimeEvidenceCurrencyCost”
from cayu import RuntimeEvidenceCurrencyCost

One currency-local priced subtotal.

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
currency str Field(max_length=_MAX_IDENTITY_CHARS)
total_cost Decimal Field(ge=0)

validate_total_cost (method)

Section titled “validate_total_cost (method)”
RuntimeEvidenceCurrencyCost.validate_total_cost(value: Decimal) -> Decimal

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceError

Section titled “RuntimeEvidenceError”
from cayu import RuntimeEvidenceError

Typed runtime-evidence traversal or bounds failure.

Bases: RuntimeError.

init (method)

Section titled “init (method)”
RuntimeEvidenceError.__init__(code: RuntimeEvidenceErrorCode, *, root_session_id: str, session_id: str | None=None, limit: int | None=None, observed: int | None=None) -> None

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceErrorCode

Section titled “RuntimeEvidenceErrorCode”
from cayu import RuntimeEvidenceErrorCode

Stable fail-closed error from runtime_evidence.

Bases: StrEnum.

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
ROOT_NOT_FOUND class attribute 'root_not_found'
STORE_UNSUPPORTED class attribute 'store_unsupported'
EVIDENCE_READ_FAILED class attribute 'evidence_read_failed'
PARENT_CONTRADICTION class attribute 'parent_contradiction'
CYCLE_DETECTED class attribute 'cycle_detected'
SESSION_LIMIT_EXCEEDED class attribute 'session_limit_exceeded'
CAUSAL_BUDGET_LIMIT_EXCEEDED class attribute 'causal_budget_limit_exceeded'
EVENT_LIMIT_EXCEEDED class attribute 'event_limit_exceeded'
EVENT_SOURCE_BYTES_EXCEEDED class attribute 'event_source_bytes_exceeded'

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceEventCursor

Section titled “RuntimeEvidenceEventCursor”
from cayu import RuntimeEvidenceEventCursor

Last durable event retained for one session.

Bases: RuntimeEvidenceSourceRef.

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
event_id str Field(max_length=_MAX_IDENTITY_CHARS)
sequence StrictInt Field(ge=1, le=MAX_DURABLE_JSON_INTEGER)

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceOperation

Section titled “RuntimeEvidenceOperation”
from cayu import RuntimeEvidenceOperation

Why a retained provider attempt was dispatched.

Bases: StrEnum.

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
AGENT_STEP class attribute 'agent_step'
AUXILIARY_INFERENCE class attribute 'auxiliary_inference'
COMPACTION class attribute 'compaction'
STRUCTURED_OUTPUT_REPAIR class attribute 'structured_output_repair'
EVALUATION class attribute 'evaluation'
REPAIR class attribute 'repair'
COMPARISON_CONTROL class attribute 'comparison_control'
UNKNOWN class attribute 'unknown'

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceOperationTotals

Section titled “RuntimeEvidenceOperationTotals”
from cayu import RuntimeEvidenceOperationTotals

Usage attributed to one typed operation.

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
operation RuntimeEvidenceOperation required
attempt_count AggregateCount Field(ge=0)
usage RuntimeEvidenceUsage required

Release source · Runtime guarantees · Capability guides

RuntimeEvidencePolicyDecision

Section titled “RuntimeEvidencePolicyDecision”
from cayu import RuntimeEvidencePolicyDecision

Allowlisted policy outcome and the event that recorded it.

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
decision Literal['allow', 'deny', 'require_approval', 'ambiguous', 'blocked'] required
tool_call_id str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
tool_name str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
matched_taint_labels tuple[str, ...] ()
source_ref RuntimeEvidenceSourceRef required

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceReceipt

Section titled “RuntimeEvidenceReceipt”
from cayu import RuntimeEvidenceReceipt

External-effect receipt identity without body or tool result.

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
receipt_id str Field(max_length=_MAX_IDENTITY_CHARS)
tool_call_id str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
reconciliation_state Literal['recorded', 'reconciled', 'unknown'] required
source_ref RuntimeEvidenceSourceRef required
receipt_evidence RuntimeEvidenceToolEffectReceipt | None None

copy_receipt_evidence (method)

Section titled “copy_receipt_evidence (method)”
RuntimeEvidenceReceipt.copy_receipt_evidence(value: object)

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceRecoverySummary

Section titled “RuntimeEvidenceRecoverySummary”
from cayu import RuntimeEvidenceRecoverySummary

Content-free interruption and recovery counts.

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
interruption_count AggregateCount Field(ge=0)
resume_count AggregateCount Field(ge=0)
manual_recovery_required_count AggregateCount Field(ge=0)
manual_reconciliation_count AggregateCount Field(ge=0)
source_refs tuple[RuntimeEvidenceSourceRef, ...] ()

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceReport

Section titled “RuntimeEvidenceReport”
from cayu import RuntimeEvidenceReport

Versioned, deterministic runtime-evidence read model.

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
schema_version Literal[6] RUNTIME_EVIDENCE_SCHEMA_VERSION
root_session_id str Field(max_length=_MAX_IDENTITY_CHARS)
scope RuntimeEvidenceScope required
sessions tuple[RuntimeEvidenceSession, ...] Field(max_length=_HARD_MAX_SESSIONS)
tasks tuple[RuntimeEvidenceTask, ...] Field(default=(), max_length=_MAX_TASKS)
lineage_totals RuntimeEvidenceTotals required
branch_totals tuple[RuntimeEvidenceBranchTotals, ...] required
causal_budget_totals RuntimeEvidenceTotals | None None
whole_workflow_totals RuntimeEvidenceTotals | None None
pricing_catalog_version str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
pricing_catalog_generated_at str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
warnings tuple[RuntimeEvidenceWarning, ...] ()

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceRequest

Section titled “RuntimeEvidenceRequest”
from cayu import RuntimeEvidenceRequest

Bounded request for a durable runtime-evidence projection.

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
root_session_id str Field(max_length=_MAX_IDENTITY_CHARS)
max_sessions StrictInt Field(ge=1, le=_HARD_MAX_SESSIONS)
max_events StrictInt Field(ge=1, le=_HARD_MAX_EVENTS)
include_descendants StrictBool True
memory_attribution_bounds MemoryAttributionBounds Field(default_factory=MemoryAttributionBounds)
include_causal_budget StrictBool False
max_causal_budget_sessions StrictInt Field(default=_DEFAULT_MAX_CAUSAL_BUDGET_SESSIONS, ge=1, le=_HARD_MAX_SESSIONS)
pricing PriceBook | None None

copy_memory_attribution_bounds (method)

Section titled “copy_memory_attribution_bounds (method)”
RuntimeEvidenceRequest.copy_memory_attribution_bounds(value: object) -> MemoryAttributionBounds

validate_root_session_id (method)

Section titled “validate_root_session_id (method)”
RuntimeEvidenceRequest.validate_root_session_id(value: str) -> str

copy_pricing (method)

Section titled “copy_pricing (method)”
RuntimeEvidenceRequest.copy_pricing(value: PriceBook | None) -> PriceBook | None

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceScope

Section titled “RuntimeEvidenceScope”
from cayu import RuntimeEvidenceScope

Exact retained descendant and optional causal-budget scope.

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
root_session_id str Field(max_length=_MAX_IDENTITY_CHARS)
causal_budget_id str Field(max_length=_MAX_IDENTITY_CHARS)
descendant_session_ids tuple[str, ...] Field(max_length=_HARD_MAX_SESSIONS)
causal_budget_session_ids tuple[str, ...] | None Field(default=None, max_length=_HARD_MAX_SESSIONS)

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceSession

Section titled “RuntimeEvidenceSession”
from cayu import RuntimeEvidenceSession

Stable, safe evidence projection for one durable session.

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
session_id str Field(max_length=_MAX_IDENTITY_CHARS)
parent_session_id str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
agent_name str Field(max_length=_MAX_IDENTITY_CHARS)
task_ids tuple[str, ...] ()
causal_budget_id str Field(max_length=_MAX_IDENTITY_CHARS)
provider_name str Field(max_length=_MAX_IDENTITY_CHARS)
model str Field(max_length=_MAX_IDENTITY_CHARS)
status SessionStatus required
last_event_cursor RuntimeEvidenceEventCursor | None required
origin_refs tuple[RuntimeEvidenceSourceRef, ...] ()
checkpoints tuple[RuntimeEvidenceCheckpoint, ...] ()
compactions tuple[RuntimeEvidenceCompaction, ...] ()
compaction_count AggregateCount Field(default=0, ge=0)
attempts tuple[RuntimeEvidenceAttempt, ...] ()
tool_calls tuple[RuntimeEvidenceToolCall, ...] ()
approvals tuple[RuntimeEvidenceApproval, ...] ()
effective_taint_labels tuple[str, ...] ()
policy_decisions tuple[RuntimeEvidencePolicyDecision, ...] ()
recovery RuntimeEvidenceRecoverySummary required
memory_attribution MemoryAttribution required
receipts tuple[RuntimeEvidenceReceipt, ...] ()
workspace_mutations tuple[RuntimeEvidenceWorkspaceMutation, ...] ()
workspace_finalization RuntimeEvidenceWorkspaceFinalization | None None
totals RuntimeEvidenceTotals required

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceSourceRef

Section titled “RuntimeEvidenceSourceRef”
from cayu import RuntimeEvidenceSourceRef

Stable source event identity for one derived fact.

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
event_id str Field(max_length=_MAX_IDENTITY_CHARS)
sequence StrictInt Field(ge=1, le=MAX_DURABLE_JSON_INTEGER)

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceTask

Section titled “RuntimeEvidenceTask”
from cayu import RuntimeEvidenceTask

Payload-free durable task identity linked to a retained session.

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
task_id str Field(max_length=_MAX_IDENTITY_CHARS)
session_id str Field(max_length=_MAX_IDENTITY_CHARS)
parent_task_id str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
status Literal['pending', 'waiting_dependencies', 'waiting_group', 'dependency_skipped', 'claimed', 'running', 'paused', 'blocked', 'needs_attention', 'completed', 'failed', 'cancelled'] required

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceToolCall

Section titled “RuntimeEvidenceToolCall”
from cayu import RuntimeEvidenceToolCall

Payload-free logical tool-call evidence.

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
tool_call_id str Field(max_length=_MAX_IDENTITY_CHARS)
tool_round_id str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
tool_name str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
idempotency_key str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
status _ToolCallStatus required
source_refs tuple[RuntimeEvidenceSourceRef, ...] required

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceToolEffectReceipt

Section titled “RuntimeEvidenceToolEffectReceipt”
from cayu import RuntimeEvidenceToolEffectReceipt

Validated, redacted receipt envelope; never external response content.

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
schema_version StrictInt Field(ge=1, le=1)
receipt_id StrictStr required
receipt_schema StrictStr required
receipt_schema_version StrictInt Field(ge=1, le=2 ** 31 - 1)
outcome Literal['completed', 'failed'] required
source Literal['adapter', 'reconciler', 'operator'] required
observed_at AwareDatetime required
receipt_digest StrictStr Field(pattern='^[0-9a-f]{64}$')
integrity dict[str, str] required
resource_versions dict[str, str] required

validate_identity (method)

Section titled “validate_identity (method)”
RuntimeEvidenceToolEffectReceipt.validate_identity(value: str, info) -> str

copy_maps (method)

Section titled “copy_maps (method)”
RuntimeEvidenceToolEffectReceipt.copy_maps(value: object, info) -> dict[str, str]

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceTotals

Section titled “RuntimeEvidenceTotals”
from cayu import RuntimeEvidenceTotals

Recomputed accounting over one explicit evidence scope.

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
session_count AggregateCount Field(ge=0)
model_step_count AggregateCount Field(ge=0)
attempt_count AggregateCount Field(ge=0)
first_attempt_count AggregateCount Field(ge=0)
provider_retry_attempt_count AggregateCount Field(ge=0)
structured_output_repair_attempt_count AggregateCount Field(ge=0)
tool_call_count AggregateCount Field(ge=0)
missing_usage_attempt_count AggregateCount Field(ge=0)
usage RuntimeEvidenceUsage required
first_attempt_usage RuntimeEvidenceUsage required
provider_retry_usage RuntimeEvidenceUsage required
structured_output_repair_usage RuntimeEvidenceUsage required
compaction_usage RuntimeEvidenceUsage required
evaluation_usage RuntimeEvidenceUsage required
repair_usage RuntimeEvidenceUsage required
comparison_control_usage RuntimeEvidenceUsage required
operations tuple[RuntimeEvidenceOperationTotals, ...] ()
priced_costs tuple[RuntimeEvidenceCurrencyCost, ...] ()
priced_attempt_count AggregateCount Field(default=0, ge=0)
unpriced_attempt_count AggregateCount Field(default=0, ge=0)

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceUsage

Section titled “RuntimeEvidenceUsage”
from cayu import RuntimeEvidenceUsage

Provider-reported token counters with commercial identity removed.

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
input_tokens AggregateCount Field(ge=0)
output_tokens AggregateCount Field(ge=0)
total_tokens AggregateCount Field(ge=0)
reasoning_output_tokens AggregateCount Field(ge=0)
cache RuntimeEvidenceCacheUsage required

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceUsageStatus

Section titled “RuntimeEvidenceUsageStatus”
from cayu import RuntimeEvidenceUsageStatus

Availability of provider-reported usage for one attempt.

Bases: StrEnum.

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
REPORTED class attribute 'reported'
MISSING class attribute 'missing'
MALFORMED class attribute 'malformed'

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceWarning

Section titled “RuntimeEvidenceWarning”
from cayu import RuntimeEvidenceWarning

One bounded, content-free evidence degradation marker.

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
code RuntimeEvidenceWarningCode required
session_id str Field(max_length=_MAX_IDENTITY_CHARS)
event_id str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
sequence StrictInt | None Field(default=None, ge=1, le=MAX_DURABLE_JSON_INTEGER)

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceWarningCode

Section titled “RuntimeEvidenceWarningCode”
from cayu import RuntimeEvidenceWarningCode

Stable reason some requested evidence is partial or unavailable.

Bases: StrEnum.

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
UNKNOWN_EVENT_TYPE class attribute 'unknown_event_type'
UNKNOWN_OPERATION class attribute 'unknown_operation'
LEGACY_ATTEMPT_IDENTITY class attribute 'legacy_attempt_identity'
MISSING_USAGE class attribute 'missing_usage'
MALFORMED_USAGE class attribute 'malformed_usage'
MALFORMED_AUXILIARY_INFERENCE class attribute 'malformed_auxiliary_inference'
UNPRICED_USAGE class attribute 'unpriced_usage'
MALFORMED_CHECKPOINT class attribute 'malformed_checkpoint'
MALFORMED_COMPACTION class attribute 'malformed_compaction'
MALFORMED_TOOL_CALL class attribute 'malformed_tool_call'
MALFORMED_APPROVAL class attribute 'malformed_approval'
MALFORMED_RECEIPT class attribute 'malformed_receipt'
MALFORMED_POLICY_DECISION class attribute 'malformed_policy_decision'
MALFORMED_TAINT_LABELS class attribute 'malformed_taint_labels'
MALFORMED_EXECUTION_PROFILE class attribute 'malformed_execution_profile'
MALFORMED_WORKSPACE_EVIDENCE class attribute 'malformed_workspace_evidence'
ORIGIN_EVIDENCE_UNAVAILABLE class attribute 'origin_evidence_unavailable'
TASK_EVIDENCE_UNAVAILABLE class attribute 'task_evidence_unavailable'
TASK_EVIDENCE_PARTIAL class attribute 'task_evidence_partial'

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceWorkspaceArtifact

Section titled “RuntimeEvidenceWorkspaceArtifact”
from cayu import RuntimeEvidenceWorkspaceArtifact

Content-free workspace evidence artifact reference.

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
kind Literal['revision-before', 'revision-after', 'revision-delta'] required
artifact_id str Field(max_length=_MAX_IDENTITY_CHARS)
sha256 str Field(min_length=64, max_length=64)
size_bytes StrictInt Field(ge=1, le=16 * 1024 * 1024)
state Literal['intent', 'published', 'referenced', 'failed', 'orphaned', 'missing'] required

validate_artifact_id (method)

Section titled “validate_artifact_id (method)”
RuntimeEvidenceWorkspaceArtifact.validate_artifact_id(value: str) -> str

validate_sha256 (method)

Section titled “validate_sha256 (method)”
RuntimeEvidenceWorkspaceArtifact.validate_sha256(value: str) -> str

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceWorkspaceAttribution

Section titled “RuntimeEvidenceWorkspaceAttribution”
from cayu import RuntimeEvidenceWorkspaceAttribution

Safe classification of responsibility for one workspace mutation.

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
confidence Literal['exclusive_tool', 'concurrent_ambiguity', 'external_or_unknown', 'unattributed_finalization_change'] required
writer_isolation Literal['exclusive', 'shared', 'unknown'] required
overlap_detected StrictBool required
direct_reconciliation Literal['not_observed', 'consistent', 'incomplete', 'contradictory', 'truncated'] required
detail_code str Field(max_length=_MAX_IDENTITY_CHARS)

validate_detail_code (method)

Section titled “validate_detail_code (method)”
RuntimeEvidenceWorkspaceAttribution.validate_detail_code(value: str) -> str

validate_attribution_shape (method)

Section titled “validate_attribution_shape (method)”
RuntimeEvidenceWorkspaceAttribution.validate_attribution_shape() -> RuntimeEvidenceWorkspaceAttribution

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceWorkspaceDelta

Section titled “RuntimeEvidenceWorkspaceDelta”
from cayu import RuntimeEvidenceWorkspaceDelta

Path-free summary of one workspace revision delta.

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
status Literal['changed', 'no_change', 'unsupported', 'failed', 'incomplete', 'truncated'] required
before_revision str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
after_revision str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
total_paths StrictInt Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)
head_changed StrictBool required
branch_changed StrictBool required
detail_code str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
attribution_confidence Literal['exclusive_tool', 'concurrent_ambiguity', 'external_or_unknown', 'unattributed_finalization_change'] | None None
source_ref RuntimeEvidenceSourceRef required

validate_optional_revision (method)

Section titled “validate_optional_revision (method)”
RuntimeEvidenceWorkspaceDelta.validate_optional_revision(value: str | None, info) -> str | None

validate_detail_code (method)

Section titled “validate_detail_code (method)”
RuntimeEvidenceWorkspaceDelta.validate_detail_code(value: str | None) -> str | None

validate_delta_shape (method)

Section titled “validate_delta_shape (method)”
RuntimeEvidenceWorkspaceDelta.validate_delta_shape() -> RuntimeEvidenceWorkspaceDelta

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceWorkspaceFinalization

Section titled “RuntimeEvidenceWorkspaceFinalization”
from cayu import RuntimeEvidenceWorkspaceFinalization

Last safely observable workspace state at environment finalization.

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
workspace_id str Field(max_length=_MAX_IDENTITY_CHARS)
binding_generation_id str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
status Literal['supported', 'unsupported', 'failed', 'incomplete', 'truncated'] required
revision str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
path_scope Literal['complete', 'changed'] required
total_paths StrictInt Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)
detail_code str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
delta RuntimeEvidenceWorkspaceDelta | None None
source_refs tuple[RuntimeEvidenceSourceRef, ...] ()

validate_identity (method)

Section titled “validate_identity (method)”
RuntimeEvidenceWorkspaceFinalization.validate_identity(value: str | None, info) -> str | None

validate_optional_revision (method)

Section titled “validate_optional_revision (method)”
RuntimeEvidenceWorkspaceFinalization.validate_optional_revision(value: str | None) -> str | None

validate_detail_code (method)

Section titled “validate_detail_code (method)”
RuntimeEvidenceWorkspaceFinalization.validate_detail_code(value: str | None) -> str | None

validate_final_revision_shape (method)

Section titled “validate_final_revision_shape (method)”
RuntimeEvidenceWorkspaceFinalization.validate_final_revision_shape() -> RuntimeEvidenceWorkspaceFinalization

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceWorkspaceMutation

Section titled “RuntimeEvidenceWorkspaceMutation”
from cayu import RuntimeEvidenceWorkspaceMutation

Correlated, content-free evidence for one workspace mutation window.

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
window_id str Field(max_length=_MAX_IDENTITY_CHARS)
workspace_id str Field(max_length=_MAX_IDENTITY_CHARS)
tool_call_id str Field(max_length=_MAX_IDENTITY_CHARS)
tool_round_id str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
before RuntimeEvidenceWorkspaceRevision | None None
after RuntimeEvidenceWorkspaceRevision | None None
delta RuntimeEvidenceWorkspaceDelta | None None
attribution RuntimeEvidenceWorkspaceAttribution | None None
terminal RuntimeEvidenceWorkspaceTerminal | None None
artifacts tuple[RuntimeEvidenceWorkspaceArtifact, ...] ()
source_refs tuple[RuntimeEvidenceSourceRef, ...] ()

validate_identity (method)

Section titled “validate_identity (method)”
RuntimeEvidenceWorkspaceMutation.validate_identity(value: str | None, info) -> str | None

validate_correlated_evidence (method)

Section titled “validate_correlated_evidence (method)”
RuntimeEvidenceWorkspaceMutation.validate_correlated_evidence() -> RuntimeEvidenceWorkspaceMutation

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceWorkspaceRevision

Section titled “RuntimeEvidenceWorkspaceRevision”
from cayu import RuntimeEvidenceWorkspaceRevision

Path-free summary of one workspace revision observation.

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
phase Literal['before', 'after'] required
status Literal['supported', 'unsupported', 'failed', 'incomplete', 'truncated'] required
revision str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
path_scope Literal['complete', 'changed'] required
total_paths StrictInt Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)
detail_code str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
source_ref RuntimeEvidenceSourceRef required

validate_optional_revision (method)

Section titled “validate_optional_revision (method)”
RuntimeEvidenceWorkspaceRevision.validate_optional_revision(value: str | None) -> str | None

validate_detail_code (method)

Section titled “validate_detail_code (method)”
RuntimeEvidenceWorkspaceRevision.validate_detail_code(value: str | None) -> str | None

validate_revision_shape (method)

Section titled “validate_revision_shape (method)”
RuntimeEvidenceWorkspaceRevision.validate_revision_shape() -> RuntimeEvidenceWorkspaceRevision

Release source · Runtime guarantees · Capability guides

RuntimeEvidenceWorkspaceTerminal

Section titled “RuntimeEvidenceWorkspaceTerminal”
from cayu import RuntimeEvidenceWorkspaceTerminal

Final durable state of one workspace-observation window.

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
status Literal['complete', 'incomplete', 'ambiguous', 'failed'] required
detail_code str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
session_run_epoch StrictInt | None Field(default=None, ge=1)
recovery_run_epoch StrictInt | None Field(default=None, ge=1)
binding_generation_id str | None Field(default=None, max_length=_MAX_IDENTITY_CHARS)
source_ref RuntimeEvidenceSourceRef required

validate_optional_identity (method)

Section titled “validate_optional_identity (method)”
RuntimeEvidenceWorkspaceTerminal.validate_optional_identity(value: str | None) -> str | None

validate_detail_code (method)

Section titled “validate_detail_code (method)”
RuntimeEvidenceWorkspaceTerminal.validate_detail_code(value: str | None) -> str | None

validate_terminal_shape (method)

Section titled “validate_terminal_shape (method)”
RuntimeEvidenceWorkspaceTerminal.validate_terminal_shape() -> RuntimeEvidenceWorkspaceTerminal

Release source · Runtime guarantees · Capability guides