# gepa

> A framework for optimizing textual system components (AI prompts, code snippets, etc.) using LLM-based reflection and Pareto-efficient evolutionary search.

- **URL**: https://www.freshcrate.ai/projects/gepa
- **Author**: pypi
- **Category**: Frameworks
- **Latest version**: `0.1.1` (2026-04-21)
- **License**: MIT
- **Source**: https://github.com/gepa-ai/gepa/issues
- **Homepage**: https://pypi.org/project/gepa/
- **Language**: Jupyter Notebook
- **GitHub**: 3,877 stars, 328 forks
- **Registry**: pypi (`gepa`)
- **Tags**: `pypi`

## Description

<p align="center">
  <img src="https://raw.githubusercontent.com/gepa-ai/gepa/refs/heads/main/assets/gepa_logo_with_text.svg" alt="GEPA Logo" width="450">
</p>

<p align="center">
  <strong>Optimize any text parameter — prompts, code, agent architectures, configurations — using LLM-based reflection and Pareto-efficient evolutionary search.</strong>
</p>

<p align="center">
  <a href="https://gepa-ai.github.io/gepa/"><strong>Website</strong></a> &ensp;|&ensp;
  <a href="https://gepa-ai.github.io/gepa/guides/quickstart/"><strong>Quick Start</strong></a> &ensp;|&ensp;
  <a href="https://arxiv.org/abs/2507.19457"><strong>Paper</strong></a> &ensp;|&ensp;
  <a href="https://gepa-ai.github.io/gepa/blog/"><strong>Blog</strong></a> &ensp;|&ensp;
  <a href="https://discord.gg/WXFSeVGdbW"><strong>Discord</strong></a>
</p>

<p align="center">
  <a href="https://pypi.org/project/gepa/"><img src="https://img.shields.io/pypi/v/gepa?logo=python&logoColor=white&color=3776ab" alt="PyPI"></a>
  <a href="https://pepy.tech/projects/gepa"><img src="https://static.pepy.tech/badge/gepa" alt="Downloads"></a>
  <a href="https://github.com/gepa-ai/gepa"><img src="https://img.shields.io/github/stars/gepa-ai/gepa?style=flat&logo=github&color=181717" alt="GitHub stars"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-green?style=flat" alt="License"></a>
</p>

<p align="center">
  <a href="https://join.slack.com/t/gepa-ai/shared_invite/zt-3o352xhyf-QZDfwmMpiQjsvoSYo7M1_w"><img src="https://badgen.net/badge/icon/Slack?icon=slack&label&color=4A154B" alt="Slack"></a>
  <a href="https://discord.gg/WXFSeVGdbW"><img src="https://dcbadge.limes.pink/api/server/https://discord.gg/WXFSeVGdbW?style=flat" alt="Discord"></a>
</p>

---

## 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

| | |
|---|---|
| **90x cheaper** | Open-source models + GEPA beat Claude Opus 4.1 at [Databricks](https://www.databricks.com/blog/building-state-art-enterprise-agents-90x-cheaper-automated-prompt-optimization) |
| **35x faster than RL** | 100–500 evaluations vs. 5,000–25,000+ for GRPO ([paper](https://arxiv.org/abs/2507.19457)) |
| **32% → 89%** | ARC-AGI agent accuracy via [architecture discovery](https://gepa-ai.github.io/gepa/blog/introducing-optimize-anything/#5-agent-architecture-discovery) |
| **40.2% cost savings** | Cloud scheduling policy [discovered by GEPA](https://gepa-ai.github.io/gepa/blog/introducing-optimize-anything/#3-systems-research), beating expert heuristics |
| **55% → 82%** | Coding agent resolve rate on Jinja via [auto-learned skills](https://gepa-ai.github.io/gepa/blog/automatically-learning-skills-for-coding-agents/) |
| **50+ production uses** | Across Shopify, Databricks, Dropbox, OpenAI, Pydantic, MLflow, Comet ML, and [more](https://gepa-ai.github.io/gepa/guides/use-cases/) |

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

---

## Installation

```bash
pip install gepa
```

To install the latest from `main`:

```bash
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](https://dspy.ai/tutorials/gepa_aime/)):

```python
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](https://dspy.ai/), where it's available as `dspy.GEPA`. See [dspy.GEPA tutorials](https://dspy.ai/tutorials/gepa_ai_program/) for executable notebooks.

```python
import dspy

optimizer = dspy.GEPA(
    metric=your_metric,
    max_metric_calls=150,
    reflection_lm="openai/gpt-5",
)
optimized

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `0.1.1` | 2026-04-21 | Low | Imported from PyPI (0.1.1) |
| `v0.1.1` | 2026-03-16 | Low | ### Highlights  **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](https://github.com/gepa-ai/gepa/pull/256))  **gskill: Automated Skill Learning for Coding Agents** — A new `gep |
| `v0.1.1` | 2026-03-16 | Low | ### Highlights  **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](https://github.com/gepa-ai/gepa/pull/256))  **gskill: Automated Skill Learning for Coding Agents** — A new `gep |
| `v0.1.1` | 2026-03-16 | Low | ### Highlights  **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](https://github.com/gepa-ai/gepa/pull/256))  **gskill: Automated Skill Learning for Coding Agents** — A new `gep |
| `v0.1.1` | 2026-03-16 | Low | ### Highlights  **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](https://github.com/gepa-ai/gepa/pull/256))  **gskill: Automated Skill Learning for Coding Agents** — A new `gep |
| `v0.1.1` | 2026-03-16 | Low | ### Highlights  **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](https://github.com/gepa-ai/gepa/pull/256))  **gskill: Automated Skill Learning for Coding Agents** — A new `gep |
| `v0.1.1` | 2026-03-16 | Low | ### Highlights  **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](https://github.com/gepa-ai/gepa/pull/256))  **gskill: Automated Skill Learning for Coding Agents** — A new `gep |
| `v0.1.1` | 2026-03-16 | Low | ### Highlights  **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](https://github.com/gepa-ai/gepa/pull/256))  **gskill: Automated Skill Learning for Coding Agents** — A new `gep |
| `v0.1.1` | 2026-03-16 | Low | ### Highlights  **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](https://github.com/gepa-ai/gepa/pull/256))  **gskill: Automated Skill Learning for Coding Agents** — A new `gep |
| `v0.1.1` | 2026-03-16 | Low | ### Highlights  **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](https://github.com/gepa-ai/gepa/pull/256))  **gskill: Automated Skill Learning for Coding Agents** — A new `gep |

## Citation

- HTML: https://www.freshcrate.ai/projects/gepa
- Markdown: https://www.freshcrate.ai/projects/gepa.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/gepa/deps

_Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._