Skip to content

OptimizeAnythingConfig

gepa.optimize_anything.OptimizeAnythingConfig(engine: str | Engine = 'gepa', name: str | None = None, max_evals: int | None = 100, max_token_cost: float | None = None, max_concurrency: int = 8, output_dir: str | Path | None = None, run_dir: str | None = None, stop_at_score: float | None = None, sandbox: bool = True, engine_config: dict[str, Any] = dict()) dataclass

Configuration for :func:gepa.optimize_anything.optimize_anything.

Attributes:

Name Type Description
engine str | Engine

Engine name ("gepa" / "autoresearch" / "meta_harness") or a constructed :class:Engine instance. When a string, the engine class is instantiated with this :class:OptimizeAnythingConfig.
name str | None

Identifier for this run, used for logging and to lay out the default output directory. When None, a name is generated on the fly from the engine, a short uuid, and a timestamp (e.g. "gepa-a1b2c3d4-20260623-153045").
max_evals int | None

Server-side cap on eval calls. None = unlimited.
max_token_cost float | None

Proposer-cost cap — cumulative USD an engine may spend on its own optimizer LLM tokens (reflection, agent). None = unlimited. This is not an eval-budget field: the eval server never sees proposer spend (a subprocess's cost isn't even knowable until it exits). Each engine reads it at construction and enforces it itself (gepa: max_reflection_cost; autoresearch/meta_harness: --max-budget-usd). At least one of max_evals / max_token_cost must be set so a run is bounded.
max_concurrency int

Eval server thread-pool size.
output_dir str | Path | None

Where the eval server persists per-eval JSON, progress_log.jsonl, and summary.json. When None, the api constructs a timestamped default (outputs/optimize_anything/<task>/ <engine>/<timestamp>/) so a run always has somewhere to land.
run_dir str | None

Engine workspace directory. Distinct from output_dir: this is where the engine writes its own artifacts (gepa run dir, autoresearch work dir, etc.). When None, subprocess engines use a tempdir; in-process engines skip artifact writes. Set explicitly to persist them.
stop_at_score float | None

Score threshold for early stop. Each engine interprets.
sandbox bool

OS-jail the subprocess engines' claude sessions (bwrap on Linux — requires the bubblewrap package — Claude Code's Seatbelt sandbox on macOS). Default True. Linux runs abort at engine start when bwrap is missing; False prints a loud warning and runs the agent unsandboxed with full host access.
engine_config dict[str, Any]

Engine-specific options that don't generalize across engines. Each engine reads the keys it understands and warns about leftovers so typos surface. The keys an engine accepts are enumerated in that engine's class docstring:

  • gepa — a GEPAConfig-shaped dict, passed through 1-to-1. Its accepted keys are the live fields of :class:~gepa.gepa_launcher.GEPAConfig (engine, reflection, merge, refiner, tracking, callbacks, stop_callbacks); the OA layer only overlays the budget/run_dir/cost-cap and merges its own callbacks. Set the reflection LM, wandb/mlflow tracking, reasoning knobs (via reflection.reflection_lm_kwargs, e.g. reasoning_effort / thinking), and (via reflection.custom_candidate_proposer) a Claude Code proposer here — see :class:~gepa.oa.engines.gepa.GepaEngine.
  • autoresearch — model, ralph, max_no_eval_seconds, handoffs, effort, max_thinking_tokens (see AutoResearchEngine / _AR_CONFIG_KEYS).
  • best_of_n — model, temperature, max_n, lm_kwargs, effort, max_thinking_tokens (see BestOfNEngine / _BON_CONFIG_KEYS).
  • meta_harness — model, max_iterations, max_candidates_per_iter, effort, max_thinking_tokens (see MetaHarnessEngine / _MH_CONFIG_KEYS).

effort (claude --effort) and max_thinking_tokens are Claude-CLI knobs, so they live in each agent engine's engine_config; the gepa engine takes reasoning knobs through reflection.reflection_lm_kwargs instead.

Attributes

engine: str | Engine = 'gepa' class-attribute instance-attribute

name: str | None = None class-attribute instance-attribute

max_evals: int | None = 100 class-attribute instance-attribute

max_token_cost: float | None = None class-attribute instance-attribute

max_concurrency: int = 8 class-attribute instance-attribute

output_dir: str | Path | None = None class-attribute instance-attribute

run_dir: str | None = None class-attribute instance-attribute

stop_at_score: float | None = None class-attribute instance-attribute

sandbox: bool = True class-attribute instance-attribute

engine_config: dict[str, Any] = field(default_factory=dict) class-attribute instance-attribute

Methods: