verbum-sdk 1.0.0__tar.gz

verbum_sdk-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,218 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*.*.*']
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }}
+
+jobs:
+  # ── Lint ────────────────────────────────────────────────────────────────────
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: ruff check
+        run: ruff check .
+
+      - name: ruff format --check
+        run: ruff format --check .
+
+  # ── Type Check ──────────────────────────────────────────────────────────────
+  typecheck:
+    name: Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: mypy
+        run: mypy
+
+      - name: mypy (examples)
+        run: mypy examples/
+
+  # ── Unit Tests ──────────────────────────────────────────────────────────────
+  test-unit:
+    name: Unit Tests / Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: pytest (unit + coverage ≥90 %)
+        run: pytest --cov --cov-report=term-missing --cov-fail-under=90
+
+  # ── Integration Tests ───────────────────────────────────────────────────────
+  # Skipped automatically when VERBUM_SDK_TEST_API_KEY is not configured.
+  # Set the secret (organisation-level) and the VERBUM_SDK_TEST_BASE_URL
+  # variable to enable live testing.
+  test-integration:
+    name: Integration Tests
+    runs-on: ubuntu-latest
+    needs: [lint, typecheck]
+    env:
+      VERBUM_SDK_TEST_API_KEY: ${{ secrets.VERBUM_SDK_TEST_API_KEY }}
+      VERBUM_SDK_TEST_BASE_URL: ${{ vars.VERBUM_SDK_TEST_BASE_URL || 'wss://sdk.verbum.ai' }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: pytest (integration)
+        run: pytest tests/integration/ -v -p no:cacheprovider
+
+  # ── Conformance Suite (mandatory gate) ─────────────────────────────────────
+  conformance:
+    name: Conformance Suite
+    runs-on: ubuntu-latest
+    needs: [test-unit]
+    env:
+      VERBUM_SDK_API_KEY: ${{ secrets.VERBUM_SDK_TEST_API_KEY }}
+      VERBUM_SDK_BASE_URL: ${{ vars.VERBUM_SDK_TEST_BASE_URL || 'wss://sdk.verbum.ai' }}
+    steps:
+      # Do NOT use submodules: recursive — the specs submodule URL may be
+      # inaccessible (private / not yet published). A dedicated step below
+      # handles the init and sets an output flag so downstream steps can skip
+      # gracefully without failing the job.
+      - uses: actions/checkout@v4
+
+      - name: Initialize specs submodule
+        id: specs
+        run: |
+          if git submodule update --init --depth=1 specs 2>/dev/null; then
+            echo "available=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "::warning::specs submodule could not be fetched (repo may be private or not yet published) — conformance suite will be skipped."
+            echo "available=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - uses: actions/setup-node@v4
+        if: steps.specs.outputs.available == 'true'
+        with:
+          node-version: '22'
+
+      - name: Install pnpm
+        if: steps.specs.outputs.available == 'true'
+        uses: pnpm/action-setup@v4
+        with:
+          version: '11'
+
+      - uses: actions/setup-python@v5
+        if: steps.specs.outputs.available == 'true'
+        with:
+          python-version: '3.12'
+
+      - name: Install Python dependencies
+        if: steps.specs.outputs.available == 'true'
+        run: pip install -e ".[dev]"
+
+      - name: Build conformance runner
+        if: steps.specs.outputs.available == 'true'
+        run: |
+          cd specs/conformance/runner
+          pnpm install --frozen-lockfile
+          pnpm build
+
+      - name: Run conformance suite (TC-001–TC-006)
+        if: steps.specs.outputs.available == 'true'
+        run: |
+          if [[ -z "$VERBUM_SDK_API_KEY" ]]; then
+            echo "::warning::VERBUM_SDK_TEST_API_KEY is not set (forked PR or secret unavailable) — skipping conformance suite."
+            exit 0
+          fi
+          node specs/conformance/runner/dist/index.js run \
+            --adapter "python tests/conformance/adapter.py" \
+            --suite specs/conformance/suite \
+            --specs-root specs \
+            --base-url "$VERBUM_SDK_BASE_URL"
+
+  # ── Build ───────────────────────────────────────────────────────────────────
+  build:
+    name: Build
+    needs: [lint, typecheck, test-unit]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build backend
+        run: pip install build
+
+      - name: Build sdist + wheel
+        run: python -m build
+
+      - name: Upload dist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist-${{ github.sha }}
+          path: dist/
+          retention-days: 7
+
+  # ── Publish to PyPI (Trusted Publisher / OIDC) ─────────────────────────────
+  # Triggered only on v*.*.* tags. Requires a PyPI Trusted Publisher entry:
+  #   Publisher:   GitHub Actions
+  #   Owner:       getstandup
+  #   Repository:  verbum-python-sdk
+  #   Workflow:    ci.yml
+  #   Environment: pypi
+  publish:
+    name: Publish to PyPI
+    needs: [conformance, build]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/verbum-sdk
+    permissions:
+      id-token: write   # required for OIDC Trusted Publisher
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist-${{ github.sha }}
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true

verbum_sdk-1.0.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+.env.local
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+*.log
+.DS_Store

verbum_sdk-1.0.0/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "specs"]
+	path = specs
+	url = https://github.com/getstandup/verbum-sdk-specs

