spdl.autoresearch.core.WorkflowSpec

class WorkflowSpec(*args, **kwargs)

Pluggable workflow contract returned by a workflow factory.

Combines supervisor-phase metadata (used by the framework to render the supervisor prompt and build the engine command) with engine-phase lifecycle hooks (used to initialise the workdir and build the WorkflowProtocol adapter).

A workflow factory is any callable matching WorkflowFactory that returns a value satisfying this protocol.

Methods

build_workflow(workdir)	Construct the engine-side adapter.
description()	Return free-form domain context for the supervisor.
engine_argv_tail()	Return the workflow-specific flags for the engine command.
setup(workdir)	Perform fresh-run workdir initialisation, idempotent on resume.
supervisor_known_config()	Return key/value pairs for the supervisor's "known config" block.
supervisor_missing_config()	Return human-readable names of required values not yet supplied.

Attributes

max_concurrency

Maximum concurrent coroutines the orchestrator should run.

build_workflow(workdir: Path) → WorkflowProtocol

Construct the engine-side adapter.

Called after setup(). The returned object is what the Orchestrator drives.

Parameters:

workdir – Directory the engine will run against.

Returns:

An object satisfying WorkflowProtocol.

description() → str | None

Return free-form domain context for the supervisor.

Describes the workflow domain, the meaning of its config fields, and what happens during a run. The framework joins this with its own supervisor instructions and the launch context (known config, missing config, engine command).

This is NOT the place for supervisor instructions (monitoring, troubleshooting, SIGINT handling, status meanings, queue surgery). Those are framework-owned and identical across every workflow. Use supervisor_known_config() / supervisor_missing_config() for the structured “what to ask the user” surface; use this method for the prose around those bullets — what each field means, what good values look like, what the engine will do with them.

Return None (or an empty string) to contribute nothing.

Returns:

Markdown context, or None.

engine_argv_tail() → list[str]

Return the workflow-specific flags for the engine command.

Appended after the framework’s own arguments when the supervisor builds the engine invocation. The returned list typically encodes domain config such as --build-command or --source-dir.

Returns:

A list of CLI tokens to forward to the engine subprocess.

property max_concurrency: int

Maximum concurrent coroutines the orchestrator should run.

setup(workdir: Path) → None

Perform fresh-run workdir initialisation, idempotent on resume.

Called once at the start of each engine invocation. Workflows detect re-runs internally (for example, by checking for config.json) and should be safe to call repeatedly. Fresh runs typically record the factory spec in the workdir so later commands can re-instantiate the workflow without the original argv.

Parameters:

workdir – Directory the engine will run against.

supervisor_known_config() → dict[str, str]

Return key/value pairs for the supervisor’s “known config” block.

Rendered as a bullet list inside the supervisor prompt so the agent can summarise what is already set. Empty values are still rendered to make missing-but-named fields visible.

Returns:

A mapping of config name to display value.

supervisor_missing_config() → list[str]

Return human-readable names of required values not yet supplied.

An empty list signals the workflow is ready to run the engine without further user interaction.

Returns:

A list of missing-config labels (for example, ["pipeline script", "build command"]).