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

# GEPA Omni quickstart

> Install GEPA Omni into Codex, configure the OpenAI-compatible endpoint, run preflight, and launch your first Omni optimization.

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`](https://docs.astral.sh/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`](https://pypi.org/project/gepa/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:

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

## 2. Configure the endpoint

All engines share the same OpenAI-compatible Chat Completions API. Set the three variables 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"
```

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

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

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:

```python theme={null}
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](/gepa-omni/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:

```python theme={null}
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](/gepa-omni/omni-workflow) — phases, budget partitioning, and continuation choices.
* [Engines and backends](/gepa-omni/engines) — GEPA, AutoResearch, Meta-Harness, and Best-of-N.
* [Writing evaluators](/gepa-omni/writing-evaluators) — feedback-rich `info`, judges, batching, and stochastic averaging.
* [API reference](/gepa-omni/api-reference) — direct PyPI vs. plugin wrapper contracts.
* [Gotchas](/gepa-omni/gotchas) — reward hacking, selection bias, and budget sizing.