typeless-sdk 0.1.0__py3-none-any.whl

typeless/__init__.py

@@ -0,0 +1,58 @@
+"""official python sdk for the typeless transcript api"""
+
+import logging
+
+from typeless._version import __version__
+from typeless._ws import AsyncStreamConnection, StreamConnection
+from typeless.async_client import AsyncTypelessClient
+from typeless.client import TypelessClient
+from typeless.exceptions import (
+    APIConnectionError,
+    APITimeoutError,
+    AudioError,
+    AudioFormatError,
+    AudioTooLargeError,
+    AudioTooLongError,
+    AuthenticationError,
+    ConcurrentLimitError,
+    InsufficientBalanceError,
+    InvalidRequestError,
+    RateLimitError,
+    ServerError,
+    TypelessError,
+)
+from typeless.models import (
+    AudioReceived,
+    StreamMessage,
+    StreamResult,
+    TranscriptResult,
+    UsageInfo,
+)
+
+logging.getLogger("typeless").addHandler(logging.NullHandler())
+
+__all__ = [
+    "__version__",
+    "AsyncTypelessClient",
+    "AsyncStreamConnection",
+    "TypelessClient",
+    "StreamConnection",
+    "TranscriptResult",
+    "UsageInfo",
+    "AudioReceived",
+    "StreamResult",
+    "StreamMessage",
+    "TypelessError",
+    "AuthenticationError",
+    "InvalidRequestError",
+    "RateLimitError",
+    "ConcurrentLimitError",
+    "InsufficientBalanceError",
+    "AudioError",
+    "AudioTooLongError",
+    "AudioFormatError",
+    "AudioTooLargeError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "ServerError",
+]

typeless/_base_client.py

