Skip to content

optimization_workflow.md

Latest commit

 

History

History
73 lines (49 loc) · 2.92 KB

optimization_workflow.md

File metadata and controls

73 lines (49 loc) · 2.92 KB
Raw

Optimization Workflow

GEPA runs a tight optimization loop:

  1. evaluate the seed candidate
  2. choose a candidate to mutate
  3. sample a minibatch from the training set
  4. build a reflective dataset from traces
  5. propose a new candidate
  6. evaluate the proposal
  7. accept or reject it
  8. repeat until a stop condition triggers

Candidate Selection

The selector is where exploration and exploitation are balanced.

  • GEPA.Strategies.CandidateSelector.Pareto samples from the current Pareto front
  • GEPA.Strategies.CandidateSelector.CurrentBest always selects the top candidate
  • GEPA.Strategies.CandidateSelector.TopKPareto samples from the top-k front members
  • GEPA.Strategies.CandidateSelector.EpsilonGreedy explores with a decaying epsilon

EpsilonGreedy is stateful: it carries the current epsilon forward across selections and can be reset back to its initial value.

Proposals

GEPA can produce proposals in three ways:

  • the adapter implements propose_new_texts/3 or /4
  • GEPA.Proposer.InstructionProposal calls an LLM with a reflective dataset
  • GEPA.Proposer.Merge combines related parents when merge mode is enabled

Instruction proposal supports custom templates and structured output. For native structured output, pass a hosted ReqLLM client such as GEPA.LLM.req_llm(:openai), :gemini, or :anthropic as :reflection_llm. Local ASM clients can be used for text proposals, but structured output is capability-gated off there.

Adapter-owned proposal callbacks are task-adapter callbacks. They are separate from the LLM adapter/provider selection used by GEPA.LLM. Merge mode is scheduled separately and can be turned off entirely.

Acceptance

GEPA.Strategies.Acceptance controls when a proposal replaces the current candidate. The common modes are:

  • strict improvement
  • improvement or equal
  • a custom function or module

The engine evaluates the proposal on the sampled minibatch first, then applies the configured acceptance rule.

Stop Conditions

The built-in stop conditions cover:

  • call budgets
  • proposal budgets
  • reflection-cost budgets
  • timeouts
  • score thresholds
  • no-improvement patience
  • tracked-candidate limits
  • explicit signal or file stops

You can compose multiple conditions with GEPA.StopCondition.Composite.

Persistence and Resume

When :run_dir is configured, GEPA persists state and can resume later. The state includes candidate history, Pareto fronts, adapter state, and the validation schema version needed to reload safely.

Progress, Callbacks, Tracking

  • GEPA.Progress prints a terminal progress line when enabled
  • GEPA.Callbacks exposes synchronous lifecycle events
  • GEPA.Tracking forwards scalar metrics and summary data to an external backend
  • GEPA.Telemetry emits a stable event schema for handlers that prefer Telemetry over callbacks

These layers sit on top of the engine. They do not change candidate semantics, but they make long runs observable and restartable.