Skip to content

Result models

Async Python SDK for submitting and observing Zeroshot runs.

ActiveExecution(*, execution: str, node: str, map_indices: tuple[int, ...] = (), started_at: int | None = None) dataclass

One graph-visible active execution.

Parameters:

  • execution (str) –

    Opaque selector accepted by log filtering.

  • node (str) –

    Executable graph node name.

  • map_indices (tuple[int, ...], default: () ) –

    Zero-based map path, outermost first; empty outside maps.

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

    Ledger recording time of NodeStarted in Unix milliseconds, or None when unknown. This is not a precise provider start measurement.

ExhaustedLoop(*, node: str, completed_iterations: int, map_indices: tuple[int, ...] = ()) dataclass

A reducer-confirmed exhausted loop visit.

Parameters:

  • node (str) –

    Graph loop name.

  • completed_iterations (int) –

    Completed rounds, independent of execution retries.

  • map_indices (tuple[int, ...], default: () ) –

    Zero-based map path, outermost first.

FailureContext(*, primary: FailureDiagnostic | None = None, recorded: tuple[FailureDiagnostic, ...] = (), verifiers: tuple[FailureDiagnostic, ...] = (), exhausted_loops: tuple[ExhaustedLoop, ...] = (), incomplete: bool = False) dataclass

Recorded failure evidence without inferring causality from log order.

Parameters:

  • primary (FailureDiagnostic | None, default: None ) –

    Explicitly identified runtime failure, when available.

  • recorded (tuple[FailureDiagnostic, ...], default: () ) –

    Recent failure records, which may include recovered or voided attempts.

  • verifiers (tuple[FailureDiagnostic, ...], default: () ) –

    Latest recorded graph-defined results per verifier and map path.

  • exhausted_loops (tuple[ExhaustedLoop, ...], default: () ) –

    Reducer-confirmed exhausted loop visits.

  • incomplete (bool, default: False ) –

    Whether additional failure evidence may be missing from this summary.

FailureDiagnostic(*, message: str, execution: ActiveExecution | None = None, cursor: str | None = None) dataclass

One producer-redacted failure record retained with the run.

Worker refusal messages distinguish authentication required, model unavailable, and stopped nodes. Messages pass through unchanged; this record also carries runtime failure diagnostics.

Parameters:

  • message (str) –

    Bounded secret-safe explanation.

  • execution (ActiveExecution | None, default: None ) –

    Associated executable graph node, or None for a run-wide record.

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

    Cursor of the original diagnostic log, when durably recorded.

LogEvent(*, run_id: str, cursor: str, timestamp: int, execution: str | None, level: Literal['debug', 'info', 'error'], target: str, message: str, map_indices: tuple[int, ...] = ()) dataclass

One safe durable native log record.

Parameters:

  • run_id (str) –

    Public durable run identity.

  • cursor (str) –

    Opaque durable log cursor.

  • timestamp (int) –

    Producer-captured Unix epoch milliseconds, preserved by replay.

  • execution (str | None) –

    Opaque execution selector, or None for run-wide records.

  • level (Literal['debug', 'info', 'error']) –

    Native debug, info, or error level.

  • map_indices (tuple[int, ...], default: () ) –

    Zero-based map path, outermost first; empty outside maps.

  • target (str) –

    Bounded native log target.

  • message (str) –

    Bounded secret-safe message.

NamedTarget(name: str, origin: str, kind: Literal['hosted', 'direct']) dataclass

A local registration, without stored login data or device identity.

Parameters:

  • name (str) –

    Exact local target name.

  • origin (str) –

    Target HTTP(S) origin.

  • kind (Literal['hosted', 'direct']) –

    Hosted authentication or unauthenticated direct access.

ResolvedGitRemote(*, url: str, forge: SourceForgeIdentity | None = None, connection: str | None = None) dataclass

Credential-free Git transport metadata.

Parameters:

  • url (str) –

    Authored HTTPS or SSH remote locator, with its original path and username.

  • forge (SourceForgeIdentity | None, default: None ) –

    Optional canonical identity for PR and merge operations.

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

    Optional named connection authorized only for Git source transport.

ResolvedSource(*, repository: str, branch: str, revision: str, remote: ResolvedGitRemote | None = None) dataclass

Immutable committed Git source snapshot.

