u-transcript-max 0.1.0a1__py3-none-any.whl

utmax/adapters/providers/base.py

@@ -0,0 +1,177 @@
+"""What every translator provides, plus the plumbing shared by the built-in providers."""
+
+from __future__ import annotations
+
+import importlib
+import re
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+from types import ModuleType
+from typing import Any, ClassVar, TypedDict, Unpack
+
+from utmax.errors import (
+    InvalidOption,
+    ProviderAuthError,
+    ProviderError,
+    ProviderNotInstalled,
+    ProviderRateLimited,
+    TranslationError,
+)
+
+__all__ = [
+    "EngineOptions",
+    "SDKTranslator",
+    "Translator",
+    "positive_int",
+    "redact_secrets",
+    "stainless_error",
+]
+
+_SECRET = re.compile(r"\b(?:sk-[A-Za-z0-9_*-]{6,}|AIza[0-9A-Za-z_-]{20,})")
+
+
+class EngineOptions(TypedDict, total=False):
+    """The engine options every translator accepts as keyword arguments."""
+
+    batch_chars: int
+    batch_items: int
+    context_items: int
+    concurrency: int
+    max_attempts: int
+
+
+def positive_int(option: str, value: object, *, minimum: int = 1) -> int:
+    """``value`` when it is an integer of at least ``minimum``, else :class:`InvalidOption`."""
+    if isinstance(value, bool) or not isinstance(value, int) or value < minimum:
+        raise InvalidOption(f"{option} must be an integer of at least {minimum}, not {value!r}.")
+    return value
+
+
+def redact_secrets(text: str) -> str:
+    """``text`` with anything shaped like an API key replaced by ``[redacted]``."""
+    return _SECRET.sub("[redacted]", text)
+
+
+class Translator(ABC):
+    """Translates batches of subtitle cues by asking an AI model for JSON.
+
+    Use :func:`utmax.translator` to get one of the built-in translators from a
+    ``"provider=model-id"`` string, or subclass this to plug in any other model: implement
+    :attr:`name` and :meth:`generate_json`, then pass an instance as ``model=`` to
+    :func:`utmax.translate`.
+
+    The engine options control how :func:`utmax.translate` splits the work:
+
+    Args:
+        batch_chars: most characters of cue text in one request.
+        batch_items: most cues in one request.
+        context_items: neighbouring source cues sent on each side as read-only context.
+        concurrency: requests running at the same time.
+        max_attempts: tries per batch before it is split in half.
+    """
+
+    def __init__(
+        self,
+        *,
+        batch_chars: int = 4000,
+        batch_items: int = 50,
+        context_items: int = 3,
+        concurrency: int = 4,
+        max_attempts: int = 2,
+    ) -> None:
+        self.batch_chars = positive_int("batch_chars", batch_chars)
+        self.batch_items = positive_int("batch_items", batch_items)
+        self.context_items = positive_int("context_items", context_items, minimum=0)
+        self.concurrency = positive_int("concurrency", concurrency)
+        self.max_attempts = positive_int("max_attempts", max_attempts)
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """``"provider=model-id"``, for example ``"claude=claude-opus-5"``.
+
+        Stored as ``Transcript.translator`` on every translation.
+        """
+
+    @property
+    def provider(self) -> str:
+        """The provider part of :attr:`name`, used in error reports."""
+        return self.name.partition("=")[0]
+
+    @abstractmethod
+    def generate_json(self, system: str, prompt: str, schema: Mapping[str, Any]) -> str:
+        """Send one request and return the model's raw answer, which should be JSON.
+
+        Args:
+            system: the system prompt.
+            prompt: the user message, a JSON document describing one batch.
+            schema: the JSON schema the answer must match.
+
+        Raise :class:`utmax.providers.InvalidResponse` for an answer that cannot be used, such
+        as one cut off by a token limit (the engine retries, then splits the batch), and a
+        :class:`utmax.errors.TranslationError` subclass when the provider fails (never retried).
+        """
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.name!r})"
+
+
+class SDKTranslator(Translator):
+    """Base of the built-in translators: a provider id, a model id and a lazily imported SDK.
+
+    API keys are handed straight to the SDK client and never stored, logged or shown by utmax.
+    """
+
+    PROVIDER: ClassVar[str]
+    EXTRA: ClassVar[str]
+
+    def __init__(self, model: str, **engine: Unpack[EngineOptions]) -> None:
+        super().__init__(**engine)
+        if not isinstance(model, str) or not model.strip():
+            raise InvalidOption(f"The {self.PROVIDER} model id must not be empty, got {model!r}.")
+        self.model = model.strip()
+
+    @property
+    def name(self) -> str:
+        return f"{self.PROVIDER}={self.model}"
+
+    def import_sdk(self, module: str) -> ModuleType:
+        """Import ``module`` (the provider's SDK), or say which extra installs it."""
+        try:
+            return importlib.import_module(module)
+        except ImportError as error:
+            command = f'pip install "u-transcript-max[{self.EXTRA}]"'
+            raise ProviderNotInstalled(
+                f"The {self.PROVIDER} translator needs the {module!r} package: {command}",
+                provider=self.PROVIDER,
+                extra=self.EXTRA,
+                suggestion=f"Install the {self.EXTRA} extra with: {command}",
+            ) from error
+
+
+def stainless_error(
+    sdk: Any, error: BaseException, *, provider: str, service: str
+) -> TranslationError | None:
+    """Map an exception of the Anthropic or OpenAI SDK (both generated by Stainless).
+
+    ``service`` names the server in the message ("Anthropic", "the server at ..."). Returns
+    ``None`` for exceptions that are not API failures, which callers re-raise.
+    """
+    detail = redact_secrets(str(getattr(error, "message", "") or error))
+    status = getattr(error, "status_code", None)
+    if isinstance(error, (sdk.AuthenticationError, sdk.PermissionDeniedError)):
+        return ProviderAuthError(
+            f"Credentials rejected by {service} (HTTP {status}): {detail}", provider=provider
+        )
+    if isinstance(error, sdk.RateLimitError):
+        return ProviderRateLimited(
+            f"Still rate-limited by {service} after the SDK's retries: {detail}",
+            provider=provider,
+        )
+    if isinstance(error, sdk.APIStatusError):
+        return ProviderError(
+            f"HTTP {status} from {service}: {detail}", provider=provider, status_code=status
+        )
+    if isinstance(error, sdk.APIConnectionError):
+        return ProviderError(f"Could not reach {service}: {detail}", provider=provider)
+    return None

