GEPA rewrites the text inside your system — a prompt, a config, even code — to push a score you care about up. It learns by reading why each attempt failed, not just the number. Scroll to see exactly how, no prior knowledge needed.
Most automated optimizers see only a score and nudge blindly. GEPA does what a good coach does: it reads the actual mistake in plain language and fixes that specific thing. GEPA calls this feedback ASI — Actionable Side Information. It's the "gradient" of text optimization.
Collapses everything that happened into one reward number, then guesses an adjustment.
"…that's all I know. Try something?"
Needs 5,000–25,000+ attempts to learn.
Reads the full record of what happened, diagnoses the cause:
Input: "A train travels 60km in 90 min. Speed in km/h?"
Output: "60 km/h" ✗
Feedback: Wrong. Forgot to convert 90 min → 1.5 h. Answer is 40.
→ rewrites the prompt to add a unit‑conversion step. Learns in 100–500 attempts.
You don't type into GEPA. It's a Python package
(pip install gepa) you call from your own code. It runs its
search, then hands you back an optimized prompt / config / program that you deploy into
your app. GEPA operates one level up from the prompt surface — it writes what runs
there, rather than living there itself. It has to be a library (not a chat box) because it needs to
run your system hundreds of times automatically and call a scoring function — things that
only exist inside a program.
Every turn of the loop tries to breed one better candidate. Click the steps, or press ▶ Auto‑play. The order matches the real engine.
Forget the smooth cost‑vs‑quality curve you may have seen. GEPA tracks, for each individual test example, which candidates score best on it. The frontier is everyone who's a champion of at least one example — so a brilliant specialist with a mediocre average never gets thrown away. Hover a column to see its champions.
How GEPA picks who to evolve next. It samples a frontier candidate weighted by how many examples it champions. Specialists of rare, hard examples still get their turn. Press the button to draw one.
Note the trap this avoids: Candidate A has the best average (it gets partial credit everywhere), yet B is the only one that fully solves the two hardest examples (ex3, ex4), and C and D — the lowest‑average pure specialists — are each the only one that solves one more (ex5, ex6). Because every one of B, C, D is the sole champion of something, none is "dominated," so the frontier keeps them all alive to evolve from. A greedy "keep the best average" optimizer would delete B, C and D and lose those skills forever.
Each generation, GEPA reads a failure and adds a targeted fix. The prompt accumulates hard‑won lessons and the score climbs. Step through a (representative) run:
Illustrative numbers in the spirit of GEPA's published results (e.g. GPT‑4.1 Mini 46.6% → 56.6% on AIME 2025).
"Beat my parent on 3 examples" and "joined the frontier" are different events. The cheap gate filters; only survivors pay for the expensive one.
Re‑run the new candidate on the same 3 training examples it was born from. Did its total beat its parent? If not → discarded instantly (just 3 rollouts spent).
Only if it passed gate ①: evaluate on the entire validation set, add it to the pool, and now update the per‑example Pareto frontier.
Install, set a key, and optimize your first prompt. Full walkthrough in the Quickstart.
1 · Install
pip install gepa2 · Set your model key
export OPENAI_API_KEY="sk-..."3 · Optimize
The words GEPA uses, each in one line. Full version in the Glossary.