Create an optimization trial record

create_trial() starts a record of one optimizer trial: which optimizer ran and with which parameters. Record the evaluation with complete_trial() and collect records in a TrialLog. You need these only when writing your own optimizer; the built-in optimizers create trials themselves.

Usage

create_trial(
  optimizer_name,
  params = list(),
  trial_id = NULL,
  notes = "",
  trace_context = list()
)

Arguments

optimizer_name

Name of the optimizer.

params

Named list of the parameters tried.

trial_id

Optional trial ID. NULL (the default) generates one from the time and a random suffix.

notes

Optional note.

trace_context

A named, JSON-compatible list of correlation fields. When omitted inside compile(), the compilation's context is used; supply list() to clear it.

Value

A trial record (a Trial S7 object) with status "pending".

See also

Other optimizer building blocks: TrialLog, complete_trial(), eval_program(), load_trial_log(), optimizer_control(), read_trials_jsonl(), sample_dataset(), split_dataset(), write_trials_jsonl()

Examples

trial <- create_trial(
  optimizer_name = "my-search",
  params = list(max_bootstrapped_demos = 4L, instructions = "Be brief.")
)
trial
#> 
#> ── Trial: trial_20260930_174401_ncnyz0 
#> • Status: pending
#> Optimizer: my-search
#> Params: max_bootstrapped_demos, instructions
#> Started: 2026-09-30 17:44:01