This release is a pre-release and may not be stable for production use.
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
| 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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file synth_containers-0.4.1.dev20260817.tar.gz.
File metadata
- Download URL: synth_containers-0.4.1.dev20260817.tar.gz
- Upload date:
- Size: 526.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
132aed579ca50cb87a85e1033381d6dff15d8a938af224327e6dd10e7f3e4d92
|
|
| MD5 |
45f494b5dfee9a845f928d1bfe690f56
|
|
| BLAKE2b-256 |
96a2b98de88810e4a83ec4b4ee407e92f2867a1310d1313f7da70c41ae7200e4
|
Provenance
The following attestation bundles were made for synth_containers-0.4.1.dev20260817.tar.gz:
Publisher:
publish-pypi.yml on synth-laboratories/containers
-
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.dev20260817.tar.gz -
Subject digest:
132aed579ca50cb87a85e1033381d6dff15d8a938af224327e6dd10e7f3e4d92 - Sigstore transparency entry: 2535581044
- Sigstore integration time:
-
Permalink:
synth-laboratories/containers@ec25929ebbe284e11987280d1b75d5b133b75c3c -
Branch / Tag:
refs/heads/dev - Owner: https://github.com/synth-laboratories
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish-pypi.yml@ec25929ebbe284e11987280d1b75d5b133b75c3c -
Trigger Event:
workflow_dispatch
-
Statement type:
File details
Details for the file synth_containers-0.4.1.dev20260817-py3-none-any.whl.
File metadata
- Download URL: synth_containers-0.4.1.dev20260817-py3-none-any.whl
- Upload date:
- Size: 520.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
0aea621ca449a6bc84cbb81ecfa2ef31137c40f608638fd5040e136e30b7c9d2
|
|
| MD5 |
bc12a6c57e41947720fdf63b3b7e3132
|
|
| BLAKE2b-256 |
2cb2bcfd727ba3dd2749cd6e59db8f33fce05342cb87bc0d1b678e7a5866ea19
|
Provenance
The following attestation bundles were made for synth_containers-0.4.1.dev20260817-py3-none-any.whl:
Publisher:
publish-pypi.yml on synth-laboratories/containers
-
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.dev20260817-py3-none-any.whl -
Subject digest:
0aea621ca449a6bc84cbb81ecfa2ef31137c40f608638fd5040e136e30b7c9d2 - Sigstore transparency entry: 2535581571
- Sigstore integration time:
-
Permalink:
synth-laboratories/containers@ec25929ebbe284e11987280d1b75d5b133b75c3c -
Branch / Tag:
refs/heads/dev - Owner: https://github.com/synth-laboratories
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish-pypi.yml@ec25929ebbe284e11987280d1b75d5b133b75c3c -
Trigger Event:
workflow_dispatch
-
Statement type:
