ads_dev 1.0.0__py3-none-any.whl

ads_dev/__init__.py

@@ -0,0 +1,40 @@
+from ._async.client import AsyncSandstorm
+from ._core import GenerationFailed, SandstormError, is_finished, verify_webhook
+from ._sync.client import Sandstorm
+from .types import (
+    Ad,
+    AdSummary,
+    Advertiser,
+    Asset,
+    Brand,
+    Character,
+    Generation,
+    GenerationEvent,
+    LibraryAsset,
+    Model,
+    Offer,
+    OfferSummary,
+    Voice,
+)
+
+__all__ = [
+    "Ad",
+    "AdSummary",
+    "Advertiser",
+    "Asset",
+    "AsyncSandstorm",
+    "Brand",
+    "Character",
+    "Generation",
+    "GenerationEvent",
+    "GenerationFailed",
+    "LibraryAsset",
+    "Model",
+    "Offer",
+    "OfferSummary",
+    "Sandstorm",
+    "SandstormError",
+    "Voice",
+    "is_finished",
+    "verify_webhook",
+]

ads_dev/_async/client.py

@@ -0,0 +1,335 @@
+from __future__ import annotations
+
+import math
+import uuid
+from collections.abc import AsyncIterator, Mapping
+from typing import Any, Generic, TypeVar
+from urllib.parse import quote
+
+import anyio
+import httpx
+from pydantic import BaseModel
+
+from .._core import (
+    LONGEST_WAIT_S,
+    RETRYABLE,
+    RUN_TIMEOUT_S,
+    GenerationFailed,
+    delay_of,
+    headers_of,
+    is_finished,
+    query_of,
+    refusal_of,
+    settings,
+)
+from ..types import (
+    Ad,
+    AdList,
+    AdSummary,
+    Advertiser,
+    AdvertiserList,
+    Asset,
+    Brand,
+    Character,
+    CharacterList,
+    Generation,
+    GenerationList,
+    LibraryAsset,
+    LibraryAssetList,
+    Model,
+    ModelList,
+    Offer,
+    OfferList,
+    OfferSummary,
+    Voice,
+    VoiceList,
+    WebhookSecret,
+)
+
+Item = TypeVar("Item", bound=BaseModel)
+
+Answer = TypeVar("Answer", bound=BaseModel)
+
+
+class Page(Generic[Item]):
+    def __init__(self, client: AsyncSandstorm, path: str, params: Mapping[str, Any], shape: type[BaseModel]) -> None:
+        self._client = client
+        self._path = path
+        self._params = params
+        self._shape = shape
+
+    async def first_page(self) -> Any:
+        return await self._client._send("GET", self._path, self._shape, query=self._params)
+
+    def __aiter__(self) -> AsyncIterator[Item]:
+        return self._items()
+
+    async def _items(self) -> AsyncIterator[Item]:
+        cursor: str | None = None
+        while True:
+            page = await self._client._send("GET", self._path, self._shape, query={**self._params, "cursor": cursor})
+            for item in page.data:
+                yield item
+            if not page.has_more or page.next_cursor is None:
+                return
+            cursor = page.next_cursor
+
+
+class Generations:
+    def __init__(self, client: AsyncSandstorm) -> None:
+        self._client = client
+
+    async def create(
+        self,
+        model: str,
+        input: Mapping[str, Any],
+        *,
+        webhook_url: str | None = None,
+        wait: int | None = None,
+        idempotency_key: str | None = None,
+    ) -> Generation:
+        body = {"model": model, "input": dict(input), **({"webhook_url": webhook_url} if webhook_url else {})}
+        return await self._client._send(
+            "POST", "/v1/generations", Generation, body=body, wait=wait, idempotency_key=idempotency_key or str(uuid.uuid4())
+        )
+
+    async def get(self, id: str, *, wait: int | None = None) -> Generation:
+        return await self._client._send("GET", f"/v1/generations/{quote(id, safe='')}", Generation, wait=wait)
+
+    async def wait(self, id: str, *, timeout: float = RUN_TIMEOUT_S) -> Generation:
+        deadline = anyio.current_time() + timeout
+        while True:
+            left = math.ceil(deadline - anyio.current_time())
+            generation = await self.get(id, wait=max(1, min(LONGEST_WAIT_S, left)))
+            if is_finished(generation):
+                return generation
+            if left <= 0:
+                raise TimeoutError(f"{id} did not finish within {timeout} s; it is still {generation.status}")
+
+    async def run(
+        self,
+        model: str,
+        input: Mapping[str, Any],
+        *,
+        webhook_url: str | None = None,
+        idempotency_key: str | None = None,
+        timeout: float = RUN_TIMEOUT_S,
+    ) -> Generation:
+        created = await self.create(model, input, webhook_url=webhook_url, wait=LONGEST_WAIT_S, idempotency_key=idempotency_key)
+        generation = created if is_finished(created) else await self.wait(created.id, timeout=timeout)
+        if generation.status != "succeeded":
+            raise GenerationFailed(generation)
+        return generation
+
+    async def cancel(self, id: str) -> Generation:
+        return await self._client._send("POST", f"/v1/generations/{quote(id, safe='')}/cancel", Generation)
+
+    def list(self, *, status: str | None = None, model: str | None = None, limit: int | None = None) -> Page[Generation]:
+        return Page(self._client, "/v1/generations", {"status": status, "model": model, "limit": limit}, GenerationList)
+
+
+class Models:
+    def __init__(self, client: AsyncSandstorm) -> None:
+        self._client = client
+
+    def list(self, *, type: str | None = None) -> Page[Model]:
+        return Page(self._client, "/v1/models", {"type": type}, ModelList)
+
+    async def get(self, id: str) -> Model:
+        return await self._client._send("GET", f"/v1/models/{quote(id, safe='')}", Model)
+
+
+class Assets:
+    def __init__(self, client: AsyncSandstorm) -> None:
+        self._client = client
+
+    def list(
+        self,
+        *,
+        type: str | None = None,
+        offer: str | None = None,
+        liked: bool | None = None,
+        archived: bool | None = None,
+        limit: int | None = None,
+    ) -> Page[LibraryAsset]:
+        return Page(self._client, "/v1/assets", {"type": type, "offer": offer, "liked": liked, "archived": archived, "limit": limit}, LibraryAssetList)
+
+    async def get(self, id: str) -> Asset:
+        return await self._client._send("GET", f"/v1/assets/{quote(id, safe='')}", Asset)
+
+    async def import_url(self, url: str, *, name: str | None = None, idempotency_key: str | None = None) -> Asset:
+        body = {"url": url, **({"name": name} if name else {})}
+        return await self._client._send("POST", "/v1/assets", Asset, body=body, idempotency_key=idempotency_key or str(uuid.uuid4()))
+
+
+class Brands:
+    def __init__(self, client: AsyncSandstorm) -> None:
+        self._client = client
+
+    async def get(self) -> Brand:
+        return await self._client._send("GET", "/v1/brand", Brand)
+
+
+class Offers:
+    def __init__(self, client: AsyncSandstorm) -> None:
+        self._client = client
+
+    def list(self, *, query: str | None = None, limit: int | None = None) -> Page[OfferSummary]:
+        return Page(self._client, "/v1/offers", {"query": query, "limit": limit}, OfferList)
+
+    async def get(self, id: str) -> Offer:
+        return await self._client._send("GET", f"/v1/offers/{quote(id, safe='')}", Offer)
+
+
+class Characters:
+    def __init__(self, client: AsyncSandstorm) -> None:
+        self._client = client
+
+    def list(self, *, query: str | None = None, kind: str | None = None) -> Page[Character]:
+        return Page(self._client, "/v1/characters", {"query": query, "kind": kind}, CharacterList)
+
+
+class Voices:
+    def __init__(self, client: AsyncSandstorm) -> None:
+        self._client = client
+
+    def list(
+        self,
+        *,
+        query: str | None = None,
+        gender: str | None = None,
+        age: str | None = None,
+        accent: str | None = None,
+        use_case: str | None = None,
+        limit: int | None = None,
+    ) -> Page[Voice]:
+        params = {"query": query, "gender": gender, "age": age, "accent": accent, "use_case": use_case, "limit": limit}
+        return Page(self._client, "/v1/voices", params, VoiceList)
+
+
+class Advertisers:
+    def __init__(self, client: AsyncSandstorm) -> None:
+        self._client = client
+
+    def list(self, *, query: str, limit: int | None = None) -> Page[Advertiser]:
+        return Page(self._client, "/v1/advertisers", {"query": query, "limit": limit}, AdvertiserList)
+
+
+class Ads:
+    def __init__(self, client: AsyncSandstorm) -> None:
+        self._client = client
+
+    def list(
+        self,
+        *,
+        query: str | None = None,
+        advertiser: str | None = None,
+        platform: str | None = None,
+        format: str | None = None,
+        status: str | None = None,
+        min_active_days: int | None = None,
+        started_after: str | None = None,
+        started_before: str | None = None,
+        limit: int | None = None,
+    ) -> Page[AdSummary]:
+        params = {
+            "query": query,
+            "advertiser": advertiser,
+            "platform": platform,
+            "format": format,
+            "status": status,
+            "min_active_days": min_active_days,
+            "started_after": started_after,
+            "started_before": started_before,
+            "limit": limit,
+        }
+        return Page(self._client, "/v1/ads", params, AdList)
+
+    async def get(self, id: str) -> Ad:
+        return await self._client._send("GET", f"/v1/ads/{quote(id, safe='')}", Ad)
+
+
+class Webhooks:
+    def __init__(self, client: AsyncSandstorm) -> None:
+        self._client = client
+
+    async def secret(self) -> str:
+        return (await self._client._send("GET", "/v1/webhooks/secret", WebhookSecret)).secret
+
+
+class AsyncSandstorm:
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        brand: str | None = None,
+        max_retries: int = 2,
+        timeout: float = 60,
+        http: httpx.AsyncClient | None = None,
+    ) -> None:
+        key, url = settings(api_key, base_url)
+        self._base_url = url
+        self._headers = headers_of(key, brand)
+        self._max_retries = max_retries
+        self._timeout = timeout
+        self._http = http or httpx.AsyncClient()
+        self.generations = Generations(self)
+        self.models = Models(self)
+        self.assets = Assets(self)
+        self.brand = Brands(self)
+        self.offers = Offers(self)
+        self.characters = Characters(self)
+        self.voices = Voices(self)
+        self.advertisers = Advertisers(self)
+        self.ads = Ads(self)
+        self.webhooks = Webhooks(self)
+
+    async def __aenter__(self) -> AsyncSandstorm:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def _send(
+        self,
+        method: str,
+        path: str,
+        shape: type[Answer],
+        *,
+        query: Mapping[str, Any] | None = None,
+        body: Mapping[str, Any] | None = None,
+        wait: int | None = None,
+        idempotency_key: str | None = None,
+    ) -> Answer:
+        headers = {
+            **self._headers,
+            **({"prefer": f"wait={wait}"} if wait is not None else {}),
+            **({"idempotency-key": idempotency_key} if idempotency_key is not None else {}),
+        }
+        attempt = 0
+        while True:
+            try:
+                response = await self._http.request(
+                    method,
+                    self._base_url + path,
+                    params=query_of(query or {}),
+                    json=body,
+                    headers=headers,
+                    timeout=self._timeout + (wait or 0),
+                )
+            except httpx.TransportError:
+                if attempt >= self._max_retries:
+                    raise
+                await anyio.sleep(delay_of(attempt, None))
+                attempt += 1
+                continue
+            if response.is_success:
+                return shape.model_validate(response.json())
+            if response.status_code not in RETRYABLE or attempt >= self._max_retries:
+                raise refusal_of(response)
+            await anyio.sleep(delay_of(attempt, response))
+            attempt += 1

