relaygpu-client 0.1.0__py3-none-any.whl

relaygpu/__init__.py

@@ -0,0 +1,21 @@
+"""Relay's Python SDK: image, video and audio generation, async tasks, file uploads, webhook verification,
+workflows, account and keys, with typed errors. A port of ``@relaygpu/client``."""
+
+from ._async.image import AsyncImageResult as AsyncImageResult
+from ._async.image import AsyncRelayImage as AsyncRelayImage
+from ._core import DEFAULT_BASE_URL as DEFAULT_BASE_URL
+from ._core import DEFAULT_TIMEOUT as DEFAULT_TIMEOUT
+from ._core import APIResponse as APIResponse
+from ._core import RetryOptions as RetryOptions
+from ._run_common import is_accepted as is_accepted
+from ._sync.image import ImageResult as ImageResult
+from ._sync.image import RelayImage as RelayImage
+from ._sync.image import to_relay_image as to_relay_image
+from ._version import VERSION as VERSION
+from .async_client import AsyncRelay as AsyncRelay
+from .client import Relay as Relay
+from .errors import *  # noqa: F403
+from .inputs import INLINE_IMAGE_MAX_BYTES as INLINE_IMAGE_MAX_BYTES
+from .webhooks import verify_webhook as verify_webhook
+
+__version__ = VERSION

relaygpu/_async/__init__.py

@@ -0,0 +1 @@
+"""Hand-written async sources; relaygpu/_sync/ is generated from them by scripts/unasync.py."""

relaygpu/_async/_http.py

@@ -0,0 +1,146 @@
+"""The transport (port of src/http.ts `HttpClient`). Hand-written async; ``_sync/_http.py`` is generated from it by
+scripts/unasync.py. Everything that is not I/O lives in ``relaygpu/_core.py``."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from .. import _clock
+from .._core import (
+    _UNSET,
+    DEFAULT_BASE_URL,
+    DEFAULT_TIMEOUT,
+    USER_AGENT,
+    APIResponse,
+    RawBody,
+    RetryOptions,
+    RetryPolicy,
+    RetryState,
+    auth_headers,
+    build_headers,
+    encode_json,
+    is_replayable,
+    parse_ok,
+    query_params,
+    read_error_body,
+    transport_errors,
+)
+from .._errors import error_from_response
+from .._exceptions import APIConnectionError, APITimeoutError
+from .._images import download_error
+
+
+class AsyncHttpClient:
+    """Headers, timeouts, the retry policy, ``X-Request-ID`` and ``Idempotency-Replayed``. Never exposes the credential."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        jwt: str | None = None,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        retry: bool | RetryOptions | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.__auth = auth_headers(api_key, jwt)
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = float(timeout) if timeout is not None else DEFAULT_TIMEOUT
+        self.retry = RetryPolicy.from_option(retry)
+        self._default_headers = dict(default_headers or {})
+        self._owns_client = http_client is None
+        self._client = http_client if http_client is not None else httpx.AsyncClient(follow_redirects=True)
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(base_url={self.base_url!r})"
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    def url(self, path: str) -> str:
+        return self.base_url + path
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,  # a Query, or a params TypedDict (only Mapping[str, Any] takes those)
+        json: Any = _UNSET,
+        content: RawBody | None = None,
+        content_type: str | None = None,
+        headers: Mapping[str, str] | None = None,
+        timeout: float | None = None,
+        idempotency_key: str | None = None,
+        no_auth: bool = False,
+    ) -> APIResponse[Any]:
+        """One API call with the retry policy. ``json`` is serialised; ``content`` is sent raw (bytes, or an iterator
+        of bytes, which is sent once and never retried). ``idempotency_key`` makes a POST retry-safe."""
+        method = method.upper()
+        is_get = method in ("GET", "HEAD")
+        hdrs = build_headers(self.__auth, self._default_headers, headers, no_auth=no_auth, idempotency_key=idempotency_key)
+        body: RawBody | None = None
+        if content is not None:
+            body = content
+            if content_type:
+                hdrs["Content-Type"] = content_type
+        elif json is not _UNSET:
+            body = encode_json(json)
+            hdrs["Content-Type"] = "application/json"
+        state = RetryState(self.retry, is_get, not is_get and idempotency_key is not None, is_replayable(body))
+        url = self.url(path)
+        params: list[tuple[str, str | int | float | bool | None]] = list(query_params(query))  # list is invariant: widen for httpx
+        t = timeout if timeout is not None else self.timeout
+        while True:
+            try:
+                res = await self._send(method, url, params, hdrs, body, t, path)
+            except (APIConnectionError, APITimeoutError):
+                wait = state.after_transport_error()
+                if wait is None:
+                    raise
+                await _clock.async_sleep(wait)
+                continue
+            if res.is_success:
+                return parse_ok(res)
+            err = error_from_response(res.status_code, read_error_body(res), res.headers)
+            wait = state.after_error(res.status_code, err.code, err.retry_after)
+            if wait is None:
+                raise err
+            await _clock.async_sleep(wait)
+
+    async def _send(
+        self,
+        method: str,
+        url: str,
+        params: list[tuple[str, str | int | float | bool | None]],
+        headers: dict[str, str],
+        body: RawBody | None,
+        timeout: float,
+        path: str,
+    ) -> httpx.Response:
+        with transport_errors(f"Request timed out after {timeout:g} s: {method} {path}", f"Connection error: {method} {path}"):
+            res = await self._client.request(
+                method,
+                url,
+                params=params or None,
+                headers=headers,
+                content=body,
+                timeout=timeout,
+            )
+            await res.aread()
+        return res
+
+    async def download(self, url: str) -> bytes:
+        """GETs an absolute result link (an output image) over the same transport. Never with the credential or the
+        client's default headers (only ``User-Agent``); redirects followed; never retried."""
+        with transport_errors(f"Image download timed out: {url}", "Image download failed"):
+            res = await self._client.get(url, headers={"User-Agent": USER_AGENT}, timeout=self.timeout, follow_redirects=True)
+            await res.aread()
+        if not res.is_success:
+            raise download_error(res.status_code)
+        return res.content

