`synth_ai.research.swarms`

Alpha client.research.swarms — launch and lifecycle for Managed Swarms. A Managed Swarm is one bounded multi-agent execution under the Managed Research (SMR) umbrella. Swarms launch directly against a project, or are composed by Managed Factories through Efforts. The wire protocol still uses run/run_id; this module is the public noun layer over it.

Functions

`swarm_state_is_terminal`

swarm_state_is_terminal(state: str) -> bool

Return whether a public swarm state string is terminal. Reuses :class:RunState (the same terminal-state source the low-level wait/contract path is projected from) instead of hand-authoring a string set. Unknown states are non-terminal.

`classify_event_kind`

classify_event_kind(kind: str) -> str

Classify a wire event kind into a coarse forward-compatible category. Returns one of "tool", "message", "turn", "usage", "status", or "other". Unknown kinds always classify as "other" so new backend event kinds never break consumers.

Classes

`SwarmPreflightBlockedError`

Raised when launch_and_wait preflight is not clear to trigger. Carries the structured blockers list and the full preflight payload so callers can act on the class of denial rather than a bare message.

`SwarmLaunchBackpressureError`

Raised when swarm launch exhausts its bounded backpressure retries.

`SwarmResult`

Typed outcome of :meth:ResearchSwarmsAPI.launch_and_wait. Methods:

`is_terminal`

is_terminal(self) -> bool

`SwarmRetryResult`

Typed outcome of :meth:ResearchSwarmHandle.retry. Provenance (which swarm this retry came from and why) lives here client-side; the launch wire has no metadata field to carry it.

`ResearchSwarmHandle`

Swarm-scoped readouts and lifecycle (public hero session type). A Managed Swarm is one bounded multi-agent execution. Prefer ResearchSwarmSession in type hints — RunHandle is not part of the public hero surface. Methods:

`swarm_id`

swarm_id(self) -> str

Public swarm identifier (wire transport still calls this run_id).

`wait_until_terminal`

wait_until_terminal(self, timeout: float, poll_interval: float = 10.0) -> ResearchSwarm

Block until the swarm reaches a terminal state (thin over wait). Args:

timeout: Max seconds to wait; the operator owns the wall clock.
poll_interval: Seconds between status polls.

Returns:

class:ResearchSwarm public state model.

`is_terminal`

is_terminal(self) -> bool

Return whether the swarm has reached a terminal state. Uses the backend run contract’s terminal flag — the same authority the low-level wait loop polls.

`retry`

retry(self, mode: Literal['from_checkpoint', 'fresh'] = 'fresh') -> SwarmRetryResult

Retry a terminal swarm, either fresh or branched from a checkpoint. Args:

mode: "fresh" re-launches the project’s configured swarm; "from_checkpoint" branches from an existing checkpoint.
reason: Optional operator reason, recorded client-side on the result (and on the branch request for checkpoint retries).
checkpoint_id: Required when mode="from_checkpoint".

Returns:

class:SwarmRetryResult with the new swarm id and handle.

Raises:

ValueError: If the source swarm is not terminal, or the mode / checkpoint arguments are inconsistent.

`progress_snapshot`

progress_snapshot(self) -> Any

Deprecated alias for snapshots.get(detail=...).

`full_progress`

full_progress(self) -> RunObservabilitySnapshot

Return the full observability snapshot (deprecated path — use snapshots.get(detail='full')).

`stream_transcript`

stream_transcript(self) -> Iterator[dict[str, Any]]

Stream transcript event pages for the swarm.

`work_product_content`

work_product_content(self, work_product_id: str) -> str | bytes

Download work product bytes or text by id.

`download_workspace_archive`

download_workspace_archive(self, destination: str) -> dict[str, Any]

Deprecated alias for workspace.download.

`list_artifacts`

list_artifacts(self) -> List[dict[str, Any]]

Deprecated alias for artifacts.list.

`ResearchSwarmsAPI`

Public Managed Swarm methods (alpha must-have). Methods:

`runbook_presets`

