Optimize any text parameter — prompts, code, agent architectures, configurations — using LLM-based reflection and Pareto-efficient evolutionary search.
Website | Quick Start | Paper | Blog | Discord
GEPA (Genetic-Pareto) is a framework for optimizing any system with textual parameters against any evaluation metric. Unlike RL or gradient-based methods that collapse execution traces into a single scalar reward, GEPA uses LLMs to read full execution traces — error messages, profiling data, reasoning logs — to diagnose why a candidate failed and propose targeted fixes. Through iterative reflection, mutation, and Pareto-aware selection, GEPA evolves high-performing variants with minimal evaluations.
If you can measure it, you can optimize it: prompts, code, agent architectures, scheduling policies, vector graphics, and more.
| 90x cheaper | Open-source models + GEPA beat Claude Opus 4.1 at Databricks |
| 35x faster than RL | 100–500 evaluations vs. 5,000–25,000+ for GRPO (paper) |
| 32% → 89% | ARC-AGI agent accuracy via architecture discovery |
| 40.2% cost savings | Cloud scheduling policy discovered by GEPA, beating expert heuristics |
| 55% → 82% | Coding agent resolve rate on Jinja via auto-learned skills |
| 50+ production uses | Across Shopify, Databricks, Dropbox, OpenAI, Pydantic, MLflow, Comet ML, and more |
"Both DSPy and (especially) GEPA are currently severely under hyped in the AI context engineering world" — Tobi Lutke, CEO, Shopify
pip install gepa
To install the latest from main:
pip install git+https://github.com/gepa-ai/gepa.git
Optimize a system prompt for math problems from the AIME benchmark in a few lines of code (full tutorial):
import gepa
trainset, valset, _ = gepa.examples.aime.init_dataset()
seed_prompt = {
"system_prompt": "You are a helpful assistant. Answer the question. "
"Put your final answer in the format '### <answer>'"
}
result = gepa.optimize(
seed_candidate=seed_prompt,
trainset=trainset,
valset=valset,
task_lm="openai/gpt-4.1-mini",
max_metric_calls=150,
reflection_lm="openai/gpt-5",
)
print("Optimized prompt:", result.best_candidate['system_prompt'])
Result: GPT-4.1 Mini goes from 46.6% → 56.6% on AIME 2025 (+10 percentage points).
The most powerful way to use GEPA for prompt optimization is within DSPy, where it's available as dspy.GEPA. See dspy.GEPA tutorials for executable notebooks.
import dspy
optimizer = dspy.GEPA(
metric=your_metric,
max_metric_calls=150,
reflection_lm="openai/gpt-5",
)
optimized_program = optimizer.compile(student=MyProgram(), trainset=trainset, valset=valset)
The optimize_anything API optimizes any text artifact — code, agent architectures, configurations, SVGs — not just prompts. You provide an evaluator; the system handles the search.
import gepa.optimize_anything as oa
from gepa.optimize_anything import optimize_anything, GEPAConfig, EngineConfig
def evaluate(candidate: str) -> float:
result = run_my_system(candidate)
oa.log(f"Output: {result.output}") # Actionable Side Information
oa.log(f"Error: {result.error}") # feeds back into reflection
return result.score
result = optimize_anything(
seed_candidate="<your initial artifact>",
evaluator=evaluate,
objective="Describe what you want to optimize for.",
config=GEPAConfig(engine=EngineConfig(max_metric_calls=100)),
)
Traditional optimizers know that a candidate failed but not why. GEPA takes a different approach:
GEPA also supports system-aware merge — combining strengths of two Pareto-optimal candidates excelling on different tasks. The key concept is Actionable Side Information (ASI): diagnostic feedback returned by evaluators that serves as the text-optimization analogue of a gradient.
For details, see the paper and the documentation.
GEPA connects to your system via the GEPAAdapter interface — implement evaluate and make_reflective_dataset, and GEPA handles the rest.
Built-in adapters:
| Adapter | Description |
|---|---|
| DefaultAdapter | System prompt optimization for single-turn LLM tasks |
| DSPy Full Program | Evolves entire DSPy programs (signatures, modules, control flow). 67% → 93% on MATH. |
| Generic RAG | Vector store-agnostic RAG optimization (ChromaDB, Weaviate, Qdrant, Pinecone) |
| MCP Adapter | Optimize MCP tool descriptions and system prompts |
| TerminalBench | Optimize the Terminus terminal-use agent |
| AnyMaths | Mathematical problem-solving and reasoning tasks |
See the adapters guide for how to build your own, and DSPy's adapter as a reference.
GEPA is integrated into several major frameworks:
dspy.GEPA for optimizing DSPy programs. Tutorials.mlflow.genai.optimize_prompts() for automatic prompt improvement.GEPA can be thought of as precomputing reasoning during optimization to produce a plan for future task instances. Here are examples of the detailed prompts GEPA discovers:
| Example GEPA Prompts | |
| HotpotQA (multi-hop QA) Prompt | AIME Prompt |
Click to view full HotpotQA prompt[HotpotQA Prompt Begin]You will be given two input fields: Your task is to generate a new search query ( Detailed task instructions and hints:
By following these principles, you will help the multi-hop retrieval system find all necessary documents to answer the multi-faceted original question completely. [HotpotQA Prompt End] |
Click to view full AIME prompt[AIME Prompt Begin] You will be given one math problem as plain text under a key like "problem." Your job is to solve it correctly and return:
Formatting:
General problem-solving guidance:
Domain-specific strategies and pitfalls (learned from typical contest problems and prior feedback):
Quality checks:
Finally:
[AIME Prompt End] |
mlflow.genai.optimize_prompts() API for automatic prompt improvement using evaluation metrics and training data. Works with any agent framework and supports multi-prompt optimization.We welcome adapters, bug fixes, and new use cases. See src/gepa/adapters/ for adapter examples and the contributing guide.
Want to highlight your use case? Reach out to lakshyaaagrawal@berkeley.edu or submit via GitHub.
@misc{agrawal2025gepareflectivepromptevolution,
title={GEPA: Reflective Prompt Evolution Can Outperform Reinforcement Learning},
author={Lakshya A Agrawal and Shangyin Tan and Dilara Soylu and Noah Ziems and Rishi Khare and Krista Opsahl-Ong and Arnav Singhvi and Herumb Shandilya and Michael J Ryan and Meng Jiang and Christopher Potts and Koushik Sen and Alexandros G. Dimakis and Ion Stoica and Dan Klein and Matei Zaharia and Omar Khattab},
year={2025},
eprint={2507.19457},
archivePrefix={arXiv},
primaryClass={cs.CL},
url={https://arxiv.org/abs/2507.19457},
}
(top 30 of 31)
Jupyter Notebook
72.0%
Python
27.8%
Optimize any text parameter — prompts, code, agent architectures, configurations — using LLM-based reflection and Pareto-efficient evolutionary search.
Website | Quick Start | Paper | Blog | Discord
GEPA (Genetic-Pareto) is a framework for optimizing any system with textual parameters against any evaluation metric. Unlike RL or gradient-based methods that collapse execution traces into a single scalar reward, GEPA uses LLMs to read full execution traces — error messages, profiling data, reasoning logs — to diagnose why a candidate failed and propose targeted fixes. Through iterative reflection, mutation, and Pareto-aware selection, GEPA evolves high-performing variants with minimal evaluations.
If you can measure it, you can optimize it: prompts, code, agent architectures, scheduling policies, vector graphics, and more.
| 90x cheaper | Open-source models + GEPA beat Claude Opus 4.1 at Databricks |
| 35x faster than RL | 100–500 evaluations vs. 5,000–25,000+ for GRPO (paper) |
| 32% → 89% | ARC-AGI agent accuracy via architecture discovery |
| 40.2% cost savings | Cloud scheduling policy discovered by GEPA, beating expert heuristics |
| 55% → 82% | Coding agent resolve rate on Jinja via auto-learned skills |
| 50+ production uses | Across Shopify, Databricks, Dropbox, OpenAI, Pydantic, MLflow, Comet ML, and more |
"Both DSPy and (especially) GEPA are currently severely under hyped in the AI context engineering world" — Tobi Lutke, CEO, Shopify
pip install gepa
To install the latest from main:
pip install git+https://github.com/gepa-ai/gepa.git
Optimize a system prompt for math problems from the AIME benchmark in a few lines of code (full tutorial):
import gepa
trainset, valset, _ = gepa.examples.aime.init_dataset()
seed_prompt = {
"system_prompt": "You are a helpful assistant. Answer the question. "
"Put your final answer in the format '### <answer>'"
}
result = gepa.optimize(
seed_candidate=seed_prompt,
trainset=trainset,
valset=valset,
task_lm="openai/gpt-4.1-mini",
max_metric_calls=150,
reflection_lm="openai/gpt-5",
)
print("Optimized prompt:", result.best_candidate['system_prompt'])
Result: GPT-4.1 Mini goes from 46.6% → 56.6% on AIME 2025 (+10 percentage points).
The most powerful way to use GEPA for prompt optimization is within DSPy, where it's available as dspy.GEPA. See dspy.GEPA tutorials for executable notebooks.
import dspy
optimizer = dspy.GEPA(
metric=your_metric,
max_metric_calls=150,
reflection_lm="openai/gpt-5",
)
optimized_program = optimizer.compile(student=MyProgram(), trainset=trainset, valset=valset)
The optimize_anything API optimizes any text artifact — code, agent architectures, configurations, SVGs — not just prompts. You provide an evaluator; the system handles the search.
import gepa.optimize_anything as oa
from gepa.optimize_anything import optimize_anything, GEPAConfig, EngineConfig
def evaluate(candidate: str) -> float:
result = run_my_system(candidate)
oa.log(f"Output: {result.output}") # Actionable Side Information
oa.log(f"Error: {result.error}") # feeds back into reflection
return result.score
result = optimize_anything(
seed_candidate="<your initial artifact>",
evaluator=evaluate,
objective="Describe what you want to optimize for.",
config=GEPAConfig(engine=EngineConfig(max_metric_calls=100)),
)
Traditional optimizers know that a candidate failed but not why. GEPA takes a different approach:
GEPA also supports system-aware merge — combining strengths of two Pareto-optimal candidates excelling on different tasks. The key concept is Actionable Side Information (ASI): diagnostic feedback returned by evaluators that serves as the text-optimization analogue of a gradient.
For details, see the paper and the documentation.
GEPA connects to your system via the GEPAAdapter interface — implement evaluate and make_reflective_dataset, and GEPA handles the rest.
Built-in adapters:
| Adapter | Description |
|---|---|
| DefaultAdapter | System prompt optimization for single-turn LLM tasks |
| DSPy Full Program | Evolves entire DSPy programs (signatures, modules, control flow). 67% → 93% on MATH. |
| Generic RAG | Vector store-agnostic RAG optimization (ChromaDB, Weaviate, Qdrant, Pinecone) |
| MCP Adapter | Optimize MCP tool descriptions and system prompts |
| TerminalBench | Optimize the Terminus terminal-use agent |
| AnyMaths | Mathematical problem-solving and reasoning tasks |
See the adapters guide for how to build your own, and DSPy's adapter as a reference.
GEPA is integrated into several major frameworks:
dspy.GEPA for optimizing DSPy programs. Tutorials.mlflow.genai.optimize_prompts() for automatic prompt improvement.GEPA can be thought of as precomputing reasoning during optimization to produce a plan for future task instances. Here are examples of the detailed prompts GEPA discovers:
| Example GEPA Prompts | |
| HotpotQA (multi-hop QA) Prompt | AIME Prompt |
Click to view full HotpotQA prompt[HotpotQA Prompt Begin]You will be given two input fields: Your task is to generate a new search query ( Detailed task instructions and hints:
By following these principles, you will help the multi-hop retrieval system find all necessary documents to answer the multi-faceted original question completely. [HotpotQA Prompt End] |
Click to view full AIME prompt[AIME Prompt Begin] You will be given one math problem as plain text under a key like "problem." Your job is to solve it correctly and return:
Formatting:
General problem-solving guidance:
Domain-specific strategies and pitfalls (learned from typical contest problems and prior feedback):
Quality checks:
Finally:
[AIME Prompt End] |
mlflow.genai.optimize_prompts() API for automatic prompt improvement using evaluation metrics and training data. Works with any agent framework and supports multi-prompt optimization.We welcome adapters, bug fixes, and new use cases. See src/gepa/adapters/ for adapter examples and the contributing guide.
Want to highlight your use case? Reach out to lakshyaaagrawal@berkeley.edu or submit via GitHub.
@misc{agrawal2025gepareflectivepromptevolution,
title={GEPA: Reflective Prompt Evolution Can Outperform Reinforcement Learning},
author={Lakshya A Agrawal and Shangyin Tan and Dilara Soylu and Noah Ziems and Rishi Khare and Krista Opsahl-Ong and Arnav Singhvi and Herumb Shandilya and Michael J Ryan and Meng Jiang and Christopher Potts and Koushik Sen and Alexandros G. Dimakis and Ion Stoica and Dan Klein and Matei Zaharia and Omar Khattab},
year={2025},
eprint={2507.19457},
archivePrefix={arXiv},
primaryClass={cs.CL},
url={https://arxiv.org/abs/2507.19457},
}
(top 30 of 31)
Jupyter Notebook
72.0%
Python
27.8%