Configuration

Async Python SDK for submitting and observing Zeroshot runs.

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

JsonValue: TypeAlias = None | bool | int | float | str | list['JsonValue'] | dict[str, 'JsonValue'] 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 ) –

  Git workspace used in place by new runs. None captures the current directory when the client opens.

• 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') dataclass

Select an executable-owned built-in graph template.

Parameters:

• name (str) –

  Exact name returned by Client.list_presets().

• delivery (str, default: 'none' ) –

  Native delivery selector: none, pull_request, or merge.

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, size: str = 'medium', session_scope: str = 'execution', connections: Mapping[str, tuple[str, ...]] | None = None) dataclass

Apply one agent runtime to every executable graph node.

Parameters:

• harness (str) –

  Native codex or claude harness name.

• provider (str) –

  Native provider name.

• model (str) –

  Native model identifier.

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

  Optional native reasoning effort.

• size (str, default: 'medium' ) –

  Native small, medium, or large run size.

• 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. Values are read only from Client.environment.

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, repository: 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.

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

  Named-target GitHub repository override in owner/name form.

• 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.

MergePlanRequest(*, title: str, repository: str, branch: str, profile: str, expires_at: str, runs: Mapping[str, MergePlanRun], submission_key: str | None = None) dataclass

A complete merge-only DAG submitted atomically to one hosted target.

Parameters:

• title (str) –

  Human-readable immutable plan title.

• repository (str) –

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

• branch (str) –

  Source branch shared by every node.

• 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.

• expires_at (str) –

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

• runs (Mapping[str, MergePlanRun]) –

  Node 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 merge-plan manifest consumed by Zeroshot.

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

One statically defined node in a hosted merge plan.

Parameters:

• input (JsonValue) –

  Closed JSON input validated against the selected profile graph.

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

  Symbolic node names that must merge successfully before this node becomes ready.

to_dict() -> dict[str, JsonValue]

Return this node's exact manifest representation.