Client and run handle¶
Async Python SDK for submitting and observing Zeroshot runs.
Client(*, target: Target | None = None, preset: Preset | None = None, runtime: _Runtime | None = None, environment: Mapping[str, str] | None = None, forward_github_token: bool = False)
¶
Submit and observe Zeroshot graph runs and hosted stacks.
Parameters:
-
target(Target | None, default:None) –Local target by default, an unauthenticated direct target, or a named hosted target.
-
preset(Preset | None, default:None) –Default executable-owned graph preset. None selects software-change.
-
runtime(_Runtime | None, default:None) –Default runtime. None requires a runtime on each string submission.
-
environment(Mapping[str, str] | None, default:None) –Submission environment values. None reads the ambient environment; an explicit mapping replaces ambient credential variables. Native saved connections and local harness login still apply.
-
forward_github_token(bool, default:False) –Send the submission environment's GH_TOKEN to a direct or hosted target. Without it, the target resolves GitHub access from its own stored connection and GH_TOKEN is not sent. Requires GH_TOKEN in the submission environment.
Raises:
-
InvalidRequestError–If forward_github_token is set for a local target.
The SDK never guesses a harness, provider, or model. Closing the client detaches observation and never stops runs.
__aenter__() -> Client
async
¶
Open the client and capture a default working folder.
Returns:
-
Client–This client.
Raises:
-
ClientClosedError–If this client was already closed.
__aexit__(exc_type: type[BaseException] | None, exc: BaseException | None, traceback: object) -> None
async
¶
Close client-owned routing state without stopping durable runs.
aclose() -> None
async
¶
Release client-owned routing state without stopping submitted runs.
run(task: str | RunRequest, **options: Unpack[_RunOptions]) -> RunResult
async
¶
Submit one graph run and wait for its terminal result.
Parameters:
-
task(str | RunRequest) –Task text for a built-in preset, or a complete RunRequest.
-
options(Unpack[_RunOptions], default:{}) –Typed keyword options. title, preset, runtime, cwd, worktree, worktree_base, repository, source_connection, branch, revision, and submission_key apply to string submissions. worktree defaults to False; worktree_base accepts local or remote. See RunRequest for local-only worktree and cleanup semantics. wait_timeout is a non-negative observation deadline in seconds; omit it to wait indefinitely.
Returns:
-
RunResult–The terminal result. Graph failure remains data until raise_for_failure() is called.
Raises:
-
InvalidRequestError–If a string submission has no effective preset or runtime, or Zeroshot rejects the request.
-
RunWaitTimeout–If observation expires; its run attribute can resume waiting.
-
RunSuspendedError–If the attempt suspends; carries its run handle and status.
-
TargetError–If the sidecar or selected target is unavailable.
-
ProtocolError–If native output is malformed or incompatible.
Cancellation detaches observation and leaves the durable run active.
submit(task: str | RunRequest, **options: Unpack[_SubmitOptions]) -> Run
async
¶
Preflight in Zeroshot, submit one durable run, and return its handle.
Parameters:
-
task(str | RunRequest) –Task text for a built-in preset, or a complete RunRequest.
-
options(Unpack[_SubmitOptions], default:{}) –Typed keyword options for string submissions: title, preset, runtime, cwd, worktree, worktree_base, repository, source_connection, branch, revision, and submission_key. worktree defaults to False; worktree_base accepts local or remote. See RunRequest for local-only worktree and cleanup semantics.
Returns:
-
Run–A durable run handle bound to this client's target.
Raises:
-
InvalidRequestError–If required selection is absent or native preflight rejects it.
-
TargetError–If native execution or target submission fails.
-
ProtocolError–If native output is malformed.
Exact RunRequest values cannot be combined with string-submission overrides. Preflight completes before local controller startup or direct-target contact.
submit_stack(request: StackRequest) -> Stack
async
¶
Validate and atomically submit one stack of runs to a hosted target.
Parameters:
-
request(StackRequest) –Immutable stack metadata, profile selector, delivery mode, and static run DAG.
Returns:
-
Stack–A durable stack handle bound to this client's hosted target.
Raises:
-
InvalidRequestError–If this client does not use HostedTarget or validation fails.
-
TargetError–If the named target is unavailable or submission fails.
-
ProtocolError–If native output is malformed.
get_stack(stack_id: str) -> Stack
¶
Reconstruct a durable hosted stack handle without target I/O.
Parameters:
-
stack_id(str) –Opaque server-assigned stack identity.
Returns:
-
Stack–A handle resolved lazily against this client's named hosted target.
Raises:
-
ClientClosedError–If this client is closed.
-
InvalidRequestError–If this client does not use HostedTarget.
get_run(run_id: str) -> Run
¶
Reconstruct a durable handle without target I/O.
Parameters:
-
run_id(str) –Opaque public run identity.
Returns:
-
Run–A handle resolved lazily against this client's target.
Raises:
-
ClientClosedError–If this client is closed.
list_runs() -> tuple[RunSummary, ...]
async
¶
Return summaries for runs retained by this client's target.
list_presets() -> tuple[str, ...]
async
¶
Return built-in preset names read dynamically from the bundled executable.
list_targets() -> tuple[NamedTarget, ...]
async
¶
List local registrations, including platform, without contacting any target.
This reads the user's registry independently of this client's run target.
remove_target(name: str) -> TargetRemoveResult
async
¶
Remove a local registration, its stored login and resume permissions.
Parameters:
-
name(str) –Exact local target name.
Returns:
-
TargetRemoveResult–The native removal receipt.
Raises:
-
InvalidRequestError–If the name is unknown or is the built-in platform target.
-
TargetError–If local storage cleanup fails.
-
ProtocolError–If the native receipt is malformed.
get_preset(name: str, *, delivery: str | None = None) -> GraphSpec
async
¶
Read one built-in preset from the bundled executable.
Parameters:
-
name(str) –Exact native preset name.
-
delivery(str | None, default:None) –Native delivery selector. None uses the executable-owned template default.
Returns:
-
GraphSpec–The GraphSpec emitted by Zeroshot, copied without changes.
Raises:
-
InvalidRequestError–If Zeroshot rejects the name or delivery combination.
-
ProtocolError–If Zeroshot emits a malformed graph document.
inbox(after: str | None = None, limit: int = 50) -> InboxPage
async
¶
Read requests still holding their runs suspended without applying expiry.
Parameters:
-
after(str | None, default:None) –Exclusive run ID cursor, or None for the first page.
-
limit(int, default:50) –Maximum entries, from 1 through 100.
Returns:
-
InboxPage–The request page and its next cursor.
Raises:
-
ValueError–If limit is outside 1 through 100.
Run(client: Client, run_id: str)
¶
Durable public run handle bound to one Client target.
id: str
property
¶
Return the opaque public Zeroshot run identity.
status() -> RunStatus
async
¶
Read the current durable run status.
Returns:
-
RunStatus–The latest target projection.
Raises:
-
RunNotFoundError–If the target no longer retains this run.
-
TargetError–If the selected target is unavailable.
-
ProtocolError–If native output is malformed.
watch(*, after: str | None = None) -> AsyncIterator[RunStatus]
¶
Open a durable status stream strictly after an optional cursor.
Parameters:
-
after(str | None, default:None) –Last consumed opaque status cursor. None replays retained history.
Returns:
-
AsyncIterator[RunStatus]–An async iterator of immutable status snapshots.
Cancelling or closing the iterator detaches observation and does not stop the run.
logs(*, after: str | None = None, execution: str | None = None) -> AsyncIterator[LogEvent]
¶
Open the durable redacted log stream with resume and execution filters.
Parameters:
-
after(str | None, default:None) –Last consumed opaque log cursor. None replays retained logs.
-
execution(str | None, default:None) –Opaque execution selector from RunStatus, or None for all records.
Returns:
-
AsyncIterator[LogEvent]–An async iterator of safe native log records.
Cancelling or closing the iterator detaches observation and does not stop the run.
wait(*, wait_timeout: float | None = None) -> RunResult
async
¶
Wait for the durable terminal result without controlling run lifetime.
Parameters:
-
wait_timeout(float | None, default:None) –Non-negative observation deadline in seconds. None waits indefinitely.
Returns:
-
RunResult–The successful or failed terminal result.
Raises:
-
ValueError–If wait_timeout is negative.
-
RunWaitTimeout–If the deadline expires. The exception carries this run handle.
-
RunSuspendedError–If the attempt suspends; carries this handle and its status.
-
RunNotFoundError–If the target no longer retains this run.
-
TargetError–If observation fails.
-
ProtocolError–If native output is malformed.
Python task cancellation remains asyncio.CancelledError and leaves the run active.
suspend() -> RunStatus
async
¶
Request suspension and return the status immediately.
Returns:
-
RunStatus–The current durable status with the suspension request recorded.
resume() -> Run
async
¶
Continue this attempt in a successor with fresh native sessions.
Returns:
-
Run–The successor run handle.
request() -> InboxRequest
async
¶
Read the request this run made, including its state and successor.
Returns:
-
InboxRequest–The complete inbox request. Inherited requests are excluded.
answer(answer: JsonValue) -> Run
async
¶
steer(text: str, *, mode: Literal['once', 'standing'] = 'standing') -> RunSteer
async
¶
Record direction without continuing a suspended run.
Parameters:
-
text(str) –Nonblank UTF-8 direction, at most 262,144 bytes. Do not include secrets.
-
mode(Literal['once', 'standing'], default:'standing') –Standing once per provider conversation, or once per node instance.
Returns:
-
RunSteer–The recorded steer, including its vector identity and receipt summary.
Raises:
-
ValueError–If mode is neither once nor standing.
-
RunNotFoundError–If the run is no longer retained.
-
TargetError–If the run refuses steering or transport fails.
-
ProtocolError–If native output is malformed.
vectors(*, after: str | None = None, limit: int = 50) -> RunVectorsPage
async
¶
Read one ordered page of the vector record.
Parameters:
-
after(str | None, default:None) –Opaque entry cursor, or None for the first page.
-
limit(int, default:50) –Number of entries, from 1 through 100.
Returns:
-
RunVectorsPage–Entries and the next cursor, if any.
Raises:
-
ValueError–If limit is outside 1 through 100.
vector(id: str) -> RunVector
async
¶
Read a vector entry with its complete content.
Parameters:
-
id(str) –Opaque entry identity.
Returns:
-
RunVector–The durable entry.
force_stop() -> RunResult
async
¶
Force-stop this run and wait for its durable terminal result.
Returns:
-
RunResult–The existing terminal result, or a failed result whose reason is force_stopped.
Raises:
-
RunSuspendedError–If the run is suspended and already has a successor, which a force-stop leaves unchanged.
-
RunNotFoundError–If the target no longer retains this run.
-
TargetError–If mutation or observation fails.
-
ProtocolError–If native output is malformed.
discard_workspace() -> bool
async
¶
Delete this run's retained workspace or local recovery-lineage checkpoints.
Local runs keep their checkout, ledger, logs and delivery recovery state. Running or resuming lineage members refuse deletion; an uncontinued suspension must be force-stopped first, and an interrupted restore must be completed. A plain local resume still uses the current checkout.
Returns:
-
bool–Whether retained workspace or checkpoint data was deleted.
Raises:
-
InvalidRequestError–If the workspace cannot be discarded in its current state.
-
RunNotFoundError–If the target no longer retains this run.
-
TargetError–If the operation fails.
-
ProtocolError–If native output is malformed.
Stack(client: Client, stack_id: str)
¶
Durable hosted stack handle bound to one Client target.
A "stacked_pull_requests" stack is complete once every pull request is open; Zeroshot never merges, retargets, or restacks them. Merge them from the bottom up: GitHub moves a child pull request onto the base branch when its merged parent's branch is deleted. A squash-merged parent leaves the child to rebase onto the base branch, and changes pushed to a parent pull request during review are not restacked, so rebase the pull requests above it by hand.
id: str
property
¶
Return the opaque server-assigned stack identity.
status() -> StackStatus
async
¶
Read the stack's current aggregate status.
watch() -> AsyncIterator[StackStatus]
¶
Poll and yield changed aggregate snapshots until the stack is terminal.
Cancelling or closing the iterator detaches observation and leaves runs active.
wait(*, wait_timeout: float | None = None) -> StackStatus
async
¶
Wait for a terminal aggregate status without controlling stack lifetime.
Parameters:
-
wait_timeout(float | None, default:None) –Non-negative observation deadline in seconds. None waits indefinitely.
Raises:
-
ValueError–If wait_timeout is negative.
-
StackWaitTimeout–If observation expires; it carries this durable handle.
-
TargetError–If the selected target is unavailable.
-
ProtocolError–If native output is malformed.
force_stop() -> StackStatus
async
¶
Force every nonterminal run to stop and wait for aggregate termination.
await run.steer(text) returns a RunSteer receipt for standing direction. It follows the handle's
local or named-target route, leaves suspended runs suspended and uses the existing typed errors.
Pass mode="once" to deliver once per node instance; mode="standing" remains the default.
Read complete text through Run.vector(receipt.id).