runbook_presets(self) -> tuple[ResearchRunbookPreset, ...]

Return supported runbook presets for swarms.create.

`check_preflight`

check_preflight(self, project_id: str | None = None, **kwargs: Any) -> dict[str, Any]

Validate a launch request before starting a swarm. Call after projects.setup.prepare to surface blockers (missing repo, secrets, budget caps) without creating a swarm record. Returns:

Preflight payload with allowed flag and structured denials.

`launch_and_wait`

launch_and_wait(self, project_id: str | None = None, **launch_kwargs: Any) -> SwarmResult

Preflight, launch, and wait for a swarm in one call (hero flow). Runs check_preflight first and fails immediately with a typed :class:SwarmPreflightBlockedError when not clear to trigger. Launch is wrapped in a bounded backpressure retry (HTTP 502/503/504 and concurrent-run-limit backpressure, max 5 attempts, capped backoff); other errors raise immediately. Then blocks until terminal and assembles a typed :class:SwarmResult. Args:

project_id: Owning project id.
objective: Primary operator message (objective launch path). When omitted, the project’s configured swarm is triggered.
timeout: REQUIRED max seconds to wait for terminal state — the operator owns the wall clock; there is no wait-forever default.
poll_interval: Seconds between status polls.
raise_if_failed: Raise when the swarm ends failed/blocked.
**launch_kwargs: Any launch-request field the backend accepts (execution_target, local_execution, limit, …).

Returns:

class:SwarmResult with final state, usage, cost, work products,
and a live handle for further readouts.

`launch_preflight`

launch_preflight(self, project_id: str | None = None, **kwargs: Any) -> dict[str, Any]

Deprecated alias for check_preflight.

`create`

create(self, project_id: str | None = None, **kwargs: Any) -> ResearchSwarmHandle | dict[str, Any]

Launch a Managed Swarm. When objective is provided, returns a :class:ResearchSwarmHandle. Objective-less calls retain their historical raw response. Use :meth:create_configured for a typed configured-swarm launch. Args:

project_id: Owning project id.
objective: Primary operator message for the swarm (preferred launch path).

Returns:

A typed handle for objective launches, otherwise the legacy raw payload.

`create_configured`

create_configured(self, project_id: str | None = None, **kwargs: Any) -> ResearchSwarmHandle

Launch the project’s configured swarm and return a typed handle.

`start`

start(self, objective: str, **kwargs: Any) -> ResearchSwarmHandle

Start a swarm with a primary objective message (deprecated — use create).

`launch`

launch(self, objective: str, **kwargs: Any) -> ResearchSwarmHandle

Deprecated alias for create with a required objective.

`trigger`

trigger(self, project_id: str | None = None, **kwargs: Any) -> dict[str, Any]

Compatibility alias for existing ReportBench drivers.

`start_run`

start_run(self, project_id: str | None = None, **kwargs: Any) -> dict[str, Any]

Deprecated alias for configured-swarm launch (prefer create).

`get`

get(self, *args: str) -> ResearchSwarmHandle

Open a swarm-scoped session handle for readouts and lifecycle control. Accepts (project_id, swarm_id), (swarm_id,) when project is implied, or keyword forms. Prefer nested readouts on the returned handle: handle.usage.get(), handle.snapshots.get(), handle.transcript.get().

`open`

open(self, *args: str) -> ResearchSwarmHandle

Open a swarm session (alias for get).

`state`

state(self, swarm_id: str) -> ResearchSwarm

Return the public swarm state model without opening a full session handle.

`public_state`

public_state(self, swarm_id: str) -> ResearchSwarm

Return the public swarm state model without opening a full session handle.

`list`

list(self, project_id: str, **kwargs: Any) -> List[dict[str, Any]]

List swarms for a project (newest first).

`list_active`

list_active(self, project_id: str, **kwargs: Any) -> List[dict[str, Any]]

Return active swarms for a project (eval-compat name).

`wait`

wait(self, project_id: str | None = None, swarm_id: str | None = None) -> ResearchSwarm

