cayu.tools.shared_artifacts

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.

`authorize_shared_artifact_materialization`

from cayu.tools import authorize_shared_artifact_materialization

Resolve one exact grant only after bounded durable ancestry validation.

async authorize_shared_artifact_materialization(*, session_store: SessionStore, caller_session_id: str, caller_session_instance_id: str, reference: dict[str, Any], policy_fingerprint: str, observed_at: str) -> dict[str, Any]

Release source · Runtime guarantees · Capability guides

`DEFAULT_SHARED_ARTIFACT_GRANT_TTL_SECONDS`

from cayu.tools import DEFAULT_SHARED_ARTIFACT_GRANT_TTL_SECONDS

DEFAULT_SHARED_ARTIFACT_GRANT_TTL_SECONDS = 24 * 60 * 60

Release source · Runtime guarantees · Capability guides

`DEFAULT_SHARED_ARTIFACT_MAX_BYTES`

from cayu.tools import DEFAULT_SHARED_ARTIFACT_MAX_BYTES

DEFAULT_SHARED_ARTIFACT_MAX_BYTES = 16 * 1024 * 1024

Release source · Runtime guarantees · Capability guides

`DEFAULT_SHARED_ARTIFACT_MAX_LINEAGE_DEPTH`

from cayu.tools import DEFAULT_SHARED_ARTIFACT_MAX_LINEAGE_DEPTH

DEFAULT_SHARED_ARTIFACT_MAX_LINEAGE_DEPTH = 64

Release source · Runtime guarantees · Capability guides

`DEFAULT_SHARED_ARTIFACT_MAX_PUBLICATIONS`

from cayu.tools import DEFAULT_SHARED_ARTIFACT_MAX_PUBLICATIONS

DEFAULT_SHARED_ARTIFACT_MAX_PUBLICATIONS = 64

Release source · Runtime guarantees · Capability guides

`MATERIALIZE_SHARED_ARTIFACT_TOOL_NAME`

from cayu.tools import MATERIALIZE_SHARED_ARTIFACT_TOOL_NAME

MATERIALIZE_SHARED_ARTIFACT_TOOL_NAME = 'materialize_shared_artifact'

Release source · Runtime guarantees · Capability guides

`MaterializeSharedArtifactTool`

from cayu.tools import MaterializeSharedArtifactTool

Materialize one authorized ancestor artifact into this isolated workspace.

Bases: Tool.

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
`spec`	`ToolSpec`	`required`

init (method)

MaterializeSharedArtifactTool.__init__(policy: SharedArtifactPolicy, *, clock: Callable[[], datetime] | None=None) -> None

name (property)

MaterializeSharedArtifactTool.name() -> str

execution_profile_identity (property)

MaterializeSharedArtifactTool.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Return the stable behavior declaration frozen with this tool’s spec.

retain_arguments_for_model (property)

MaterializeSharedArtifactTool.retain_arguments_for_model() -> bool

Retain bounded redacted original inputs privately for the same profile.

Independent of audit publication; oversized and compacted-away inputs may be omitted. This does not grant knowledge read or activation rights.

description (property)

MaterializeSharedArtifactTool.description() -> str

schema (property)

MaterializeSharedArtifactTool.schema() -> dict[str, Any]

run (method)

async MaterializeSharedArtifactTool.run(ctx: ToolContext, args: dict[str, Any]) -> ToolResult

reconcile_durable_tool_call (method)

async MaterializeSharedArtifactTool.reconcile_durable_tool_call(*, parent_session_id: str, parent_run_epoch: int, execution_profile_fingerprint: str | None, environment_name: str | None, environment_allocation_fingerprint: str | None, model_step_id: str, model_attempt_id: str, tool_round_id: str, tool_call_id: str, idempotency_key: str, arguments: dict[str, Any], started: bool, load_operation: Callable[[str], Awaitable[dict[str, Any] | None]], recovery_authority: DurableToolRecoveryAuthority | None=None) -> DurableToolRecoveryEvidence | None

Release source · Runtime guarantees · Capability guides

`MAX_SHARED_ARTIFACT_BYTES`

from cayu.tools import MAX_SHARED_ARTIFACT_BYTES

