storerouter 0.1.0__py3-none-any.whl

storerouter/__init__.py

@@ -0,0 +1,90 @@
+"""StoreRouter Python SDK: structured product data from real merchant catalogs.
+
+Look up any product URL as normalized JSON, search products across stores,
+and discover brands and stores::
+
+    from storerouter import StoreRouter
+
+    with StoreRouter() as client:  # reads STOREROUTER_API_KEY
+        product = client.lookup_product("https://www.allbirds.com/products/mens-tree-runners").product
+        page = client.search_products(q="linen shirt", stores=["everlane.com"], limit=5)
+
+:class:`AsyncStoreRouter` has the same methods as coroutines.
+"""
+
+import importlib.metadata as _metadata
+
+from octogen_ai_sdk import (
+    Facet,
+    MissingAPIKeyError,
+    RequestContext,
+    RequestContextDefaults,
+    SearchFacet,
+)
+from octogen_ai_sdk import OctogenAPIError as APIError
+from octogen_ai_sdk import OctogenAuthenticationError as AuthenticationError
+from octogen_ai_sdk import OctogenConnectionError as APIConnectionError
+from octogen_ai_sdk import OctogenError as StoreRouterError
+from octogen_ai_sdk import OctogenForbiddenError as PermissionDeniedError
+from octogen_ai_sdk import OctogenInsufficientCreditError as InsufficientCreditError
+from octogen_ai_sdk import OctogenNotFoundError as NotFoundError
+from octogen_ai_sdk import OctogenRateLimitError as RateLimitError
+from octogen_ai_sdk import OctogenServerError as InternalServerError
+from octogen_ai_sdk import OctogenTimeoutError as APITimeoutError
+from octogen_ai_sdk import OctogenValidationError as ValidationError
+
+from storerouter import models
+from storerouter._client import (
+    API_KEY_ENV_VAR,
+    BASE_URL_ENV_VAR,
+    DEFAULT_BASE_URL,
+    AsyncStoreRouter,
+    LookupResult,
+    StoreRouter,
+)
+from storerouter._retry import RetryTransport
+from storerouter.models import (
+    Product,
+    ProductListItem,
+    ProductLookupResponse,
+    ProductSearchPage,
+    ProductVariant,
+)
+
+try:
+    __version__ = _metadata.version("storerouter")
+except _metadata.PackageNotFoundError:  # pragma: no cover - source checkout
+    __version__ = "0.0.0"
+
+__all__ = [
+    "API_KEY_ENV_VAR",
+    "BASE_URL_ENV_VAR",
+    "DEFAULT_BASE_URL",
+    "APIConnectionError",
+    "APIError",
+    "APITimeoutError",
+    "AsyncStoreRouter",
+    "AuthenticationError",
+    "Facet",
+    "InsufficientCreditError",
+    "InternalServerError",
+    "LookupResult",
+    "MissingAPIKeyError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "Product",
+    "ProductListItem",
+    "ProductLookupResponse",
+    "ProductSearchPage",
+    "ProductVariant",
+    "RateLimitError",
+    "RequestContext",
+    "RequestContextDefaults",
+    "RetryTransport",
+    "SearchFacet",
+    "StoreRouter",
+    "StoreRouterError",
+    "ValidationError",
+    "__version__",
+    "models",
+]

storerouter/_client.py

