cayu.artifacts.base

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.

ArtifactIdentityConflictError

from cayu.artifacts import ArtifactIdentityConflictError

An idempotent write named an artifact id that holds other bytes or metadata.

Also raised when the id holds a corrupt or incomplete artifact that a deterministic retry cannot prove is its own.

Bases: ValueError.

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

Release source · Runtime guarantees · Capability guides

ArtifactListResult

from cayu.artifacts import ArtifactListResult

Decorators: @dataclass(frozen=True).

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
artifacts	tuple[ArtifactMetadata, ...]	required
total_count	int | None	required
truncated	bool	False

Release source · Runtime guarantees · Capability guides

ArtifactMetadata

from cayu.artifacts import ArtifactMetadata

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
id	str	required
filename	str	required
content_type	str	'application/octet-stream'
size_bytes	int	required
scope	ArtifactScope	ArtifactScope.SESSION
session_id	str | None	None
agent_name	str | None	None
environment_name	str | None	None
created_at	datetime	Field(default_factory=lambda: datetime.now(UTC))
labels	Mapping[str, str]	Field(default_factory=dict, exclude_if=lambda value: not value)
metadata	Mapping[str, Any]	Field(default_factory=dict)

copy_access_labels (method)

ArtifactMetadata.copy_access_labels(value)

freeze_access_labels (method)

ArtifactMetadata.freeze_access_labels(value)

serialize_access_labels (method)

ArtifactMetadata.serialize_access_labels(value)

copy_metadata (method)

ArtifactMetadata.copy_metadata(value: Mapping[str, Any]) -> dict[str, Any]

freeze_metadata (method)

ArtifactMetadata.freeze_metadata(value: Mapping[str, Any]) -> Mapping[str, Any]

serialize_metadata (method)

ArtifactMetadata.serialize_metadata(value: Mapping[str, Any]) -> dict[str, Any]

validate_clean_nonblank (method)

ArtifactMetadata.validate_clean_nonblank(value: str, info) -> str

validate_content_type (method)

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

validate_filename (method)

ArtifactMetadata.validate_filename(value: str, info) -> str

validate_optional_clean_nonblank (method)

ArtifactMetadata.validate_optional_clean_nonblank(value: str | None, info) -> str | None

validate_size_bytes (method)

ArtifactMetadata.validate_size_bytes(value: int, info) -> int

validate_scope_owner (method)

ArtifactMetadata.validate_scope_owner() -> ArtifactMetadata

model_copy (method)

ArtifactMetadata.model_copy(*, update: Mapping[str, Any] | None=None, deep: bool=False) -> Self

Return an independently validated immutable metadata record.

Release source · Runtime guarantees · Capability guides

ArtifactReadResult

from cayu.artifacts import ArtifactReadResult

Decorators: @dataclass(frozen=True).

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
metadata	ArtifactMetadata	required
content	bytes	required
total_bytes	int	required
truncated	bool	False
source_bytes_read	int | None	None
redaction_truncated	bool	False
offset	int	0

Release source · Runtime guarantees · Capability guides

ArtifactScope

from cayu.artifacts import ArtifactScope

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
SESSION	class attribute	'session'
ENVIRONMENT	class attribute	'environment'

Release source · Runtime guarantees · Capability guides

ArtifactStore

from cayu.artifacts import ArtifactStore

Durable uploaded/generated file storage for an environment.

Bases: ABC.

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
id	str	required

put_bytes (method)

async ArtifactStore.put_bytes(content: bytes, *, artifact_id: str | None=None, filename: str, content_type: str | None=None, scope: ArtifactScope=ArtifactScope.SESSION, session_id: str | None=None, agent_name: str | None=None, environment_name: str | None=None, metadata: dict[str, Any] | None=None) -> ArtifactMetadata

Store bytes and return a durable artifact reference.

artifact_id opts into idempotent addressing. Implementations must return an existing artifact only when its content and immutable metadata match the requested value exactly; a conflicting identity must fail. This decision must be atomic across concurrent callers: for conflicting writes to one identity, at most one value may commit and every loser must observe a conflict rather than replace or acknowledge the winner.

Cancellation or a caller-owned timeout after dispatch does not prove that the mutation stopped. Implementations must settle the invocation as one of: committed when the exact bytes and immutable metadata are durable, readable by id, and list-visible; absent only after positive proof that no state owned by the invocation remains; or reconciliation_required with bounded, content-free identity evidence. Caller cancellation remains authoritative after that classification. Reconciliation-required evidence is diagnostic only: it is never ArtifactMetadata and cannot authorize reads or publication.

