pypi / gepa
gepa
What changed in gepa 0.1, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-26.
5 breaking25 new APIs and options9 behavior and defaults7 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initgepa 0.146 changes
Breaking changes 5
The experimental parameter is removed; use sampling_strategy such as SameParentSampling or PxNSampling instead.
Using it with a reflection_strategy that does not expose total_cost now raises instead of silently never stopping.
Combining it with adapter.propose_new_texts or custom_candidate_proposer now raises ValueError instead of silently ignoring the conflicting configuration.
The litellm floor is raised to at least 1.83 when installing gepa[full] to address Dependabot alerts.
Now defaults to True, retaining best outputs on the result object; pass False to restore the old behavior and reduce memory use for large validation sets.
New APIs and options 25
Adds an optional adapter seam for batching multi-proposal evaluations; adapters implementing only evaluate() continue to use sequential fallback.
Lets optimize_anything evaluate all pending candidate-example pairs in one external call, with caching, warm-start injection, exception policy, and standard output packaging.
Accepts a custom ReflectionLM implementation in optimize or ReflectionConfig to control the reflection step.
A protocol for custom reflection implementations, allowing developers to control reflective mutation calls and implement stateful reflectors.
Adds a diagnostics metadata channel for multi-call reflectors that flows through callbacks, trackers, and proposal metadata.
Acceptance criteria may implement this hook to provide custom rejection messages.
Chooses the parent and minibatch tasks for multi-proposal iterations; available strategies include SingleMutationSampling, SameParentSampling, IndependentSampling, and PxNSampling.
Chooses which proposal improvements enter the pool, with built-in strategies for all, best, or top-k improvements.
Adds a tracker metric for the score after subsampling.
Adds a tracker metric for the score before subsampling.
Adds a pluggable acceptance criterion, with strict_improvement and improvement_or_equal choices or a custom AcceptanceCriterion.
Optimize LangChain/LangGraph applications directly with gepa.optimize; install the langchain extra.
Adds strict_improvement and improvement_or_equal as selectable acceptance criteria.
Allows passing a custom acceptance criterion for reflective mutation.
Adds logprob-aware scoring and reflection for classification tasks.
Experimental option for generating and evaluating multiple candidate proposals per optimize_anything iteration; the interface is expected to change.
Adds adapter_state so adapters can persist state across checkpoint and resume.
Exposes trainset_loader for datasets that change during optimization.
Optimize LangChain/LangGraph applications directly with gepa.optimize; install the gepa[langchain] extra.
Adds a budget knob for controlling reflection cost.
Logs into an already-active MLflow run without GEPA managing its lifecycle.
The callback exposes reflection LM prompts and outputs.
The unified LM layer adds first-class handling of reasoning models as reflection LMs.
Passes provider-specific parameters to the reflection model.
Logs into an already-active WandB run without GEPA managing its lifecycle.
Behavior and default changes 9
Stop conditions are checked between iterations, so multi-proposal strategies can exceed max_metric_calls by up to one iteration's evaluations.
Becomes optional when batch_evaluator is provided; evaluations, including refiner steps, route through the batch function.
Entries now include per-task ids and before/after scores, task count, accepted program indices, and stable proposal ids while preserving legacy keys.
Fires per evaluation stage with self-consistent deltas; aggregate metric_calls_delta rather than counting events.
Merge proposals now fire GEPACallback events.
Selection strategies now receive all evaluated proposals and the acceptance criterion; custom strategies may surface proposals rejected by that criterion.
Run directories written by v0.1.1 are migrated automatically on load; state written by v0.1.2 is not designed to load in v0.1.1.
Reflection prompts and outputs are logged to a proposals table for run archaeology.
Run directories written by v0.1.1 are migrated automatically on load; v0.1.2 state is not designed to load in v0.1.1.
Fixes and other changes 7
Criteria are evaluated exactly once per proposal, with results memoized so stateful or stochastic criteria behave correctly.
Identical child candidates within an iteration are deduplicated before valset evaluation.
Now fires for every unselected proposal with a reason identifying acceptance failure, selection drop, or duplication.
No longer hides batch_complete from wrapped callables that provide it, preventing batched reflection from being silently downgraded.
Fixes a crash when outputs=None and a reflection_lm type mismatch.
The callback protocol now works in optimize_anything runs, as well as gepa.optimize runs.
Refiner evaluator calls are now counted toward the metric-call budget.