# 5. Glossary

Every term you'll meet in GEPA, defined in plain language with an example. Terms are grouped by
theme; within each group they build on each other. Cross‑references point to the page where a term is
explained in depth.

---

## The basics (no prior knowledge assumed)

**LLM (Large Language Model)** — an AI system that takes text in and produces text out (e.g. GPT,
Claude, Gemini). GEPA optimizes the text you feed an LLM, and also uses an LLM to do the optimizing.
*Example: `openai/gpt-4o-mini`.*

**Prompt** — the text instruction you give an LLM to steer its behavior. *Example: "You are a helpful
assistant. Answer concisely."* Often the thing GEPA optimizes.

**System prompt** — a prompt that sets the model's overall role/behavior, applied before the user's
input. The default thing GEPA tunes in simple setups.

**Score / metric** — a number measuring how well a candidate did, where **higher is always better**
in GEPA. *Example: fraction of questions answered correctly (0.0–1.0).*

**Evaluator / metric function** — your code that takes a candidate's output and returns a score (and,
ideally, a sentence of feedback). The thing that defines "good." See [Recipes](04-recipes.md).

**Feedback** — a plain‑language explanation of *why* an output scored the way it did. The richer this
is, the better GEPA optimizes. *Example: "Incorrect — reversed the digits in the final answer."*

**Gradient** — (from machine learning) the numeric signal telling a numeric optimizer which direction
to adjust numbers to improve. Text has no gradient; GEPA's stand‑in is **ASI** (below).

---

## Core GEPA concepts

**GEPA** — **GE**netic‑**PA**reto. A framework that optimizes textual system components via
LLM‑based reflection and Pareto‑efficient evolutionary search. See [What is GEPA?](01-what-is-gepa.md).

**Component** — one named, editable piece of text in your system. *Example: the key `"system_prompt"`.*
A system may have several components (e.g. one prompt per agent step).

**Candidate** — one complete set of component values; a single full configuration to try. Represented
as a `dict[str, str]`, e.g. `{"system_prompt": "..."}`. The thing GEPA evolves.

**Seed candidate** — the starting candidate you hand GEPA. Can also be `None` ("seedless"), in which
case the reflection LLM writes the first draft from your objective.

**Reflection** — the step where a strong LLM reads the captured failure records and diagnoses the
cause, then rewrites a component. The "thinking" in GEPA. See [How GEPA works](02-how-gepa-works.md).

**Reflection LM (`reflection_lm`)** — the strong model that performs reflection and writes improved
text. Should be capable; this is where rewrite quality comes from. *Example: `openai/gpt-5`.*

**Task LM (`task_lm`)** — the model that actually does the job and whose prompt is being optimized.
Can be small/cheap. Distinct from the reflection LM.

**ASI (Actionable Side Information)** — the plain‑language diagnostic feedback (errors, outputs,
hints, reference answers) that reflection reads. GEPA's text‑native replacement for a gradient. **The
single most important concept in GEPA.** You produce it via your evaluator's feedback or `oa.log(...)`.

**Mutation** — creating a new candidate by having the reflection LLM rewrite a component to fix a
diagnosed problem. Not random — it's directed by ASI.

**Merge** — an optional crossover step that combines two candidates excelling on *different* examples
into one that inherits both strengths. Enabled with `use_merge=True`.

---

## Search & the Pareto frontier

**Pool / population** — the growing set of all candidates GEPA has kept. It starts with just the seed.

