Sinapsis Protocol Quickstart
Install sinapsis-protocol and serialize, restore and store DataContainers.
The Python sinapsis-protocol 0.1.0 implementation serializes and reconstructs Sinapsis DataContainer objects. This article is a usage guide, not the UDT architecture specification.
Install
Core:
pip install sinapsis-protocolOptional adapters:
pip install 'sinapsis-protocol[numpy]'pip install 'sinapsis-protocol[torch]'pip install 'sinapsis-protocol[pandas]'pip install 'sinapsis-protocol[polars]'Everything optional:
pip install 'sinapsis-protocol[all]'msgpack is part of the core dependency set. sinapsis_core is intentionally not imported when sinapsis_protocol itself is imported.
Basic usage
The public API for a normal Sinapsis container is:
from sinapsis_protocol import (
serialize_data_container,
deserialize_data_container,
)
packet = serialize_data_container(data_container)
restored = deserialize_data_container(packet)
For example:
import numpy as np
from sinapsis_core.data_containers.data_packet import DataContainer, ImagePacket
container = DataContainer(
images=[
ImagePacket(
content=np.arange(3 * 100 * 100, dtype=np.float32).reshape(3, 100, 100)
)
]
)
packet = serialize_data_container(container)
restored = deserialize_data_container(packet)
assert type(restored) is DataContainer
assert type(restored.images[0]) is ImagePacket
assert type(restored.images[0].content) is np.ndarray
assert restored.images[0].content.shape == (3, 100, 100)
The serializer recursively visits every dataclass field. For the example above, the logical tree is:
DataContainer
└── images
└── ImagePacket
└── content
└── numpy.ndarray
Other fields on ImagePacket (id, source, embedding, generic_data, annotations, etc.) are traversed in the same way.
Artifacts
Large payloads should not have to live inside a single MessagePack allocation. The protocol therefore separates the wire representation from payload storage.
from sinapsis_protocol import LocalArtifactStore, serialize_data_container
store = LocalArtifactStore("/staging", "alice", "agent-123")
packet = serialize_data_container(data_container, artifact_store=store)
ArtifactStore is an abstraction, so a deployment can replace local staging with object storage or another service without changing packet semantics.
API and streaming envelopes
The protocol also describes SSEEnvelope for API/SSE exchanges. Such an envelope holds request/event context and may contain a partial DataContainer. This is distinct from MessagePack wire framing; see the Wire Format article for details and an example.
Next steps
To register packet dataclasses or payload adapters, see Extending the Protocol. To understand codec choices, see Payload Codecs.
Published from Git revision 7b7ba25d627b