spdl.autoresearch.core.WorkflowProtocol

class WorkflowProtocol(*args, **kwargs)

Protocol for domain-specific adapters that drive the work engine.

Implementations must provide load, checkpoint, make_coro, on_result, and summarize.

Methods

checkpoint(queued, running, status)	Persist the current scheduler state.
load()	Return the initial list of work specs to process.
make_coro(spec)	Create the coroutine that executes a work spec.
on_result(spec, result)	Process a completed result and return specs to enqueue.
summarize(workdir)	Return a human-readable summary of the workdir state.

checkpoint(queued: list[TaskSpec], running: list[TaskSpec], status: str) → None

Persist the current scheduler state.

Called on every engine loop iteration and on interruption. status is one of "running", "stopped", or "interrupted".

load() → list[TaskSpec]

Return the initial list of work specs to process.

Called once at the start of Orchestrator.run when no initial_specs are provided. Typically reads from a checkpoint file to resume interrupted work.

make_coro(spec: TaskSpec) → Coroutine[Any, Any, TaskResult]

Create the coroutine that executes a work spec.

The returned coroutine is scheduled as an asyncio.Task. It should return a TaskResult whose children field contains any follow-up specs to enqueue.

async on_result(spec: TaskSpec, result: TaskResult) → list[TaskSpec]

Process a completed result and return specs to enqueue.

Called after a work coroutine finishes. The adapter can filter duplicates, update persistent state, or transform the result’s children before they enter the priority queue.

summarize(workdir: Path) → str

Return a human-readable summary of the workdir state.

Required. Must be safe to call at any time — before any run, in the middle of a run, after a paused or interrupted run, and after a clean exit. The framework calls this method to handle autoresearch summary <wd> invocations on demand and writes the result to <wd>/report.md automatically when the engine exits cleanly.

Implementations should render the summary deterministically from durable workdir state (master tables, summary files, recorded failures), without invoking long-running operations such as coding-agent calls.