@@ -0,0 +1,348 @@
+"""The async :class:`AsyncStoreRouter` and blocking :class:`StoreRouter` clients."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import os
+import threading
+from collections.abc import Callable, Coroutine, Sequence
+from concurrent.futures import Future
+from dataclasses import dataclass
+from types import TracebackType
+from typing import Any, Concatenate, Generic, ParamSpec, Self, TypeVar, overload
+
+import httpx
+from octogen_ai_sdk import (
+    MissingAPIKeyError,
+    OctogenAuthenticationError,
+    OctogenClient,
+    OctogenError,
+    OctogenForbiddenError,
+    OctogenInsufficientCreditError,
+    RequestContextDefaults,
+)
+from octogen_ai_sdk.models import (
+    MerchantProductUrlLookupResponse,
+    MerchantProductView,
+    ProductLookupCachePolicy,
+    ProductLookupMatchMode,
+    ProductLookupResolutionMode,
+)
+
+from storerouter._retry import DEFAULT_MAX_RETRIES, RetryTransport
+
+#: The variable the StoreRouter docs, CLI and integrations name. Prefer it.
+API_KEY_ENV_VAR = "STOREROUTER_API_KEY"
+#: Read when ``STOREROUTER_API_KEY`` is unset: the Octogen SDKs' own name.
+FALLBACK_API_KEY_ENV_VAR = "OCTOGEN_PLATFORM_API_KEY"
+BASE_URL_ENV_VAR = "STOREROUTER_BASE_URL"
+DEFAULT_BASE_URL = "https://api.storerouter.ai/v1"
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_LOOKUP_CONCURRENCY = 8
+
+#: Sent as the request context's ``application`` unless you pass your own
+#: ``default_context``, so StoreRouter can tell this SDK's traffic apart.
+APPLICATION = "storerouter-python"
+
+#: Errors every other URL in a batch would hit too. They stop the batch
+#: instead of being recorded once per URL.
+_BATCH_FATAL_ERRORS = (
+    OctogenAuthenticationError,
+    OctogenForbiddenError,
+    OctogenInsufficientCreditError,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class LookupResult:
+    """One URL's outcome in :meth:`AsyncStoreRouter.lookup_products`.
+
+    Exactly one of ``response`` and ``error`` is set.
+    """
+
+    url: str
+    response: MerchantProductUrlLookupResponse | None = None
+    error: OctogenError | None = None
+
+    @property
+    def ok(self) -> bool:
+        return self.error is None
+
+    @property
+    def product(self) -> MerchantProductView | None:
+        """The normalized product, or ``None`` when the lookup failed."""
+        return self.response.product if self.response is not None else None
+
+
+class AsyncStoreRouter(OctogenClient):
+    """Async client for the StoreRouter API.
+
+    The API key comes from ``api_key``, else ``STOREROUTER_API_KEY``, else
+    ``OCTOGEN_PLATFORM_API_KEY``. The base URL comes from ``base_url``, else
+    ``STOREROUTER_BASE_URL``, else ``https://api.storerouter.ai/v1``.
+
+    429 and 5xx responses and failed connections are retried up to
+    ``max_retries`` times, honoring ``Retry-After``. Pass ``http_client`` to
+    bring your own ``httpx.AsyncClient``; it is used as is, without retries
+    unless its transport is a :class:`storerouter.RetryTransport`.
+
+    Every method of ``octogen_ai_sdk.OctogenClient`` is available; this class
+    adds :meth:`lookup_products` for batches of URLs.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.AsyncClient | None = None,
+        default_context: RequestContextDefaults | None = None,
+    ) -> None:
+        resolved_key = (
+            api_key
+            or os.environ.get(API_KEY_ENV_VAR)
+            or os.environ.get(FALLBACK_API_KEY_ENV_VAR)
+        )
+        if not resolved_key:
+            raise MissingAPIKeyError(
+                f"StoreRouter API key required. Set {API_KEY_ENV_VAR} or pass "
+                "api_key. Get one at https://dev.storerouter.ai."
+            )
+        owns_client = http_client is None
+        if http_client is None:
+            http_client = httpx.AsyncClient(
+                timeout=timeout,
+                transport=RetryTransport(max_retries=max_retries),
+            )
+        super().__init__(
+            api_key=resolved_key,
+            base_url=(base_url or os.environ.get(BASE_URL_ENV_VAR) or DEFAULT_BASE_URL),
+            timeout=timeout,
+            http_client=http_client,
+            default_context=(
+                default_context
+                if default_context is not None
+                else RequestContextDefaults(application=APPLICATION)
+            ),
+        )
+        # The base class only closes a client it created itself.
+        self._owns_client = owns_client
+
+    async def lookup_products(
+        self,
+        urls: Sequence[str],
+        *,
+        max_concurrency: int = DEFAULT_LOOKUP_CONCURRENCY,
+        match_mode: ProductLookupMatchMode | str | None = None,
+        resolution_mode: ProductLookupResolutionMode | str | None = None,
+        on_demand_cache_policy: ProductLookupCachePolicy | str | None = None,
+        timeout: float | httpx.Timeout | None = None,
+    ) -> list[LookupResult]:
+        """Look up many product URLs concurrently, one result per URL, in order.
+
+        A URL that fails (not found, invalid, still rate limited after
+        retries) gets a :class:`LookupResult` with ``error`` set, and the rest
+        of the batch carries on. Authentication, permission and credit errors
+        apply to every URL alike, so they are raised and stop the batch.
+
+        Each URL is one ``POST /v1/products/lookup`` call; only successful
+        lookups are billed.
+        """
+        if isinstance(urls, str):
+            raise TypeError("lookup_products() takes a sequence of URLs, not a str")
+        if max_concurrency < 1:
+            raise ValueError("max_concurrency must be >= 1")
+        semaphore = asyncio.Semaphore(max_concurrency)
+
+        async def one(url: str) -> LookupResult:
+            async with semaphore:
+                try:
+                    response = await self.lookup_product(
+                        url,
+                        match_mode=match_mode,
+                        resolution_mode=resolution_mode,
+                        on_demand_cache_policy=on_demand_cache_policy,
+                        timeout=timeout,
+                    )
+                except _BATCH_FATAL_ERRORS:
+                    raise
+                except OctogenError as exc:
+                    return LookupResult(url=url, error=exc)
+                return LookupResult(url=url, response=response)
+
+        try:
+            async with asyncio.TaskGroup() as group:
+                tasks = [group.create_task(one(url)) for url in urls]
+        except* _BATCH_FATAL_ERRORS as group_error:
+            # Raise the first fatal error itself, not an ExceptionGroup.
+            raise group_error.exceptions[0] from None
+        return [task.result() for task in tasks]
+
+
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+
+
+class _Blocking(Generic[_P, _R]):
+    """A blocking twin of an :class:`AsyncStoreRouter` method, same signature.
+
+    A descriptor rather than a plain wrapper function so type checkers bind
+    ``self`` and show the async method's parameters on the sync client.
+    """
+
+    def __init__(
+        self,
+        method: Callable[Concatenate[AsyncStoreRouter, _P], Coroutine[Any, Any, _R]],
+    ) -> None:
+        self._name = ""
+        self.__doc__ = method.__doc__
+        # The async signature without ``self``, for help() and Jupyter.
+        signature = inspect.signature(method)
+        self._signature = signature.replace(
+            parameters=list(signature.parameters.values())[1:]
+        )
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        self._name = name
+
+    @overload
+    def __get__(self, instance: None, owner: type | None = None) -> Self: ...
+
+    @overload
+    def __get__(
+        self, instance: StoreRouter, owner: type | None = None
+    ) -> Callable[_P, _R]: ...
+
+    def __get__(
+        self, instance: StoreRouter | None, owner: type | None = None
+    ) -> Self | Callable[_P, _R]:
+        if instance is None:
+            return self
+        name = self._name
+
+        def call(*args: _P.args, **kwargs: _P.kwargs) -> _R:
+            return instance._run(getattr(instance._client, name)(*args, **kwargs))
+
+        call.__name__ = name
+        call.__qualname__ = f"StoreRouter.{name}"
+        call.__doc__ = self.__doc__
+        call.__dict__["__signature__"] = self._signature
+        return call
+
+
+class StoreRouter:
+    """Blocking client for the StoreRouter API.
+
+    Same constructor and methods as :class:`AsyncStoreRouter`, without
+    ``await``. It runs the async client on a private event-loop thread, so it
+    works anywhere, including inside Jupyter or a running event loop. Close it
+    with :meth:`close` or use it as a context manager.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_context: RequestContextDefaults | None = None,
+    ) -> None:
+        # Fail on a missing key here, before a thread exists to clean up.
+        self._client = AsyncStoreRouter(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            default_context=default_context,
+        )
+        self._loop = asyncio.new_event_loop()
+        self._thread = threading.Thread(
+            target=self._loop.run_forever, name="storerouter-client", daemon=True
+        )
+        self._thread.start()
+        self._closed = False
+
+    def _run(self, coroutine: Coroutine[Any, Any, _R]) -> _R:
+        if self._closed:
+            coroutine.close()
+            raise RuntimeError("StoreRouter client is closed")
+        future: Future[_R] = asyncio.run_coroutine_threadsafe(coroutine, self._loop)
+        return future.result()
+
+    def close(self) -> None:
+        """Close connections and stop the client's event-loop thread."""
+        if self._closed:
+            return
+        try:
+            self._run(self._client.aclose())
+        finally:
+            self._closed = True
+            self._loop.call_soon_threadsafe(self._loop.stop)
+            self._thread.join()
+            self._loop.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    # Products
+    lookup_product = _Blocking(AsyncStoreRouter.lookup_product)
+    lookup_products = _Blocking(AsyncStoreRouter.lookup_products)
+    lookup_product_markdown = _Blocking(AsyncStoreRouter.lookup_product_markdown)
+    parse_product_alias = _Blocking(AsyncStoreRouter.parse_product_alias)
+    retrieve_product = _Blocking(AsyncStoreRouter.retrieve_product)
+    retrieve_products = _Blocking(AsyncStoreRouter.retrieve_products)
+    resolve_product_from_html = _Blocking(AsyncStoreRouter.resolve_product_from_html)
+    search_products = _Blocking(AsyncStoreRouter.search_products)
+    count_product_facets = _Blocking(AsyncStoreRouter.count_product_facets)
+    more_like_this_products = _Blocking(AsyncStoreRouter.more_like_this_products)
+
+    # Stores
+    get_store = _Blocking(AsyncStoreRouter.get_store)
+    search_stores = _Blocking(AsyncStoreRouter.search_stores)
+    search_similar_stores = _Blocking(AsyncStoreRouter.search_similar_stores)
+
+    # Brands
+    search_brands = _Blocking(AsyncStoreRouter.search_brands)
+    search_brand_prefix = _Blocking(AsyncStoreRouter.search_brand_prefix)
+    search_similar_brands = _Blocking(AsyncStoreRouter.search_similar_brands)
+    get_brand_directory = _Blocking(AsyncStoreRouter.get_brand_directory)
+    get_brand_details = _Blocking(AsyncStoreRouter.get_brand_details)
+    get_brand_coverage = _Blocking(AsyncStoreRouter.get_brand_coverage)
+    browse_brand_products = _Blocking(AsyncStoreRouter.browse_brand_products)
+    get_brand_top_categories = _Blocking(AsyncStoreRouter.get_brand_top_categories)
+
+    # Taxonomy
+    list_taxonomy_categories = _Blocking(AsyncStoreRouter.list_taxonomy_categories)
+    list_taxonomy_attributes = _Blocking(AsyncStoreRouter.list_taxonomy_attributes)
+    list_taxonomy_attribute_values = _Blocking(
+        AsyncStoreRouter.list_taxonomy_attribute_values
+    )
+
+    # Account and coverage URL lists
+    get_me = _Blocking(AsyncStoreRouter.get_me)
+    create_coverage_url_list = _Blocking(AsyncStoreRouter.create_coverage_url_list)
+    list_coverage_url_lists = _Blocking(AsyncStoreRouter.list_coverage_url_lists)
+    get_coverage_url_list = _Blocking(AsyncStoreRouter.get_coverage_url_list)
+    delete_coverage_url_list = _Blocking(AsyncStoreRouter.delete_coverage_url_list)
+    add_coverage_url_list_urls = _Blocking(AsyncStoreRouter.add_coverage_url_list_urls)
+    remove_coverage_url_list_urls = _Blocking(
+        AsyncStoreRouter.remove_coverage_url_list_urls
+    )
+    check_coverage_url_list_urls = _Blocking(
+        AsyncStoreRouter.check_coverage_url_list_urls
+    )
+    list_coverage_url_list_urls = _Blocking(
+        AsyncStoreRouter.list_coverage_url_list_urls
+    )

