synth-optimizers

Prompt-program optimizers for production agents — open-source GEPA on a language-agnostic task contract.

PyPI · Containers · Cookbooks

synth-optimizers runs GEPA — reflective prompt evolution — against any task exposed through the synth-containers HTTP contract. Point it at a container and a TOML config; it proposes prompt changes, rolls them out, scores them, keeps a Pareto frontier, and returns a deployable candidate with replayable evidence.

• Container boundary — the optimizer only speaks HTTP. It never imports your task code or sees your model credentials.
• Inspectable runs — every candidate carries its prompt diff, per-seed scores, rollout traces, cache profile, and usage.
• Rust core, thin Python — the GEPA state machine is Rust (PyO3); configure runs with GepaConfig or TOML.

Install

pip install synth-optimizers
# or
uv add synth-optimizers

Latest daily dev build:

pip install --pre \
  synth-containers==0.2.0.dev202605312141 \
  synth-optimizers==0.2.0.dev202605312141

uv add --prerelease allow \
  synth-containers==0.2.0.dev202605312141 \
  synth-optimizers==0.2.0.dev202605312141

Install uv for local development and editable installs.

Local development

Pair this repo with synth-containers at matching dev versions, then sync and install editable:

cd optimizers
uv sync --group dev
uv pip install -e ../containers
uv pip install -e .
uv run maturin develop --manifest-path rust/crates/synth_optimizers_py/Cargo.toml

Quickstart

A run is defined by TOML (or GepaConfig): which container to talk to, which prompt modules to optimize, and how to score them.

[container]
url = "http://127.0.0.1:8765"
command = ["uv", "run", "python", "banking77_container/synth_service_app.py", "--port", "8765"]

[candidate]
target_modules = ["stage2_system"]

[seed_candidate]
stage2_system = "Classify the query into exactly one Banking77 intent. Return only the label."

[dataset]
train_seeds = [0, 1, 2, 3, 4, 5, 6, 7]
heldout_seeds = [100, 101, 102, 103]

from synth_containers import Container
from synth_optimizers import GepaConfig, GepaRun, OptimizerRun, TasksetSelection

container = Container("my-task")

with container.serve() as handle:
    result = OptimizerRun(
        GepaConfig(
            container=handle.connection(),
            taskset=TasksetSelection(train_ids=["train:0", "train:1"], heldout_ids=["test:100"]),
            program=None,
            objectives=None,
            policy=None,
        )
    ).execute()

print(result.best_candidate)
print(f"cost: ${result.cost_usd:.2f}")

Or load TOML directly: GepaRun.from_toml("gepa.toml").execute().

CLI:

synth-optimizers gepa run --config gepa.toml
synth-optimizers gepa service --db service.sqlite
synth-optimizers events compare --left a.jsonl --right b.jsonl

Runnable task examples: GEPA cookbooks (Banking77, HotpotQA, MiniGrid, TBLite, Crafter).

export OPENAI_API_KEY="sk-..."
export SYNTH_OPTIMIZERS_TERMINAL=1   # optional: live usage in the terminal

[policy]
provider = "openai"
model = "gpt-4.1-nano"
api_key_env = "OPENAI_API_KEY"

[proposer]
backend = "codex_app_server"
runtime_substrate = "local"
provider = "openai"
auth_mode = "api_key"
api_key_env = "OPENAI_API_KEY"
copy_host_auth = false
model = "gpt-5.4-nano"
sandbox_mode = "workspace-write"
approval_policy = "never"
timeout_seconds = 900

Features

• OpenAI API key proposer — run-local Codex home; does not use your host ~/.codex login.
• OpenRouter proposer — provider-aware Codex config and base URL; OpenRouter works for policy rollouts too.
• ChatGPT subscription proposer — auth_mode = "chatgpt" with required codex_home (OAuth via Codex CLI or opencode-openai-codex-auth); models include gpt-5.4-mini, gpt-5.3-codex, gpt-5.3-codex-spark, gpt-5.5; proposer usage is $0, policy rollouts still bill normally.
• Live usage — SYNTH_OPTIMIZERS_TERMINAL=1 prints running token and cost splits (usage total=… policy=… proposer=…).
• Docker proposer — runtime_substrate = "docker" with [proposer.docker].image; workspaces stage under ~/.cache/synth-gepa-docker-workspaces/, sync back, then cleanup; image: docker/codex-gepa-proposer/Dockerfile.
• Gemini and other policy providers — supported on the policy side via [policy].provider, base_url, and container env keys; proposer stays Codex.
• DeepSeek direct — not supported through Codex (/responses mismatch); use an OpenRouter DeepSeek slug instead.
• Preflight validation — missing keys, missing codex_home/auth.json, or disallowed ChatGPT models fail before rollouts start.

Agent docs: skills/gepa/SKILL.md.

Links

• Cookbooks — runnable GEPA examples
• synth-containers — the task contract
• uv — Python package and project manager
• GEPA service OpenAPI
• GEPA paper

License

Apache-2.0