Parameters:

  • repository (str) –

    Native repository identity.

  • branch (str) –

    Selected source branch.

  • revision (str) –

    Exact forty- or sixty-four-character Git object ID.

  • remote (ResolvedGitRemote | None, default: None ) –

    Generic transport metadata; None preserves a legacy GitHub source.

RunResult(*, run_id: str, succeeded: bool, output: JsonValue = None, delivery_receipt: JsonValue = None, failure: str | None = None, context: FailureContext | None = None) dataclass

Terminal outcome from Client.run(), Run.wait(), or Run.force_stop().

Parameters:

  • run_id (str) –

    Public durable run identity.

  • succeeded (bool) –

    Whether the graph completed successfully.

  • output (JsonValue, default: None ) –

    Successful graph-authored output, which may be JSON null.

  • delivery_receipt (JsonValue, default: None ) –

    Native delivery evidence, independent of output; None when unavailable.

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

    Stable nonempty failure reason when succeeded is false.

  • context (FailureContext | None, default: None ) –

    Structured safe failure evidence, or None for older run data.

raise_for_failure() -> None

Raise RunFailedError for a failed graph result; otherwise return None.

RunStatus(*, run_id: str, title: str, source: ResolvedSource | None, size: str, cursor: str, phase: Literal['admitted', 'running', 'stopping', 'suspended', 'finished'], active_executions: tuple[ActiveExecution, ...] = (), result: RunResult | None = None, graph_result: RunResult | None = None, controller: ControllerObservation | None = None, suspend_requested: bool = False, reason: Literal['command', 'wait', 'request'] | None = None, node: str | None = None, created_at: int | None = None, due_at: int | None = None, request: HumanRequest | None = None, steers: tuple[RunSteer, ...] = (), omitted_steers: int = 0, recorded_at: int | None = None) dataclass

Current durable projection for one run.

Parameters:

  • run_id (str) –

    Public durable run identity.

  • title (str) –

    Immutable persisted title.

  • source (ResolvedSource | None) –

    Immutable Git source snapshot, or None when unavailable for a local run.

  • size (str) –

    Opaque size identifier accepted by the target.

  • cursor (str) –

    Opaque durable status cursor.

  • phase (Literal['admitted', 'running', 'stopping', 'suspended', 'finished']) –

    admitted, running, stopping, suspended, or finished.

  • active_executions (tuple[ActiveExecution, ...], default: () ) –

    Every currently active graph execution.

  • result (RunResult | None, default: None ) –

    Terminal result only when phase is finished.

  • graph_result (RunResult | None, default: None ) –

    Recorded graph result while running or stopping, before finalization ends.

  • controller (ControllerObservation | None, default: None ) –

    Availability observation, omitted for responding controllers and ended runs.

  • suspend_requested (bool, default: False ) –

    Whether a running run has a durable suspension request.

  • reason (Literal['command', 'wait', 'request'] | None, default: None ) –

    Why an ended attempt suspended.

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

    Node held back by suspension.

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

    Suspension time in Unix epoch milliseconds.

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

    Earliest continuation time for a suspended wait, in epoch milliseconds.

  • request (HumanRequest | None, default: None ) –

    Human request contract when suspended for a request.

  • steers (tuple[RunSteer, ...], default: () ) –

    Human and peer messages with recorded receiving executions.

  • omitted_steers (int, default: 0 ) –

    Older directions omitted by the bounded status listing.

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

    Ledger recording time of the event producing a watch notification, in Unix milliseconds. None for status responses and old events without timing. Imported history carries its import time, not the original execution time. Cursor defines order.

RunSteer(*, id: str, created_at: int, text_bytes: int, excerpt: str, received_executions: int, executions: tuple[str, ...], executions_omitted: bool = False, mode: Literal['once', 'standing'] = 'standing', network: dict[str, JsonValue] | None = None) dataclass

A steering message with recorded receiving executions.

Parameters:

  • id (str) –

    Vector entry identity, usable with Run.vector().

  • created_at (int) –

    Recording time in Unix epoch milliseconds.

  • text_bytes (int) –

    Full UTF-8 text length.

  • excerpt (str) –

    First 1,024 bytes, cut at a character boundary.

  • received_executions (int) –

    Total recorded receiving executions.

  • executions (tuple[str, ...]) –

    Up to 64 most recent execution references.

  • executions_omitted (bool, default: False ) –

    Whether earlier receiving executions were omitted.

  • mode (Literal['once', 'standing'], default: 'standing' ) –

    Once per node instance or standing guidance for each provider conversation.

  • network (dict[str, JsonValue] | None, default: None ) –

    Network names and originating node, instance and execution. None for human direction.

RunSummary(*, run_id: str, title: str, source: ResolvedSource | None, size: str, cursor: str, phase: Literal['admitted', 'running', 'stopping', 'suspended', 'finished'], force_stop_requested: bool, graph_result: RunResult | None = None, controller: ControllerObservation | None = None, suspend_requested: bool = False, reason: Literal['command', 'wait', 'request'] | None = None, node: str | None = None, created_at: int | None = None, due_at: int | None = None, request: HumanRequest | None = None) dataclass

Inventory projection returned by Client.list_runs().

Parameters:

  • run_id (str) –

    Public durable run identity.

  • title (str) –

    Immutable persisted title.

  • source (ResolvedSource | None) –

    Immutable Git source snapshot, or None when unavailable for a local run.

  • size (str) –

    Opaque size identifier accepted by the target.

  • cursor (str) –

    Opaque durable status cursor.

  • phase (Literal['admitted', 'running', 'stopping', 'suspended', 'finished']) –

    admitted, running, stopping, suspended, or finished.

  • force_stop_requested (bool) –

    Whether the current projection reflects a force-stop request.

  • graph_result (RunResult | None, default: None ) –

    Recorded graph result while running or stopping, before finalization ends.

  • controller (ControllerObservation | None, default: None ) –

    Availability observation, omitted for responding controllers and ended runs.

  • suspend_requested (bool, default: False ) –

    Whether a running run has a durable suspension request.

  • reason (Literal['command', 'wait', 'request'] | None, default: None ) –

    Why an ended attempt suspended.

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

    Node held back by suspension.

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

    Suspension time in Unix epoch milliseconds.

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

    Earliest continuation time for a suspended wait, in epoch milliseconds.

  • request (HumanRequest | None, default: None ) –

    Human request contract when suspended for a request.

HumanRequest(*, id: str, text: str, signals: JsonValue, output: JsonValue, expires_at: int) dataclass

A host-run question and its declared answer contract.

Parameters:

  • id (str) –

    Opaque request vector identity.

  • text (str) –

    Question supplied by the graph.

  • signals (JsonValue) –

    Declared signals and their allowed labels.

  • output (JsonValue) –

    Closed record payload schema.

  • expires_at (int) –

    Exclusive answer deadline in Unix epoch milliseconds.

InboxEntry(*, run_id: str, node: str, created_at: int, expires_at: int, state: Literal['pending', 'expired']) dataclass

One bounded request summary.

Parameters:

  • run_id (str) –

    Run held suspended by this request.

  • node (str) –

    Request verifier name.

  • created_at (int) –

    Creation time in Unix epoch milliseconds.

  • expires_at (int) –

    Exclusive answer deadline in Unix epoch milliseconds.

  • state (Literal['pending', 'expired']) –

    Pending or expired; reading never applies expiry.

InboxPage(*, requests: tuple[InboxEntry, ...], next_after: str | None) dataclass

One request page in run ID order.

Parameters:

  • requests (tuple[InboxEntry, ...]) –

    Bounded summaries for runs still held suspended.

  • next_after (str | None) –

    Run ID cursor for the next page, or None at the end.

InboxRequest(*, run_id: str, node: str, created_at: int, request: HumanRequest, state: Literal['pending', 'answered', 'expired', 'stopped'], successor_run_id: str | None) dataclass

The request made by a run, including its disposition.

Parameters:

  • run_id (str) –

    Run that asked the question.

  • node (str) –

    Request verifier name.

  • created_at (int) –

    Creation time in Unix epoch milliseconds.

  • request (HumanRequest) –

    Complete question and answer contract.

  • state (Literal['pending', 'answered', 'expired', 'stopped']) –

    Pending, answered, expired, or stopped.

  • successor_run_id (str | None) –

    Accepted continuation, if any.

RunVector(*, id: str, run_id: str, created_at: int, kind: str, content: JsonValue) dataclass

