Skip to main content


Sinapsis
sinapsis-sdk

Typed Python clients for Sinapsis APIs.

sinapsis-sdk is the asynchronous Python client library for Sinapsis Cloud and the Sinapsis Local API. It provides typed resource methods for submitting Agents, managing executions, discovering Templates, and interacting with supported platform services without hand-building HTTP requests.

The SDK uses sinapsis-contracts for shared request/response types and endpoint definitions, and the sinapsis Python interface for Agent and data models.

Installation

Requires Python 3.13+. Install from the standard Python package index:

uv pip install sinapsis-sdk
# or
pip install sinapsis-sdk

For a project managed by uv, use uv add sinapsis-sdk.

Choose a client

Client Import Purpose
CloudSinapsisAPIClient sinapsis_sdk.cloud_api.client Authenticated Cloud execution, saved Agents, schedules, Templates and platform resources.
SinapsisAPIClient sinapsis_sdk.local_api.client Execution and job control through a running Local API.

Both clients are asynchronous and support async with for automatic HTTP connection cleanup. Call await client.aclose() if you do not use a context manager.

The Local API and Cloud are different execution backends. A method supported by one is not necessarily available on the other.

Sinapsis Cloud

Configure access

Set up a Cloud account and credentials using the Sinapsis CLI:

sinx-cloud configure
sinx-cloud profiles show cloud

Don't have an account? Visit sinapsis.tech to create one.

The Cloud client uses your configured credentials. For API integrations, the SDK also supports scoped API-key authentication. Use an appropriate key scope for the operation being performed.

Connect and discover Templates

import asyncio

from sinapsis_sdk.cloud_api.client import CloudSinapsisAPIClient


async def main() -> None:
    async with CloudSinapsisAPIClient() as client:
        results = await client.templates.search("vision", limit=10)
        for template in results.items:
            print(template.get("class_name"), template.get("description"))


asyncio.run(main())

The default Cloud API endpoint is https://api.sinapsis.tech/. To use another deployment, pass an explicit configuration:

from sinapsis_sdk.cloud_api.client import CloudSinapsisAPIClient
from sinapsis_sdk.cloud_api.cloud_config import CloudAPIConfig

client = CloudSinapsisAPIClient(
    CloudAPIConfig(api_url="https://api.sinapsis.tech/", timeout=30.0)
)
# Use the client inside async code and close it with await client.aclose().

Cloud resource reference

Resources are accessed as attributes of CloudSinapsisAPIClient:

Resource Representative methods What it does
client.jobs submit, get_status, get_result, stream_results, cancel Submit a definition and inspect, stream or cancel its execution.
client.agents register, list, get, publish, versions, version, latest_version, all_versions Manage saved Agents and immutable versions.
client.schedules create, list, get, update, pause, resume, runs, delete Schedule an existing saved Agent version.
client.templates list, search, get, packages, search_registry Search available Templates and packages.
client.files upload, list, create, search, get, fetch, delete Work with Cloud files.
client.secrets create, list_user_secrets, get, delete Manage secret metadata and creation.
client.api_keys issue, generate, list_scoped, delete, validate Issue and manage scoped API keys.
client.webhooks register, list_user_webhooks, get, toggle, delete Manage webhook integrations.

The SDK also exposes archived_recent_results() and archived_stream_results() on client.jobs for bounded historical result retrieval where supported by the Cloud API.

Submit an Agent

A Cloud job can be submitted directly from an Agent definition; registration is not required for immediate execution.

import asyncio
from pathlib import Path

import yaml
from sinapsis_sdk.cloud_api.client import CloudSinapsisAPIClient


async def main() -> None:
    definition = yaml.safe_load(Path("agent.yaml").read_text())

    async with CloudSinapsisAPIClient() as client:
        job = await client.jobs.submit(definition)
        print("Job ID:", job.job_id)

        status = await client.jobs.get_status(job.job_id)
        print("Status:", status.state)


asyncio.run(main())

PyYAML is used only to load the example file; install it separately if needed. submit() returns AgentCreateResponse. get_status() returns AgentStatusResponse.

For streaming, use async for message in client.jobs.stream_results(job_id). The SDK decodes MessagePack output and filters control sentinels rather than exposing them as ordinary Agent results.

Save and version Agents

from sinapsis_sdk.cloud_api.client import CloudSinapsisAPIClient


async def save_and_publish(
    client: CloudSinapsisAPIClient,
    definition: dict,
    updated_definition: dict,
) -> None:
    registration = await client.agents.register(definition, version="v1")
    print(registration.agent_id, registration.agent_version_id)

    # A new definition creates a new immutable version.
    new_version = await client.agents.publish(
        registration.agent_id,
        updated_definition,
        version="v2",
    )
    print(new_version.id)

The definition and updated_definition variables are Agent-definition dictionaries supplied by the application. Version labels are required for both register() and publish().

Schedule a saved version

from datetime import time

from sinapsis_contracts.cloud_api.models.saved_agent import AgentRegistration
from sinapsis_contracts.cloud_api.models.scheduling import ScheduleCreate, ScheduleType
from sinapsis_sdk.cloud_api.client import CloudSinapsisAPIClient


