Engines and backends

GEPA Omni ships four engines behind one evaluator contract. The gepa engine is the PyPI reflective engine; the other three are plugin-native and use a shared Task, BudgetTracker, and external evaluation workspace.

Comparison

Engine	Search behavior	Local runtime
`gepa`	Reflects on evaluator feedback, mutates candidates, and keeps a Pareto frontier.	PyPI `gepa==0.1.4` standalone engine with the external Chat Completions proposer.
`autoresearch`	Long-horizon experiment loop with Ralph-style continuation.	Plugin-native engine; backend labels select the shared Chat Completions runner.
`meta_harness`	Proposes candidates while the framework evaluates and selects them.	Plugin-native engine with fresh agent sessions by default.
`best_of_n`	Samples independent candidates and keeps the best.	Plugin-native comparison baseline.

Omit engine to run the default Omni workflow, or pass one of these values to run_optimization() to compare a single engine head-to-head.

Shared Chat Completions runtime

All engines call the same OpenAI-compatible Chat Completions endpoint. The historical Codex names remain public compatibility surfaces, but model calls no longer invoke a provider CLI. CodexAgentProposer and the native agent engines use OpenAIChatCompletionRunner underneath. Configure the endpoint once:

export OPENAI_BASE_URL="https://api.openai.com/v1"
export OPENAI_MODEL="your-model"
export OPENAI_API_KEY="your-api-key"

OPENAI_MODEL is authoritative. Legacy agent_model, codex_model, and backend command parameters remain accepted for source compatibility but do not select a different provider or executable.

Read-only GEPA proposer

CodexAgentProposer implements:

proposer(
    candidate,
    reflective_dataset,
    components_to_update,
    *,
    metadata=None,
) -> dict[str, str]

Each call creates a unique external diagnostics directory containing the candidate, reflective data, requested component names, request, response, usage, and validation errors. The request is a JSON Chat Completions call with response_format={"type": "json_object"}. The response must contain new_texts with exactly the requested keys and string values. Pass input_cost_per_million, output_cost_per_million, and max_token_cost when a PyPI GEPA run is cost-bounded. sandbox=False is rejected, and the plugin checkout is never used for proposal artifacts.

Native agent runner

The production native runner is OpenAIChatCompletionRunner:

from native_omni import OpenAIChatCompletionRunner

runner = OpenAIChatCompletionRunner(backend="codex", timeout_seconds=600)
result = runner.run(
    prompt,
    work_dir="/tmp/gepa-native-workspace",
    max_token_cost=5.0,
)

The runner retains Chat Completions message history for AutoResearch continuations, records usage and cost, and writes the raw response to the external workspace. The model receives text and JSON in the request. It does not receive local shell or filesystem tools. sandbox=True is mandatory at the wrapper boundary, and external run_dir and output_dir paths are always required. CodexAgentRunner is retained only for callers that directly depend on the old subprocess class. The plugin pipeline does not construct it.

Parallelism

For GEPA P×N proposal sampling, pass gepa_parallel_proposals=(parents, mutations) with a suitable max_concurrency. Omitting it retains the sequential one-worker configuration. EngineConfig.max_workers and parallel control proposal concurrency for the PyPI reflective engine.

Preflight per engine

Preflight is non-interactive and does not send a prompt unless --test-lm is supplied:

uv run python skills/gepa-omni-skill/scripts/preflight.py --engine codex
uv run python skills/gepa-omni-skill/scripts/preflight.py \
  --engine autoresearch --agent-backend codex \
  --codex-input-cost-per-million 2 \
  --codex-output-cost-per-million 8

Preflight validates the pinned PyPI GEPA API where relevant, the native Chat Completions runner, and all three OPENAI_* variables.

Fleet-RLM

Fleet Pi

GEPA Omni

Qredence Skills

Fleet Reasoner

Qredence Plugins

Comparison

Shared Chat Completions runtime

Read-only GEPA proposer

Native agent runner

Parallelism

Preflight per engine

​Comparison

​Shared Chat Completions runtime

​Read-only GEPA proposer

​Native agent runner

​Parallelism

​Preflight per engine

Comparison

Shared Chat Completions runtime

Read-only GEPA proposer

Native agent runner

Parallelism

Preflight per engine