Engine

gepa.optimize_anything.Engine(config: OptimizeAnythingConfig)

Bases: Protocol

Contract every engine implements.

Construction takes an :class:OptimizeAnythingConfig; the public API calls :meth:run with a task and an eval server, then :meth:process_result for post-run artifact persistence.

Configure the engine from a single :class:OptimizeAnythingConfig.

Read cross-cutting fields directly (config.run_dir, config.stop_at_score, …) and pop engine-specific keys from config.engine_config onto self. Warn (or raise) on unknown keys in config.engine_config to surface typos.

Budget contract: the engine MUST honor config.max_token_cost (the proposer-cost cap — USD on the engine's own optimizer LLM tokens). The eval server enforces only the eval-call budget and cannot enforce the proposer cap: it never observes the engine's out-of-band LLM spend (and a subprocess's cost isn't knowable until it exits). Read the cap here and translate it into your native mechanism (max_reflection_cost, --max-budget-usd, …).

Source code in gepa/oa/engine.py

def __init__(self, config: OptimizeAnythingConfig) -> None:
    """Configure the engine from a single :class:`OptimizeAnythingConfig`.

    Read cross-cutting fields directly (``config.run_dir``,
    ``config.stop_at_score``, …) and pop engine-specific keys from
    ``config.engine_config`` onto ``self``. Warn (or raise) on unknown keys
    in ``config.engine_config`` to surface typos.

    Budget contract: the engine MUST honor ``config.max_token_cost`` (the
    proposer-cost cap — USD on the engine's own optimizer LLM tokens). The
    eval server enforces only the eval-call budget and cannot enforce the
    proposer cap: it never observes the engine's out-of-band LLM spend (and
    a subprocess's cost isn't knowable until it exits). Read the cap here
    and translate it into your native mechanism (``max_reflection_cost``,
    ``--max-budget-usd``, …).
    """
    ...

Attributes

name: str instance-attribute

Methods:

run(task: Task, server: EvalServer) -> Result

Run optimization and return the best candidate.

Parameters:

Name	Type	Description	Default
task	Task	Task definition.	required
server	EvalServer	The eval server. Call server.evaluate(candidate) for in-process eval, or use server.url for HTTP-based eval. server.budget enforces the eval-call budget; the proposer-cost cap lives on config.max_token_cost (read at construction), not on the server.	required

Source code in gepa/oa/engine.py

def run(self, task: Task, server: EvalServer) -> Result:
    """Run optimization and return the best candidate.

    Args:
        task: Task definition.
        server: The eval server. Call ``server.evaluate(candidate)`` for
            in-process eval, or use ``server.url`` for HTTP-based eval.
            ``server.budget`` enforces the eval-call budget; the
            proposer-cost cap lives on ``config.max_token_cost`` (read at
            construction), not on the server.
    """
    ...

process_result(result: Result, output_dir: Path | None) -> None

Persist engine-specific artifacts under output_dir after :meth:run.

Default is a no-op. Engines that produced files, transcripts, or workspaces should override this to copy/write them.

output_dir is None when the caller (typically via :func:optimize_anything_with_server) built an :class:EvalServer without an output_dir — engines that need a destination must no-op in that case rather than crashing.

Source code in gepa/oa/engine.py

def process_result(self, result: Result, output_dir: Path | None) -> None:
    """Persist engine-specific artifacts under ``output_dir`` after :meth:`run`.

    Default is a no-op. Engines that produced files, transcripts, or
    workspaces should override this to copy/write them.

    ``output_dir`` is ``None`` when the caller (typically via
    :func:`optimize_anything_with_server`) built an :class:`EvalServer`
    without an ``output_dir`` — engines that need a destination must
    no-op in that case rather than crashing.
    """
    return