ads_dev/_core.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+import random
+import re
+import time
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from .types import Generation, GenerationEvent
+
+BASE_URL = "https://ads.dev"
+
+LONGEST_WAIT_S = 60
+
+RUN_TIMEOUT_S = 60 * 60
+
+RETRYABLE = frozenset({408, 429, 500, 502, 503, 504})
+
+FINISHED = frozenset({"succeeded", "failed", "canceled"})
+
+MISSING_KEY = (
+    "Pass api_key or set SANDSTORM_API_KEY. To make a key: "
+    "curl -fsSL https://ads.dev/login.mjs -o sandstorm-login.mjs && node sandstorm-login.mjs"
+)
+
+
+class SandstormError(Exception):
+    def __init__(self, status: int, refusal: Mapping[str, Any]) -> None:
+        super().__init__(refusal.get("message", ""))
+        self.status = status
+        self.type: str = refusal.get("type", "api_error")
+        self.code: str = refusal.get("code", "unreadable")
+        self.param: str | None = refusal.get("param")
+        self.request_id: str | None = refusal.get("request_id")
+
+
+class GenerationFailed(Exception):
+    def __init__(self, generation: Generation) -> None:
+        super().__init__(generation.error.message if generation.error else f"{generation.id} was {generation.status}")
+        self.generation = generation
+
+
+def is_finished(generation: Generation) -> bool:
+    return generation.status in FINISHED
+
+
+def settings(api_key: str | None, base_url: str | None) -> tuple[str, str]:
+    key = api_key or os.environ.get("SANDSTORM_API_KEY")
+    if not key:
+        raise ValueError(MISSING_KEY)
+    return key, (base_url or os.environ.get("SANDSTORM_API_URL") or BASE_URL).rstrip("/")
+
+
+def headers_of(api_key: str, brand: str | None) -> dict[str, str]:
+    return {"authorization": f"Bearer {api_key}", **({"sandstorm-brand": brand} if brand else {})}
+
+
+def query_of(params: Mapping[str, Any]) -> dict[str, str]:
+    return {name: ("true" if value is True else "false" if value is False else str(value)) for name, value in params.items() if value is not None}
+
+
+def refusal_of(response: httpx.Response) -> SandstormError:
+    try:
+        return SandstormError(response.status_code, response.json()["error"])
+    except (ValueError, KeyError, TypeError):
+        return SandstormError(
+            response.status_code,
+            {"message": response.text or response.reason_phrase, "request_id": response.headers.get("sandstorm-request-id")},
+        )
+
+
+def delay_of(attempt: int, response: httpx.Response | None) -> float:
+    try:
+        after = float(response.headers["retry-after"]) if response is not None else 0
+    except (KeyError, ValueError):
+        after = 0
+    return after if after > 0 else min(8.0, 0.5 * 2**attempt) * random.uniform(0.75, 1.25)
+
+
+SIGNATURE = re.compile(r"^[0-9a-f]{64}$")
+
+
+def verify_webhook(secret: str, body: str | bytes, signature: str | None, *, tolerance_seconds: float = 300, now: float | None = None) -> GenerationEvent:
+    text = body.decode() if isinstance(body, bytes) else body
+    parts = dict(part.split("=", 1) for part in (signature or "").split(",") if "=" in part)
+    given = parts.get("v1", "")
+    if not parts.get("t", "").isdigit() or not SIGNATURE.match(given):
+        raise ValueError("The Sandstorm-Signature header is missing or malformed.")
+    timestamp = int(parts["t"])
+    if abs((time.time() if now is None else now) - timestamp) > tolerance_seconds:
+        raise ValueError("The webhook is older than the tolerance; refuse it as a possible replay.")
+    expected = hmac.new(secret.encode(), f"{timestamp}.{text}".encode(), hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(expected, given):
+        raise ValueError("The webhook signature does not match; it was not sent by Sandstorm with this secret.")
+    return GenerationEvent.model_validate(json.loads(text))