Skip to content

OptimizationState

gepa.optimize_anything.OptimizationState(best_example_evals: list[dict]) dataclass

Accumulated optimization context injected into evaluators that declare an opt_state parameter.

Provides historical evaluation results so your evaluator can warm-start from previous best solutions (e.g., pass the best-known circle packing to a new optimization attempt).

To receive this, simply add opt_state: OptimizationState to your evaluator signature — GEPA injects it automatically.

Example::

def evaluator(candidate, example, opt_state: OptimizationState):
    prev_best = opt_state.best_example_evals[0]["side_info"] if opt_state.best_example_evals else None
    # ... use prev_best to warm-start ...

Attributes

best_example_evals: list[dict] instance-attribute

Top-K best evaluations for the current example, sorted by score (descending).

Each entry: {"score": float, "side_info": dict}. K is controlled by EngineConfig.best_example_evals_k (default 30).

Functions