NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI
PyPI, #1262 most downloaded on PyPI
A framework for optimizing textual system components (AI prompts, code snippets, etc.) using LLM-based reflection and Pareto-efficient evolutionary search.
Latest stable
0.1.4
Last release 4 months ago
15 Jul 2026
Release timing varies
gaps range from 1 weeks to 4 months
Most releases are documented
notes for 25 of 29 stable releases
1 version withdrawn
withdrawn after publishing
1 years old
36 releases · first in 2025
Drag across the ruler to compare, or tap a release to open it.
…and hardened through five review rounds. One breaking change is called out under Breaking & upgrade notes.
This release ships the reflection-LM protocol and batch-based parallel proposals ([RFC #329](https://github.com/gepa-ai/gepa/issues/329), Phases 1 & 4) — the largest change to GEPA's proposal machinery since the project started, contributed by @Benzhang2004 in #369 and hardened through five review rounds. One breaking change is called out under Breaking & upgrade notes.
pip install -U gepa
sampling_strategy= chooses the (parent, minibatch) tasks — SingleMutationSampling (default, classic GEPA), SameParentSampling(n), IndependentSampling(n), PxNSampling(p, n) — and selection_strategy= decides which improvements enter the pool: AllImprovements (default), BestImprovement, TopKImprovements(k). Defaults reproduce previous behavior exactly (pinned by replay tests against a recorded pre-change run). Full guide: [Parallel Proposals](https://gepa-ai.github.io/gepa/guides/parallel-proposals/).ReflectionLM protocol + reflection_strategy= (#369, RFC #329 Phase 1): the reflection step is now a seam. Pass a custom ReflectionLM implementation to gepa.optimize(reflection_strategy=...) or ReflectionConfig(reflection_strategy=...) to own how reflective mutation calls the reflection model — the entry point for session-based, aggregating (ComBEE-style, #307), and coding-agent reflectors. Stateful implementations return a successor from reflect(); chaining semantics are documented in [RFC #329](https://github.com/gepa-ai/gepa/issues/329#issuecomment-4981863763). Multi-call reflectors get a ReflectionProposal.metadata diagnostics channel that flows through to callbacks, trackers, and proposal metadata.batch_evaluator= — one external call for all pending evaluations (optimize_anything): hand GEPA a function that receives every pending (candidate, example) pair in a single call (provider batch APIs, Slurm/Ray, your own cluster) and return one result per pair. Parity with the standard evaluator path: shared evaluation caching (only misses reach your function, still as one call), per-pair opt_states warm-start injection, raise_on_exception policy with a documented _gepa_transient_failure contract (failures are never cached), str-candidate unwrapping, and identical output packaging. evaluator= is now optional when batch_evaluator= is provided — everything routes through your batch function, including refiner steps as singleton batches.GEPAAdapter.batch_evaluate seam lets adapters parallelize multi-proposal evaluations however they like; adapters that only implement evaluate() keep working unchanged (sequential fallback).on_candidate_rejected with an accurate reason — acceptance failure, dropped-by-selection, or duplicate — and acceptance criteria may provide a reject_reason(proposal, state) hook for custom messages. Criteria are judged exactly once per proposal (memoized), so stateful or stochastic criteria behave correctly. Identical child candidates within an iteration are deduplicated before valset evaluation.full_program_trace entries now record every task in multi-task iterations (n_tasks, tasks with per-task ids and before/after scores) and every accepted program index (new_program_indices); each proposal carries a stable metadata["proposal_id"]. Legacy keys are preserved for existing tooling.on_budget_updated now fires per evaluation stage (parent minibatch, child minibatch, valset) with self-consistent deltas — totals unchanged. New tracker metrics subsample/before and subsample/after join the existing subsample_score/new_subsample_score keys.optimize_anything merge proposals now fire GEPACallback events — the known issue from the v0.1.2 notes (#290 gap).TrackingLM no longer hides batch_complete from wrapped callables that provide it, so batched reflection is not silently downgraded.EngineConfig.num_parallel_proposals is removed. The v0.1.2 notes anticipated a one-release deprecation shim; we're removing the parameter outright instead — it was experimental, shipped in only two patch releases, and the replacement is strictly more expressive. Migration: num_parallel_proposals=n → EngineConfig(sampling_strategy=SameParentSampling(n)) (or PxNSampling(p, n) to vary parents too), optionally with selection_strategy=.reflection_strategy combined with adapter.propose_new_texts or custom_candidate_proposer raises ValueError (previously such conflicting configuration would be silently ignored); max_reflection_cost with a reflection_strategy that doesn't expose total_cost raises instead of silently never stopping.on_budget_updated events, sum metric_calls_delta rather than counting events (counts per iteration increased; totals and monotonicity are unchanged).PxNSampling(4, 4) can overrun max_metric_calls by up to one full iteration's evaluations. See the guide's budget section.parallel=True / batch_evaluator), the full batch_evaluator contract, budget semantics, and custom reflection strategies.@Benzhang2004 (Jialin Zhang) authored #369 and carried it through five rounds of review — and makes his first contribution to GEPA with the largest feature PR in the project's history. Thanks also to @Shangyint for design review on RFC #329, and to everyone whose issues shaped the strategy interfaces (#61, #116, #298, #324).
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.1.3...v0.1.4
Your coding agent can read these notes before it upgrades. Set up the MCP server →
…sampling/selection strategies (see #369), with a deprecation shim for one release. Use it, but don't build durable config around the parameter name.
This release ships everything merged to main since v0.1.1 (March 2026): two new adapters, parallel proposal generation, reflection-cost controls, a unified LM layer, dependency security bumps, and a large expansion of the docs and showcase.
pip install -U gepa
gepa.optimize (#361, @bryonkucharski). Install with pip install 'gepa[langchain]'.pip install 'gepa[confidence]'.max_reflection_cost budget knob, with cost/token tracking moved into a unified LM layer (#327, #325); pass provider-specific parameters to the reflection model via reflection_lm_kwargs (#336).optimize_anything — the GEPACallback protocol now works in optimize_anything runs, not just gepa.optimize (#290).wandb_attach_existing / mlflow_attach_existing log into an already-active run without GEPA managing its lifecycle (#280), and reflection prompts/outputs are logged to a proposals table for run archaeology (#276, #254)."strict_improvement" or "improvement_or_equal", or pass your own AcceptanceCriterion (#304).GEPAState.adapter_state so custom adapters survive checkpoint/resume (#230, @lukedhlee).trainset_loader exposed in IterationStartEvent for datasets that change during optimization (#247).DspyAdapter: fixed a crash on outputs=None and a reflection_lm type mismatch (#320, @Archelunch).litellm, mlflow, and requests floors to address Dependabot alerts (#322). If you install gepa[full], this raises the litellm floor to ≥1.83.track_best_outputs now defaults to True (#286). Best outputs are retained on the result object by default, which is what most users expect when inspecting results — but it increases memory use for large valsets. Pass track_best_outputs=False to restore the old behavior, especially if you embed GEPA inside a training loop.run_dir with v0.1.2 is supported. Note that a state written by v0.1.2 is not designed to be loaded by v0.1.1 — finish in-flight runs on the version that started them, or upgrade before resuming.full extra was restructured (#322 and packaging cleanups); if you previously pinned workarounds for 3.14, they should no longer be necessary.optimize_anything can generate and evaluate multiple candidate proposals per iteration via EngineConfig.num_parallel_proposals. This interface is experimental and will change: per RFC #329, the next minor release replaces the integer knob with composable sampling/selection strategies (see #369), with a deprecation shim for one release. Use it, but don't build durable config around the parameter name.optimize_anything runs, merge-proposal events do not yet fire GEPACallback hooks (the callback plumbing from #290 does not reach the merge proposer). Mutation/iteration events are unaffected. A fix is queued for the next release.@Shangyint, @lukedhlee, @bryonkucharski, @rodolfo-nobrega, @Archelunch, and @arnaudleg for code contributions in this release, and everyone who filed the issues these fixes came from.
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.1.1...v0.1.3
…sampling/selection strategies (see #369), with a deprecation shim for one release. Use it, but don't build durable config around the parameter name.
This release ships everything merged to main since v0.1.1 (March 2026): two new adapters, parallel proposal generation, reflection-cost controls, a unified LM layer, dependency security bumps, and a large expansion of the docs and showcase.
pip install -U gepa
gepa.optimize (#361, @bryonkucharski). Install with pip install 'gepa[langchain]'.pip install 'gepa[confidence]'.max_reflection_cost budget knob, with cost/token tracking moved into a unified LM layer (#327, #325); pass provider-specific parameters to the reflection model via reflection_lm_kwargs (#336).optimize_anything — the GEPACallback protocol now works in optimize_anything runs, not just gepa.optimize (#290).wandb_attach_existing / mlflow_attach_existing log into an already-active run without GEPA managing its lifecycle (#280), and reflection prompts/outputs are logged to a proposals table for run archaeology (#276, #254)."strict_improvement" or "improvement_or_equal", or pass your own AcceptanceCriterion (#304).GEPAState.adapter_state so custom adapters survive checkpoint/resume (#230, @lukedhlee).trainset_loader exposed in IterationStartEvent for datasets that change during optimization (#247).DspyAdapter: fixed a crash on outputs=None and a reflection_lm type mismatch (#320, @Archelunch).litellm, mlflow, and requests floors to address Dependabot alerts (#322). If you install gepa[full], this raises the litellm floor to ≥1.83.track_best_outputs now defaults to True (#286). Best outputs are retained on the result object by default, which is what most users expect when inspecting results — but it increases memory use for large valsets. Pass track_best_outputs=False to restore the old behavior, especially if you embed GEPA inside a training loop.run_dir with v0.1.2 is supported. Note that a state written by v0.1.2 is not designed to be loaded by v0.1.1 — finish in-flight runs on the version that started them, or upgrade before resuming.full extra was restructured (#322 and packaging cleanups); if you previously pinned workarounds for 3.14, they should no longer be necessary.optimize_anything can generate and evaluate multiple candidate proposals per iteration via EngineConfig.num_parallel_proposals. This interface is experimental and will change: per RFC #329, the next minor release replaces the integer knob with composable sampling/selection strategies (see #369), with a deprecation shim for one release. Use it, but don't build durable config around the parameter name.optimize_anything runs, merge-proposal events do not yet fire GEPACallback hooks (the callback plumbing from #290 does not reach the merge proposer). Mutation/iteration events are unaffected. A fix is queued for the next release.@Shangyint, @lukedhlee, @bryonkucharski, @rodolfo-nobrega, @Archelunch, and @arnaudleg for code contributions in this release, and everyone who filed the issues these fixes came from.
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.1.1...v0.1.2
Candidate Tree Visualization — GEPA now generates an interactive HTML lineage tree of all candidates explored during optimization. Nodes are color-cod
Candidate Tree Visualization — GEPA now generates an interactive HTML lineage tree of all candidates explored during optimization. Nodes are color-coded by role (best, Pareto front, seed) with hover previews and click-to-pin tooltips for reading full prompt text. The tree is automatically logged to WandB and MLflow at each step — no configuration needed. (#256)
gskill: Automated Skill Learning for Coding Agents — A new gepa.gskill module that uses optimize_anything to automatically discover and learn repository-specific skills for coding agents, powered by SWE-smith and Docker. (#213)
Top-K Pareto Candidate Selector — New candidate_selection_strategy="top_k_pareto" limits parent selection to the top-K candidates by aggregate score (default K=5), focusing mutation effort on the most promising programs. (#246)
EngineConfig now defaults to parallel=True with max_workers=os.cpu_count(). No configuration changes needed. (#240)os.replace(), preventing corruption on interrupted runs. (#242)run_log.json and candidates.json are now written to the run directory after each state save, enabling post-hoc analysis without extra code. (#245)on_optimization_start now fires before seed valset evaluation, not after. (#244)cloudpickle is now a proper dependency in the full extras group — use_cloudpickle=True no longer raises ModuleNotFoundError. (#242)optimize_anything example suites: AIME math, ARC-AGI, circle packing, and blackbox optimization. (#234)Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.1.0...v0.1.1
Introducing optimize_anything, GEPA's new API for optimizing any text parameter. Checkout the blogpost at https://gepa-ai.github.io/gepa/blog/2026/02/
Introducing optimize_anything, GEPA's new API for optimizing any text parameter. Checkout the blogpost at https://gepa-ai.github.io/gepa/blog/2026/02/18/introducing-optimize-anything/
optimize_anything: unified high-level API for GEPA by @LakshyAAAgrawal in https://github.com/gepa-ai/gepa/pull/204optimize_anything and GEPA for Agent Skills Optimization by @LakshyAAAgrawal in https://github.com/gepa-ai/gepa/pull/214Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.27...v0.1.0
Update README by @LakshyAAAgrawal in https://github.com/gepa-ai/gepa/pull/174
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.26...v0.0.27
Add cache by @LakshyAAAgrawal in https://github.com/gepa-ai/gepa/pull/166
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.25...v0.0.26
Add Python 3.14 support by @Copilot in https://github.com/gepa-ai/gepa/pull/165
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.24...v0.0.25
Allow for objective and hybrid pareto frontier tracking by @MatsErdkamp in https://github.com/gepa-ai/gepa/pull/92
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.23...v0.0.24
Update README.md by @LakshyAAAgrawal in https://github.com/gepa-ai/gepa/pull/135
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.22...v0.0.23
Skip components that are not present in reflective dataset instead of raising KeyError failure by @heyalexchoi in https://github.com/gepa-ai/gepa/pull
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.21...v0.0.22
Add logging option for individual valset scores by @LakshyAAAgrawal in https://github.com/gepa-ai/gepa/pull/131
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.20...v0.0.21
Enhance types by @mwildehahn in https://github.com/gepa-ai/gepa/pull/93
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.19...v0.0.20
Dynamic Validation in GEPAState by @aria42 in https://github.com/gepa-ai/gepa/pull/100
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.18...v0.0.19
Mock wandb and mlflow instead of testing storage by @TomeHirata in https://github.com/gepa-ai/gepa/pull/89
reflection_prompt_template parameter to optimize function by @CDBiddulph in https://github.com/gepa-ai/gepa/pull/91Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.17...v0.0.18
Add reference to ATLAS+GEPA for incident diagnosis by @LakshyAAAgrawal in https://github.com/gepa-ai/gepa/pull/84
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.16...v0.0.17
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.15...v0.0.16
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.15...v0.0.16
Add link for 100% accuracy using GEPA on clock-hands problem by @LakshyAAAgrawal in https://github.com/gepa-ai/gepa/pull/78
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.14...v0.0.15-alpha.1
Add max candidates stopper by @LakshyAAAgrawal in https://github.com/gepa-ai/gepa/pull/77
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.13...v0.0.14
Add link for multi-agent system in healthcare using DSPy by @LakshyAAAgrawal in https://github.com/gepa-ai/gepa/pull/68
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.12...v0.0.13
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.11...v0.0.12
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.11...v0.0.12
Add video link to README by @LakshyAAAgrawal in https://github.com/gepa-ai/gepa/pull/63
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.10...v0.0.11
Introduce mlflow by @TomeHirata in https://github.com/gepa-ai/gepa/pull/51
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.9...v0.0.10
Added google-auth as dependency to make LiteLLM Google Vertex-friendly ... by @egmaminta in https://github.com/gepa-ai/gepa/pull/41
google-auth as dependency to make LiteLLM Google Vertex-friendly ... by @egmaminta in https://github.com/gepa-ai/gepa/pull/41Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.8...v0.0.9
feat: improved the README.md for AnyMaths; fixed AnyMathsAdapter code; provided example training and dataset preparation; added eval results and sampl
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.7...v0.0.8
Fix TQDM by @LakshyAAAgrawal in https://github.com/gepa-ai/gepa/pull/32
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.6...v0.0.7
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.5...v0.0.6
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.5...v0.0.6
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.6-alpha.2...v0.0.6-alpha.3
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.6-alpha.2...v0.0.6-alpha.3
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.6-alpha.1...v0.0.6-alpha.2
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.6-alpha.1...v0.0.6-alpha.2
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.5...v0.0.6-alpha.1
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.5...v0.0.6-alpha.1
Nothing published for this version
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.5-alpha.12...v0.0.5-alpha.13
Full Changelog: https://github.com/gepa-ai/gepa/compare/v0.0.5-alpha.12...v0.0.5-alpha.13
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
One column per month.