synth-containers 0.2.0.dev202605312141

Shared Synth container and environment runtime substrate

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

Latest daily dev build:

pip install --pre synth-containers==0.2.0.dev202605312141
uv add --prerelease allow synth-containers==0.2.0.dev202605312141

Local Better SDK Dev

This branch pair expects:

• containers: package synth-containers==0.2.0.dev202605312141
• optimizers: package synth-optimizers==0.2.0.dev202605312141

Install both editable checkouts with uv (sibling repos under your workspace):

cd optimizers
uv sync --group dev
uv pip install -e ../containers
uv pip install -e .

Verify import paths and versions:

uv run python -c "import importlib.metadata as m, synth_containers, synth_optimizers; print(synth_containers.__file__); print(m.version('synth-containers')); print(synth_optimizers.__version__)"

The SDK validation examples (Banking77, TBLite, Crafter, MiniGrid) live in local optimizers/dev_examples/ (gitignored — not shipped in the repo).

The contract

Route	Method	Purpose
/metadata	GET	contract version + capabilities
/program	GET	mutable prompt fields + seed candidate
/dataset	GET	split names + row counts
/dataset/rows	POST	rows for a requested seed list
/rollout	POST	run a candidate on a row → reward + usage
/health	GET	liveness

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