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

# Introduction to GEPA Omni

> GEPA Omni packages the GEPA Anything optimization stack as an Agent Plugins 1.0 plugin, running four engines behind one evaluator contract.

GEPA Omni optimizes any scorable text artifact — prompts, programs, configurations, schemas, SQL, regular expressions, plans, or agent instructions — from plain evaluator feedback. It ships the reflective GEPA engine from PyPI plus three plugin-native engines (AutoResearch, Meta-Harness, Best-of-N) and runs them together in a two-phase **Omni** workflow.

## Why GEPA Omni

<CardGroup cols={2}>
  <Card title="One evaluator in, a better artifact out" icon="wand-magic-sparkles">
    Write a function that scores a candidate and explains why it failed. The engines handle mutation, selection, and budgeting.
  </Card>

  <Card title="Four engines, one contract" icon="layer-group">
    GEPA, AutoResearch, Meta-Harness, and Best-of-N all run against the same candidate, data, and budget.
  </Card>

  <Card title="Omni by default" icon="split">
    Phase 1 explores with three engines in parallel; Phase 2 continues the best candidate with a fresh optimizer.
  </Card>

  <Card title="Portable plugin packaging" icon="plug">
    Ships as an Agent Plugins 1.0 manifest plus a Codex compatibility manifest, so any compatible coding agent can install and drive it.
  </Card>
</CardGroup>

## Names

The repository is `fleet-gepa-omni`, the installable plugin is `gepa-omni`, and the shipped skill is `gepa-omni-skill`. These are separate identities by design.

## Install with Codex

Add the GitHub repository as a Codex marketplace, then install the plugin:

```bash theme={null}
codex plugin marketplace add Qredence/gepa-omni
codex plugin add gepa-omni@Qredence
```

Start a new Codex task after installation so the skill loads, then invoke it by naming the skill and describing the candidate and evaluator:

```text theme={null}
Use $gepa-omni-skill to improve this prompt against my evaluator. Preserve the
output format and report the held-out score separately.
```

## How Omni works

Omni is the default workflow. Three isolated exploration engines run against the same candidate, objective, evaluator, and selection data. The best Phase 1 candidate is handed to a fresh Phase 2 continuation — GEPA by default. Set `continuation_engine` to `autoresearch` or `meta_harness` to continue natively instead.

Key boundaries:

* `test_set` is withheld from every Phase 1 branch and scored only by the final Phase 2 run.
* Omni requires an explicit positive `max_evals` and/or `max_token_cost`. The total is split into four balanced slices (three explorations plus one continuation), so an evaluation-only run needs at least four evaluations.
* Omni is orchestration, not a public `engine="omni"` value. Omit the engine override for the default workflow, or select a standalone engine to compare.
* Keep `run_dir` and `output_dir` outside the checkout whenever an engine needs a workspace or writes diagnostics.

## The evaluator contract

GEPA Omni optimizes whatever your evaluator returns: a higher-is-better score plus feedback that explains why a candidate failed.

```python theme={null}
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"),
    }
```

Return failures, diffs, outputs, and partial-credit details in `info`. A bare float gives the proposer little direction. For stochastic systems, average multiple samples inside the evaluator and include the sample diagnostics.

Launch directly against the pinned PyPI API:

```python theme={null}
import os
from gepa.optimize_anything import EngineConfig, GEPAConfig, ReflectionConfig, optimize_anything

result = optimize_anything(
    seed_candidate="candidate text",
    evaluator=evaluate,
    dataset=dataset,
    valset=valset,
    objective="Improve the candidate against the evaluator.",
    config=GEPAConfig(
        engine=EngineConfig(max_metric_calls=100, run_dir="external-runs/example"),
        reflection=ReflectionConfig(reflection_lm=os.environ["OPENAI_MODEL"]),
    ),
)
```

Data arguments:

| Input      | Role                                                  |
| ---------- | ----------------------------------------------------- |
| `dataset`  | Examples used for multi-task optimization.            |
| `valset`   | Representative selection and generalization examples. |
| `test_set` | Sealed, reporting-only examples for the final score.  |

