Optimizers

An optimizer proposes candidates (instruction or demo overlays), evaluates them with your metric on your trainset, and keeps the best. compile is the entry point: it takes a module, a training set, and a metric, then searches for better instructions, and in some cases demos, for each Predict leaf. The module is mutated in place: after compile returns, calling the module produces better results with no code changes.

use dspy_rs::{COPRO, Optimizer};

let optimizer = COPRO::builder()
    .breadth(10)
    .depth(1)
    .eval_concurrency(16)
    .build();
optimizer
    .compile(&mut module, examples.clone(), &metric)
    .await?;

All five optimizers are thin strategies over the shared evaluation engine. Candidates are overlays evaluated through a cached, budget-metered, bounded-concurrency fan-out, and winners are installed through the apply_candidate seam. The engine types (EvalEngine, Candidate, Budget, Spend, ParetoView) are documented in Optimizer engine. Step-by-step how-to pages: COPRO, MIPROv2, and GEPA.

The Optimizer trait

#[allow(async_fn_in_trait)]
pub trait Optimizer {
    type Report;

    async fn compile<E, M, MT>(
        &self,
        module: &mut M,
        trainset: Vec<E>,
        metric: &MT,
    ) -> Result<Self::Report>
    where
        E: ToInput<M::Input> + serde::Serialize + Send + Sync,
        M: Module + for<'a> Facet<'a>,
        MT: TypedMetric<E, M>;
}

compile takes exclusive &mut access to the module: no concurrent call() during optimization. The trainset is Vec<E> for any row type that projects into the module’s input via ToInput — a #[derive(Example)] struct, an (Input, Output) tuple, or a hand-written impl; the Serialize bound feeds rollout-cache uids, which content-hash the whole row. All type parameters are inferred from the arguments, so no turbofish is needed: optimizer.compile(&mut module, trainset, &metric). The Facet bound is what lets the optimizer discover Predict leaves by reflection and address them by dotted path. compile returns an error when no optimizable predictors are found, when a metric evaluation fails, or when an LM call fails during candidate evaluation. Each optimizer declares its own Report:

Optimizer	`Report` type
`COPRO`	`()`
`MIPROv2`	`()`
`GEPA`	`GEPAResult`
`SIMBA`	`SimbaReport`
`BootstrapFewShot`	`BootstrapReport`

Choosing an optimizer

Optimizer	Strategy	Needs feedback?	Cost
`BootstrapFewShot`	One-shot demo harvesting from a teacher pass	No	Low (2 × trainset)
`COPRO`	Breadth-first instruction search	No	Low (breadth × depth × trainset)
`SIMBA`	Minibatch introspective ascent (demos + rules)	No	Low (steps × minibatch)
`GEPA`	Genetic-Pareto evolution with feedback	Yes	Medium-high (iterations × eval)
`MIPROv2`	Trace-guided candidate generation	No	Medium (candidates × trials × trainset)

GEPA is the only optimizer that requires textual feedback from the metric. The others use numerical scores alone.

COPRO

Breadth-first instruction search: generates breadth candidate instructions per predictor, evaluates each on the trainset, installs the best, and repeats for depth rounds. The base instruction always competes in every round. How-to: COPRO.

Field	Type	Default	Description
`breadth`	`usize`	`10`	Candidates per round per predictor. Must be greater than 1; `compile` errors otherwise.
`depth`	`usize`	`3`	Optimization rounds; each refines the previous best.
`init_temperature`	`f32`	`1.4`	Currently unused. Reserved for LM-generated candidate diversity.
`track_stats`	`bool`	`false`	Per-round statistics flag. The report type is `()`, so nothing is returned either way.
`prompt_model`	`Option<LM>`	`None`	Separate LM for generating candidate instructions.
`eval_concurrency`	`usize`	`16`	Concurrent LM calls during candidate evaluation.

Cost: approximately breadth × depth × num_predictors × trainset_size LM calls, minus rollout-cache hits. Runs with an unlimited engine budget.

MIPROv2

Trace-guided instruction and demo optimizer. Four phases: one traced teacher pass over the trainset; demo bootstrapping from successful spans via the trace name-join; generation of num_candidates instruction variants per predictor seeded by prompting tips; evaluation of up to num_trials candidates per predictor on one sampled minibatch, keeping the best. Demos are installed before instruction search so candidates are scored against the module as it will actually run. How-to: MIPROv2.

Field	Type	Default	Description
`num_candidates`	`usize`	`10`	Instruction variants generated per predictor.
`num_trials`	`usize`	`20`	Maximum candidates evaluated per predictor. When lower than `num_candidates`, only the first `num_trials` are evaluated.
`minibatch_size`	`usize`	`25`	Examples per candidate evaluation.
`max_bootstrapped_demos`	`usize`	`4`	Demos installed per predictor from successful traces.
`min_demo_score`	`f64`	`0.0`	Minimum whole-program score for a trace to qualify as a demo source.
`eval_concurrency`	`usize`	`16`	Concurrent LM calls during candidate evaluation.
`seed`	`Option<u64>`	`None`	Fixes minibatch sampling. `None` is nondeterministic.

