deepslate-core

Shared core library for Deepslate's realtime voice AI SDKs.

You probably don't need to install this directly.

Install deepslate-livekit or deepslate-pipecat instead — they pull in deepslate-core automatically. This package is for developers building custom Deepslate integrations outside of LiveKit or Pipecat.

What's Inside

deepslate-core provides everything needed to connect to the Deepslate Realtime API from any async Python application:

• DeepslateSession — High-level session that manages the full WebSocket lifecycle, protobuf framing, session initialization, reconnection, and callback dispatch. The primary building block for custom integrations.
• DeepslateOptions — API credentials and connection configuration
• VadConfig — Server-side Voice Activity Detection parameters
• HostedTtsConfig / HostedTtsMode — Deepslate-hosted (cloned) voice TTS configuration
• ElevenLabsTtsConfig / ElevenLabsLocation — ElevenLabs TTS configuration
• BaseDeepslateClient — Low-level async WebSocket client with exponential-backoff reconnection (used internally by DeepslateSession)
• Protobuf definitions — Compiled .proto bindings for the Deepslate realtime wire protocol

Installation

pip install deepslate-core

Requirements

• Python 3.11 or higher

Dependencies

• aiohttp>=3.10.0 — Async HTTP and WebSocket client
• protobuf>=5.26.0 — Protocol buffer serialization

Usage

This section is for custom integration authors. For standard usage see the LiveKit or Pipecat packages.

Credentials

from deepslate.core import DeepslateOptions

# Load from environment variables (recommended)
opts = DeepslateOptions.from_env()

# Or configure manually
opts = DeepslateOptions(
    vendor_id="your_vendor_id",
    organization_id="your_org_id",
    api_key="your_api_key",
    system_prompt="You are a helpful assistant.",
)

Required environment variables:

DEEPSLATE_VENDOR_ID=your_vendor_id
DEEPSLATE_ORGANIZATION_ID=your_organization_id
DEEPSLATE_API_KEY=your_api_key

VAD Configuration

from deepslate.core import VadConfig

vad = VadConfig(
    confidence_threshold=0.4,   # 0.0–1.0
    min_volume=0.0,             # 0.0–1.0
    start_duration_ms=150,
    stop_duration_ms=390,
    backbuffer_duration_ms=1000,
)

TTS Configuration

Two TTS providers are supported. Pass either config as tts_config to DeepslateSession.create().

Deepslate-hosted (cloned) voice

Use a voice that has been cloned and hosted within Deepslate. No external provider credentials required.

from deepslate.core import HostedTtsConfig, HostedTtsMode

tts = HostedTtsConfig(voice_id="c3dfa73f-a1ab-4aad-b48a-0e9b9fe4a69f")

# Explicit mode selection
tts = HostedTtsConfig(
    voice_id="c3dfa73f-a1ab-4aad-b48a-0e9b9fe4a69f",
    mode=HostedTtsMode.HIGH_QUALITY,  # or HostedTtsMode.LOW_LATENCY
)

HostedTtsMode values:

ElevenLabs

from deepslate.core import ElevenLabsTtsConfig, ElevenLabsLocation

# Load from environment variables
tts = ElevenLabsTtsConfig.from_env()

# Or configure manually
tts = ElevenLabsTtsConfig(
    api_key="your_elevenlabs_key",
    voice_id="21m00Tcm4TlvDq8ikWAM",
    model_id="eleven_turbo_v2",
    location=ElevenLabsLocation.US,  # US (default), EU, or INDIA
)

Experiments

No stability guarantees. Experiments may change or disappear without a version bump or warning.

Deepslate can enable server-side experiments for a session. Pass them as a plain map of experiment name to parameter value. Names are opaque strings; an experiment that takes no parameters is enabled with None:

from deepslate.core import DeepslateOptions

opts = DeepslateOptions.from_env(
    experiments={"example-experiment:1": None},
)

