Runs

zeroth.runtime.runs

Run and thread domain contracts.

This package is the canonical import location for the run domain: the models that describe a run and its thread, and the narrow repository protocols the runtime executes against. Concrete persistence lives outside the runtime and is injected through these protocols.

ConditionResultRecorder

Saves condition evaluation results onto a Run for later inspection.

Use this after branch resolution to persist the results so you can see exactly why each branch was taken or suppressed.

record

record(run: Run, result: RunConditionResult) -> Run

Append a single condition result to the run and update its timestamp.

record_many

record_many(
    run: Run, results: Iterable[RunConditionResult]
) -> Run

Append multiple condition results to the run at once and update its timestamp.

Run

Bases: RunState

A single execution of a graph (workflow).

Extends the vendored RunState with Zeroth-specific fields like execution history, node visit counts, and condition results. Each run belongs to a thread and tracks its progress from start to finish.

RunConditionResult

Bases: BaseModel

A record of a condition (branching decision) that was evaluated during a run.

When a graph has conditional edges, this captures which condition was checked, whether it matched, and which edge was selected. The run domain republishes it as part of the persisted run surface.

RunFailureState

Bases: BaseModel

Details about why a run failed.

When a run ends in an error, this stores the reason and any extra details so you can figure out what went wrong.

RunHistoryEntry

Bases: BaseModel

A record of one node's execution within a run.

Each time a node runs (or retries), a new entry is added to the run's execution history. This captures what went in, what came out, and when it happened.

RunState

Bases: BaseModel

touch

touch() -> None

Touch.

Thread

Bases: BaseModel

A container that groups related runs together over time.

Think of a thread like a conversation: each message exchange is a "run", and the thread ties them all together. It also tracks which agents participated, any saved checkpoints, and attached memory.

ThreadMemoryBinding

Bases: BaseModel

A reference linking a thread to a memory instance.

Threads can have memory (like a scratchpad) attached to them. This binding says which memory connector and instance to use.

ThreadStatus

Bases: StrEnum

Lifecycle states for a thread.

A thread starts as ACTIVE, moves to COMPLETED when all its work is done, and can be ARCHIVED when it's no longer needed but you want to keep it.

CheckpointStore

Bases: Protocol

Snapshot run state so an interrupted execution can resume.

write_checkpoint async

write_checkpoint(run: Run) -> str

Save a snapshot of the run and return the checkpoint ID.

get_checkpoint async

get_checkpoint(checkpoint_id: str) -> Run | None

Load a checkpoint by its ID.

RunReader

Bases: Protocol

Load persisted runs by identity.

get async

get(run_id: str) -> Run | None

Load a run by its ID, or return None if not found.

RunWriter

Bases: Protocol

Persist runs as execution progresses.

create async

create(run: Run) -> Run

Save a new run and return the persisted version.

put async

put(run: Run) -> Run

Save (insert or update) a run and return the persisted version.

put_if_status async

put_if_status(run: Run, expected_status: RunStatus) -> Run

Save a run only while its persisted status matches the snapshot.

ThreadStore

Bases: Protocol

Resolve and update the thread that groups a sequence of runs.

get async

get(thread_id: str) -> Thread | None

Load a thread by its ID, or return None if not found.

resolve async

resolve(
    thread_id: str | None,
    *,
    graph_version_ref: str,
    deployment_ref: str,
    participating_agent_refs: Sequence[str] | None = None,
    state_snapshot_refs: Sequence[str] | None = None,
    checkpoint_refs: Sequence[str] | None = None,
    memory_bindings: Sequence[ThreadMemoryBinding]
    | None = None,
    run_id: str | None = None,
    status: ThreadStatus | None = None,
) -> Thread

Find or create a thread, merging in any new data.