Skip to content

Getting Started

This guide creates a local semantic channel store, appends an event, queries it back, and exposes the same store over HTTP.

Install

python -m pip install -e ".[dev,server]"

For documentation work:

python -m pip install -e ".[docs]"
mkdocs serve

Run the package tests before changing protocol or service behavior:

python -m pytest

Create A Channel

sssn --store .sssn create-channel events --schema demo.Event

Append a semantic event:

sssn --store .sssn append events '{"text":"hello"}' --kind message --source demo

Query it back:

sssn --store .sssn query-events events

The local store will create:

.sssn/
  sssn.sqlite
  artifacts/

Use Python

from sssn import Channel, Event, LocalStore

store = LocalStore(".sssn")
store.create_channel(Channel(name="events", schema="demo.Event", form="log"))
event = store.append_event(
    Event(channel="events", source="demo", kind="message", payload={"text": "hello"})
)

print(event.id)
print(store.query_events("events")[0].payload)

Events receive store cursors when the backend can provide them. Use the returned cursor as after_cursor to continue polling without rereading old events.

Serve A Store

sssn --store .sssn serve --host 127.0.0.1 --port 7700

Call it with the sync client:

from sssn import SSSNClient

client = SSSNClient("http://127.0.0.1:7700")
channel = client.create_channel({"name": "remote-events", "form": "log"})
event = client.append_event({"channel": channel.name, "payload": {"ok": True}})
same_event = client.get_event(event.id)

Use AsyncSSSNClient for async workers and services.

Continue

  • Channels explains the center resource.
  • Local Store covers cursor, artifact, and snapshot behavior.
  • HTTP Client covers remote calls and error envelopes.