relaygpu/_async/account.py

@@ -0,0 +1,83 @@
+"""The ``account`` namespace (port of src/account.ts)."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import TYPE_CHECKING, Any, cast
+
+from .._generated.types import (
+    CreditHistoryResponse,
+    CreditsResponse,
+    CustomerPricingResponse,
+    CustomerUsageResponse,
+    KeyWithAnalytics,
+    MetricsPage,
+    ModelAllowlistResponse,
+    ModelAllowlistView,
+    ProfileResponse,
+    UsageTimeseriesPage,
+)
+from .._shapes import CreditHistoryParams, KeyUsageParams, MetricsParams, UsageParams, UsageTimeseriesParams
+from .._util import path_id
+
+if TYPE_CHECKING:
+    from typing_extensions import Unpack
+
+    from .client import AsyncRelay
+
+
+class AsyncAccount:
+    """Account reads (Customer + Metrics ops). Auth: a dashboard JWT, or the superkey of a partner (custom) tier. A plain
+    inference key gets the server's 403 as ``PermissionDeniedError``; the SDK never guesses the key class client-side.
+
+    Query parameters are keyword arguments with the spec's names; ``from`` is spelled ``from_``."""
+
+    def __init__(self, relay: AsyncRelay) -> None:
+        self._relay = relay
+
+    async def _get(self, path: str, params: Mapping[str, Any] | None = None) -> Any:
+        res = await self._relay._http.request("GET", path, query=params)
+        return res.data
+
+    async def credits(self) -> CreditsResponse:
+        """``GET /v2/customer/credits``: balance, promos, consumption."""
+        return cast(CreditsResponse, await self._get("/v2/customer/credits"))
+
+    async def credits_history(self, **params: Unpack[CreditHistoryParams]) -> CreditHistoryResponse:
+        """``GET /v2/customer/credits/history``. **JWT only** (a superkey is refused by the server)."""
+        return cast(CreditHistoryResponse, await self._get("/v2/customer/credits/history", params))
+
+    async def usage(self, **params: Unpack[UsageParams]) -> CustomerUsageResponse:
+        """``GET /v2/customer/usage``: per-key analytics; page with ``starting_after`` = ``next_cursor``."""
+        return cast(CustomerUsageResponse, await self._get("/v2/customer/usage", params))
+
+    async def usage_by_key(self, key_id: str, **params: Unpack[KeyUsageParams]) -> KeyWithAnalytics:
+        """``GET /v2/customer/usage/{key_id}``. Address the key by ``key_id``, never its secret."""
+        return cast(KeyWithAnalytics, await self._get(f"/v2/customer/usage/{path_id(key_id)}", params))
+
+    async def usage_timeseries(self, **params: Unpack[UsageTimeseriesParams]) -> UsageTimeseriesPage:
+        """``GET /v2/customer/usage/timeseries``: bucketed spend/tokens (``start_time`` = Unix seconds, required)."""
+        return cast(UsageTimeseriesPage, await self._get("/v2/customer/usage/timeseries", params))
+
+    async def metrics(self, **params: Unpack[MetricsParams]) -> MetricsPage:
+        """``GET /v2/customer/metrics``: latency percentiles and error splits (``start_time`` = Unix seconds, required)."""
+        return cast(MetricsPage, await self._get("/v2/customer/metrics", params))
+
+    async def pricing(self) -> CustomerPricingResponse:
+        """``GET /v2/customer/pricing``: the account's effective rows (custom-tier overrides included)."""
+        return cast(CustomerPricingResponse, await self._get("/v2/customer/pricing"))
+
+    async def profile(self) -> ProfileResponse:
+        """``GET /v2/customer/profile``: profile, tier (``tier_details.is_custom``), balance, allowlist."""
+        return cast(ProfileResponse, await self._get("/v2/customer/profile"))
+
+    async def model_allowlist(self) -> ModelAllowlistView:
+        """``GET /v2/customer/model-allowlist``: the customer-wide scope list for non-superkey keys (``None`` = unset)."""
+        return cast(ModelAllowlistView, await self._get("/v2/customer/model-allowlist"))
+
+    async def set_model_allowlist(self, model_allowlist: Sequence[str] | None) -> ModelAllowlistResponse:
+        """``PATCH /v2/customer/model-allowlist``: replaces the list (``None`` clears it). Scopes are
+        ``{mode}.{source}.{model}``. Partner tiers only; the superkey stays exempt."""
+        body = {"model_allowlist": None if model_allowlist is None else [*model_allowlist]}
+        res = await self._relay._http.request("PATCH", "/v2/customer/model-allowlist", json=body)
+        return cast(ModelAllowlistResponse, res.data)

