cayu.snapshots.bundles

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.

AGENT_BUNDLE_INDEX_FILENAME

from cayu.snapshots import AGENT_BUNDLE_INDEX_FILENAME

AGENT_BUNDLE_INDEX_FILENAME = 'index.json'

Release source · Runtime guarantees · Capability guides

AGENT_BUNDLE_MAX_INDEX_BYTES

from cayu.snapshots import AGENT_BUNDLE_MAX_INDEX_BYTES

AGENT_BUNDLE_MAX_INDEX_BYTES = 16 * 1024 * 1024

Release source · Runtime guarantees · Capability guides

AGENT_BUNDLE_MAX_OBJECT_BYTES

from cayu.snapshots import AGENT_BUNDLE_MAX_OBJECT_BYTES

AGENT_BUNDLE_MAX_OBJECT_BYTES = 64 * 1024 * 1024 * 1024

Release source · Runtime guarantees · Capability guides

AGENT_BUNDLE_MAX_OBJECTS

from cayu.snapshots import AGENT_BUNDLE_MAX_OBJECTS

AGENT_BUNDLE_MAX_OBJECTS = 1000000

Release source · Runtime guarantees · Capability guides

AGENT_BUNDLE_MAX_TOTAL_BYTES

from cayu.snapshots import AGENT_BUNDLE_MAX_TOTAL_BYTES

AGENT_BUNDLE_MAX_TOTAL_BYTES = 4 * 1024 * 1024 * 1024 * 1024

Release source · Runtime guarantees · Capability guides

AGENT_BUNDLE_OBJECT_DIRECTORY

from cayu.snapshots import AGENT_BUNDLE_OBJECT_DIRECTORY

AGENT_BUNDLE_OBJECT_DIRECTORY = 'objects'

Release source · Runtime guarantees · Capability guides

AGENT_BUNDLE_RECORD_TYPE

from cayu.snapshots import AGENT_BUNDLE_RECORD_TYPE

AGENT_BUNDLE_RECORD_TYPE = 'cayu.agent-bundle'

Release source · Runtime guarantees · Capability guides

AGENT_BUNDLE_SCHEMA_VERSION

from cayu.snapshots import AGENT_BUNDLE_SCHEMA_VERSION

AGENT_BUNDLE_SCHEMA_VERSION = 1

Release source · Runtime guarantees · Capability guides

agent_snapshot_component_package

from cayu.snapshots import agent_snapshot_component_package

Build a strict portable component and its deduplicated blob objects.

agent_snapshot_component_package(*, kind: AgentSnapshotComponentKind, provider_id: str, component_schema: str, profile: AgentSnapshotProfile, payload: dict[str, object], files: Mapping[str, bytes] | None=None, file_content_types: Mapping[str, str] | None=None, executable_paths: Iterable[str]=(), external_bindings: Iterable[AgentExternalBindingRequirement]=(), session_disposition: AgentSnapshotSessionDisposition | None=None) -> tuple[AgentSnapshotComponentPackage, dict[str, bytes]]

Release source · Runtime guarantees · Capability guides

AgentBundle

from cayu.snapshots import AgentBundle

Bases: _BundleModel.

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
record_type	Literal['cayu.agent-bundle']	AGENT_BUNDLE_RECORD_TYPE
schema_version	Literal[1]	AGENT_BUNDLE_SCHEMA_VERSION
bundle_id	StrictStr	required
snapshot_ref	AgentSnapshotRef	required
export_binding_id	StrictStr	required
export_authority_scope_fingerprint	StrictStr	required
destination_inventory_fingerprint	StrictStr	required
profile	AgentSnapshotProfile	required
mode	AgentBundleMode	required
snapshot_document	AgentBundleObjectRef	required
closure	tuple[AgentBundleObjectRef, ...]	required
transferred_digests	tuple[StrictStr, ...]	required
external_bindings	tuple[AgentExternalBindingRequirement, ...]	required
size_report	AgentBundleSizeReport	required

validate_bundle_id (method)

AgentBundle.validate_bundle_id(value: str, info) -> str

validate_closure_array (method)

AgentBundle.validate_closure_array(value: object) -> object

validate_transferred (method)

AgentBundle.validate_transferred(value: object) -> tuple[str, ...]

validate_bindings_array (method)

AgentBundle.validate_bindings_array(value: object) -> object

validate_bundle (method)

AgentBundle.validate_bundle() -> AgentBundle

