verbum-sdk 1.0.0__py3-none-any.whl

verbum/__init__.py

@@ -0,0 +1,54 @@
+"""Verbum SDK — Python client for Verbum AI speech services (sync and async)."""
+
+from verbum._types import VerbumClientOptions
+from verbum._version import SDK_VERSION
+from verbum.auth import ApiToken, ApiTokenAuth, AuthConfig, AuthProvider, create_api_token
+from verbum.client import AsyncRestSurface, AsyncVerbumClient, RestSurface, VerbumClient
+from verbum.rest import CircuitOpenError, UnauthorizedError
+from verbum.stt import AsyncSttModule, AsyncSttSession, SttModule, SttSession
+from verbum.stt.types import SttConnectOptions, SttSessionState, SttStateChangeEvent
+from verbum.ws.types import (
+    PiiEntity,
+    SpeechNormalization,
+    SpeechResult,
+    SpeechTranslation,
+    SpeechWord,
+    WsOptions,
+)
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    "__version__",
+    "SDK_VERSION",
+    # Client
+    "VerbumClient",
+    "AsyncVerbumClient",
+    "VerbumClientOptions",
+    "RestSurface",
+    "AsyncRestSurface",
+    # Auth
+    "ApiToken",
+    "ApiTokenAuth",
+    "AuthConfig",
+    "AuthProvider",
+    "create_api_token",
+    # REST errors
+    "UnauthorizedError",
+    "CircuitOpenError",
+    # STT
+    "SttModule",
+    "AsyncSttModule",
+    "SttSession",
+    "AsyncSttSession",
+    "SttConnectOptions",
+    "SttSessionState",
+    "SttStateChangeEvent",
+    # WebSocket / speech result types
+    "WsOptions",
+    "PiiEntity",
+    "SpeechWord",
+    "SpeechTranslation",
+    "SpeechNormalization",
+    "SpeechResult",
+]

verbum/_types.py

