verbum-sdk 1.0.0

Python SDK for Verbum AI speech services (sync and async)

verbum-sdk (Python)

Python SDK for Verbum AI speech services — real-time speech-to-text and speech-to-speech streaming, translation, text analysis, text-to-speech, and batch transcription. Sync and async clients ship from a single package.

Install

pip install verbum-sdk

Quickstart — sync

from verbum import VerbumClient, VerbumClientOptions, SttConnectOptions, create_api_token

client = VerbumClient(VerbumClientOptions(
    api_token=create_api_token("sk-..."),
    base_url="wss://sdk.verbum.ai",
))

# Context manager — session.stop() is called automatically on exit
with client.stt.connect(SttConnectOptions(language=["en-US"], encoding="PCM")) as session:
    session.on_recognized(lambda result: print(result.text))
    session.stream(pcm_bytes)   # call repeatedly with PCM audio chunks
# session is stopped here

Or without the context manager:

session = client.stt.connect(SttConnectOptions(language=["en-US"], encoding="PCM"))
session.on_recognized(lambda result: print(result.text))
session.stream(pcm_bytes)
session.stop()

Quickstart — async

import asyncio
from verbum import AsyncVerbumClient, VerbumClientOptions, SttConnectOptions, create_api_token

async def main() -> None:
    client = AsyncVerbumClient(VerbumClientOptions(
        api_token=create_api_token("sk-..."),
        base_url="wss://sdk.verbum.ai",
    ))

    # Awaitable + async context manager — both patterns work
    async with client.stt.connect(SttConnectOptions(language=["en-US"], encoding="PCM")) as session:
        session.on_recognized(lambda result: print(result.text))
        await session.stream(pcm_bytes)

asyncio.run(main())

From a non-async context (e.g. an ML pipeline):

session = client.stt.connect_sync(SttConnectOptions(language=["en-US"], encoding="PCM"))
session.stream_sync(pcm_bytes)   # thread-safe, no event loop required
session.stop_sync()

Quickstart — REST resources

from verbum.rest.types import TranslateRequest, SingleText

# Translation
result = client.rest.translator.translate(
    TranslateRequest(texts=[SingleText("Hello, world!")], to=["es", "fr"])
)
print(result.translations)

# Batch transcription (shortcut via client.batch)
from verbum.rest.types import BatchTranscribeRequest
job = client.batch.create_batch_job(BatchTranscribeRequest(urls=["https://..."], language="en-US"))
status = client.batch.get_batch_job_status(job.transcription_id)
result = client.batch.get_batch_job_result(job.transcription_id)

# Usage / consumption (shortcut via client.usage)
from verbum.rest.types import ConsumptionQuery
records = client.usage.get_consumption(ConsumptionQuery(start_date="2026-01-01", end_date="2026-12-31"))

Jupyter notebook

A live microphone transcription demo is available at notebooks/realtime_transcription.ipynb.

pip install "verbum-sdk[notebooks]"
jupyter lab notebooks/realtime_transcription.ipynb

API docs

Full API reference generated by Sphinx:

pip install "verbum-sdk[docs]"
cd docs && make html
# open docs/_build/html/index.html

Project layout

src/verbum/
  client.py       VerbumClient / AsyncVerbumClient
  auth/           API token auth provider
  stt/            SttModule / SttSession (+ Async variants) — full implementation
  ws/             Socket.IO transport (VerbumWebSocket / AsyncVerbumWebSocket)
  rest/           REST resource clients — translator, text-analysis, speech/TTS,
                  scribe, usage; circuit-breaker + retry on the base client

This mirrors the reference TypeScript SDK (src/*.ts) module-for-module so the two implementations stay easy to diff against each other during development.

Protocol & conformance

This SDK speaks the wire protocol documented in specs/PROTOCOL.md (Engine.IO v4 over WebSocket, Socket.IO /listen and /repeat namespaces) and passes the shared conformance suite (TC-001–TC-006) as a mandatory CI gate.

specs/ is a git submodule of verbum-sdk-specs; after cloning, run:

git submodule update --init --recursive

Development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

ruff check .                        # lint
ruff format --check .               # format check
mypy                                # type check
pytest                              # unit tests (≥90 % coverage enforced)
pytest tests/integration/ -v        # integration tests (requires VERBUM_SDK_TEST_API_KEY)

Run the conformance suite locally (requires Node ≥ 22 + pnpm ≥ 11):

cd specs/conformance/runner && pnpm install && pnpm build && cd ../../..
VERBUM_SDK_API_KEY=<key> node specs/conformance/runner/dist/index.js run \
  --adapter "python tests/conformance/adapter.py" \
  --suite specs/conformance/suite \
  --specs-root specs

Project status

Area	Status
Packaging / tooling	Done
verbum.auth	Done
verbum.stt session state machine	Done
verbum.ws Socket.IO transport	Done
verbum.rest.* (translator, text-analysis, speech, scribe, usage)	Done
verbum.rest.* (users, projects, invitations, metrics — manager-api)	Not planned
Unit tests (≥90 % coverage)	Done
Integration tests	Done
Conformance suite (TC-001–TC-006)	Done
Sphinx API docs	Done
Jupyter quickstart notebook	Done
PyPI publish (CI/CD)	Done