Configuration

Async Python SDK for submitting and observing Zeroshot runs.

Target: TypeAlias = LocalTarget | DirectTarget | HostedTarget module-attribute

StackDelivery: TypeAlias = Literal['merge', 'stacked_pull_requests'] module-attribute

How a hosted stack lands its runs.

"merge" merges each run into the base branch before its dependents start. "stacked_pull_requests" orders the runs into one linear stack and opens each pull request against the previous run's branch without merging anything.

JsonValue: TypeAlias = bool | int | float | str | list['JsonValue'] | dict[str, 'JsonValue'] | None module-attribute

LocalTarget(workspace: str | PathLike[str] | None = None, *, state_dir: str | PathLike[str] | None = None) dataclass

Execute against the local Zeroshot controller.

Parameters:

• workspace (str | PathLike[str] | None, default: None ) –

  Default working folder, used in place. None captures the current folder when the client opens; per-run cwd is relative to this folder.

• state_dir (str | PathLike[str] | None, default: None ) –

  Optional native controller state directory. Reuse it to observe local runs from later client instances; None uses the native package-owned default.

DirectTarget(origin: str, *, workspace: str | PathLike[str] | None = None) dataclass

Connect to an unauthenticated Zeroshot target, including the Docker image.

Parameters:

• origin (str) –

  Target HTTP(S) origin. Native validation permits plain HTTP only on loopback.

• workspace (str | PathLike[str] | None, default: None ) –

  Git worktree used to select source and report dirty state. None captures the current directory when the client opens.

HostedTarget(name: str) dataclass

Use a named hosted target already configured and logged in through the CLI.

Parameters:

• name (str) –

  Exact local target name from zeroshot target list. The SDK reuses that target's stored origin and login.

Preset(name: str, *, delivery: str | None = None, pull_request_feedback: str = 'consider') dataclass

Select an executable-owned built-in graph template.

Parameters:

• name (str) –

  Exact name returned by Client.list_presets().

• delivery (str | None, default: None ) –

  Native delivery selector. None uses the executable-owned template default.

• pull_request_feedback (str, default: 'consider' ) –

  Whether pull-request feedback is considered or ignored for pull_request and merge delivery.

GraphSpec(document: Mapping[str, JsonValue]) dataclass

Bases: _OpaqueDocument

Opaque custom GraphSpec passed unchanged to Zeroshot.

Parameters:

• document (Mapping[str, JsonValue]) –

  JSON-compatible GraphSpec mapping. Python performs no semantic validation.

from_dict(value: Mapping[str, JsonValue]) -> GraphSpec classmethod

Construct an opaque GraphSpec without validating or traversing it.

to_dict() -> dict[str, JsonValue]

Return a defensive mutable copy suitable for native JSON encoding.

UniformRuntime(*, harness: str, provider: str, model: str, effort: str | None = None, context_window: int | None = None, max_tokens: int | None = None, size: str | None = None, workspace_checkpoints: bool = True, session_scope: str = 'execution', connections: Mapping[str, tuple[str, ...]] | None = None, active_memory: Mapping[str, JsonValue] | None = None, global_agents: Mapping[str, JsonValue] | None = None, harness_config: Mapping[str, JsonValue] | None = None) dataclass

Apply one agent runtime to every executable graph node.

Parameters:

• harness (str) –

  Harness identifier enabled by the selected host.

• provider (str) –

  Native provider name.

• model (str) –

  Native model identifier.

• effort (str | None, default: None ) –

  Optional native reasoning effort.

• context_window (int | None, default: None ) –

  Optional caller-declared model context window. None keeps the provider's own default.

• max_tokens (int | None, default: None ) –

  Optional caller-declared model output limit. None keeps the provider's own default.

• size (str | None, default: None ) –

  Opaque target-owned size identifier. None leaves the choice to the target default.

• workspace_checkpoints (bool, default: True ) –

  Whether to capture workspace snapshots. Defaults to enabled.

• session_scope (str, default: 'execution' ) –

  execution opens a fresh session for each execution; node_instance reuses a live session when that graph node instance runs again.

• connections (Mapping[str, tuple[str, ...]] | None, default: None ) –

  Connection keys mapped to the exact environment field names their agent nodes need. None selects the executable-owned provider defaults; an empty mapping declares no connections.

