synth-containers

The task contract for Synth optimizers and evals — wrap any task as a small HTTP service that optimizers can target without touching your code.

PyPI · Optimizers · Cookbooks

A Synth container is a small HTTP service around a task. It owns the dataset, the scoring/verifier logic, the mutable prompt or policy fields, and the policy-model credential boundary. An optimizer like synth-optimizers GEPA sees one URL and a typed rollout contract — it never imports your task package or reads private evaluator state. The same contract works whether the task is a classifier, a coding agent, or a live game environment, and in Python, Rust, or TypeScript.

Install

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

Local Synth development

Register the current checkout once after changing Containers or its package version:

./scripts/register-local-dev-build.sh

The command builds a wheel, installs it into an immutable machine-local directory, verifies the installed version, and atomically selects it for local Workshop builds. No launch flags or environment variables are required. Re-running it reuses an identical registered wheel.

Sibling Optimizers development remains editable through its checked-in uv source:

cd ../optimizers
uv sync --group dev

The contract

The Python SDK also provides Container, Container.serve(), ContainerHandle, and ContainerConnection for URL-only optimizer handoff. Use generic route hints and capability metadata here; optimizer-specific GEPA settings belong in synth-optimizers.

Example

from fastapi import Body, FastAPI
from synth_containers import GEPA_OPTIMIZER_CONTRACT_VERSION

app = FastAPI()

@app.post("/rollout")
def rollout(payload: dict = Body(...)) -> dict:
    candidate, row = payload["candidate"], payload["row"]
    # run the task with the candidate's mutable fields, score it with a real verifier
    return {"reward": ..., "usage": ...}

See the cookbooks for complete containers: Banking77, HotpotQA, MiniGrid, TBLite, and Crafter.

Links

• Optimizers — GEPA on this contract
• Cookbooks — runnable containers
• Agent skill — drop into a coding agent to build and debug containers
• Contract OpenAPI

License

MIT