@@ -0,0 +1,380 @@
+import asyncio
+import logging
+import os
+import time
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, BinaryIO
+from urllib.parse import urlencode, urlsplit
+
+from typeless._constants import (
+    DEFAULT_AUDIO_FILENAME,
+    DEFAULT_BASE_URL,
+    ENV_API_KEY,
+    ENV_BASE_URL,
+    STREAM_PATH,
+    TRANSCRIBE_PATH,
+)
+from typeless._retry import backoff_delay, is_retryable
+from typeless._transport import (
+    AsyncTransport,
+    MultipartFile,
+    Request,
+    Response,
+    Transport,
+    TransportConnectionError,
+    TransportTimeoutError,
+    create_default_async_transport,
+    create_default_transport,
+)
+from typeless._utils import build_user_agent
+from typeless.exceptions import (
+    APIConnectionError,
+    APITimeoutError,
+    AuthenticationError,
+    ServerError,
+    exception_from_response,
+)
+from typeless.models import TranscriptResult, parse_transcript_result
+
+logger = logging.getLogger("typeless")
+
+AudioInput = str | Path | bytes | BinaryIO
+
+
+def _normalize_base_url(base_url: str) -> str:
+    """ensure base_url has an http or https scheme for http and websocket endpoints"""
+    base_url = base_url.rstrip("/")
+    scheme = urlsplit(base_url).scheme
+    if not scheme:
+        return f"https://{base_url}"
+    if scheme in ("http", "https"):
+        return base_url
+    raise ValueError("base_url must use http:// or https://")
+
+
+def _filename_from_stream(stream: BinaryIO) -> str | None:
+    """derive a base filename from a binary stream name attribute when available"""
+    name = getattr(stream, "name", None)
+    if isinstance(name, str) and name:
+        return Path(name).name
+    return None
+
+
+def _build_audio_part(audio: AudioInput) -> MultipartFile:
+    """normalize an audio input into a multipart file part with a non empty filename"""
+    if isinstance(audio, str):
+        audio = Path(audio)
+    if isinstance(audio, Path):
+        return MultipartFile(
+            field_name="audio",
+            source=audio,
+            filename=audio.name or DEFAULT_AUDIO_FILENAME,
+        )
+    if isinstance(audio, bytes | bytearray):
+        return MultipartFile(
+            field_name="audio",
+            source=bytes(audio),
+            filename=DEFAULT_AUDIO_FILENAME,
+        )
+    return MultipartFile(
+        field_name="audio",
+        source=audio,
+        filename=_filename_from_stream(audio) or DEFAULT_AUDIO_FILENAME,
+    )
+
+
+class BaseClient:
+    """shared configuration and pure request logic for the typeless clients"""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None,
+        base_url: str | None,
+        timeout: float,
+        max_retries: int,
+    ) -> None:
+        """resolve the api key base url timeout and retry budget"""
+        resolved_key = api_key or os.environ.get(ENV_API_KEY)
+        if not resolved_key:
+            raise AuthenticationError(
+                "the api key must be set either by passing api_key "
+                "or by setting the TYPELESS_API_KEY environment variable"
+            )
+        self._api_key = resolved_key
+        self._base_url = _normalize_base_url(base_url or os.environ.get(ENV_BASE_URL) or DEFAULT_BASE_URL)
+        self._timeout = timeout
+        self._max_retries = max_retries
+
+    def _transcribe_url(self) -> str:
+        """build the absolute url for the transcription endpoint"""
+        return f"{self._base_url}{TRANSCRIBE_PATH}"
+
+    def _build_stream_url(
+        self,
+        *,
+        model: str,
+        sample_rate: int,
+        encoding: str,
+        channels: int,
+        language: str | None,
+    ) -> str:
+        """build the websocket url with the connection query parameters"""
+        base = self._base_url
+        if base.startswith("https://"):
+            ws_base = "wss://" + base[len("https://") :]
+        elif base.startswith("http://"):
+            ws_base = "ws://" + base[len("http://") :]
+        else:
+            raise ValueError("base_url must use http:// or https://")
+        params = {
+            "token": self._api_key,
+            "model": model,
+            "sample_rate": str(sample_rate),
+            "encoding": encoding,
+            "channels": str(channels),
+        }
+        if language is not None:
+            params["language"] = language
+        return f"{ws_base}{STREAM_PATH}?{urlencode(params)}"
+
+    def _build_headers(self) -> dict[str, str]:
+        """build the authorization and user agent headers"""
+        return {
+            "Authorization": f"Token {self._api_key}",
+            "User-Agent": build_user_agent(),
+        }
+
+    def _build_transcribe_request(
+        self,
+        audio: AudioInput,
+        *,
+        model: str,
+        language: str | None,
+    ) -> Request:
+        """build the multipart request for a transcription call"""
+        data: dict[str, str] = {"model": model}
+        if language is not None:
+            data["language"] = language
+        return Request(
+            method="POST",
+            url=self._transcribe_url(),
+            headers=self._build_headers(),
+            data=data,
+            files=[_build_audio_part(audio)],
+            timeout=self._timeout,
+        )
+
+    def _parse_success(self, response: Response[Any]) -> TranscriptResult:
+        """parse a success response body into a transcript result"""
+        try:
+            body = response.json
+        except (ValueError, TypeError) as exc:
+            raise ServerError("the response body is not valid json") from exc
+        if not isinstance(body, dict):
+            raise ServerError("the response body is not a json object")
+        return parse_transcript_result(body)
+
+    def _retry_after_seconds(self, headers: Mapping[str, str]) -> int | None:
+        """read the retry after header as a number of seconds"""
+        value = None
+        for key, header_value in headers.items():
+            if key.lower() == "retry-after":
+                value = header_value
+                break
+        if value is None:
+            return None
+        try:
+            return int(value)
+        except (ValueError, TypeError):
+            return None
+
+    def _extract_error(
+        self,
+        response: Response[Any],
+    ) -> tuple[str | None, str | None, dict[str, object] | None, str | None, int | None]:
+        """extract the code message details request id and retry after from a non success response"""
+        try:
+            body = response.json
+        except (ValueError, TypeError):
+            body = {}
+        if not isinstance(body, dict):
+            body = {}
+        error = body.get("error")
+        error = error if isinstance(error, dict) else {}
+        code = error.get("code")
+        message = error.get("message")
+        details = error.get("details")
+        request_id = body.get("request_id")
+        return (
+            code if isinstance(code, str) else None,
+            message if isinstance(message, str) else None,
+            details if isinstance(details, dict) else None,
+            request_id if isinstance(request_id, str) else None,
+            self._retry_after_seconds(response.headers),
+        )
+
+    def _can_retry(
+        self,
+        *,
+        attempt: int,
+        request: Request,
+        code: str | None,
+        status_code: int,
+    ) -> bool:
+        """decide whether a failed response can be retried"""
+        if attempt >= self._max_retries or not request.is_replayable:
+            return False
+        return is_retryable(code=code, status_code=status_code)
+
+    def _can_retry_connection(self, *, attempt: int, request: Request) -> bool:
+        """decide whether a connection failure can be retried"""
+        return attempt < self._max_retries and request.is_replayable
+
+    def _log_send(self, request: Request) -> None:
+        """log the outgoing request method url and form fields"""
+        logger.debug("sending request %s %s fields %s", request.method, request.url, request.data)
+
+    def _connection_retry_delay(self, exc: TransportConnectionError, *, attempt: int, request: Request) -> float:
+        """return the backoff delay for a connection failure or raise when it cannot be retried"""
+        if not self._can_retry_connection(attempt=attempt, request=request):
+            raise APIConnectionError("the connection to the api failed") from exc
+        delay = backoff_delay(attempt)
+        logger.warning("retrying after connection error in %.2f seconds attempt %d", delay, attempt + 1)
+        return delay
+
+    def _response_retry_delay(self, response: Response[Any], *, attempt: int, request: Request) -> float | None:
+        """return none for a final response or a backoff delay or raise the mapped error"""
+        logger.debug("received response status %d", response.status_code)
+        if response.status_code < 400:
+            return None
+        code, message, details, request_id, retry_after = self._extract_error(response)
+        if self._can_retry(
+            attempt=attempt,
+            request=request,
+            code=code,
+            status_code=response.status_code,
+        ):
+            delay = backoff_delay(attempt, retry_after=retry_after)
+            logger.warning(
+                "retrying after status %d in %.2f seconds attempt %d",
+                response.status_code,
+                delay,
+                attempt + 1,
+            )
+            return delay
+        raise exception_from_response(
+            code=code,
+            message=message,
+            request_id=request_id,
+            details=details,
+            retry_after=retry_after,
+            status_code=response.status_code,
+        )
+
+
+class SyncAPIClient(BaseClient):
+    """synchronous client that owns a transport and runs the retry loop"""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None,
+        base_url: str | None,
+        timeout: float,
+        max_retries: int,
+        transport: Transport | None = None,
+    ) -> None:
+        """initialize the shared configuration and the synchronous transport"""
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._transport = transport if transport is not None else create_default_transport(timeout=self._timeout)
+
+    def _request(self, request: Request) -> Response[Any]:
+        """send a request and retry transient failures with exponential backoff"""
+        attempt = 0
+        while True:
+            self._log_send(request)
+            try:
+                response = self._transport.send(request)
+            except TransportTimeoutError as exc:
+                raise APITimeoutError("the request timed out") from exc
+            except TransportConnectionError as exc:
+                time.sleep(self._connection_retry_delay(exc, attempt=attempt, request=request))
+                attempt += 1
+                continue
+            delay = self._response_retry_delay(response, attempt=attempt, request=request)
+            if delay is None:
+                return response
+            time.sleep(delay)
+            attempt += 1
+
+    def close(self) -> None:
+        """close the client and release the underlying connection pool"""
+        self._transport.close()
+
+    def __enter__(self) -> "SyncAPIClient":
+        """enter the runtime context and return the client"""
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        """exit the runtime context and close the client"""
+        self.close()
+
+
+class AsyncAPIClient(BaseClient):
+    """asynchronous client that owns a transport and runs the retry loop"""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None,
+        base_url: str | None,
+        timeout: float,
+        max_retries: int,
+        transport: AsyncTransport | None = None,
+    ) -> None:
+        """initialize the shared configuration and the asynchronous transport"""
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._transport = transport if transport is not None else create_default_async_transport(timeout=self._timeout)
+
+    async def _request(self, request: Request) -> Response[Any]:
+        """send a request and retry transient failures with exponential backoff"""
+        attempt = 0
+        while True:
+            self._log_send(request)
+            try:
+                response = await self._transport.send(request)
+            except TransportTimeoutError as exc:
+                raise APITimeoutError("the request timed out") from exc
+            except TransportConnectionError as exc:
+                await asyncio.sleep(self._connection_retry_delay(exc, attempt=attempt, request=request))
+                attempt += 1
+                continue
+            delay = self._response_retry_delay(response, attempt=attempt, request=request)
+            if delay is None:
+                return response
+            await asyncio.sleep(delay)
+            attempt += 1
+
+    async def close(self) -> None:
+        """close the client and release the underlying connection pool"""
+        await self._transport.close()
+
+    async def __aenter__(self) -> "AsyncAPIClient":
+        """enter the runtime context and return the client"""
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        """exit the runtime context and close the client"""
+        await self.close()