utmax/adapters/providers/claude.py

@@ -0,0 +1,108 @@
+"""Claude through the official ``anthropic`` SDK, with structured JSON output."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from typing import Any, Unpack
+
+from utmax.adapters.providers.base import (
+    EngineOptions,
+    SDKTranslator,
+    positive_int,
+    redact_secrets,
+    stainless_error,
+)
+from utmax.core.translate.batching import InvalidResponse
+from utmax.errors import InvalidOption, ProviderAuthError, TranslationRefused
+
+__all__ = ["ClaudeTranslator"]
+
+log = logging.getLogger("utmax.translate")
+
+_EFFORTS = ("low", "medium", "high", "xhigh", "max")
+_CUT_OFF = frozenset({"max_tokens", "model_context_window_exceeded"})
+
+
+class ClaudeTranslator(SDKTranslator):
+    """Translates with Anthropic's Claude models (``pip install "u-transcript-max[claude]"``).
+
+    Args:
+        model: a Claude model id such as ``"claude-opus-5"``.
+        api_key: an Anthropic API key; by default the SDK finds one itself
+            (``ANTHROPIC_API_KEY``, ``ANTHROPIC_AUTH_TOKEN`` or an ``ant auth login`` profile).
+        effort: ``"low"``, ``"medium"``, ``"high"``, ``"xhigh"`` or ``"max"``; omitted means
+            the model's default.
+        max_tokens: the most tokens one answer may use.
+        client: a ready ``anthropic.Anthropic`` client, used instead of creating one.
+        **engine: engine options, see :class:`utmax.providers.Translator`.
+    """
+
+    PROVIDER = "claude"
+    EXTRA = "claude"
+
+    def __init__(
+        self,
+        model: str,
+        *,
+        api_key: str | None = None,
+        effort: str | None = None,
+        max_tokens: int = 16000,
+        client: Any = None,
+        **engine: Unpack[EngineOptions],
+    ) -> None:
+        super().__init__(model, **engine)
+        if effort is not None and effort not in _EFFORTS:
+            raise InvalidOption(f"effort must be one of {', '.join(_EFFORTS)}, not {effort!r}.")
+        self.effort = effort
+        self.max_tokens = positive_int("max_tokens", max_tokens)
+        self._sdk = self.import_sdk("anthropic")
+        if client is None:
+            try:
+                client = self._sdk.Anthropic(api_key=api_key)
+            except self._sdk.CredentialsError as error:
+                raise self._no_credentials(error) from error
+        self._client = client
+
+    def generate_json(self, system: str, prompt: str, schema: Mapping[str, Any]) -> str:
+        output_config: dict[str, Any] = {"format": {"type": "json_schema", "schema": dict(schema)}}
+        if self.effort is not None:
+            output_config["effort"] = self.effort
+        try:
+            message = self._client.messages.create(
+                model=self.model,
+                max_tokens=self.max_tokens,
+                system=system,
+                messages=[{"role": "user", "content": prompt}],
+                output_config=output_config,
+            )
+        except TypeError as error:
+            # anthropic raises this TypeError before sending when it finds no credentials.
+            if "authentication" not in str(error).lower():
+                raise
+            raise self._no_credentials(error) from error
+        except self._sdk.CredentialsError as error:
+            raise self._no_credentials(error) from error
+        except self._sdk.AnthropicError as error:
+            mapped = stainless_error(self._sdk, error, provider=self.PROVIDER, service="Anthropic")
+            if mapped is None:
+                raise
+            raise mapped from error
+        if message.stop_reason == "refusal":
+            category = getattr(message.stop_details, "category", None) or "unspecified"
+            raise TranslationRefused(
+                f"Claude declined to translate this batch (refusal category: {category}).",
+                provider=self.PROVIDER,
+            )
+        text = "".join(block.text for block in message.content if block.type == "text")
+        if message.stop_reason in _CUT_OFF:
+            log.info("%s: the answer stopped early (%s)", self.name, message.stop_reason)
+            raise InvalidResponse(f"the answer was cut off ({message.stop_reason})", raw=text)
+        return text
+
+    def _no_credentials(self, error: Exception) -> ProviderAuthError:
+        return ProviderAuthError(
+            f"No usable Anthropic credentials were found: {redact_secrets(str(error))}",
+            provider=self.PROVIDER,
+            suggestion="Pass api_key=... or set the ANTHROPIC_API_KEY environment variable.",
+        )

utmax/adapters/providers/gemini.py

@@ -0,0 +1,133 @@
+"""Gemini through the official ``google-genai`` SDK, with JSON Schema output."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from typing import Any, Unpack
+
+from utmax.adapters.providers.base import (
+    EngineOptions,
+    SDKTranslator,
+    positive_int,
+    redact_secrets,
+)
+from utmax.core.translate.batching import InvalidResponse
+from utmax.errors import (
+    ProviderAuthError,
+    ProviderError,
+    ProviderRateLimited,
+    TranslationError,
+    TranslationRefused,
+)
+
+__all__ = ["GeminiTranslator"]
+
+log = logging.getLogger("utmax.translate")
+
+_REFUSED = frozenset(
+    {"SAFETY", "RECITATION", "LANGUAGE", "BLOCKLIST", "PROHIBITED_CONTENT", "SPII"}
+)
+
+
+class GeminiTranslator(SDKTranslator):
+    """Translates with Google's Gemini models (``pip install "u-transcript-max[gemini]"``).
+
+    Args:
+        model: a Gemini model id such as ``"gemini-2.5-flash"``.
+        api_key: a Gemini API key; by default the SDK reads ``GEMINI_API_KEY`` or
+            ``GOOGLE_API_KEY``.
+        retry_attempts: tries per request, the first included, on HTTP 408, 429 and 5xx; the
+            SDK does not retry unless asked to.
+        client: a ready ``google.genai.Client``, used instead of creating one.
+        **engine: engine options, see :class:`utmax.providers.Translator`.
+    """
+
+    PROVIDER = "gemini"
+    EXTRA = "gemini"
+
+    def __init__(
+        self,
+        model: str,
+        *,
+        api_key: str | None = None,
+        retry_attempts: int = 5,
+        client: Any = None,
+        **engine: Unpack[EngineOptions],
+    ) -> None:
+        super().__init__(model, **engine)
+        self.retry_attempts = positive_int("retry_attempts", retry_attempts)
+        self._genai = self.import_sdk("google.genai")
+        self._types = self.import_sdk("google.genai.types")
+        self._errors = self.import_sdk("google.genai.errors")
+        self._httpx = self.import_sdk("httpx")
+        if client is None:
+            try:
+                client = self._genai.Client(api_key=api_key)
+            except ValueError as error:
+                raise ProviderAuthError(
+                    f"No Gemini API key was found: {redact_secrets(str(error))}",
+                    provider=self.PROVIDER,
+                    suggestion="Pass api_key=... or set the GEMINI_API_KEY environment variable.",
+                ) from error
+        self._client = client
+
+    def generate_json(self, system: str, prompt: str, schema: Mapping[str, Any]) -> str:
+        types = self._types
+        config = types.GenerateContentConfig(
+            system_instruction=system,
+            response_mime_type="application/json",
+            response_json_schema=dict(schema),
+            http_options=types.HttpOptions(
+                retry_options=types.HttpRetryOptions(attempts=self.retry_attempts)
+            ),
+            # No tools are sent; this skips the SDK's function-calling loop and its log notice.
+            automatic_function_calling=types.AutomaticFunctionCallingConfig(disable=True),
+        )
+        try:
+            response = self._client.models.generate_content(
+                model=self.model, contents=prompt, config=config
+            )
+        except self._errors.APIError as error:
+            raise self._api_error(error) from error
+        except self._httpx.TransportError as error:
+            raise ProviderError(
+                f"Could not reach Gemini: {redact_secrets(str(error))}", provider=self.PROVIDER
+            ) from error
+        feedback = response.prompt_feedback
+        if feedback is not None and feedback.block_reason:
+            raise TranslationRefused(
+                f"Gemini blocked this batch ({_label(feedback.block_reason)}).",
+                provider=self.PROVIDER,
+            )
+        candidate = response.candidates[0] if response.candidates else None
+        reason = _label(candidate.finish_reason) if candidate is not None else ""
+        if reason in _REFUSED:
+            raise TranslationRefused(
+                f"Gemini stopped answering this batch ({reason}).", provider=self.PROVIDER
+            )
+        text: str = response.text or ""
+        if reason == "MAX_TOKENS":
+            log.info("%s: the answer stopped early (MAX_TOKENS)", self.name)
+            raise InvalidResponse("the answer was cut off (MAX_TOKENS)", raw=text)
+        return text
+
+    def _api_error(self, error: Any) -> TranslationError:
+        code = error.code
+        detail = redact_secrets(f"{error.status}: {error.message}")
+        if code in (401, 403) or "api key" in str(error.message or "").lower():
+            return ProviderAuthError(
+                f"Credentials rejected by Gemini (HTTP {code}): {detail}", provider=self.PROVIDER
+            )
+        if code == 429:
+            return ProviderRateLimited(
+                f"Still rate-limited by Gemini after {self.retry_attempts} attempts: {detail}",
+                provider=self.PROVIDER,
+            )
+        return ProviderError(
+            f"HTTP {code} from Gemini: {detail}", provider=self.PROVIDER, status_code=code
+        )
+
+
+def _label(value: object) -> str:
+    return str(getattr(value, "value", value) or "")

