Optimizers API
code
synth-optimizers gepa run --config gepa.tomlsynth-optimizers gepa service --db service.sqlite --host 127.0.0.1 --port 8080python
from synth_optimizers import GepaRunresult = GepaRun.from_toml("gepa.toml").execute()result.best_candidateresult.manifest_pathresult.frontier_pathresult.normalized_event_feed_pathresult.cache_profile_pathShared across optimizer algorithms. GEPA adds [gepa] — see GEPA.
- run.run_id
- string
- run.output_dir
- path
- run.seed
- integer
- container.url
- string — optional if command set
- container.command
- string[]
- container.cwd
- path
- container.startup_timeout_seconds
- integer
- dataset.train_split
- string
- dataset.heldout_split
- string
- dataset.train_seeds
- integer[]
- dataset.heldout_seeds
- integer[]
- dataset.filters
- object
- candidate.target_modules
- string[]
- candidate.candidate_id_prefix
- string — optional
- seed_candidate.*
- string fields — baseline prompts
- policy.provider
- string
- policy.model
- string
- policy.base_url
- string — optional
- policy.api_key_env
- string — TOML only, not on rollout wire
- policy.credential_mode
- byok | proxy
- cache.mode
- off | readwrite | readonly
- cache.path
- path
- cache.namespace
- string
| mode | Behavior |
|---|---|
| readwrite | Live run; cache rollouts + proposer |
| readonly | Replay; fail on cache miss |
| off | No SQLite cache |
| Env | Overrides |
|---|---|
| SYNTH_OPTIMIZERS_CACHE_MODE | cache.mode |
| SYNTH_OPTIMIZERS_CACHE_PATH | cache.path |
| SYNTH_OPTIMIZERS_CACHE_NAMESPACE | cache.namespace |
| SYNTH_OPTIMIZERS_CONTAINER_HTTP_TIMEOUT_SECONDS | container HTTP timeout |
| File | Contents |
|---|---|
| best_candidate.json | Deployable prompt overlay |
| result_manifest.json | Run summary, paths, cost, usage |
| candidate_registry.json | All candidates + scores |
| frontier.json | Pareto set |
| events.jsonl | Raw events |
| events.normalized.jsonl | Normalized events |
| cache_profile.json | Cache hits/misses |
| workspace.sqlite | Service mode workspace |
Optional. OpenAPI: gepa-service-v1.yaml
| Route | Method |
|---|---|
| /health | GET |
| /runs | POST |
| /runs/{run_id} | GET |
| /runs/{run_id}/cancel | POST |
| /runs/{run_id}/artifacts | GET |
| /runs/{run_id}/artifacts/{name} | GET |
| /runs/{run_id}/candidates | GET |
| /runs/{run_id}/ws | GET |
Cookbook smoke runs use one-shot gepa run, not the service.