This release is a pre-release and may not be stable for production use.
Synth AI SDK
Python SDK and CLI for Managed Research and Research Factory.
Documentation: https://docs.usesynth.ai/sdk/overview
Installation
uv add synth-ai
Authenticate
Set SYNTH_API_KEY before using the SDK or CLI:
export SYNTH_API_KEY="sk_..."
Local Workspaces
For local multi-repo development, synth-ai treats workspace resolution as a
read-only overlay. .env and Synth home config may provide defaults and
secrets; selecting a worktree must not rewrite those defaults.
Use SYNTH_WORKSPACE_MANIFEST or SYNTH_WORKSPACE_ROOT for command-scoped
worktree resolution. The resolver in synth_ai.core.utils.workspace returns
repo paths and a scoped env mapping for subprocesses without mutating .env.
Pass base_url when you need to pin a production, local, staging, or private
backend explicitly:
from synth_ai import SynthClient
client = SynthClient(base_url="http://127.0.0.1:8000")
The CLI also reads SYNTH_BACKEND_URL and accepts --backend-url.
Quickstart
from synth_ai import SynthClient
from synth_ai.core.research.public import SwarmSpec
with SynthClient() as client:
swarm = client.research.swarms.create(
SwarmSpec(objective="Assess this repository and produce a concise report.")
)
for event in swarm.events():
print(event.kind, event.telemetry.sequence)
result = swarm.wait(timeout_seconds=900)
print(result.swarm_id, result.state)
resolved = swarm.configuration()
print(resolved.config_version_id, resolved.snapshot_sha256)
usage = swarm.usage()
print(usage.money.nominal_pico_usd, usage.tokens.totals.input_tokens)
evidence = swarm.evidence()
print(evidence.artifacts, evidence.work_products)
create returns a durable handle immediately. events() yields typed events,
including an explicit UnknownSwarmEvent for forward-compatible server events;
wait() uses a monotonic deadline and returns the terminal typed Swarm.
configuration() returns the immutable, versioned, secret-redacted launch
snapshot bound to that swarm, so replay and audit do not depend on the
project's current mutable configuration.
usage() returns one typed cost, token, and actor-attribution projection plus
its source, record count, observation time, and terminal-state freshness. It
does not expose the legacy raw ledger-entry dictionaries.
evidence() returns the complete durable artifact and WorkProduct index with
strict counts and lifecycle freshness. Artifact and WorkProduct content reads
use the same typed transport and return bytes; they do not expose storage
authority.
Research SDK
The only customer entrypoint is SynthClient().research. Its stable namespaces
are projects, swarms, and factories.
Create a durable project when work needs reusable configuration:
from synth_ai import SynthClient
from synth_ai.core.research.public import EnvironmentKind, ProjectSpec, RuntimeKind, SwarmSpec
with SynthClient() as client:
project = client.research.projects.create(
ProjectSpec(
name="Repository assessment",
pool_id="pool_default",
runtime_kind=RuntimeKind("python"),
environment_kind=EnvironmentKind("docker"),
orchestrator_profile_id="profile_orchestrator",
default_worker_profile_id="profile_worker",
)
)
swarm = client.research.swarms.create(
SwarmSpec(objective="Produce the assessment."),
project_id=project.project_id,
)
print(swarm.wait().state)
Factories provide a typed durable optimization loop with native sync/async parity:
from synth_ai import SynthClient
from synth_ai.core.research.public import EffortSpec, FactorySpec, ProjectId
with SynthClient() as client:
factory = client.research.factories.create(
FactorySpec(name="Prompt optimizer")
)
effort = client.research.factories.efforts.create(
EffortSpec(
factory_id=factory.factory_id,
project_id=ProjectId("project_existing"),
name="Improve the system prompt",
)
)
print(effort.effort_id, effort.state)
Limits, economics, secrets, Tag, rich evidence projections, and administrative
resource APIs remain available under client.research.advanced while their
contracts are stabilized. Advanced APIs are not covered by the stable surface
guarantee.
CLI discovery:
synth-ai research --help
CLI
synth-ai --help
synth-ai research --help
Public Surface
Use SynthClient as the front door:
| Surface | Client namespace | Use it for |
|---|---|---|
| Research / Factory | client.research |
Typed hosted projects, swarms, Factory lifecycles, and Efforts. |
| CLI | synth-ai |
Terminal access to Research commands. |
Infrastructure clients (containers, tunnels, pools) are parked under old/ for
later restoration and are not composed on SynthClient right now.
Use Managed Research when you want hosted research workers, repo runs, evidence, checkpoints, MCP, or final reports.
Managed Research Billing
Standalone SMR and Managed Factory draw from the same org-level allowance and flex-credit wallet. Free, Standard ($20/month), and Max ($200/month) expose premium and value usage windows with reset times, then use explicit flex credits after included usage is exhausted. Premium models consume allowance faster; value models stretch the same allowance further. Promo, make-good, banked, and override grants are manual audit events rather than automatic resets.
The canonical backend surfaces are GET /smr/billing/catalog,
GET /smr/billing/plan, GET /smr/billing/runs/{run_id}/drawdown, and
GET /smr/billing/factory-efforts/{factory_effort_id}/drawdown. In the Python
SDK, use client.research.advanced.economics for authoritative billing reads
while the economics contract remains advanced. Do not infer
allowance from legacy Autumn balances or local spend summaries, and do not
recompute discounts in the client.
Links
Local Development
Use uv run for Python tools:
uv sync --group dev
uv run ruff format --check .
uv run ruff check .
uv run ty check
make docs-gen # generate Mintlify SDK reference into docs/
make docs-dev # preview at http://localhost:3000/overview
Optional: install Lefthook and run
lefthook install to run formatting, linting, and type checks on staged Python
files.
SMR Handoff X thread — hand agent tasks to Managed Research from Cursor, Codex, or Claude Code (repo).
1 maintainer
Release files for synth-ai 0.17.5.dev589
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| synth_ai-0.17.5.dev589.tar.gz | 709.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| synth_ai-0.17.5.dev589-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.5 MB
Release files / synth_ai-0.17.5.dev589.tar.gz
| Download URL | synth_ai-0.17.5.dev589.tar.gz |
|---|---|
| Size | 709.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e18132bb4564066d8750711244a6b265d019a83e0f4c46a9b4478b8ca9e413aa
|
|
BLAKE2b-256 checksum How to use checksums |
ab63b8463add17bc5c9f4c4b0e545895c6a82891966e128f2578156b7d52ffaf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 30, 2026.
Transparency logRelease files / synth_ai-0.17.5.dev589-py3-none-any.whl
| Download URL | synth_ai-0.17.5.dev589-py3-none-any.whl |
|---|---|
| Size | 825.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ff21844a81e3a537ced72f99ddebc82411b33079515be3f54e2b109c09d9e374
|
|
BLAKE2b-256 checksum How to use checksums |
2479eaabe419901749c8b7f3bbdfd580cb820adc9015ff97e9cc53fb02414f58
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 30, 2026.
Transparency log
