Metadata-Version: 2.4
Name: verbum-sdk
Version: 1.0.3
Summary: Python SDK for Verbum AI speech services (sync and async)
Project-URL: Homepage, https://github.com/getstandup/verbum-python-sdk
Project-URL: Repository, https://github.com/getstandup/verbum-python-sdk
Project-URL: Issues, https://github.com/getstandup/verbum-python-sdk/issues
Author: Verbum
License-Expression: MIT
License-File: LICENSE
Keywords: s2s,sdk,speech-to-speech,speech-to-text,stt,translation,verbum
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: aiohttp<4,>=3.9
Requires-Dist: httpx<1,>=0.27
Requires-Dist: python-socketio[asyncio-client,client]<6,>=5.11
Requires-Dist: requests<3,>=2.31
Requires-Dist: websocket-client<2,>=1.8
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: types-requests>=2.31; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo>=2024; extra == 'docs'
Requires-Dist: myst-parser>=3; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints>=2; extra == 'docs'
Requires-Dist: sphinx>=7; extra == 'docs'
Provides-Extra: notebooks
Requires-Dist: ipykernel>=6; extra == 'notebooks'
Requires-Dist: jupyter>=1.1; extra == 'notebooks'
Requires-Dist: numpy>=1.26; extra == 'notebooks'
Requires-Dist: sounddevice>=0.4; extra == 'notebooks'
Description-Content-Type: text/markdown

# verbum-sdk (Python)

[![CI](https://github.com/getstandup/verbum-python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/getstandup/verbum-python-sdk/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/verbum-sdk)](https://pypi.org/project/verbum-sdk/)
[![Python](https://img.shields.io/pypi/pyversions/verbum-sdk)](https://pypi.org/project/verbum-sdk/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Python SDK for [Verbum](https://verbum.ai) 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

```bash
pip install verbum-sdk
```

## Quickstart — sync

```python
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:

```python
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

```python
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):

```python
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

```python
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`](./notebooks/realtime_transcription.ipynb).

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

## API docs

Full API reference generated by Sphinx:

```bash
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](https://github.com/getstandup/verbum-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`](./specs/PROTOCOL.md) (Engine.IO v4 over WebSocket,
Socket.IO `/listen` and `/repeat` namespaces) and passes the shared
[conformance suite](./specs/conformance/README.md) (TC-001–TC-006) as a
mandatory CI gate.

`specs/` is a git submodule of
[`verbum-sdk-specs`](https://github.com/getstandup/verbum-sdk-specs); after
cloning, run:

```bash
git submodule update --init --recursive
```

## Development

```bash
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):

```bash
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 |

