Skip to main content

​
Overview

EngineConfig controls the core optimization loop behavior in GEPA. It manages evaluation budget, parallelization, caching, and basic stopping conditions. Most users only need to set max_metric_calls (evaluation budget) and optionally parallel/max_workers for concurrent evaluation.

​
Class Definition

from gepa.optimize_anything import EngineConfig

engine = EngineConfig(
    max_metric_calls=200,
    parallel=True,
    max_workers=8,
    cache_evaluation=True,
    run_dir="./experiments/run_001",
)

​
Parameters

​
Basic Settings

​
run_dir
str | None
default:"None"
Directory for storing experiment outputs, logs, and cache files.When set, GEPA will:
  • Save optimization state and results
  • Enable file-based stop condition (gepa.stop file)
  • Store evaluation cache on disk (if cache_evaluation=True)
​
seed
int
default:"0"
Random seed for reproducibility. Affects:
  • Random sampling in batch samplers
  • Stochastic candidate selection strategies
​
display_progress_bar
bool
default:"False"
Show a progress bar during optimization.
​
raise_on_exception
bool
default:"True"
Whether to raise exceptions from evaluator failures.If False, failed evaluations return score 0.0 with error details in side_info.
​
use_cloudpickle
bool
default:"True"
Use cloudpickle for serialization in subprocess evaluation.Enables serialization of lambda functions and closures.
​
track_best_outputs
bool
default:"False"
Track and store the best outputs for each example.Useful for debugging and analyzing optimization progress.

​
Stopping Conditions

​
max_metric_calls
int | None
default:"None"
Maximum number of evaluator calls (evaluation budget).This is the most common stopping condition.The optimization stops when the total number of evaluations reaches this limit.
​
max_candidate_proposals
int | None
default:"None"
Maximum number of candidate proposals.Stops after generating this many new candidates, regardless of evaluation count.

​
Strategy Selection

​
val_evaluation_policy
EvaluationPolicy | Literal['full_eval']
default:"'full_eval'"
Policy for validating candidates on the validation set.Options:
  • "full_eval": Evaluate on all validation examples
  • Custom EvaluationPolicy instance for incremental validation
​
candidate_selection_strategy
CandidateSelector | Literal['pareto', 'current_best', 'epsilon_greedy']
default:"'pareto'"
Strategy for selecting candidates for reflection.Options:
  • "pareto": Select from Pareto frontier (preserves diverse strengths)
  • "current_best": Always select the best candidate
  • "epsilon_greedy": Epsilon-greedy exploration
  • Custom CandidateSelector instance
​
frontier_type
FrontierType
default:"'hybrid'"
Type of Pareto frontier to maintain.Options:
  • "hybrid": Hybrid frontier combining per-task and global scores
  • "per_task": Track best per task
  • "global": Track global best only

​
Parallelization

​
parallel
bool
default:"False"
Enable parallel evaluation of candidates.When True, multiple evaluations run concurrently using a process pool.
​
max_workers
int | None
default:"None"
Maximum number of worker processes for parallel evaluation.If None, defaults to the number of CPU cores.Only used when parallel=True.

​
Evaluation Caching

​
cache_evaluation
bool
default:"False"
Enable caching of evaluation results.Prevents re-evaluating identical candidates, saving computation.
​
cache_evaluation_storage
Literal['memory', 'disk', 'auto']
default:"'auto'"
Where to store the evaluation cache.Options:
  • "memory": In-memory cache (lost after process exits)
  • "disk": Persistent cache in run_dir (requires run_dir to be set)
  • "auto": Use disk if run_dir is set, otherwise memory

​
OptimizationState Tracking

​
best_example_evals_k
int
default:"30"
Number of top evaluations to track per example.These are passed to evaluators that declare an opt_state: OptimizationState parameter, enabling warm-starting from previous best solutions.

​
Standard I/O Capture

​
capture_stdio
bool
default:"False"
Automatically capture stdout/stderr during evaluation.When True, any print() output inside your evaluator is captured and included in side_info under "stdout" and "stderr" keys.Useful for:
  • Quick prototyping without modifying existing code
  • Wrapping evaluation scripts that already have print statements
  • Debugging evaluator behavior
Captures:
  • All Python-level output: print(), sys.stdout.write()
  • Third-party library output through sys.stdout
Does NOT capture:
  • C extensions writing directly to file descriptors
  • Output from subprocesses spawned by libraries
For subprocess output, capture it manually and use oa.log() instead.

​
Usage Examples

​
Basic Configuration

from gepa.optimize_anything import optimize_anything, GEPAConfig, EngineConfig

# Minimal - just set the budget
config = GEPAConfig(
    engine=EngineConfig(max_metric_calls=200)
)

result = optimize_anything(
    seed_candidate="initial code",
    evaluator=my_evaluator,
    config=config,
)

​
Parallel Evaluation

engine = EngineConfig(
    max_metric_calls=500,
    parallel=True,
    max_workers=16,  # Use 16 processes
)

config = GEPAConfig(engine=engine)

​
With Caching

engine = EngineConfig(
    max_metric_calls=1000,
    cache_evaluation=True,
    cache_evaluation_storage="disk",  # Persistent cache
    run_dir="./experiments/run_001",
)

config = GEPAConfig(engine=engine)

​
Capture Print Statements

def my_evaluator(candidate):
    result = run_simulation(candidate)
    # These prints are captured automatically
    print(f"Simulation time: {result.time}")
    print(f"Resource usage: {result.resources}")
    return result.score

engine = EngineConfig(
    max_metric_calls=200,
    capture_stdio=True,  # Capture print output
)

result = optimize_anything(
    seed_candidate=initial_code,
    evaluator=my_evaluator,
    config=GEPAConfig(engine=engine),
)

​
Multiple Stopping Conditions

from gepa.utils import NoImprovementStopper

engine = EngineConfig(
    max_metric_calls=1000,  # Hard limit
    max_candidate_proposals=100,  # Or stop after 100 proposals
)

# Add additional conditions via stop_callbacks
config = GEPAConfig(
    engine=engine,
    stop_callbacks=NoImprovementStopper(max_iterations_without_improvement=50),
)

​
Full Production Setup

engine = EngineConfig(
    # Core settings
    run_dir="./experiments/optimization_001",
    seed=42,
    
    # Budget
    max_metric_calls=5000,
    
    # Performance
    parallel=True,
    max_workers=32,
    
    # Caching
    cache_evaluation=True,
    cache_evaluation_storage="disk",
    
    # Tracking
    track_best_outputs=True,
    display_progress_bar=True,
    
    # Evaluation
    capture_stdio=True,
    raise_on_exception=False,  # Don't crash on bad candidates
    
    # Strategy
    candidate_selection_strategy="pareto",
    frontier_type="hybrid",
)

config = GEPAConfig(engine=engine)

​
File-Based Stop Condition

When run_dir is set, GEPA automatically enables a file-based stop condition. Create a file named gepa.stop in the run directory to gracefully stop the optimization: 
# Stop the optimization
touch ./experiments/run_001/gepa.stop
This is useful for:
  • Manual intervention during long-running optimizations
  • Integration with monitoring systems
  • Scheduled stops via cron jobs

Build docs developers (and LLMs) love

Get started for freeTalk to us