verbum_sdk-1.0.0/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-07-09
+
+### Added
+
+- **Testing**: complete unit test suite (`test_package`, `test_rest_client`,
+  `test_rest_resources`, `test_stt_session`, `test_session_features`,
+  `test_ws_transport`) with ≥90 % branch-coverage gate enforced via
+  `coverage.report.fail_under = 90`.
+- **Integration tests** (`tests/integration/`): auth, REST resources, and live
+  STT smoke tests — auto-skipped when `VERBUM_SDK_TEST_API_KEY` is absent.
+- **Conformance suite** wired as a mandatory CI gate (TC-001–TC-006 via the
+  Python adapter at `tests/conformance/adapter.py` and the shared runner in
+  `specs/conformance/runner/`).
+- **Jupyter notebook** `notebooks/realtime_transcription.ipynb` — end-to-end
+  real-time transcription demo with `sounddevice` + `verbum-sdk`.
+- **Sphinx API documentation** (`docs/`) using `furo` theme, `autodoc`, and
+  `sphinx-autodoc-typehints`; `pyproject.toml` `docs` extra added.
+- **CI/CD pipeline** (`ci.yml`): ruff lint, mypy type check, pytest unit
+  (matrix 3.9–3.13), pytest integration, conformance suite gate,
+  `python -m build`, publish to PyPI on `v*.*.*` tags via Trusted Publisher
+  (OIDC — no stored secrets).
+- `pyproject.toml`: `docs` and `notebooks` optional-dependency groups;
+  `coverage.run.branch = true`; `coverage.report.fail_under = 90`.
+- `verbum.stt.session`: `SttSession` / `AsyncSttSession` gain context-manager
+  support (`__enter__`/`__exit__`, `__aenter__`/`__aexit__`) and an
+  `on_recognized` typed convenience callback.
+- `verbum.stt`: `_AsyncSttConnectHandle` — dual awaitable + async-context-manager
+  interface; `AsyncSttModule.connect_sync` for non-async scripts.
+- `verbum.client`: `batch` and `usage` feature-layer shortcuts on both
+  `VerbumClient` and `AsyncVerbumClient`.
+- `verbum.ws`: full Socket.IO transport (`VerbumWebSocket` / `AsyncVerbumWebSocket`)
+  with custom exponential-backoff reconnection (max_retries, initial_backoff_ms,
+  max_backoff_ms).
+- `verbum.rest.*`: complete implementations for translator, text-analysis,
+  speech/TTS, scribe, usage; circuit-breaker + retry on base client.
+
+### Changed
+
+- Package version `0.1.0` → `1.0.0` (first stable release).
+- Development Status classifier: `Alpha` → `Production/Stable`.
+- `README.md`: complete sync quickstart, async quickstart, REST quickstart,
+  Jupyter notebook link, Sphinx docs link, and updated project-status table.
+
+## [0.1.0] - 2026-06-01
+
+Initial bootstrap — not published to PyPI.
+
+### Added
+
+- Project scaffold: `pyproject.toml` (hatchling), `src/verbum` package layout,
+  lint/type/test tooling (ruff, mypy, pytest), initial CI workflow.
+- `verbum.auth`: `ApiToken`, `ApiTokenAuth`, `create_api_token`.
+- `verbum.stt`: `SttModule` / `AsyncSttModule`, `SttSession` / `AsyncSttSession`
+  state machine.
+- `verbum.client`: `VerbumClient` / `AsyncVerbumClient`.
+- `specs/` submodule (`verbum-sdk-specs`) with the shared WebSocket protocol
+  spec and conformance suite.
+- Conformance adapter skeleton at `tests/conformance/adapter.py`.
+
+[Unreleased]: https://github.com/getstandup/verbum-python-sdk/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/getstandup/verbum-python-sdk/compare/v0.1.0...v1.0.0
+[0.1.0]: https://github.com/getstandup/verbum-python-sdk/releases/tag/v0.1.0

verbum_sdk-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Verbum
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

verbum_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: verbum-sdk
+Version: 1.0.0
+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 |
+