How gepa-ai/gepa works
1. What this repository is
- gepa is a Python optimization framework for evolving textual artifacts: prompts, DSPy programs, RAG pipelines, agent configs, tool descriptions, and similar “text parameters.”
- The architecture centers on a search loop that repeatedly evaluates candidates, captures diagnostics, reflects on failures with an LLM, and mutates the candidate toward better performance.
2. Top-level package boundary
- The installable library lives under src/gepa/.
- The package exports a small public surface in src/gepa/api.py and module entry points like src/gepa/optimize_anything.py, while most implementation details are split into core engine, adapters, proposers, strategies, logging, and utilities.
- This is not a web service; it is a Python library with example runners, notebooks, docs, and tests.
3. Core optimization engine
- src/gepa/core/engine.py is the orchestration center.
- Core types in src/gepa/core/state.py, result.py, data_loader.py, and callbacks.py represent the optimization state, intermediate results, batch loading, and lifecycle events.
- The engine coordinates evaluation, selection, proposal generation, acceptance, stopping, and persistence of optimization progress.
4. Adapter boundary: how GEPA plugs into external systems
- The key abstraction is GEPAAdapter in src/gepa/core/adapter.py.
- Adapters define how a target system is evaluated and how reflective training data is built from execution traces or side information.
- Built-in adapters under src/gepa/adapters/ are the main integration boundary to external ecosystems:
- default prompt optimization
- confidence-aware classification
- DSPy and DSPy full-program evolution
- generic RAG with multiple vector stores
- MCP tool-use optimization
- TerminalBench/Terminus
- LangChain
- AnyMaths
- optimize-anything adapter
5. Search and mutation subsystem
- src/gepa/proposer/ contains the proposal logic that creates new candidate variants.
- merge.py handles combining promising candidates.
- reflective_mutation/ implements the LLM-driven mutation path that uses accumulated feedback to produce improved candidates.
- This subsystem is the “generator” side of the optimization loop.
6. Selection and evaluation policies
- src/gepa/strategies/ contains the policies that decide what gets evaluated and what gets promoted:
- candidate selection
- component selection
- batch sampling
- acceptance criteria
- evaluation policies
- instruction proposal helpers
- This layer is where Pareto-aware or exploration-vs-exploitation behavior is encoded, separate from the engine and adapter logic.
7. Evaluation data and feedback flow
- The main data flow is: seed candidate → adapter evaluation → captured traces/metrics → reflective dataset → proposer mutation → new candidate.
- src/gepa/core/data_loader.py and adapter-specific code shape training/validation/evaluation splits into the form expected by the optimizer.
- The README’s “Actionable Side Information” concept maps to the data returned by evaluators and passed back into reflection, not just scalar scores.
8. Logging, callbacks, and experiment tracking
- src/gepa/logging/ and src/gepa/core/callbacks.py provide observability around the optimization loop.
- Callback events cover optimization start/end, iteration start/end, evaluation start/end, candidate accepted/rejected, merge events, Pareto updates, state save, and error reporting.
- Logging is a first-class boundary because GEPA relies on trace-rich feedback for human inspection and for LLM reflection.
9. Optimize-anything API as a generic front door
- src/gepa/optimize_anything.py exposes a framework-agnostic API for optimizing arbitrary text artifacts.
- It wraps the core engine with a simpler interface: a seed candidate, an evaluator function, an objective string, and config objects.
- This is the “universal” entry point for non-DSPy users and for problems where the artifact is not a prompt.
10. Specialized gskill subsystem
- src/gepa/gskill/ is a more specialized application layer focused on coding-agent / SWE-style skill optimization.
- It includes experiment logging, cost tracking, harnesses, and evaluation helpers for Claude Code / Mini SWE Agent workflows.
- This looks like a domain-specific package built on top of the same GEPA ideas, not the core optimizer itself.
11. Examples as integration blueprints
- examples/ contains runnable end-to-end projects showing how the engine is used in practice.
- These cover AIME math, ARC-AGI, blackbox optimization, circle packing, confidence-aware classification, LangChain, and two ADR-style simulations.
- The examples are useful architectural references because they show how adapters, datasets, and LMs are composed around the core optimizer.
12. Documentation and generated API surface
- docs/ is a full MkDocs site with guides, API references, blog posts, and tutorials.
- docs/scripts/generate_api_docs.py suggests the API reference is generated from source structure.
- The docs folder is part of the project’s distribution story and mirrors the library’s subsystem boundaries.
13. Testing and quality gates
- tests/ is broad and integration-heavy, covering core optimization, adapters, caching, selection policies, callbacks, logging, visualization, and end-to-end prompt optimization.
- pyrightconfig.json, .pre-commit-config.yaml, and pyproject.toml indicate static typing and formatting/linting are part of the architecture.
- GitHub Actions workflows handle tests, docs generation, and build/release automation.
14. How to draw the main architecture
- At the center, draw the optimization engine.
- Feed it from the left with seed candidates, datasets, and evaluator/adapter implementations.
- Surround it with strategies/proposers that decide sampling, selection, acceptance, and mutation.
- Route all runs through logging/callbacks/state for observability and persistence.
- Show examples, docs, and tests as outer layers demonstrating and validating the same core workflow.
Main entry points: engine.py Engine · __init__.py Strategies · adapter.py Adapter · tests Tests
Components 23
Core engine
Optimization orchestration, state, results, and adapter boundary.
- Engine · Coordinates evaluation, proposal, acceptance, stopping, and persistence.
src/gepa/core/engine.py - Adapter · Defines how a target system is evaluated and traced for reflection.
src/gepa/core/adapter.py - State · Optimization state and progress snapshots.
src/gepa/core/state.py - Result · Final and intermediate optimization outputs.
src/gepa/core/result.py - Data loader · Shapes datasets and splits into optimizer-ready batches.
src/gepa/core/data_loader.py
Search loop
Candidate generation, mutation, and selection policies.
- Proposer · Creates new candidate variants from feedback and merges.
src/gepa/proposer/base.py - Merge · Combines promising candidates into a stronger variant.
src/gepa/proposer/merge.py - Reflective mutation · LLM-driven mutation path using accumulated feedback.
src/gepa/proposer/reflective_mutation/reflective_mutation.py - Strategies · Candidate selection, batch sampling, acceptance, and evaluation policies.
src/gepa/strategies/__init__.py
Integrations
Built-in adapters and framework-specific integration layers.
- Default adapter · Baseline prompt optimization adapter.
src/gepa/adapters/default_adapter/default_adapter.py - DSPy adapter · Adapter for DSPy modules and instruction proposal helpers.
src/gepa/adapters/dspy_adapter/dspy_adapter.py - DSPy full program · Evolves full DSPy programs rather than only prompts.
src/gepa/adapters/dspy_full_program_adapter/full_program_adapter.py - RAG adapter · Generic RAG integration with multiple vector store backends.
src/gepa/adapters/generic_rag_adapter/generic_rag_adapter.py - MCP adapter · MCP tool-use optimization and client boundary.
src/gepa/adapters/mcp_adapter/mcp_adapter.py
Public surface
Library entry points and generic front doors.
- API · Small public surface for the installable library.
src/gepa/api.py - Optimize anything · Framework-agnostic API for optimizing arbitrary text artifacts.
src/gepa/optimize_anything.py
Observability
Logging, callbacks, and experiment tracking.
- Callbacks · Optimization, iteration, evaluation, merge, and error events.
src/gepa/core/callbacks.py - Logging · Experiment tracking and structured logging around optimization runs.
src/gepa/logging/logger.py - Tracker · Experiment tracking and run persistence utilities.
src/gepa/logging/experiment_tracker.py
Domain layer
Specialized skill-optimization package built on GEPA.
- gskill · Coding-agent and SWE-style skill optimization utilities.
src/gepa/gskill/gskill/__init__.py
Connections 29
- API → Engine: exposes · Public API routes callers toward the core optimizer.
- Optimize anything → Engine: wraps · Generic entry point wraps the core orchestration loop.
- Engine → Adapter: evaluates via · Engine delegates task-specific execution and trace capture to adapters.
- Engine → State: reads/writes · Optimization progress is stored in state snapshots.
- Engine → Result: produces · Engine emits final and intermediate results.
- Engine → Data loader: loads batches · Dataset splitting and batch shaping feed evaluation.
- Engine → Callbacks: emits events · Lifecycle events support logging, persistence, and inspection.
- Engine → Strategies: uses policies · Selection, acceptance, and sampling decisions are policy-driven.
- Engine → Proposer: asks for candidates · Engine invokes proposal generation during search.
- Proposer → Merge: combines · Merge path consolidates promising candidates.
- Proposer → Reflective mutation: mutates · Reflective mutation uses feedback to produce improved candidates.
- Strategies → Proposer: guides · Selection policies steer which candidates get proposed or refined.
- Strategies → Data loader: samples from · Batch and evaluation policies influence what data is considered.
- Default adapter → Adapter: implements · Default prompt optimization is a concrete adapter.
- DSPy adapter → Adapter: implements · DSPy integration is a concrete adapter.
- DSPy full program → DSPy adapter: extends · Full-program evolution builds on DSPy integration concepts.
- RAG adapter → Adapter: implements · Generic RAG is a concrete adapter boundary.
- MCP adapter → Adapter: implements · MCP tool-use integration is a concrete adapter.
- Logging → Tracker: tracks · Logging layer connects to experiment tracking and persistence.
- Callbacks → Logging: feeds · Lifecycle events are consumed by loggers and trackers.
- gskill → Engine: builds on · Domain-specific skill optimization is layered on GEPA core.
- Examples → API: demonstrate · Example projects show public usage patterns.
- Examples → RAG adapter: showcase · Examples illustrate adapter-driven end-to-end workflows.
- Docs → API: documents · Docs mirror the library surface and subsystem boundaries.
- Docs → Strategies: explains · Guides describe selection, sampling, and acceptance policies.
- Tests → Engine: validates · Integration tests cover the optimization loop.
- Tests → RAG adapter: validates · Adapter tests exercise integration behavior.
- Tests → Callbacks: validates · Tests cover callback lifecycle and event emission.
- Tests → Strategies: validates · Tests cover policy behavior and selection logic.