typeless/_constants.py

@@ -0,0 +1,68 @@
+# default configuration values and api error code constants
+DEFAULT_BASE_URL = "https://api.typelessapi.com"
+TRANSCRIBE_PATH = "/v1/transcribe"
+STREAM_PATH = "/v1/transcribe/stream"
+
+ENV_API_KEY = "TYPELESS_API_KEY"
+ENV_BASE_URL = "TYPELESS_BASE_URL"
+
+DEFAULT_TIMEOUT_SECONDS = 300.0
+DEFAULT_MAX_RETRIES = 3
+
+MAX_CONNECTIONS = 100
+MAX_KEEPALIVE_CONNECTIONS = 20
+
+DEFAULT_SAMPLE_RATE = 16000
+DEFAULT_CHANNELS = 1
+DEFAULT_ENCODING = "pcm16"
+
+KEEP_ALIVE_INTERVAL_SECONDS = 20.0
+WS_RECEIVE_POLL_SECONDS = 0.5
+
+RETRY_BACKOFF_BASE_SECONDS = 1.0
+RETRY_BACKOFF_FACTOR = 2.0
+RETRY_MAX_DELAY_SECONDS = 60.0
+RETRY_JITTER_RATIO = 0.2
+
+RETRYABLE_STATUS_CODES = frozenset({408, 429, 500, 502, 503, 504})
+NON_RETRYABLE_STATUS_CODES = frozenset({400, 401, 402, 403, 413})
+
+DEFAULT_AUDIO_FILENAME = "audio"
+
+ERROR_INVALID_REQUEST = "INVALID_REQUEST"
+ERROR_INVALID_API_KEY = "INVALID_API_KEY"
+ERROR_MISSING_API_KEY = "MISSING_API_KEY"
+ERROR_ACCOUNT_SUSPENDED = "ACCOUNT_SUSPENDED"
+ERROR_RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED"
+ERROR_CONCURRENT_LIMIT_EXCEEDED = "CONCURRENT_LIMIT_EXCEEDED"
+ERROR_INSUFFICIENT_BALANCE = "INSUFFICIENT_BALANCE"
+ERROR_AUDIO_TOO_LONG = "AUDIO_TOO_LONG"
+ERROR_AUDIO_FORMAT_UNSUPPORTED = "AUDIO_FORMAT_UNSUPPORTED"
+ERROR_FILE_TOO_LARGE = "FILE_TOO_LARGE"
+ERROR_TRANSCRIPTION_FAILED = "TRANSCRIPTION_FAILED"
+ERROR_SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE"
+ERROR_INTERNAL_ERROR = "INTERNAL_ERROR"
+ERROR_QUOTA_EXCEEDED = "QUOTA_EXCEEDED"
+
+RETRYABLE_ERROR_CODES = frozenset(
+    {
+        ERROR_RATE_LIMIT_EXCEEDED,
+        ERROR_TRANSCRIPTION_FAILED,
+        ERROR_SERVICE_UNAVAILABLE,
+        ERROR_INTERNAL_ERROR,
+    }
+)
+NON_RETRYABLE_ERROR_CODES = frozenset(
+    {
+        ERROR_INVALID_REQUEST,
+        ERROR_INVALID_API_KEY,
+        ERROR_MISSING_API_KEY,
+        ERROR_ACCOUNT_SUSPENDED,
+        ERROR_CONCURRENT_LIMIT_EXCEEDED,
+        ERROR_INSUFFICIENT_BALANCE,
+        ERROR_AUDIO_TOO_LONG,
+        ERROR_AUDIO_FORMAT_UNSUPPORTED,
+        ERROR_FILE_TOO_LARGE,
+        ERROR_QUOTA_EXCEEDED,
+    }
+)

