onlist 0.1.0__py3-none-any.whl

onlist/__init__.py

@@ -0,0 +1,48 @@
+"""Onlist Python SDK -- Official client for the Onlist AI API marketplace."""
+
+from onlist._client import AsyncOnlist, Onlist
+from onlist._exceptions import (
+    APIError,
+    AuthenticationError,
+    InsufficientBalanceError,
+    OnlistError,
+    ProviderError,
+    RateLimitError,
+)
+from onlist._version import __version__
+from onlist.types import (
+    MaxPrice,
+    Model,
+    ModelDetail,
+    ModelListResponse,
+    Pricing,
+    Provider,
+    ProviderDetail,
+    ProviderListResponse,
+    ProviderRouting,
+)
+
+__all__ = [
+    # Clients
+    "AsyncOnlist",
+    "Onlist",
+    # Exceptions
+    "APIError",
+    "AuthenticationError",
+    "InsufficientBalanceError",
+    "OnlistError",
+    "ProviderError",
+    "RateLimitError",
+    # Types
+    "MaxPrice",
+    "Model",
+    "ModelDetail",
+    "ModelListResponse",
+    "Pricing",
+    "Provider",
+    "ProviderDetail",
+    "ProviderListResponse",
+    "ProviderRouting",
+    # Meta
+    "__version__",
+]

onlist/_client.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import os
+from typing import Any, Mapping
+
+import httpx
+import openai
+
+from onlist._constants import BASE_URL, ENV_API_KEY, MARKETPLACE_BASE_URL
+from onlist._version import __version__
+from onlist.resources.marketplace import AsyncMarketplace, Marketplace
+
+
+class Onlist(openai.OpenAI):
+    """Onlist API client. Drop-in replacement for ``openai.OpenAI``.
+
+    All OpenAI-compatible methods (``chat.completions``, ``embeddings``,
+    ``images``, ``audio``, ``models``) work identically. The ``marketplace``
+    attribute provides access to Onlist-specific APIs.
+
+    Example::
+
+        from onlist import Onlist
+
+        client = Onlist(api_key="sk-...")
+
+        # OpenAI-compatible
+        response = client.chat.completions.create(
+            model="anthropic/claude-sonnet-4",
+            messages=[{"role": "user", "content": "Hello!"}],
+        )
+
+        # Onlist marketplace
+        models = client.marketplace.models.list()
+    """
+
+    marketplace: Marketplace
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | httpx.URL | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        resolved_key = api_key or os.environ.get(ENV_API_KEY)
+
+        merged_headers = dict(default_headers or {})
+        merged_headers.setdefault("User-Agent", f"onlist-python/{__version__}")
+        merged_headers.setdefault("HTTP-Referer", "https://onlist.io")
+
+        super().__init__(
+            api_key=resolved_key,
+            base_url=base_url or BASE_URL,
+            default_headers=merged_headers,
+            **kwargs,
+        )
+
+        marketplace_base = str(self.base_url).split("/v1")[0]
+
+        effective_key = self.api_key if isinstance(self.api_key, str) else resolved_key
+        self.marketplace = Marketplace(
+            api_key=effective_key,
+            base_url=marketplace_base or MARKETPLACE_BASE_URL,
+        )
+
+    def close(self) -> None:
+        super().close()
+        self.marketplace.close()
+
+
+class AsyncOnlist(openai.AsyncOpenAI):
+    """Async Onlist API client. Drop-in replacement for ``openai.AsyncOpenAI``.
+
+    Example::
+
+        import asyncio
+        from onlist import AsyncOnlist
+
+        async def main():
+            client = AsyncOnlist(api_key="sk-...")
+            response = await client.chat.completions.create(
+                model="openai/gpt-4o",
+                messages=[{"role": "user", "content": "Hello!"}],
+            )
+            print(response.choices[0].message.content)
+
+        asyncio.run(main())
+    """
+
+    marketplace: AsyncMarketplace
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | httpx.URL | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        resolved_key = api_key or os.environ.get(ENV_API_KEY)
+
+        merged_headers = dict(default_headers or {})
+        merged_headers.setdefault("User-Agent", f"onlist-python/{__version__}")
+        merged_headers.setdefault("HTTP-Referer", "https://onlist.io")
+
+        super().__init__(
+            api_key=resolved_key,
+            base_url=base_url or BASE_URL,
+            default_headers=merged_headers,
+            **kwargs,
+        )
+
+        marketplace_base = str(self.base_url).split("/v1")[0]
+
+        effective_key = self.api_key if isinstance(self.api_key, str) else resolved_key
+        self.marketplace = AsyncMarketplace(
+            api_key=effective_key,
+            base_url=marketplace_base or MARKETPLACE_BASE_URL,
+        )
+
+    async def close(self) -> None:
+        await super().close()
+        await self.marketplace.close()