Public helper types: PromptCandidate (an instruction with its evaluated score: f64) and PromptingTips (the rotation of prompting best practices appended to candidates, default_tips() and format_for_prompt()). Public methods on MIPROv2: select_best_traces, create_prompt_candidates, format_schema_fields. The report is ().

GEPA

Genetic-Pareto instruction evolution driven by per-example feedback. Each generation samples a parent proportional to Pareto coverage, re-evaluates it on a trainset minibatch, has a reflection LM (prompt_model) rewrite the instruction from the feedback and the mutated component’s execution trace, then scores the child on the validation columns. Without a prompt_model, mutation degrades to deterministic feedback concatenation. Only instruction space is searched: no demo mutation, no crossover. How-to: GEPA.

GEPA errors if any Eval from the metric has feedback: None. Build metrics with Eval::with_feedback.

Field	Type	Default	Description
`num_iterations`	`usize`	`20`	Evolutionary generations.
`minibatch_size`	`usize`	`25`	Examples per parent re-evaluation within each generation.
`num_trials`	`usize`	`10`	Currently unused. Reserved for multi-child evolution.
`temperature`	`f32`	`1.0`	Currently unused. Reserved for mutation diversity control.
`track_stats`	`bool`	`true`	Record all candidates, evolution history, and frontier history in the result.
`track_best_outputs`	`bool`	`false`	Re-run the best instruction on the eval set and record outputs.
`max_rollouts`	`Option<usize>`	`None`	Hard cap on evaluation rollouts.
`max_lm_calls`	`Option<usize>`	`None`	Hard cap on LM calls (rollouts plus generation).
`prompt_model`	`Option<LM>`	`None`	Reflection LM that rewrites instructions from feedback. Strongly recommended.
`eval_concurrency`	`usize`	`16`	Concurrent LM calls during candidate evaluation.
`seed`	`Option<u64>`	`None`	Fixes minibatch sampling and parent selection.

GEPA additionally exposes compile_with_valset(module, trainset, valset, metric). With Some(valset), initial evaluation and child scoring use the validation set while parent re-evaluation uses trainset minibatches; with None, the trainset serves both roles (this is what compile does).

GEPAResult

Field	Type	Description
`best_candidate`	`GEPACandidate`	Best average score on the Pareto frontier; installed on the module.
`all_candidates`	`Vec<GEPACandidate>`	Every evaluated candidate. Empty unless `track_stats`.
`total_rollouts`	`usize`	Evaluation rollouts consumed.
`total_lm_calls`	`usize`	LM calls consumed (rollouts plus candidate generation).
`evolution_history`	`Vec<(usize, f32)>`	`(generation, best_average_score)` pairs for plotting convergence.
`highest_score_achieved_per_val_task`	`Vec<f32>`	Best score per validation example across all candidates.
`best_outputs_valset`	`Option<Vec<serde_json::Value>>`	Best outputs on the eval set. `Some` only with `track_best_outputs`.
`frontier_history`	`Vec<ParetoStatistics>`	Frontier snapshot per generation (see Optimizer engine).

GEPACandidate carries id, instruction, module_name, example_scores: Vec<f32>, parent_id: Option<usize>, and generation, plus average_score() and mutate(new_instruction, generation).

SIMBA

Stochastic Introspective Mini-Batch Ascent, the cheap agentic default. SIMBA keeps one current program as a candidate overlay and hill-climbs. Each step: sample a seeded trainset minibatch; pick the best and worst rollout of the current program on it (served from engine bookkeeping, no extra rollouts); propose exactly one move; accept it through the engine’s minibatch gate. A child is promoted to a full-trainset evaluation only when its minibatch mean strictly beats the current program’s, so rejected moves never pay for a full pass. The winner is installed when compile returns. The two moves, in order of preference:

Move	Trigger	Effect
`SimbaMove::AppendDemo`	Best rollout scored at least `min_demo_score` and yields new demos	Appends one harvested demo per predictor, capped at `max_demos`, oldest dropped, duplicates skipped.
`SimbaMove::AppendRule`	Otherwise	A reflection LM distills one rule from the best and worst rollouts, appended to the instruction of the predictor with the most spans in the worst rollout. Without `prompt_model`, the worst rollout’s metric feedback is appended verbatim.

