speechrevolutions 0.2.0__tar.gz

speechrevolutions-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Speech Revolutions
+
+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.

speechrevolutions-0.2.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: speechrevolutions
+Version: 0.2.0
+Summary: Official Python SDK for the Speech Revolutions speech-to-text API
+Author: Speech Revolutions
+License: MIT
+Project-URL: Homepage, https://speechrevolutions.com
+Project-URL: Documentation, https://docs.speechrevolutions.com
+Project-URL: Repository, https://github.com/SpeechRevolutions/python-sdk
+Project-URL: Issues, https://github.com/SpeechRevolutions/python-sdk/issues
+Keywords: speech-to-text,stt,transcription,whisper,asr
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Requires-Dist: httpx>=0.27
+Provides-Extra: progress
+Requires-Dist: tqdm>=4.65; extra == "progress"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: tqdm>=4.65; extra == "dev"
+Dynamic: license-file
+
+# Speech Revolutions — Python SDK
+
+Official Python client for the [Speech Revolutions](https://speechrevolutions.com) speech-to-text API.
+
+## Install
+
+```bash
+pip install speechrevolutions
+```
+
+For console progress bars, install the optional `tqdm` extra:
+
+```bash
+pip install "speechrevolutions[progress]"
+```
+
+## Quick start
+
+```python
+from speechrevolutions import SpeechRevolutions
+
+client = SpeechRevolutions()  # reads SPEECHREVOLUTIONS_API_KEY or STT_API_KEY
+result = client.transcribe("meeting.mp3", speaker_labels=True)
+print(result.text)
+
+for u in result.utterances:
+    print(f"Speaker {u.speaker}: {u.text}")
+```
+
+### Async
+
+```python
+from speechrevolutions import AsyncSpeechRevolutions
+
+async with AsyncSpeechRevolutions() as client:
+    result = await client.transcribe("meeting.mp3", speaker_labels=True)
+    print(result.text)
+```
+
+### From a URL (Deepgram-style)
+
+```python
+result = client.transcribe_url("https://example.com/audio.mp3")
+# or
+result = client.transcribe("https://example.com/audio.mp3")
+```
+
+### Options as kwargs or config object
+
+```python
+# kwargs (ElevenLabs / Deepgram style). `diarize` is an alias for `speaker_labels`.
+result = client.transcribe("a.mp3", diarize=True, output_type="json")
+
+# config object (AssemblyAI style)
+from speechrevolutions import TranscribeOptions
+result = client.transcribe("a.mp3", options=TranscribeOptions(speaker_labels=True))
+```
+
+Defaults: `output_type="json"`, `word_timestamps`, `speaker_labels`, `nltk` all
+`True`, `tier="standard"`, `custom_vocabulary=None`.
+
+### Live progress
+
+Unlike AssemblyAI/Deepgram (which give no percentage for pre-recorded audio),
+you get real-time progress — for **both** the file upload and the
+transcription — as a console bar, a callback, or both.
+
+```python
+# 1. Console bars (uses tqdm if installed: pip install "speechrevolutions[progress]")
+#    Shows an "Uploading" byte bar, then a "Transcribing" bar.
+result = client.transcribe("meeting.mp3", progress=True)
+
+# 2. Programmatic — read event.percent (0–100) to drive your own UI / API
+def on_progress(event):        # transcription
+    print(event.percent, event.step)      # e.g. 42.0 "transcribe"
+
+def on_upload(event):          # upload (event.step == "upload")
+    print("upload", event.percent)
+
+result = client.transcribe(
+    "meeting.mp3",
+    on_progress=on_progress,
+    on_upload_progress=on_upload,
+)
+```
+
+`progress=True` and the callbacks compose — the bars render *and* your callbacks
+still fire for every event.
+
+## Result shape
+
+Default `output_type` is `json`. The SDK parses it into a transcript-first object:
+
+| Field | Like |
+|-------|------|
+| `result.text` | AssemblyAI / ElevenLabs |
+| `result.transcript` | Deepgram alias |
+| `result.words` | word + start/end/speaker |
+| `result.utterances` | AssemblyAI speaker turns |
+| `result.to_deepgram()` | Deepgram-shaped dict |
+| `result.to_dict()` | normalized JSON |
+| `result.content` / `result.save()` | raw bytes / file |
+
+```python
+dg = result.to_deepgram()
+print(dg["results"]["channels"][0]["alternatives"][0]["transcript"])
+```
+
+## Webhooks & retrieving results later
+
+`submit()` uploads and enqueues a job and returns its id **without waiting** —
+ideal for batch/background work. Collect the result later via a webhook
+(`callback_url`, a signed POST — verify `X-SR-Signature: sha256=…` against the
+raw bytes) or by polling:
+
+```python
+job_id = client.submit("meeting.mp3")       # returns immediately, no waiting
+# ...or notify a webhook instead of polling:
+client.transcribe("meeting.mp3", callback_url="https://you.example.com/hook")
+
+status = client.get_job_status(job_id)      # .status: processing|completed|failed
+if status.is_completed:
+    result = client.get_transcript(job_id)  # downloads + parses
+page = client.list_jobs(limit=50)           # {"jobs": [...], "next_before": ...}
+```
+
+See `examples/` for a full submit/poll/webhook walkthrough.
+
+## Robustness
+
+`SpeechRevolutions(max_retries=3, retry_backoff=0.5, proxies={"https": "..."})`.
+Transient 429/5xx/network errors are retried (honoring `Retry-After`). Errors are
+typed (`RateLimitError`, `AuthenticationError`, …) and carry `.status_code` and
+`.request_id` for correlating with support.
+
+## Auth
+
+```bash
+export SPEECHREVOLUTIONS_API_KEY=stt_...
+# or
+export STT_API_KEY=stt_...
+```
+
+Or `SpeechRevolutions(api_key="stt_...")`.
+
+## Other languages
+
+Speech Revolutions also publishes SDKs for
+[JavaScript/TypeScript](https://github.com/SpeechRevolutions/node-sdk),
+[Go](https://github.com/SpeechRevolutions/speechrevolutions-go), and
+[C#/.NET](https://github.com/SpeechRevolutions/csharp-sdk) — see
+[docs.speechrevolutions.com](https://docs.speechrevolutions.com) for a
+cross-language feature comparison.
+
+## License
+
+MIT

speechrevolutions-0.2.0/README.md

@@ -0,0 +1,157 @@
+# Speech Revolutions — Python SDK
+
+Official Python client for the [Speech Revolutions](https://speechrevolutions.com) speech-to-text API.
+
+## Install
+
+```bash
+pip install speechrevolutions
+```
+
+For console progress bars, install the optional `tqdm` extra:
+
+```bash
+pip install "speechrevolutions[progress]"
+```
+
+## Quick start
+
+```python
+from speechrevolutions import SpeechRevolutions
+
+client = SpeechRevolutions()  # reads SPEECHREVOLUTIONS_API_KEY or STT_API_KEY
+result = client.transcribe("meeting.mp3", speaker_labels=True)
+print(result.text)
+
+for u in result.utterances:
+    print(f"Speaker {u.speaker}: {u.text}")
+```
+
+### Async
+
+```python
+from speechrevolutions import AsyncSpeechRevolutions
+
+async with AsyncSpeechRevolutions() as client:
+    result = await client.transcribe("meeting.mp3", speaker_labels=True)
+    print(result.text)
+```
+
+### From a URL (Deepgram-style)
+
+```python
+result = client.transcribe_url("https://example.com/audio.mp3")
+# or
+result = client.transcribe("https://example.com/audio.mp3")
+```
+
+### Options as kwargs or config object
+
+```python
+# kwargs (ElevenLabs / Deepgram style). `diarize` is an alias for `speaker_labels`.
+result = client.transcribe("a.mp3", diarize=True, output_type="json")
+
+# config object (AssemblyAI style)
+from speechrevolutions import TranscribeOptions
+result = client.transcribe("a.mp3", options=TranscribeOptions(speaker_labels=True))
+```
+
+Defaults: `output_type="json"`, `word_timestamps`, `speaker_labels`, `nltk` all
+`True`, `tier="standard"`, `custom_vocabulary=None`.
+
+### Live progress
+
+Unlike AssemblyAI/Deepgram (which give no percentage for pre-recorded audio),
+you get real-time progress — for **both** the file upload and the
+transcription — as a console bar, a callback, or both.
+
+```python
+# 1. Console bars (uses tqdm if installed: pip install "speechrevolutions[progress]")
+#    Shows an "Uploading" byte bar, then a "Transcribing" bar.
+result = client.transcribe("meeting.mp3", progress=True)
+
+# 2. Programmatic — read event.percent (0–100) to drive your own UI / API
+def on_progress(event):        # transcription
+    print(event.percent, event.step)      # e.g. 42.0 "transcribe"
+
+def on_upload(event):          # upload (event.step == "upload")
+    print("upload", event.percent)
+
+result = client.transcribe(
+    "meeting.mp3",
+    on_progress=on_progress,
+    on_upload_progress=on_upload,
+)
+```
+
+`progress=True` and the callbacks compose — the bars render *and* your callbacks
+still fire for every event.
+
+## Result shape
+
+Default `output_type` is `json`. The SDK parses it into a transcript-first object:
+
+| Field | Like |
+|-------|------|
+| `result.text` | AssemblyAI / ElevenLabs |
+| `result.transcript` | Deepgram alias |
+| `result.words` | word + start/end/speaker |
+| `result.utterances` | AssemblyAI speaker turns |
+| `result.to_deepgram()` | Deepgram-shaped dict |
+| `result.to_dict()` | normalized JSON |
+| `result.content` / `result.save()` | raw bytes / file |
+
+```python
+dg = result.to_deepgram()
+print(dg["results"]["channels"][0]["alternatives"][0]["transcript"])
+```
+
+## Webhooks & retrieving results later
+
+`submit()` uploads and enqueues a job and returns its id **without waiting** —
+ideal for batch/background work. Collect the result later via a webhook
+(`callback_url`, a signed POST — verify `X-SR-Signature: sha256=…` against the
+raw bytes) or by polling:
+
+```python
+job_id = client.submit("meeting.mp3")       # returns immediately, no waiting
+# ...or notify a webhook instead of polling:
+client.transcribe("meeting.mp3", callback_url="https://you.example.com/hook")
+
+status = client.get_job_status(job_id)      # .status: processing|completed|failed
+if status.is_completed:
+    result = client.get_transcript(job_id)  # downloads + parses
+page = client.list_jobs(limit=50)           # {"jobs": [...], "next_before": ...}
+```
+
+See `examples/` for a full submit/poll/webhook walkthrough.
+
+## Robustness
+
+`SpeechRevolutions(max_retries=3, retry_backoff=0.5, proxies={"https": "..."})`.
+Transient 429/5xx/network errors are retried (honoring `Retry-After`). Errors are
+typed (`RateLimitError`, `AuthenticationError`, …) and carry `.status_code` and
+`.request_id` for correlating with support.
+
+## Auth
+
+```bash
+export SPEECHREVOLUTIONS_API_KEY=stt_...
+# or
+export STT_API_KEY=stt_...
+```
+
+Or `SpeechRevolutions(api_key="stt_...")`.
+
+## Other languages
+
+Speech Revolutions also publishes SDKs for
+[JavaScript/TypeScript](https://github.com/SpeechRevolutions/node-sdk),
+[Go](https://github.com/SpeechRevolutions/speechrevolutions-go), and
+[C#/.NET](https://github.com/SpeechRevolutions/csharp-sdk) — see
+[docs.speechrevolutions.com](https://docs.speechrevolutions.com) for a
+cross-language feature comparison.
+
+## License
+
+MIT

speechrevolutions-0.2.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "speechrevolutions"
+version = "0.2.0"
+description = "Official Python SDK for the Speech Revolutions speech-to-text API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Speech Revolutions" }]
+keywords = ["speech-to-text", "stt", "transcription", "whisper", "asr"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "requests>=2.28",
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+progress = ["tqdm>=4.65"]
+dev = ["pytest>=7.0", "pytest-asyncio>=0.23", "tqdm>=4.65"]
+
+[project.urls]
+Homepage = "https://speechrevolutions.com"
+Documentation = "https://docs.speechrevolutions.com"
+Repository = "https://github.com/SpeechRevolutions/python-sdk"
+Issues = "https://github.com/SpeechRevolutions/python-sdk/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# Without this marker the wheel ships no types, and every consumer of a fully
+# annotated SDK gets `Any` back from their type checker. PEP 561.
+[tool.setuptools.package-data]
+speechrevolutions = ["py.typed"]

speechrevolutions-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

speechrevolutions-0.2.0/src/speechrevolutions/__init__.py

@@ -0,0 +1,72 @@
+"""Speech Revolutions STT Python SDK."""
+
+from speechrevolutions.client import SpeechRevolutions, SpeechRevolutionsClient, STTClient
+from speechrevolutions.exceptions import (
+    APIError,
+    AuthenticationError,
+    JobFailedError,
+    JobNotFoundError,
+    RateLimitError,
+    STTError,
+    TimeoutError,
+    UploadError,
+)
+from speechrevolutions.models import (
+    JobStatus,
+    OutputType,
+    ProcessingTier,
+    ProgressEvent,
+    TranscribeOptions,
+    UploadJob,
+)
+from speechrevolutions.transcript import LanguageSegment, Transcript, Utterance, Word
+
+__all__ = [
+    # Clients
+    "STTClient",
+    "SpeechRevolutions",
+    "SpeechRevolutionsClient",
+    "AsyncSTTClient",
+    "AsyncSpeechRevolutions",
+    "AsyncSpeechRevolutionsClient",
+    # Models
+    "OutputType",
+    "ProcessingTier",
+    "TranscribeOptions",
+    "ProgressEvent",
+    "UploadJob",
+    "JobStatus",
+    "Transcript",
+    "Word",
+    "Utterance",
+    "LanguageSegment",
+    # Errors
+    "STTError",
+    "AuthenticationError",
+    "RateLimitError",
+    "JobNotFoundError",
+    "JobFailedError",
+    "UploadError",
+    "TimeoutError",
+    "APIError",
+]
+
+__version__ = "0.2.0"
+
+
+def __getattr__(name: str):
+    """Lazy-load async client so sync users don't need httpx until they import it."""
+    if name in {"AsyncSTTClient", "AsyncSpeechRevolutions", "AsyncSpeechRevolutionsClient"}:
+        from speechrevolutions.async_client import (
+            AsyncSpeechRevolutions,
+            AsyncSpeechRevolutionsClient,
+            AsyncSTTClient,
+        )
+
+        mapping = {
+            "AsyncSTTClient": AsyncSTTClient,
+            "AsyncSpeechRevolutions": AsyncSpeechRevolutions,
+            "AsyncSpeechRevolutionsClient": AsyncSpeechRevolutionsClient,
+        }
+        return mapping[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

speechrevolutions-0.2.0/src/speechrevolutions/_audio.py

@@ -0,0 +1,63 @@
+"""Audio input helpers: local path, bytes, file objects, or remote URL."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import BinaryIO
+from urllib.parse import urlparse
+
+import requests
+
+from speechrevolutions.exceptions import APIError
+
+
+def is_url(value: str) -> bool:
+    try:
+        parsed = urlparse(value)
+        return parsed.scheme in ("http", "https") and bool(parsed.netloc)
+    except Exception:
+        return False
+
+
+def read_audio(
+    audio: str | Path | bytes | BinaryIO,
+    *,
+    session: requests.Session | None = None,
+    timeout: float = 120.0,
+) -> tuple[bytes, int]:
+    """
+    Normalize audio input to bytes.
+
+    Accepts a local filesystem path, http(s) URL, raw bytes, or binary file object.
+    """
+    if isinstance(audio, (str, Path)):
+        value = str(audio)
+        if is_url(value):
+            sess = session or requests.Session()
+            try:
+                resp = sess.get(value, timeout=timeout)
+            except requests.exceptions.RequestException as exc:
+                raise APIError(f"Failed to download audio URL: {exc}") from exc
+            if resp.status_code != 200:
+                raise APIError(
+                    f"Failed to download audio URL (HTTP {resp.status_code})",
+                    status_code=resp.status_code,
+                    body=resp.text[:300],
+                )
+            data = resp.content
+        else:
+            path = Path(value)
+            if not path.exists():
+                raise FileNotFoundError(f"Audio file not found: {path}")
+            data = path.read_bytes()
+    elif isinstance(audio, bytes):
+        data = audio
+    elif hasattr(audio, "read"):
+        raw = audio.read()
+        data = raw if isinstance(raw, bytes) else raw.encode("utf-8")
+    else:
+        raise TypeError(f"Unsupported audio type: {type(audio)!r}")
+
+    if not data:
+        raise ValueError("Audio is empty")
+    return data, len(data)

speechrevolutions-0.2.0/src/speechrevolutions/_config.py

@@ -0,0 +1,129 @@
+"""Shared SDK constants and API-key resolution."""
+
+from __future__ import annotations
+
+import os
+
+from speechrevolutions.exceptions import AuthenticationError
+
+DEFAULT_BASE_URL = "https://api.speechrevolutions.com"
+ENV_API_KEY_NAMES = ("SPEECHREVOLUTIONS_API_KEY", "STT_API_KEY")
+
+#: Overrides the API host. Symmetric with the key: if a caller can supply an
+#: API key from the environment, they can point it at an environment too.
+#: Needed for staging, for an egress proxy or gateway, and for running any
+#: published example (the cookbook) against something that is not production.
+ENV_BASE_URL_NAMES = ("SPEECHREVOLUTIONS_BASE_URL", "STT_BASE_URL")
+
+UPLOAD_PROGRESS_INTERVAL = 10
+UPLOAD_MAX_ATTEMPTS = 4
+UPLOAD_BASE_DELAY = 1.0
+
+SSE_MAX_RECONNECTS = 10
+SSE_RECONNECT_DELAY = 3.0
+
+#: How many times to retry a stream endpoint that answered with a NON-2xx
+#: status, as opposed to one whose connection dropped.
+#:
+#: The two failures look the same to the reconnect loop and are not the same
+#: thing. A dropped connection is transient — the server was streaming a moment
+#: ago and will be again — so ten attempts on a 3s timer is right. A non-2xx
+#: status is a refusal: a proxy, load balancer or corporate egress that does not
+#: pass `text/event-stream` answers every attempt identically, forever. Retrying
+#: that ten times costs 30 seconds before the client falls back to polling, on
+#: EVERY job, which is longer than the median job takes to transcribe.
+#:
+#: Two attempts, so a genuinely transient 502/503 still gets a second chance,
+#: then fall back to polling — which works and is only marginally slower.
+SSE_MAX_STATUS_REFUSALS = 2
+
+POLL_INTERVAL = 5.0
+
+# Transient-failure retry policy for JSON API requests (not uploads/SSE, which
+# have their own retry loops). Overridable per-client via STTClient(...).
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_RETRY_BACKOFF = 0.5  # seconds; exponential (0.5, 1.0, 2.0, …), capped
+RETRY_BACKOFF_MAX = 30.0
+RETRY_STATUS_CODES = frozenset({429, 500, 502, 503, 504})
+
+# Endpoints that CREATE a job, and so are not safe to blindly retry.
+#
+# A job is created the moment the server handles one of these; the response
+# carrying the job_id back is what can be lost. Retrying after the request may
+# have arrived creates a SECOND job for the same audio — two transcripts, two
+# charges — and the caller never learns about the orphan. The API has no
+# idempotency key, so the only safe rule is to retry these solely when the
+# request provably never reached the server: a connect timeout (no connection
+# was ever established) or a 429 (explicitly refused before any work).
+#
+# Every other endpoint either reads, or acts on a job_id the caller already
+# holds, and stays fully retryable.
+JOB_CREATING_PATHS = frozenset(
+    {
+        "/api/v1/upload",
+        "/api/v1/upload/multipart/create",
+    }
+)
+
+
+def creates_job(path: str) -> bool:
+    """True if `path` creates a job, and so must not be blindly retried."""
+    return path.split("?", 1)[0].rstrip("/") in JOB_CREATING_PATHS
+
+
+# Response headers checked (case-insensitively) for a correlation id.
+REQUEST_ID_HEADERS = ("x-request-id", "x-amzn-requestid", "cf-ray")
+
+
+def extract_request_id(headers: object) -> str | None:
+    """Return the first present request-id header value, or None."""
+    get = getattr(headers, "get", None)
+    if get is None:
+        return None
+    for name in REQUEST_ID_HEADERS:
+        value = get(name)
+        if value:
+            return str(value)
+    return None
+
+
+def parse_retry_after(value: str | None) -> float | None:
+    """Parse a Retry-After header (delta-seconds form) into seconds."""
+    if not value:
+        return None
+    try:
+        return max(0.0, float(value))
+    except (TypeError, ValueError):
+        return None  # HTTP-date form is not honored; caller falls back to backoff
+
+
+def resolve_base_url(base_url: str | None) -> str:
+    """An explicit argument wins, then the environment, then production."""
+    if base_url:
+        return base_url.rstrip("/")
+    for name in ENV_BASE_URL_NAMES:
+        value = os.environ.get(name)
+        if value:
+            return value.rstrip("/")
+    return DEFAULT_BASE_URL
+
+
+def resolve_api_key(api_key: str | None) -> str:
+    if api_key:
+        return api_key
+    for name in ENV_API_KEY_NAMES:
+        value = os.environ.get(name)
+        if value:
+            return value
+    raise AuthenticationError(
+        "api_key is required (pass api_key=... or set "
+        "SPEECHREVOLUTIONS_API_KEY / STT_API_KEY)"
+    )
+
+
+# Identifies the SDK to the platform, which makes a client-side problem findable
+# in our edge logs without the caller reproducing it. It is also insurance: the
+# edge answers a request with NO User-Agent with a bare 403, which is how the C#
+# client turned out to be unable to reach production at all while passing every
+# test that pointed at a local mock.
+USER_AGENT = "speechrevolutions-python/0.2.0"