Docs /guides/ Sinapsis Protocol Quickstart
guides / protocol

Sinapsis Protocol Quickstart

Install sinapsis-protocol and serialize, restore and store DataContainers.

protocolpythonquickstartDocumentation latest

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:

Terminalbash
pip install sinapsis-protocol

Optional adapters:

Terminalbash
pip install 'sinapsis-protocol[numpy]'
pip install 'sinapsis-protocol[torch]'
pip install 'sinapsis-protocol[pandas]'
pip install 'sinapsis-protocol[polars]'

Everything optional:

Terminalbash
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:

python
from sinapsis_protocol import (
    serialize_data_container,
    deserialize_data_container,
)

packet = serialize_data_container(data_container)
restored = deserialize_data_container(packet)

For example:

python
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:

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

python
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