relaygpu/_async/audio.py

@@ -0,0 +1,86 @@
+"""Text-to-speech and speech-to-text (port of src/audio.ts)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import TYPE_CHECKING, Any, cast
+
+from ..types import KnownSpeechModel, KnownTranscribeModel, Mode, TaskProgress, UploadOptions
+from .run import run
+
+if TYPE_CHECKING:
+    from .client import AsyncRelay
+
+
+class AsyncAudio:
+    """Text-to-speech and speech-to-text. Same options as the image helpers: an async answer (``async_=True``) is
+    waited for."""
+
+    def __init__(self, relay: AsyncRelay) -> None:
+        self._relay = relay
+
+    async def _run(self, model: str, input: Mapping[str, Any], **options: Any) -> dict[str, Any]:
+        """The one body of ``speech`` and ``transcribe``: ``run(..., wait=True)``, so never the 202 envelope."""
+        return cast("dict[str, Any]", await run(self._relay, model, input, wait=True, **options))
+
+    async def speech(
+        self,
+        model: KnownSpeechModel | str,
+        input: Mapping[str, Any],
+        *,
+        on_progress: Callable[[TaskProgress], None] | None = None,
+        timeout: float | None = None,
+        mode: Mode | None = None,
+        store_output: str | None = None,
+        webhook_url: str | None = None,
+        idempotency_key: str | None = None,
+        async_: bool | None = None,
+        upload: UploadOptions | None = None,
+        inline_images: bool = False,
+    ) -> dict[str, Any]:
+        """Text-to-speech. Returns the response body: ``audio_url`` (a link that expires) or ``audio_base64`` +
+        ``content_type``, per model."""
+        return await self._run(
+            model,
+            input,
+            on_progress=on_progress,
+            timeout=timeout,
+            mode=mode,
+            store_output=store_output,
+            webhook_url=webhook_url,
+            idempotency_key=idempotency_key,
+            async_=async_,
+            upload=upload,
+            inline_images=inline_images,
+        )
+
+    async def transcribe(
+        self,
+        model: KnownTranscribeModel | str,
+        input: Mapping[str, Any],
+        *,
+        on_progress: Callable[[TaskProgress], None] | None = None,
+        timeout: float | None = None,
+        mode: Mode | None = None,
+        store_output: str | None = None,
+        webhook_url: str | None = None,
+        idempotency_key: str | None = None,
+        async_: bool | None = None,
+        upload: UploadOptions | None = None,
+        inline_images: bool = False,
+    ) -> dict[str, Any]:
+        """Speech-to-text. ``audio_url`` may be a link or bytes / a path / a file-like object (uploaded first). Returns
+        ``{text, language?, duration?}``."""
+        return await self._run(
+            model,
+            input,
+            on_progress=on_progress,
+            timeout=timeout,
+            mode=mode,
+            store_output=store_output,
+            webhook_url=webhook_url,
+            idempotency_key=idempotency_key,
+            async_=async_,
+            upload=upload,
+            inline_images=inline_images,
+        )

relaygpu/_async/client.py

@@ -0,0 +1,218 @@
+"""The async client (port of src/client.ts). ``_sync/client.py`` (``Relay``) is generated from this file."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from types import TracebackType
+from typing import Any, Literal, overload
+
+import httpx
+
+from .._core import _UNSET, Query, RawBody, RetryOptions
+from ..types import AsyncAccepted, CostEstimate, HealthResponse, Mode, TaskProgress, UploadOptions, UsageInput
+from ._http import AsyncHttpClient
+from .account import AsyncAccount
+from .audio import AsyncAudio
+from .estimate import estimate_cost
+from .files import AsyncFiles
+from .image import AsyncImages
+from .keys import AsyncKeys
+from .models import AsyncModels, AsyncPricing, AsyncTiers, health
+from .run import run
+from .tasks import AsyncTasks
+from .video import AsyncVideos
+from .webhooks import AsyncWebhooks
+from .workflows import AsyncWorkflows
+
+
+class AsyncRelay:
+    """The Relay client.
+
+    ``api_key`` (``relay_sk_…``) is sent as ``X-API-Key``; ``jwt`` (a dashboard login token) as ``Authorization:
+    Bearer``; never both. Catalog reads (``models``, ``pricing``, ``tiers``, ``health``) and task polls need no
+    credential. ``timeout`` is seconds per HTTP attempt (default 600). ``retry=False`` disables every retry.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        jwt: str | None = None,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        retry: bool | RetryOptions | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._http = AsyncHttpClient(
+            api_key=api_key,
+            jwt=jwt,
+            base_url=base_url,
+            timeout=timeout,
+            retry=retry,
+            default_headers=default_headers,
+            http_client=http_client,
+        )
+        self.models = AsyncModels(self)
+        self.pricing = AsyncPricing(self)
+        self.tiers = AsyncTiers(self)
+        self.tasks = AsyncTasks(self)
+        self.image = AsyncImages(self)
+        self.video = AsyncVideos(self)
+        self.audio = AsyncAudio(self)
+        self.files = AsyncFiles(self)
+        self.workflows = AsyncWorkflows(self)
+        self.account = AsyncAccount(self)
+        self.keys = AsyncKeys(self)
+        self.webhooks = AsyncWebhooks(self)
+
+    @property
+    def base_url(self) -> str:
+        return self._http.base_url
+
+    def __repr__(self) -> str:
+        # Never reveal the credential when the client is logged or printed.
+        return f"AsyncRelay(base_url={self._http.base_url!r})"
+
+    async def health(self) -> HealthResponse:
+        """``GET /v2/health``."""
+        return await health(self)
+
+    @overload
+    async def run(
+        self,
+        model: str,
+        input: Mapping[str, Any],
+        *,
+        wait: Literal[True] = True,
+        on_progress: Callable[[TaskProgress], None] | None = None,
+        timeout: float | None = None,
+        mode: Mode | None = None,
+        store_output: str | None = None,
+        webhook_url: str | None = None,
+        idempotency_key: str | None = None,
+        async_: bool | None = None,
+        upload: UploadOptions | None = None,
+        inline_images: bool = False,
+    ) -> dict[str, Any]: ...
+
+    @overload
+    async def run(
+        self,
+        model: str,
+        input: Mapping[str, Any],
+        *,
+        wait: Literal[False],
+        on_progress: Callable[[TaskProgress], None] | None = None,
+        timeout: float | None = None,
+        mode: Mode | None = None,
+        store_output: str | None = None,
+        webhook_url: str | None = None,
+        idempotency_key: str | None = None,
+        async_: bool | None = None,
+        upload: UploadOptions | None = None,
+        inline_images: bool = False,
+    ) -> dict[str, Any] | AsyncAccepted: ...
+
+    @overload
+    async def run(
+        self,
+        model: str,
+        input: Mapping[str, Any],
+        *,
+        wait: bool,
+        on_progress: Callable[[TaskProgress], None] | None = None,
+        timeout: float | None = None,
+        mode: Mode | None = None,
+        store_output: str | None = None,
+        webhook_url: str | None = None,
+        idempotency_key: str | None = None,
+        async_: bool | None = None,
+        upload: UploadOptions | None = None,
+        inline_images: bool = False,
+    ) -> dict[str, Any] | AsyncAccepted: ...
+
+    async def run(
+        self,
+        model: str,
+        input: Mapping[str, Any],
+        *,
+        wait: bool = True,
+        on_progress: Callable[[TaskProgress], None] | None = None,
+        timeout: float | None = None,
+        mode: Mode | None = None,
+        store_output: str | None = None,
+        webhook_url: str | None = None,
+        idempotency_key: str | None = None,
+        async_: bool | None = None,
+        upload: UploadOptions | None = None,
+        inline_images: bool = False,
+    ) -> dict[str, Any] | AsyncAccepted:
+        """Runs any model: resolves its route through ``models.get``, submits, and (by default) waits for the result.
+
+        A sync route returns its body; an async route (or ``async_=True``) waits and returns the task's ``result``;
+        ``wait=False`` returns the ``202`` envelope instead (narrow with ``is_accepted``).
+        """
+        return await run(
+            self,
+            model,
+            input,
+            wait=wait,
+            on_progress=on_progress,
+            timeout=timeout,
+            mode=mode,
+            store_output=store_output,
+            webhook_url=webhook_url,
+            idempotency_key=idempotency_key,
+            async_=async_,
+            upload=upload,
+            inline_images=inline_images,
+        )
+
+    async def estimate_cost(self, model: str, usage: UsageInput) -> CostEstimate:
+        """Client-side estimate from ``/v2/pricing`` rows. An estimate, never an invoice."""
+        return await estimate_cost(self, model, usage)
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = _UNSET,
+        query: Query | None = None,
+        headers: Mapping[str, str] | None = None,
+        content: RawBody | None = None,
+        content_type: str | None = None,
+        timeout: float | None = None,
+        idempotency_key: str | None = None,
+        no_auth: bool = False,
+    ) -> Any:
+        """Escape hatch: any route, typed errors and the retry policy included. Returns the parsed body."""
+        res = await self._http.request(
+            method,
+            path,
+            json=json,
+            query=query,
+            headers=headers,
+            content=content,
+            content_type=content_type,
+            timeout=timeout,
+            idempotency_key=idempotency_key,
+            no_auth=no_auth,
+        )
+        return res.data
+
+    async def aclose(self) -> None:
+        """Closes the HTTP connection pool (not a ``http_client`` you passed in)."""
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncRelay:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()

relaygpu/_async/estimate.py

@@ -0,0 +1,18 @@
+"""``estimate_cost`` (port of src/estimate.ts): the one network call; the math lives in ``relaygpu/_estimate.py``."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .._estimate import estimate
+from ..types import CostEstimate, UsageInput
+
+if TYPE_CHECKING:
+    from .client import AsyncRelay
+
+
+async def estimate_cost(relay: AsyncRelay, model: str, usage: UsageInput) -> CostEstimate:
+    """Estimates the USD cost of a call from ``GET /v2/pricing`` (the only network call). An estimate, never an
+    invoice: the bill comes from provider-reported usage and any custom-tier pricing your account carries. Raises a
+    ``RelayError`` for a model with no row in the mode, an unknown billing type or an unoffered storage SKU."""
+    return estimate(await relay.pricing.get(), model, usage)