Skip to main content

​
synth_ai.research.run_readouts

Nested run readout namespaces on ResearchRunHandle.

​
Classes

​
ResearchRunUsageActorsAPI

Per-actor usage breakdown for a run. Methods:

​
get 

get(self) -> SmrRunActorUsage
Return token and cost usage grouped by runtime actor.

​
ResearchRunUsageCostAPI

Run-level cost summary readouts. Methods:

​
get 

get(self) -> SmrRunCostSummary
Return aggregated cost fields for the run.

​
ResearchRunUsageLimitsAPI

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).

​
ResearchRunUsageAPI

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

​
actors 

actors(self) -> ResearchRunUsageActorsAPI
Per-actor usage slice.

​
cost 

cost(self) -> ResearchRunUsageCostAPI
Run cost summary slice.

​
limits 

limits(self) -> ResearchRunUsageLimitsAPI
Resource limit and progress slice.

​
get 

get(self) -> SmrRunUsage
Return canonical usage totals for the run.

​
ResearchRunProgressAPI

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

​
get 

get(self) -> dict[str, Any]
Return coarse progress fields (phase, percent, status text).

​
ResearchRunSnapshotsAPI

Observability snapshots (control vs full detail). Methods:

​
get 

get(self) -> Any
Return an observability snapshot for the run. Args:
  • detail: "control" for operator dashboard fields or "full" for the expanded observability projection.

​
ResearchRunEventsObjectivesAPI

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.

​
ResearchRunEventsTasksAPI

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.

​
ResearchRunEventsAPI

Structured and streaming runtime events for a run. Methods:

​
objectives 

objectives(self) -> ResearchRunEventsObjectivesAPI
Objective-scoped event list.

​
tasks 

tasks(self) -> ResearchRunEventsTasksAPI
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.

​
ResearchRunTasksAPI

Task summaries attached to a run. Methods:

​
list 

list(self) -> List[Any]
List task summaries for the run. Args:
  • kind: Optional task kind filter.
  • limit: Maximum summaries to return.

​
ResearchRunMessageQueueMessagesAPI

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.

​
ResearchRunMessageQueueThreadsAPI

Message queue threads for operator steering. Methods:

​
list 

list(self) -> List[Any]
List message queue threads for the run.

​
ResearchRunMessageQueueInteractionsAPI

Pending and completed message queue interactions. Methods:

​
list 

list(self) -> List[Any]
List interactions, optionally filtered by status.

​
ResearchRunMessageQueueAPI

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

​
messages 

messages(self) -> ResearchRunMessageQueueMessagesAPI
Outbound messages API.

​
threads 

threads(self) -> ResearchRunMessageQueueThreadsAPI
Thread listing API.

​
interactions 

interactions(self) -> ResearchRunMessageQueueInteractionsAPI
Interaction listing API.

​
ResearchRunRuntimeMessagesAPI

Runtime messages visible to operators and viewers. Methods:

​
list 

list(self) -> List[dict[str, Any]]
List runtime messages for the run. 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.

​
ResearchRunTranscriptAPI

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.

​
ResearchRunMilestonesAPI

Run-scoped milestone readouts. Methods:

​
list_primary_parent 

list_primary_parent(self) -> List[dict[str, Any]]
List primary parent milestones linked to the run.

​
ResearchRunWorkProductsContentAPI

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.

​
ResearchRunTrainedModelsAPI

Trained model artifacts produced by a run. Methods:

​
list 

list(self) -> List[Any]
List trained models registered for the run.

​
ResearchRunWorkProductsEvalPackagesAPI

Container eval packages attached to run work products. Methods:

​
list 

list(self) -> List[Any]
List eval packages exported from the run workspace.

​
ResearchRunWorkProductsAPI

Work products and derived outputs from a run. Methods:

​
content 

content(self) -> ResearchRunWorkProductsContentAPI
Download work product bodies.

​
eval_packages 

eval_packages(self) -> ResearchRunWorkProductsEvalPackagesAPI
List container eval packages.

​
list 

list(self) -> List[Any]
List work product metadata for the run.

​
ResearchRunArtifactsManifestAPI

Artifact manifest for a run. Methods:

​
get 

get(self) -> Any
Return the artifact manifest describing available run outputs.

​
ResearchRunArtifactsContentAPI

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.

​
ResearchRunArtifactsAPI

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

