Sinapsis
A single contract for the AI ecosystem.
Python-native. Type-safe. Composable.
Build AI systems from reusable Python components. Combine models, libraries, APIs, and custom code through a shared computational contract, without coupling your application to one framework or execution environment.
📚 Documentation · 🚀 Tutorials · 🌐 Website
Overview
Sinapsis is a Python framework for building computational systems from reusable Templates and composing them into Agents. A Template encapsulates a capability—a model, an API call, data processing, or any other Python computation. An Agent connects Templates into a declarative workflow through consistent interfaces and a shared data model.
The sinapsis package is the stable, public Python API for this framework. It exposes the interfaces used by applications, integrations, and Template developers while relying on sinapsis-core for the underlying implementation.
Applications · Templates · Integrations · Platform tooling
│
▼
sinapsis
Stable public Python API
│
▼
sinapsis-core
Framework implementation
This separation allows sinapsis-core to evolve without requiring downstream projects to follow internal refactors. Code integrating with the framework should use supported sinapsis.* imports, rather than importing directly from sinapsis_core internals.
sinapsis is a public interface to the core—not a separate runtime or an alternative validation layer.
Why Sinapsis?
Python-first by design
Python is the common language across much of AI and machine learning. Sinapsis builds on that ecosystem instead of replacing it: implement capabilities with ordinary Python code, use familiar libraries and package tooling, and compose those capabilities without repeatedly writing bespoke integration layers.
Use the Python tools you already know. Sinapsis provides the common structure that lets them work together.
Type safety with Pydantic
Sinapsis uses Pydantic to define and validate Agent schemas, Template configuration, and structured framework models. Validation happens at the framework's schema boundaries, so invalid definitions and incompatible configuration values can be caught early rather than surfacing as obscure runtime errors.
This gives Python developers typed models, explicit contracts, and predictable serialization—while retaining the flexibility of Python and declarative YAML configuration.
A single computational and data contract
Templates communicate through a common data model built around DataContainer and typed packets for content such as text, images, audio, time series, and binary data. Components can focus on their own computation rather than inventing new data conventions for every integration.
Compose and reuse
Build a capability once as a Template, use it across Agents, or compose Agents into larger systems. Sinapsis supports declarative dependencies, orchestration, and reusable configurations across different AI/ML domains—not just LLM applications.
Separate what runs from where it runs
The Agent and Template contract describes the computation independently of its execution environment. The wider Sinapsis ecosystem can build on that contract for local, remote, and distributed execution without requiring a new application model.
Installation
Python 3.13 is required. We recommend uv, although pip is also supported.
With uv:
uv venv --python 3.13
source .venv/bin/activate
uv pip install sinapsis
Or with pip:
python3.13 -m pip install sinapsis
No --extra-index-url is needed. Install additional Template packages only for the capabilities your application uses; these may bring their own optional dependencies.
Quick start
1. Define an Agent
Create agent.yml:
agent:
name: hello_world
templates:
- template_name: Input
class_name: InputTemplate
attributes: {}
- template_name: HelloWorld
class_name: HelloWorld
template_input: Input
attributes:
display_text: "Hello from Sinapsis!"
An Agent defines what runs and how Templates connect. The Template classes referenced in a configuration must be available in the environment when the Agent is executed.
2. Validate the definition through Python
The sinapsis.agent module exposes the canonical Agent schema builder:
from pathlib import Path
import yaml
from sinapsis.agent import AgentSchema, generic_agent_schema_builder
configuration = yaml.safe_load(Path("agent.yml").read_text(encoding="utf-8"))
agent_schema: AgentSchema = generic_agent_schema_builder(configuration)
# Export a JSON-compatible definition for APIs, storage, or other integrations.
validated_definition = agent_schema.model_dump(mode="json")
generic_agent_schema_builder() validates the definition using the canonical core schema and returns an AgentSchema Pydantic model. Consumers should reuse this validation path, not create a second Agent-graph validator or alter core-generated schema fields.
3. Use the common data model
The public interface also exposes the framework's shared transport types:
from sinapsis.data_transport import DataContainer
Templates exchange data through the same container contract instead of requiring a different transport model for every library or modality.
4. Execute your Agent
To run the YAML workflow, use the separately distributed Sinapsis CLI (sinx) or the Sinapsis APIs and platform tooling. For example, in an environment where the CLI and required Templates are installed:
sinx-venv jobs run agent.yml
The CLI is a separate package; installing sinapsis alone does not imply that sinx is installed. See the tutorials and examples for end-to-end workflows.
Public API and compatibility
sinapsis exists to give downstream code a clear, durable integration boundary. Core runtime and implementation modules can be reorganized while the supported public imports remain consistent.
For example:
from sinapsis.agent import AgentSchema, generic_agent_schema_builder
from sinapsis.data_transport import DataContainer
When building against Sinapsis:
- Import from
sinapsis.*. Avoid relying on internalsinapsis_core.*module locations. - Validate through the canonical schema builder. Keep one authoritative definition of an Agent and its structure.
- Preserve typed contracts. Use the framework's Pydantic schemas and common data containers rather than custom parallel representations.
- Rely on package boundaries. Use public API contracts for integrations; treat undocumented core internals as implementation details.
The public API is intentionally smaller than the full set of internal symbols in sinapsis-core. Stability applies to supported interfaces, not every implementation detail.
Repository
Sinapsis is developed in the Sinapsis Hub monorepo alongside sinapsis-core, Template packages, applications, and platform services. Each package has its own responsibilities and release lifecycle.
This README documents the sinapsis Python distribution. For the broader ecosystem, architecture, and deployment options, see the monorepo README and official documentation.
Documentation and resources
License
Unless otherwise noted, sinapsis is dual-licensed under your choice of the MIT License or the Apache License, Version 2.0 (MIT OR Apache-2.0). See LICENSE-MIT and LICENSE-APACHE in the monorepo for the full terms.
Build faster. Integrate less. Get to production sooner.
Metadata
Release files for sinapsis 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-1.0.0.tar.gz | 36.4 kB | Without provenance | Details for sinapsis-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sinapsis-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for sinapsis-1.0.0-py3-none-any.whl |
Total release size: 54.0 kB
Release files / sinapsis-1.0.0.tar.gz
| Download URL | sinapsis-1.0.0.tar.gz |
|---|---|
| Size | 36.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b35d9d8f5c27f5dc76f0414fe820be0aec7ba07de2c341e5925e3d3d5577b7d3
|
|
BLAKE2b-256 checksum How to use checksums |
a717bc219ad71c786a399a94e01426edb9edec2f466a2328e0ddaefdd4fdd744
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.17
|
Release files / sinapsis-1.0.0-py3-none-any.whl
| Download URL | sinapsis-1.0.0-py3-none-any.whl |
|---|---|
| Size | 17.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7cf9a29c560f2a84414d24f248038bdf9cfca89d6e60180cffdd04925e9f971a
|
|
BLAKE2b-256 checksum How to use checksums |
18eef763577670d0534249cd7a84e45b0f994e7266e9eb6878d2023a72db257f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.17
|
Security for sinapsis 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.