# gepa-ai/gepa architecture

> Architecture diagram of the GitHub repository gepa-ai/gepa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gepa-ai/gepa
- Repository: https://github.com/gepa-ai/gepa
- Video tour (about a minute): https://gitdiagram.com/gepa-ai/gepa/video

## Overview

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: [`src/gepa/core/engine.py`](https://github.com/gepa-ai/gepa/blob/main/src/gepa/core/engine.py) (Engine), [`src/gepa/strategies/__init__.py`](https://github.com/gepa-ai/gepa/blob/main/src/gepa/strategies/__init__.py) (Strategies), [`src/gepa/core/adapter.py`](https://github.com/gepa-ai/gepa/blob/main/src/gepa/core/adapter.py) (Adapter), [`tests`](https://github.com/gepa-ai/gepa/tree/main/tests) (Tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_src_core["Core engine"]
  node_engine["Engine<br/>orchestrator<br/>[engine.py]"]
  node_adapter["Adapter<br/>integration contract<br/>[adapter.py]"]
  node_state["State<br/>[state.py]"]
  node_result["Result<br/>[result.py]"]
  node_data_loader["Data loader<br/>batching<br/>[data_loader.py]"]
end

subgraph group_src_search["Search loop"]
  node_proposer["Proposer<br/>candidate generation<br/>[base.py]"]
  node_merge["Merge<br/>[merge.py]"]
  node_reflective_mutation["Reflective mutation<br/>llm mutation"]
  node_strategies["Strategies<br/>selection policies<br/>[__init__.py]"]
end

subgraph group_src_integration["Integrations"]
  node_adapters_default["Default adapter<br/>prompt adapter<br/>[default_adapter.py]"]
  node_adapters_dspy["DSPy adapter<br/>dspy integration<br/>[dspy_adapter.py]"]
  node_adapters_dspy_full["DSPy full program<br/>program evolution"]
  node_adapters_rag["RAG adapter<br/>retrieval pipeline"]
  node_adapters_mcp["MCP adapter<br/>tool-use integration<br/>[mcp_adapter.py]"]
end

subgraph group_src_surface["Public surface"]
  node_api["API<br/>public exports<br/>[api.py]"]
  node_optimize_anything["Optimize anything<br/>generic entrypoint"]
end

subgraph group_src_obs["Observability"]
  node_callbacks["Callbacks<br/>lifecycle events<br/>[callbacks.py]"]
  node_logging["Logging<br/>observability<br/>[logger.py]"]
  node_tracker["Tracker<br/>experiment tracking"]
end

subgraph group_src_domain["Domain layer"]
  node_gskill["gskill<br/>domain layer<br/>[__init__.py]"]
end

subgraph group_outer["Project perimeter"]
  node_examples["Examples<br/>runnable demos"]
  node_docs["Docs"]
  node_tests["Tests<br/>quality gate"]
end

node_api -->|"exposes"| node_engine
node_optimize_anything -->|"wraps"| node_engine
node_engine -->|"evaluates via"| node_adapter
node_engine -->|"reads/writes"| node_state
node_engine -->|"produces"| node_result
node_engine -->|"loads batches"| node_data_loader
node_engine -->|"emits events"| node_callbacks
node_engine -->|"uses policies"| node_strategies
node_engine -->|"asks for candidates"| node_proposer
node_proposer -->|"combines"| node_merge
node_proposer -->|"mutates"| node_reflective_mutation
node_strategies -->|"guides"| node_proposer
node_strategies -->|"samples from"| node_data_loader
node_adapters_default -->|"implements"| node_adapter
node_adapters_dspy -->|"implements"| node_adapter
node_adapters_dspy_full -->|"extends"| node_adapters_dspy
node_adapters_rag -->|"implements"| node_adapter
node_adapters_mcp -->|"implements"| node_adapter
node_logging -->|"tracks"| node_tracker
node_callbacks -->|"feeds"| node_logging
node_gskill -->|"builds on"| node_engine
node_examples -->|"demonstrate"| node_api
node_examples -->|"showcase"| node_adapters_rag
node_docs -->|"documents"| node_api
node_docs -->|"explains"| node_strategies
node_tests -->|"validates"| node_engine
node_tests -->|"validates"| node_adapters_rag
node_tests -->|"validates"| node_callbacks
node_tests -->|"validates"| node_strategies

click node_api "https://github.com/gepa-ai/gepa/blob/main/src/gepa/api.py"
click node_optimize_anything "https://github.com/gepa-ai/gepa/blob/main/src/gepa/optimize_anything.py"
click node_engine "https://github.com/gepa-ai/gepa/blob/main/src/gepa/core/engine.py"
click node_adapter "https://github.com/gepa-ai/gepa/blob/main/src/gepa/core/adapter.py"
click node_state "https://github.com/gepa-ai/gepa/blob/main/src/gepa/core/state.py"
click node_result "https://github.com/gepa-ai/gepa/blob/main/src/gepa/core/result.py"
click node_data_loader "https://github.com/gepa-ai/gepa/blob/main/src/gepa/core/data_loader.py"
click node_callbacks "https://github.com/gepa-ai/gepa/blob/main/src/gepa/core/callbacks.py"
click node_logging "https://github.com/gepa-ai/gepa/blob/main/src/gepa/logging/logger.py"
click node_tracker "https://github.com/gepa-ai/gepa/blob/main/src/gepa/logging/experiment_tracker.py"
click node_proposer "https://github.com/gepa-ai/gepa/blob/main/src/gepa/proposer/base.py"
click node_merge "https://github.com/gepa-ai/gepa/blob/main/src/gepa/proposer/merge.py"
click node_reflective_mutation "https://github.com/gepa-ai/gepa/blob/main/src/gepa/proposer/reflective_mutation/reflective_mutation.py"
click node_strategies "https://github.com/gepa-ai/gepa/blob/main/src/gepa/strategies/__init__.py"
click node_adapters_default "https://github.com/gepa-ai/gepa/blob/main/src/gepa/adapters/default_adapter/default_adapter.py"
click node_adapters_dspy "https://github.com/gepa-ai/gepa/blob/main/src/gepa/adapters/dspy_adapter/dspy_adapter.py"
click node_adapters_dspy_full "https://github.com/gepa-ai/gepa/blob/main/src/gepa/adapters/dspy_full_program_adapter/full_program_adapter.py"
click node_adapters_rag "https://github.com/gepa-ai/gepa/blob/main/src/gepa/adapters/generic_rag_adapter/generic_rag_adapter.py"
click node_adapters_mcp "https://github.com/gepa-ai/gepa/blob/main/src/gepa/adapters/mcp_adapter/mcp_adapter.py"
click node_gskill "https://github.com/gepa-ai/gepa/blob/main/src/gepa/gskill/gskill/__init__.py"
click node_examples "https://github.com/gepa-ai/gepa/tree/main/examples"
click node_docs "https://github.com/gepa-ai/gepa/tree/main/docs"
click node_tests "https://github.com/gepa-ai/gepa/tree/main/tests"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_engine,node_adapter,node_state,node_result,node_data_loader,node_examples,node_docs,node_tests toneBlue
class node_proposer,node_merge,node_reflective_mutation,node_strategies toneAmber
class node_adapters_default,node_adapters_dspy,node_adapters_dspy_full,node_adapters_rag,node_adapters_mcp toneMint
class node_api,node_optimize_anything toneRose
class node_callbacks,node_logging,node_tracker toneIndigo
class node_gskill toneTeal
```

## Components

### Core engine

Optimization orchestration, state, results, and adapter boundary.

- [Engine](https://github.com/gepa-ai/gepa/blob/main/src/gepa/core/engine.py): orchestrator · Coordinates evaluation, proposal, acceptance, stopping, and persistence. · `src/gepa/core/engine.py`
- [Adapter](https://github.com/gepa-ai/gepa/blob/main/src/gepa/core/adapter.py): integration contract · Defines how a target system is evaluated and traced for reflection. · `src/gepa/core/adapter.py`
- [State](https://github.com/gepa-ai/gepa/blob/main/src/gepa/core/state.py): run state · Optimization state and progress snapshots. · `src/gepa/core/state.py`
- [Result](https://github.com/gepa-ai/gepa/blob/main/src/gepa/core/result.py): run result · Final and intermediate optimization outputs. · `src/gepa/core/result.py`
- [Data loader](https://github.com/gepa-ai/gepa/blob/main/src/gepa/core/data_loader.py): batching · Shapes datasets and splits into optimizer-ready batches. · `src/gepa/core/data_loader.py`

### Search loop

Candidate generation, mutation, and selection policies.

- [Proposer](https://github.com/gepa-ai/gepa/blob/main/src/gepa/proposer/base.py): candidate generation · Creates new candidate variants from feedback and merges. · `src/gepa/proposer/base.py`
- [Merge](https://github.com/gepa-ai/gepa/blob/main/src/gepa/proposer/merge.py): candidate merge · Combines promising candidates into a stronger variant. · `src/gepa/proposer/merge.py`
- [Reflective mutation](https://github.com/gepa-ai/gepa/blob/main/src/gepa/proposer/reflective_mutation/reflective_mutation.py): llm mutation · LLM-driven mutation path using accumulated feedback. · `src/gepa/proposer/reflective_mutation/reflective_mutation.py`
- [Strategies](https://github.com/gepa-ai/gepa/blob/main/src/gepa/strategies/__init__.py): selection policies · Candidate selection, batch sampling, acceptance, and evaluation policies. · `src/gepa/strategies/__init__.py`

### Integrations

Built-in adapters and framework-specific integration layers.

- [Default adapter](https://github.com/gepa-ai/gepa/blob/main/src/gepa/adapters/default_adapter/default_adapter.py): prompt adapter · Baseline prompt optimization adapter. · `src/gepa/adapters/default_adapter/default_adapter.py`
- [DSPy adapter](https://github.com/gepa-ai/gepa/blob/main/src/gepa/adapters/dspy_adapter/dspy_adapter.py): dspy integration · Adapter for DSPy modules and instruction proposal helpers. · `src/gepa/adapters/dspy_adapter/dspy_adapter.py`
- [DSPy full program](https://github.com/gepa-ai/gepa/blob/main/src/gepa/adapters/dspy_full_program_adapter/full_program_adapter.py): program evolution · Evolves full DSPy programs rather than only prompts. · `src/gepa/adapters/dspy_full_program_adapter/full_program_adapter.py`
- [RAG adapter](https://github.com/gepa-ai/gepa/blob/main/src/gepa/adapters/generic_rag_adapter/generic_rag_adapter.py): retrieval pipeline · Generic RAG integration with multiple vector store backends. · `src/gepa/adapters/generic_rag_adapter/generic_rag_adapter.py`
- [MCP adapter](https://github.com/gepa-ai/gepa/blob/main/src/gepa/adapters/mcp_adapter/mcp_adapter.py): tool-use integration · 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](https://github.com/gepa-ai/gepa/blob/main/src/gepa/api.py): public exports · Small public surface for the installable library. · `src/gepa/api.py`
- [Optimize anything](https://github.com/gepa-ai/gepa/blob/main/src/gepa/optimize_anything.py): generic entrypoint · Framework-agnostic API for optimizing arbitrary text artifacts. · `src/gepa/optimize_anything.py`

### Observability

Logging, callbacks, and experiment tracking.

- [Callbacks](https://github.com/gepa-ai/gepa/blob/main/src/gepa/core/callbacks.py): lifecycle events · Optimization, iteration, evaluation, merge, and error events. · `src/gepa/core/callbacks.py`
- [Logging](https://github.com/gepa-ai/gepa/blob/main/src/gepa/logging/logger.py): observability · Experiment tracking and structured logging around optimization runs. · `src/gepa/logging/logger.py`
- [Tracker](https://github.com/gepa-ai/gepa/blob/main/src/gepa/logging/experiment_tracker.py): experiment tracking · Experiment tracking and run persistence utilities. · `src/gepa/logging/experiment_tracker.py`

### Domain layer

Specialized skill-optimization package built on GEPA.

- [gskill](https://github.com/gepa-ai/gepa/blob/main/src/gepa/gskill/gskill/__init__.py): domain layer · Coding-agent and SWE-style skill optimization utilities. · `src/gepa/gskill/gskill/__init__.py`

### Project perimeter

Examples, docs, and tests around the library.

- [Examples](https://github.com/gepa-ai/gepa/tree/main/examples): runnable demos · End-to-end reference projects showing how GEPA is composed. · `examples`
- [Docs](https://github.com/gepa-ai/gepa/tree/main/docs): mkdocs site · Guides, API reference, tutorials, and blog content. · `docs`
- [Tests](https://github.com/gepa-ai/gepa/tree/main/tests): quality gate · Integration-heavy coverage for engine, adapters, and policies. · `tests`

## Connections

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