Block until a swarm reaches a terminal state. Args:

timeout: Max seconds to wait (None waits indefinitely).
poll_interval: Seconds between status polls.
raise_if_failed: Raise when the swarm ends in a failed state.

Returns:

Final ResearchSwarm public state model.

`transcript`

transcript(self, swarm_id: str) -> dict[str, Any]

Fetch a transcript page for a swarm (prefer handle.transcript.get).

`stream_events`

stream_events(self, swarm_id: str) -> Iterator[RunRuntimeStreamEvent]

Stream runtime events for a swarm (prefer handle.events.stream).

`resource_limits`

resource_limits(self, swarm_id: str) -> SmrResourceLimits

Return configured resource limits for the swarm.

`progress_toward_resource_limits`

progress_toward_resource_limits(self, swarm_id: str) -> SmrResourceLimitProgress

Return progress toward resource limits for the swarm.

`stop`

stop(self, swarm_id: str) -> ManagedResearchRunControlAck

Request graceful stop for a swarm.

`pause`

pause(self, swarm_id: str) -> ManagedResearchRunControlAck

Pause an active swarm.

`resume`

resume(self, swarm_id: str) -> ManagedResearchRunControlAck

Resume a paused swarm.

`results`

results(self, project_id: str, swarm_id: str) -> dict[str, Any]

Return final swarm results when execution completes.

`logs`

logs(self, project_id: str, swarm_id: str) -> dict[str, Any]

List structured log records for a swarm.

`logs_page`

logs_page(self, project_id: str, swarm_id: str) -> SyncPage[dict[str, Any]]

Fetch a paginated page of swarm logs. Returns:

SyncPage with items, next_cursor, and has_more for
cursor-based iteration without hand-parsing wire payloads.

`execution`

execution(self, project_id: str, swarm_id: str, **kwargs: Any) -> Any

Return orchestrator execution metadata for a swarm.

`orchestrator`

orchestrator(self, project_id: str, swarm_id: str) -> dict[str, Any]

Return orchestrator state for a swarm (actors, phases, checkpoints).

​synth_ai.research.swarms

​Functions

​swarm_state_is_terminal

​classify_event_kind

​Classes

​SwarmPreflightBlockedError

​SwarmLaunchBackpressureError

​SwarmResult

​is_terminal

​SwarmRetryResult

​ResearchSwarmHandle

​swarm_id

​wait_until_terminal

​is_terminal

​retry

​progress_snapshot

​full_progress

​stream_transcript

​work_product_content

​download_workspace_archive

​list_artifacts

​ResearchSwarmsAPI

​runbook_presets

​check_preflight

​launch_and_wait

​launch_preflight

​create

​create_configured

​start

​launch

​trigger

​start_run

​get

​open

​state

​public_state

​list

​list_active

​wait

​transcript

​stream_events

​resource_limits

​progress_toward_resource_limits

​stop

​pause

​resume

​results

​logs

​logs_page

​execution

​orchestrator

`synth_ai.research.swarms`

Functions

`swarm_state_is_terminal`

`classify_event_kind`

Classes

`SwarmPreflightBlockedError`

`SwarmLaunchBackpressureError`

`SwarmResult`

`is_terminal`

`SwarmRetryResult`

`ResearchSwarmHandle`

`swarm_id`

`wait_until_terminal`

`is_terminal`

`retry`

`progress_snapshot`

`full_progress`

`stream_transcript`

`work_product_content`

`download_workspace_archive`

`list_artifacts`

`ResearchSwarmsAPI`

`runbook_presets`

`check_preflight`

`launch_and_wait`

`launch_preflight`

`create`

`create_configured`

`start`

`launch`

`trigger`

`start_run`

`get`

`open`

`state`

`public_state`

`list`

`list_active`

`wait`

`transcript`

`stream_events`

`resource_limits`

`progress_toward_resource_limits`

`stop`

`pause`

`resume`

`results`

`logs`

`logs_page`

`execution`

`orchestrator`