otari 0.0.1__py3-none-any.whl

otari/__init__.py

@@ -0,0 +1,85 @@
+"""otari - Python client for the otari gateway.
+
+Example::
+
+    from otari import OtariClient
+
+    client = OtariClient(
+        api_base="http://localhost:8000",
+        platform_token="your-token-here",
+    )
+
+    response = await client.completion(
+        model="openai:gpt-4o-mini",
+        messages=[{"role": "user", "content": "Hello!"}],
+    )
+    print(response.choices[0].message.content)
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from otari.client import OtariClient
+from otari.errors import (
+    AuthenticationError,
+    BatchNotCompleteError,
+    GatewayTimeoutError,
+    InsufficientFundsError,
+    ModelNotFoundError,
+    OtariError,
+    RateLimitError,
+    UnsupportedCapabilityError,
+    UpstreamProviderError,
+)
+from otari.types import (
+    BatchRequestItem,
+    BatchResult,
+    BatchResultError,
+    BatchResultItem,
+    ChatCompletion,
+    ChatCompletionChunk,
+    ChatCompletionMessageParam,
+    CreateBatchParams,
+    CreateEmbeddingResponse,
+    EmbeddingCreateParams,
+    ListBatchesOptions,
+    Model,
+    OtariClientOptions,
+    Response,
+    ResponseStreamEvent,
+    Stream,
+)
+
+try:
+    __version__ = version("otari")
+except PackageNotFoundError:
+    __version__ = "0.0.0-dev"
+
+
+__all__ = [
+    "AuthenticationError",
+    "BatchNotCompleteError",
+    "BatchRequestItem",
+    "BatchResult",
+    "BatchResultError",
+    "BatchResultItem",
+    "ChatCompletion",
+    "ChatCompletionChunk",
+    "ChatCompletionMessageParam",
+    "CreateBatchParams",
+    "CreateEmbeddingResponse",
+    "EmbeddingCreateParams",
+    "GatewayTimeoutError",
+    "InsufficientFundsError",
+    "ListBatchesOptions",
+    "Model",
+    "ModelNotFoundError",
+    "OtariClient",
+    "OtariClientOptions",
+    "OtariError",
+    "RateLimitError",
+    "Response",
+    "ResponseStreamEvent",
+    "Stream",
+    "UnsupportedCapabilityError",
+    "UpstreamProviderError",
+]

otari/client.py

@@ -0,0 +1,645 @@
+"""OtariClient: Python client for the otari gateway.
+
+Wraps the OpenAI Python SDK (``AsyncOpenAI``), adding gateway-specific
+auth handling and error mapping for platform mode. Extracted from the
+``GatewayProvider`` in `any-llm <https://github.com/mozilla-ai/any-llm>`_.
+
+Example::
+
+    from otari import OtariClient
+
+    client = OtariClient(
+        api_base="http://localhost:8000",
+        platform_token="tk_xxx",
+    )
+
+    response = await client.completion(
+        model="openai:gpt-4o-mini",
+        messages=[{"role": "user", "content": "Hello!"}],
+    )
+    print(response.choices[0].message.content)
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import urllib.parse
+from typing import TYPE_CHECKING, Any, overload
+
+import httpx
+import openai
+from openai import AsyncOpenAI
+
+from otari.errors import (
+    AuthenticationError,
+    BatchNotCompleteError,
+    GatewayTimeoutError,
+    InsufficientFundsError,
+    ModelNotFoundError,
+    OtariError,
+    RateLimitError,
+    UnsupportedCapabilityError,
+    UpstreamProviderError,
+)
+
+if TYPE_CHECKING:
+    from openai import AsyncStream
+    from openai.types import CreateEmbeddingResponse, Model
+    from openai.types.chat import (
+        ChatCompletion,
+        ChatCompletionChunk,
+    )
+    from openai.types.responses import (
+        Response,
+        ResponseStreamEvent,
+    )
+
+    from otari.types import (
+        BatchResult,
+        CreateBatchParams,
+        ListBatchesOptions,
+    )
+
+PROVIDER_NAME = "gateway"
+GATEWAY_HEADER_NAME = "Otari-Key"
+
+# Locked phrasing used by the gateway to signal that the selected
+# provider does not support a moderation request.
+_UNSUPPORTED_MODERATION_RE = re.compile(r"does not support (?:multimodal )?moderation")
+
+_ENV_API_BASE = "GATEWAY_API_BASE"
+_ENV_API_KEY = "GATEWAY_API_KEY"
+_ENV_PLATFORM_TOKEN = "GATEWAY_PLATFORM_TOKEN"  # noqa: S105
+
+_STATUS_TO_ERROR: dict[int, type[AuthenticationError] | type[ModelNotFoundError]] = {
+    401: AuthenticationError,
+    403: AuthenticationError,
+    404: ModelNotFoundError,
+}
+
+
+class OtariClient:
+    """Client for the otari gateway.
+
+    Supports two authentication modes (mirroring the TypeScript SDK and
+    the Python ``GatewayProvider``):
+
+    - **Platform mode**: A Bearer token is sent in the standard Authorization
+      header. Errors are mapped to typed otari exceptions.
+    - **Non-platform mode**: An API key is sent via a custom ``Otari-Key``
+      header. Errors from the OpenAI SDK pass through unmodified.
+
+    Args:
+        api_base: Base URL of the gateway (e.g. ``"http://localhost:8000"``).
+            Falls back to the ``GATEWAY_API_BASE`` environment variable.
+        api_key: API key for non-platform mode.
+            Falls back to ``GATEWAY_API_KEY`` env var.
+        platform_token: Platform token for platform mode.
+            Falls back to ``GATEWAY_PLATFORM_TOKEN`` env var.
+        default_headers: Additional default headers to send with every request.
+        openai_options: Extra keyword arguments forwarded to the underlying
+            ``AsyncOpenAI`` constructor.
+
+    Example::
+
+        client = OtariClient(
+            api_base="http://localhost:8000",
+            platform_token="tk_xxx",
+        )
+
+        response = await client.completion(
+            model="openai:gpt-4o-mini",
+            messages=[{"role": "user", "content": "Hello!"}],
+        )
+        print(response.choices[0].message.content)
+    """
+
+    openai: AsyncOpenAI
+    """The underlying OpenAI client instance."""
+
+    platform_mode: bool
+    """Whether the client is operating in platform mode."""
+
+    def __init__(
+        self,
+        api_base: str | None = None,
+        *,
+        api_key: str | None = None,
+        platform_token: str | None = None,
+        default_headers: dict[str, str] | None = None,
+        openai_options: dict[str, Any] | None = None,
+    ) -> None:
+        raw_base = api_base or os.environ.get(_ENV_API_BASE)
+
+        if not raw_base:
+            msg = (
+                "api_base is required for the gateway client. "
+                f"Pass it as api_base or set the {_ENV_API_BASE} environment variable."
+            )
+            raise ValueError(msg)
+
+        # Ensure the base URL includes /v1 since the gateway expects
+        # OpenAI-compatible paths like /v1/chat/completions.
+        cleaned = raw_base.rstrip("/")
+        api_base_url = cleaned if cleaned.endswith("/v1") else f"{cleaned}/v1"
+
+        self._base_url = api_base_url
+
+        resolved_platform_token = platform_token or os.environ.get(_ENV_PLATFORM_TOKEN)
+        resolved_api_key = api_key or os.environ.get(_ENV_API_KEY, "")
+
+        headers: dict[str, str] = {**(default_headers or {})}
+        extra_kwargs: dict[str, Any] = {**(openai_options or {})}
+
+        # Auth resolution (same logic as TS SDK / Python GatewayProvider):
+        # 1. Explicit platform_token -> platform mode
+        # 2. GATEWAY_PLATFORM_TOKEN env + no api_key option -> platform mode
+        # 3. Otherwise -> non-platform mode
+        if resolved_platform_token and not api_key:
+            self.platform_mode = True
+            self._platform_token: str | None = resolved_platform_token
+            self._api_key: str | None = None
+            self.openai = AsyncOpenAI(
+                api_key=resolved_platform_token,
+                base_url=api_base_url,
+                default_headers=headers or None,
+                **extra_kwargs,
+            )
+        else:
+            self.platform_mode = False
+            self._platform_token = None
+            self._api_key = resolved_api_key or None
+            if resolved_api_key:
+                headers[GATEWAY_HEADER_NAME] = f"Bearer {resolved_api_key}"
+            # In non-platform mode we still need to pass *some* API key to the
+            # OpenAI client (it validates the field).
+            self.openai = AsyncOpenAI(
+                api_key=resolved_api_key or "unused",
+                base_url=api_base_url,
+                default_headers=headers or None,
+                **extra_kwargs,
+            )
+
+        # Store auth headers for batch/raw HTTP calls.
+        self._auth_headers: dict[str, str] = {}
+        if resolved_platform_token and not api_key:
+            self._auth_headers["Authorization"] = f"Bearer {resolved_platform_token}"
+        elif resolved_api_key:
+            self._auth_headers[GATEWAY_HEADER_NAME] = f"Bearer {resolved_api_key}"
+        if default_headers:
+            self._auth_headers.update(default_headers)
+
+        # httpx client for raw HTTP calls (batch, etc.)
+        self._http = httpx.AsyncClient()
+
+    # -- Chat completions ---------------------------------------------------
+
+    @overload
+    async def completion(
+        self,
+        *,
+        model: str,
+        messages: list[dict[str, Any]],
+        stream: None = ...,
+        **kwargs: Any,
+    ) -> ChatCompletion: ...
+
+    @overload
+    async def completion(
+        self,
+        *,
+        model: str,
+        messages: list[dict[str, Any]],
+        stream: bool = ...,
+        **kwargs: Any,
+    ) -> ChatCompletion | AsyncStream[ChatCompletionChunk]: ...
+
+    async def completion(
+        self,
+        *,
+        model: str,
+        messages: list[dict[str, Any]],
+        stream: bool | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Create a chat completion.
+
+        When ``stream=True`` is set, returns an async iterable of chunks.
+
+        Args:
+            model: Model identifier (e.g. ``"openai:gpt-4o-mini"``).
+            messages: List of message dicts with ``role`` and ``content``.
+            stream: Whether to stream the response.
+            **kwargs: Additional parameters forwarded to the OpenAI API.
+
+        Returns:
+            A ``ChatCompletion`` or an async stream of ``ChatCompletionChunk``.
+        """
+        try:
+            params: dict[str, Any] = {"model": model, "messages": messages, **kwargs}
+            if stream is not None:
+                params["stream"] = stream
+            return await self.openai.chat.completions.create(**params)
+        except Exception as exc:
+            self._handle_error(exc)
+            raise
+
+    # -- Responses API ------------------------------------------------------
+
+    async def response(
+        self,
+        *,
+        model: str,
+        input: Any,  # noqa: A002
+        stream: bool | None = None,
+        **kwargs: Any,
+    ) -> Response | AsyncStream[ResponseStreamEvent]:
+        """Create a response using the OpenAI Responses API.
+
+        Args:
+            model: Model identifier (e.g. ``"openai:gpt-4o-mini"``).
+            input: The input for the response.
+            stream: Whether to stream the response.
+            **kwargs: Additional parameters forwarded to the OpenAI API.
+
+        Returns:
+            A ``Response`` or an async stream of ``ResponseStreamEvent``.
+        """
+        try:
+            params: dict[str, Any] = {"model": model, "input": input, **kwargs}
+            if stream is not None:
+                params["stream"] = stream
+            result: Response | AsyncStream[ResponseStreamEvent] = await self.openai.responses.create(**params)
+        except Exception as exc:
+            self._handle_error(exc)
+            raise
+        else:
+            return result
+
+    # -- Embeddings ---------------------------------------------------------
+
+    async def embedding(
+        self,
+        *,
+        model: str,
+        input: str | list[str],  # noqa: A002
+        **kwargs: Any,
+    ) -> CreateEmbeddingResponse:
+        """Create embeddings for the given input.
+
+        Args:
+            model: Model identifier (e.g. ``"openai:text-embedding-3-small"``).
+            input: Text or list of texts to embed.
+            **kwargs: Additional parameters forwarded to the OpenAI API.
+
+        Returns:
+            An ``CreateEmbeddingResponse``.
+        """
+        try:
+            return await self.openai.embeddings.create(model=model, input=input, **kwargs)
+        except Exception as exc:
+            self._handle_error(exc)
+            raise
+
+    # -- Models -------------------------------------------------------------
+
+    async def list_models(self) -> list[Model]:
+        """List available models from the gateway.
+
+        Returns:
+            A list of ``Model`` objects.
+        """
+        try:
+            page = await self.openai.models.list()
+        except Exception as exc:
+            self._handle_error(exc)
+            raise
+        else:
+            return [model async for model in page]
+
+    # -- Batch operations ---------------------------------------------------
+
+    async def create_batch(self, params: CreateBatchParams) -> dict[str, Any]:
+        """Create a batch job.
+
+        Args:
+            params: Batch creation parameters including model and requests array.
+
+        Returns:
+            The created batch object.
+        """
+        return await self._batch_request("POST", "/batches", body=dict(params))
+
+    async def retrieve_batch(self, batch_id: str, provider: str) -> dict[str, Any]:
+        """Retrieve the status of a batch job.
+
+        Args:
+            batch_id: The ID of the batch to retrieve.
+            provider: The provider name (e.g. ``"openai"``).
+
+        Returns:
+            The batch object with current status.
+        """
+        encoded_id = httpx.URL(f"/batches/{batch_id}").raw_path.decode()
+        return await self._batch_request(
+            "GET",
+            f"{encoded_id}?provider={_url_encode(provider)}",
+        )
+
+    async def cancel_batch(self, batch_id: str, provider: str) -> dict[str, Any]:
+        """Cancel a batch job.
+
+        Args:
+            batch_id: The ID of the batch to cancel.
+            provider: The provider name (e.g. ``"openai"``).
+
+        Returns:
+            The batch object with updated status.
+        """
+        encoded_id = httpx.URL(f"/batches/{batch_id}").raw_path.decode()
+        return await self._batch_request(
+            "POST",
+            f"{encoded_id}/cancel?provider={_url_encode(provider)}",
+        )
+
+    async def list_batches(
+        self,
+        provider: str,
+        options: ListBatchesOptions | None = None,
+    ) -> list[dict[str, Any]]:
+        """List batch jobs for a provider.
+
+        Args:
+            provider: The provider name (e.g. ``"openai"``).
+            options: Optional pagination parameters.
+
+        Returns:
+            List of batch objects.
+        """
+        params_parts = [f"provider={_url_encode(provider)}"]
+        if options:
+            if "after" in options:
+                params_parts.append(f"after={_url_encode(options['after'])}")
+            if "limit" in options:
+                params_parts.append(f"limit={options['limit']}")
+        query = "&".join(params_parts)
+        response = await self._batch_request("GET", f"/batches?{query}")
+        data: list[dict[str, Any]] = response.get("data", [])
+        return data
+
+    async def retrieve_batch_results(
+        self,
+        batch_id: str,
+        provider: str,
+    ) -> BatchResult:
+        """Retrieve the results of a completed batch job.
+
+        Args:
+            batch_id: The ID of the batch.
+            provider: The provider name (e.g. ``"openai"``).
+
+        Returns:
+            The batch results containing per-request outcomes.
+
+        Raises:
+            BatchNotCompleteError: If the batch is not yet complete.
+        """
+        from otari.types import BatchResult as BatchResultType  # noqa: PLC0415
+        from otari.types import BatchResultItem  # noqa: PLC0415
+
+        encoded_id = httpx.URL(f"/batches/{batch_id}").raw_path.decode()
+        data = await self._batch_request(
+            "GET",
+            f"{encoded_id}/results?provider={_url_encode(provider)}",
+        )
+        items = [
+            BatchResultItem(
+                custom_id=entry["custom_id"],
+                result=entry.get("result"),
+                error=entry.get("error"),
+            )
+            for entry in data.get("results", [])
+        ]
+        return BatchResultType(results=items)
+
+    # -- Error handling -----------------------------------------------------
+
+    def _handle_error(self, error: Exception) -> None:
+        """Convert ``openai.APIStatusError`` to typed otari exceptions.
+
+        Most mappings only apply in platform mode; in non-platform mode the
+        original error propagates unchanged. The one exception is
+        :class:`UnsupportedCapabilityError`, which surfaces in both modes.
+        """
+        if not isinstance(error, openai.APIStatusError):
+            return
+
+        status = error.status_code
+        headers = error.response.headers
+        correlation_id = headers.get("x-correlation-id")
+        retry_after = headers.get("retry-after")
+
+        detail = str(getattr(error, "message", str(error)))
+        if correlation_id:
+            detail = f"{detail} (correlation_id={correlation_id})"
+
+        # Unsupported-capability is surfaced regardless of mode.
+        if status == 400 and _UNSUPPORTED_MODERATION_RE.search(detail):
+            provider = _parse_unsupported_provider(detail)
+            capability = "multimodal_moderation" if "multimodal" in detail else "moderation"
+            raise UnsupportedCapabilityError(
+                detail,
+                status_code=status,
+                original_error=error,
+                provider_name=PROVIDER_NAME,
+                provider=provider,
+                capability=capability,
+            ) from error
+
+        # The rest of the mappings only apply in platform mode.
+        if not self.platform_mode:
+            return
+
+        if (error_cls := _STATUS_TO_ERROR.get(status)) is not None:
+            raise error_cls(
+                detail,
+                status_code=status,
+                original_error=error,
+                provider_name=PROVIDER_NAME,
+            ) from error
+
+        if status == 402:
+            raise InsufficientFundsError(
+                detail,
+                status_code=status,
+                original_error=error,
+                provider_name=PROVIDER_NAME,
+            ) from error
+
+        if status == 429:
+            raise RateLimitError(
+                detail,
+                status_code=status,
+                original_error=error,
+                provider_name=PROVIDER_NAME,
+                retry_after=retry_after,
+            ) from error
+
+        if status == 502:
+            raise UpstreamProviderError(
+                detail,
+                status_code=status,
+                original_error=error,
+                provider_name=PROVIDER_NAME,
+            ) from error
+
+        if status == 504:
+            raise GatewayTimeoutError(
+                detail,
+                status_code=status,
+                original_error=error,
+                provider_name=PROVIDER_NAME,
+            ) from error
+
+        # Unrecognized status: let the original error propagate.
+
+    # -- Batch HTTP helpers -------------------------------------------------
+
+    async def _batch_request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Make a direct HTTP request for batch operations.
+
+        Unlike completion/embedding which use ``self.openai``, batch methods
+        use direct HTTP because the gateway batch API has a custom JSON format.
+        """
+        url = f"{self._base_url}{path}"
+        headers = {
+            "Content-Type": "application/json",
+            **self._auth_headers,
+        }
+
+        response = await self._http.request(
+            method,
+            url,
+            headers=headers,
+            json=body if body is not None else None,
+        )
+
+        if not response.is_success:
+            await self._handle_batch_error(response)
+
+        result: dict[str, Any] = response.json()
+        return result
+
+    async def _handle_batch_error(self, response: httpx.Response) -> None:
+        """Map batch HTTP errors to typed SDK errors."""
+        try:
+            data = response.json()
+            detail = data.get("detail", response.reason_phrase)
+        except Exception:
+            detail = response.reason_phrase or ""
+
+        message = detail if isinstance(detail, str) else (response.reason_phrase or "")
+        correlation_id = response.headers.get("x-correlation-id")
+        full_message = f"{message} (correlation_id={correlation_id})" if correlation_id else message
+
+        status = response.status_code
+
+        if status in (401, 403):
+            raise AuthenticationError(
+                full_message,
+                status_code=status,
+                provider_name=PROVIDER_NAME,
+            )
+
+        if status == 404:
+            msg = (
+                full_message
+                if "not found" in full_message.lower()
+                else f"This gateway does not support batch operations. Upgrade your gateway. ({full_message})"
+            )
+            raise OtariError(msg, status_code=404, provider_name=PROVIDER_NAME)
+
+        if status == 409:
+            raise BatchNotCompleteError(
+                full_message,
+                status_code=409,
+                provider_name=PROVIDER_NAME,
+                batch_id=_extract_batch_id(message),
+                batch_status=_extract_status(message),
+            )
+
+        if status == 422:
+            raise OtariError(full_message, status_code=422, provider_name=PROVIDER_NAME)
+
+        if status == 429:
+            raise RateLimitError(
+                full_message,
+                status_code=429,
+                provider_name=PROVIDER_NAME,
+                retry_after=response.headers.get("retry-after"),
+            )
+
+        if status == 502:
+            raise UpstreamProviderError(
+                full_message,
+                status_code=502,
+                provider_name=PROVIDER_NAME,
+            )
+
+        if status == 504:
+            raise GatewayTimeoutError(
+                full_message,
+                status_code=504,
+                provider_name=PROVIDER_NAME,
+            )
+
+        raise OtariError(full_message, status_code=status, provider_name=PROVIDER_NAME)
+
+    # -- Cleanup ------------------------------------------------------------
+
+    async def close(self) -> None:
+        """Close the underlying HTTP clients."""
+        await self._http.aclose()
+        await self.openai.close()
+
+    async def __aenter__(self) -> OtariClient:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+
+# ---------------------------------------------------------------------------
+# Module-level helpers
+# ---------------------------------------------------------------------------
+
+
+def _parse_unsupported_provider(detail: str) -> str:
+    """Parse the provider name from a gateway 400 detail string.
+
+    Example: ``"Provider anthropic does not support moderation"``
+    """
+    match = re.search(r"Provider\s+(\S+)\s+does not", detail)
+    return match.group(1) if match else "unknown"
+
+
+def _extract_batch_id(message: str) -> str | None:
+    match = re.search(r"Batch '([^']+)'", message)
+    return match.group(1) if match else None
+
+
+def _extract_status(message: str) -> str | None:
+    match = re.search(r"status: (\w+)", message)
+    return match.group(1) if match else None
+
+
+def _url_encode(value: str) -> str:
+    """Percent-encode a single URL component."""
+    return urllib.parse.quote(value, safe="")

otari/errors.py

@@ -0,0 +1,159 @@
+"""Exception hierarchy for otari gateway errors.
+
+Mirrors the TypeScript SDK's exception classes. In platform mode,
+OpenAI ``APIStatusError`` status codes are mapped to these typed errors
+so callers can handle specific failure modes.
+"""
+
+from __future__ import annotations
+
+
+class OtariError(Exception):
+    """Base exception for all otari errors.
+
+    Attributes:
+        message: Human-readable error message.
+        status_code: HTTP status code from the gateway, if available.
+        original_error: The original SDK exception that triggered this error.
+        provider_name: Name of the provider that raised the error.
+    """
+
+    default_message: str = "An error occurred"
+
+    def __init__(
+        self,
+        message: str | None = None,
+        *,
+        status_code: int | None = None,
+        original_error: Exception | None = None,
+        provider_name: str | None = None,
+    ) -> None:
+        self.message = message or self.default_message
+        super().__init__(self.message)
+        self.status_code = status_code
+        self.original_error = original_error
+        self.provider_name = provider_name
+
+    def __str__(self) -> str:
+        if self.provider_name:
+            return f"[{self.provider_name}] {self.message}"
+        return self.message
+
+
+class AuthenticationError(OtariError):
+    """Raised when authentication with the gateway fails (HTTP 401, 403)."""
+
+    default_message = "Authentication failed"
+
+
+class ModelNotFoundError(OtariError):
+    """Raised when the requested model is not found (HTTP 404)."""
+
+    default_message = "Model not found"
+
+
+class InsufficientFundsError(OtariError):
+    """Raised when the user's budget or credits are exhausted (HTTP 402)."""
+
+    default_message = "Insufficient funds or budget exceeded"
+
+
+class RateLimitError(OtariError):
+    """Raised when the API rate limit is exceeded (HTTP 429).
+
+    Attributes:
+        retry_after: Value of the ``Retry-After`` header, when the server
+            provides one. May be a number of seconds or an HTTP-date string.
+    """
+
+    default_message = "Rate limit exceeded"
+
+    def __init__(
+        self,
+        message: str | None = None,
+        *,
+        status_code: int | None = None,
+        original_error: Exception | None = None,
+        provider_name: str | None = None,
+        retry_after: str | None = None,
+    ) -> None:
+        super().__init__(
+            message,
+            status_code=status_code,
+            original_error=original_error,
+            provider_name=provider_name,
+        )
+        self.retry_after = retry_after
+
+
+class UpstreamProviderError(OtariError):
+    """Raised when the upstream provider is unreachable or errors (HTTP 502)."""
+
+    default_message = "Upstream provider error"
+
+
+class GatewayTimeoutError(OtariError):
+    """Raised when the gateway times out waiting for the upstream provider (HTTP 504)."""
+
+    default_message = "Gateway timeout waiting for upstream provider"
+
+
+class BatchNotCompleteError(OtariError):
+    """Raised when attempting to retrieve results for a batch that is not yet complete (HTTP 409).
+
+    Attributes:
+        batch_id: The ID of the batch.
+        batch_status: The current status of the batch.
+    """
+
+    default_message = "Batch is not yet complete"
+
+    def __init__(
+        self,
+        message: str | None = None,
+        *,
+        status_code: int | None = None,
+        original_error: Exception | None = None,
+        provider_name: str | None = None,
+        batch_id: str | None = None,
+        batch_status: str | None = None,
+    ) -> None:
+        super().__init__(
+            message,
+            status_code=status_code,
+            original_error=original_error,
+            provider_name=provider_name,
+        )
+        self.batch_id = batch_id
+        self.batch_status = batch_status
+
+
+class UnsupportedCapabilityError(OtariError):
+    """Raised when the gateway reports that the selected provider does not
+    support a requested capability (e.g. moderation).
+
+    Attributes:
+        capability: Capability that was requested (e.g. ``"moderation"``).
+        provider: Provider name reported by the gateway (e.g. ``"anthropic"``).
+    """
+
+    default_message = "The selected provider does not support this capability"
+
+    def __init__(
+        self,
+        message: str | None = None,
+        *,
+        status_code: int | None = None,
+        original_error: Exception | None = None,
+        provider_name: str | None = None,
+        capability: str = "",
+        provider: str = "",
+    ) -> None:
+        super().__init__(
+            message,
+            status_code=status_code,
+            original_error=original_error,
+            provider_name=provider_name,
+        )
+        self.capability = capability
+        self.provider = provider

otari/types.py

@@ -0,0 +1,106 @@
+"""Configuration and type re-exports for the otari gateway client.
+
+Re-exports OpenAI SDK types so consumers don't need to import ``openai`` directly.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, TypedDict
+
+# ---------------------------------------------------------------------------
+# Re-export OpenAI types that callers interact with directly.
+# These use explicit `as` aliases to make the re-exports public per PEP 484.
+# The TC002 / PLC0414 warnings are intentionally suppressed because these
+# imports exist solely for re-export.
+# ---------------------------------------------------------------------------
+from openai import Stream as Stream  # noqa: PLC0414
+from openai.types import CreateEmbeddingResponse as CreateEmbeddingResponse  # noqa: PLC0414
+from openai.types import EmbeddingCreateParams as EmbeddingCreateParams  # noqa: PLC0414
+from openai.types import Model as Model  # noqa: PLC0414
+from openai.types.chat import ChatCompletion as ChatCompletion  # noqa: PLC0414, TC002
+from openai.types.chat import ChatCompletionChunk as ChatCompletionChunk  # noqa: PLC0414
+from openai.types.chat import ChatCompletionMessageParam as ChatCompletionMessageParam  # noqa: PLC0414
+from openai.types.responses import Response as Response  # noqa: PLC0414
+from openai.types.responses import ResponseStreamEvent as ResponseStreamEvent  # noqa: PLC0414
+
+# ---------------------------------------------------------------------------
+# Client options
+# ---------------------------------------------------------------------------
+
+
+class OtariClientOptions(TypedDict, total=False):
+    """Options for constructing an :class:`~otari.client.OtariClient`.
+
+    Auth resolution order (mirrors the TypeScript SDK / Python GatewayProvider):
+      1. Explicit ``platform_token`` -> platform mode (Bearer token in Authorization header)
+      2. ``GATEWAY_PLATFORM_TOKEN`` env var (when no ``api_key``) -> platform mode
+      3. ``api_key`` or ``GATEWAY_API_KEY`` env var -> non-platform mode (``Otari-Key`` header)
+      4. No credentials -> non-platform mode, no auth header
+    """
+
+    api_base: str
+    """Base URL of the gateway (e.g. ``"http://localhost:8000"``)."""
+
+    api_key: str
+    """API key for non-platform mode. Sent via ``Otari-Key: Bearer <key>``."""
+
+    platform_token: str
+    """Platform token for platform mode. Sent as Bearer in the Authorization header."""
+
+    default_headers: dict[str, str]
+    """Additional default headers to send with every request."""
+
+    openai_options: dict[str, Any]
+    """Extra options forwarded to the underlying ``AsyncOpenAI`` constructor."""
+
+
+# ---------------------------------------------------------------------------
+# Batch types
+# ---------------------------------------------------------------------------
+
+
+class BatchRequestItem(TypedDict):
+    """A single request within a batch."""
+
+    custom_id: str
+    body: dict[str, Any]
+
+
+class CreateBatchParams(TypedDict, total=False):
+    """Parameters for creating a batch job."""
+
+    model: str
+    requests: list[BatchRequestItem]
+    completion_window: str
+    metadata: dict[str, str]
+
+
+class ListBatchesOptions(TypedDict, total=False):
+    """Pagination options for listing batches."""
+
+    after: str
+    limit: int
+
+
+class BatchResultError(TypedDict):
+    """Error information for a failed batch request."""
+
+    code: str
+    message: str
+
+
+@dataclass
+class BatchResultItem:
+    """Result of a single request within a batch."""
+
+    custom_id: str
+    result: ChatCompletion | None = None
+    error: BatchResultError | None = None
+
+
+@dataclass
+class BatchResult:
+    """Aggregated results of a completed batch job."""
+
+    results: list[BatchResultItem] = field(default_factory=list)

otari-0.0.1.dist-info/METADATA

@@ -0,0 +1,304 @@
+Metadata-Version: 2.4
+Name: otari
+Version: 0.0.1
+Summary: Python client for the otari gateway
+Project-URL: Homepage, https://github.com/mozilla-ai/otari-sdk-python
+Project-URL: Documentation, https://mozilla-ai.github.io/otari/
+Project-URL: Repository, https://github.com/mozilla-ai/otari-sdk-python
+Project-URL: Issues, https://github.com/mozilla-ai/otari-sdk-python/issues
+Author-email: Mozilla AI <ai-engineering@mozilla.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: openai>=1.99.3
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <img src="https://raw.githubusercontent.com/mozilla-ai/otari/refs/heads/main/docs/public/images/otari-logo-mark.png" width="20%" alt="Project logo"/>
+  </picture>
+</p>
+
+<div align="center">
+
+# otari (Python)
+
+![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)
+[![PyPI](https://img.shields.io/pypi/v/otari)](https://pypi.org/project/otari/)
+<a href="https://discord.gg/4gf3zXrQUc">
+    <img src="https://img.shields.io/static/v1?label=Chat%20on&message=Discord&color=blue&logo=Discord&style=flat-square" alt="Discord">
+</a>
+
+**Python client for [otari-gateway](https://github.com/mozilla-ai/otari).**
+Communicate with any LLM provider through the gateway using a single, typed interface.
+
+[TypeScript SDK](https://github.com/mozilla-ai/otari-sdk-ts) | [Documentation](https://mozilla-ai.github.io/otari/) | [Platform (Beta)](https://otari.ai/)
+
+</div>
+
+## Quickstart
+
+```python
+from otari import OtariClient
+
+client = OtariClient(
+    api_base="http://localhost:8000",
+    platform_token="your-token-here",
+)
+
+response = await client.completion(
+    model="openai:gpt-4o-mini",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+
+print(response.choices[0].message.content)
+```
+
+**That's it!** Change the model string to switch between LLM providers through the gateway.
+
+## Installation
+
+### Requirements
+
+- Python 3.11 or newer
+- A running [otari-gateway](https://mozilla-ai.github.io/otari/gateway/overview/) instance
+
+### Install
+
+```bash
+pip install otari
+```
+
+### Setting Up Credentials
+
+Set environment variables for your gateway:
+
+```bash
+export GATEWAY_API_BASE="http://localhost:8000"
+export GATEWAY_PLATFORM_TOKEN="your-token-here"
+# or for non-platform mode:
+export GATEWAY_API_KEY="your-key-here"
+```
+
+Alternatively, pass credentials directly when creating the client (see [Usage](#usage) examples).
+
+## otari-gateway
+
+This Python SDK is a client for [otari-gateway](https://github.com/mozilla-ai/otari), an **optional** FastAPI-based proxy server that adds enterprise-grade features on top of the core library:
+
+- **Budget Management** - Enforce spending limits with automatic daily, weekly, or monthly resets
+- **API Key Management** - Issue, revoke, and monitor virtual API keys without exposing provider credentials
+- **Usage Analytics** - Track every request with full token counts, costs, and metadata
+- **Multi-tenant Support** - Manage access and budgets across users and teams
+
+The gateway sits between your applications and LLM providers, exposing an OpenAI-compatible API that works with any supported provider.
+
+### Quick Start
+
+```bash
+docker run \
+  -e GATEWAY_MASTER_KEY="your-secure-master-key" \
+  -e OPENAI_API_KEY="your-api-key" \
+  -p 8000:8000 \
+  ghcr.io/mozilla-ai/otari/gateway:latest
+```
+
+> **Note:** You can use a specific release version instead of `latest` (e.g., `1.2.0`). See [available versions](https://github.com/orgs/mozilla-ai/packages/container/package/otari%2Fgateway).
+
+### Managed Platform (Beta)
+
+Prefer a hosted experience? The [otari platform](https://otari.ai/) provides a managed control plane for keys, usage tracking, and cost visibility across providers, while still building on the same `otari` interfaces.
+
+## Usage
+
+### Authentication Modes
+
+The client supports two authentication modes, matching the TypeScript SDK:
+
+#### Platform Mode (Recommended)
+
+Uses a Bearer token in the standard Authorization header:
+
+```python
+client = OtariClient(
+    api_base="http://localhost:8000",
+    platform_token="tk_your_platform_token",
+)
+```
+
+#### Non-Platform Mode
+
+Sends the API key via a custom `Otari-Key` header:
+
+```python
+client = OtariClient(
+    api_base="http://localhost:8000",
+    api_key="your-api-key",
+)
+```
+
+#### Auto-Detection from Environment Variables
+
+When no explicit credentials are provided, the client reads from environment variables:
+
+```python
+# Uses GATEWAY_API_BASE, GATEWAY_PLATFORM_TOKEN, or GATEWAY_API_KEY
+client = OtariClient()
+```
+
+### Chat Completions
+
+```python
+response = await client.completion(
+    model="openai:gpt-4o-mini",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+
+print(response.choices[0].message.content)
+```
+
+### Streaming
+
+```python
+stream = await client.completion(
+    model="openai:gpt-4o-mini",
+    messages=[{"role": "user", "content": "Tell me a story."}],
+    stream=True,
+)
+
+async for chunk in stream:
+    content = chunk.choices[0].delta.content
+    if content:
+        print(content, end="", flush=True)
+```
+
+### Responses API
+
+```python
+response = await client.response(
+    model="openai:gpt-4o-mini",
+    input="Summarize this in one sentence.",
+)
+
+print(response.output_text)
+```
+
+### Embeddings
+
+```python
+result = await client.embedding(
+    model="openai:text-embedding-3-small",
+    input="Hello world",
+)
+
+print(result.data[0].embedding)
+```
+
+### Listing Models
+
+```python
+models = await client.list_models()
+for model in models:
+    print(model.id)
+```
+
+### Error Handling
+
+In platform mode, HTTP errors are mapped to typed exceptions:
+
+```python
+from otari import OtariClient, AuthenticationError, RateLimitError
+
+try:
+    response = await client.completion(
+        model="openai:gpt-4o-mini",
+        messages=[{"role": "user", "content": "Hello!"}],
+    )
+except AuthenticationError as e:
+    print(f"Invalid credentials: {e.message}")
+except RateLimitError as e:
+    print(f"Rate limited, retry after: {e.retry_after}")
+```
+
+| HTTP Status | Error Class | Description |
+|------------|-------------|-------------|
+| 400 (capability) | `UnsupportedCapabilityError` | Selected provider does not support the requested capability |
+| 401, 403 | `AuthenticationError` | Invalid or missing credentials |
+| 402 | `InsufficientFundsError` | Budget or credits exhausted |
+| 404 | `ModelNotFoundError` | Model not found or unavailable |
+| 429 | `RateLimitError` | Rate limit exceeded (includes `retry_after`) |
+| 502 | `UpstreamProviderError` | Upstream provider unreachable |
+| 504 | `GatewayTimeoutError` | Gateway timed out waiting for provider |
+
+`UnsupportedCapabilityError` surfaces in both platform and non-platform modes; the other mappings are platform-mode only.
+
+### Context Manager
+
+The client supports async context manager for automatic cleanup:
+
+```python
+async with OtariClient(api_base="http://localhost:8000") as client:
+    response = await client.completion(
+        model="openai:gpt-4o-mini",
+        messages=[{"role": "user", "content": "Hello!"}],
+    )
+```
+
+## Why choose `otari`?
+
+- **Simple, unified interface** - Single client for all providers through the gateway, switch models with just a string change
+- **Developer friendly** - Full type hints for better IDE support and clear, actionable error messages
+- **Leverages the OpenAI SDK** - Built on the official OpenAI Python SDK for maximum compatibility
+- **Async-first** - Built on `AsyncOpenAI` for modern async Python applications
+- **Stays framework-agnostic** so it can be used across different projects and use cases
+- **Battle-tested** - Powers our own production tools ([any-agent](https://github.com/mozilla-ai/any-agent))
+
+## Development
+
+```bash
+# Create a virtual environment
+python -m venv .venv
+source .venv/bin/activate
+
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run unit tests
+pytest tests/
+
+# Lint
+ruff check src/ tests/
+
+# Type-check
+mypy src/
+```
+
+## Documentation
+
+- **[Full Documentation](https://mozilla-ai.github.io/otari/)** - Complete guides and API reference
+- **[Supported Providers](https://mozilla-ai.github.io/otari/providers/)** - List of all supported LLM providers
+- **[Gateway Documentation](https://mozilla-ai.github.io/otari/gateway/overview/)** - Gateway setup and deployment
+- **[TypeScript SDK](https://github.com/mozilla-ai/otari-sdk-ts)** - The TypeScript SDK for Node.js applications
+- **[otari Platform (Beta)](https://otari.ai/)** - Hosted control plane for key management, usage tracking, and cost visibility
+
+## Contributing
+
+We welcome contributions from developers of all skill levels! Please see the [Contributing Guide](https://github.com/mozilla-ai/otari/blob/main/CONTRIBUTING.md) or open an issue to discuss changes.
+
+## License
+
+This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

otari-0.0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+otari/__init__.py,sha256=luzKKUh6Ay3Wx_PPfA7oCn2aZoblwgmuC4yz8iOXjDs,1889
+otari/client.py,sha256=k5ePI3N2_-kKiO5To7MuNM09w0j9IlUvBHhYLaMNQHY,21437
+otari/errors.py,sha256=FihxwKzQ8W7FDHbDOC3kz3fupMCqwoRo3b7v6BqoRTo,4792
+otari/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+otari/types.py,sha256=E9eqo_i5GPYW6Vpp5SKO3eI0tgqIqvuc6B3m-3dWnXQ,3761
+otari-0.0.1.dist-info/METADATA,sha256=FstVSf2M8-a7lXgvZPTOun4fCD4KRn36K3G5RNOl-Rc,9504
+otari-0.0.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+otari-0.0.1.dist-info/RECORD,,

otari-0.0.1.dist-info/WHEEL

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