Each experiment defines its own value, so what a value means, and whether one is needed at all, depends on the experiment. Values may be any JSON value: None, booleans, numbers, strings, lists, or nested objects, and a parameter object may be filled in partially:

opts = DeepslateOptions.from_env(
    experiments={
        "example-experiment:1": {"some_setting": "value", "another_setting": 3},
    },
)

The SDK holds no catalogue of experiments: it sends whatever you pass, and the server ignores names it does not know. Ask your Deepslate contact which experiments are available and what values they accept.

DeepslateSession

DeepslateSession is the recommended entry point for custom integrations. It handles the full protocol lifecycle — session initialization, protobuf serialization, reconnection, and server-event routing — delivering events to a DeepslateSessionListener so your code only deals with application logic.

Subclass DeepslateSessionListener and override only the methods you care about, then pass the instance to DeepslateSession.create(). Use create() when your code owns the connection — it creates its own BaseDeepslateClient and closes it automatically when close() is called:

import asyncio
from deepslate.core import (
    DeepslateOptions,
    DeepslateSession,
    DeepslateSessionListener,
    ElevenLabsTtsConfig,
)

class MyListener(DeepslateSessionListener):
    def __init__(self) -> None:
        self.session: DeepslateSession | None = None

    async def on_session_initialized(self) -> None:
        # Session is ready — safe to send the first message
        if self.session:
            await self.session.send_text("What is the capital of France?")

    async def on_text_fragment(self, text: str) -> None:
        print(text, end="", flush=True)

    async def on_audio_chunk(
        self, pcm_bytes: bytes, sample_rate: int, channels: int, transcript: str | None
    ) -> None:
        # Forward PCM audio to your output device / transport
        ...

    async def on_tool_call(self, call_id: str, name: str, params: dict) -> None:
        result = await dispatch_tool(name, params)
        if self.session:
            await self.session.send_tool_response(call_id, result)

    async def on_error(self, category: str, message: str, trace_id: str | None) -> None:
        print(f"[{category}] {message}")

    async def on_response_begin(self) -> None:
        print("\n--- response start ---")

    async def on_response_end(self) -> None:
        print("--- response end ---\n")


async def main():
    opts = DeepslateOptions.from_env(
        system_prompt="You are a helpful assistant."
    )
    tts = ElevenLabsTtsConfig.from_env()
    listener = MyListener()

    session = DeepslateSession.create(
        opts,
        tts_config=tts,
        user_agent="MyApp/1.0",
        listener=listener,
    )
    listener.session = session
    session.start()

    # Initialize for text-only interaction (audio sessions initialize automatically).
    # on_session_initialized will be called once the session is ready.
    await session.initialize(sample_rate=24000, channels=1)

    await asyncio.sleep(5)  # Wait for response
    await session.close()


asyncio.run(main())

Sending audio

Audio sessions initialize automatically on the first send_audio() call. The session also sends a ReconfigureSessionRequest transparently if the audio format changes mid-session:

# pcm_bytes: raw signed 16-bit PCM
await session.send_audio(pcm_bytes, sample_rate=16000, channels=1)

Updating tools at runtime

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the weather for a city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string"}
                },
                "required": ["city"],
            },
        },
    }
]

await session.update_tools(tools)

Tool definitions are re-synced automatically after every reconnect.

Reconnection

start() drives BaseDeepslateClient.run_with_retry() internally. On a dropped connection the session resets its state, re-sends InitializeSessionRequest, re-syncs tool definitions, and resumes — all without any action required from your code. Call close() to stop the retry loop permanently.

API Reference

DeepslateSession.create()

Factory that creates a session together with its own BaseDeepslateClient. The session owns the client and closes it when close() is called.

DeepslateSession — send methods

DeepslateSessionListener

Subclass this and override only the methods you need. All methods are async and default to no-ops.

DeepslateOptions

VadConfig

Documentation

• Deepslate Documentation
• API Reference

License

Apache License 2.0 — see LICENSE for details.