koog-agents-optimization/ai.koog.agents.optimization.optimizers.gepa/GEPAOptimizer

GEPAOptimizer

class GEPAOptimizer<Input, Output, InputLabel>(reflectionModel: LLModel, val storagePath: ResilientPath, maxIterations: Int, minibatchSize: Int, componentSelection: ComponentSelection, enableCrossover: Boolean, maxMergeInvocations: Int = 5, randomSeed: Long = 42, labelExtractor: (TrainSetItem<Input, InputLabel>) -> String) : AgentOptimizer<Input, Output, InputLabel>

GEPA (Genetic-Pareto Optimizer for Reflective Prompt Evolution).

An instruction-only optimizer that evolves module instructions via reflective LLM feedback on failure cases, with Pareto-based candidate selection for diversity.

Early implementation. This is a non-official re-implementation that deviates from the original GEPA algorithm (https://arxiv.org/abs/2507.19457) and may underperform the paper. Validate on your own task before relying on it; closing the gap is future work.

Key differences from MIPROv2:

Optimizes instructions only (no demonstrations) -> shorter, more generalizable prompts
Uses textual feedback from a reflection LM analyzing failure traces
a Pareto frontier maintains diverse candidate pool (vs. best-so-far)
Optional crossover merges complementary candidates

Parameters

reflectionModel

LLM model for reflection / instruction proposal. Calls are routed through the training DSL's tracked executePrompt, so timing and consumption are recorded under the appropriate iteration stage.

storagePath

Path for saving the optimization artifact.

maxIterations

Maximum number of evolution iterations.

minibatchSize

Number of training items sampled per iteration for reflection.

componentSelection

How to select which modules to update each iteration.

enableCrossover

Whether to attempt merging complementary candidates during the loop.

maxMergeInvocations

Maximum number of crossover attempts per optimization run.

randomSeed

Seed for reproducibility.

labelExtractor

Converts a dataset item's label to a string for the reflection LM.

Constructors

GEPAOptimizer

constructor(reflectionModel: LLModel, storagePath: ResilientPath, maxIterations: Int, minibatchSize: Int, componentSelection: ComponentSelection, enableCrossover: Boolean, maxMergeInvocations: Int = 5, randomSeed: Long = 42, labelExtractor: (TrainSetItem<Input, InputLabel>) -> String)

Types

Companion

object Companion

Persistence helpers for the evolved OptimizationArtifact.

Properties

storagePath

val storagePath: ResilientPath

Functions

loadOptimizedAgent

open override fun loadOptimizedAgent(baseAgent: GraphAIAgent<Input, Output>): GraphAIAgent<Input, Output>

Loads training artifacts produced by train and applies them to the given baseAgent.

train

open suspend override fun train(session: TrainingSession<Input, Output, InputLabel>): TrainingResult

Trains the agent using the provided session, which gives access to a TrainingSession.use block where the training scope (agent, dataset, tracked execution methods) is available.