`synth_ai.research.swarm_readouts`

Nested run readout namespaces on ResearchSwarmHandle.

Classes

`ResearchSwarmUsageActorsAPI`

Per-actor usage breakdown for a swarm. Methods:

`get`

get(self) -> SmrRunActorUsage

Return token and cost usage grouped by runtime actor.

`ResearchSwarmUsageCostAPI`

Run-level cost summary readouts. Methods:

`get`

get(self) -> SmrRunCostSummary

Return aggregated cost fields for the swarm.

`ResearchSwarmUsageLimitsAPI`

Org and run resource limit readouts. Methods:

`get`

get(self) -> SmrResourceLimits

Return configured resource limits applicable to the run.

`progress`

progress(self) -> SmrResourceLimitProgress

Return progress toward resource limits (tokens, spend, concurrency).

`ResearchSwarmUsageAPI`

Token, cost, and limit readouts for a swarm. Methods:

`actors`

actors(self) -> ResearchSwarmUsageActorsAPI

Per-actor usage slice.

`cost`

cost(self) -> ResearchSwarmUsageCostAPI

Run cost summary slice.

`limits`

limits(self) -> ResearchSwarmUsageLimitsAPI

Resource limit and progress slice.

`get`

get(self) -> SmrRunUsage

Return canonical usage totals for the swarm.

`ResearchSwarmProgressAPI`

High-level progress summary for dashboards and polling loops. Methods:

`get`

get(self) -> dict[str, Any]

Return the backward-compatible raw progress payload.

`get_typed`

get_typed(self) -> ResearchSwarmProgress

Return typed state, phase, stalls, tasks, and recommended actions.

`ResearchSwarmSnapshotsAPI`

Observability snapshots (control vs full detail). Methods:

`get`

get(self) -> Any

Return an observability snapshot for the swarm. Args:

detail: "control" for operator dashboard fields or "full" for the expanded observability projection.

`ResearchSwarmEventsObjectivesAPI`

Objective lifecycle events emitted during a run. Methods:

`list`

list(self) -> dict[str, Any]

List objective events with optional cursor pagination. Args:

limit: Maximum events to return on this page.
cursor: Opaque cursor from a prior response.

Returns:

Event page payload including items and an optional next cursor.

`ResearchSwarmEventsTasksAPI`

Task lifecycle events emitted during a run. Methods:

`list`

list(self) -> dict[str, Any]

List task events with optional cursor pagination. Args:

limit: Maximum events to return on this page.
cursor: Opaque cursor from a prior response.

Returns:

Event page payload including items and an optional next cursor.

`ResearchSwarmEventsAPI`

Structured and streaming runtime events for a swarm. Methods:

`objectives`

objectives(self) -> ResearchSwarmEventsObjectivesAPI

Objective-scoped event list.

`tasks`

tasks(self) -> ResearchSwarmEventsTasksAPI

Task-scoped event list.

`stream`

stream(self) -> Iterator[RunRuntimeStreamEvent]

Stream runtime events over SSE. Args:

transcript_cursor: Resume streaming after this transcript cursor.
view: Projection name (for example "operator").
last_event_id: Resume after this event id when reconnecting.
timeout: Optional read timeout in seconds.

`ResearchSwarmTasksAPI`

Task summaries attached to a run. Methods:

`list`

list(self) -> List[Any]

List task summaries for the swarm. Args:

kind: Optional task kind filter.
limit: Maximum summaries to return.

`ResearchSwarmMessageQueueMessagesAPI`

Outbound operator messages on the run message queue. Methods:

`list`

list(self) -> List[Any]

List queued messages, optionally scoped to a thread.

`send`

send(self, **kwargs: Any) -> dict[str, Any]

Publish a message to the run message queue. Args:

body: Message body text.
**kwargs: Additional wire fields forwarded to the backend.

`ResearchSwarmMessageQueueThreadsAPI`

Message queue threads for operator steering. Methods:

`list`

list(self) -> List[Any]

List message queue threads for the swarm.

`ResearchSwarmMessageQueueInteractionsAPI`

Pending and completed message queue interactions. Methods:

`list`

list(self) -> List[Any]

List interactions, optionally filtered by status.

`ResearchSwarmMessageQueueAPI`

