qbrix 0.1.3__py3-none-any.whl

qbrix/__init__.py

@@ -0,0 +1,91 @@
+from qbrix._client import AsyncQbrix
+from qbrix._client import Qbrix
+from qbrix._config import QbrixConfig
+from qbrix._mod_client import _load_client
+from qbrix._mod_client import _reset_client
+from qbrix._proxies import AgentProxy
+from qbrix._proxies import ExperimentProxy
+from qbrix._proxies import GateProxy
+from qbrix._proxies import PoolProxy
+from qbrix._version import __version__
+from qbrix.resource.agent import AgentResource
+from qbrix.resource.experiment import ExperimentResource
+from qbrix.resource.gate import GateResource
+from qbrix.resource.pool import PoolResource
+from qbrix.exception import AuthenticationError
+from qbrix.exception import BadRequestError
+from qbrix.exception import ConflictError
+from qbrix.exception import ForbiddenError
+from qbrix.exception import InternalServerError
+from qbrix.exception import NotFoundError
+from qbrix.exception import QbrixAPIError
+from qbrix.exception import QbrixConnectionError
+from qbrix.exception import QbrixError
+from qbrix.exception import QbrixTimeoutError
+from qbrix.exception import RateLimitedError
+from qbrix.exception import ServiceUnavailableError
+from qbrix.model import Arm
+from qbrix.model import ArmCreate
+from qbrix.model import Context
+from qbrix.model import Experiment
+from qbrix.model import ExperimentCreate
+from qbrix.model import ExperimentUpdate
+from qbrix.model import GateConfig
+from qbrix.model import GateCreate
+from qbrix.model import GateRule
+from qbrix.model import PaginatedResponse
+from qbrix.model import Pool
+from qbrix.model import PoolCreate
+from qbrix.model import PoolUpdate
+from qbrix.model import SelectedArm
+from qbrix.model import SelectResponse
+
+# module-level resource proxies — no explicit client instantiation required.
+# reads QBRIX_API_KEY and QBRIX_BASE_URL from environment on first use.
+pool: PoolResource = PoolProxy().__as_proxied__()  # type: ignore[assignment]
+experiment: ExperimentResource = ExperimentProxy().__as_proxied__()  # type: ignore[assignment]
+gate: GateResource = GateProxy().__as_proxied__()  # type: ignore[assignment]
+agent: AgentResource = AgentProxy().__as_proxied__()  # type: ignore[assignment]
+
+__all__ = [
+    "__version__",
+    "AsyncQbrix",
+    "Qbrix",
+    "QbrixConfig",
+    # module-level proxies
+    "pool",
+    "experiment",
+    "gate",
+    "agent",
+    "_load_client",
+    "_reset_client",
+    # exceptions
+    "AuthenticationError",
+    "BadRequestError",
+    "ConflictError",
+    "ForbiddenError",
+    "InternalServerError",
+    "NotFoundError",
+    "QbrixAPIError",
+    "QbrixConnectionError",
+    "QbrixError",
+    "QbrixTimeoutError",
+    "RateLimitedError",
+    "ServiceUnavailableError",
+    # models
+    "Arm",
+    "ArmCreate",
+    "Context",
+    "Experiment",
+    "ExperimentCreate",
+    "ExperimentUpdate",
+    "GateConfig",
+    "GateCreate",
+    "GateRule",
+    "PaginatedResponse",
+    "Pool",
+    "PoolCreate",
+    "PoolUpdate",
+    "SelectedArm",
+    "SelectResponse",
+]

qbrix/_base_client.py

