Python integration

The gateway image ships a pip-installable package at /opt/speko/python (also installable from the source repo). Requires Python ≥ 3.10; the LiveKit plugin needs the livekit extra.

pip install /opt/speko/python          # inside the container build
pip install "speko-gateway[livekit]"   # with the LiveKit plugin dependency

LiveKit plugin

from speko_gateway.livekit import STT

stt = STT(
    language="en",
    provider="auto",
    model="auto",
    credential_source="auto",
    sample_rate=16_000,
)

sample_rate is forwarded to the provider unchanged — the gateway does not resample, so it has to match what the chosen adapter accepts, and the default of 16_000 does not suit every one. OpenAI STT accepts 24_000 only; sending anything else fails session create as 502 session_open_failed, which names no field. Note the TTS class defaults to 24_000 instead, so the two are not interchangeable.

A livekit.agents.stt.STT subclass with streaming and interim results. It connects to the gateway over the Unix socket automatically and maps gateway events onto LiveKit speech events (speech.started/speech.ended → start/end of speech, transcript.delta → interim, transcript.final → final).

provider and model default to "auto". credential_source="auto" chooses managed when SPEKO_API_KEY or SPEKO_API_KEY_FILE is configured and BYOK otherwise. Set it explicitly to mix managed and BYOK voice legs in the same process.

Conversation profiler

Attach the optional probe to collect content-free turn timing in the dashboard profiler:

from speko_gateway.probe import ConversationProbe

probe = ConversationProbe(session)
probe.start()
await session.start(...)
# ...
await probe.aclose()

TTS

from speko_gateway.livekit import TTS

tts = TTS(
    voice="",
    language="en",
    provider="auto",
    model="auto",
    sample_rate=24_000,
    max_input_characters=100_000,
    credential_source="auto",
)

A livekit.agents.tts.TTS subclass, synthesizing over the same socket. Note the default sample_rate is 24_000 here, where the STT class defaults to 16_000.

LLM

from speko_gateway.livekit import LLM

llm = LLM(
    provider="auto",
    model="auto",
    objective="balanced",
    max_output_tokens=8192,
)

A livekit.agents.llm.LLM subclass. Unlike STT and TTS it does not use the local socket — language models are not part of the gateway build, so this calls the hosted Router directly. A failure here is a Router problem, not a sidecar one.

It reports timing markers for speech, transcription, LLM, tools, TTS, playback, and interruptions through the gateway's local POST /v1/turn-events endpoint. It never sends transcripts, prompts, tool names or arguments, synthesized text, or audio. SPEKO_TELEMETRY_DISABLED=true suppresses it entirely.

GatewayClient

For anything beyond the plugin, the low-level async client:

import asyncio
from speko_gateway.client import GatewayClient, SessionConfig

async def main():
    client = GatewayClient.from_env()   # reads SPEKO_SOCKET_PATH + SPEKO_LOCAL_AUTH_TOKEN
    await client.ready()

    session = await client.open(SessionConfig(
        kind="stt",
        provider="deepgram",
        language="en",
        sample_rate_hz=16_000,
    ))

    await session.send_audio(pcm_bytes)
    await session.commit_audio()

    async for event in session.events():
        if event.type == "transcript.final":
            print(event.data["text"])
        if event.type in ("session.closed", "error"):
            break

    await session.aclose()

asyncio.run(main())

Session methods: send_audio, commit_audio, append_text, commit_text, cancel, finish, aclose, and the events() iterator. open() generates a UUID idempotency key unless you pass idempotency_key= yourself.

Secrets follow the same rules as the gateway: SPEKO_LOCAL_AUTH_TOKEN_FILE works anywhere SPEKO_LOCAL_AUTH_TOKEN does.