Sympheny Toolbox

The official typed Python client for the Sympheny SaaS API: every documented endpoint as a typed method, synchronous and asynchronous, with authentication handled for you.

Documentation

Full documentation lives at https://docs.sympheny.com/:

• SDK guide and reference: https://docs.sympheny.com/sdk/
• REST API reference: https://docs.sympheny.com/api/

Install

pip install sympheny-toolbox

Requires Python 3.11+.

Quick start

from sympheny_toolbox import Sympheny

client = Sympheny("you@example.com", "your-password")

for project in client.projects.list():
    print(project.project_name)

The same API is available asynchronously via AsyncSympheny:

from sympheny_toolbox import AsyncSympheny

async with AsyncSympheny("you@example.com", "your-password") as client:
    projects = await client.projects.list()

Endpoints are grouped on the client the way the documented API groups them (client.projects, client.analyses, client.scenarios, client.hubs, client.solver_jobs, and so on); see the SDK reference. Requests and responses use Pydantic models generated from the OpenAPI spec (sympheny_toolbox.models). Higher-level helpers that combine several calls, such as running a solver job and downloading its results, live in sympheny_toolbox.workflows and are documented under Workflows.

Failed requests raise sympheny_toolbox.errors.SymphenyError subclasses: AuthenticationError (401), PermissionDeniedError (403), NotFoundError (404), APIError (any other unsuccessful status), and UnexpectedResponseError.

Development

The client is layered: the merged OpenAPI spec in specs/ generates models.py, the hand-written asynchronous client in _async/ is the source of truth, and the synchronous client in _sync/ is generated from it by an unasync-style transform. Regenerate it with uv run python scripts/generate_sync.py after changing anything under _async/.

Run every check (drift check, ruff, mypy, tests under coverage) with ./scripts/check.sh. Tests live under tests/ and run against a mock API (httpx.MockTransport), so they need no credentials and never reach the real Sympheny API.

To release: bump the version in pyproject.toml, add the matching CHANGELOG.md entry, and push a vX.Y.Z tag. The publish workflow checks that the tag matches the project version, runs all checks, and publishes to PyPI.