storerouter/_retry.py

@@ -0,0 +1,92 @@
+"""Retry 429 and 5xx responses at the transport, under every client method."""
+
+from __future__ import annotations
+
+import asyncio
+import random
+from collections.abc import Awaitable, Callable
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
+
+import httpx
+
+#: Statuses worth another attempt: rate limited, or a server-side failure.
+RETRY_STATUSES = frozenset({429, 500, 502, 503, 504})
+
+DEFAULT_MAX_RETRIES = 2
+_BACKOFF_BASE = 0.5
+_BACKOFF_CAP = 8.0
+#: A ``Retry-After`` longer than this is the server asking us to stop, not to
+#: wait, so the response is returned (and raised) instead of slept on.
+_RETRY_AFTER_CAP = 60.0
+
+
+class RetryTransport(httpx.AsyncBaseTransport):
+    """Wrap a transport and retry 429/5xx responses and failed connections.
+
+    Waits ``Retry-After`` when the server sends one, else exponential backoff
+    with full jitter. Only connection failures are retried, never read
+    timeouts: a request that timed out mid-flight may have done its (billed)
+    work, and an on-demand lookup can legitimately be slow.
+    """
+
+    def __init__(
+        self,
+        inner: httpx.AsyncBaseTransport | None = None,
+        *,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+    ) -> None:
+        if max_retries < 0:
+            raise ValueError("max_retries must be >= 0")
+        self._inner = inner or httpx.AsyncHTTPTransport()
+        self._max_retries = max_retries
+        self._sleep = sleep
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        attempt = 0
+        while True:
+            try:
+                response = await self._inner.handle_async_request(request)
+            except (httpx.ConnectError, httpx.ConnectTimeout):
+                if attempt >= self._max_retries:
+                    raise
+                delay = _backoff(attempt)
+            else:
+                if (
+                    response.status_code not in RETRY_STATUSES
+                    or attempt >= self._max_retries
+                ):
+                    return response
+                retry_after = _retry_after_seconds(response.headers.get("Retry-After"))
+                if retry_after is not None and retry_after > _RETRY_AFTER_CAP:
+                    return response
+                delay = retry_after if retry_after is not None else _backoff(attempt)
+                await response.aclose()
+            attempt += 1
+            await self._sleep(delay)
+
+    async def aclose(self) -> None:
+        await self._inner.aclose()
+
+
+def _backoff(attempt: int) -> float:
+    return random.uniform(0, min(_BACKOFF_CAP, _BACKOFF_BASE * 2**attempt))
+
+
+def _retry_after_seconds(value: str | None) -> float | None:
+    """``Retry-After`` as seconds: delta-seconds or an HTTP date."""
+    if not value:
+        return None
+    value = value.strip()
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        pass
+    try:
+        when = parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=UTC)
+    return max(0.0, (when - datetime.now(UTC)).total_seconds())

