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,
)

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()

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.