MAX_SHARED_ARTIFACT_BYTES = 64 * 1024 * 1024

Release source · Runtime guarantees · Capability guides

`MAX_SHARED_ARTIFACT_GRANT_TTL_SECONDS`

from cayu.tools import MAX_SHARED_ARTIFACT_GRANT_TTL_SECONDS

MAX_SHARED_ARTIFACT_GRANT_TTL_SECONDS = 30 * 24 * 60 * 60

Release source · Runtime guarantees · Capability guides

`MAX_SHARED_ARTIFACT_PUBLICATIONS`

from cayu.tools import MAX_SHARED_ARTIFACT_PUBLICATIONS

MAX_SHARED_ARTIFACT_PUBLICATIONS = 1024

Release source · Runtime guarantees · Capability guides

`PUBLISH_WORKSPACE_ARTIFACT_TOOL_NAME`

from cayu.tools import PUBLISH_WORKSPACE_ARTIFACT_TOOL_NAME

PUBLISH_WORKSPACE_ARTIFACT_TOOL_NAME = 'publish_workspace_artifact'

Release source · Runtime guarantees · Capability guides

`PublishWorkspaceArtifactTool`

from cayu.tools import PublishWorkspaceArtifactTool

Publish one exact workspace file for explicit descendant handoff.

Bases: Tool.

Fields and attributes

Name	Type	Default
`spec`	`ToolSpec`	`required`

init (method)

PublishWorkspaceArtifactTool.__init__(policy: SharedArtifactPolicy, *, clock: Callable[[], datetime] | None=None) -> None

name (property)

PublishWorkspaceArtifactTool.name() -> str

execution_profile_identity (property)

PublishWorkspaceArtifactTool.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Return the stable behavior declaration frozen with this tool’s spec.

retain_arguments_for_model (property)

PublishWorkspaceArtifactTool.retain_arguments_for_model() -> bool

Retain bounded redacted original inputs privately for the same profile.

Independent of audit publication; oversized and compacted-away inputs may be omitted. This does not grant knowledge read or activation rights.

description (property)

PublishWorkspaceArtifactTool.description() -> str

schema (property)

PublishWorkspaceArtifactTool.schema() -> dict[str, Any]

run (method)

async PublishWorkspaceArtifactTool.run(ctx: ToolContext, args: dict[str, Any]) -> ToolResult

reconcile_durable_tool_call (method)

async PublishWorkspaceArtifactTool.reconcile_durable_tool_call(*, parent_session_id: str, parent_run_epoch: int, execution_profile_fingerprint: str | None, environment_name: str | None, environment_allocation_fingerprint: str | None, model_step_id: str, model_attempt_id: str, tool_round_id: str, tool_call_id: str, idempotency_key: str, arguments: dict[str, Any], started: bool, load_operation: Callable[[str], Awaitable[dict[str, Any] | None]], recovery_authority: DurableToolRecoveryAuthority | None=None) -> DurableToolRecoveryEvidence | None

Release source · Runtime guarantees · Capability guides

`revoke_shared_artifact_grant`

from cayu.tools import revoke_shared_artifact_grant

Programmatically revoke one exact grant without deleting its evidence.

async revoke_shared_artifact_grant(session_store: SessionStore, reference: SharedArtifactRef | str, *, reason: str, revoked_at: datetime | None=None) -> SharedArtifactGrant

Release source · Runtime guarantees · Capability guides

`SHARED_ARTIFACT_REFERENCE_PREFIX`

from cayu.tools import SHARED_ARTIFACT_REFERENCE_PREFIX

SHARED_ARTIFACT_REFERENCE_PREFIX = 'cayu-shared-artifact-v1.'

Release source · Runtime guarantees · Capability guides

`SHARED_ARTIFACT_SCHEMA_VERSION`

from cayu.tools import SHARED_ARTIFACT_SCHEMA_VERSION

SHARED_ARTIFACT_SCHEMA_VERSION = 1

Release source · Runtime guarantees · Capability guides

`SharedArtifactAudience`

from cayu.tools import SharedArtifactAudience