• harness_config (Mapping[str, JsonValue] | None, default: None ) –

  Optional secret-free native args/options for each agent binding.

• active_memory (Mapping[str, JsonValue] | None, default: None ) –

  Optional native repository/graph recall and collection controls.

• global_agents (Mapping[str, JsonValue] | None, default: None ) –

  Optional native built-in global-agent settings, including postmortem.

to_dict() -> dict[str, JsonValue]

Encode the declarative uniform runtime consumed and validated by Zeroshot.

RuntimePlan(document: Mapping[str, JsonValue]) dataclass

Bases: _OpaqueDocument

Opaque native RuntimePlan passed unchanged to Zeroshot.

Parameters:

• document (Mapping[str, JsonValue]) –

  JSON-compatible RuntimePlan mapping. Python performs no semantic validation.

from_dict(value: Mapping[str, JsonValue]) -> RuntimePlan classmethod

Construct an opaque RuntimePlan without validating graph bindings.

to_dict() -> dict[str, JsonValue]

Return a defensive mutable copy suitable for native JSON encoding.

RunRequest(*, title: str, graph: GraphSpec, initial_input: JsonValue, runtime: RuntimePlan, cwd: str | Path | None = None, repository: str | None = None, source_connection: str | None = None, branch: str | None = None, revision: str | None = None, submission_key: str | None = None) dataclass

Inputs for one custom Zeroshot graph run.

Parameters:

• title (str) –

  Human-readable persisted run title.

• graph (GraphSpec) –

  Opaque GraphSpec passed to Zeroshot without changes.

• initial_input (JsonValue) –

  Closed JSON input that Zeroshot validates against the graph.

• runtime (RuntimePlan) –

  Opaque RuntimePlan passed to Zeroshot without changes.

• cwd (str | Path | None, default: None ) –

  Working folder relative to the captured client workspace; None uses that workspace.

• repository (str | None, default: None ) –

  Source override as a Git clone URL or GitHub owner/name shorthand.

• source_connection (str | None, default: None ) –

  Explicit source-only named connection key.

• branch (str | None, default: None ) –

  Named-target source branch override.

• revision (str | None, default: None ) –

  Named-target exact source commit override.

• submission_key (str | None, default: None ) –

  Stable idempotency key; None generates one before native preflight.

StackRequest(*, title: str, repository: str, branch: str, profile: str, delivery: StackDelivery, expires_at: str, runs: Mapping[str, StackRun], submission_key: str | None = None) dataclass

An immutable DAG of runs submitted atomically to one hosted target.

Parameters:

• title (str) –

  Human-readable immutable stack title.

• repository (str) –

  Source repository in owner/name form, shared by every run.

• branch (str) –

  Base branch shared by every run.

• profile (str) –

  Hosted profile selector in user:name or org:name form. Agent bindings cannot declare GH_TOKEN; only the Git delivery binding can declare it.

• delivery (StackDelivery) –

  How the stack lands. "merge" requires exactly one builtin.git-delivery.merge@2 or builtin.git-delivery.merge@3 node in the profile and merges each run into the base branch before its dependents start; a run may need several others. "stacked_pull_requests" requires exactly one builtin.git-delivery.pr@2 node, turns the runs into one linear stack in dependency order with ties broken by run name, and opens each run's pull request against the previous run's branch, the first against the base branch. Nothing is merged.

• expires_at (str) –

  RFC 3339 deadline for the whole stack, at most seven days in the future.

• runs (Mapping[str, StackRun]) –

  Run names mapped to static inputs and symbolic dependencies.

• submission_key (str | None, default: None ) –

  Stable idempotency key; None generates one before native validation.

to_dict() -> dict[str, JsonValue]

Return the strict public stack manifest consumed by Zeroshot.

StackRun(*, input: JsonValue, needs: tuple[str, ...] = ()) dataclass

One statically defined run in a hosted stack.

Parameters:

• input (JsonValue) –

  Closed JSON input validated against the selected profile graph.

• needs (tuple[str, ...], default: () ) –

  Symbolic run names that must succeed before this run becomes ready. With "merge" delivery each of them has merged into the base branch first. With "stacked_pull_requests" delivery they only order the linear stack, in which each run needs exactly the run before it.

to_dict() -> dict[str, JsonValue]

Return this run's exact manifest representation.