> ## 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 to improve any scorable text artifact.
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
Write a function that scores a candidate and explains why it failed. The engines handle mutation, selection, and budgeting.
GEPA, AutoResearch, Meta-Harness, and Best-of-N all run against the same candidate, data, and budget.
Phase 1 explores with three engines in parallel; Phase 2 continues the best candidate with a fresh optimizer.
Ships as an Agent Plugins 1.0 manifest plus a Codex compatibility manifest, so any compatible coding agent can install and drive it.
## 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
Install, configure the endpoint, run preflight, and launch your first Omni run.
Phases, budget partitioning, and continuation choices.
The four engines and the shared Chat Completions runtime.
Feedback-rich `info`, judges, batching, multi-objective, and stochastic averaging.
Published `optimize_anything` and plugin `run_optimization` / `run_omni` contracts.
Reward hacking, selection bias, budget sizing, and stop conditions.
## 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).