Introduction to GEPA Omni

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

One evaluator in, a better artifact out

Write a function that scores a candidate and explains why it failed. The engines handle mutation, selection, and budgeting.

Four engines, one contract

GEPA, AutoResearch, Meta-Harness, and Best-of-N all run against the same candidate, data, and budget.

Omni by default

Phase 1 explores with three engines in parallel; Phase 2 continues the best candidate with a fresh optimizer.

Portable plugin packaging

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:

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:

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.

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:

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:

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 for repository development.
The published gepa[full]==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:

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

Quickstart

Install, configure the endpoint, run preflight, and launch your first Omni run.

Omni workflow

Phases, budget partitioning, and continuation choices.

Engines and backends

The four engines and the shared Chat Completions runtime.

Writing evaluators

Feedback-rich info, judges, batching, multi-objective, and stochastic averaging.

API reference

Published optimize_anything and plugin run_optimization / run_omni contracts.

Gotchas

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

Fleet-RLM

Fleet Pi

GEPA Omni

Qredence Skills

Fleet Reasoner

Qredence Plugins

Why GEPA Omni

One evaluator in, a better artifact out

Four engines, one contract

Omni by default

Portable plugin packaging

Names

Install with Codex

How Omni works

The evaluator contract

Engines and backends

Requirements

Packaging

Learn more

Quickstart

Omni workflow

Engines and backends

Writing evaluators

API reference

Gotchas

Attribution

​Why GEPA Omni

One evaluator in, a better artifact out

Four engines, one contract

Omni by default

Portable plugin packaging

​Names

​Install with Codex

​How Omni works

​The evaluator contract

​Engines and backends

​Requirements

​Packaging

​Learn more

Quickstart

Omni workflow

Engines and backends

Writing evaluators

API reference

Gotchas

​Attribution

Why GEPA Omni

Names

Install with Codex

How Omni works

The evaluator contract

Engines and backends

Requirements

Packaging

Learn more

Attribution