@@ -0,0 +1,279 @@
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+from typing import Any
+from typing import TypeVar
+
+import httpx
+from pydantic import BaseModel
+
+from qbrix._config import QbrixConfig
+from qbrix.exception import QbrixAPIError
+from qbrix.exception import QbrixConnectionError
+from qbrix.exception import QbrixTimeoutError
+from qbrix.exception import RateLimitedError
+from qbrix.exception import STATUS_CODE_TO_EXCEPTION
+
+_T = TypeVar("_T", bound=BaseModel)
+
+
+class BaseClient:
+    _config: QbrixConfig
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        **kwargs: Any,
+    ) -> None:
+        overrides: dict[str, Any] = {}
+        if api_key is not None:
+            overrides["api_key"] = api_key
+        if base_url is not None:
+            overrides["base_url"] = base_url
+        if timeout is not None:
+            overrides["timeout"] = timeout
+        if max_retries is not None:
+            overrides["max_retries"] = max_retries
+        overrides.update(kwargs)
+        self._config = QbrixConfig(**overrides)
+
+    def _build_headers(self) -> dict[str, str]:
+        headers: dict[str, str] = {"Accept": "application/json"}
+        if self._config.api_key:
+            headers["X-API-Key"] = self._config.api_key
+        return headers
+
+    @staticmethod
+    def _make_status_error(response: httpx.Response) -> QbrixAPIError:
+        detail = ""
+        context = None
+        try:
+            body = response.json()
+            detail = body.get("detail", response.text)
+            context = body.get("context")
+        except Exception:  # noqa
+            detail = response.text
+
+        status = response.status_code
+        exc_cls = STATUS_CODE_TO_EXCEPTION.get(status, QbrixAPIError)
+
+        if exc_cls is RateLimitedError:
+            retry_after_raw = response.headers.get("Retry-After")
+            retry_after = float(retry_after_raw) if retry_after_raw else None
+            return RateLimitedError(status, detail, context, retry_after)
+
+        return exc_cls(status, detail, context)
+
+    def _should_retry(self, response: httpx.Response) -> bool:
+        return response.status_code in self._config.retry_on
+
+    def _calculate_retry_delay(self, attempt: int) -> float:
+        delay = self._config.retry_base_delay * (2**attempt)
+        delay = min(delay, self._config.retry_max_delay)
+        return delay + random.uniform(0, delay * 0.1)
+
+
+class SyncAPIClient(BaseClient):
+    _client: httpx.Client
+
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._client = httpx.Client(
+            base_url=self._config.base_url,
+            headers=self._build_headers(),
+            timeout=self._config.timeout,
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        cast_to: type[_T] | None = None,
+    ) -> _T | dict[str, Any]:
+        last_exc: Exception | None = None
+
+        for attempt in range(self._config.max_retries + 1):
+            try:
+                response = self._client.request(
+                    method, path, json=body, params=params
+                )
+            except httpx.ConnectError as exc:
+                raise QbrixConnectionError(str(exc)) from exc
+            except httpx.TimeoutException as exc:
+                raise QbrixTimeoutError(str(exc)) from exc
+
+            if response.is_success:
+                if response.status_code == 204 or not response.content:
+                    return cast_to.model_validate({}) if cast_to else {}
+                data = response.json()
+                return cast_to.model_validate(data) if cast_to else data
+
+            if not self._should_retry(response):
+                raise self._make_status_error(response)
+
+            last_exc = self._make_status_error(response)
+
+            if attempt < self._config.max_retries:
+                time.sleep(self._calculate_retry_delay(attempt))
+
+        if last_exc:
+            raise last_exc
+
+        return {}
+
+    def get(
+        self,
+        path: str,
+        *,
+        cast_to: type[_T] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> _T | dict[str, Any]:
+        return self.request("GET", path, cast_to=cast_to, params=params)
+
+    def post(
+        self,
+        path: str,
+        *,
+        body: dict[str, Any] | None = None,
+        cast_to: type[_T] | None = None,
+    ) -> _T | dict[str, Any]:
+        return self.request("POST", path, body=body, cast_to=cast_to)
+
+    def put(
+        self,
+        path: str,
+        *,
+        body: dict[str, Any] | None = None,
+        cast_to: type[_T] | None = None,
+    ) -> _T | dict[str, Any]:
+        return self.request("PUT", path, body=body, cast_to=cast_to)
+
+    def patch(
+        self,
+        path: str,
+        *,
+        body: dict[str, Any] | None = None,
+        cast_to: type[_T] | None = None,
+    ) -> _T | dict[str, Any]:
+        return self.request("PATCH", path, body=body, cast_to=cast_to)
+
+    def delete(self, path: str) -> None:
+        self.request("DELETE", path)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> SyncAPIClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+class AsyncAPIClient(BaseClient):
+    _client: httpx.AsyncClient
+
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._client = httpx.AsyncClient(
+            base_url=self._config.base_url,
+            headers=self._build_headers(),
+            timeout=self._config.timeout,
+        )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        cast_to: type[_T] | None = None,
+    ) -> _T | dict[str, Any]:
+        last_exc: Exception | None = None
+
+        for attempt in range(self._config.max_retries + 1):
+            try:
+                response = await self._client.request(
+                    method, path, json=body, params=params
+                )
+            except httpx.ConnectError as exc:
+                raise QbrixConnectionError(str(exc)) from exc
+            except httpx.TimeoutException as exc:
+                raise QbrixTimeoutError(str(exc)) from exc
+
+            if response.is_success:
+                if response.status_code == 204 or not response.content:
+                    return cast_to.model_validate({}) if cast_to else {}
+                data = response.json()
+                return cast_to.model_validate(data) if cast_to else data
+
+            if not self._should_retry(response):
+                raise self._make_status_error(response)
+
+            last_exc = self._make_status_error(response)
+
+            if attempt < self._config.max_retries:
+                await asyncio.sleep(self._calculate_retry_delay(attempt))
+
+        if last_exc:
+            raise last_exc
+
+        return {}
+
+    async def get(
+        self,
+        path: str,
+        *,
+        cast_to: type[_T] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> _T | dict[str, Any]:
+        return await self.request("GET", path, cast_to=cast_to, params=params)
+
+    async def post(
+        self,
+        path: str,
+        *,
+        body: dict[str, Any] | None = None,
+        cast_to: type[_T] | None = None,
+    ) -> _T | dict[str, Any]:
+        return await self.request("POST", path, body=body, cast_to=cast_to)
+
+    async def put(
+        self,
+        path: str,
+        *,
+        body: dict[str, Any] | None = None,
+        cast_to: type[_T] | None = None,
+    ) -> _T | dict[str, Any]:
+        return await self.request("PUT", path, body=body, cast_to=cast_to)
+
+    async def patch(
+        self,
+        path: str,
+        *,
+        body: dict[str, Any] | None = None,
+        cast_to: type[_T] | None = None,
+    ) -> _T | dict[str, Any]:
+        return await self.request("PATCH", path, body=body, cast_to=cast_to)
+
+    async def delete(self, path: str) -> None:
+        await self.request("DELETE", path)
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncAPIClient:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()

qbrix/_client.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from functools import cached_property
+
+from qbrix._base_client import AsyncAPIClient
+from qbrix._base_client import SyncAPIClient
+from qbrix.resource.agent import AgentResource
+from qbrix.resource.agent import AsyncAgentResource
+from qbrix.resource.experiment import AsyncExperimentResource
+from qbrix.resource.experiment import ExperimentResource
+from qbrix.resource.gate import AsyncGateResource
+from qbrix.resource.gate import GateResource
+from qbrix.resource.pool import AsyncPoolResource
+from qbrix.resource.pool import PoolResource
+
+
+class Qbrix(SyncAPIClient):
+    """synchronous qbrix SDK client.
+
+    Usage::
+
+        with Qbrix(api_key="optiq_xxx") as client:
+            result = client.agent.select("exp-id", context={"id": "user-1"})
+            client.agent.feedback(result.request_id, reward=1.0)
+    """
+
+    @cached_property
+    def pool(self) -> PoolResource:
+        return PoolResource(self)
+
+    @cached_property
+    def experiment(self) -> ExperimentResource:
+        return ExperimentResource(self)
+
+    @cached_property
+    def gate(self) -> GateResource:
+        return GateResource(self)
+
+    @cached_property
+    def agent(self) -> AgentResource:
+        return AgentResource(self)
+
+
+class AsyncQbrix(AsyncAPIClient):
+    """asynchronous qbrix SDK client.
+
+    Usage::
+
+        async with AsyncQbrix(api_key="optiq_xxx") as client:
+            result = await client.agent.select("exp-id", context={"id": "user-1"})
+            await client.agent.feedback(result.request_id, reward=1.0)
+    """
+
+    @cached_property
+    def pool(self) -> AsyncPoolResource:
+        return AsyncPoolResource(self)
+
+    @cached_property
+    def experiment(self) -> AsyncExperimentResource:
+        return AsyncExperimentResource(self)
+
+    @cached_property
+    def gate(self) -> AsyncGateResource:
+        return AsyncGateResource(self)
+
+    @cached_property
+    def agent(self) -> AsyncAgentResource:
+        return AsyncAgentResource(self)
+
+
+Client = Qbrix
+AsyncClient = AsyncQbrix

qbrix/_config.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from pydantic_settings import BaseSettings
+from pydantic_settings import SettingsConfigDict
+
+
+class QbrixConfig(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="QBRIX_")
+
+    base_url: str = "http://localhost:8080"
+    api_key: str | None = None
+    timeout: float = 5.0
+    max_retries: int = 0
+    retry_on: tuple[int, ...] = (429, 502, 503, 504)
+    retry_base_delay: float = 0.5
+    retry_max_delay: float = 30.0

qbrix/_mod_client.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from qbrix._client import Qbrix
+
+_mod_client: "Qbrix | None" = None
+
+
+def _load_client() -> "Qbrix":
+    global _mod_client
+    if _mod_client is None:
+        from qbrix._client import Qbrix
+        _mod_client = Qbrix()
+    return _mod_client
+
+
+def _reset_client() -> None:
+    """Reset the module-level default client. Useful in tests."""
+    global _mod_client
+    _mod_client = None

qbrix/_proxies.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from qbrix._util import LazyProxy
+from qbrix.resource.agent import AgentResource
+from qbrix.resource.experiment import ExperimentResource
+from qbrix.resource.gate import GateResource
+from qbrix.resource.pool import PoolResource
+
+
+def _load_client() -> "Qbrix":  # type: ignore[name-defined]  # noqa: F821
+    from qbrix._mod_client import _load_client as _lc
+
+    return _lc()
+
+
+class PoolProxy(LazyProxy[PoolResource]):
+    def __load__(self) -> PoolResource:
+        return _load_client().pool
+
+
+class ExperimentProxy(LazyProxy[ExperimentResource]):
+    def __load__(self) -> ExperimentResource:
+        return _load_client().experiment
+
+
+class GateProxy(LazyProxy[GateResource]):
+    def __load__(self) -> GateResource:
+        return _load_client().gate
+
+
+class AgentProxy(LazyProxy[AgentResource]):
+    def __load__(self) -> AgentResource:
+        return _load_client().agent

qbrix/_util.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class LazyProxy(Generic[T]):
+    """Defers instantiation of a resource until first attribute access."""
+
+    def __init__(self) -> None:
+        object.__setattr__(self, "_proxied", None)
+
+    def __load__(self) -> T:
+        raise NotImplementedError
+
+    def __getattr__(self, name: str) -> object:
+        proxied = object.__getattribute__(self, "_proxied")
+        if proxied is None:
+            proxied = self.__load__()
+            object.__setattr__(self, "_proxied", proxied)
+        return getattr(proxied, name)
+
+    def __as_proxied__(self) -> "LazyProxy[T]":
+        return self

qbrix/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.3"  # x-release-please-version

qbrix/exception.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class QbrixError(Exception):
+    """base exception for all qbrix SDK errors."""
+
+
+class QbrixAPIError(QbrixError):
+    """error returned by the qbrix API."""
+
+    status_code: int
+    detail: str
+    context: dict[str, Any] | None
+
+    def __init__(
+        self,
+        status_code: int,
+        detail: str,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        self.context = context
+        super().__init__(f"[{status_code}] {detail}")
+
+
+class BadRequestError(QbrixAPIError):
+    """400 — malformed request."""
+
+
+class AuthenticationError(QbrixAPIError):
+    """401 — invalid or missing credentials."""
+
+
+class ForbiddenError(QbrixAPIError):
+    """403 — insufficient permissions."""
+
+
+class NotFoundError(QbrixAPIError):
+    """404 — resource not found."""
+
+
+class ConflictError(QbrixAPIError):
+    """409 — resource conflict."""
+
+
+class RateLimitedError(QbrixAPIError):
+    """429 — rate limit exceeded."""
+
+    retry_after: float | None
+
+    def __init__(
+        self,
+        status_code: int,
+        detail: str,
+        context: dict[str, Any] | None = None,
+        retry_after: float | None = None,
+    ) -> None:
+        super().__init__(status_code, detail, context)
+        self.retry_after = retry_after
+
+
+class InternalServerError(QbrixAPIError):
+    """500 — server error."""
+
+
+class ServiceUnavailableError(QbrixAPIError):
+    """503 — downstream service failure."""
+
+
+class QbrixConnectionError(QbrixError):
+    """failed to connect to the qbrix API."""
+
+
+class QbrixTimeoutError(QbrixError):
+    """request to the qbrix API timed out."""
+
+
+STATUS_CODE_TO_EXCEPTION: dict[int, type[QbrixAPIError]] = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: ForbiddenError,
+    404: NotFoundError,
+    409: ConflictError,
+    429: RateLimitedError,
+    500: InternalServerError,
+    503: ServiceUnavailableError,
+}

qbrix/model/__init__.py

@@ -0,0 +1,41 @@
+from qbrix.model.agent import FeedbackRequest
+from qbrix.model.agent import FeedbackResponse
+from qbrix.model.agent import SelectedArm
+from qbrix.model.agent import SelectRequest
+from qbrix.model.agent import SelectResponse
+from qbrix.model.auth import APIKeyInfo
+from qbrix.model.common import Context
+from qbrix.model.common import PaginatedResponse
+from qbrix.model.experiment import Experiment
+from qbrix.model.experiment import ExperimentCreate
+from qbrix.model.experiment import ExperimentUpdate
+from qbrix.model.gate import GateConfig
+from qbrix.model.gate import GateCreate
+from qbrix.model.gate import GateRule
+from qbrix.model.pool import Arm
+from qbrix.model.pool import ArmCreate
+from qbrix.model.pool import Pool
+from qbrix.model.pool import PoolCreate
+from qbrix.model.pool import PoolUpdate
+
+__all__ = [
+    "Arm",
+    "ArmCreate",
+    "APIKeyInfo",
+    "Context",
+    "Experiment",
+    "ExperimentCreate",
+    "ExperimentUpdate",
+    "FeedbackRequest",
+    "FeedbackResponse",
+    "GateConfig",
+    "GateCreate",
+    "GateRule",
+    "PaginatedResponse",
+    "Pool",
+    "PoolCreate",
+    "PoolUpdate",
+    "SelectedArm",
+    "SelectRequest",
+    "SelectResponse",
+]