onlist/_constants.py

@@ -0,0 +1,3 @@
+BASE_URL = "https://onlist.io/v1"
+MARKETPLACE_BASE_URL = "https://onlist.io"
+ENV_API_KEY = "ONLIST_API_KEY"

onlist/_exceptions.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class OnlistError(Exception):
+    """Base exception for all Onlist SDK errors."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+
+class APIError(OnlistError):
+    """An error returned by the Onlist API."""
+
+    status_code: int
+    type: str | None
+    code: str | None
+    param: str | None
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        type: str | None = None,
+        code: str | None = None,
+        param: str | None = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.type = type
+        self.code = code
+        self.param = param
+        self.body = body
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}("
+            f"message={self.message!r}, "
+            f"status_code={self.status_code}, "
+            f"code={self.code!r})"
+        )
+
+
+class AuthenticationError(APIError):
+    """Raised on 401 responses (missing or invalid API key)."""
+
+    def __init__(self, message: str = "Invalid API key", **kwargs: Any) -> None:
+        kwargs.setdefault("status_code", 401)
+        super().__init__(message, **kwargs)
+
+
+class InsufficientBalanceError(APIError):
+    """Raised on 402 responses (insufficient balance)."""
+
+    def __init__(self, message: str = "Insufficient balance", **kwargs: Any) -> None:
+        kwargs.setdefault("status_code", 402)
+        super().__init__(message, **kwargs)
+
+
+class RateLimitError(APIError):
+    """Raised on 429 responses (rate limited)."""
+
+    def __init__(self, message: str = "Rate limited", **kwargs: Any) -> None:
+        kwargs.setdefault("status_code", 429)
+        super().__init__(message, **kwargs)
+
+
+class ProviderError(APIError):
+    """Raised when no provider is available for the request."""
+
+    pass
+
+
+def _raise_for_status(status_code: int, body: Any) -> None:
+    """Parse an Onlist error response and raise the appropriate exception."""
+    error = {}
+    if isinstance(body, dict):
+        error = body.get("error", body)
+
+    message = error.get("message", str(body)) if isinstance(error, dict) else str(body)
+    etype = error.get("type") if isinstance(error, dict) else None
+    code = error.get("code") if isinstance(error, dict) else None
+    param = error.get("param") if isinstance(error, dict) else None
+
+    kwargs = dict(
+        status_code=status_code,
+        type=etype,
+        code=code,
+        param=param,
+        body=body,
+    )
+
+    if status_code == 401:
+        raise AuthenticationError(message, **kwargs)
+    if status_code == 402:
+        raise InsufficientBalanceError(message, **kwargs)
+    if status_code == 429:
+        raise RateLimitError(message, **kwargs)
+    if code and code.startswith("no_provider"):
+        raise ProviderError(message, **kwargs)
+
+    raise APIError(message, **kwargs)

onlist/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

onlist/resources/__init__.py

@@ -0,0 +1,3 @@
+from onlist.resources.marketplace import AsyncMarketplace, Marketplace
+
+__all__ = ["Marketplace", "AsyncMarketplace"]

onlist/resources/marketplace.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from onlist._exceptions import _raise_for_status
+from onlist._version import __version__
+from onlist.types.model import ModelDetail, ModelListResponse
+from onlist.types.provider import Provider, ProviderDetail, ProviderListResponse
+
+
+_DEFAULT_TIMEOUT = 30.0
+
+
+def _default_headers(api_key: str | None) -> dict[str, str]:
+    headers: dict[str, str] = {
+        "User-Agent": f"onlist-python/{__version__}",
+        "Accept": "application/json",
+    }
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    return headers
+
+
+def _encode_path(segment: str) -> str:
+    """URL-encode a path segment, preserving ``/`` for model IDs like ``author/model``."""
+    return quote(segment, safe="/")
+
+
+def _parse_response(response: httpx.Response) -> Any:
+    if response.status_code >= 400:
+        try:
+            body = response.json()
+        except Exception:
+            body = response.text
+        _raise_for_status(response.status_code, body)
+    body = response.json()
+    if isinstance(body, dict) and "data" in body and "success" in body:
+        body = body["data"]
+    return body
+
+
+class MarketplaceModels:
+    """Query the Onlist model catalog."""
+
+    def __init__(self, client: httpx.Client) -> None:
+        self._client = client
+
+    def list(
+        self,
+        *,
+        limit: int = 20,
+        offset: int = 0,
+        q: str | None = None,
+    ) -> ModelListResponse:
+        """List models with pricing and provider counts.
+
+        Args:
+            limit: Maximum results to return.
+            offset: Number of results to skip.
+            q: Optional search query.
+        """
+        params: dict[str, Any] = {"limit": limit, "offset": offset}
+        if q:
+            params["q"] = q
+        resp = self._client.get("/api/mkt/models", params=params)
+        return ModelListResponse.model_validate(_parse_response(resp))
+
+    def get(self, model_id: str) -> ModelDetail:
+        """Get detailed info for a model, including all provider offers.
+
+        Args:
+            model_id: Model identifier, e.g. ``"anthropic/claude-sonnet-4-6"``.
+        """
+        resp = self._client.get(f"/api/mkt/models/{_encode_path(model_id)}")
+        data = _parse_response(resp)
+        if isinstance(data, dict) and "data" in data:
+            data = data["data"]
+        return ModelDetail.model_validate(data)
+
+
+class MarketplaceProviders:
+    """Query provider (seller) profiles."""
+
+    def __init__(self, client: httpx.Client) -> None:
+        self._client = client
+
+    def list(
+        self,
+        *,
+        sort: str | None = None,
+        q: str | None = None,
+    ) -> ProviderListResponse:
+        """List all providers on the marketplace.
+
+        Args:
+            sort: Sort order (e.g. ``"score"``).
+            q: Optional search query.
+        """
+        params: dict[str, Any] = {}
+        if sort:
+            params["sort"] = sort
+        if q:
+            params["q"] = q
+        resp = self._client.get("/api/mkt/providers", params=params)
+        return ProviderListResponse.model_validate(_parse_response(resp))
+
+    def get(self, slug: str) -> ProviderDetail:
+        """Get a provider's public profile by slug.
+
+        Args:
+            slug: Provider slug, e.g. ``"alice-shop"``.
+        """
+        resp = self._client.get(f"/api/mkt/provider/{_encode_path(slug)}")
+        data = _parse_response(resp)
+        if isinstance(data, dict) and "data" in data:
+            data = data["data"]
+        return ProviderDetail.model_validate(data)
+
+
+class Marketplace:
+    """Access Onlist marketplace data.
+
+    Provides read-only access to the public marketplace APIs:
+    model catalog, provider directory, and more.
+    """
+
+    models: MarketplaceModels
+    providers: MarketplaceProviders
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers=_default_headers(api_key),
+            timeout=timeout,
+        )
+        self.models = MarketplaceModels(self._client)
+        self.providers = MarketplaceProviders(self._client)
+
+    def close(self) -> None:
+        self._client.close()
+
+
+# ---------------------------------------------------------------------------
+# Async mirror
+# ---------------------------------------------------------------------------
+
+
+class AsyncMarketplaceModels:
+    def __init__(self, client: httpx.AsyncClient) -> None:
+        self._client = client
+
+    async def list(
+        self,
+        *,
+        limit: int = 20,
+        offset: int = 0,
+        q: str | None = None,
+    ) -> ModelListResponse:
+        params: dict[str, Any] = {"limit": limit, "offset": offset}
+        if q:
+            params["q"] = q
+        resp = await self._client.get("/api/mkt/models", params=params)
+        return ModelListResponse.model_validate(_parse_response(resp))
+
+    async def get(self, model_id: str) -> ModelDetail:
+        resp = await self._client.get(f"/api/mkt/models/{_encode_path(model_id)}")
+        data = _parse_response(resp)
+        if isinstance(data, dict) and "data" in data:
+            data = data["data"]
+        return ModelDetail.model_validate(data)
+
+
+class AsyncMarketplaceProviders:
+    def __init__(self, client: httpx.AsyncClient) -> None:
+        self._client = client
+
+    async def list(
+        self,
+        *,
+        sort: str | None = None,
+        q: str | None = None,
+    ) -> ProviderListResponse:
+        params: dict[str, Any] = {}
+        if sort:
+            params["sort"] = sort
+        if q:
+            params["q"] = q
+        resp = await self._client.get("/api/mkt/providers", params=params)
+        return ProviderListResponse.model_validate(_parse_response(resp))
+
+    async def get(self, slug: str) -> ProviderDetail:
+        resp = await self._client.get(f"/api/mkt/provider/{_encode_path(slug)}")
+        data = _parse_response(resp)
+        if isinstance(data, dict) and "data" in data:
+            data = data["data"]
+        return ProviderDetail.model_validate(data)
+
+
+class AsyncMarketplace:
+    """Async version of :class:`Marketplace`."""
+
+    models: AsyncMarketplaceModels
+    providers: AsyncMarketplaceProviders
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        self._client = httpx.AsyncClient(
+            base_url=base_url,
+            headers=_default_headers(api_key),
+            timeout=timeout,
+        )
+        self.models = AsyncMarketplaceModels(self._client)
+        self.providers = AsyncMarketplaceProviders(self._client)
+
+    async def close(self) -> None:
+        await self._client.aclose()

onlist/types/__init__.py

@@ -0,0 +1,28 @@
+from onlist.types.model import (
+    Architecture,
+    Model,
+    ModelDetail,
+    ModelListResponse,
+    Pricing,
+    TopProvider,
+)
+from onlist.types.provider import (
+    Provider,
+    ProviderDetail,
+    ProviderListResponse,
+)
+from onlist.types.routing import MaxPrice, ProviderRouting
+
+__all__ = [
+    "Architecture",
+    "MaxPrice",
+    "Model",
+    "ModelDetail",
+    "ModelListResponse",
+    "Pricing",
+    "Provider",
+    "ProviderDetail",
+    "ProviderListResponse",
+    "ProviderRouting",
+    "TopProvider",
+]

onlist/types/model.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class Pricing(BaseModel):
+    prompt: str = "0"
+    completion: str = "0"
+    request: str | None = None
+
+
+class Architecture(BaseModel):
+    modality: str | None = None
+    input_modalities: list[str] | None = None
+    output_modalities: list[str] | None = None
+    tokenizer: str | None = None
+
+
+class TopProvider(BaseModel):
+    context_length: int | None = None
+    max_completion_tokens: int | None = None
+    is_moderated: bool | None = None
+
+
+class Model(BaseModel):
+    id: str
+    name: str | None = None
+    author: str | None = None
+    owned_by: str | None = None
+    canonical_slug: str | None = None
+    created: int | None = None
+    description: str | None = None
+    context_length: int | None = None
+    max_output_length: int | None = None
+    architecture: Architecture | None = None
+    pricing: Pricing | None = None
+    supported_parameters: list[str] | None = None
+    quantization: str | None = None
+    top_provider: TopProvider | None = None
+    is_ready: bool | None = None
+
+    model_config = {"extra": "allow"}
+
+
+class ProviderOffer(BaseModel):
+    listing_id: int | None = None
+    provider_id: int | None = None
+    slug: str | None = None
+    name: str | None = None
+    logo_url: str | None = None
+    score: float | None = None
+    price_input_usd: str | None = None
+    price_output_usd: str | None = None
+    availability_7d: float | None = None
+
+    model_config = {"extra": "allow"}
+
+
+class ModelDetail(BaseModel):
+    id: str
+    name: str | None = None
+    author: str | None = None
+    owned_by: str | None = None
+    context_length: int | None = None
+    max_output_length: int | None = None
+    architecture: Architecture | None = None
+    pricing: Pricing | None = None
+    description: str | None = None
+    providers: list[ProviderOffer] = Field(default_factory=list)
+
+    model_config = {"extra": "allow"}
+
+
+class ModelListResponse(BaseModel):
+    """Response from ``marketplace.models.list()``."""
+
+    data: list[dict[str, Any]] = Field(default_factory=list)
+    total: int | None = None
+    offset: int | None = None
+    limit: int | None = None
+
+    model_config = {"extra": "allow"}

onlist/types/provider.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class Provider(BaseModel):
+    id: int | None = None
+    slug: str
+    name: str | None = None
+    display_name: str | None = None
+    description: str | None = None
+    logo_url: str | None = None
+    listing_count: int | None = None
+    follower_count: int | None = None
+    weighted_score: float | None = None
+    sample_count: int | None = None
+    max_rpm: int | None = None
+    availability_7d: float | None = None
+
+    @property
+    def score(self) -> float | None:
+        return self.weighted_score
+
+    @property
+    def model_count(self) -> int | None:
+        return self.listing_count
+
+    model_config = {"extra": "allow"}
+
+
+class ProviderDetail(BaseModel):
+    id: int | None = None
+    slug: str
+    name: str | None = None
+    display_name: str | None = None
+    description: str | None = None
+    logo_url: str | None = None
+    listing_count: int | None = None
+    follower_count: int | None = None
+    weighted_score: float | None = None
+    max_rpm: int | None = None
+    availability_7d: float | None = None
+    listings: list[dict[str, Any]] = Field(default_factory=list)
+
+    @property
+    def score(self) -> float | None:
+        return self.weighted_score
+
+    @property
+    def model_count(self) -> int | None:
+        return self.listing_count
+
+    model_config = {"extra": "allow"}
+
+
+class ProviderListResponse(BaseModel):
+    """Response from ``marketplace.providers.list()``."""
+
+    items: list[Provider] = Field(default_factory=list)
+
+    @property
+    def data(self) -> list[Provider]:
+        return self.items
+
+    @property
+    def total(self) -> int:
+        return len(self.items)
+
+    model_config = {"extra": "allow"}

onlist/types/routing.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class MaxPrice(BaseModel):
+    """USD-per-token price caps for provider routing."""
+
+    prompt: float | None = None
+    completion: float | None = None
+
+
+class ProviderRouting(BaseModel):
+    """OpenRouter-compatible provider routing controls.
+
+    Pass as ``extra_body={"provider": routing.model_dump(exclude_none=True)}``
+    or simply as a dict.
+
+    Example::
+
+        from onlist.types import ProviderRouting
+
+        routing = ProviderRouting(only=["alice-shop"], sort="price")
+        client.chat.completions.create(
+            model="anthropic/claude-sonnet-4",
+            messages=[...],
+            extra_body={"provider": routing.model_dump(exclude_none=True)},
+        )
+    """
+
+    only: list[str] | None = None
+    sort: Literal["price", "throughput"] | None = None
+    order: list[str] | None = None
+    allow: list[str] | None = None
+    ignore: list[str] | None = None
+    allow_fallbacks: bool | None = None
+    max_price: MaxPrice | None = None

onlist-0.1.0.dist-info/METADATA

@@ -0,0 +1,303 @@
+Metadata-Version: 2.4
+Name: onlist
+Version: 0.1.0
+Summary: Official Python SDK for Onlist, the AI API marketplace. Access GPT, Claude, Gemini, DeepSeek and 40+ models through one OpenAI-compatible API.
+Project-URL: Homepage, https://onlist.io
+Project-URL: Documentation, https://onlist.io/docs
+Project-URL: Repository, https://github.com/OnlistTeam/onlist-python
+Project-URL: API Reference, https://onlist.io/docs/api
+Project-URL: Model Catalog, https://onlist.io/models
+Project-URL: Provider Directory, https://onlist.io/providers
+Project-URL: Changelog, https://github.com/OnlistTeam/onlist-python/releases
+Project-URL: Issues, https://github.com/OnlistTeam/onlist-python/issues
+Author-email: Onlist <dev@onlist.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,ai-api,ai-gateway,anthropic,api,chat-completion,claude,deepseek,gemini,gpt,llm,llm-proxy,marketplace,model-router,onlist,openai,openrouter,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Description-Content-Type: text/markdown
+
+# Onlist Python SDK
+
+The official Python client for [Onlist](https://onlist.io), the AI API marketplace.
+
+Onlist aggregates 40+ AI model providers behind a single OpenAI-compatible API.
+This SDK is a drop-in replacement for the OpenAI Python client, so you can switch
+with one line of code.
+
+[![PyPI version](https://img.shields.io/pypi/v/onlist.svg)](https://pypi.org/project/onlist/)
+[![Python versions](https://img.shields.io/pypi/pyversions/onlist.svg)](https://pypi.org/project/onlist/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/OnlistTeam/onlist-python/blob/main/LICENSE)
+
+## Installation
+
+```bash
+pip install onlist
+```
+
+## Quick Start
+
+```python
+from onlist import Onlist
+
+client = Onlist(api_key="sk-...")  # or set ONLIST_API_KEY env var
+
+response = client.chat.completions.create(
+    model="anthropic/claude-sonnet-4",
+    messages=[{"role": "user", "content": "What is Onlist?"}],
+)
+print(response.choices[0].message.content)
+```
+
+Get your API key at [onlist.io](https://onlist.io).
+
+## Authentication
+
+The client reads your API key from:
+1. The `api_key` parameter
+2. The `ONLIST_API_KEY` environment variable
+3. The `OPENAI_API_KEY` environment variable (fallback, for easy migration)
+
+```bash
+export ONLIST_API_KEY="sk-..."
+```
+
+## Provider Routing
+
+Onlist's marketplace lets you choose which provider serves your request.
+Use the `provider` field via `extra_body`:
+
+```python
+# Pin to a specific provider
+response = client.chat.completions.create(
+    model="anthropic/claude-sonnet-4",
+    messages=[{"role": "user", "content": "Hello"}],
+    extra_body={"provider": "alice-shop"},
+)
+
+# Route to the cheapest provider
+response = client.chat.completions.create(
+    model="openai/gpt-4o",
+    messages=[{"role": "user", "content": "Hello"}],
+    extra_body={"provider": {"sort": "price"}},
+)
+
+# Full routing control
+response = client.chat.completions.create(
+    model="openai/gpt-4o",
+    messages=[{"role": "user", "content": "Hello"}],
+    extra_body={
+        "provider": {
+            "allow": ["alice-shop", "bob-relay"],
+            "sort": "price",
+            "allow_fallbacks": True,
+            "max_price": {"prompt": 0.000003, "completion": 0.000015},
+        }
+    },
+)
+```
+
+You can also use the typed helper:
+
+```python
+from onlist import ProviderRouting
+
+routing = ProviderRouting(
+    allow=["alice-shop", "bob-relay"],
+    sort="price",
+)
+
+response = client.chat.completions.create(
+    model="openai/gpt-4o",
+    messages=[{"role": "user", "content": "Hello"}],
+    extra_body={"provider": routing.model_dump(exclude_none=True)},
+)
+```
+
+## Streaming
+
+```python
+stream = client.chat.completions.create(
+    model="anthropic/claude-sonnet-4",
+    messages=[{"role": "user", "content": "Write a haiku about APIs"}],
+    stream=True,
+)
+
+for chunk in stream:
+    content = chunk.choices[0].delta.content
+    if content:
+        print(content, end="", flush=True)
+```
+
+## Async Usage
+
+```python
+import asyncio
+from onlist import AsyncOnlist
+
+async def main():
+    client = AsyncOnlist(api_key="sk-...")
+
+    response = await client.chat.completions.create(
+        model="openai/gpt-4o",
+        messages=[{"role": "user", "content": "Hello!"}],
+    )
+    print(response.choices[0].message.content)
+
+asyncio.run(main())
+```
+
+## Marketplace API
+
+Query the Onlist marketplace for models and providers:
+
+```python
+from onlist import Onlist
+
+client = Onlist(api_key="sk-...")
+
+# List available models with pricing
+models = client.marketplace.models.list(limit=10)
+for m in models.data:
+    print(f"{m['id']} - input: {m.get('pricing', {}).get('prompt', 'N/A')}")
+
+# Get detailed model info with all provider offers
+detail = client.marketplace.models.get("anthropic/claude-sonnet-4")
+print(f"{detail.id} - {len(detail.providers)} providers")
+
+# Browse providers
+providers = client.marketplace.providers.list()
+for p in providers.data:
+    print(f"{p.slug} - score: {p.score}")
+
+# Get a specific provider's profile
+provider = client.marketplace.providers.get("alice-shop")
+print(f"{provider.display_name} - {provider.model_count} models")
+```
+
+## Other APIs
+
+Since Onlist is fully OpenAI-compatible, all standard endpoints work:
+
+```python
+# Embeddings
+embedding = client.embeddings.create(
+    model="openai/text-embedding-3-small",
+    input="Hello world",
+)
+
+# Image generation
+image = client.images.generate(
+    model="openai/gpt-image-2",
+    prompt="A sunset over Tokyo",
+)
+
+# Text-to-speech
+audio = client.audio.speech.create(
+    model="openai/tts-1",
+    voice="alloy",
+    input="Welcome to Onlist.",
+)
+```
+
+## Error Handling
+
+For OpenAI-compatible API calls (`chat.completions`, `embeddings`, etc.), the
+standard `openai` exceptions are raised:
+
+```python
+import openai
+from onlist import Onlist
+
+client = Onlist(api_key="sk-...")
+
+try:
+    response = client.chat.completions.create(
+        model="openai/gpt-4o",
+        messages=[{"role": "user", "content": "Hello"}],
+    )
+except openai.AuthenticationError:
+    print("Invalid API key")
+except openai.RateLimitError as e:
+    print(f"Rate limited: {e.message}")
+```
+
+For marketplace API calls (`client.marketplace.*`), Onlist-specific exceptions
+are raised:
+
+```python
+from onlist import Onlist, AuthenticationError, APIError
+
+client = Onlist(api_key="sk-...")
+
+try:
+    providers = client.marketplace.providers.list()
+except AuthenticationError:
+    print("Invalid API key for marketplace")
+except APIError as e:
+    print(f"API error {e.status_code}: {e.message}")
+```
+
+## Migrate from OpenAI or OpenRouter
+
+Already using the OpenAI SDK? Change one line:
+
+```diff
+- from openai import OpenAI
+- client = OpenAI(api_key="sk-...")
++ from onlist import Onlist
++ client = Onlist(api_key="sk-...")
+```
+
+Or, if you prefer to keep using `openai` directly:
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    api_key="your-onlist-key",
+    base_url="https://onlist.io/v1",
+)
+```
+
+## Routing Metadata
+
+Onlist returns routing information in response headers. Access them to see
+which provider actually served your request:
+
+```python
+# Use the with_raw_response pattern from the openai SDK:
+raw_response = client.chat.completions.with_raw_response.create(
+    model="openai/gpt-4o",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+print(raw_response.headers.get("x-onlist-route-id"))
+print(raw_response.headers.get("x-onlist-provider"))
+
+# Parse the completion as usual:
+response = raw_response.parse()
+print(response.choices[0].message.content)
+```
+
+## Links
+
+- [Onlist Website](https://onlist.io)
+- [API Documentation](https://onlist.io/docs)
+- [Model Catalog](https://onlist.io/models)
+- [Provider Directory](https://onlist.io/providers)
+- [GitHub](https://github.com/OnlistTeam/onlist-python)

onlist-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+onlist/__init__.py,sha256=kKbL6LBo8VaGTQRygaXWPpoknNL_H_OmDN71gneURJY,949
+onlist/_client.py,sha256=Y1lIHfZuMGXjAPsWnfXw0YahvgGtUSGw3F21qa93hLw,3733
+onlist/_constants.py,sha256=ThkP4jJqW9aURURnJBtKxypfA-CB6u47iNGkQ14p0Bc,108
+onlist/_exceptions.py,sha256=3qXyAVj5AxJL1dtw6LMMOu5QzovbZSkRj2xfs5N0Xuk,2996
+onlist/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+onlist/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+onlist/resources/__init__.py,sha256=7pwEzUUXM64ryWYxPYHmikpxSz9gcNKiZNPEGsCTiQ0,118
+onlist/resources/marketplace.py,sha256=R60TErHfQfv6aPUF8pEQ48bbn4R-X6SxFR8JOwxlGE0,6880
+onlist/types/__init__.py,sha256=dob6SJt64cTyxMvlpz0vpRdSrxfQTxbPSvQ7jsB7_iU,522
+onlist/types/model.py,sha256=PjxnXemrtx_Tn1HsrkW5nVolLDvj_auOJ7ucg5DeL2M,2236
+onlist/types/provider.py,sha256=ZA1u6wMY7w-fKae5ozJ80krcZtIHgwfJf-Nq2aOhWb0,1759
+onlist/types/routing.py,sha256=_ik0H2MhJP25XEjlcDuODfE-Z0p9R3XmyDazs3vUnpg,1065
+onlist-0.1.0.dist-info/METADATA,sha256=t8PcUGdnGlW5YT7CurnxyceEihVJqGNMyRdMSr4mn3w,8424
+onlist-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+onlist-0.1.0.dist-info/licenses/LICENSE,sha256=jDzyf0B2yCzZDc_3lR6iOGgP6Va4q9YvmCSP5Q-RTkw,1075
+onlist-0.1.0.dist-info/RECORD,,

onlist-0.1.0.dist-info/WHEEL

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

onlist-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Onlist (onlist.io)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.