identity_material (method)

AgentBundle.identity_material() -> dict[str, object]

create (method)

AgentBundle.create(*, snapshot_ref: AgentSnapshotRef, export_binding_id: str, export_authority_scope_fingerprint: str, destination_inventory_fingerprint: str, profile: AgentSnapshotProfile, mode: AgentBundleMode, snapshot_document: AgentBundleObjectRef, closure: Iterable[AgentBundleObjectRef], transferred_digests: Iterable[str], external_bindings: Iterable[AgentExternalBindingRequirement], size_report: AgentBundleSizeReport) -> AgentBundle

Release source · Runtime guarantees · Capability guides

AgentBundleCoordinator

from cayu.snapshots import AgentBundleCoordinator

Export and import complete authorized AgentSnapshot closures.

init (method)

AgentBundleCoordinator.__init__(*, snapshot_store: AgentSnapshotStore, object_store: AgentSnapshotObjectStore, secret_redactor: SecretRedactor | None=None, materialization_authority: AgentBundleMaterializationAuthority | None=None, terminal_authority: AgentSnapshotTerminalAuthority | None=None) -> None

export (method)

async AgentBundleCoordinator.export(*, operation_id: str, access: AgentSnapshotAccess, profile: AgentSnapshotProfile, destination: str | Path, mode: AgentBundleMode=AgentBundleMode.FULL, destination_inventory: AgentBundleInventory | None=None) -> AgentBundleExportReceipt

export_container (method)

async AgentBundleCoordinator.export_container(*, operation_id: str, access: AgentSnapshotAccess, profile: AgentSnapshotProfile, destination: str | Path | BinaryIO, mode: AgentBundleMode=AgentBundleMode.FULL, destination_inventory: AgentBundleInventory | None=None) -> AgentBundleContainerReceipt

Export one authorized snapshot closure as a single .cayu file.

The ordinary directory remains the canonical unpacked representation. Root protection spans directory construction, container publication, and acknowledgement; a cancellation or failed publication retains the protection for an exact retry.

import_bundle (method)

async AgentBundleCoordinator.import_bundle(*, operation_id: str, source: str | Path, subject: AgentSnapshotSubject, authority_scope_fingerprint: str, owner: str, retention_class: AgentSnapshotRetentionClass=AgentSnapshotRetentionClass.RELEASE) -> AgentBundleImportReceipt

import_container (method)

async AgentBundleCoordinator.import_container(*, operation_id: str, source: str | Path | BinaryIO, subject: AgentSnapshotSubject, authority_scope_fingerprint: str, owner: str, retention_class: AgentSnapshotRetentionClass=AgentSnapshotRetentionClass.RELEASE) -> AgentBundleImportReceipt

Validate a .cayu container, then atomically import and pin its bundle.

materialize (method)

async AgentBundleCoordinator.materialize(request: AgentBundleMaterializationRequest, *, materialization_root: str | Path) -> AgentBundleMaterializationReceipt

capture_terminal (method)

async AgentBundleCoordinator.capture_terminal(request: AgentSnapshotTerminalCaptureRequest, *, providers: Iterable[AgentSnapshotComponentProvider]) -> AgentSnapshotTerminalCaptureReceipt

Release source · Runtime guarantees · Capability guides

AgentBundleError

from cayu.snapshots import AgentBundleError

Bases: RuntimeError.

init (method)

AgentBundleError.__init__(code: str, detail: str | None=None) -> None

Release source · Runtime guarantees · Capability guides

AgentBundleExportReceipt

from cayu.snapshots import AgentBundleExportReceipt

Bases: _BundleModel.

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
record_type	Literal['cayu.agent-bundle-export-receipt']	'cayu.agent-bundle-export-receipt'
schema_version	Literal[1]	1
receipt_id	StrictStr	required
operation_id	StrictStr	Field(max_length=256)
bundle	AgentBundle	required
destination_fingerprint	StrictStr	required

validate_digests (method)

AgentBundleExportReceipt.validate_digests(value: str, info) -> str

validate_operation_id (method)

AgentBundleExportReceipt.validate_operation_id(value: str, info) -> str

validate_receipt (method)

AgentBundleExportReceipt.validate_receipt() -> AgentBundleExportReceipt

identity_material (method)

AgentBundleExportReceipt.identity_material() -> dict[str, object]

create (method)