utmax/adapters/providers/openai.py

@@ -0,0 +1,169 @@
+"""OpenAI and OpenAI-compatible servers through the official ``openai`` SDK."""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+from collections.abc import Mapping
+from typing import Any, Literal, Unpack
+
+from utmax.adapters.http import redact
+from utmax.adapters.providers.base import EngineOptions, SDKTranslator, stainless_error
+from utmax.core.translate.batching import InvalidResponse
+from utmax.errors import InvalidOption, ProviderAuthError, TranslationRefused
+
+__all__ = ["JsonMode", "OpenAITranslator"]
+
+log = logging.getLogger("utmax.translate")
+
+JsonMode = Literal["auto", "json_schema", "json_object", "prompt"]
+
+_MODES: tuple[JsonMode, ...] = ("auto", "json_schema", "json_object", "prompt")
+_STEP_DOWN: dict[str, JsonMode] = {"json_schema": "json_object", "json_object": "prompt"}
+_FORMAT_WORDS = ("response_format", "json_schema", "json_object", "structured output")
+_SCHEMA_NAME = "subtitle_translation"
+_NO_KEY = "not-needed"
+
+
+class OpenAITranslator(SDKTranslator):
+    """Translates with OpenAI or any OpenAI-compatible server (``pip install
+    "u-transcript-max[openai]"``): Ollama, LM Studio, vLLM, Groq, DeepSeek and others.
+
+    Args:
+        model: a model id such as ``"gpt-5-mini"`` or ``"llama3.1:8b"``.
+        api_key: the API key. Without ``base_url`` the SDK falls back to ``OPENAI_API_KEY``;
+            with ``base_url`` only this argument is sent, so your OpenAI key never reaches
+            another server and keyless local servers need nothing.
+        base_url: the address of an OpenAI-compatible API, such as
+            ``"http://localhost:11434/v1"`` for Ollama.
+        json_mode: how the answer is kept to JSON: ``"json_schema"`` (strict structured
+            output), ``"json_object"``, ``"prompt"`` (instructions only) or ``"auto"``, which
+            starts with ``json_schema`` and steps down each time the server rejects the mode,
+            remembering the working one for later requests.
+        client: a ready ``openai.OpenAI`` client, used instead of creating one.
+        **engine: engine options, see :class:`utmax.providers.Translator`.
+    """
+
+    PROVIDER = "openai"
+    EXTRA = "openai"
+
+    def __init__(
+        self,
+        model: str,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        json_mode: JsonMode = "auto",
+        client: Any = None,
+        **engine: Unpack[EngineOptions],
+    ) -> None:
+        super().__init__(model, **engine)
+        if json_mode not in _MODES:
+            raise InvalidOption(f"json_mode must be one of {', '.join(_MODES)}, not {json_mode!r}.")
+        self.json_mode = json_mode
+        self._mode: JsonMode = "json_schema" if json_mode == "auto" else json_mode
+        self._lock = threading.Lock()
+        self._extra_body: dict[str, Any] | None = None
+        self._service = "OpenAI" if base_url is None else f"the server at {redact(base_url)}"
+        self._sdk = self.import_sdk("openai")
+        self._client = client if client is not None else self._make_client(api_key, base_url)
+
+    @property
+    def mode(self) -> JsonMode:
+        """The JSON mode of the next request; ``"auto"`` settles on one of the other three."""
+        return self._mode
+
+    def generate_json(self, system: str, prompt: str, schema: Mapping[str, Any]) -> str:
+        while True:
+            mode = self._mode
+            try:
+                completion = self._client.chat.completions.create(
+                    **self._request(mode, system, prompt, schema)
+                )
+            except self._sdk.OpenAIError as error:
+                if self._rejects_json_mode(mode, error):
+                    self._step_down(mode)
+                    continue
+                mapped = stainless_error(
+                    self._sdk, error, provider=self.PROVIDER, service=self._service
+                )
+                if mapped is None:
+                    raise
+                raise mapped from error
+            return self._answer(completion)
+
+    def _make_client(self, api_key: str | None, base_url: str | None) -> Any:
+        if base_url is not None and api_key is None:
+            api_key = _NO_KEY
+        try:
+            return self._sdk.OpenAI(api_key=api_key, base_url=base_url)
+        except self._sdk.OpenAIError as error:
+            raise ProviderAuthError(
+                "No OpenAI API key was found for the openai translator.",
+                provider=self.PROVIDER,
+                suggestion="Pass api_key=... or set the OPENAI_API_KEY environment variable.",
+            ) from error
+
+    def _request(
+        self, mode: JsonMode, system: str, prompt: str, schema: Mapping[str, Any]
+    ) -> dict[str, Any]:
+        if mode != "json_schema":
+            system += (
+                "\n\nThe reply must be a JSON object that matches this JSON Schema:\n"
+                + json.dumps(dict(schema))
+            )
+        request: dict[str, Any] = {
+            "model": self.model,
+            "messages": [
+                {"role": "system", "content": system},
+                {"role": "user", "content": prompt},
+            ],
+        }
+        if mode == "json_schema":
+            request["response_format"] = {
+                "type": "json_schema",
+                "json_schema": {"name": _SCHEMA_NAME, "schema": dict(schema), "strict": True},
+            }
+        elif mode == "json_object":
+            request["response_format"] = {"type": "json_object"}
+        if self._extra_body is not None:
+            request["extra_body"] = self._extra_body
+        return request
+
+    def _rejects_json_mode(self, mode: JsonMode, error: Exception) -> bool:
+        if self.json_mode != "auto" or mode not in _STEP_DOWN:
+            return False
+        if not isinstance(error, (self._sdk.BadRequestError, self._sdk.UnprocessableEntityError)):
+            return False
+        text = f"{getattr(error, 'message', '')} {getattr(error, 'body', '')}".lower()
+        return any(word in text for word in _FORMAT_WORDS)
+
+    def _step_down(self, tried: JsonMode) -> None:
+        with self._lock:
+            if self._mode == tried:
+                self._mode = _STEP_DOWN[tried]
+                log.info(
+                    "%s rejected response_format %s; using %s from now on",
+                    self.name,
+                    tried,
+                    self._mode,
+                )
+
+    def _answer(self, completion: Any) -> str:
+        if not completion.choices:
+            raise InvalidResponse("the answer had no choices")
+        choice = completion.choices[0]
+        refusal = getattr(choice.message, "refusal", None)
+        if refusal:
+            raise TranslationRefused(
+                f"The model declined to translate this batch: {refusal}", provider=self.PROVIDER
+            )
+        if choice.finish_reason == "content_filter":
+            raise TranslationRefused(
+                "The provider's content filter blocked this batch.", provider=self.PROVIDER
+            )
+        text: str = choice.message.content or ""
+        if choice.finish_reason == "length":
+            raise InvalidResponse("the answer was cut off (finish_reason=length)", raw=text)
+        return text

