GEPA

GEPA (Genetic-Pareto) is a framework for optimizing any system with textual parameters against any evaluation metric. Instead of collapsing execution traces into a single scalar reward, it uses LLMs to read full traces — error messages, logs, reasoning — to diagnose why a candidate failed and propose targeted edits, then evolves high-performing variants through reflection, mutation, and Pareto-aware selection.

If you can measure it, you can optimize it: GEPA has been applied to prompts, code snippets, agent architectures, scheduling policies, and more, often reaching strong results with only hundreds of evaluations. It exposes a small optimize API plus pluggable adapters for integrating with frameworks like DSPy.

What You Get

• A single optimize entry point for improving any text-parameterized system
• LLM-based reflection that reads full execution traces to diagnose failures
• Pareto-efficient evolutionary search that finds strong variants in few evaluations
• Pluggable adapters for systems like DSPy and custom evaluation harnesses
• Worked examples and datasets (e.g. AIME) plus extensive documentation

Common Use Cases

• Optimizing system prompts for LLM tasks against a benchmark metric
• Discovering and refining agent architectures or tool-use strategies
• Improving code snippets, configs, or policies where quality is measurable

Under The Hood

Architecture - The codebase is organized under src/gepa/ into a core optimization engine, strategies (candidate/component selection), proposer (mutation/merge including reflective proposers), adapters (integration points like DSPy and custom systems), plus examples, utils, and logging. The public gepa.optimize(...) API wires a seed candidate, a dataset, and an adapter into the evolutionary loop; the adapter is the inversion-of-control boundary that runs and scores each candidate.

Tech Stack - Pure Python packaged with pyproject.toml (uv lockfile present), targeting LLM providers for the reflection step. Docs are built with MkDocs and the repo includes Jupyter-notebook examples (hence GitHub’s language detection). Optional integrations include DSPy.

Code Quality - A tests/ suite is present, pyright is configured (pyrightconfig.json), and the project ships contributor docs (AGENTS.md, CLAUDE.md, CONTRIBUTING.md). Development is very active with consistent maintenance.

API Design - The headline API is deliberately compact — a few lines to optimize a prompt — while advanced use is expressed through adapters and proposers. Naming maps to the paper’s concepts (Pareto selection, reflective mutation), and quickstart plus tutorials keep the initial learning curve moderate despite the conceptual depth.