sinapsis-contracts
Shared, typed API contracts for the Sinapsis ecosystem.
sinapsis-contracts defines the HTTP request and response models, endpoint paths, enums, and shared transport constants used by Sinapsis APIs, the Python SDK, and CLI integrations.
Contracts keep API consumers and providers aligned. The package is intentionally distinct from the Sinapsis Agent runtime: it describes how services exchange information, not how a workflow is executed.
Installation
Requires Python 3.13+ and uses Pydantic for typed validation.
uv pip install sinapsis-contracts
# or
pip install sinapsis-contracts
Applications using sinapsis-sdk ordinarily receive sinapsis-contracts as a dependency automatically.
Package structure
| Module | Contents |
|---|---|
sinapsis_contracts.common.paths |
API base version and health endpoint constants. |
sinapsis_contracts.common.sentinels |
Shared Sinapsis stream and completion sentinels. |
sinapsis_contracts.cloud_api.models |
Cloud Agent execution, status, saved-Agent/version, scheduling, metrics, secret, webhook and package-index models. |
sinapsis_contracts.cloud_api.paths |
Cloud endpoint path constants for Agents, Management, scheduling, files, secrets, API keys, webhooks and documentation. |
sinapsis_contracts.local_api.models |
Local API requests and responses for Agents, jobs, approval feedback and health. |
sinapsis_contracts.local_api.paths |
Local API Agent and job endpoint paths. |
sinapsis_contracts.cloud_api.models.api_key_permissions |
Named API-key permission values. |
Import the model or path from its defined package; the top-level sinapsis_contracts package is not intended as an all-in-one export.
Contract boundaries
flowchart LR
Consumer[CLI / SDK / API clients]
C[sinapsis-contracts<br/>Pydantic DTOs · paths · enums]
Server[Local / Cloud APIs]
Core[sinapsis<br/>AgentSchema · Template · DataContainer]
Consumer --> C
Server --> C
C -. transport definitions .-> Core
Server --> Core
One canonical Agent graph
The canonical runtime validator is exposed by sinapsis, not by sinapsis-contracts:
from sinapsis.agent import AgentSchema, generic_agent_schema_builder
agent_schema: AgentSchema = generic_agent_schema_builder(agent_definition)
agent_definition is an application-provided Agent dictionary. Contracts representing saved definitions deliberately preserve them as dict[str, Any]. They must not reinterpret runtime graph fields or introduce a second Agent-schema validation path.
This distinction matters for derived schema content, numeric template_type values, and canonical serialization:
persistable_definition = agent_schema.model_dump(mode="json")
The stored definition remains a JSON-compatible representation of the validated runtime schema.
Local API contracts
The local API defines the following request and response models:
| Model | Purpose |
|---|---|
AgentResponse, AgentsResponse |
Agent creation, listing and process state. |
StartJobRequest, StartJobResponse |
Start a finite execution for an existing Agent. |
JobResponse, JobActionResponse |
Query or cancel a job. |
ApprovalRequest, ApprovalResponse |
Provide approval feedback for an execution. |
HealthResponse |
API health and stream identity. |
from sinapsis_contracts.local_api.models import StartJobRequest
request = StartJobRequest(agent_id="my-agent-id")
payload = request.model_dump(mode="json", exclude_none=True)
# {'agent_id': 'my-agent-id'}
StartJobRequest.payload, when provided, is a base64-encoded serialized DataContainer, not arbitrary JSON. For transport-compatible encoding and decoding, use the SDK and the Sinapsis protocol APIs.
Cloud execution contracts
Cloud Agent execution requests and responses live under cloud_api.models.agents:
from sinapsis_contracts.cloud_api.models.agents.payloads import InlineAgentExecutionRequest
from sinapsis_contracts.cloud_api.models.agents.responses import AgentCreateResponse
request = InlineAgentExecutionRequest(agent_definition=agent_definition)
response = AgentCreateResponse.model_validate({"job_id": "example-job-id"})
agent_definition is a Python dictionary of the user-defined graph. Execution status and cancellation use AgentStatusResponse and AgentCancelResponse respectively.
Saved Agents and immutable versions
Management contracts for saved Agents are defined in sinapsis_contracts.cloud_api.models.saved_agent:
| Type | Role |
|---|---|
AgentRegisterRequest |
Submit a definition and an explicit version label. |
AgentRegistration |
Return registered Agent/version IDs and checksum. |
Agent |
Describe saved identity, ownership and metadata. |
AgentVersion |
Describe an immutable version and its stored definition. |
AgentVersionPublishRequest |
Publish an updated immutable definition. |
AgentRegistrationSource |
Distinguish explicit registration from execution-created records. |
from sinapsis_contracts.cloud_api.models.saved_agent import AgentRegisterRequest
request = AgentRegisterRequest(version="v1", definition=agent_definition)
body = request.model_dump(mode="json", exclude_none=True)
A version label is required. A saved definition is transferred as an opaque JSON-compatible dictionary; the runtime owns the graph semantics.
Scheduling contracts
sinapsis_contracts.cloud_api.models.scheduling provides creation, update, lifecycle and run-history models.
Recurrence types are ONCE, DAILY, WEEKLY, and INTERVAL. They have distinct fields:
| Type | Required recurrence fields |
|---|---|
ONCE |
Timezone-aware run_at timestamp. |
DAILY |
local_time, with an IANA timezone. |
WEEKLY |
local_time plus weekdays (0 Monday through 6 Sunday). |
INTERVAL |
interval_seconds (60–31,536,000). |
The Pydantic model validates that fields match the selected recurrence type; incompatible combinations raise validation errors.
from datetime import time
from uuid import UUID
from sinapsis_contracts.cloud_api.models.scheduling import (
ScheduleCreate,
ScheduleType,
)
schedule = ScheduleCreate(
name="morning-report",
agent_id=UUID("00000000-0000-0000-0000-000000000001"),
agent_version_id=UUID("00000000-0000-0000-0000-000000000002"),
schedule_type=ScheduleType.DAILY,
local_time=time(9, 0),
timezone="Europe/London",
)
The UUIDs above are illustrative; the application must supply real IDs from an accessible saved Agent/version. A schedule is pinned to that specific version.
To replace recurrence settings when updating a schedule, the request nests the complete ScheduleFields model:
from datetime import time
from sinapsis_contracts.cloud_api.models.scheduling import (
ScheduleFields, SchedulePatch, ScheduleType,
)
patch = SchedulePatch(
recurrence=ScheduleFields(
schedule_type=ScheduleType.DAILY,
local_time=time(8, 30),
timezone="Europe/London",
)
)
Other models include AgentSchedule, SchedulePage, ScheduleRun, ScheduleRunPage, ScheduleStatus and OccurrenceStatus. Scheduled occurrences are separate from their execution jobs.
For end-user CLI commands, see Scheduling.md.
Endpoint paths
Endpoint paths are centralized so callers do not duplicate literal API routes. Both Local and Cloud use the /api/v1 API prefix.
from sinapsis_contracts.common.paths import BaseApiPaths
from sinapsis_contracts.local_api.paths import API_JOB_PATHS
job_path = BaseApiPaths.render(
API_JOB_PATHS.job,
base=API_JOB_PATHS.base,
job_id="example-job-id",
)
# /api/v1/jobs/example-job-id
Common path instances include API_AGENT_PATHS, API_JOB_PATHS, AGENT_PATHS, SAVED_AGENT_PATHS, SCHEDULE_PATHS, FILE_PATHS, USER_SECRET_PATHS, and WEBHOOK_PATHS.
The Cloud path classes and Local path classes are distinct. Applications should use the path definitions belonging to their intended API.
Permissions, results and compatibility
ApiKeyPermissiondefines named scopes used when requesting a scoped API key. Scopes do not replace server-side access checks.- Cloud scheduling contracts include
ArchivedResultFrame/ArchivedResultPagefor historical MessagePack frames encoded as base64. - Public models use Pydantic's
model_validate()andmodel_dump(mode="json"). Some request models useextra="forbid"; do not assume every response model has identical unknown-field handling. - The package also defines webhook, secret, file, metric and package-index request/response models used by their respective integrations.
If a request or response contract changes, update its API provider and consumers together. Reuse existing types and paths rather than maintaining local copies of the same contract.
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_contracts 1.0.1
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_contracts-1.0.1.tar.gz | 40.0 kB | Without provenance | Details for sinapsis_contracts-1.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sinapsis_contracts-1.0.1-py3-none-any.whl | Python 3 | none | any | Details for sinapsis_contracts-1.0.1-py3-none-any.whl |
Total release size: 73.7 kB
Release files / sinapsis_contracts-1.0.1.tar.gz
| Download URL | sinapsis_contracts-1.0.1.tar.gz |
|---|---|
| Size | 40.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0b6c0253d4e325f8eb1a3f95a6579195af8aff69256df1dbfc16439a5fa5e9e0
|
|
BLAKE2b-256 checksum How to use checksums |
e99f6b1a3fe7124407c798b740a0c943fa2eead3a770a237c87d21026b185fae
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.17
|
Release files / sinapsis_contracts-1.0.1-py3-none-any.whl
| Download URL | sinapsis_contracts-1.0.1-py3-none-any.whl |
|---|---|
| Size | 33.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
436043a6fd8bd3241bae5c4f0f86850b68d4f721a8914669e65b1cbb6be34c68
|
|
BLAKE2b-256 checksum How to use checksums |
46e8fdb831ada32aca83bd49628f9ea609758761ccf339d8bd531f53b22414b9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.17
|
Security for sinapsis_contracts 1.0.1
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.