Skip to content

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)

Submit and observe Zeroshot graph runs and hosted merge plans.

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 ) –

    Source for runtime-declared environment values. None reads the ambient environment at submission time. An explicit mapping is the complete value source.

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 local workspace.

Returns:

Raises:

__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 

run(
    task: str,
    *,
    title: str | None = None,
    preset: Preset | None = None,
    runtime: _Runtime | None = None,
    repository: str | None = None,
    branch: str | None = None,
    revision: str | None = None,
    submission_key: str | None = None,
    wait_timeout: float | None = None,
) -> RunResult

run(
    task: RunRequest, *, wait_timeout: float | None = None
) -> RunResult

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, repository, branch, revision, and submission_key apply to string submissions. 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.

  • 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 

submit(task: str, **options: Unpack[_SubmitOptions]) -> Run

submit(task: RunRequest) -> Run

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, repository, branch, revision, and submission_key.

Returns:

  • Run –

    A durable run handle bound to this client's target.

Raises:

Exact RunRequest values cannot be combined with string-submission overrides. Preflight completes before local controller startup or direct-target contact.

submit_plan(request: MergePlanRequest) -> MergePlan async

Validate and atomically submit one merge-only DAG to a hosted target.

Parameters:

  • request (MergePlanRequest) –

    Immutable plan metadata, profile selector, and static run DAG.

Returns:

  • MergePlan –

    A durable merge-plan handle bound to this client's hosted target.

Raises:

get_plan(plan_id: str) -> MergePlan

Reconstruct a durable hosted merge-plan handle without target I/O.

Parameters:

  • plan_id (str) –

    Opaque server-assigned plan identity.

Returns:

  • MergePlan –

    A handle resolved lazily against this client's named hosted target.

Raises:

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:

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.

get_preset(name: str, *, delivery: str = 'none') -> GraphSpec async

Read one built-in preset from the bundled executable.

Parameters:

  • name (str) –

    Exact native preset name.

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

    Native delivery selector, such as none, pull_request, or merge.

Returns:

  • GraphSpec –

    The GraphSpec emitted by Zeroshot, copied without changes.

Raises:

MergePlan(client: Client, plan_id: str)

Durable hosted merge-plan handle bound to one Client target.

id: str property

Return the opaque server-assigned merge-plan identity.

status() -> MergePlanStatus async

Read the plan's current aggregate status.

watch() -> AsyncIterator[MergePlanStatus]

Poll and yield changed aggregate snapshots until the plan is terminal.

Cancelling or closing the iterator detaches observation and leaves runs active.

wait(*, wait_timeout: float | None = None) -> MergePlanStatus async

Wait for a terminal aggregate status without controlling plan lifetime.

Parameters:

  • wait_timeout (float | None, default: None ) –

    Non-negative observation deadline in seconds. None waits indefinitely.

Raises:

  • ValueError –

    If wait_timeout is negative.

  • MergePlanWaitTimeout –

    If observation expires; it carries this durable handle.

  • TargetError –

    If the selected target is unavailable.

  • ProtocolError –

    If native output is malformed.

force_stop() -> MergePlanStatus async

Force every nonterminal run to stop and wait for aggregate termination.

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:

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.

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

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: