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