AgentBundleExportReceipt.create(*, operation_id: str, bundle: AgentBundle, destination_fingerprint: str) -> AgentBundleExportReceipt

Release source · Runtime guarantees · Capability guides

AgentBundleImportReceipt

from cayu.snapshots import AgentBundleImportReceipt

Bases: _BundleModel.

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
record_type	Literal['cayu.agent-bundle-import-receipt']	'cayu.agent-bundle-import-receipt'
schema_version	Literal[1]	1
receipt_id	StrictStr	required
operation_id	StrictStr	Field(max_length=256)
bundle_id	StrictStr	required
snapshot_ref	AgentSnapshotRef	required
binding_id	StrictStr	required
pin	AgentSnapshotPinReceipt	required
imported_digests	tuple[StrictStr, ...]	required
reused_digests	tuple[StrictStr, ...]	required

validate_digests (method)

AgentBundleImportReceipt.validate_digests(value: str, info) -> str

validate_operation_id (method)

AgentBundleImportReceipt.validate_operation_id(value: str, info) -> str

validate_digest_arrays (method)

AgentBundleImportReceipt.validate_digest_arrays(value: object, info) -> tuple[str, ...]

validate_receipt (method)

AgentBundleImportReceipt.validate_receipt() -> AgentBundleImportReceipt

identity_material (method)

AgentBundleImportReceipt.identity_material() -> dict[str, object]

create (method)

AgentBundleImportReceipt.create(*, operation_id: str, bundle: AgentBundle, binding_id: str, pin: AgentSnapshotPinReceipt, imported_digests: Iterable[str], reused_digests: Iterable[str]) -> AgentBundleImportReceipt

Release source · Runtime guarantees · Capability guides

AgentBundleInventory

from cayu.snapshots import AgentBundleInventory

Bases: _BundleModel.

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
object_digests	tuple[StrictStr, ...]	()

validate_digests (method)

AgentBundleInventory.validate_digests(value: object) -> tuple[str, ...]

fingerprint (property)

AgentBundleInventory.fingerprint() -> str

Release source · Runtime guarantees · Capability guides

AgentBundleMaterializationAuthority

from cayu.snapshots import AgentBundleMaterializationAuthority

Application authority that allocates and activates fresh runtime bindings.

Bases: ABC.

authorize_materialization (method)

async AgentBundleMaterializationAuthority.authorize_materialization(request: AgentBundleMaterializationRequest) -> AgentBundleMaterializationAuthorization

Return a source-owned receipt for this exact request.

Release source · Runtime guarantees · Capability guides

AgentBundleMaterializationAuthorization

from cayu.snapshots import AgentBundleMaterializationAuthorization

Application-owned allocation and external-binding authorization receipt.

Bases: _BundleModel.

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
record_type	Literal['cayu.agent-bundle-materialization-authorization']	'cayu.agent-bundle-materialization-authorization'
schema_version	Literal[1]	1
authorization_id	StrictStr	required
request_fingerprint	StrictStr	required
authority_fingerprint	StrictStr	required
fresh_identities	AgentMaterializationFreshIdentities	required
external_bindings	tuple[AgentExternalBindingResolution, ...]	()

validate_digests (method)

AgentBundleMaterializationAuthorization.validate_digests(value: str, info) -> str

validate_bindings_array (method)

AgentBundleMaterializationAuthorization.validate_bindings_array(value: object) -> object

validate_authorization (method)

AgentBundleMaterializationAuthorization.validate_authorization() -> AgentBundleMaterializationAuthorization

identity_material (method)

AgentBundleMaterializationAuthorization.identity_material() -> dict[str, object]

state_partition_fingerprint (property)

AgentBundleMaterializationAuthorization.state_partition_fingerprint() -> str

create (method)

AgentBundleMaterializationAuthorization.create(*, request: AgentBundleMaterializationRequest, authority_fingerprint: str, fresh_identities: AgentMaterializationFreshIdentities, external_bindings: Iterable[AgentExternalBindingResolution]=()) -> AgentBundleMaterializationAuthorization

Release source · Runtime guarantees · Capability guides

AgentBundleMaterializationReceipt

from cayu.snapshots import AgentBundleMaterializationReceipt

