API reference

There are two intentionally distinct API layers:

The published gepa==0.1.4 package exposes the standalone reflective optimize_anything() engine.
This plugin exposes run_optimization() and run_omni() for the native AutoResearch, Meta-Harness, Best-of-N, and two-phase Omni workflows.

The native runtime is checked in under scripts/native_omni/ and is independent of the installed GEPA package.

Mental model

optimize_anything is black-box optimization over a candidate. The evaluator returns a higher-is-better score plus optional feedback; the search engine uses that feedback to propose and select candidates. A budget bounds evaluator calls and, for agentic plugin engines, model-token spend. The direct PyPI API has no top-level engine= selector — it is the reflective GEPA engine. Engine selection belongs to the plugin wrapper: gepa means the PyPI reflective engine, and autoresearch, meta_harness, and best_of_n mean plugin-native engines.

Published PyPI GEPA API

from gepa.optimize_anything import GEPAConfig, optimize_anything

result = optimize_anything(
    seed_candidate="candidate text",
    evaluator=evaluate,
    batch_evaluator=None,
    dataset=dataset,
    valset=valset,
    objective="Improve the candidate against the evaluator.",
    background="Optional context for a seedless run.",
    config=GEPAConfig(...),
)

seed_candidate may be a string, a named component mapping, or None when the engine can bootstrap from objective and background. Examples in dataset and valset are opaque values passed to the evaluator. The direct PyPI call has no test_set parameter.

Config

import os
from gepa.optimize_anything import EngineConfig, GEPAConfig, ReflectionConfig

config = GEPAConfig(
    engine=EngineConfig(
        max_metric_calls=300,
        max_workers=16,
        run_dir="/tmp/gepa-run",
    ),
    reflection=ReflectionConfig(
        reflection_lm=os.environ["OPENAI_MODEL"],
        reflection_minibatch_size=5,
    ),
)

Field	Purpose
`EngineConfig.max_metric_calls`	Cap on evaluation calls.
`EngineConfig.max_workers` / `parallel`	Proposal concurrency.
`EngineConfig.max_reflection_cost`	Optional cap on reflection spend.
`GEPAConfig.stop_callbacks`	Score-based or other stopping policies.
`EngineConfig.run_dir`	GEPA state and diagnostics. PyPI 0.1.4 has no direct `output_dir` argument.

Unknown or misspelled fields raise TypeError. Do not pass the plugin wrapper’s max_evals, max_token_cost, engine_config, or output_dir fields to this direct API.

Evaluator and data splits

def evaluate(candidate: str, example) -> tuple[float, dict]:
    output = run_system(candidate, example)
    score = grade(output, example)
    return score, {
        "output": output,
        "expected": example.get("gold"),
        "error": example.get("error"),
    }

Use evaluator(candidate) for a single task and evaluator(candidate, example) with dataset or valset. A bare float is accepted, but (score, info) gives the proposer useful failure details. batch_evaluator accepts a list of (candidate, example) pairs and returns one score or (score, info) per pair in order. The plugin-native evaluation server applies the same normalization and enforces batch cardinality.

Mode	Configuration	Selection behavior
Single-task	`dataset=None, valset=None`	Solve one hard problem.
Multi-task	`dataset=[...]`	Score and select on the shared dataset.
Generalization	`dataset=[...], valset=[...]`	Optimize on `dataset`, select on `valset`.

For the plugin wrapper, put held-out examples in task["test_set"]. They are never exposed through the native agent task endpoint or passed to Phase 1. The wrapper scores them after optimization and may expose metadata["test_score"] and metadata["test_scores"].

Plugin wrapper

from omni_pipeline import run_optimization

result = run_optimization(
    "candidate text",
    task={
        "evaluator": evaluate,
        "dataset": trainset,
        "valset": valset,
        "test_set": heldout,
        "objective": "Improve the candidate.",
    },
    engine="autoresearch",
    max_evals=100,
    max_token_cost=5.0,
    run_dir="/tmp/gepa-native-run",
    output_dir="/tmp/gepa-native-output",
    agent_backend="codex",
)

engine="gepa" routes to PyPI gepa==0.1.4 and requires its nested GEPAConfig contract. The other explicit engines are plugin-native and use a shared Task, BudgetTracker, and external evaluation workspace. Omitting engine selects run_omni(). All wrapper run_dir and output_dir paths must be absolute and outside the checkout. sandbox=False is rejected at the wrapper boundary.

`run_omni`

from omni_pipeline import run_omni

result = run_omni(
    seed_candidate,
    task=task,
    max_evals=40,
    max_token_cost=20.0,
    run_dir="/tmp/omni-run",
    output_dir="/tmp/omni-output",
    continuation_engine="gepa",
)

See Omni workflow for phase boundaries, budget partitioning, and continuation options.

Fleet-RLM

Fleet Pi

GEPA Omni

Qredence Skills

Fleet Reasoner

Qredence Plugins

Mental model

Published PyPI GEPA API

Config

Evaluator and data splits

Plugin wrapper

`run_omni`

​Mental model

​Published PyPI GEPA API

​Config

​Evaluator and data splits

​Plugin wrapper

​run_omni

Mental model

Published PyPI GEPA API

Config

Evaluator and data splits

Plugin wrapper

`run_omni`