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

# API reference

> Two intentionally distinct API layers: the published gepa==0.1.4 optimize_anything engine, and the plugin wrapper run_optimization / run_omni for the native AutoResearch, Meta-Harness, Best-of-N, and Omni workflows.

There are two intentionally distinct API layers:

1. The published `gepa==0.1.4` package exposes the standalone reflective `optimize_anything()` engine.
2. This plugin exposes `run_optimization()` and `run_omni()` for the native AutoResearch, Meta-Harness, Best-of-N, and two-phase Omni workflows.

The native runtime is checked in under `scripts/native_omni/` and is independent of the installed GEPA package.

## Mental model

`optimize_anything` is black-box optimization over a candidate. The evaluator returns a higher-is-better score plus optional feedback; the search engine uses that feedback to propose and select candidates. A budget bounds evaluator calls and, for agentic plugin engines, model-token spend.

The direct PyPI API has no top-level `engine=` selector — it is the reflective GEPA engine. Engine selection belongs to the plugin wrapper: `gepa` means the PyPI reflective engine, and `autoresearch`, `meta_harness`, and `best_of_n` mean plugin-native engines.

## Published PyPI GEPA API

```python theme={null}
from gepa.optimize_anything import GEPAConfig, optimize_anything

result = optimize_anything(
    seed_candidate="candidate text",
    evaluator=evaluate,
    batch_evaluator=None,
    dataset=dataset,
    valset=valset,
    objective="Improve the candidate against the evaluator.",
    background="Optional context for a seedless run.",
    config=GEPAConfig(...),
)
```

`seed_candidate` may be a string, a named component mapping, or `None` when the engine can bootstrap from `objective` and `background`. Examples in `dataset` and `valset` are opaque values passed to the evaluator. The direct PyPI call has no `test_set` parameter.

### Config

```python theme={null}
import os
from gepa.optimize_anything import EngineConfig, GEPAConfig, ReflectionConfig

config = GEPAConfig(
    engine=EngineConfig(
        max_metric_calls=300,
        max_workers=16,
        run_dir="/tmp/gepa-run",
    ),
    reflection=ReflectionConfig(
        reflection_lm=os.environ["OPENAI_MODEL"],
        reflection_minibatch_size=5,
    ),
)
```

| Field                                   | Purpose                                                                     |
| --------------------------------------- | --------------------------------------------------------------------------- |
| `EngineConfig.max_metric_calls`         | Cap on evaluation calls.                                                    |
| `EngineConfig.max_workers` / `parallel` | Proposal concurrency.                                                       |
| `EngineConfig.max_reflection_cost`      | Optional cap on reflection spend.                                           |
| `GEPAConfig.stop_callbacks`             | Score-based or other stopping policies.                                     |
| `EngineConfig.run_dir`                  | GEPA state and diagnostics. PyPI 0.1.4 has no direct `output_dir` argument. |

Unknown or misspelled fields raise `TypeError`. Do not pass the plugin wrapper's `max_evals`, `max_token_cost`, `engine_config`, or `output_dir` fields to this direct API.

## Evaluator and data splits

```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"),
    }
```

Use `evaluator(candidate)` for a single task and `evaluator(candidate, example)` with `dataset` or `valset`. A bare float is accepted, but `(score, info)` gives the proposer useful failure details.

`batch_evaluator` accepts a list of `(candidate, example)` pairs and returns one score or `(score, info)` per pair in order. The plugin-native evaluation server applies the same normalization and enforces batch cardinality.

| Mode           | Configuration                 | Selection behavior                         |
| -------------- | ----------------------------- | ------------------------------------------ |
| Single-task    | `dataset=None, valset=None`   | Solve one hard problem.                    |
| Multi-task     | `dataset=[...]`               | Score and select on the shared dataset.    |
| Generalization | `dataset=[...], valset=[...]` | Optimize on `dataset`, select on `valset`. |

For the plugin wrapper, put held-out examples in `task["test_set"]`. They are never exposed through the native agent task endpoint or passed to Phase 1. The wrapper scores them after optimization and may expose `metadata["test_score"]` and `metadata["test_scores"]`.

## Plugin wrapper

```python theme={null}
from omni_pipeline import run_optimization

result = run_optimization(
    "candidate text",
    task={
        "evaluator": evaluate,
        "dataset": trainset,
        "valset": valset,
        "test_set": heldout,
        "objective": "Improve the candidate.",
    },
    engine="autoresearch",
    max_evals=100,
    max_token_cost=5.0,
    run_dir="/tmp/gepa-native-run",
    output_dir="/tmp/gepa-native-output",
    agent_backend="codex",
)
```

`engine="gepa"` routes to PyPI `gepa==0.1.4` and requires its nested `GEPAConfig` contract. The other explicit engines are plugin-native and use a shared `Task`, `BudgetTracker`, and external evaluation workspace. Omitting `engine` selects `run_omni()`.

All wrapper `run_dir` and `output_dir` paths must be absolute and outside the checkout. `sandbox=False` is rejected at the wrapper boundary.

## `run_omni`

```python theme={null}
from omni_pipeline import run_omni

result = run_omni(
    seed_candidate,
    task=task,
    max_evals=40,
    max_token_cost=20.0,
    run_dir="/tmp/omni-run",
    output_dir="/tmp/omni-output",
    continuation_engine="gepa",
)
```

See [Omni workflow](/gepa-omni/omni-workflow) for phase boundaries, budget partitioning, and continuation options.