Bases: _BundleModel.

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
record_type	Literal['cayu.agent-bundle-materialization-receipt']	'cayu.agent-bundle-materialization-receipt'
schema_version	Literal[1]	1
receipt_id	StrictStr	required
operation_id	StrictStr	Field(max_length=256)
bundle_id	StrictStr	required
materialization_request_fingerprint	StrictStr	required
snapshot_ref	AgentSnapshotRef	required
profile	AgentSnapshotProfile	required
mode	AgentSnapshotMaterializationMode	required
materialization	AgentSnapshotMaterialization	required
materialization_fingerprint	StrictStr	required
state_scope_id	StrictStr	required
authorization	AgentBundleMaterializationAuthorization	required
fresh_identities	AgentMaterializationFreshIdentities	required
external_bindings	tuple[AgentExternalBindingResolution, ...]	required

validate_digests (method)

AgentBundleMaterializationReceipt.validate_digests(value: str, info) -> str

validate_operation_id (method)

AgentBundleMaterializationReceipt.validate_operation_id(value: str, info) -> str

validate_bindings_array (method)

AgentBundleMaterializationReceipt.validate_bindings_array(value: object) -> object

validate_receipt (method)

AgentBundleMaterializationReceipt.validate_receipt() -> AgentBundleMaterializationReceipt

identity_material (method)

AgentBundleMaterializationReceipt.identity_material() -> dict[str, object]

create (method)

AgentBundleMaterializationReceipt.create(*, request: AgentBundleMaterializationRequest, authorization: AgentBundleMaterializationAuthorization, materialization: AgentSnapshotMaterialization) -> AgentBundleMaterializationReceipt

Release source · Runtime guarantees · Capability guides

AgentBundleMaterializationRequest

from cayu.snapshots import AgentBundleMaterializationRequest

Bases: _BundleModel.

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(max_length=256)
bundle	AgentBundle	required
access	AgentSnapshotAccess	required
mode	AgentSnapshotMaterializationMode	required
candidate_id	StrictStr	Field(max_length=256)
trial_id	StrictStr	Field(max_length=256)
state_mode	AgentSnapshotTrialStateMode	required

validate_text (method)

AgentBundleMaterializationRequest.validate_text(value: str, info) -> str

validate_request (method)

AgentBundleMaterializationRequest.validate_request() -> AgentBundleMaterializationRequest

request_fingerprint (property)

AgentBundleMaterializationRequest.request_fingerprint() -> str

Release source · Runtime guarantees · Capability guides

AgentBundleMode

from cayu.snapshots import AgentBundleMode

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
FULL	class attribute	'full'
THIN	class attribute	'thin'

Release source · Runtime guarantees · Capability guides

AgentBundleObjectKind

from cayu.snapshots import AgentBundleObjectKind

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
SNAPSHOT_DOCUMENT	class attribute	'snapshot_document'
SNAPSHOT_NODE	class attribute	'snapshot_node'
COMPONENT_MANIFEST	class attribute	'component_manifest'
COMPONENT_BLOB	class attribute	'component_blob'
OPERATION_RECEIPT	class attribute	'operation_receipt'

Release source · Runtime guarantees · Capability guides

AgentBundleObjectRef

from cayu.snapshots import AgentBundleObjectRef

Bases: _BundleModel.

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
digest	StrictStr	required
kind	AgentBundleObjectKind	required
schema_id	StrictStr	Field(max_length=256)
byte_count	StrictInt	Field(ge=0, le=AGENT_BUNDLE_MAX_OBJECT_BYTES)

validate_digest (method)

AgentBundleObjectRef.validate_digest(value: str, info) -> str

validate_schema (method)

AgentBundleObjectRef.validate_schema(value: str, info) -> str

identity_material (method)

AgentBundleObjectRef.identity_material() -> dict[str, object]

validate_kind_size (method)

AgentBundleObjectRef.validate_kind_size() -> AgentBundleObjectRef

Release source · Runtime guarantees · Capability guides

AgentBundleSizeReport

from cayu.snapshots import AgentBundleSizeReport

Bases: _BundleModel.

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_manifest_bytes	StrictInt	Field(ge=1)
logical_closure_bytes	StrictInt	Field(ge=1)
unique_stored_bytes	StrictInt	Field(ge=0)
shared_stored_bytes	StrictInt	Field(ge=0)
incremental_transfer_bytes	StrictInt	Field(ge=0)
materialized_disk_bytes	StrictInt	Field(ge=0)
unresolved_external_bindings	tuple[StrictStr, ...]	()

validate_unresolved (method)

