> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qredence.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Engines and backends

> The four GEPA Omni engines — GEPA, AutoResearch, Meta-Harness, and Best-of-N — plus how the shared OpenAI-compatible Chat Completions runtime powers all of them.

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](/gepa-omni/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:

```bash theme={null}
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:

```python theme={null}
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`:

```python theme={null}
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:

```bash theme={null}
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.