Skip to content

README.md

Latest commit

 

History

History
261 lines (203 loc) · 9.82 KB

README.md

File metadata and controls

261 lines (203 loc) · 9.82 KB
Raw

Synth AI SDK

PyPI version License Python versions

Python SDK and CLI for Synth Index, 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.sdk.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.sdk.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.sdk.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

Project creation also accepts the backend-owned ProjectSpec.policy mapping. For example, a server-enabled fresh project can request policy={"host_resource_custody_mode": "horizons_docker_sessions_only"}. The backend validates this restricted mode and owns its immutable resource binding; SDK serialization does not grant additional authority.

Container pools

The optional synth-ai[pools] extra exposes the canonical synth-containers client through AsyncSynthClient.pools. It uses the same configured backend credential and keeps hosted admission, resource ownership, and recovery in the backend. The enclosing async client closes the pool transport.

from synth_ai import AsyncSynthClient

async def inspect_lease(lease_id: str, task_id: str):
    async with AsyncSynthClient() as client:
        return await client.pools.get_lease_interactive(lease_id, task_id=task_id)

For explicit lifetime management, from synth_ai.pools import PoolClient re-exports the same implementation. Research-only installations do not import this optional dependency. Development candidates must install the exact pinned containers wheel; an unpublished candidate extra is not a release claim.

CLI

synth-ai --help
synth-ai research --help

Public Surface

Use SynthClient as the front door:

Surface Client namespace Use it for
Index client.index Authenticated, funded FAST/DEEP Search and Contribution lifecycle.
Research / Factory client.research Typed hosted projects, swarms, Factory lifecycles, and Efforts.
CLI / MCP synth-ai, synth-ai-index-mcp Terminal commands and an Index-only coding-agent server.

Index is an API/MCP product, not a browser search page. Anonymous public catalog and known-ID Contribution reads use PublicIndexClient; even a public-scope Search requires an API key, an authorized organization, and funding. An Index-only MCP server starts read-only, advertising public browse without a key and Search only when a key is configured. Contribution writes require a separate explicit opt-in and grant.

from uuid import uuid4

from synth_ai import SynthClient
from synth_ai.sdk.index import SearchBillingConstraints

request_key = str(uuid4())  # Persist this before sending; reuse it on uncertain retry.
with SynthClient() as synth:  # Reads SYNTH_API_KEY.
    result = synth.index.search(
        query="What evidence supports the retrieval design?",
        mode="fast",
        billing=SearchBillingConstraints(allow_wallet=True, max_charge_cents=5),
        idempotency_key=request_key,
    )
    print(result.response, result.usage)

FAST's five-cent ceiling is explicit wallet consent, not a claim that DEEP has the same price. See the Index SDK guide for DEEP's durable Search ID, reconnect/cancel, private collections, receipts, and coding-agent MCP setup. These calls require a deployed Index API; installing the SDK alone does not make a Search available.

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