AgentBundleSizeReport.validate_unresolved(value: object) -> tuple[str, ...]

Release source · Runtime guarantees · Capability guides

AgentExternalBindingKind

from cayu.snapshots import AgentExternalBindingKind

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
CREDENTIAL	class attribute	'credential'
EVALUATOR	class attribute	'evaluator'
BUDGET	class attribute	'budget'
LEASE	class attribute	'lease'
EXTERNAL_SERVICE	class attribute	'external_service'
HOSTED_PROVIDER	class attribute	'hosted_provider'

Release source · Runtime guarantees · Capability guides

AgentExternalBindingRequirement

from cayu.snapshots import AgentExternalBindingRequirement

Bases: _BundleModel.

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	AgentExternalBindingKind	required
name	StrictStr	Field(max_length=256)
requirement_fingerprint	StrictStr	required
required	StrictBool	True

validate_name (method)

AgentExternalBindingRequirement.validate_name(value: str, info) -> str

validate_fingerprint (method)

AgentExternalBindingRequirement.validate_fingerprint(value: str, info) -> str

identity_material (method)

AgentExternalBindingRequirement.identity_material() -> dict[str, object]

Release source · Runtime guarantees · Capability guides

AgentExternalBindingResolution

from cayu.snapshots import AgentExternalBindingResolution

Bases: _BundleModel.

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
requirement	AgentExternalBindingRequirement	required
resolution_fingerprint	StrictStr	required
authority_fingerprint	StrictStr	required

validate_digests (method)

AgentExternalBindingResolution.validate_digests(value: str, info) -> str

identity_material (method)

AgentExternalBindingResolution.identity_material() -> dict[str, object]

Release source · Runtime guarantees · Capability guides

AgentMaterializationFreshIdentities

from cayu.snapshots import AgentMaterializationFreshIdentities

Bases: _BundleModel.

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
runtime_identity	StrictStr	required
session_identity	StrictStr	required
operation_identity	StrictStr	required
budget_identity	StrictStr	required
lease_identity	StrictStr	required
scratch_identity	StrictStr	required
evaluator_identity	StrictStr | None	None
discovery_grant_ids	tuple[StrictStr, ...]	()

validate_digests (method)

AgentMaterializationFreshIdentities.validate_digests(value: str | None, info) -> str | None

validate_discovery_grants (method)

AgentMaterializationFreshIdentities.validate_discovery_grants(value: object) -> tuple[str, ...]

require_empty_discovery_grants (method)

AgentMaterializationFreshIdentities.require_empty_discovery_grants() -> AgentMaterializationFreshIdentities

identity_material (method)

AgentMaterializationFreshIdentities.identity_material() -> dict[str, object]

Release source · Runtime guarantees · Capability guides

AgentSnapshotComponentFile

from cayu.snapshots import AgentSnapshotComponentFile

Bases: _BundleModel.

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
path	StrictStr	Field(max_length=1024)
digest	StrictStr	required
byte_count	StrictInt	Field(ge=0, le=AGENT_BUNDLE_MAX_OBJECT_BYTES)
content_type	StrictStr	Field(max_length=256)
executable	StrictBool	False

validate_path (method)

AgentSnapshotComponentFile.validate_path(value: str, info) -> str

validate_digest (method)

AgentSnapshotComponentFile.validate_digest(value: str, info) -> str

validate_content_type (method)

AgentSnapshotComponentFile.validate_content_type(value: str, info) -> str

Release source · Runtime guarantees · Capability guides

AgentSnapshotComponentPackage

from cayu.snapshots import AgentSnapshotComponentPackage

Provider-owned portable content named by a snapshot component ref.

Bases: _BundleModel.

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
record_type	Literal['cayu.agent-snapshot-component']	'cayu.agent-snapshot-component'
schema_version	Literal[1]	1
kind	AgentSnapshotComponentKind	required
provider_id	StrictStr	Field(max_length=256)
component_schema	StrictStr	Field(max_length=256)
profile	AgentSnapshotProfile	required
session_disposition	AgentSnapshotSessionDisposition | None	None
payload	dict[str, object]	required
files	tuple[AgentSnapshotComponentFile, ...]	()
external_bindings	tuple[AgentExternalBindingRequirement, ...]	()

validate_identifiers (method)

AgentSnapshotComponentPackage.validate_identifiers(value: str, info) -> str

validate_payload (method)

AgentSnapshotComponentPackage.validate_payload(value: object) -> dict[str, object]

