Research Factories

Define bounded recurring experiments, confirm due work, and inspect durable outputs.

A Factory is the parent operating unit for repeated Managed Research work. An Effort is one recurring line of inquiry inside it. Each confirmed wake produces at most the reviewed work and returns a receipt that binds the execution to its preview.

Core objects

Object	Responsibility
Factory	Objective, lifecycle, budget, active-work caps, workspace links, and output projection
Effort	Hypothesis or topic, project, cadence, next wake, run kind, and decision state
Preview	Ready work, immutable preview identity, resolved request contract, consequences, and expiry
Receipt	Confirmed preview identity, execution time, launched/skipped/failed counts, and run identities
Experiment	Comparable execution and evaluation evidence under the Factory objective
Result	The public object a Factory produces — report, prompt, policy, dataset, model, artifact, or code change — with optional evaluation and current-best selection
WorkProduct	The durable content that backs a Result; the Result id is the WorkProduct id

Preview and confirmation

Use the public Research namespace to keep the confirmation token in memory and out of logs:

from synth_ai import SynthClient

research = SynthClient().research

preview = research.factories.preview_wake(factory_id, limit=1)
if preview.ready:
    receipt = research.factories.wake_due(factory_id, preview=preview)
    print(receipt.receipt_id, receipt.confirmed_preview_id)

Do not reconstruct the confirmation request from mutable local state. Pass the typed preview object back to wake_due; the SDK replays its exact request_contract and verifies that the returned receipt is bound to the same preview.

If preview.ready == 0, do not confirm. Inspect its reasons, next wake, budget, capacity, or workspace state and take the named recovery action.

Results

A Factory produces Results — the objects directly valuable to you: reports, prompts, policies, datasets, models, artifacts, and draft code changes. Each Result is backed by a durable WorkProduct, and the Result id is the WorkProduct id.

research = SynthClient().research

for result in research.factories.results.list(factory_id):
    print(result.result_id, result.kind, result.readiness, result.title)

result = research.factories.results.get(factory_id, result_id)

Filter the listing by Effort, run, kind, readiness, evaluation status, or current-best state. Ordinary Results carry evaluation = None and selection = None; they need no optimization vocabulary.

Optional: evaluation and current best

When a Factory hillclimbs against a benchmark, a Result can carry a benchmark-owned evaluation and be selected as the current best for a named objective. A Factory that is not optimizing never needs this.

# Attach a benchmark-owned grade to a Result
research.factories.results.evaluate(
    factory_id,
    result_id,
    evaluation=grading_record,
)

# Mark a passing Result as current best for a named objective/scope
research.factories.results.select_current_best(
    factory_id,
    result_id=result_id,
    scope="banking77_accuracy",
    reason="highest passing held-out score",
)

# Append-only current-best history
for event in research.factories.results.list_selection_events(factory_id):
    print(event.action, event.result_id, event.scope, event.score)

Selecting another passing Result changes current-best state without deleting or rewriting the earlier Result; restore_current_best re-selects a prior Result. The research.factories.candidates and research.factories.champions namespaces remain as legacy compatibility surfaces over the same backend authority — new code should use Results.

Cadence, concurrency, and budget

The dashboard supports continuous (minimum 15 minutes), hourly, daily, and weekly cadence choices. Factory caps bound active runs and active Efforts; budget policy bounds spend. The backend remains authoritative when an account, workspace, provider, or runtime has a stricter limit.

The first Effort wake can be due immediately. Later wakes follow the stored recurrence policy. Overlap is off by default; turn it on only when experiments are independent and the additional concurrency is intentional.

For every standing or 24/7 Factory, set all three controls together: budget_policy.limit bounds the Factory window, budget_policy.ordinary_run_limit_usd bounds each ordinary run, and cap_policy.max_active_runs bounds concurrent exposure. Spend enforcement is reactive to metering reports, so these controls limit—but cannot eliminate—the in-flight overspend window.

Failure, retry, and recovery

• A preview is not evidence that execution succeeded.
• An expired or mismatched preview must be replaced with a new preview; never reuse or edit its opaque token.
• Structured denials name the resource or policy that prevented launch.
• Retry the same typed boundary only when the error says it is retryable.
• A committed run must be recovered through its idempotency and receipt authority, not recreated through another service or persistence layer.
• Pause an Effort or Factory to stop future wakes. Use run controls separately when an already-started run must be cancelled.

Privacy and support

Factory objectives, workspace bindings, preview tokens, and private outputs are organization-scoped control-plane data. Never put preview tokens, credentials, or private artifact contents in evidence packets or support messages.

For support, include the Factory ID, Effort ID, receipt ID, run ID, timestamp, and structured error code. Do not include the preview token or API key.

MCP tools

The focused workflow uses:

• smr_create_factory, smr_link_factory_workspace_project, and smr_create_effort;
• smr_preview_factory_wake and smr_wake_due_factory_efforts;
• smr_get_factory_status and smr_list_factory_efforts;
• smr_list_factory_results and smr_get_factory_result to read Results, with smr_evaluate_factory_result, smr_select_factory_result_current_best, smr_restore_factory_result_current_best, and smr_list_factory_result_selection_events for the optional evaluation and current-best flow; and
• smr_pause_effort, smr_resume_effort, smr_pause_factory, and smr_archive_factory.

The preview operation may share a write-capable authorization scope when the backend dry-run updates scheduler metadata. Treat the exact published MCP tool scope as authoritative; do not infer read-only semantics from the word “preview.”

Next

• Research Factory Quickstart
• Python SDK Quickstart
• MCP Quickstart
• Usage and Budgets