@@ -0,0 +1,29 @@
+"""Top-level client configuration types.
+
+Mirrors ``src/types/index.ts`` in the reference TypeScript SDK.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+from verbum.auth import ApiToken
+
+
+@dataclass(frozen=True)
+class VerbumClientOptions:
+    """Configuration options for :class:`VerbumClient` / :class:`AsyncVerbumClient`."""
+
+    api_token: ApiToken
+    """Use :func:`verbum.create_api_token` to construct one from a plain string."""
+
+    base_url: str
+    """Base URL for the Verbum service, e.g. ``"wss://sdk.verbum.ai"``."""
+
+    on_unauthorized: Callable[[object], None] | None = None
+    """Called when a REST request returns HTTP 401.
+
+    Notification hook only — ``UnauthorizedError`` is still raised after this
+    callback fires. If omitted, no callback runs before the error is raised.
+    """

verbum/_version.py

@@ -0,0 +1 @@
+SDK_VERSION = "1.0.0"

verbum/auth/__init__.py

@@ -0,0 +1,15 @@
+from verbum.auth.types import (
+    ApiToken,
+    ApiTokenAuth,
+    AuthConfig,
+    AuthProvider,
+    create_api_token,
+)
+
+__all__ = [
+    "ApiToken",
+    "ApiTokenAuth",
+    "AuthConfig",
+    "AuthProvider",
+    "create_api_token",
+]

verbum/auth/types.py

@@ -0,0 +1,59 @@
+"""Auth primitives shared by the sync and async clients.
+
+Mirrors ``src/auth/*.ts`` in the reference TypeScript SDK.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import NewType, Protocol
+
+ApiToken = NewType("ApiToken", str)
+"""Distinct token type. Use :func:`create_api_token` to construct one."""
+
+
+def create_api_token(token: str) -> ApiToken:
+    """Casts a plain string to an :class:`ApiToken`.
+
+    Call this once at application entry-point when constructing a client.
+    """
+    return ApiToken(token)
+
+
+@dataclass(frozen=True)
+class AuthConfig:
+    """Configuration for an authentication provider."""
+
+    api_token: ApiToken
+
+
+class AuthProvider(Protocol):
+    """Contract that all auth providers must fulfill."""
+
+    def get_token(self) -> ApiToken:
+        """Returns the resolved API token."""
+        ...
+
+    def rest_headers(self) -> dict[str, str]:
+        """Headers to merge into every REST request."""
+        ...
+
+    def socketio_auth(self) -> dict[str, object]:
+        """The ``auth`` payload to pass when opening a Socket.IO connection."""
+        ...
+
+
+class ApiTokenAuth:
+    """API-token-based auth provider (default)."""
+
+    def __init__(self, config: AuthConfig) -> None:
+        self._token = config.api_token
+
+    def get_token(self) -> ApiToken:
+        return self._token
+
+    def rest_headers(self) -> dict[str, str]:
+        return {"x-api-key": self._token}
+
+    def socketio_auth(self) -> dict[str, object]:
+        return {"token": self._token}

verbum/client.py

@@ -0,0 +1,122 @@
+"""Main Verbum SDK clients — sync and async.
+
+Mirrors ``src/client.ts`` in the reference TypeScript SDK.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from verbum._types import VerbumClientOptions
+from verbum.auth import ApiTokenAuth, AuthConfig
+from verbum.rest.invitations import AsyncInvitationsApi, InvitationsApi
+from verbum.rest.metrics import AsyncMetricsApi, MetricsApi
+from verbum.rest.projects import AsyncProjectsApi, ProjectsApi
+from verbum.rest.scribe import AsyncScribeApi, ScribeApi
+from verbum.rest.speech import AsyncSpeechApi, SpeechApi
+from verbum.rest.text_analysis import AsyncTextAnalysisApi, TextAnalysisApi
+from verbum.rest.translator import AsyncTranslatorApi, TranslatorApi
+from verbum.rest.usage import AsyncUsageApi, UsageApi
+from verbum.rest.users import AsyncUsersApi, UsersApi
+from verbum.stt import AsyncSttModule, SttModule
+
+__all__ = ["VerbumClient", "AsyncVerbumClient", "RestSurface", "AsyncRestSurface"]
+
+
+def _rest_base_url(ws_base_url: str) -> str:
+    """Derives the REST base URL from the WebSocket base URL."""
+    return re.sub(r"^wss?://", "https://", ws_base_url)
+
+
+@dataclass(frozen=True)
+class RestSurface:
+    """REST API surface exposed at ``client.rest.*``."""
+
+    users: UsersApi
+    projects: ProjectsApi
+    invitations: InvitationsApi
+    usage: UsageApi
+    metrics: MetricsApi
+    translator: TranslatorApi
+    text_analysis: TextAnalysisApi
+    speech: SpeechApi
+    scribe: ScribeApi
+
+
+@dataclass(frozen=True)
+class AsyncRestSurface:
+    """REST API surface exposed at ``client.rest.*`` (async)."""
+
+    users: AsyncUsersApi
+    projects: AsyncProjectsApi
+    invitations: AsyncInvitationsApi
+    usage: AsyncUsageApi
+    metrics: AsyncMetricsApi
+    translator: AsyncTranslatorApi
+    text_analysis: AsyncTextAnalysisApi
+    speech: AsyncSpeechApi
+    scribe: AsyncScribeApi
+
+
+class VerbumClient:
+    """Sync Verbum SDK client.
+
+    Example::
+
+        client = VerbumClient(VerbumClientOptions(
+            api_token=create_api_token("sk-..."),
+            base_url="wss://sdk.verbum.ai",
+        ))
+        with client.stt.connect(SttConnectOptions(language=["en-US"], encoding="PCM")) as session:
+            session.on_recognized(lambda r: print(r.text))
+            session.stream(pcm_bytes)
+    """
+
+    def __init__(self, options: VerbumClientOptions) -> None:
+        self._auth = ApiTokenAuth(AuthConfig(api_token=options.api_token))
+        self.stt = SttModule(options.base_url, self._auth)
+
+        rest_base = _rest_base_url(options.base_url)
+        on401 = options.on_unauthorized
+        self.rest = RestSurface(
+            users=UsersApi(rest_base, self._auth, on401),
+            projects=ProjectsApi(rest_base, self._auth, on401),
+            invitations=InvitationsApi(rest_base, self._auth, on401),
+            usage=UsageApi(rest_base, self._auth, on401),
+            metrics=MetricsApi(rest_base, self._auth, on401),
+            translator=TranslatorApi(rest_base, self._auth, on401),
+            text_analysis=TextAnalysisApi(rest_base, self._auth, on401),
+            speech=SpeechApi(rest_base, self._auth, on401),
+            scribe=ScribeApi(rest_base, self._auth, on401),
+        )
+
+        # Feature-layer shortcuts
+        self.batch: ScribeApi = self.rest.scribe
+        self.usage: UsageApi = self.rest.usage
+
+
+class AsyncVerbumClient:
+    """Async Verbum SDK client. See :class:`VerbumClient` for usage."""
+
+    def __init__(self, options: VerbumClientOptions) -> None:
+        self._auth = ApiTokenAuth(AuthConfig(api_token=options.api_token))
+        self.stt = AsyncSttModule(options.base_url, self._auth)
+
+        rest_base = _rest_base_url(options.base_url)
+        on401 = options.on_unauthorized
+        self.rest = AsyncRestSurface(
+            users=AsyncUsersApi(rest_base, self._auth, on401),
+            projects=AsyncProjectsApi(rest_base, self._auth, on401),
+            invitations=AsyncInvitationsApi(rest_base, self._auth, on401),
+            usage=AsyncUsageApi(rest_base, self._auth, on401),
+            metrics=AsyncMetricsApi(rest_base, self._auth, on401),
+            translator=AsyncTranslatorApi(rest_base, self._auth, on401),
+            text_analysis=AsyncTextAnalysisApi(rest_base, self._auth, on401),
+            speech=AsyncSpeechApi(rest_base, self._auth, on401),
+            scribe=AsyncScribeApi(rest_base, self._auth, on401),
+        )
+
+        # Feature-layer shortcuts
+        self.batch: AsyncScribeApi = self.rest.scribe
+        self.usage: AsyncUsageApi = self.rest.usage

verbum/rest/__init__.py

@@ -0,0 +1,272 @@
+"""Base REST client shared by every ``verbum.rest.*`` resource module.
+
+Mirrors ``src/rest/index.ts`` in the reference TypeScript SDK:
+
+- Applies API-token auth and an ``X-Verbum-SDK: python/{version}`` header
+  on every request.
+- Retries on 5xx up to 3 times with exponential backoff; no retry on 4xx.
+- Circuit breaker: opens after consecutive 5xx/network failures and
+  fast-fails until a reset timeout elapses.
+- Raises :class:`UnauthorizedError` on HTTP 401.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, Callable
+
+import httpx
+import requests
+
+from verbum._version import SDK_VERSION
+from verbum.auth import AuthProvider
+
+__all__ = ["SDK_VERSION", "UnauthorizedError", "CircuitOpenError", "RestClient", "AsyncRestClient"]
+
+_MAX_RETRIES = 3
+_BASE_BACKOFF_SECONDS = 1.0
+_FAILURE_THRESHOLD = 3
+_RESET_TIMEOUT_SECONDS = 30.0
+
+
+class UnauthorizedError(Exception):
+    """Raised when a REST request returns HTTP 401 (Unauthorized).
+
+    The underlying response is attached for callers that need to inspect it.
+    """
+
+    def __init__(self, response: object) -> None:
+        super().__init__("Unauthorized: API token is invalid or has been revoked (HTTP 401)")
+        self.response = response
+
+
+class CircuitOpenError(Exception):
+    """Raised when a request is rejected because the circuit breaker is open.
+
+    The circuit will allow a probe request after ``reset_at`` (seconds
+    since the epoch, as returned by ``time.time()``).
+    """
+
+    def __init__(self, reset_at: float) -> None:
+        super().__init__(f"Circuit is open — next probe allowed after {reset_at}")
+        self.reset_at = reset_at
+
+
+class _CircuitBreaker:
+    """Opens after ``failure_threshold`` consecutive failures; fast-fails
+    requests until ``reset_timeout_seconds`` has elapsed, then allows a
+    single probe request through.
+    """
+
+    def __init__(
+        self,
+        failure_threshold: int = _FAILURE_THRESHOLD,
+        reset_timeout_seconds: float = _RESET_TIMEOUT_SECONDS,
+    ) -> None:
+        self._failure_threshold = failure_threshold
+        self._reset_timeout_seconds = reset_timeout_seconds
+        self._state: str = "closed"  # "closed" | "open" | "half-open"
+        self._failures = 0
+        self._opened_at = 0.0
+        self._probe_in_flight = False
+
+    @property
+    def next_probe_at(self) -> float:
+        return self._opened_at + self._reset_timeout_seconds
+
+    def can_request(self) -> bool:
+        if self._state == "closed":
+            return True
+        if self._state == "half-open":
+            # Allow only one probe at a time to avoid thundering-herd on recovery.
+            if self._probe_in_flight:
+                return False
+            self._probe_in_flight = True
+            return True
+        # OPEN — check whether the reset window has elapsed.
+        if time.time() - self._opened_at >= self._reset_timeout_seconds:
+            self._state = "half-open"
+            self._probe_in_flight = True
+            return True
+        return False
+
+    def record_success(self) -> None:
+        self._state = "closed"
+        self._failures = 0
+        self._probe_in_flight = False
+
+    def record_failure(self) -> None:
+        self._failures += 1
+        self._probe_in_flight = False
+        if self._state == "half-open":
+            # Failed probe → re-open with a fresh timer.
+            self._state = "open"
+            self._opened_at = time.time()
+        elif self._state == "closed" and self._failures >= self._failure_threshold:
+            # Threshold reached while closed → open for the first time.
+            self._state = "open"
+            self._opened_at = time.time()
+        # If already open, preserve the original opened_at so the window is not extended.
+
+
+def _sdk_headers(auth_provider: AuthProvider, extra: dict[str, str] | None) -> dict[str, str]:
+    headers = {"X-Verbum-SDK": f"python/{SDK_VERSION}"}
+    if extra:
+        headers.update(extra)
+    headers.update(auth_provider.rest_headers())
+    return headers
+
+
+class RestClient:
+    """Sync base REST client, built on ``requests.Session``."""
+
+    def __init__(
+        self,
+        base_url: str,
+        auth_provider: AuthProvider,
+        on_unauthorized: Callable[[requests.Response], None] | None = None,
+    ) -> None:
+        self._base_url = base_url
+        self._auth_provider = auth_provider
+        self._on_unauthorized = on_unauthorized
+        self._circuit = _CircuitBreaker()
+        self._session = requests.Session()
+
+    def close(self) -> None:
+        """Closes the underlying ``requests.Session``, releasing pooled connections."""
+        self._session.close()
+
+    def __enter__(self) -> RestClient:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> requests.Response:
+        """Makes an authenticated request with retry and circuit-breaker logic.
+
+        - Raises :class:`CircuitOpenError` immediately if the circuit is open.
+        - Retries on 5xx up to ``_MAX_RETRIES`` times with exponential backoff.
+        - Returns the last 5xx response once retries are exhausted.
+        - No retry on 4xx — returns the response immediately.
+        - Raises :class:`UnauthorizedError` on HTTP 401.
+        - Retries on network errors; re-raises after max retries.
+        """
+        if not self._circuit.can_request():
+            raise CircuitOpenError(self._circuit.next_probe_at)
+
+        url = f"{self._base_url}{path}"
+        request_headers = _sdk_headers(self._auth_provider, headers)
+
+        for attempt in range(_MAX_RETRIES + 1):
+            try:
+                response = self._session.request(
+                    method, url, json=json, params=params, headers=request_headers
+                )
+            except requests.RequestException:
+                self._circuit.record_failure()
+                if attempt < _MAX_RETRIES:
+                    time.sleep((2**attempt) * _BASE_BACKOFF_SECONDS)
+                    continue
+                raise
+
+            if response.status_code == 401:
+                # Auth failure is not a server fault — do not penalise the circuit.
+                self._circuit.record_success()
+                if self._on_unauthorized is not None:
+                    self._on_unauthorized(response)
+                raise UnauthorizedError(response)
+
+            if response.status_code >= 500:
+                self._circuit.record_failure()
+                if attempt < _MAX_RETRIES:
+                    time.sleep((2**attempt) * _BASE_BACKOFF_SECONDS)
+                    continue
+                return response
+
+            # 2xx / 3xx / 4xx (non-401): surface immediately, no retry.
+            self._circuit.record_success()
+            return response
+
+        raise AssertionError("unreachable")  # pragma: no cover
+
+
+class AsyncRestClient:
+    """Async base REST client, built on ``httpx.AsyncClient``."""
+
+    def __init__(
+        self,
+        base_url: str,
+        auth_provider: AuthProvider,
+        on_unauthorized: Callable[[httpx.Response], None] | None = None,
+    ) -> None:
+        self._base_url = base_url
+        self._auth_provider = auth_provider
+        self._on_unauthorized = on_unauthorized
+        self._circuit = _CircuitBreaker()
+        self._client = httpx.AsyncClient()
+
+    async def aclose(self) -> None:
+        """Closes the underlying ``httpx.AsyncClient``, releasing connections."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncRestClient:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        """Async counterpart of :meth:`RestClient._request`. See there for behavior."""
+        if not self._circuit.can_request():
+            raise CircuitOpenError(self._circuit.next_probe_at)
+
+        url = f"{self._base_url}{path}"
+        request_headers = _sdk_headers(self._auth_provider, headers)
+
+        for attempt in range(_MAX_RETRIES + 1):
+            try:
+                response = await self._client.request(
+                    method, url, json=json, params=params, headers=request_headers
+                )
+            except httpx.HTTPError:
+                self._circuit.record_failure()
+                if attempt < _MAX_RETRIES:
+                    await asyncio.sleep((2**attempt) * _BASE_BACKOFF_SECONDS)
+                    continue
+                raise
+
+            if response.status_code == 401:
+                self._circuit.record_success()
+                if self._on_unauthorized is not None:
+                    self._on_unauthorized(response)
+                raise UnauthorizedError(response)
+
+            if response.status_code >= 500:
+                self._circuit.record_failure()
+                if attempt < _MAX_RETRIES:
+                    await asyncio.sleep((2**attempt) * _BASE_BACKOFF_SECONDS)
+                    continue
+                return response
+
+            self._circuit.record_success()
+            return response
+
+        raise AssertionError("unreachable")  # pragma: no cover

verbum/rest/_serde.py

@@ -0,0 +1,14 @@
+"""Tiny (de)serialization helpers shared by the ``verbum.rest.*`` resource
+modules. Not part of the public API.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def compact(d: dict[str, Any]) -> dict[str, Any]:
+    """Drops ``None``-valued keys so optional fields are omitted from the
+    JSON request body rather than sent as ``null``.
+    """
+    return {k: v for k, v in d.items() if v is not None}

verbum/rest/invitations.py

@@ -0,0 +1,20 @@
+"""API client for the Invitations resource.
+
+Out of scope for VSDK-763: this belongs to the internal manager-api, which
+has no public endpoint spec in ``public-docs/``. Left unimplemented until
+that spec exists.
+"""
+
+from __future__ import annotations
+
+from verbum.rest import AsyncRestClient, RestClient
+
+__all__ = ["InvitationsApi", "AsyncInvitationsApi"]
+
+
+class InvitationsApi(RestClient):
+    pass
+
+
+class AsyncInvitationsApi(AsyncRestClient):
+    pass

verbum/rest/metrics.py

@@ -0,0 +1,20 @@
+"""API client for Metric Conversion Ratios.
+
+Out of scope for VSDK-763: this belongs to the internal manager-api, which
+has no public endpoint spec in ``public-docs/``. Left unimplemented until
+that spec exists.
+"""
+
+from __future__ import annotations
+
+from verbum.rest import AsyncRestClient, RestClient
+
+__all__ = ["MetricsApi", "AsyncMetricsApi"]
+
+
+class MetricsApi(RestClient):
+    pass
+
+
+class AsyncMetricsApi(AsyncRestClient):
+    pass

verbum/rest/projects.py

@@ -0,0 +1,20 @@
+"""API client for the Projects resource.
+
+Out of scope for VSDK-763: this belongs to the internal manager-api, which
+has no public endpoint spec in ``public-docs/``. Left unimplemented until
+that spec exists.
+"""
+
+from __future__ import annotations
+
+from verbum.rest import AsyncRestClient, RestClient
+
+__all__ = ["ProjectsApi", "AsyncProjectsApi"]
+
+
+class ProjectsApi(RestClient):
+    pass
+
+
+class AsyncProjectsApi(AsyncRestClient):
+    pass