utmax/adapters/providers/openrouter.py

@@ -0,0 +1,59 @@
+"""OpenRouter, which speaks the OpenAI API, through the official ``openai`` SDK."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Unpack
+
+from utmax.adapters.providers.base import EngineOptions
+from utmax.adapters.providers.openai import OpenAITranslator
+from utmax.errors import ProviderAuthError
+
+__all__ = ["OPENROUTER_BASE_URL", "OpenRouterTranslator"]
+
+OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
+
+
+class OpenRouterTranslator(OpenAITranslator):
+    """Translates with any model on OpenRouter (``pip install "u-transcript-max[openrouter]"``).
+
+    Every request asks OpenRouter to route only to hosts that support all parameters sent
+    (``provider.require_parameters``), so structured JSON output is honoured; the JSON mode
+    steps down like ``OpenAITranslator(json_mode="auto")``.
+
+    Args:
+        model: an OpenRouter model id such as ``"anthropic/claude-opus-5"``.
+        api_key: the OpenRouter key; by default ``OPENROUTER_API_KEY`` (``OPENAI_API_KEY`` is
+            never used).
+        app_name: your application's name, sent as OpenRouter's ``X-Title`` header.
+        client: a ready ``openai.OpenAI`` client pointed at OpenRouter.
+        **engine: engine options, see :class:`utmax.providers.Translator`.
+    """
+
+    PROVIDER = "openrouter"
+    EXTRA = "openrouter"
+
+    def __init__(
+        self,
+        model: str,
+        *,
+        api_key: str | None = None,
+        app_name: str | None = None,
+        client: Any = None,
+        **engine: Unpack[EngineOptions],
+    ) -> None:
+        self.app_name = app_name
+        super().__init__(model, api_key=api_key, client=client, **engine)
+        self._service = "OpenRouter"
+        self._extra_body = {"provider": {"require_parameters": True}}
+
+    def _make_client(self, api_key: str | None, base_url: str | None) -> Any:
+        key = api_key or os.environ.get("OPENROUTER_API_KEY")
+        if not key:
+            raise ProviderAuthError(
+                "No OpenRouter API key was found for the openrouter translator.",
+                provider=self.PROVIDER,
+                suggestion="Pass api_key=... or set the OPENROUTER_API_KEY environment variable.",
+            )
+        headers = {"X-Title": self.app_name} if self.app_name else None
+        return self._sdk.OpenAI(api_key=key, base_url=OPENROUTER_BASE_URL, default_headers=headers)