GEPA Omni quickstart

Run your first GEPA Omni optimization in under ten minutes. This walks you from install through a preflight-checked Omni run against your own evaluator.

Prerequisites

Python 3.10 or newer.
uv if you plan to develop against the repository.
An OpenAI-compatible Chat Completions endpoint and API key.
The published gepa[full]==0.1.4 environment for the reflective GEPA engine.

1. Install the plugin

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.

2. Configure the endpoint

All engines share the same OpenAI-compatible Chat Completions API. Set the three variables before launching:

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 for every engine and every branch of the Omni workflow. The plugin never asks for an API key in chat — configure it through the environment or a secret manager. If a model or base URL is missing, the interactive skill asks once and applies the answer to the current process only.

3. Run preflight

Preflight validates configuration and the native runtime without sending a prompt. Run it before every live Omni run:

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

Pass --test-lm only if you explicitly want to exercise the endpoint with a single call.

4. Write an evaluator

The evaluator is where nearly all of the quality comes from. Return a higher-is-better score and a feedback-rich info dict:

def evaluate(candidate: str, example) -> tuple[float, dict]:
    output = run_system(candidate, example)
    score = grade(output, example)
    return score, {
        "score": score,
        "output": output,
        "expected": example.get("gold"),
        "error_type": example.get("error"),
    }

See Writing evaluators for judge-based scoring, batching, stochastic averaging, and multi-objective scoring.

5. Launch Omni

Use the plugin wrapper run_omni() for the default two-phase workflow:

from omni_pipeline import run_omni

result = run_omni(
    "candidate text",
    task={
        "evaluator": evaluate,
        "dataset": trainset,
        "valset": valset,
        "test_set": heldout,
        "objective": "Improve the candidate against the evaluator.",
    },
    max_evals=40,
    max_token_cost=20.0,
    run_dir="/tmp/omni-run",
    output_dir="/tmp/omni-output",
    continuation_engine="gepa",
)

Omni splits the total budget into three exploration slices plus one continuation slice. An explicit positive max_evals and/or max_token_cost is required. When max_evals is the only bound, provide at least four evaluations so every phase receives a positive slice. Keep both run_dir and output_dir absolute and outside the checkout.

6. Read the result

Omni returns the best Phase 1 candidate handed to a fresh Phase 2 continuation, the selection score, and — when task["test_set"] is supplied — a held-out report in metadata["test_score"] and metadata["test_scores"]. Report the wrapper’s held-out result separately from the selection score. The direct PyPI optimize_anything() signature has no test_set argument and does not produce held-out metadata.

Next steps

Omni workflow — phases, budget partitioning, and continuation choices.
Engines and backends — GEPA, AutoResearch, Meta-Harness, and Best-of-N.
Writing evaluators — feedback-rich info, judges, batching, and stochastic averaging.
API reference — direct PyPI vs. plugin wrapper contracts.
Gotchas — reward hacking, selection bias, and budget sizing.

Fleet-RLM

Fleet Pi

GEPA Omni

Qredence Skills

Fleet Reasoner

Qredence Plugins

Prerequisites

1. Install the plugin

2. Configure the endpoint

3. Run preflight

4. Write an evaluator

5. Launch Omni

6. Read the result

Next steps

​Prerequisites

​1. Install the plugin

​2. Configure the endpoint

​3. Run preflight

​4. Write an evaluator

​5. Launch Omni

​6. Read the result

​Next steps

Prerequisites

1. Install the plugin

2. Configure the endpoint

3. Run preflight

4. Write an evaluator

5. Launch Omni

6. Read the result

Next steps