Built-in stores attach evidence to the authoritative exception and emit late completion through ArtifactWriteSettlementObserver. Third-party stores must provide equivalent semantics. They register an operation before dispatch with register_artifact_write_operation so Cayu can identify active work at a runtime deadline, and atomically record its terminal classification and release observer ownership through that registration. record_artifact_write_settlement is only for already-terminal evidence without an active registration.

read_bytes (method)

async ArtifactStore.read_bytes(artifact_id: str, *, max_bytes: int | None=None) -> ArtifactReadResult

Read an artifact by id.

max_bytes is a hard materialization boundary. When it is not None, implementations must not read into application memory or return more than max_bytes content bytes. They must report the artifact’s full size in total_bytes when known and set truncated=True whenever additional bytes exist.

This guarantee is load-bearing for server and tool callers that use ArtifactStore implementations supplied by applications. A store that ignores max_bytes violates the public contract.

Implementations should raise InvalidArtifactIdError when the id is syntactically invalid for the store, and FileNotFoundError when a valid id does not exist. They should raise ArtifactStoreUnavailableError for operational backend failures. Other validation failures indicate invalid store data rather than a malformed caller request.

read_range (method)

async ArtifactStore.read_range(artifact_id: str, *, offset: int, max_bytes: int) -> ArtifactReadResult

Read a bounded range of an immutable artifact, without scanning its prefix.

Offsets address stored bytes. Return the exact offset, full committed size, and at most max_bytes bytes; truncated means bytes remain after this range. Offset equal to size returns an empty final range; beyond size is invalid. Content read amplification must not grow with offset. Metadata I/O is extra. Adapters without range support raise NotImplementedError; callers must not emulate this operation by fetching ever larger prefixes. Identity and content must remain immutable across calls (deletion may yield not found).

list (method)

async ArtifactStore.list(*, scope: ArtifactScope | None=None, session_id: str | None=None, agent_name: str | None=None, environment_name: str | None=None, limit: int | None=None) -> ArtifactListResult

List artifact metadata.

Implementations should raise ArtifactStoreUnavailableError for operational backend failures.

supports_session_closure_claims (property)

ArtifactStore.supports_session_closure_claims() -> bool

Whether closure fences publication and retains an exact durable set.

load_session_closure_claim (method)

async ArtifactStore.load_session_closure_claim(session_id: str) -> ArtifactClosureClaim | None

Load a retained claim without acquiring authority or mutating artifacts.

claim_session_closure (method)

async ArtifactStore.claim_session_closure(session_id: str, plan_id: str, *, max_records: int, max_bytes: int) -> ArtifactClosureClaim

Fence a session and durably capture its complete artifact set.

Claim acquisition must serialize with every session-scoped publication. An accepted claim proves earlier writes have settled and blocks later writes, including after process restart. Uncertain external mutations cannot be treated as quiescent. Exact replay returns the original set, including artifacts already deleted; a different plan is a conflict. The claim remains durable after the last artifact is deleted.

delete_session_closure_artifact (method)

async ArtifactStore.delete_session_closure_artifact(claim: ArtifactClosureClaim, artifact_id: str) -> None

Delete only an item authenticated by the exact retained claim.

Validate the complete claim, item membership, session ownership, and immutable metadata digest before mutation. An absent claimed item is idempotent success; a replacement under the same ID is a conflict. Cancellation does not release an in-flight deletion’s ownership.

supports_pins (property)

ArtifactStore.supports_pins() -> bool

Whether durable pins serialize with deletion across processes.

pin (method)

async ArtifactStore.pin(artifact_id: str, *, owner: str) -> None

Retain an existing artifact until this exact owner releases its pin.

Pinning an absent artifact must fail. Success must be durable and serialize with delete; repeated acquisition by an owner is idempotent.

release_pin (method)

async ArtifactStore.release_pin(artifact_id: str, *, owner: str) -> None

Release only this owner. Callers must first retire dependent state.

delete (method)

async ArtifactStore.delete(artifact_id: str) -> None

Delete an artifact if it exists.

Release source · Runtime guarantees · Capability guides

ArtifactStoreUnavailableError

from cayu.artifacts import ArtifactStoreUnavailableError

An artifact store cannot currently complete an operation.

Bases: RuntimeError.

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

Release source · Runtime guarantees · Capability guides

copy_artifact_read_result

from cayu.artifacts import copy_artifact_read_result

Copy and revalidate a store read at a consumer boundary.

copy_artifact_read_result(value: ArtifactReadResult, *, expected_artifact_id: str | None=None, max_content_bytes: int | None=None, expected_offset: int=0) -> ArtifactReadResult

Release source · Runtime guarantees · Capability guides

InvalidArtifactIdError

from cayu.artifacts import InvalidArtifactIdError

An artifact identifier is not valid for the selected store.

Bases: ValueError.

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

Release source · Runtime guarantees · Capability guides