**Pareto frontier** — the set of candidates that are the **best at at least one thing**, even if their
average is low. GEPA keeps all of them so it never discards a useful specialist. Plain definition: the
"undominated" set — nothing else beats them in every respect. See
[How GEPA works → The Pareto frontier, demystified](02-how-gepa-works.md#the-pareto-frontier-demystified).

**Instance frontier (`frontier_type="instance"`)** — GEPA's default: the frontier is tracked **per
individual validation example**. For each example, GEPA records the best score and the *set* of
candidates achieving it; the frontier is the union of those sets. *This is the "champions board"
model.*

**Champion (of an example)** — a candidate achieving the best‑known score on a specific validation
example. Ties mean multiple champions for that example.

**Dominated candidate** — one whose every win is also covered by some single other candidate; it adds
no unique value and is dropped from selection.

**Candidate selection strategy (`candidate_selection_strategy`)** — how GEPA chooses which candidate
to mutate next. Default `"pareto"` samples frontier candidates weighted by how many examples they
champion. Others: `"current_best"`, `"epsilon_greedy"`, `"top_k_pareto"`.

**Objective / cartesian / hybrid frontier** — advanced `frontier_type` options for when your
evaluator returns multiple named scores (objectives). Track champions per objective, per
(example × objective), or both. Default `"instance"` suits most users.

---

## Running an optimization

**Rollout** — one execution of a candidate on one example, producing an output (and, when requested, a
trace). The atomic unit of work.

**Metric call** — one rollout + its scoring. **GEPA's unit of budget.** *Example: `max_metric_calls=150`
means GEPA stops after 150 of these.*

**Minibatch** — the small set of training examples (default **3**) a candidate is tried on each
iteration, used for cheap acceptance decisions.

**Acceptance criterion** — the rule deciding whether a new candidate beats its parent on the
minibatch. Default `"strict_improvement"` (must be strictly better); also `"improvement_or_equal"`.
This is **Gate 1**.

**Full evaluation** — scoring an accepted candidate on the entire valset; only this updates the Pareto
frontier. This is **Gate 2**.

**Trainset** — examples GEPA experiments on during search (it reads their traces to learn).

**Valset** — held‑out examples GEPA scores candidates against to judge real quality. Defaults to the
trainset if you don't supply one.

**Trajectory / trace** — the captured record of what happened during a rollout (output, errors,
intermediate steps). Opaque to GEPA's engine; consumed by your adapter to build the reflective dataset.

**Reflective dataset** — the clean, structured records (`Inputs`, `Generated Outputs`, `Feedback`)
your adapter builds from trajectories and hands to the reflection LLM.

**Stop condition / stopper** — what ends the run: `max_metric_calls`, a timeout, "no improvement for K
iterations", a reflection‑cost cap, or a manual `gepa.stop` file. At least one is required.

**Budget** — the total resources GEPA may spend, expressed in metric calls (and optionally a
reflection‑cost cap or time limit).

---

## Plumbing & integration

**Adapter (`GEPAAdapter`)** — the glue connecting GEPA to your system. Implements `evaluate` and
`make_reflective_dataset` (and optionally `propose_new_texts`). See [Recipe C](04-recipes.md#recipe-c--plug-gepa-into-your-own-system-write-an-adapter).

**`DefaultAdapter`** — the built‑in adapter for single‑turn prompt tasks; pair it with a `task_lm`.

**`optimize_anything`** — the general entry point that optimizes any text artifact via an
`evaluator(candidate) -> score` function, no dataset required. Has single‑task, multi‑task, and
generalization modes.

**`oa.log(...)`** — call it inside an `optimize_anything` evaluator to record diagnostics; the output
is captured as ASI for reflection.

**`GEPAResult`** — the object returned by an optimization. Key fields: `best_candidate`, `best_idx`,
`val_aggregate_scores`, `candidates`, `total_metric_calls`, `per_val_instance_best_candidates`.

**LiteLLM** — the library GEPA uses to talk to many model providers through one interface, hence model
names like `provider/model` (`openai/gpt-4o-mini`, `anthropic/claude-haiku-4-5`).

**DSPy** — a framework for building LLM pipelines; exposes GEPA as `dspy.GEPA` to optimize the
instructions inside a DSPy program. The recommended route for complex AI pipelines.

**Callback** — an object GEPA notifies on events (`on_iteration_start`, `on_candidate_accepted`, …)
so you can observe or react to progress. See `docs/docs/guides/callbacks.md`.

**`run_dir`** — a directory where GEPA saves state; enables checkpointing, resuming, and the
auto‑generated candidate‑tree visualization.

---

Back to the [onboarding hub](README.md) · open the [interactive guide](index.html).