​
manifest 

manifest(self) -> ResearchRunArtifactsManifestAPI
Artifact manifest API.

​
content 

content(self) -> ResearchRunArtifactsContentAPI
Artifact content download API.

​
list 

list(self) -> List[Any]
List artifacts for the run with optional type filter.

​
ResearchRunResultsAPI

Final run results and outcome payload. Methods:

​
get 

get(self) -> dict[str, Any]
Return the run results document when execution has finished.

​
ResearchRunLogsAPI

Structured run logs for debugging and audit. Methods:

​
list 

list(self) -> dict[str, Any]
List log records with optional cursor pagination.

​
ResearchRunOrchestratorAPI

Orchestrator state and routing metadata for a run. Methods:

​
get 

get(self) -> dict[str, Any]
Return orchestrator readouts for the run.

​
ResearchRunWorkspaceAPI

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.

​
ResearchRunCodeAPI

Run code archive download. Methods:

​
download 

download(self, path: str) -> dict[str, Any]
Download run code to the given local path.

​
ResearchRunActorsAPI

Runtime actor inventory for a run. Methods:

​
list 

list(self) -> dict[str, Any]
List actors participating in the run.

​
ResearchRunEvidenceAPI

Operator evidence bundle for debugging run behavior. Methods:

​
get 

get(self) -> dict[str, Any]
Return operator evidence with optional per-section limits.

​
ResearchRunAuthorityAPI

Authority and permission readouts for operators. Methods:

​
get 

get(self) -> Any
Return authority readouts for the run. Args:
  • include_runtime_authority: Include live runtime authority fields when available.

​
ResearchRunExecutionAPI

Execution state and worker routing for a run. Methods:

​
get 

get(self, **kwargs: Any) -> Any
Return execution readouts for the run.

​
ResearchRunTickingAPI

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

​
get 

get(self) -> Any
Return current ticking state for the run.

​
set 

set(self, update: Any = None, **kwargs: Any) -> Any
Update ticking configuration for the run.

​
ResearchRunReadoutsMixin

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

​
usage 

usage(self) -> ResearchRunUsageAPI
Usage, cost, and limit readouts.

​
progress 

progress(self) -> ResearchRunProgressAPI
Coarse progress for polling UIs.

​
snapshots 

snapshots(self) -> ResearchRunSnapshotsAPI
Observability snapshots (control or full).

​
events 

events(self) -> ResearchRunEventsAPI
Structured and streaming runtime events.

​
tasks 

tasks(self) -> ResearchRunTasksAPI
Task summaries for the run.

​
message_queue 

message_queue(self) -> ResearchRunMessageQueueAPI
Operator message queue threads and outbound messages.

​
messages 

messages(self) -> ResearchRunRuntimeMessagesAPI
Runtime messages visible to operators.

​
transcript 

transcript(self) -> ResearchRunTranscriptAPI
Transcript pages with optional cursor pagination.

​
work_products 

work_products(self) -> ResearchRunWorkProductsAPI
Work products produced by the run.

​
trained_models 

trained_models(self) -> ResearchRunTrainedModelsAPI
Trained models registered for the run.

​
artifacts 

artifacts(self) -> ResearchRunArtifactsAPI
Run artifacts listing and download.

​
results 

results(self) -> ResearchRunResultsAPI
Final run results when execution completes.

​
logs 

logs(self) -> ResearchRunLogsAPI
Structured run logs.

​
orchestrator 

orchestrator(self) -> ResearchRunOrchestratorAPI
Orchestrator readouts for the run.

​
workspace 

workspace(self) -> ResearchRunWorkspaceAPI
Run workspace archive download.

​
code 

code(self) -> ResearchRunCodeAPI
Run code archive download.

​
actors 

actors(self) -> ResearchRunActorsAPI
Runtime actor inventory.

​
evidence 

evidence(self) -> ResearchRunEvidenceAPI
Operator evidence bundle for debugging.

​
authority 

authority(self) -> ResearchRunAuthorityAPI
Authority and permission readouts.

​
execution 

execution(self) -> ResearchRunExecutionAPI
Execution state readouts.

​
milestones 

milestones(self) -> ResearchRunMilestonesAPI
Run-scoped milestone readouts.

​
ticking 

ticking(self) -> ResearchRunTickingAPI
Run ticking / heartbeat controls.