git:20260822.1806da1 to git:20260822.02a1a1d

---

name: gepa

description: Runs the GEPA optimization loop (arXiv:2507.19457) — sample-efficient reflective Pareto search. A cheap train-minibatch pre-gate decides whether a proposal is worth an expensive val evaluation, and parents are sampled from a per-instance frontier so specialists survive instead of being averaged away. Use when rollouts are expensive and the scorer returns informative per-task feedback, and you want the most quality per evaluation. Use hill-climb instead for a first baseline run or for feedback-poor binary pass/fail tasks.

component: algorithm

argument-hint: "--run-dir DIR --project DIR --optimizer 'CMD {workdir} {prompt}' [--max-metric-calls N --minibatch-size 4 --component-selector round_robin|all --max-merges 2 --resume]"

allowed-tools: Read, Write, Bash

provides: [candidate]

needs: [scores, traces, reflective_dataset, candidate]

sources: [gepa]

---

# gepa — sample-efficient reflective Pareto search

`algorithms/hill-climb` owns the mechanics every algorithm shares: parent →

## The two mechanisms, and why removing either turns GEPA back into hill-climb

**1. The parent is sampled from per-instance winners, not from the global best.**

A mean is a lossy summary. A candidate that fixes one genuinely hard task while

regressing three easy ones has a *worse* mean than the incumbent, so a

best-parent rule discards it — and with it the only text in the pool that has

ever solved that task. GEPA instead scores per val instance and samples

frequency-weighted over candidates that (co-)win at least one, so specialists and

stepping-stones stay reachable as parents while their mean is still behind. That

is the quality-diversity argument (MAP-Elites): keep the *set* that covers the

task distribution, not the single champion. Sampling is stochastic and seeded, so

the exploration is reproducible.

**2. A cheap train minibatch pre-gates the expensive val evaluation.** Rollouts

dominate cost and a full-val eval costs `|val| · n_trials` of them. Most

proposals are bad; paying full price to find that out is what makes naive

reflective search unaffordable, and GEPA's headline "~35× fewer rollouts" comes

almost entirely from *not* paying it. So parent and child are evaluated on the

**same** small train minibatch (`2 · minibatch-size` rollouts, eval-cached) and

the child is dropped unless `sum(child) > sum(parent)`. The minibatch never

*decides* acceptance — it decides whether acceptance is worth measuring.

A side benefit of (2): reflection reads **train** traces, so the proposer never

sees the split its gate is computed on.

## What differs from hill-climb, step by step

1. **Parent** — frequency-weighted sample over per-instance (co-)winners

(`--selection-strategy`, default `pareto_per_instance`), not the current best.

2. **Signal** — a minibatch of `--minibatch-size` (default 4) **train** ids,

evaluated with traces, instead of the whole train focus set.

3. **Reflective dataset** — `REFLECTION.md` in the optimizer workdir, over the

parent's failing minibatch tasks (`phases/diagnose` owns what one is and what

shape it takes). "Failing" is the hard threshold `reward < 1.0`, so with a

graded scorer that never reaches 1.0 every sampled task is listed and the

header always reads `0/N pass` — read it as "sampled tasks, worst first". Each

entry is truncated to ~800 chars and at most 12 tasks are written: a summary,

not an archive; untruncated rollouts stay in `rollouts/train/`. The prompt also

4. **Local gate** — child on the same minibatch, `sum(child) > sum(parent)`, else

dropped with no val spend. This is the extra stage; everything after it is

hill-climb's.

5. **Merge** — every `--merge-cadence` accepts, find two strict-frontier

dominators sharing a common ancestor both beat and recombine them

component-by-component (each component from whichever descendant changed it),

then minibatch-gate and val-gate the result like any other child.

Note the word "frontier" covers two different sets here: the *sampling pool* in

step 1 is every candidate with ≥1 instance win, which can include dominated

candidates; the strict per-task Pareto frontier (`selection.pareto_frontier`) is

a subset of it and is what the merge and the reported `frontier_size` use.

## Component selection

A **component** is one editable file of the candidate. (Unrelated to

hill-climb's `--focus`, which selects *tasks*; this selects *files*.)

- **`--component-selector round_robin`** (default): one component per iteration,

cycled, written to `FOCUS.md`. Small attributable changes are exactly the unit

the merge can later recombine — a sprawling multi-file rewrite cannot be.

- **`--component-selector all`**: list every component; the optimizer may edit

anywhere. Use for monolithic capabilities or genuinely cross-cutting changes.

For a single-file capability the two coincide and the merge skips gracefully

(`gepa_merge_skip`) rather than emitting a degenerate child.

## Key hyperparameters

- `--max-metric-calls` (default 0 = unlimited): PRIMARY budget, checked

**between** iterations. An in-flight iteration runs to completion, so actual

- `--max-iterations` (default 50): secondary cap on propose→gate iterations.

- `--minibatch-size` (default 4): train ids per cheap local gate.

- `--n-trials` (default 1): rollouts/task on the full-val eval (raise under noise

so the significance gate is trustworthy). Minibatch evals are always 1 trial.

- `--max-merges` (default 2): cap on merge **attempts that built a candidate** —

a merge rejected at either gate consumes one. A skip (no eligible pair) is free.

- `--merge-cadence` (default 3): accepts between merge attempts.

- `--protected-paths` (empty = off; `default` = the built-in globs): seals the

eval surface (scorer/gold/tasks/tests).

A child that edits one is **INDECISIVE** — no reward recorded, not remembered

as rejected, stall counter untouched — because scoring a gold-hacking edit at

- `--workers` (default 1): pools the minibatch rollouts. Only safe when the

adapter's `run_target` is thread-safe.

- `--store` / `--store-commit-cmd` (default `git`): where accepted candidates are

committed.

- `--gate-mode` / `--k-se`, `--no-regression`, `--seed`: as hill-climb.

- `--resume`: rebuild pool/lineage/frontier from `gepa_state.json` + each

accepted candidate's rollouts and continue the search. Preserved spend keeps

the budget honest; the parent-sampling RNG stream restarts, so a resumed run is

not byte-identical.

## Known gaps (present tense — the shipped loop, not the paper)

## How to run

```bash

python scripts/check.py # behavioral, offline (mock optimizer + synthetic adapter)

python scripts/run.py --run-dir .capevolve/run_X --project .capevolve/project \

--optimizer 'python .../run-optimizer/scripts/run.py --name mock --workdir {workdir} --prompt {prompt}' \

--max-metric-calls 400 --minibatch-size 4 --component-selector round_robin

```

Requires `baseline` first (reads the seed's full-val result from `baseline.json`).

Reports the pool, `frontier_size`, best candidate, accepts, merges, and

metric-calls spent.

## Agent-mode loop

When `orchestration_mode: agent`, follow `orchestrate/orchestrate` §Agent-mode

loop for the shared rules, and make each round GEPA-shaped: pick the parent by

per-instance win count; sample `minibatch-size` **train** ids; evaluate parent

then child on that same minibatch and drop the child unless `sum(child) >

sum(parent)`; only then pay for a full **val** eval and its gate. Reflect on the

train minibatch, never on val — val is the judge, not the teacher.

## References

- `references/concepts.md` — the paper's thesis (language as a richer learning

medium than a scalar), the frequency-weighted per-instance frontier, the

system-aware merge and its tie-breaking, the metric-call/eval-cache accounting,

and how the pieces relate to the hill-climb / skillopt siblings. Load when you

need the reasoning behind a knob rather than its value. Cites arXiv:2507.19457.