cayu.environments.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.

copy_environment

from cayu.environments import copy_environment

copy_environment(environment: Environment) -> Environment

Release source · Runtime guarantees · Capability guides

DEFAULT_WORKSPACE_INSTRUCTION_PATHS

from cayu.environments import DEFAULT_WORKSPACE_INSTRUCTION_PATHS

DEFAULT_WORKSPACE_INSTRUCTION_PATHS = ('AGENTS.md', '.cayu/AGENTS.md')

Release source · Runtime guarantees · Capability guides

DEFAULT_WORKSPACE_INSTRUCTIONS_MAX_BYTES

from cayu.environments import DEFAULT_WORKSPACE_INSTRUCTIONS_MAX_BYTES

DEFAULT_WORKSPACE_INSTRUCTIONS_MAX_BYTES = 32 * 1024

Release source · Runtime guarantees · Capability guides

Environment

from cayu.environments import Environment

Execution context an agent session can use.

The environment is intentionally thin for now. Concrete local, Docker, hosted, or customer-hosted environments can bind workspace, runner, vault, and MCP services without making those details part of AgentSpec.

init (method)

Environment.__init__(spec: EnvironmentSpec, *, workspace: Workspace | None=None, artifact_store: ArtifactStore | None=None, runner: Runner | None=None, vault: Vault | None=None, proxy: CredentialProxy | None=None, knowledge_store: KnowledgeStore | None=None, knowledge_access_scope: KnowledgeAccessScope | None=None, binding: WorkspaceBinding | None=None, mcp_servers: Iterable[McpServerSpec] | None=None, workspace_instructions: WorkspaceInstructionsInput | None=None) -> None

knowledge_store (property)

Environment.knowledge_store() -> KnowledgeStore | None

Return the registration-time knowledge store binding.

The binding is intentionally read-only. Runtime execution profiles and isolated intervention admission both authenticate this exact object; replacing it after admission would turn those checks into a check/use race.

knowledge_access_scope (property)

Environment.knowledge_access_scope() -> KnowledgeAccessScope | None

Return a defensive copy of the registration-time access scope.

resolve_secret (method)

async Environment.resolve_secret(ref: SecretRef, *, scope: dict[str, Any] | None=None) -> ResolvedSecret

Resolve a secret ref through the environment vault.

Release source · Runtime guarantees · Capability guides

EnvironmentSpec

from cayu.environments import EnvironmentSpec

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
name	str	required
metadata	dict[str, Any]	Field(default_factory=dict)
execution_profile_identity	ExecutionProfileBehaviorIdentity | None	None
lifecycle_policy	EnvironmentLifecyclePolicy | None	None
workspace_checkpoint_policy	WorkspaceCheckpointPolicy | None	None

copy_workspace_checkpoint_policy (method)

EnvironmentSpec.copy_workspace_checkpoint_policy(value: object) -> WorkspaceCheckpointPolicy | None

copy_lifecycle_policy (method)

EnvironmentSpec.copy_lifecycle_policy(value: object) -> EnvironmentLifecyclePolicy | None

copy_metadata (method)

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

validate_nonblank_name (method)

EnvironmentSpec.validate_nonblank_name(value: str, info) -> str

Release source · Runtime guarantees · Capability guides

load_workspace_instructions

from cayu.environments import load_workspace_instructions

async load_workspace_instructions(environment: Environment) -> WorkspaceInstructions | None

Release source · Runtime guarantees · Capability guides

WorkspaceInstructions

from cayu.environments import WorkspaceInstructions

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
content	str	required
sources	tuple[str, ...]	('explicit',)

validate_content (method)

WorkspaceInstructions.validate_content(value: str) -> str

validate_sources (method)

WorkspaceInstructions.validate_sources(value) -> tuple[str, ...]

Release source · Runtime guarantees · Capability guides

WorkspaceInstructionsConfig

from cayu.environments import WorkspaceInstructionsConfig

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
paths	tuple[str, ...]	DEFAULT_WORKSPACE_INSTRUCTION_PATHS
mode	Literal['first_found', 'merge']	'first_found'
max_bytes	int	DEFAULT_WORKSPACE_INSTRUCTIONS_MAX_BYTES

validate_paths (method)

WorkspaceInstructionsConfig.validate_paths(value) -> tuple[str, ...]

validate_max_bytes (method)

WorkspaceInstructionsConfig.validate_max_bytes(value: int) -> int

Release source · Runtime guarantees · Capability guides