Operator steering via threads, messages, and interactions. Methods:

`messages`

messages(self) -> ResearchSwarmMessageQueueMessagesAPI

Outbound messages API.

`threads`

threads(self) -> ResearchSwarmMessageQueueThreadsAPI

Thread listing API.

`interactions`

interactions(self) -> ResearchSwarmMessageQueueInteractionsAPI

Interaction listing API.

`ResearchSwarmRuntimeMessagesAPI`

Runtime messages visible to operators and viewers. Methods:

`list`

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

List runtime messages for the swarm. Args:

status: Optional delivery or read status filter.
viewer_role: Role used to project the message list.
viewer_target: Optional target id or list of targets.
limit: Maximum messages to return.

`ResearchSwarmTranscriptAPI`

Transcript pages and cursor-based pagination for run events. Methods:

`get`

get(self) -> dict[str, Any]

Fetch a transcript page (use get_page for SyncPage iteration).

`get_page`

get_page(self) -> SyncPage[dict[str, Any]]

Fetch a transcript page wrapped as SyncPage for iteration.

`ResearchSwarmMilestonesAPI`

Swarm-scoped milestone readouts. Methods:

`list_primary_parent`

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

List primary parent milestones linked to the run.

`ResearchSwarmWorkProductsContentAPI`

Fetch work product payload bytes or text. Methods:

`get`

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

Return work product content. Args:

work_product_id: Work product identifier from list.
as_text: When True, decode as UTF-8 text; otherwise return bytes.

`ResearchSwarmTrainedModelsAPI`

Trained model artifacts produced by a run. Methods:

`list`

list(self) -> List[Any]

List trained models registered for the swarm.

`ResearchSwarmWorkProductsEvalPackagesAPI`

Container eval packages attached to run work products. Methods:

`list`

list(self) -> List[Any]

List eval packages exported from the run workspace.

`ResearchSwarmWorkProductsAPI`

Work products and derived outputs from a run. Methods:

`content`

content(self) -> ResearchSwarmWorkProductsContentAPI

Download work product bodies.

`eval_packages`

eval_packages(self) -> ResearchSwarmWorkProductsEvalPackagesAPI

List container eval packages.

`list`

list(self) -> List[ResearchWorkProduct]

List work product metadata for the swarm.

`ResearchSwarmHostedArtifactsAPI`

Hosted artifact receipt and operator actions for a swarm. Methods:

`get`

get(self) -> dict[str, Any]

Return hosted artifact status for this run.

`content`

content(self, hosted_artifact_id: str | None = None) -> str | bytes

Fetch hosted HTML for this run’s artifact.

`publish_public`

publish_public(self, slug: str) -> dict[str, Any]

Promote this run’s hosted artifact to the public index.

`assign_reviewer`

assign_reviewer(self, reason: str) -> dict[str, Any]

Dispatch an artifact_reviewer for this run’s hosted artifact.

`ResearchSwarmArtifactsManifestAPI`

Artifact manifest for a swarm. Methods:

`get`

get(self) -> ResearchArtifactManifest

Return the artifact manifest describing available run outputs.

`ResearchSwarmArtifactsContentAPI`

Download individual run artifacts. Methods:

`get`

get(self, artifact_id: str) -> str | bytes

Return artifact content by id. Args:

artifact_id: Artifact identifier from list or the manifest.
as_text: When True, decode as UTF-8 text; otherwise return bytes.

`ResearchSwarmArtifactsAPI`

Run artifacts listing, manifest, and content download. Methods:

`manifest`

manifest(self) -> ResearchSwarmArtifactsManifestAPI

Artifact manifest API.

`content`

content(self) -> ResearchSwarmArtifactsContentAPI

Artifact content download API.

`list`

list(self) -> List[ResearchArtifact]

List artifacts for the swarm with optional type filter.

`ResearchSwarmResultsAPI`

Final run results and outcome payload. Methods:

`get`

get(self) -> dict[str, Any]

Return the run results document when execution has finished.

`ResearchSwarmLogsAPI`

Structured run logs for debugging and audit. Methods:

`list`

list(self) -> dict[str, Any]

List log records with optional cursor pagination.

`ResearchSwarmOrchestratorAPI`

Orchestrator state and routing metadata for a swarm. Methods:

`get`

get(self) -> dict[str, Any]

Return orchestrator readouts for the swarm.

`ResearchSwarmWorkspaceAPI`

Run workspace archive download. Methods:

`download`

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

Download the run workspace archive to a local path. Args:

destination: Local filesystem path for the archive.
timeout_seconds: Optional download timeout.

`ResearchSwarmCodeAPI`

Run code archive download. Methods:

`download`

download(self, path: str) -> dict[str, Any]

Download run code to the given local path.

`ResearchSwarmActorsAPI`

Runtime actor inventory for a swarm. Methods:

`list`

list(self) -> dict[str, Any]

List actors participating in the run.

`ResearchSwarmEvidenceAPI`

Operator evidence bundle for debugging run behavior. Methods:

`get`

get(self) -> SmrRunOperatorEvidence

Return operator evidence with optional per-section limits.

`ResearchSwarmAuthorityAPI`

Authority and permission readouts for operators. Methods:

`get`

get(self) -> Any

Return authority readouts for the swarm. Args:

include_runtime_authority: Include live runtime authority fields when available.

`ResearchSwarmExecutionAPI`

Execution state and worker routing for a swarm. Methods:

`get`

get(self, **kwargs: Any) -> Any

Return execution readouts for the swarm.

`ResearchSwarmTickingAPI`

Run ticking / heartbeat controls for long-running workloads. Methods:

`get`

get(self) -> Any

Return current ticking state for the swarm.

`set`

set(self, update: Any = None, **kwargs: Any) -> Any

Update ticking configuration for the swarm.

`ResearchSwarmReadoutsMixin`

Lazy nested readout namespaces on :class:ResearchSwarmHandle. Access via handle.usage, handle.progress, handle.snapshots, handle.transcript, handle.message_queue, etc. Methods:

`usage`

usage(self) -> ResearchSwarmUsageAPI

Usage, cost, and limit readouts.

`progress`

progress(self) -> ResearchSwarmProgressAPI

Coarse progress for polling UIs.

`snapshots`

snapshots(self) -> ResearchSwarmSnapshotsAPI

Observability snapshots (control or full).

`events`

events(self) -> ResearchSwarmEventsAPI

Structured and streaming runtime events.

`tasks`

tasks(self) -> ResearchSwarmTasksAPI

Task summaries for the swarm.

`message_queue`

message_queue(self) -> ResearchSwarmMessageQueueAPI

Operator message queue threads and outbound messages.

`messages`

messages(self) -> ResearchSwarmRuntimeMessagesAPI

Runtime messages visible to operators.

`transcript`

transcript(self) -> ResearchSwarmTranscriptAPI

Transcript pages with optional cursor pagination.

`work_products`

work_products(self) -> ResearchSwarmWorkProductsAPI

Work products produced by the run.

`hosted_artifact`

hosted_artifact(self) -> ResearchSwarmHostedArtifactsAPI

Hosted Open Research artifact receipt for the swarm.

`trained_models`

trained_models(self) -> ResearchSwarmTrainedModelsAPI

Trained models registered for the swarm.

`artifacts`

artifacts(self) -> ResearchSwarmArtifactsAPI

Run artifacts listing and download.

`results`

results(self) -> ResearchSwarmResultsAPI

Final run results when execution completes.

`logs`

logs(self) -> ResearchSwarmLogsAPI

Structured run logs.

`orchestrator`

orchestrator(self) -> ResearchSwarmOrchestratorAPI

Orchestrator readouts for the swarm.

`workspace`

workspace(self) -> ResearchSwarmWorkspaceAPI

Run workspace archive download.

`code`

code(self) -> ResearchSwarmCodeAPI

Run code archive download.

`actors`

actors(self) -> ResearchSwarmActorsAPI

Runtime actor inventory.

`evidence`

evidence(self) -> ResearchSwarmEvidenceAPI

Operator evidence bundle for debugging.

`authority`

authority(self) -> ResearchSwarmAuthorityAPI

Authority and permission readouts.

`execution`

execution(self) -> ResearchSwarmExecutionAPI

Execution state readouts.

`milestones`

milestones(self) -> ResearchSwarmMilestonesAPI

Swarm-scoped milestone readouts.

`ticking`