typeless/_retry.py

@@ -0,0 +1,41 @@
+import math
+import random
+
+from typeless._constants import (
+    NON_RETRYABLE_ERROR_CODES,
+    RETRY_BACKOFF_BASE_SECONDS,
+    RETRY_BACKOFF_FACTOR,
+    RETRY_JITTER_RATIO,
+    RETRY_MAX_DELAY_SECONDS,
+    RETRYABLE_ERROR_CODES,
+    RETRYABLE_STATUS_CODES,
+)
+
+
+def is_retryable(*, code: str | None, status_code: int | None) -> bool:
+    """return whether a failed request should be retried"""
+    if code is not None:
+        if code in NON_RETRYABLE_ERROR_CODES:
+            return False
+        if code in RETRYABLE_ERROR_CODES:
+            return True
+
+    if status_code is not None:
+        return status_code in RETRYABLE_STATUS_CODES
+
+    return False
+
+
+def backoff_delay(attempt: int, *, retry_after: float | None = None) -> float:
+    """compute the delay before the next retry attempt"""
+    if retry_after is not None:
+        delay = float(retry_after)
+        if math.isfinite(delay) and delay >= 0:
+            return min(delay, RETRY_MAX_DELAY_SECONDS)
+
+    base = min(
+        RETRY_BACKOFF_BASE_SECONDS * (RETRY_BACKOFF_FACTOR**attempt),
+        RETRY_MAX_DELAY_SECONDS,
+    )
+    jitter = base * RETRY_JITTER_RATIO * random.random()
+    return min(base + jitter, RETRY_MAX_DELAY_SECONDS)