One immutable entry in the run's ordered vector record.

Parameters:

  • id (str) –

    Opaque ordered entry identity, preserved by continuation.

  • run_id (str) –

    Attempt that wrote the entry.

  • created_at (int) –

    Entry time in Unix epoch milliseconds.

  • kind (str) –

    Entry kind.

  • content (JsonValue) –

    Complete kind-specific JSON fields.

RunVectorsPage(*, run_id: str, vectors: tuple[RunVector, ...], next_after: str | None) dataclass

A bounded page of the vector record.

Parameters:

  • run_id (str) –

    Run whose record was read.

  • vectors (tuple[RunVector, ...]) –

    Ordered bounded summaries; use Run.vector() for complete content.

  • next_after (str | None) –

    Cursor for the next page, or None at the end.

SourceForgeIdentity(*, provider: str, repository: str) dataclass

Repository identity owned by one source-code adapter.

Parameters:

  • provider (str) –

    Opaque registered source provider identifier.

  • repository (str) –

    Opaque repository identity interpreted by that provider.

StackRunStatus(*, name: str, run_id: str, state: Literal['blocked', 'materializing', 'queued', 'provisioning', 'running', 'cancelling', 'succeeded', 'failed', 'cancelled', 'expired'], needs: tuple[str, ...], source_branch: str | None, source_revision: str | None, ready_at: str | None, queue_expires_at: str | None, terminal_at: str | None, waiting_reason: str | None, error_code: str | None) dataclass

Current lifecycle projection for one run in a hosted stack.

Parameters:

  • name (str) –

    Stable symbolic run name from the manifest.

  • run_id (str) –

    Server-assigned public run identity.

  • state (Literal['blocked', 'materializing', 'queued', 'provisioning', 'running', 'cancelling', 'succeeded', 'failed', 'cancelled', 'expired']) –

    Current materialization or run state.

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

    Stable symbolic dependency names.

  • source_branch (str | None) –

    Source branch the run started from once it materializes; in stacked pull-request delivery this is the previous run's pull-request branch, which its pull request targets.

  • source_revision (str | None) –

    Exact source revision once the run materializes.

  • ready_at (str | None) –

    RFC 3339 time when source materialization completed and the run became ready.

  • queue_expires_at (str | None) –

    RFC 3339 per-run queue deadline, set to the earlier of the stack deadline and seven days after readiness.

  • terminal_at (str | None) –

    RFC 3339 terminal time.

  • waiting_reason (str | None) –

    Stable explanation while queued or blocked, when supplied.

  • error_code (str | None) –

    Stable terminal error category, including dependency_failed.

terminal: bool property

Whether this run can no longer change state.

StackStatus(*, stack_id: str, title: str, state: Literal['queued', 'running', 'succeeded', 'failed', 'cancelled', 'expired'], repository: str, branch: str, submitted_at: str, expires_at: str, runs: tuple[StackRunStatus, ...]) dataclass

Current aggregate projection for an immutable hosted stack.

Parameters:

  • stack_id (str) –

    Server-assigned immutable stack identity.

  • title (str) –

    Human-readable immutable stack title.

  • state (Literal['queued', 'running', 'succeeded', 'failed', 'cancelled', 'expired']) –

    Aggregate stack state.

  • repository (str) –

    Source repository from the submitted manifest, shared by every run.

  • branch (str) –

    Base branch shared by every run.

  • submitted_at (str) –

    RFC 3339 admission time.

  • expires_at (str) –

    RFC 3339 whole-stack deadline.

  • runs (tuple[StackRunStatus, ...]) –

    Stable server-assigned run receipts and their current states.

terminal: bool property

Whether every possible transition for this stack has completed.

succeeded: bool property

Whether every run in the stack was delivered successfully.

TargetRemoveResult(name: str, removed: bool) dataclass

Receipt for removing a local target and its saved access.

Parameters:

  • name (str) –

    Removed target name.

  • removed (bool) –

    True after successful cleanup and registry removal.

RunStatus.steers contains recorded directions and their recorded receiving execution references. Each RunSteer includes a vector ID, recording time, UTF-8 byte length, excerpt, total receiving executions and the 64 most recent references. Its mode is once or standing; optional network metadata retains destination names and the originating node, node instance and execution. RunStatus.omitted_steers reports omitted older steers.