auriko 0.1.0__py3-none-any.whl

auriko/__init__.py

@@ -0,0 +1,24 @@
+"""Auriko SDK — Intelligent LLM routing."""
+
+from ._client import AsyncClient, Client
+from ._version import __version__
+from .errors import (
+    APIConnectionError,
+    APIStatusError,
+    AurikoAPIError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    map_openai_error,
+)
+from .response_headers import ResponseHeaders
+from ._streaming import AsyncStream, Stream
+
+try:
+    from ._openai_client import AurikoAsyncOpenAI
+except ModuleNotFoundError:
+    pass  # Available with: pip install auriko[openai-compat]

auriko/_base_client.py

@@ -0,0 +1,111 @@
+"""Shared non-I/O logic for Client and AsyncClient."""
+
+from __future__ import annotations
+
+import os
+import random
+from typing import Any, Mapping, Optional, TypeVar
+
+import httpx
+
+from ._version import __version__
+from .errors.mapping import _map_error_from_envelope
+from .errors.types import APIStatusError, AurikoAPIError, AuthenticationError
+from .response_headers import ResponseHeaders
+
+T = TypeVar("T")
+
+_DEFAULT_BASE_URL = "https://api.auriko.ai/v1"
+_DEFAULT_TIMEOUT = 60.0
+_DEFAULT_MAX_RETRIES = 2
+
+_INITIAL_RETRY_DELAY = 0.5
+_RETRY_DELAY_MULTIPLIER = 1.5
+_MAX_RETRY_DELAY = 30.0
+
+
+class BaseClient:
+    """Shared configuration and pure-logic helpers for sync and async clients."""
+
+    api_key: str
+    base_url: str
+    timeout: float
+    max_retries: int
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ) -> None:
+        resolved_key = api_key or os.environ.get("AURIKO_API_KEY")
+        if not resolved_key:
+            raise AuthenticationError(
+                message="API key is missing. Set AURIKO_API_KEY or pass api_key=.",
+                status_code=0,
+                type="authentication_error",
+                code="missing_api_key",
+            )
+        self.api_key = resolved_key
+
+        url = (base_url or _DEFAULT_BASE_URL).rstrip("/")
+        if not url.endswith("/v1"):
+            url += "/v1"
+        self.base_url = url + "/"
+
+        self.timeout = timeout if timeout is not None else _DEFAULT_TIMEOUT
+        self.max_retries = max_retries if max_retries is not None else _DEFAULT_MAX_RETRIES
+
+    @property
+    def _default_headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": f"auriko-python/{__version__}",
+        }
+
+    @staticmethod
+    def _calculate_retry_delay(
+        attempt: int,
+        retry_after_header: Optional[str] = None,
+    ) -> float:
+        delay = _INITIAL_RETRY_DELAY * (_RETRY_DELAY_MULTIPLIER ** attempt)
+        delay = min(delay, _MAX_RETRY_DELAY)
+        delay *= 0.8 + random.random() * 0.4
+
+        if retry_after_header is not None:
+            try:
+                retry_after = float(retry_after_header)
+                delay = max(delay, retry_after)
+            except (ValueError, OverflowError):
+                pass
+
+        return delay
+
+    def _make_error(
+        self,
+        status_code: int,
+        body: Any,
+        *,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> AurikoAPIError:
+        """Create a typed error from an HTTP error response via strict envelope dispatch."""
+        response_headers = ResponseHeaders(headers) if headers is not None else None
+        return _map_error_from_envelope(
+            status_code, body, response_headers=response_headers,
+        )
+
+    def _parse_response(self, response: httpx.Response, cast_to: type[T]) -> T:
+        """Parse response JSON and validate against a Pydantic model."""
+        try:
+            data = response.json()
+        except Exception as e:
+            raise APIStatusError(
+                message="Response body is not valid JSON.",
+                status_code=response.status_code,
+                type="api_error",
+                code="invalid_response",
+                response_headers=ResponseHeaders(response.headers),
+            ) from e
+        return cast_to.model_validate(data)  # type: ignore[union-attr]

auriko/_client.py

@@ -0,0 +1,372 @@
+"""Auriko API client — sync and async."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Optional
+
+import httpx
+
+from ._base_client import BaseClient
+from .errors.mapping import is_retryable
+from .errors.types import APIConnectionError
+
+
+class Client(BaseClient):
+    """Synchronous Auriko API client."""
+
+    _httpx: httpx.Client
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ) -> None:
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._httpx = httpx.Client(
+            base_url=self.base_url,
+            headers=self._default_headers,
+            timeout=self.timeout,
+            follow_redirects=True,
+        )
+
+        from .resources.chat import Chat
+        from .resources.me import Me
+        from .resources.models import Models
+
+        self.chat = Chat(self)
+        self.models = Models(self)
+        self.me = Me(self)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Optional[dict[str, Any]] = None,
+        params: Optional[dict[str, Any]] = None,
+        headers: Optional[dict[str, str]] = None,
+    ) -> httpx.Response:
+        request = self._httpx.build_request(
+            method, path, json=body, params=params, headers=headers,
+        )
+        retries_remaining = self.max_retries
+
+        while True:
+            try:
+                response = self._httpx.send(request)
+            except httpx.TimeoutException as e:
+                if retries_remaining > 0:
+                    retries_remaining -= 1
+                    time.sleep(self._calculate_retry_delay(
+                        self.max_retries - retries_remaining - 1,
+                    ))
+                    continue
+                raise APIConnectionError(
+                    message="Request timed out before a response was received.",
+                    cause=e,
+                ) from e
+            except httpx.NetworkError as e:
+                if retries_remaining > 0:
+                    retries_remaining -= 1
+                    time.sleep(self._calculate_retry_delay(
+                        self.max_retries - retries_remaining - 1,
+                    ))
+                    continue
+                raise APIConnectionError(cause=e) from e
+            except httpx.TransportError as e:
+                raise APIConnectionError(cause=e) from e
+
+            if response.status_code >= 400:
+                try:
+                    error_body = response.json()
+                except Exception:
+                    text = response.text
+                    error_body = text[:4096] if text else None
+
+                exc = self._make_error(
+                    response.status_code, error_body, headers=response.headers,
+                )
+                if is_retryable(exc) and retries_remaining > 0:
+                    retries_remaining -= 1
+                    retry_after = (
+                        exc.response_headers.get("Retry-After")
+                        if exc.response_headers is not None
+                        else None
+                    )
+                    response.close()
+                    time.sleep(self._calculate_retry_delay(
+                        self.max_retries - retries_remaining - 1,
+                        retry_after,
+                    ))
+                    continue
+                raise exc
+
+            return response
+
+    def _request_stream(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Optional[dict[str, Any]] = None,
+        params: Optional[dict[str, Any]] = None,
+        headers: Optional[dict[str, str]] = None,
+    ) -> httpx.Response:
+        request = self._httpx.build_request(
+            method, path, json=body, params=params, headers=headers,
+        )
+        retries_remaining = self.max_retries
+
+        while True:
+            try:
+                response = self._httpx.send(request, stream=True)
+            except httpx.TimeoutException as e:
+                if retries_remaining > 0:
+                    retries_remaining -= 1
+                    time.sleep(self._calculate_retry_delay(
+                        self.max_retries - retries_remaining - 1,
+                    ))
+                    continue
+                raise APIConnectionError(
+                    message="Request timed out before a response was received.",
+                    cause=e,
+                ) from e
+            except httpx.NetworkError as e:
+                if retries_remaining > 0:
+                    retries_remaining -= 1
+                    time.sleep(self._calculate_retry_delay(
+                        self.max_retries - retries_remaining - 1,
+                    ))
+                    continue
+                raise APIConnectionError(cause=e) from e
+            except httpx.TransportError as e:
+                raise APIConnectionError(cause=e) from e
+
+            if response.status_code >= 400:
+                response.read()
+                try:
+                    error_body = response.json()
+                except Exception:
+                    text = response.text
+                    error_body = text[:4096] if text else None
+
+                exc = self._make_error(
+                    response.status_code, error_body, headers=response.headers,
+                )
+                if is_retryable(exc) and retries_remaining > 0:
+                    retries_remaining -= 1
+                    retry_after = (
+                        exc.response_headers.get("Retry-After")
+                        if exc.response_headers is not None
+                        else None
+                    )
+                    response.close()
+                    time.sleep(self._calculate_retry_delay(
+                        self.max_retries - retries_remaining - 1,
+                        retry_after,
+                    ))
+                    continue
+                response.close()
+                raise exc
+
+            return response
+
+    def close(self) -> None:
+        self._httpx.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+class AsyncClient(BaseClient):
+    """Asynchronous Auriko API client."""
+
+    _httpx: httpx.AsyncClient
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ) -> None:
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._httpx = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers=self._default_headers,
+            timeout=self.timeout,
+            follow_redirects=True,
+        )
+
+        from .resources.chat import AsyncChat
+        from .resources.me import AsyncMe
+        from .resources.models import AsyncModels
+
+        self.chat = AsyncChat(self)
+        self.models = AsyncModels(self)
+        self.me = AsyncMe(self)
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Optional[dict[str, Any]] = None,
+        params: Optional[dict[str, Any]] = None,
+        headers: Optional[dict[str, str]] = None,
+    ) -> httpx.Response:
+        import anyio
+
+        request = self._httpx.build_request(
+            method, path, json=body, params=params, headers=headers,
+        )
+        retries_remaining = self.max_retries
+
+        while True:
+            try:
+                response = await self._httpx.send(request)
+            except httpx.TimeoutException as e:
+                if retries_remaining > 0:
+                    retries_remaining -= 1
+                    await anyio.sleep(self._calculate_retry_delay(
+                        self.max_retries - retries_remaining - 1,
+                    ))
+                    continue
+                raise APIConnectionError(
+                    message="Request timed out before a response was received.",
+                    cause=e,
+                ) from e
+            except httpx.NetworkError as e:
+                if retries_remaining > 0:
+                    retries_remaining -= 1
+                    await anyio.sleep(self._calculate_retry_delay(
+                        self.max_retries - retries_remaining - 1,
+                    ))
+                    continue
+                raise APIConnectionError(cause=e) from e
+            except httpx.TransportError as e:
+                raise APIConnectionError(cause=e) from e
+
+            if response.status_code >= 400:
+                try:
+                    error_body = response.json()
+                except Exception:
+                    text = response.text
+                    error_body = text[:4096] if text else None
+
+                exc = self._make_error(
+                    response.status_code, error_body, headers=response.headers,
+                )
+                if is_retryable(exc) and retries_remaining > 0:
+                    retries_remaining -= 1
+                    retry_after = (
+                        exc.response_headers.get("Retry-After")
+                        if exc.response_headers is not None
+                        else None
+                    )
+                    await response.aclose()
+                    await anyio.sleep(self._calculate_retry_delay(
+                        self.max_retries - retries_remaining - 1,
+                        retry_after,
+                    ))
+                    continue
+                raise exc
+
+            return response
+
+    async def _request_stream(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Optional[dict[str, Any]] = None,
+        params: Optional[dict[str, Any]] = None,
+        headers: Optional[dict[str, str]] = None,
+    ) -> httpx.Response:
+        import anyio
+
+        request = self._httpx.build_request(
+            method, path, json=body, params=params, headers=headers,
+        )
+        retries_remaining = self.max_retries
+
+        while True:
+            try:
+                response = await self._httpx.send(request, stream=True)
+            except httpx.TimeoutException as e:
+                if retries_remaining > 0:
+                    retries_remaining -= 1
+                    await anyio.sleep(self._calculate_retry_delay(
+                        self.max_retries - retries_remaining - 1,
+                    ))
+                    continue
+                raise APIConnectionError(
+                    message="Request timed out before a response was received.",
+                    cause=e,
+                ) from e
+            except httpx.NetworkError as e:
+                if retries_remaining > 0:
+                    retries_remaining -= 1
+                    await anyio.sleep(self._calculate_retry_delay(
+                        self.max_retries - retries_remaining - 1,
+                    ))
+                    continue
+                raise APIConnectionError(cause=e) from e
+            except httpx.TransportError as e:
+                raise APIConnectionError(cause=e) from e
+
+            if response.status_code >= 400:
+                await response.aread()
+                try:
+                    error_body = response.json()
+                except Exception:
+                    text = response.text
+                    error_body = text[:4096] if text else None
+
+                exc = self._make_error(
+                    response.status_code, error_body, headers=response.headers,
+                )
+                if is_retryable(exc) and retries_remaining > 0:
+                    retries_remaining -= 1
+                    retry_after = (
+                        exc.response_headers.get("Retry-After")
+                        if exc.response_headers is not None
+                        else None
+                    )
+                    await response.aclose()
+                    await anyio.sleep(self._calculate_retry_delay(
+                        self.max_retries - retries_remaining - 1,
+                        retry_after,
+                    ))
+                    continue
+                await response.aclose()
+                raise exc
+
+            return response
+
+    async def close(self) -> None:
+        await self._httpx.aclose()
+
+    async def __aenter__(self) -> AsyncClient:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()

auriko/_openai_client.py

@@ -0,0 +1,196 @@
+"""AurikoAsyncOpenAI — AsyncOpenAI subclass with automatic routing metadata capture and error mapping."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+from collections.abc import AsyncIterator
+from typing import Any, Callable
+
+import httpx
+import openai
+from openai import AsyncOpenAI, DefaultAsyncHttpxClient
+
+from .errors.openai_bridge import make_bridge_error
+from .errors.types import AuthenticationError
+from .route_types import RoutingMetadata
+
+logger = logging.getLogger(__name__)
+
+
+def _resolve_api_key(api_key: str | None) -> str:
+    """Resolve API key: explicit arg > AURIKO_API_KEY env > raise.
+
+    Does NOT fall back to OPENAI_API_KEY — consistent with
+    _base_client.py:43-53 and SDK_STRATEGY.md.
+    """
+    resolved = api_key or os.environ.get("AURIKO_API_KEY")
+    if not resolved:
+        raise AuthenticationError(
+            message="API key is missing. Set AURIKO_API_KEY or pass api_key=.",
+            status_code=0,
+            type="authentication_error",
+            code="missing_api_key",
+        )
+    return resolved
+
+
+class _MetadataCapturingStream(httpx.AsyncByteStream):
+    """Wraps an SSE byte stream to capture routing_metadata during iteration.
+
+    Yields every chunk immediately (zero buffering, no TTFT impact).
+    Scans accumulated buffer for the metadata event on natural completion
+    or on aclose() (which fires first when the OpenAI SDK breaks on [DONE]).
+    """
+
+    def __init__(
+        self,
+        inner: httpx.AsyncByteStream,
+        on_metadata: Callable[[RoutingMetadata], None],
+    ) -> None:
+        self._inner = inner
+        self._on_metadata = on_metadata
+        self._buffer = bytearray()
+        self._extracted = False
+
+    async def __aiter__(self) -> AsyncIterator[bytes]:
+        async for chunk in self._inner:
+            self._buffer.extend(chunk)
+            yield chunk
+        self._extract_metadata()
+
+    async def aclose(self) -> None:
+        self._extract_metadata()
+        await self._inner.aclose()
+
+    def _extract_metadata(self) -> None:
+        """Scan buffer for the last data: event before [DONE], extract routing_metadata."""
+        if self._extracted:
+            return
+        self._extracted = True
+        try:
+            text = self._buffer.decode("utf-8", errors="replace")
+            last_data: str | None = None
+            for line in text.splitlines():
+                stripped = line.strip()
+                if stripped.startswith("data: ") and stripped != "data: [DONE]":
+                    last_data = stripped[6:]
+            if last_data is None:
+                return
+            payload = json.loads(last_data)
+            raw_metadata = payload.get("routing_metadata")
+            if raw_metadata is None:
+                return
+            metadata = RoutingMetadata.model_validate(raw_metadata)
+            self._on_metadata(metadata)
+        except Exception:
+            logger.debug("Failed to extract routing_metadata from SSE stream", exc_info=True)
+
+
+class AurikoAsyncOpenAI(AsyncOpenAI):
+    """**Experimental.** AsyncOpenAI subclass with automatic routing metadata capture and error mapping.
+
+    Most users should use ``auriko.AsyncClient`` (native SDK) or ``AsyncOpenAI(base_url=...)``
+    (plain OpenAI-compatible). Use ``AurikoAsyncOpenAI`` only when passing an OpenAI client to
+    a framework that discards routing metadata from responses.
+
+    Usage::
+
+        client = AurikoAsyncOpenAI(api_key="ak-...")
+        response = await client.chat.completions.create(
+            model="gpt-4o-mini",
+            messages=[{"role": "user", "content": "Hello"}],
+        )
+        print(client.last_routing_metadata)
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str = "https://api.auriko.ai/v1",
+        on_response: Callable[[RoutingMetadata], Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if "http_client" in kwargs:
+            raise TypeError(
+                "AurikoAsyncOpenAI does not accept http_client. "
+                "Remove it or use AsyncOpenAI(base_url=...) directly."
+            )
+        if on_response is not None and asyncio.iscoroutinefunction(on_response):
+            raise TypeError("on_response must be a sync callable, not async")
+
+        resolved_key = _resolve_api_key(api_key)
+
+        self._last_metadata: RoutingMetadata | None = None
+        self._on_response = on_response
+
+        async def _request_hook(request: httpx.Request) -> None:
+            self._last_metadata = None
+
+        def _deliver_metadata(metadata: RoutingMetadata) -> None:
+            self._last_metadata = metadata
+            if self._on_response is not None:
+                try:
+                    self._on_response(metadata)
+                except Exception:
+                    logger.debug("on_response callback raised", exc_info=True)
+
+        async def _response_hook(response: httpx.Response) -> None:
+            try:
+                if response.status_code >= 400:
+                    return
+
+                content_type = response.headers.get("content-type", "")
+
+                if "text/event-stream" in content_type:
+                    response.stream = _MetadataCapturingStream(
+                        response.stream, _deliver_metadata,
+                    )
+                else:
+                    await response.aread()
+                    body = response.json()
+                    raw_metadata = body.get("routing_metadata")
+                    if raw_metadata is not None:
+                        metadata = RoutingMetadata.model_validate(raw_metadata)
+                        _deliver_metadata(metadata)
+            except Exception:
+                logger.debug(
+                    "Failed to capture routing_metadata from response",
+                    exc_info=True,
+                )
+
+        http_client = DefaultAsyncHttpxClient(
+            event_hooks={
+                "request": [_request_hook],
+                "response": [_response_hook],
+            },
+        )
+
+        super().__init__(
+            api_key=resolved_key,
+            base_url=base_url,
+            http_client=http_client,
+            **kwargs,
+        )
+
+    def _make_status_error(
+        self,
+        err_msg: str,
+        *,
+        body: object,
+        response: httpx.Response,
+    ) -> openai.APIStatusError:
+        openai_error = super()._make_status_error(err_msg, body=body, response=response)
+        return make_bridge_error(openai_error, response=response, raw_body=body)
+
+    @property
+    def last_routing_metadata(self) -> RoutingMetadata | None:
+        """Routing metadata from the most recent successful response.
+
+        Returns None if no metadata is available (before any request, after an error,
+        or if the response did not contain routing_metadata).
+        """
+        return self._last_metadata