Qredence Documentation

Run your first GEPA Omni optimization in under ten minutes. This walks you from install through a preflight-checked 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.

1. Install the plugin

Add the GitHub repository as a Codex marketplace, then install the fleet-optimize plugin. It ships both gepa-omni-skill and fleet-optimize-skill:

codex plugin marketplace add Qredence/gepa-omni
codex plugin add fleet-optimize@Qredence

Start a new Codex task after installation so the skills load.

2. Install the Python package

To call GEPA Omni from your own application, install the gepa-omni package from a repository checkout. The plugin does not install it for you:

uv pip install ./packages/gepa-omni

The package declares the validated upstream GEPA Git revision as a dependency.

3. Configure the endpoint

Set the base URL and model for an OpenAI-compatible Chat Completions endpoint:

export OPENAI_BASE_URL="https://api.openai.com/v1"
export OPENAI_MODEL="your-model"
export OPENAI_API_KEY="your-api-key"

OPENAI_API_KEY is used only for the official api.openai.com host. For any other provider, keep OPENAI_BASE_URL and OPENAI_MODEL, and supply the key through GEPA_OMNI_API_KEY (or set GEPA_OMNI_API_KEY_ENV to the name of a provider-specific variable). See Providers and endpoint security. OPENAI_MODEL is authoritative for every engine. The skill never asks for an API key in chat. If a model or base URL is missing, it asks once and applies the answer to the current process only.

4. Run preflight

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

uv run python plugins/fleet-optimize/skills/gepa-omni-skill/scripts/preflight.py \
  --engine gepa

For a cost-capped fixed portfolio, also pass the cap and both token rates:

uv run python plugins/fleet-optimize/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.

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

6. Launch

Call optimize with an OmniConfig. The default auto strategy pilots eligible engines and continues with the best one:

from gepa_omni import OmniConfig, optimize

result = optimize(
    seed_candidate="candidate text",
    evaluator=evaluate,
    dataset=trainset,
    valset=valset,
    test_set=heldout,
    objective="Improve the candidate against the evaluator.",
    config=OmniConfig(
        strategy="auto",
        max_evals=100,
        run_dir="/tmp/gepa-omni-run",
        output_dir="/tmp/gepa-omni-output",
    ),
)

Set max_evals, max_token_cost, or both. A token cap also needs input_cost_per_million and output_cost_per_million. Keep run_dir and output_dir absolute and outside the checkout; when omitted, temporary directories are created. Use strategy="gepa" for a predictable standalone run, or strategy="omni" for the fixed portfolio. omni requires the plugin runtime and raises a RuntimeError from a package-only install.

7. Read the result

optimize returns a result with best_candidate, best_score, total_evals, metadata, and the engine-specific raw result. When test_set is supplied, the held-out report is in metadata["heldout_score"] and metadata["heldout_scores"] (also exposed as test_score and test_scores). With auto, metadata["auto"] records the pilot engines, pilot scores, seed score, and chosen continuation. Report the held-out score separately from the selection score.

Next steps

Fleet Optimize: parallel P×N proposals on the latest upstream GEPA.
Omni workflow: the fixed portfolio and the adaptive auto strategy.
Engines and backends: GEPA, AutoResearch, Meta-Harness, Best-of-N, and provider security.
Writing evaluators: feedback-rich info, judges, batching, and stochastic averaging.
API reference: the gepa_omni package and direct upstream contracts.
Gotchas: reward hacking, selection bias, and budget sizing.

Fleet-RLM

Fleet Prime Agent

Fleet Pi

GEPA Omni

Qredence Skills

Fleet Reasoner

Qredence Plugins

GEPA Omni quickstart

Prerequisites

1. Install the plugin

2. Install the Python package

3. Configure the endpoint

4. Run preflight

5. Write an evaluator

6. Launch

7. Read the result

Next steps

​Prerequisites

​1. Install the plugin

​2. Install the Python package

​3. Configure the endpoint

​4. Run preflight

​5. Write an evaluator

​6. Launch

​7. Read the result

​Next steps

Prerequisites

1. Install the plugin

2. Install the Python package

3. Configure the endpoint

4. Run preflight

5. Write an evaluator

6. Launch

7. Read the result

Next steps