ticking(self) -> ResearchSwarmTickingAPI

Run ticking / heartbeat controls.

​synth_ai.research.swarm_readouts

​Classes

​ResearchSwarmUsageActorsAPI

​get

​ResearchSwarmUsageCostAPI

​get

​ResearchSwarmUsageLimitsAPI

​get

​progress

​ResearchSwarmUsageAPI

​actors

​cost

​limits

​get

​ResearchSwarmProgressAPI

​get

​get_typed

​ResearchSwarmSnapshotsAPI

​get

​ResearchSwarmEventsObjectivesAPI

​list

​ResearchSwarmEventsTasksAPI

​list

​ResearchSwarmEventsAPI

​objectives

​tasks

​stream

​ResearchSwarmTasksAPI

​list

​ResearchSwarmMessageQueueMessagesAPI

​list

​send

​ResearchSwarmMessageQueueThreadsAPI

​list

​ResearchSwarmMessageQueueInteractionsAPI

​list

​ResearchSwarmMessageQueueAPI

​messages

​threads

​interactions

​ResearchSwarmRuntimeMessagesAPI

​list

​ResearchSwarmTranscriptAPI

​get

​get_page

​ResearchSwarmMilestonesAPI

​list_primary_parent

​ResearchSwarmWorkProductsContentAPI

​get

​ResearchSwarmTrainedModelsAPI

​list

​ResearchSwarmWorkProductsEvalPackagesAPI

​list

​ResearchSwarmWorkProductsAPI

​content

​eval_packages

​list

​ResearchSwarmHostedArtifactsAPI

​get

​content

​publish_public

​assign_reviewer

​ResearchSwarmArtifactsManifestAPI

​get

​ResearchSwarmArtifactsContentAPI

​get

​ResearchSwarmArtifactsAPI

​manifest

​content

​list

​ResearchSwarmResultsAPI

​get

​ResearchSwarmLogsAPI

​list

​ResearchSwarmOrchestratorAPI

​get

​ResearchSwarmWorkspaceAPI

​download

​ResearchSwarmCodeAPI

​download

`synth_ai.research.swarm_readouts`

Classes

`ResearchSwarmUsageActorsAPI`

`get`

`ResearchSwarmUsageCostAPI`

`get`

`ResearchSwarmUsageLimitsAPI`

`get`

`progress`

`ResearchSwarmUsageAPI`

`actors`

`cost`

`limits`

`get`

`ResearchSwarmProgressAPI`

`get`

`get_typed`

`ResearchSwarmSnapshotsAPI`

`get`

`ResearchSwarmEventsObjectivesAPI`

`list`

`ResearchSwarmEventsTasksAPI`

`list`

`ResearchSwarmEventsAPI`

`objectives`

`tasks`

`stream`

`ResearchSwarmTasksAPI`

`list`

`ResearchSwarmMessageQueueMessagesAPI`

`list`

`send`

`ResearchSwarmMessageQueueThreadsAPI`

`list`

`ResearchSwarmMessageQueueInteractionsAPI`

`list`

`ResearchSwarmMessageQueueAPI`

`messages`

`threads`

`interactions`

`ResearchSwarmRuntimeMessagesAPI`

`list`

`ResearchSwarmTranscriptAPI`

`get`

`get_page`

`ResearchSwarmMilestonesAPI`

`list_primary_parent`

`ResearchSwarmWorkProductsContentAPI`

`get`

`ResearchSwarmTrainedModelsAPI`

`list`

`ResearchSwarmWorkProductsEvalPackagesAPI`

`list`

`ResearchSwarmWorkProductsAPI`

`content`

`eval_packages`

`list`

`ResearchSwarmHostedArtifactsAPI`

`get`

`content`

`publish_public`

`assign_reviewer`

`ResearchSwarmArtifactsManifestAPI`

`get`

`ResearchSwarmArtifactsContentAPI`

`get`

`ResearchSwarmArtifactsAPI`

`manifest`

`content`

`list`

`ResearchSwarmResultsAPI`

`get`

`ResearchSwarmLogsAPI`

`list`

`ResearchSwarmOrchestratorAPI`

`get`

`ResearchSwarmWorkspaceAPI`

`download`

`ResearchSwarmCodeAPI`

`download`