cayu.artifacts.aws_s3

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.

S3ArtifactStore

from cayu.artifacts import S3ArtifactStore

Direct S3 object implementation of ArtifactStore.

Content is written first and metadata.json last. The metadata object is the commit marker, so interrupted writes are never listed as artifacts. Each publication writes its content under a key unique to that publication (<artifact_id>/<generation>/content) and names the generation in its metadata. Artifacts published before generations keep reading from <artifact_id>/content.

list scans every committed metadata object under prefix and fetches each metadata document before filtering, sorting, and applying limit. This keeps totals exact but targets modest artifact volumes. High-volume deployments should maintain a separate query index.

Durable pins live in one conditional-write state object per artifact under _pins/. Pin, release, and deletion change it only by compare-and-swap, so pins serialize with deletion across processes without a lock service. Deletion removes exact generations and removes the metadata only on a matching ETag, so a deletion S3 applies late cannot remove a later publication of the same identity.

Decorators: @model_store_surface('artifacts').

Bases: ArtifactStore.

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
artifact_access_version	class attribute	1

put_bytes (method)

async S3ArtifactStore.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

read_bytes (method)

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

read_range (method)

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

list (method)

async S3ArtifactStore.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

supports_session_closure_claims (property)

S3ArtifactStore.supports_session_closure_claims() -> bool

load_session_closure_claim (method)

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

claim_session_closure (method)

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

delete_session_closure_artifact (method)

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

supports_pins (property)

S3ArtifactStore.supports_pins() -> bool

pin (method)

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

release_pin (method)

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

delete (method)

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

init (method)

S3ArtifactStore.__init__(bucket: str, *, prefix: str='cayu/artifacts', store_id: str | None=None, region_name: str | None=None, profile_name: str | None=None, endpoint_url: str | None=None, kms_key_id: str | None=None, client: Any | None=None) -> None

Release source · Runtime guarantees · Capability guides