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

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

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.

License

MIT

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

synth_containers-0.4.1.tar.gz (590.2 kB view details)

Uploaded Aug 21, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

synth_containers-0.4.1-py3-none-any.whl (562.3 kB view details)

Uploaded Aug 21, 2026 Python 3

File details

Details for the file synth_containers-0.4.1.tar.gz.

File metadata

Download URL: synth_containers-0.4.1.tar.gz
Upload date: Aug 21, 2026
Size: 590.2 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for synth_containers-0.4.1.tar.gz
Algorithm	Hash digest
SHA256	`df3b8f5e04b6260ad2b1bd3a00ced618721938c9638d21e38b8c10d5c693acd1`
MD5	`9b29434d695a398a82e1530be1e9e6c4`
BLAKE2b-256	`6aafc521e3f35bf4fea80e1f01dbd7a45b5c3ffd5f0928a7e714f1c2430df601`

See more details on using hashes here.

Provenance

The following attestation bundles were made for synth_containers-0.4.1.tar.gz:

Publisher: publish-pypi.yml on synth-laboratories/containers

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: synth_containers-0.4.1.tar.gz
- Subject digest: df3b8f5e04b6260ad2b1bd3a00ced618721938c9638d21e38b8c10d5c693acd1
- Sigstore transparency entry: 2550108869
- Sigstore integration time: Aug 21, 2026
Source repository:
- Permalink: synth-laboratories/containers@b8bfe4c93a161df1606a150071c1e61665c671d8
- Branch / Tag: refs/tags/v0.4.1
- Owner: https://github.com/synth-laboratories
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-pypi.yml@b8bfe4c93a161df1606a150071c1e61665c671d8
- Trigger Event: push