typeless/_transport/__init__.py

@@ -0,0 +1,38 @@
+from typeless._constants import DEFAULT_TIMEOUT_SECONDS
+from typeless._transport.base import (
+    AsyncTransport,
+    MultipartFile,
+    Request,
+    Response,
+    Transport,
+    TransportConnectionError,
+    TransportError,
+    TransportTimeoutError,
+)
+from typeless._transport.httpx_backend import HttpxAsyncTransport, HttpxTransport
+
+
+def create_default_transport(*, timeout: float = DEFAULT_TIMEOUT_SECONDS) -> Transport:
+    """create the default synchronous transport"""
+    return HttpxTransport(timeout=timeout)
+
+
+def create_default_async_transport(*, timeout: float = DEFAULT_TIMEOUT_SECONDS) -> AsyncTransport:
+    """create the default asynchronous transport"""
+    return HttpxAsyncTransport(timeout=timeout)
+
+
+__all__ = [
+    "AsyncTransport",
+    "HttpxAsyncTransport",
+    "HttpxTransport",
+    "MultipartFile",
+    "Request",
+    "Response",
+    "Transport",
+    "TransportConnectionError",
+    "TransportError",
+    "TransportTimeoutError",
+    "create_default_async_transport",
+    "create_default_transport",
+]

typeless/_transport/base.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from functools import cached_property
+from pathlib import Path
+from typing import Any, BinaryIO, Generic, Protocol, TypeVar
+
+RawResponseT = TypeVar("RawResponseT")
+
+FileSource = bytes | Path | BinaryIO
+
+
+def _source_is_replayable(source: FileSource) -> bool:
+    """whether a multipart source can be sent again for a retry"""
+    if isinstance(source, bytes | Path):
+        return True
+    return source.seekable()
+
+
+@dataclass
+class MultipartFile:
+    """neutral description of a single multipart file part"""
+
+    field_name: str
+    source: FileSource
+    filename: str | None = None
+    content_type: str | None = None
+
+
+@dataclass
+class Request:
+    """library agnostic http request"""
+
+    method: str
+    url: str
+    headers: dict[str, str] = field(default_factory=dict)
+    params: dict[str, str] = field(default_factory=dict)
+    data: dict[str, str] = field(default_factory=dict)
+    files: list[MultipartFile] = field(default_factory=list)
+    content: bytes | None = None
+    timeout: float | None = None
+
+    @property
+    def is_replayable(self) -> bool:
+        """whether the request body can be resent for a retry"""
+        return all(_source_is_replayable(item.source) for item in self.files)
+
+
+@dataclass
+class Response(Generic[RawResponseT]):
+    """library agnostic http response"""
+
+    status_code: int
+    headers: Mapping[str, str]
+    content: bytes
+    raw_response: RawResponseT
+
+    @cached_property
+    def json(self) -> Any:
+        """decode the response body as json"""
+        return json.loads(self.content)
+
+
+class Transport(Protocol):
+    """synchronous transport interface"""
+
+    def send(self, request: Request) -> Response[Any]:
+        """send a request and return a response"""
+        ...
+
+    def close(self) -> None:
+        """release the underlying resources"""
+        ...
+
+
+class AsyncTransport(Protocol):
+    """asynchronous transport interface"""
+
+    async def send(self, request: Request) -> Response[Any]:
+        """send a request and return a response"""
+        ...
+
+    async def close(self) -> None:
+        """release the underlying resources"""
+        ...
+
+
+class TransportError(Exception):
+    """base class for transport level failures"""
+
+    pass
+
+
+class TransportConnectionError(TransportError):
+    """raised when the connection cannot be established"""
+
+    pass
+
+
+class TransportTimeoutError(TransportError):
+    """raised when the request exceeds the configured timeout"""
+
+    pass