async def schedule_registered_agent(
    client: CloudSinapsisAPIClient,
    registration: AgentRegistration,
) -> None:
    schedule = ScheduleCreate(
        name="morning-report",
        agent_id=registration.agent_id,
        agent_version_id=registration.agent_version_id,
        schedule_type=ScheduleType.DAILY,
        local_time=time(9, 0),
        timezone="Europe/London",
    )

    created = await client.schedules.create(schedule)
    print(created.id, created.next_run_at)

A schedule refers to one immutable Agent version. Publishing another version does not change an existing schedule. For CLI scheduling commands, see Scheduling.md.

Scoped API keys

from sinapsis_contracts.cloud_api.models.api_key_permissions import ApiKeyPermission
from sinapsis_sdk.cloud_api.client import CloudSinapsisAPIClient


async def issue_reporting_key(client: CloudSinapsisAPIClient) -> str:
    issued = await client.api_keys.issue(
        "reporting-service",
        scopes=[ApiKeyPermission.JOBS_READ.value],
    )
    # Store securely: the plaintext value is shown only on creation.
    return issued.api_key

Choose only the permissions needed by the integration. Listing keys returns metadata, not the original plaintext value.

Sinapsis Local API

The local client communicates with a running sinapsis-api service. It does not run Agents within the SDK process.

import asyncio

from sinapsis.agent import AgentSchema, generic_agent_schema_builder
from sinapsis_sdk.common.base_config import BaseAPIConfig
from sinapsis_sdk.local_api.client import SinapsisAPIClient


async def main(agent_definition: dict) -> None:
    schema: AgentSchema = generic_agent_schema_builder(agent_definition)

    async with SinapsisAPIClient(
        BaseAPIConfig(api_url="http://127.0.0.1:8005")
    ) as client:
        submitted = await client.jobs.submit(schema)
        status = await client.jobs.get_status(submitted.job_id)
        print(submitted.job_id, status.status)


# Call asyncio.run(main(your_agent_definition)) with an Agent dictionary.
Local resource Method Return type / behaviour
client.jobs.submit(schema) Submit a validated AgentSchema StartJobResponse
client.jobs.get_status(job_id) Retrieve job state JobResponse
client.jobs.get_result(job_id) Read retained events list[LocalJobEvent]
client.jobs.stream_results(job_id, after=0) Stream decoded events Async iterator of LocalJobEvent
client.jobs.cancel(job_id) Request cancellation JobActionResponse
client.jobs.feedback(job_id, request) Respond to an approval request ApprovalResponse

LocalJobEvent preserves both the decoded SSEEnvelope (event.envelope) and its event-stream metadata (event.metadata, including the cursor). The Cloud job stream and the Local API event stream intentionally have different result shapes.

Models, transport and errors

  • Agent graph validation remains with sinapsis.agent.generic_agent_schema_builder(). The SDK transports Agent definitions; it does not replace the canonical graph validator.
  • Typed API contracts live in sinapsis-contracts. Resources deserialize responses into Pydantic models where applicable.
  • HTTP errors are represented by SDK exceptions such as AuthenticationError, AuthorizationError, NotFoundError, APIError, and NetworkError from sinapsis_sdk.common.exceptions.
  • Timeouts are configured through CloudAPIConfig or BaseAPIConfig. Established streaming connections are handled separately from ordinary request timeouts.
from sinapsis_sdk.common.exceptions import NotFoundError
from sinapsis_sdk.cloud_api.client import CloudSinapsisAPIClient


async def print_job_state(client: CloudSinapsisAPIClient, job_id: str) -> None:
    try:
        status = await client.jobs.get_status(job_id)
        print(status.state)
    except NotFoundError:
        print("Job not found or not accessible")

Documentation and resources

License

Sinapsis open-source components are available under your choice of the MIT License; or the Apache License 2.0 unless otherwise noted.

Metadata

Release files for sinapsis_sdk 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sinapsis_sdk 1.0.0
File Size Uploaded Provenance Actions
sinapsis_sdk-1.0.0.tar.gz 31.5 kB Without provenance Details for sinapsis_sdk-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sinapsis_sdk 1.0.0
File Interpreter ABI Platform Actions
sinapsis_sdk-1.0.0-py3-none-any.whl Python 3 none any Details for sinapsis_sdk-1.0.0-py3-none-any.whl

Total release size: 71.7 kB

Release files / sinapsis_sdk-1.0.0.tar.gz

Download URL sinapsis_sdk-1.0.0.tar.gz
Size 31.5 kB
Tags Source
SHA-256 checksum
How to use checksums
639db4ec63ae4748bed0e149042a99e5a5d356ae37690b5ed90587ef53e11b69
BLAKE2b-256 checksum
How to use checksums
12815b3ddd1c5ea12b68a3458d879505b9167fd3b391760e95296f705027951f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"22.04","id":"jammy","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / sinapsis_sdk-1.0.0-py3-none-any.whl

Download URL sinapsis_sdk-1.0.0-py3-none-any.whl
Size 40.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e12892962909f02803b1a4505303e906af1ed806ba66c4b008734697e3c46020
BLAKE2b-256 checksum
How to use checksums
5bcea2c8b30adff6168ffd3bd3b7949b0de58a2c2eb8daee0b3187c716d962aa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"22.04","id":"jammy","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for sinapsis_sdk 1.0.0

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page