Workspace API Reference

Bases: BaseModel

Specification for creating an isolated workspace.

Parameters:

Name	Description	Default
`run_id`	Globally unique identifier. The workspace directory is named after this ID.	required
`project_root`	Path to the business project root (must contain `skills/` and `agents/` directories).	required
`data_inputs`	Mapping of logical names to source file paths. Files are copied into `workspace/data/` at creation time.	required
`extra_env`	Additional environment variables passed to the Agent SDK.	required
`force`	If True, overwrite existing workspace with the same `run_id`. If False (default), raise `WorkspaceError`.	required

Example

from pathlib import Path from scrivai import WorkspaceSpec spec = WorkspaceSpec( ... run_id="audit-001", ... project_root=Path("/path/to/project"), ... force=True, ... )

Bases: BaseModel

Reference to an existing workspace; used by both the business layer and PES.

Bases: Protocol

WorkspaceManager Protocol (M0.25 implementation).

`create(spec)`

Create a new workspace from spec; behaviour on run_id conflict is determined by spec.force.

`archive(handle, success)`

Archive a workspace. success=True creates a tar.gz and removes the directory; False writes a .failed marker.

`cleanup_old(days=30)`

Delete archives and .failed workspaces whose mtime exceeds the given number of days.

Bases: BaseModel

Workspace snapshot metadata (written to meta.json).

Create a workspace manager with default directory layout.

Returns a WorkspaceManager (Protocol-typed) backed by the local filesystem. Workspaces are created under workspaces_root and archived to archives_root.

Parameters:

Name	Type	Description	Default
`workspaces_root`	`Path \| str`	Directory for active workspaces. Defaults to `~/.scrivai/workspaces`.	`'~/.scrivai/workspaces'`
`archives_root`	`Path \| str`	Directory for archived workspaces. Defaults to `~/.scrivai/archives`.	`'~/.scrivai/archives'`

Returns:

Type	Description
`WorkspaceManager`	A `WorkspaceManager` instance.

Example

from scrivai import build_workspace_manager ws_mgr = build_workspace_manager() ws_mgr = build_workspace_manager( ... workspaces_root="/tmp/my-workspaces", ... archives_root="/tmp/my-archives", ... )