Skip to content

Python SDK

The SLIM Python SDK (slim-bindings) provides an idiomatic Python API for building applications on SLIM. Bindings are generated from the same Rust core as every other language binding via UniFFI, with async/await support through asyncio and native libraries bundled into platform-specific wheels.

Requirements
Runtime Python 3.10 or higher
Package slim-bindings on PyPI
Examples python/examples in slim-bindings

The PyPI package ships native libraries for Linux, macOS, and Windows on x64 and arm64. No additional runtime setup is required after install.

Installation

pip install slim-bindings

Add to your pyproject.toml:

[project]
dependencies = ["slim-bindings"]

uv add slim-bindings

Getting Started

The SDK tutorials build a full application step by step — initialising the service, connecting to a node, creating an app, opening sessions, receiving messages, and adding persistence — with Python snippets shown alongside every other binding.

Start with Connecting to SLIM.

API Overview

Type Description
slim_bindings module Static entry point for initialisation and global service access
Service Manages connections and creates apps
App Application handle for sessions, subscriptions, and routing
Session Session for sending and receiving messages
Name Identity in org/namespace/app format
ReceivedMessage Received message with payload (bytes) and context metadata
SessionConfig Session configuration (type, MLS, retries)
ClientConfig Client connection configuration (endpoint, TLS, transport auth)
ServerConfig Server listen configuration (endpoint, TLS, transport auth)
OidcConfig OIDC transport authentication settings
OidcPolicyConfig Claim-based access policy (CEL, REGO, REGO_FILE)

UniFFI async methods require registering the running event loop with uniffi_set_event_loop before calling any async API.

Session Configuration

session_config = slim_bindings.SessionConfig(
    session_type=slim_bindings.SessionType.POINT_TO_POINT,
    max_retries=5,
    interval=datetime.timedelta(seconds=5),
    metadata={},
    mls_settings=slim_bindings.MlsSettings(
        header_integrity_validation_percent=100,
        max_seen_control_message_ids_size=None,
    ),
)

session = await app.create_session_and_wait_async(session_config, remote_name)

SessionConfig and MlsSettings take keyword arguments only and define no defaults, so every field must be passed. max_retries=None and interval=None fall back to the SLIM defaults, and mls_settings=None disables MLS.

Transport Authentication

Separate from the app identity passed to create_app_with_secret, the gRPC connection to a SLIM node can carry its own credentials.

OIDC (client credentials)

import datetime

oidc = slim_bindings.OidcConfig(
    issuer_url="https://auth.example.com",
    client_id="my-client",
    client_secret="s3cr3t",
    scope="openid profile",
    timeout=datetime.timedelta(seconds=30),
)

base = slim_bindings.new_insecure_client_config("http://127.0.0.1:46357")
client_config = slim_bindings.ClientConfig(
    **{**vars(base), "auth": slim_bindings.ClientAuthenticationConfig.OIDC(config=oidc)}
)
conn_id = await service.connect_async(client_config)

For the refresh-token flow, set refresh_token (or refresh_token_file, which is rewritten in place as tokens rotate) instead of client_secret.

OIDC (server verification)

oidc = slim_bindings.OidcConfig(
    issuer_url="https://auth.example.com",
    audience="slim",
    jwks_ttl=datetime.timedelta(hours=1),
    claim_cache_ttl=datetime.timedelta(minutes=1),
    policy=slim_bindings.OidcPolicyConfig.CEL(
        expression='"admin" in claims.groups'
    ),
)

base = slim_bindings.new_insecure_server_config("127.0.0.1:46357")
server_config = slim_bindings.ServerConfig(
    **{**vars(base), "auth": slim_bindings.ServerAuthenticationConfig.OIDC(config=oidc)}
)
await service.run_server_async(server_config)

policy accepts OidcPolicyConfig.CEL, OidcPolicyConfig.REGO (which must define package slim.auth with default allow = false), or OidcPolicyConfig.REGO_FILE.

JSON configuration

new_config_from_json accepts a full gRPC client config covering TLS material, backoff, and every authentication mode (basic, static_jwt, jwt, spire, oidc):

{
  "endpoint": "http://127.0.0.1:46357",
  "tls": { "insecure": true },
  "auth": {
    "type": "oidc",
    "issuer_url": "https://auth.example.com",
    "client_id": "my-client",
    "client_secret": "s3cr3t",
    "audience": "slim",
    "policy": { "cel": "\"admin\" in claims.groups" }
  }
}

The schema matches the client configuration schema in the slim repository.

SLIMRPC

The Python SDK includes SLIMRPC support for Protobuf-based RPC over SLIM. Install the protoc-gen-slimrpc-python plugin and add it to your buf.gen.yaml alongside the standard Python protobuf plugin. See the SLIMRPC Compiler and the Serving and Client tutorials.

Examples

The slim-bindings/python directory includes complete working examples:

Example Description
examples/point_to_point 1:1 messaging with request/reply
examples/group Group sessions with moderator/participant roles
examples/slimrpc/simple Protobuf RPC over SLIM

Point-to-point:

cd python
task examples:p2p:alice    # Receiver
task examples:p2p:no-mls:bob   # Sender (in another terminal)

SLIMRPC (requires a running SLIM node and generated proto code):

task examples:rpc:server
task examples:rpc:client

Platform Support

Platform Architecture Status
Linux x86_64 Supported
Linux aarch64 Supported
macOS x86_64 Supported
macOS aarch64 (Apple Silicon) Supported
Windows x86_64 Supported

Wheels bundle the correct native library for each platform automatically.

Building from Source

To build the Python SDK from the slim-bindings repository:

git clone https://github.com/agntcy/slim-bindings
cd slim-bindings/python

# Build and install in development mode
task build

To create distributable wheels:

task python:bindings:packaging

See the python README for the full list of development tasks.

Next Steps