Closed lineage audiences supported by the first handoff protocol.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`DESCENDANT_FORK_OR_SUBAGENT`	`class attribute`	`'descendant_fork_or_subagent'`

Release source · Runtime guarantees · Capability guides

`SharedArtifactAuthorizationError`

from cayu.tools import SharedArtifactAuthorizationError

The caller could not prove one active lineage-scoped grant.

Bases: PermissionError.

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

Release source · Runtime guarantees · Capability guides

`SharedArtifactGrant`

from cayu.tools import SharedArtifactGrant

Durable read/materialize-only authority owned by the source session.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`record_type`	`Literal['cayu.shared-artifact-grant']`	`_GRANT_RECORD_TYPE`
`schema_version`	`Literal[1]`	`SHARED_ARTIFACT_SCHEMA_VERSION`
`reference`	`SharedArtifactRef`	`required`
`source_session_instance_id`	`str`	`Field(max_length=64)`
`source_workspace_id`	`str`	`Field(max_length=1024)`
`source_path_sha256`	`str`	`Field(pattern=_RAW_SHA256_PATTERN)`
`root_invocation_id`	`str`	`Field(max_length=64)`
`root_session_id`	`str`	`Field(max_length=1024)`
`invocation_origin_sha256`	`str`	`Field(pattern=_RAW_SHA256_PATTERN)`
`causal_budget_id`	`str`	`Field(max_length=1024)`
`content_type`	`str`	`Field(max_length=1024)`
`policy_fingerprint`	`str`	`Field(pattern=_RAW_SHA256_PATTERN)`
`audience`	`SharedArtifactAudience`	`required`
`max_lineage_depth`	`StrictInt`	`Field(ge=1, le=DEFAULT_SHARED_ARTIFACT_MAX_LINEAGE_DEPTH)`
`retention_class`	`str`	`Field(max_length=128)`
`published_at`	`datetime`	`required`
`expires_at`	`datetime`	`required`
`status`	`SharedArtifactGrantStatus`	`SharedArtifactGrantStatus.ACTIVE`
`revoked_at`	`datetime \| None`	`None`
`revocation_reason`	`str \| None`	`Field(default=None, max_length=1024)`

validate_text (method)

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

normalize_time (method)

SharedArtifactGrant.normalize_time(value: datetime | None) -> datetime | None

validate_lifecycle (method)

SharedArtifactGrant.validate_lifecycle() -> SharedArtifactGrant

Release source · Runtime guarantees · Capability guides

`SharedArtifactGrantStatus`

from cayu.tools import SharedArtifactGrantStatus

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`ACTIVE`	`class attribute`	`'active'`
`REVOKED`	`class attribute`	`'revoked'`

Release source · Runtime guarantees · Capability guides

`SharedArtifactMaterializationReceipt`

from cayu.tools import SharedArtifactMaterializationReceipt

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`record_type`	`Literal['cayu.shared-artifact-materialization-receipt']`	`_MATERIALIZATION_RECEIPT_RECORD_TYPE`
`schema_version`	`Literal[1]`	`SHARED_ARTIFACT_SCHEMA_VERSION`
`operation_id`	`str`	`Field(pattern=_OPERATION_ID_PATTERN)`
`reference`	`SharedArtifactRef`	`required`
`source_workspace_id`	`str`	`Field(max_length=1024)`
`destination_session_id`	`str`	`Field(max_length=1024)`
`destination_workspace_id`	`str`	`Field(max_length=1024)`
`destination_path_sha256`	`str`	`Field(pattern=_RAW_SHA256_PATTERN)`
`policy_fingerprint`	`str`	`Field(pattern=_RAW_SHA256_PATTERN)`
`bytes_written`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`terminal_disposition`	`Literal['materialized']`	`'materialized'`
`materialized_at`	`datetime`	`required`

validate_text (method)

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

normalize_time (method)

SharedArtifactMaterializationReceipt.normalize_time(value: datetime) -> datetime

Release source · Runtime guarantees · Capability guides

`SharedArtifactPolicy`

from cayu.tools import SharedArtifactPolicy