validate_arrays (method)

AgentSnapshotComponentPackage.validate_arrays(value: object, info) -> object

validate_package (method)

AgentSnapshotComponentPackage.validate_package() -> AgentSnapshotComponentPackage

identity_material (method)

AgentSnapshotComponentPackage.identity_material() -> dict[str, object]

digest (property)

AgentSnapshotComponentPackage.digest() -> str

document (property)

AgentSnapshotComponentPackage.document() -> bytes

Release source · Runtime guarantees · Capability guides

AgentSnapshotMaterializationMode

from cayu.snapshots import AgentSnapshotMaterializationMode

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
MATERIALIZE	class attribute	'materialize'
FORK_AS_SEED	class attribute	'fork_as_seed'
RESTORE	class attribute	'restore'

Release source · Runtime guarantees · Capability guides

AgentSnapshotObjectStore

from cayu.snapshots import AgentSnapshotObjectStore

Content-addressed provider-object storage composed with AgentSnapshotStore.

Bases: ABC.

put (method)

async AgentSnapshotObjectStore.put(reference: AgentBundleObjectRef, content: bytes) -> None

get (method)

async AgentSnapshotObjectStore.get(reference: AgentBundleObjectRef) -> bytes | None

has_digest (method)

async AgentSnapshotObjectStore.has_digest(digest: str) -> bool

get_digest (method)

async AgentSnapshotObjectStore.get_digest(digest: str, *, max_bytes: int) -> bytes | None

Load one bounded content-addressed object when metadata is discovered later.

verify (method)

async AgentSnapshotObjectStore.verify(reference: AgentBundleObjectRef) -> bool

put_file (method)

async AgentSnapshotObjectStore.put_file(reference: AgentBundleObjectRef, source: str | Path) -> None

Stream one regular file into immutable object storage.

copy_to (method)

async AgentSnapshotObjectStore.copy_to(reference: AgentBundleObjectRef, destination: str | Path) -> None

Stream one verified immutable object to a new regular file.

contains_secret (method)

async AgentSnapshotObjectStore.contains_secret(reference: AgentBundleObjectRef, redactor: SecretRedactor) -> bool

inventory (method)

async AgentSnapshotObjectStore.inventory() -> AgentBundleInventory

Release source · Runtime guarantees · Capability guides

AgentSnapshotProfile

from cayu.snapshots import AgentSnapshotProfile

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
REUSABLE_AGENT	class attribute	'reusable_agent'
CONTINUING_AGENT	class attribute	'continuing_agent'
EVALUATION_CANDIDATE	class attribute	'evaluation_candidate'

Release source · Runtime guarantees · Capability guides

AgentSnapshotSessionDisposition

from cayu.snapshots import AgentSnapshotSessionDisposition

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
FRESH_ON_MATERIALIZE	class attribute	'fresh_on_materialize'
SAFE_FRONTIER	class attribute	'safe_frontier'
NON_RESTORABLE	class attribute	'non_restorable'

Release source · Runtime guarantees · Capability guides

AgentSnapshotTerminalAuthority

from cayu.snapshots import AgentSnapshotTerminalAuthority

Application authority that verifies durable runtime/session terminal evidence.

Bases: ABC.

authorize_terminal_capture (method)

async AgentSnapshotTerminalAuthority.authorize_terminal_capture(*, request: AgentSnapshotTerminalCaptureRequest, materialization: AgentSnapshotMaterialization, trial: AgentSnapshotTrialBinding, result: AgentSnapshotResultBinding) -> AgentSnapshotTerminalAuthorization

Verify source-owned runtime evidence and authorize descendant capture.

Release source · Runtime guarantees · Capability guides

AgentSnapshotTerminalAuthorization

from cayu.snapshots import AgentSnapshotTerminalAuthorization

Application-owned verification of one durable runtime result and frontier.

Bases: _BundleModel.

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
record_type	Literal['cayu.agent-snapshot-terminal-authorization']	'cayu.agent-snapshot-terminal-authorization'
schema_version	Literal[1]	1
authorization_id	StrictStr	required
request_fingerprint	StrictStr	required
result_fingerprint	StrictStr	required
runtime_evidence_fingerprint	StrictStr	required
authority_fingerprint	StrictStr	required

validate_digests (method)

AgentSnapshotTerminalAuthorization.validate_digests(value: str, info) -> str

validate_authorization (method)