The direct PyPI `optimize_anything()` signature has no `test_set` argument and does not produce held-out-score metadata. The plugin wrapper `run_optimization(..., engine="gepa")` may accept `task["test_set"]` and score it after the run. Report that wrapper result separately from the selection score.

## Engines and backends

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

All engines use the same OpenAI-compatible Chat Completions API. Configure the endpoint, model, and key once before launching:

```bash theme={null}
export OPENAI_BASE_URL="https://api.openai.com/v1"
export OPENAI_MODEL="your-model"
export OPENAI_API_KEY="your-api-key"
```

`agent_backend` remains a compatibility label (`codex`, `pi`, or `claude`) kept in runtime and session metadata. `OPENAI_MODEL` is authoritative, and the three `OPENAI_*` variables are used for every model call.

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.

## Requirements

* Python 3.10 or newer.
* [`uv`](https://docs.astral.sh/uv/) for repository development.
* The published [`gepa[full]==0.1.4`](https://pypi.org/project/gepa/0.1.4/) environment for standalone `gepa` and the reflective integration.
* `OPENAI_BASE_URL`, `OPENAI_MODEL`, and `OPENAI_API_KEY` for an OpenAI-compatible Chat Completions endpoint.
* Both input and output USD-per-million token rates when using `max_token_cost`.

Preflight checks the shared API configuration and native runtime before a live run. It never prompts for configuration or performs a model call unless `--test-lm` is explicitly supplied:

```bash theme={null}
uv run python skills/gepa-omni-skill/scripts/preflight.py \
  --engine omni \
  --max-token-cost 5 \
  --codex-input-cost-per-million 2 \
  --codex-output-cost-per-million 8
```

## Packaging

GEPA Omni is packaged twice from the same tracked content:

* `plugin.json` — the portable [Agent Plugins 1.0](https://agent-plugins.org/) manifest.
* `.codex-plugin/plugin.json` — the OpenAI/Codex compatibility manifest.
* `.agents/plugins/marketplace.json` — marketplace metadata, which lets the GitHub repository itself act as a plugin marketplace.
* `skills/gepa-omni-skill/` — the shared payload (instructions, references, scripts, and the native runtime) referenced by both manifests.

`tools/stage_plugin.py` builds deployable bundles from a development checkout: `--format portable` emits `plugin.json` + `skills/` + `LICENSE`, and `--format codex` emits `.codex-plugin/` + `skills/` + `LICENSE`.

## Learn more

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/gepa-omni/quickstart">
    Install, configure the endpoint, run preflight, and launch your first Omni run.
  </Card>

  <Card title="Omni workflow" icon="split" href="/gepa-omni/omni-workflow">
    Phases, budget partitioning, and continuation choices.
  </Card>

  <Card title="Engines and backends" icon="layer-group" href="/gepa-omni/engines">
    The four engines and the shared Chat Completions runtime.
  </Card>

  <Card title="Writing evaluators" icon="ruler-combined" href="/gepa-omni/writing-evaluators">
    Feedback-rich `info`, judges, batching, multi-objective, and stochastic averaging.
  </Card>

  <Card title="API reference" icon="code" href="/gepa-omni/api-reference">
    Published `optimize_anything` and plugin `run_optimization` / `run_omni` contracts.
  </Card>

  <Card title="Gotchas" icon="triangle-exclamation" href="/gepa-omni/gotchas">
    Reward hacking, selection bias, budget sizing, and stop conditions.
  </Card>
</CardGroup>

## Attribution

GEPA Omni is distributed under the MIT License and builds on the original **GEPA Anything** project (`optimize_anything`, [gepa-ai/gepa](https://github.com/gepa-ai/gepa), MIT). The reflective engine is consumed from the pinned `gepa==0.1.4` PyPI release, and portions of the shipped native runtime are adapted from the pinned upstream commit `8a2bed96`.

Source: [github.com/Qredence/gepa-omni](https://github.com/Qredence/gepa-omni).