Research Factory Quickstart

This walkthrough creates one private Factory for a bounded Craftax policy experiment. Craftax is the example, not the product boundary: the same loop works for any objective with an explicit baseline, metric, evaluator, workspace, budget, and stopping condition.

This guide targets synth-ai[research] 0.16.0 and is bound to release source c98f5faa. Publish it only with the matching package release and backend Factory routes.

1. Install and authenticate

uv add "synth-ai[research]==0.16.0"
export SYNTH_API_KEY="sk_..."
export SYNTH_RESEARCH_PROJECT_ID="project_..."

2. Define bounded work

import os
from datetime import datetime, timezone

from synth_ai import SynthClient

client = SynthClient()
research = client.research
control = research.session

project = research.projects.get(os.environ["SYNTH_RESEARCH_PROJECT_ID"])

factory = control.factories.create(
    {
        "name": "Craftax policy factory",
        "description": "Beat the baseline on benchmark-owned held-out reward.",
        "budget_policy": {"limit": 25, "currency": "USD", "period": "month"},
        "cap_policy": {"max_active_runs": 1, "max_active_efforts": 1},
        "publication_policy": {"visibility": "private"},
    }
)

control.factories.link_workspace_project(
    factory.factory_id,
    project.project_id,
    display_name="Craftax evaluation workspace",
)

effort = control.factories.create_effort(
    factory.factory_id,
    name="Improve held-out reward",
    hypothesis_or_topic=(
        "Propose one small policy change and accept it only when the held-out "
        "evaluator beats the pinned baseline."
    ),
    effort_type="optimizer",
    recurrence_policy={"cadence": "daily", "max_active_runs": 1},
    next_wake_at=datetime.now(timezone.utc),
)

SYNTH_RESEARCH_PROJECT_ID must identify an existing prepared project whose workspace contains the pinned baseline, evaluator, allowed source, model/provider references, and output path. Runnable-project creation requires the deployment-specific runtime and agent-profile contract; this quickstart does not guess those values. A Factory is not permission to read arbitrary organization resources.

3. Preview, inspect, and confirm

preview = research.factories.preview_wake(factory.factory_id, limit=1)

print("preview:", preview.preview_id)
print("ready:", preview.ready)
print("expires:", preview.preview_expires_at)
for item in preview.efforts:
    print(item.effort_id, item.status, item.reason, item.launch_preview)

if preview.ready != 1:
    raise RuntimeError("Expected exactly one ready experiment; nothing launched")

receipt = research.factories.wake_due(factory.factory_id, preview=preview)
print("receipt:", receipt.receipt_id)
print("confirmed preview:", receipt.confirmed_preview_id)
print("launched:", receipt.launched)

Keep the opaque preview token in process memory. The typed wake_due call replays the preview’s exact request contract and checks the returned receipt.

4. Inspect experiments and outputs

status = research.factories.status(factory.factory_id)

print("next wake:", status.next_wake_at)
print("experiment:", status.experiment_observability)
for run in status.latest_runs:
    print("run:", run.run_id, run.public_state)
for product in status.latest_work_products:
    print("work product:", product.work_product_id, product.title, product.readiness)

Open a WorkProduct in the dashboard from /smr/factories, or through its authenticated content endpoint. Treat a candidate as unaccepted until the configured evaluator records the held-out comparison.

5. Stop safely

Pause the Effort to prevent future wakes. Archive only resources created for this rehearsal after any active run reaches a terminal state:

control.efforts.pause(effort.effort_id)

# After the active run is terminal:
control.efforts.archive_reference(effort.effort_id)
control.factories.archive(factory.factory_id)
research.close()

Pausing a Factory or Effort does not imply that an already-started run was cancelled. Use the run’s explicit stop control when that is required.

REST API equivalent

For an already configured Factory, preview and confirm through the same backend boundary. Keep the opaque token in a shell variable and remove it from displayed output:

export SYNTH_API_KEY="sk_..."
export FACTORY_ID="factory_..."
export SYNTH_API_URL="https://api.usesynth.ai"

preview=$(curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Authorization: Bearer $SYNTH_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"dry_run":true,"limit":1,"continue_on_error":true}' \
  "$SYNTH_API_URL/smr/factories/$FACTORY_ID/wake-due")

printf '%s' "$preview" | jq 'del(.preview_token)'

confirm=$(printf '%s' "$preview" | jq -c '(.request_contract // {}) + {
  dry_run: false,
  confirmed_preview_id: .preview_id,
  confirmed_preview_token: .preview_token
}')

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Authorization: Bearer $SYNTH_API_KEY" \
  --header "Content-Type: application/json" \
  --data "$confirm" \
  "$SYNTH_API_URL/smr/factories/$FACTORY_ID/wake-due" \
  | jq 'del(.preview_token)'

Do not run the confirmation request when ready is zero. Do not write preview, confirm, or shell tracing output to an evidence packet because each contains the opaque token.

MCP equivalent

Ask your MCP client:

Create a private Craftax Research Factory with a $25 monthly budget, one active
run, one daily Effort, and my configured Craftax workspace. Preview exactly one
due experiment and show me the objective, workspace, consequences, expiry, and
ready count. Do not confirm until I approve. After approval, confirm the exact
preview, return the receipt ID, and show the resulting run and WorkProduct.

The client should use smr_preview_factory_wake before smr_wake_due_factory_efforts and must not print the preview token.

Evidence boundary

The SDK examples are source-bound to release candidate c98f5faa. The release packet, not this guide, owns the final wheel hash plus the production Craftax run and WorkProduct receipts. This example does not substitute documentation for those receipts, claim every objective improves, or claim that long-horizon durability clocks are complete.

Getting Started

Managed Research

Stack