AgentSnapshotTerminalAuthorization.validate_authorization() -> AgentSnapshotTerminalAuthorization

identity_material (method)

AgentSnapshotTerminalAuthorization.identity_material() -> dict[str, object]

create (method)

AgentSnapshotTerminalAuthorization.create(*, request: AgentSnapshotTerminalCaptureRequest, result: AgentSnapshotResultBinding, authority_fingerprint: str) -> AgentSnapshotTerminalAuthorization

Release source · Runtime guarantees · Capability guides

AgentSnapshotTerminalCaptureReceipt

from cayu.snapshots import AgentSnapshotTerminalCaptureReceipt

Bases: _BundleModel.

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
record_type	Literal['cayu.agent-snapshot-terminal-capture-receipt']	'cayu.agent-snapshot-terminal-capture-receipt'
schema_version	Literal[1]	1
receipt_id	StrictStr	required
operation_id	StrictStr	Field(max_length=256)
terminal_request_fingerprint	StrictStr	required
parent_materialization_fingerprint	StrictStr	required
parent_result_fingerprint	StrictStr	required
parent_snapshot_ref	AgentSnapshotRef	required
descendant_snapshot_ref	AgentSnapshotRef	required
profile	AgentSnapshotProfile	required
terminal_disposition	AgentSnapshotTerminalDisposition	required
finalization_policy	StrictStr	Field(max_length=256)
safe_frontier_fingerprint	StrictStr | None	None
terminal_authorization	AgentSnapshotTerminalAuthorization	required

validate_digests (method)

AgentSnapshotTerminalCaptureReceipt.validate_digests(value: str | None, info) -> str | None

validate_text (method)

AgentSnapshotTerminalCaptureReceipt.validate_text(value: str, info) -> str

validate_receipt (method)

AgentSnapshotTerminalCaptureReceipt.validate_receipt() -> AgentSnapshotTerminalCaptureReceipt

identity_material (method)

AgentSnapshotTerminalCaptureReceipt.identity_material() -> dict[str, object]

create (method)

AgentSnapshotTerminalCaptureReceipt.create(*, request: AgentSnapshotTerminalCaptureRequest, result: AgentSnapshotResultBinding, authorization: AgentSnapshotTerminalAuthorization, descendant_snapshot_ref: AgentSnapshotRef) -> AgentSnapshotTerminalCaptureReceipt

Release source · Runtime guarantees · Capability guides

AgentSnapshotTerminalCaptureRequest

from cayu.snapshots import AgentSnapshotTerminalCaptureRequest

Bases: _BundleModel.

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(max_length=256)
capture	AgentSnapshotCaptureRequest	required
parent_materialization_fingerprint	StrictStr	required
parent_result_fingerprint	StrictStr	required
profile	AgentSnapshotProfile	required
finalization_policy	StrictStr	Field(max_length=256)

validate_text (method)

AgentSnapshotTerminalCaptureRequest.validate_text(value: str, info) -> str

validate_digests (method)

AgentSnapshotTerminalCaptureRequest.validate_digests(value: str, info) -> str

validate_safe_terminal (method)

AgentSnapshotTerminalCaptureRequest.validate_safe_terminal() -> AgentSnapshotTerminalCaptureRequest

request_fingerprint (property)

AgentSnapshotTerminalCaptureRequest.request_fingerprint() -> str

Release source · Runtime guarantees · Capability guides

FileSystemAgentSnapshotObjectStore

from cayu.snapshots import FileSystemAgentSnapshotObjectStore

Ordinary-filesystem CAS with atomic immutable-object publication.

Bases: AgentSnapshotObjectStore.

put (method)

async FileSystemAgentSnapshotObjectStore.put(reference: AgentBundleObjectRef, content: bytes) -> None

get (method)

async FileSystemAgentSnapshotObjectStore.get(reference: AgentBundleObjectRef) -> bytes | None

has_digest (method)

async FileSystemAgentSnapshotObjectStore.has_digest(digest: str) -> bool

get_digest (method)

async FileSystemAgentSnapshotObjectStore.get_digest(digest: str, *, max_bytes: int) -> bytes | None

verify (method)

async FileSystemAgentSnapshotObjectStore.verify(reference: AgentBundleObjectRef) -> bool

put_file (method)

async FileSystemAgentSnapshotObjectStore.put_file(reference: AgentBundleObjectRef, source: str | Path) -> None