storerouter/models.py

@@ -0,0 +1,25 @@
+"""Every request and response model, re-exported from ``octogen_ai_sdk.models``.
+
+The friendlier names below are aliases of the same classes:
+
+- :data:`Product` -- the full normalized product a lookup returns.
+- :data:`ProductListItem` -- one search, brand-browse or more-like-this result.
+- :data:`ProductLookupResponse` -- a lookup's envelope: ``product`` plus how
+  it was resolved.
+- :data:`ProductSearchPage` -- one page of search results.
+"""
+
+from octogen_ai_sdk.models import *  # noqa: F403
+from octogen_ai_sdk.models import (
+    MerchantProductListItem,
+    MerchantProductUrlLookupResponse,
+    MerchantProductView,
+    MerchantVariantView,
+    ProgrammaticProductSearchPage,
+)
+
+Product = MerchantProductView
+ProductVariant = MerchantVariantView
+ProductListItem = MerchantProductListItem
+ProductLookupResponse = MerchantProductUrlLookupResponse
+ProductSearchPage = ProgrammaticProductSearchPage

storerouter-0.1.0.dist-info/METADATA

@@ -0,0 +1,391 @@
+Metadata-Version: 2.4
+Name: storerouter
+Version: 0.1.0
+Summary: Python SDK for StoreRouter: look up any product URL as structured JSON, search products across stores, and discover brands and stores
+Keywords: storerouter,ecommerce,product-data,product-search,product-lookup,web-scraping,structured-data,shopping,ai-agents,sdk
+Author: StoreRouter (Octogen AI)
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: octogen-ai-sdk>=0.17.0,<1.0.0
+Requires-Dist: pydantic>=2.0
+Requires-Python: >=3.11
+Project-URL: Homepage, https://storerouter.ai
+Project-URL: Documentation, https://storerouter.ai/docs
+Project-URL: Source, https://github.com/octogen-ai/octogen-dev/tree/main/sdks/storerouter-python
+Project-URL: Issues, https://github.com/octogen-ai/octogen-dev/issues
+Project-URL: Changelog, https://github.com/octogen-ai/octogen-dev/blob/main/sdks/storerouter-python/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# StoreRouter Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/storerouter)](https://pypi.org/project/storerouter/)
+[![Python](https://img.shields.io/pypi/pyversions/storerouter)](https://pypi.org/project/storerouter/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/octogen-ai/octogen-dev/blob/main/LICENSE)
+
+`storerouter` is the official Python SDK for [StoreRouter](https://storerouter.ai),
+an API that returns **structured e-commerce product data**. Use it to:
+
+- turn a product page URL into normalized JSON (title, brand, price, currency,
+  stock, variants, images, identifiers, taxonomy category and attributes);
+- search products across thousands of stores, or only the stores you name;
+- discover stores and brands.
+
+Every result uses **one product schema**, whatever store it came from, and
+every response is a typed Pydantic model. The package has sync and async
+clients, and it retries 429 and 5xx responses for you.
+
+```bash
+pip install storerouter
+```
+
+## Quickstart
+
+Get an API key at [dev.storerouter.ai](https://dev.storerouter.ai) and export it:
+
+```bash
+export STOREROUTER_API_KEY="sk_..."
+```
+
+```python
+from storerouter import StoreRouter
+
+client = StoreRouter()  # reads STOREROUTER_API_KEY
+
+result = client.lookup_product(
+    "https://www.allbirds.com/products/mens-runner-nz-jersey-light-grey-syrah"
+)
+product = result.product
+print(product.title, product.current_price, product.currency, product.in_stock)
+# Men's Runner NZ Jersey - Light Grey/Syrah (Blizzard Sole) 110.0 USD True
+```
+
+## Look up a product URL
+
+`lookup_product` takes the URL of any product page. It returns the indexed
+product when StoreRouter already has it, and otherwise extracts the page on
+demand. `result.source` says which: `"indexed"` or `"on_demand"`.
+
+```python
+result = client.lookup_product(
+    "https://www.allbirds.com/products/mens-runner-nz-jersey-light-grey-syrah"
+)
+print(result.product.model_dump_json(by_alias=True, exclude_none=True, indent=2))
+```
+
+This is real output, shortened. It shows one of 19 variants and some of the
+enrichment attributes. It leaves out the description, the long brand
+description, the image list, the store's own attributes and the request ID on
+image URLs.
+
+```json
+{
+  "uuid": "2b7a52cc-93e4-545a-999c-ed6f41f54ea6",
+  "catalogKey": "allbirds",
+  "productUrl": "https://www.allbirds.com/products/mens-runner-nz-jersey-light-grey-syrah",
+  "title": "Men's Runner NZ Jersey - Light Grey/Syrah (Blizzard Sole)",
+  "brand": { "name": "Allbirds", "slug": "allbirds", "url": "www.allbirds.com" },
+  "currentPrice": 110.0,
+  "originalPrice": 110.0,
+  "currency": "USD",
+  "inStock": true,
+  "availability": "InStock",
+  "primaryImage": {
+    "url": "https://cdn.shopify.com/s/files/1/1104/4168/files/A12548_26Q1_Runner-NZ-Jersey-Light-Grey-Syrah-Bizzard-Sole_PDP_LEFT.png?v=1774551568",
+    "cdnUrl": "https://cdn.storerouter.ai/91b22b320476b49b1d658a81b4f2aad6/6afbe5a521bcb04aa95fbb111487a33d.webp",
+    "width": 4000,
+    "height": 4000,
+    "mimeType": "image/webp"
+  },
+  "sizes": [
+    "8",
+    "8.5",
+    "9",
+    "9.5",
+    "10",
+    "10.5",
+    "11",
+    "11.5",
+    "12",
+    "12.5",
+    "13",
+    "13.5",
+    "14"
+  ],
+  "colors": [{ "label": "Light Grey/Syrah (Blizzard Sole)" }],
+  "categories": [{ "name": "Shoes" }],
+  "variants": [
+    {
+      "sku": "mens-runner-nz-jersey-light-grey-syrah",
+      "productUrl": "https://www.allbirds.com/products/mens-runner-nz-jersey-light-grey-syrah",
+      "color": { "label": "Light Grey/Syrah (Blizzard Sole)" },
+      "inStock": true,
+      "availability": "InStock",
+      "currentPrice": 110.0,
+      "currency": "USD"
+    }
+  ],
+  "identifiers": { "productId": "7258388856912", "productGroupId": "7258388856912" },
+  "details": { "materials": ["cotton"], "fit": [], "patterns": [] },
+  "audience": { "genders": ["male"], "ageGroups": ["adult"] },
+  "enrichment": {
+    "type": "sneakers",
+    "category_path": ["Apparel & Accessories", "Shoes", "Sneakers"],
+    "color_family": ["Gray", "Red", "White"],
+    "gender": "male",
+    "age_groups": ["adult"],
+    "attributes": {
+      "Activity Type": ["Running"],
+      "Closure type": ["Lace-Up"],
+      "Footwear material": ["Cotton"],
+      "Sneaker style": ["Athletic"],
+      "Shoe Type (Silhouette/Style)": ["Low-Top"]
+    },
+    "summary": "Men's light grey jersey textile sneakers featuring contrasting red laces and a clean white sole."
+  },
+  "languageCode": "en-US",
+  "updatedAt": "2026-11-06T10:34:25.665193Z"
+}
+```
+
+Want Markdown for an LLM prompt instead of JSON? Call
+`client.lookup_product_markdown(url)`.
+
+### Look up many URLs at once
+
+`lookup_products` runs lookups concurrently (8 at a time by default) and
+returns one `LookupResult` per URL, in the same order. A URL that fails does
+not stop the batch.
+
+```python
+results = client.lookup_products([
+    "https://www.allbirds.com/products/mens-runner-nz-jersey-light-grey-syrah",
+    "https://www.jcrew.com/p/mens/categories/clothing/shirts/linen/short-sleeve-camp-collar-shirt-in-irish-linen/BG997",
+    "https://www.example.com/not-a-product",
+])
+for r in results:
+    if r.ok:
+        print("ok  ", r.product.title, r.product.current_price)
+    else:
+        print("fail", r.url, type(r.error).__name__, r.error)
+```
+
+```text
+ok   Men's Runner NZ Jersey - Light Grey/Syrah (Blizzard Sole) 110.0
+ok   Short-sleeve camp-collar shirt in Irish linen 87.99
+fail https://www.example.com/not-a-product OctogenNotFoundError product_not_found
+```
+
+## Search products
+
+`search_products` takes a natural-language query. By default StoreRouter
+understands it: it rewrites the query for retrieval and turns implied
+constraints into filters. You can narrow the search with:
+
+- `stores`: up to 20 store domains;
+- `facets`: filters such as `color_family`, `gender`, `brand_name`,
+  `category_path.depth_N` and taxonomy attributes;
+- `price_min` and `price_max`.
+
+With `relax=True`, a query that finds nothing is retried with its filters
+dropped in stages. Only the facets you mark `relaxable=True` can be dropped.
+
+```python
+from storerouter import SearchFacet
+
+page = client.search_products(
+    q="linen shirt",
+    stores=["jcrew.com"],
+    facets=[SearchFacet(name="color_family", values=["Blue"], relaxable=True)],
+    relax=True,
+    limit=3,
+)
+for item in page.items:
+    print(f"{item.title} | {item.current_price} {item.currency} | {item.product_url}")
+```
+
+```text
+Short-sleeve camp-collar shirt in Irish linen | 87.99 USD | https://www.jcrew.com/p/mens/categories/clothing/shirts/linen/short-sleeve-camp-collar-shirt-in-irish-linen/BG997
+Gamine button-up shirt in linen | 87.99 USD | https://www.jcrew.com/p/womens/categories/clothing/matching-sets/gamine-button-up-shirt-in-linen/CV033
+Washed linen shirt with point collar | 104.99 USD | https://www.jcrew.com/p/mens/categories/clothing/shirts/linen/washed-linen-shirt-with-point-collar/CH601
+```
+
+`page.effective_query` shows the search that actually ran: the understood
+filters, and which facets `relax` dropped. To get the next page, pass
+`cursor=page.next_cursor`. Each item is a `ProductListItem`, a lighter
+version of `Product`. To get the full record, call `lookup_product` with the
+item's URL, or `retrieve_products` with the item UUIDs.
+
+Related calls:
+
+- `count_product_facets`: facet value counts for a query;
+- `more_like_this_products`: products similar to the ones you pass;
+- `list_taxonomy_categories` and `list_taxonomy_attributes`: the category tree
+  and attribute names that facets accept.
+
+## Stores and brands
+
+```python
+store = client.get_store("allbirds.com")        # is this store covered, and how well?
+for catalog in store.catalogs:
+    print(catalog.catalog_display_name, catalog.product_count)
+
+stores = client.search_stores("sustainable sneakers", limit=3)
+print([s.store.primary_domain for s in stores.results])
+# ['seavees.com', 'stellamccartney.com', '8000kicks.com']
+
+brands = client.search_brands("minimalist sneakers", limit=3)
+print([(b.brand_name, b.domain) for b in brands.results])
+# [('Little Love Bug Co.', 'littlelovebugcompany.com'), ('ALIVEFORM', 'aliveform.co'), ('Camper', 'camper.com')]
+
+brand = client.get_brand_details("allbirds")
+print(brand.founded_year, brand.origin_country, brand.price_tier)
+# 2016 New Zealand PREMIUM
+```
+
+More brand calls: `search_brand_prefix` (autocomplete), `search_similar_brands`,
+`get_brand_directory`, `get_brand_coverage`, `browse_brand_products` and
+`get_brand_top_categories`. For stores there is also `search_similar_stores`.
+
+## Async
+
+`AsyncStoreRouter` has the same constructor and the same methods as
+`StoreRouter`, as coroutines:
+
+```python
+import asyncio
+from storerouter import AsyncStoreRouter
+
+async def main() -> None:
+    async with AsyncStoreRouter() as client:
+        page = await client.search_products(q="wool sweater", limit=2)
+        print([item.title for item in page.items])
+
+asyncio.run(main())
+```
+
+`StoreRouter` runs the async client on a private event-loop thread. It
+therefore works inside Jupyter and other code that already runs an event
+loop. Close it with `client.close()`, or use it in a `with` block.
+
+## The normalized product schema
+
+Every lookup returns a `Product` (`storerouter.models.Product`). Every search
+result is a `ProductListItem`, which is a subset of `Product`. Python
+attributes use snake_case. The JSON wire format uses camelCase:
+`model_dump(by_alias=True)`.
+
+| Field                                | What it holds                                                                                  |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------- |
+| `uuid`, `catalog_key`, `product_url` | StoreRouter's stable ID, the store's catalog, and the canonical product URL                    |
+| `title`, `description`               | As the store states them                                                                       |
+| `brand`                              | `name`, `slug`, `url`, `description`                                                           |
+| `current_price`, `original_price`    | Sale price and list price, as numbers                                                          |
+| `currency`                           | ISO 4217 code, for example `USD`                                                               |
+| `in_stock`, `availability`           | Stock rolled up across variants, and the schema.org availability term                          |
+| `variants`                           | Per-variant `sku`, `color`, `size`, `in_stock`, `current_price`, `original_price`, `image_url` |
+| `sizes`, `colors`                    | Sizes and color labels (with swatches and hex codes when the store has them)                   |
+| `primary_image`, `images`            | Store image URL plus a StoreRouter CDN copy (`cdn_url`), with dimensions                       |
+| `identifiers`                        | `product_id`, `gtin`, `product_group_id`                                                       |
+| `categories`, `breadcrumbs`          | The store's own categories and breadcrumb trail                                                |
+| `details`                            | `materials`, `fit`, `dimensions`, `patterns`                                                   |
+| `audience`                           | `genders`, `age_groups`                                                                        |
+| `rating`, `reviews`                  | Aggregate rating and individual reviews                                                        |
+| `promotions`, `videos`, `tags`       | Promotions with codes, product videos, and store tags                                          |
+| `additional_attributes`              | Name/value pairs as the store states them                                                      |
+| `enrichment`                         | Added by StoreRouter (see below)                                                               |
+| `item_condition`, `language_code`    | schema.org item condition, and the language of the text                                        |
+| `updated_at`                         | When StoreRouter last refreshed the product                                                    |
+
+StoreRouter adds `enrichment` itself. It holds:
+
+- the product `type`;
+- a taxonomy `category_path`, root first;
+- `color_family`, `gender`, `age_groups` and `styles`;
+- category-specific `attributes`: fit and fabric for apparel, skin type for
+  skincare, notes for fragrance, upholstery for furniture;
+- a `canonical_brand` profile;
+- a one-line `summary`.
+
+The full machine-readable schema is the
+[OpenAPI document](https://cdn.storerouter.ai/openapi/platform/v1/openapi.json).
+
+## Errors and retries
+
+The client retries 429, 500, 502, 503 and 504 responses, and connections that
+fail to open. It waits for `Retry-After` when the server sends one, and uses
+exponential backoff otherwise. Read timeouts are not retried. Set the number
+of retries with `StoreRouter(max_retries=...)` (the default is 2, and 0
+disables retries).
+
+When a call fails, it raises a typed error. Each one is an alias of the
+matching `octogen_ai_sdk` error:
+
+| Error                     | When                                                 |
+| ------------------------- | ---------------------------------------------------- |
+| `MissingAPIKeyError`      | No key passed, and none in the environment           |
+| `AuthenticationError`     | 401: the key is invalid                              |
+| `InsufficientCreditError` | 402: the organization is out of credit               |
+| `PermissionDeniedError`   | 403: the key cannot use this endpoint or catalog     |
+| `NotFoundError`           | 404: product not found, or store not covered         |
+| `ValidationError`         | 422: invalid request                                 |
+| `RateLimitError`          | 429 after retries; `error.retry_after` is in seconds |
+| `InternalServerError`     | 5xx after retries                                    |
+| `APITimeoutError`         | The request timed out                                |
+| `APIConnectionError`      | Network failure                                      |
+
+`APIError` is the base class of every HTTP error, and `StoreRouterError` is
+the base class of them all. HTTP errors carry `status_code`, `detail` and
+`request_id`.
+
+## Configuration
+
+| Setting  | Argument                                | Environment variable                                    | Default                         |
+| -------- | --------------------------------------- | ------------------------------------------------------- | ------------------------------- |
+| API key  | `api_key=`                              | `STOREROUTER_API_KEY` (then `OCTOGEN_PLATFORM_API_KEY`) | required                        |
+| Base URL | `base_url=`                             | `STOREROUTER_BASE_URL`                                  | `https://api.storerouter.ai/v1` |
+| Timeout  | `timeout=` (seconds or `httpx.Timeout`) |                                                         | 60 s                            |
+| Retries  | `max_retries=`                          |                                                         | 2                               |
+
+Every method also accepts a per-call `timeout=`. Requests use
+`Authorization: Bearer <key>`. Billing is per successful request, and every
+organization gets free credit each month: see
+[pricing](https://storerouter.ai/docs/guides/pricing-and-billing).
+
+## Other ways to use StoreRouter
+
+- **MCP server for AI agents**: `https://mcp.dev.storerouter.ai/mcp`
+  (Streamable HTTP with OAuth). It gives Claude, ChatGPT, Cursor and other MCP
+  clients product search, product lookup, and store and brand tools. See the
+  [setup guides](https://storerouter.ai/docs/mcp/overview).
+- **LangChain**: [`langchain-storerouter`](https://pypi.org/project/langchain-storerouter/)
+- **TypeScript**: [`@storerouter/sdk`](https://www.npmjs.com/package/@storerouter/sdk)
+- **CLI**: [`@storerouter/cli`](https://www.npmjs.com/package/@storerouter/cli)
+- **REST**: the [API reference](https://storerouter.ai/docs/api-reference)
+  and the [OpenAPI document](https://cdn.storerouter.ai/openapi/platform/v1/openapi.json)
+
+`storerouter` is built on [`octogen-ai-sdk`](https://pypi.org/project/octogen-ai-sdk/),
+the lower-level async SDK for the same API. It adds the sync client, retries,
+batch lookup and the `STOREROUTER_*` settings. Every `octogen_ai_sdk` model is
+available from `storerouter.models`.
+
+## Documentation
+
+- [StoreRouter docs](https://storerouter.ai/docs)
+- [API reference](https://storerouter.ai/docs/api-reference)
+- [MCP server](https://storerouter.ai/docs/mcp/overview)
+- [Source and issues](https://github.com/octogen-ai/octogen-dev/tree/main/sdks/storerouter-python)
+
+## License
+
+Apache-2.0

storerouter-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+storerouter/__init__.py,sha256=66VL6PRr4gDQomJbWHkGR4bpuDkPvrjSsrDPzDqzdXY,2716
+storerouter/_client.py,sha256=8_6IGJ4fDORHw85w8pNerQzP_lN8-FCHbsaoQBTUfKw,13183
+storerouter/_retry.py,sha256=7FwZBxJQvwQLaTG3rMTwPBULM7UzyNuO5k-wk4LBv4Q,3220
+storerouter/models.py,sha256=7EtFLikeBdY6Iv8hzqZdDzE9sxZ6sceJxc1BZp7ZjtM,907
+storerouter/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+storerouter-0.1.0.dist-info/WHEEL,sha256=MWx7psoF7KNST9G72pGtiBYuaXRXQXBk9pw5R6FzYko,80
+storerouter-0.1.0.dist-info/METADATA,sha256=pSEzf8jW1zxueEonYNjjOQlL4Jf_9olosYebiiloZNA,18365
+storerouter-0.1.0.dist-info/RECORD,,

storerouter-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.7
+Root-Is-Purelib: true
+Tag: py3-none-any