Application-sealed publication and materialization policy.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal[1]`	`SHARED_ARTIFACT_SCHEMA_VERSION`
`publish_path_prefixes`	`tuple[str, ...]`	`required`
`materialize_path_prefixes`	`tuple[str, ...]`	`required`
`allowed_content_types`	`tuple[str, ...]`	`required`
`max_bytes`	`StrictInt`	`Field(default=DEFAULT_SHARED_ARTIFACT_MAX_BYTES, ge=1, le=MAX_SHARED_ARTIFACT_BYTES)`
`max_publications_per_session`	`StrictInt`	`Field(default=DEFAULT_SHARED_ARTIFACT_MAX_PUBLICATIONS, ge=1, le=MAX_SHARED_ARTIFACT_PUBLICATIONS)`
`grant_ttl_seconds`	`StrictInt`	`Field(default=DEFAULT_SHARED_ARTIFACT_GRANT_TTL_SECONDS, ge=1, le=MAX_SHARED_ARTIFACT_GRANT_TTL_SECONDS)`
`max_lineage_depth`	`StrictInt`	`Field(default=DEFAULT_SHARED_ARTIFACT_MAX_LINEAGE_DEPTH, ge=1, le=DEFAULT_SHARED_ARTIFACT_MAX_LINEAGE_DEPTH)`
`audience`	`SharedArtifactAudience`	`SharedArtifactAudience.DESCENDANT_FORK_OR_SUBAGENT`
`retention_class`	`str`	`Field(default='lineage_handoff', max_length=128)`
`allow_overwrite`	`StrictBool`	`False`

copy_path_prefixes (method)

SharedArtifactPolicy.copy_path_prefixes(value: object, info) -> tuple[str, ...]

copy_content_types (method)

SharedArtifactPolicy.copy_content_types(value: object) -> tuple[str, ...]

validate_retention_class (method)

SharedArtifactPolicy.validate_retention_class(value: str) -> str

fingerprint (property)

SharedArtifactPolicy.fingerprint() -> str

Release source · Runtime guarantees · Capability guides

`SharedArtifactPublicationReceipt`

from cayu.tools import SharedArtifactPublicationReceipt

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`record_type`	`Literal['cayu.shared-artifact-publication-receipt']`	`_PUBLICATION_RECEIPT_RECORD_TYPE`
`schema_version`	`Literal[1]`	`SHARED_ARTIFACT_SCHEMA_VERSION`
`operation_id`	`str`	`Field(pattern=_OPERATION_ID_PATTERN)`
`reference`	`SharedArtifactRef`	`required`
`source_workspace_id`	`str`	`Field(max_length=1024)`
`source_path_sha256`	`str`	`Field(pattern=_RAW_SHA256_PATTERN)`
`content_type`	`str`	`Field(max_length=1024)`
`policy_fingerprint`	`str`	`Field(pattern=_RAW_SHA256_PATTERN)`
`retention_class`	`str`	`Field(max_length=128)`
`terminal_disposition`	`Literal['published']`	`'published'`
`published_at`	`datetime`	`required`

validate_text (method)

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

normalize_time (method)

SharedArtifactPublicationReceipt.normalize_time(value: datetime) -> datetime

Release source · Runtime guarantees · Capability guides

`SharedArtifactRef`

from cayu.tools import SharedArtifactRef

Opaque routing identity for one grant; possession is not authorization.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal[1]`	`SHARED_ARTIFACT_SCHEMA_VERSION`
`artifact_store_id`	`str`	`Field(max_length=1024)`
`artifact_id`	`str`	`Field(pattern=_ARTIFACT_ID_PATTERN)`
`content_digest`	`str`	`Field(pattern=_SHA256_IDENTIFIER_PATTERN)`
`size_bytes`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`source_session_id`	`str`	`Field(max_length=1024)`
`access_grant_id`	`str`	`Field(pattern=_GRANT_ID_PATTERN)`

validate_identity (method)

SharedArtifactRef.validate_identity(value: str, info) -> str

to_opaque_ref (method)

SharedArtifactRef.to_opaque_ref() -> str

from_opaque_ref (method)

SharedArtifactRef.from_opaque_ref(value: str) -> SharedArtifactRef

Release source · Runtime guarantees · Capability guides