Field	Type	Default	Description
`max_steps`	`usize`	`8`	Ascent steps to attempt.
`minibatch_size`	`usize`	`8`	Examples sampled per step.
`max_demos`	`usize`	`4`	Demo-set cap per predictor.
`min_demo_score`	`f64`	`1.0`	Rollout score needed to qualify as a demo source; below it the step falls back to append-rule.
`prompt_model`	`Option<LM>`	`None`	Reflection LM for append-rule moves. Strongly recommended.
`max_metric_calls`	`Option<usize>`	`None`	Hard cap on metric calls (rollouts).
`max_lm_calls`	`Option<usize>`	`None`	Hard cap on LM call units (rollouts plus reflection).
`eval_concurrency`	`usize`	`16`	Rollouts in flight during evaluation.
`seed`	`Option<u64>`	`None`	Fixes minibatch sampling.

Cost: trainset_size for the baseline pass, then minibatch_size rollouts per step, plus the remaining trainset_size - minibatch_size only on promotion and one reflection call per rule move. The run stops cleanly when the budget no longer fits a step.

SimbaStep and SimbaReport

Each SimbaStep records one step:

Field	Type	Description
`step`	`usize`	Step index, 0-based.
`move_kind`	`SimbaMove`	`AppendDemo` or `AppendRule`.
`parent_minibatch_score`	`f64`	Current program’s minibatch mean, the gate threshold.
`child_minibatch_score`	`f64`	Proposed child’s mean on the same minibatch.
`accepted`	`bool`	Whether the gate promoted the child.
`full_score`	`Option<f64>`	Full-trainset mean of the child; `Some` only when promoted.

The SimbaReport summarizes the run:

Field	Type	Description
`baseline_score`	`f64`	Mean metric score of the unmodified module over the trainset.
`final_score`	`f64`	Full-trainset mean of the final program; equals the baseline when nothing was accepted.
`steps`	`Vec<SimbaStep>`	Per-step outcomes, in order.
`accepted`	`usize`	Steps promoted by the gate.
`rejected`	`usize`	Steps rejected by the gate.
`spend`	`Spend`	Engine spend for the whole run, reflection calls included.

BootstrapFewShot

The simplest complete optimizer: one teacher pass, one candidate, one comparison. It runs the module over the trainset under trace capture, harvests few-shot demos from successful spans of rollouts scoring at least min_demo_score, evaluates the demo candidate on the same engine (teacher rollouts already sit in the rollout cache, so the baseline never re-runs), and installs the demos only when the candidate’s mean beats the baseline.

Field	Type	Default	Description
`max_demos`	`usize`	`4`	Maximum demos installed per predictor.
`min_demo_score`	`f64`	`1.0`	Minimum whole-rollout score for a rollout’s spans to qualify as demos. The default assumes a 0 to 1 metric; lower it for graded metrics.
`eval_concurrency`	`usize`	`16`	Concurrent rollouts during evaluation.
`max_metric_calls`	`Option<usize>`	`None`	Hard cap on metric calls (rollouts).
`max_lm_calls`	`Option<usize>`	`None`	Hard cap on LM call units.

BootstrapReport

Field	Type	Description
`baseline_score`	`f64`	Mean metric score of the unmodified module over the trainset.
`candidate_score`	`Option<f64>`	Mean score with demos attached. `None` when no demos were harvested or the budget stopped before the candidate evaluation.
`adopted`	`bool`	Whether the demo candidate beat the baseline and was installed.
`demos_per_predictor`	`BTreeMap<String, usize>`	Demos harvested per predictor, keyed by dotted path.
`spend`	`Spend`	Engine spend for the whole run.

adopted: false with a populated demos_per_predictor means demos were harvested but did not beat the baseline; the module is left unchanged.

Demo harvesting

Demo harvesting is a pure name join over captured traces. A rollout trace records one span per Predict invocation under the same dotted-path component name the mutation seam addresses, so successful spans (parsed output present) from rollouts scoring at least the optimizer’s min_demo_score become flat demo rows for exactly the predictor that produced them: no pointer identity, identical behavior for fx and struct harnesses. Rows are ranked by whole-rollout score, deduplicated on input fields so repeated inputs do not crowd the demo set, and capped per predictor. BootstrapFewShot, MIPROv2, and SIMBA share this machinery; it is internal to the crate and not part of the public API.

Get Started

Building Blocks

Programs as Data

Tools & Agents

Evaluation & Optimization

Utilities

The Optimizer trait

Choosing an optimizer

COPRO

MIPROv2

GEPA

GEPAResult

SIMBA

SimbaStep and SimbaReport

BootstrapFewShot

BootstrapReport

Demo harvesting

See also

​The Optimizer trait

​Choosing an optimizer

​COPRO

​MIPROv2

​GEPA

​GEPAResult

​SIMBA

​SimbaStep and SimbaReport

​BootstrapFewShot

​BootstrapReport

​Demo harvesting

​See also

The Optimizer trait

Choosing an optimizer

COPRO

MIPROv2

GEPA

GEPAResult

SIMBA

SimbaStep and SimbaReport

BootstrapFewShot

BootstrapReport

Demo harvesting

See also