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, andNetworkErrorfromsinapsis_sdk.common.exceptions. - Timeouts are configured through
CloudAPIConfigorBaseAPIConfig. 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.