Synth Python SDK
A typed Python client for Synth Index search with citations, Swarms research runs, account access, and hosted or local MCP. Python 3.11 or newer is required.
Swarms requires organization admission. An unavailable operation raises
UnsupportedOperationError with code operation_unavailable. Inspect
client.account.entitlements() for your organization's access conditions.
pip install synth-ai
pip install 'synth-ai[mcp]'
synth-ai login
Use browser login or set SYNTH_API_KEY. Stored login credentials are reloaded
on every authenticated call. SYNTH_API_URL overrides the default API origin,
https://api.usesynth.ai. Anonymous Index search needs no login or API key.
from synth_ai import SynthClient
from synth_ai.sdk.index import PublicSearchOptions
with SynthClient.anonymous() as client:
result = client.index.search("reproducible retrieval", options=PublicSearchOptions())
print(result.response)
Authenticated search has an explicit maximum charge:
from synth_ai import SynthClient
from synth_ai.sdk.index import KeyedSearchOptions
from synth_ai.types.money import Money
with SynthClient() as client:
result = client.index.search(
"reproducible retrieval",
options=KeyedSearchOptions(maximum_charge=Money(coefficient=5, scale=2)),
)
print(result.response)
Create a Swarms project, launch bounded work, wait, and download its results:
from synth_ai import SynthClient
from synth_ai.options import ObservationOptions
from synth_ai.sdk.swarms import Limits
from synth_ai.types.money import Money
with SynthClient() as client:
project = client.swarms.projects.create("Research", objective="Compare retrieval methods")
run = client.swarms.create(message="Compare retrieval methods", project_id=project.project_id,
limits=Limits(maximum_charge=Money(coefficient=2, scale=0), wall_time_seconds=600,
maximum_tasks=4, maximum_parallel_tasks=2))
result = run.wait(observation=ObservationOptions(timeout_seconds=660, idle_timeout_seconds=120,
reconnect_deadline_seconds=30, retry_count_max=3, maximum_events=2000, poll_interval_seconds=2))
bundle = run.download("research-results")
The download verifies exact repository and artifact digests before publishing a
new destination directory. Its manifest records the run reference, final commit,
artifacts, objective verdicts, and answers. Existing destinations are refused.
See Swarms for input artifacts, guidance, resources, controls,
and usage. Both SynthClient and AsyncSynthClient expose the same operations;
async methods are awaited and clients support managed contexts.
Catch SynthError for API and transport failures. Common types are
AuthenticationError, RateLimitError, BudgetExceededError,
RequestTimeoutError, and OutcomeUncertainError.
After OutcomeUncertainError, resolve the retained identity before deciding
whether to submit new work: client.resolve_mutation(error.identity).
MutationCancelledError derives from asyncio.CancelledError and also retains
its mutation identity. A local timeout or closing a client does not cancel a run.
Requests have total deadlines. Reads retry transient failures with bounded
jitter and honor Retry-After. Mutations are never automatically replayed.
Call run.cancel(), run.pause(), or run.resume() for remote controls.
Use a stable MutationOptions(idempotency_key=...) for recoverable writes.
Errors carry operation and request identifiers. Responses accept additive
fields; unknown enum values remain visible. ClientOptions(strict_contract=True)
requires exact schema hashes. Client options can borrow caller-owned HTTPX
clients; closing the SDK leaves a borrowed client open. File-based login requires
POSIX ownership and permissions; explicit API keys work on other platforms.
Account companion
The source candidate extends the existing synth-ai CLI with read-only cloud
account commands. Its version follows the SDK and MCP package:
synth-ai --version
synth-ai login
synth-ai auth status --json
synth-ai account context --json
synth-ai account plan
synth-ai account balance
synth-ai account alerts
synth-ai account usage --days 7 --json
synth-ai account logs --days 7 --limit 50 --json
synth-ai account billing
synth-ai account keys
synth-ai account apps
Billing, API-key lifecycle and connected-app management open the dashboard;
these commands never purchase, change subscriptions or run workloads. Use
--no-browser for a URL. Set SYNTH_DASHBOARD_URL to the dashboard origin when
using a custom API origin. API-key setup also supports the existing
synth-ai login --with-token stdin flow. Private-file storage and canonical
SYNTH_API_KEY / SYNTH_API_URL precedence remain unchanged.
The new account reads require a backend serving account.v1 and explicit
account scopes for financial data. Self-identity/context inspection is available
to every valid customer credential, without workload capability discovery.
account:read permits limits together with billing-read; account:billing:read permits
plan/balance/alert settings, and usage/logs require both usage-read and billing-read. Existing
credentials do not gain these grants automatically. Fresh OAuth consent names
the account permissions. The existing account limits discovery command keeps
its negotiated product-policy contract.
SDK sync/async clients expose account.context(), plan(), balance(),
alerts(), limits(), usage(start, end) and events(start, end). Event reads return one
bounded page and an explicit cursor. Dates must be timezone-aware; windows are
bounded to 366 days. The CLI also accepts matching --from / --to timestamps
and an optional --product filter for usage/logs.
JSON retains exact money coefficients/scales, original event IDs and string sequence numbers, pending/unknown values, source coverage and observation times. Successful reads exit 0, including explicitly partial observations; refused or unavailable operations exit 1, and invalid command/input exits 2. Account reads use their own observational protocol and do not claim Index/Swarms execution manifest qualification. Native issuer, installed-package and deployed-cohort acceptance remain required before release.
1 maintainer
Metadata
1 maintainer
Release files for synth-ai 0.23.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| synth_ai-0.23.6-py3-none-any.whl | Python 3 | none | any | Details |
Release files / synth_ai-0.23.6-py3-none-any.whl
| Download URL | synth_ai-0.23.6-py3-none-any.whl |
|---|---|
| Size | 352.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d24d62703ba345000069c669141feee3e7a0e7387e7cdf696f9bb70e83f66e05
|
|
BLAKE2b-256 checksum How to use checksums |
3e6852ada5cf6dccc74cfe1c20075fea96e28779eb5f663821d179dba3ad33e4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Oct 23, 2026.
Transparency logSecurity for synth-ai 0.23.6
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.
Full provenance
All 1 file in this release has been uploaded with provenance metadata.
Attestation for synth_ai-0.23.6-py3-none-any.whl
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 Oct 23, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
