gepa-ai/gepa

Optimize any text parameter — prompts, code, agent architectures, configurations — using LLM-based reflection and Pareto-efficient evolutionary search.

Website  |  Quick Start  |  Paper  |  Blog  |  Discord

What is GEPA?

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.

Key Results

"Both DSPy and (especially) GEPA are currently severely under hyped in the AI context engineering world" — Tobi Lutke, CEO, Shopify

Installation

pip install gepa

To install the latest from main:

pip install git+https://github.com/gepa-ai/gepa.git

Quick Start

Simple Prompt Optimization

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).

With DSPy (Recommended for AI Pipelines)

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)

optimize_anything: Beyond Prompts

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)),
)

How It Works

Traditional optimizers know that a candidate failed but not why. GEPA takes a different approach:

1. Select a candidate from the Pareto frontier (candidates excelling on different task subsets)
2. Execute on a minibatch, capturing full execution traces
3. Reflect — an LLM reads the traces (error messages, profiler output, reasoning logs) and diagnoses failures
4. Mutate — generate an improved candidate informed by accumulated lessons from all ancestors
5. Accept — add to the pool if improved, update the Pareto front

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.

Adapters: Plug GEPA into Any System

GEPA connects to your system via the GEPAAdapter interface — implement evaluate and make_reflective_dataset, and GEPA handles the rest.

Built-in adapters:

See the adapters guide for how to build your own, and DSPy's adapter as a reference.

Integrations

GEPA is integrated into several major frameworks:

• DSPy — dspy.GEPA for optimizing DSPy programs. Tutorials.
• MLflow — mlflow.genai.optimize_prompts() for automatic prompt improvement.
• Comet ML Opik — Core optimization algorithm in Opik Agent Optimizer.
• Pydantic — Prompt optimization for Pydantic AI.
• OpenAI Cookbook — Self-evolving agents with GEPA.
• HuggingFace Cookbook — Prompt optimization guide.
• Google ADK / Gemini Enterprise Agent Platform — adk optimize powered by GEPA, also shipped inside Google Cloud's Gemini Enterprise Agent Platform Quality Flywheel. ADK docs · Community tutorial.
• Microsoft AI: MAI-Thinking-1 — Uses GEPA / DSPy to optimize the Qwen3-30B LLM-judge prompt that filters Code pages in the model's pre-training pipeline (~233B tokens of curated data).

Example Optimized Prompts

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: question and summary_1. Your task is to generate a new search query (query) optimized for the second hop of a multi-hop retrieval system. The original user question is typically complex and requires information from multiple documents to answer. The first hop query is the original question used to retrieve an initial set of documents. Your goal is to generate a second hop query that retrieves additional relevant documents that were not found in the first hop but are necessary to answer the original question completely. Detailed task instructions and hints: Input Understanding: question is the original multi-hop question posed by the user. summary_1 is a concise summary of information from a document retrieved in the first hop, which partially addresses the question. Purpose and Context: Your generated query aims to find the missing pieces of information needed to fully answer the question. The multi-hop retrieval system works in stages: First hop: The original question returns some documents. Second hop: Your query must help retrieve any other relevant documents NOT found in the first hop that hold complementary or broader context necessary for final answer extraction. Key Observations from Examples and Feedback: First-hop documents often cover one entity or aspect in the question. Remaining relevant documents often involve connected or higher-level concepts mentioned in summary_1 but not explicitly asked in the original question. The query should be formulated to explicitly target these missing, but logically linked, documents. Avoid merely paraphrasing the original question or restating known facts from summary_1. Instead, infer what broader or related entities/concepts might provide the crucial missing information. For example, if summary_1 describes a population for a small civil parish, but the question wants total population of the wider region, your query should target that wider region (e.g., "Madeira archipelago population in 2011"). Similarly, if summary_1 covers a song and the question wants the album it came from, but first hop got song-level documents, your query should retrieve documents about the album itself. How to Build the Query: Identify the entities or topics mentioned in summary_1 that appear related but different from first-hop documents. Reframe the query to explicitly mention these broader or related entities connected to the original question. Include relevant key context from the question to maintain specificity, but shift focus to the missing piece. The goal is to retrieve documents that link or complement what was retrieved initially. Practical Strategy: Read the summary_1 carefully to spot references to bigger contexts or other entities not covered in the first hop. Ask yourself, "What entity or aspect does this summary hint at that could answer the original question but was not found yet?" Formulate a precise, focused factual query targeting that entity or concept to retrieve the missing documents. Output: Produce only the field query as a clear, concise question or keyword phrase designed for efficient retrieval of second-hop documents. Ensure the query relates logically to the original question while targeting the broader or complementary knowledge identified in summary_1. Do not include the original question or simply rephrase it. Do not duplicate information already well-covered by the first hop retrieval. 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]