Research a draft task by task

Inspect and improve each step before freezing and running the complete pipeline.

A registered draft can run one task at a time in a private research workspace. This is useful when you want to inspect an extraction before sending it to a cluster, tune the extraction, and then let the cluster consume only the newest successful result.

Run one task

state = workspace.research("event-recommendations", "v1")

research_run = workspace.run_research_task(
    "event-recommendations",
    "v1",
    "extract-events",
    # Omit sources when these rows already exist in the workspace Space.
    sources={"headlines": sample_headlines},
    sample_size=100,
    sample_seed=7,
    max_cost_usd=2.00,
)

status = workspace.research_run(
    "event-recommendations", "v1", research_run["research_run_id"]
)
preview = workspace.research_task_output(
    "event-recommendations", "v1", "extract-events", limit=50
)

The browser provides the same controls on every draft version. Starting returns a durable research run ID; model work may continue, and you can reconnect later. You can also stop a live run with workspace.stop_research_task(...). Every input Space is capped to the selected sample size. The seed makes the choice reproducible; change it to inspect another hand.

Current results and reruns

Only a successful result becomes current. Rerunning a task successfully replaces the result shown to downstream research. A failed or stopped run leaves the preceding successful result intact. Research history retains cost, duration, status, and row counts.

Improve the draft from evidence

After inspecting a task result, edit the draft through the ordinary UI, SDK node-editing methods, or exported public code. Researchers and coding agents can refine a prompt, exact transformation, normal grouping rule, semantic gate, or task topology. Read the Planner rationale for expected hand sizes, costs, uncertainty, and known failure modes before retaining a preliminary rule. Validate any changed cutoff on a separate hand; a visible sample is evidence to investigate, not proof that a rule is safe.

Automatic second-, third-, or later-shot DAG improvement is experimental rather than a first-class Planner promise. The separate optimization surface remains available after execution and review: it automatically tunes supported runtime parameters and proposes external prompt or parameter changes for explicit admission. Neither research execution nor optimization advice silently mutates a draft.

Dependency order

A downstream task unlocks only after every task that produces its inputs has a current result. Barriers are also respected. If you rerun an upstream task, dependent results become stale and must be rerun before later tasks can proceed. You cannot override an interior Space with uploaded rows; rerun its producer instead.

Research results are isolated

Research rows do not appear as production session output and are never written to connected sinks. The interface shows the version's ordinary logical Space names; experimental storage is not part of your pipeline definition.

Declare when satisfied

Declaration freezes the draft and its research history, then discards experimental rows, logs, relationship evidence, and unused draft prompts. It does not promote experimental data into production. A declared run starts from its bound sources and final prompt bindings. Compatible model-call cache entries remain reusable inside this workspace; sibling workspaces and organizations are fully isolated. Before declaration, researchers may inspect current research output without turning it into pipeline input.