copy_to (method)

async FileSystemAgentSnapshotObjectStore.copy_to(reference: AgentBundleObjectRef, destination: str | Path) -> None

contains_secret (method)

async FileSystemAgentSnapshotObjectStore.contains_secret(reference: AgentBundleObjectRef, redactor: SecretRedactor) -> bool

inventory (method)

async FileSystemAgentSnapshotObjectStore.inventory() -> AgentBundleInventory

init (method)

FileSystemAgentSnapshotObjectStore.__init__(root: str | Path) -> None

Release source · Runtime guarantees · Capability guides

load_portable_agent_snapshot_component_providers

from cayu.snapshots import load_portable_agent_snapshot_component_providers

Reconstruct portable providers from an imported snapshot and object CAS.

async load_portable_agent_snapshot_component_providers(snapshot: AgentSnapshot, *, object_store: AgentSnapshotObjectStore, materialization_root: str | Path, secret_redactor: SecretRedactor | None=None) -> tuple[PortableAgentSnapshotComponentProvider, ...]

Release source · Runtime guarantees · Capability guides

PortableAgentSnapshotComponentProvider

from cayu.snapshots import PortableAgentSnapshotComponentProvider

Production adapter for immutable provider-owned component packages.

Owning subsystems construct the package from an exact safe frontier. This adapter supplies durable content storage, verification and idempotent filesystem materialization; it does not infer which application data is authorized to inherit.

Bases: AgentSnapshotComponentProvider.

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	AgentSnapshotComponentKind	required
provider_id	str	required

capture (method)

async PortableAgentSnapshotComponentProvider.capture(request: AgentSnapshotCaptureRequest, selector: AgentSnapshotComponentSelector) -> AgentSnapshotComponentCapture

verify (method)

async PortableAgentSnapshotComponentProvider.verify(snapshot: AgentSnapshot, component: AgentSnapshotComponentRef) -> bool

materialize (method)

async PortableAgentSnapshotComponentProvider.materialize(snapshot: AgentSnapshot, component: AgentSnapshotComponentRef, request: AgentSnapshotMaterializationRequest, operation: AgentSnapshotMaterializationOperation) -> AgentSnapshotMaterializedComponent

recover_materialization_operation (method)

async PortableAgentSnapshotComponentProvider.recover_materialization_operation(snapshot: AgentSnapshot, component: AgentSnapshotComponentRef, request: AgentSnapshotMaterializationRequest, operation: AgentSnapshotMaterializationOperation) -> AgentSnapshotMaterializedComponent

recover (method)

async PortableAgentSnapshotComponentProvider.recover(snapshot: AgentSnapshot, component: AgentSnapshotComponentRef, materialized: AgentSnapshotMaterializedComponent, materialization: AgentSnapshotMaterialization) -> AgentSnapshotMaterializedComponent

init (method)

PortableAgentSnapshotComponentProvider.__init__(package: AgentSnapshotComponentPackage, blobs: Mapping[str, bytes], *, object_store: AgentSnapshotObjectStore, materialization_root: str | Path, execution_profile: AgentSnapshotExecutionProfileRef | None=None, consistency: AgentSnapshotConsistency=AgentSnapshotConsistency.FRONTIER_CONSISTENT, redaction: AgentSnapshotRedaction=AgentSnapshotRedaction.BOUNDED_PROJECTION, materialization: AgentSnapshotMaterializationCapability=AgentSnapshotMaterializationCapability.RESTORABLE, revision: str | None=None, frontier: str | None=None, secret_redactor: SecretRedactor | None=None) -> None

Release source · Runtime guarantees · Capability guides

store_agent_snapshot_component_package

from cayu.snapshots import store_agent_snapshot_component_package

Stream regular files into CAS and return their portable component manifest.

async store_agent_snapshot_component_package(*, kind: AgentSnapshotComponentKind, provider_id: str, component_schema: str, profile: AgentSnapshotProfile, payload: dict[str, object], file_paths: Mapping[str, str | Path], object_store: AgentSnapshotObjectStore, file_content_types: Mapping[str, str] | None=None, executable_paths: Iterable[str]=(), external_bindings: Iterable[AgentExternalBindingRequirement]=(), session_disposition: AgentSnapshotSessionDisposition | None=None, secret_redactor: SecretRedactor | None=None) -> AgentSnapshotComponentPackage

Release source · Runtime guarantees · Capability guides