Create a research run

The new-run page creates a Research Contract, not merely a form submission. Only a contract that passes server-side preview validation can be created and started. An unfinished draft is saved on the device. You can also copy a previous run's configuration; input files and global model settings are intentionally not copied.

1. Research goal

• Task title — up to 120 characters, used in navigation and export names.
• What should this run establish? — a testable goal that names the object, scope, and desired result.
• Research questions — one per line. They guide the Reasoner but do not replace acceptance criteria.

For example:

Title: Reference ring boundary scan
Goal: Locate the positive-x survival/loss boundary after 128 turns
Question: What interval brackets the transition?

Avoid vague goals such as “study this data”; they do not define a useful stopping condition.

Copy configuration from a previous task copies goal, questions, workflow, capabilities, constraints, acceptance, and budget. Only capabilities still available are retained, and input files are cleared to prevent accidental data reuse.

2. Scientific workflow

These switches add optional completion requirements:

• Enable hypothesis verification permits versioned hypotheses, plans, approvals, verification requests, and results. Runtime rejects those actions when the switch is off.
• Require scientific artifacts for completion requires selected kinds in addition to all metrics: analysis_result, evidence, scientific_claim, hypothesis, verification_plan, verification_result, or scientific_report.
• Require reusable final predictor requires an evaluated model and inference program that obey the declared file-predictor-v1 input/output filenames.

Authorize pipeline selects installed Analysis, Knowledge, Verification, and Report capabilities in one operator action. It does not bypass permission review. CriteriaEngine still owns metric acceptance; artifact completeness is a separate additional gate.

3. Capabilities

Capabilities are grouped into domain experiments, execution/training, evaluation, analysis, knowledge/verification, and reporting/visualization. Selecting one authorizes the Reasoner to call it in this contract. Runtime rejects an unselected capability even when its plugin is installed.

Each card identifies its stable capability name, provider plugin, Core/Domain category, domain, trusted-metric status, scientific artifact flow, and declared output metrics.

Capability constraints is an advanced JSON field. For example, require evaluation datasets to use 128 turns:

{
  "beam.xsuite.generate_stability_dataset": [
    {
      "when": {"dataset_role": "evaluation"},
      "require": {"num_turns": 128}
    }
  ]
}

Each capability maps to a rule array; every rule contains only object-valued when and require. Leave {} when no constraint is needed.

4. Input artifacts

Import up to 20 files. CSV, JSON, and Parquet are classified as DATASET; Python files as source.python; other files as OTHER. Desktop imports bytes into ArtifactStore and does not persist the original host path.

Review name, type, and size. Preview computes a SHA-256, and each input becomes immutable after creation. Cross-action use is by Artifact ID; Runtime verifies run ownership, visibility, and hash before materializing an input into a plugin workspace.

5. Acceptance criteria

At least one criterion is required, and every criterion must be satisfied. Operators are >=, >, <=, <, and ==; one metric can appear only once.

Metric names come from selected capabilities' metric_outputs. Because generated programs may publish ordinary custom metrics through result.json, selecting the local executor also enables a custom metric name.

With Require trusted metric, a value from ordinary code or a solver cannot satisfy the criterion; a plugin declaring trusted_metrics must publish it. For example:

balanced_accuracy >= 0.90, trusted required

This prevents a training program from satisfying model-quality acceptance with its own claim.

6. Research budget

Desktop exposes Actions, Experiments, Failures, Solver calls, Training runs, Training samples, Model calls, and Model tokens. A blank field means “not set,” not zero. Unlimited budget removes every budget ceiling, but does not remove capability, policy, or acceptance checks.

Start with small but workable limits. When a limit is reached, the run becomes BUDGET_EXHAUSTED; its record is preserved, and the Control Room can raise that limit and resume atomically.

YAML also supports wall time, CPU/GPU hours, Reasoner calls/tokens, code generation/repair calls, and repair attempts. See Research configuration.

7. Review and start

Review Research Contract validates:

• goal, metrics, budgets, and file formats;
• enabled capabilities and possible metric producers;
• a trusted producer for each trusted criterion;
• model providers, profiles, and routing;
• workflow, final-predictor, and constraint consistency;
• uploaded file sizes and hashes.

Review plugins, capabilities, every criterion, models, executor, routing, input hashes, and warnings. Start Research first appends immutable RunCreated, then starts the background loop. To create without starting, use CLI new or separate Control API create/start calls.

Revising acceptance

Acceptance cannot change while a run is running. Pause it, then use State → Edit acceptance criteria. Saving creates an auditable revision and immediately reassesses existing evidence. A historical terminal status is not silently rewritten: a successful run that fails revised criteria is labeled as having completed under an earlier criterion.