superwise-api 4.16.0__tar.gz → 4.18.0__tar.gz

{superwise_api-4.16.0 → superwise_api-4.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: superwise-api
-Version: 4.16.0
+Version: 4.18.0
 Summary: Superwise SDK for Python
 License: MIT
 Keywords: OpenAPI,SuperwiseSDK
@@ -14,6 +14,8 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: Pillow (>=10.0.0,<11.0.0)
 Requires-Dist: aenum (>=3.1.11)
+Requires-Dist: aiohttp (==3.13.5)
+Requires-Dist: jsonschema (>=4.26.0,<5.0.0)
 Requires-Dist: pydantic (>=2.10.4,<3.0.0)
 Requires-Dist: pydantic-settings (>=2.7.0,<3.0.0)
 Requires-Dist: python-dateutil (>=2.8.2)

{superwise_api-4.16.0 → superwise_api-4.18.0}/pyproject.toml

@@ -1,16 +1,18 @@
 [tool.poetry]
 packages = [{ include = "superwise_api", from = "." }]
-version = "4.16.0"
+version = "4.18.0"
 include = ["superwise_api/client/py.typed"]
 
 [tool.poetry.dependencies]
 urllib3 = ">= 1.25.3"
+aiohttp = "= 3.13.5"
 python-dateutil = ">=2.8.2"
 pydantic = "^2.10.4"
 aenum = ">=3.1.11"
 requests = "^2.32.0"
 pydantic-settings = "^2.7.0"
 Pillow = "^10.0.0"
+jsonschema = "^4.26.0"
 
 
 [tool.poetry.group.dev.dependencies]

superwise_api-4.18.0/superwise_api/async_client/__init__.py

@@ -0,0 +1,3 @@
+from superwise_api.async_client.client import AsyncSuperwiseClient
+
+__all__ = ["AsyncSuperwiseClient"]

superwise_api-4.18.0/superwise_api/async_client/client.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import aiohttp
+
+from superwise_api.auth import fetch_token_async
+from superwise_api.config import Settings
+from superwise_api.async_client.entities.dataset import AsyncDatasetAPI
+from superwise_api.async_client.entities.sentinel import AsyncSentinelAPI
+from superwise_api.async_client.transport import AiohttpTransport
+
+
+class AsyncSuperwiseClient:
+    """Async Superwise client.
+
+    Two usage patterns:
+
+        # Context manager:
+        async with AsyncSuperwiseClient(client_id="...", client_secret="...") as client:
+            await client.dataset.log_record(...)
+
+        # Caller-supplied session:
+        async with aiohttp.ClientSession() as session:
+            client = AsyncSuperwiseClient(..., session=session)
+            await client.dataset.log_record(...)
+    """
+
+    def __init__(
+        self,
+        client_id: str | None = None,
+        client_secret: str | None = None,
+        auth_host: str | None = None,
+        api_host: str | None = None,
+        use_hosted_auth: bool | None = None,
+        session: aiohttp.ClientSession | None = None,
+    ) -> None:
+        settings = Settings(
+            **{
+                k: v
+                for k, v in dict(
+                    client_id=client_id,
+                    client_secret=client_secret,
+                    auth_host=auth_host,
+                    api_host=api_host,
+                    use_hosted_auth=use_hosted_auth,
+                ).items()
+                if v is not None
+            }
+        )
+
+        async def _token_factory() -> str:
+            return await fetch_token_async(settings.auth_url, settings.client_id, settings.client_secret)
+
+        self._transport = AiohttpTransport(
+            base_url=settings.api_host,
+            token_factory=_token_factory,
+            session=session,
+        )
+        self._dataset = AsyncDatasetAPI(self._transport)
+        self._sentinel = AsyncSentinelAPI(self._transport)
+
+    async def __aenter__(self) -> AsyncSuperwiseClient:
+        await self._transport.__aenter__()
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self._transport.__aexit__()
+
+    @property
+    def dataset(self) -> AsyncDatasetAPI:
+        return self._dataset
+
+    @property
+    def sentinel(self) -> AsyncSentinelAPI:
+        return self._sentinel

superwise_api-4.18.0/superwise_api/async_client/entities/__init__.py

@@ -0,0 +1,4 @@
+from superwise_api.async_client.entities.dataset import AsyncDatasetAPI
+from superwise_api.async_client.entities.sentinel import AsyncSentinelAPI
+
+__all__ = ["AsyncDatasetAPI", "AsyncSentinelAPI"]

superwise_api-4.18.0/superwise_api/async_client/entities/dataset.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from superwise_api.request_builders.dataset_request_builder import (
+    parse_log_batch_response,
+    parse_log_record_response,
+    prepare_log_batch_request,
+    prepare_log_record_request,
+)
+from superwise_api.async_client.transport import AsyncTransport
+
+
+class AsyncDatasetAPI:
+    def __init__(self, transport: AsyncTransport) -> None:
+        self._transport = transport
+
+    async def log_record(
+        self,
+        dataset_id: str,
+        data: dict,
+        images: dict[str, tuple[bytes, str]] | None = None,
+    ) -> None:
+        req = prepare_log_record_request(dataset_id, data, images)
+        status, body = await self._transport.execute(req)
+        return parse_log_record_response(status, body)
+
+    async def log_batch(self, dataset_id: str, records: list[dict]) -> dict | None:
+        req = prepare_log_batch_request(dataset_id, records)
+        status, body = await self._transport.execute(req)
+        return parse_log_batch_response(status, body)

superwise_api-4.18.0/superwise_api/async_client/entities/sentinel.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from typing import Any
+
+from superwise_api.async_client.transport import AsyncTransport
+from superwise_api.request_builders.sentinel_request_builder import (
+    parse_delete_sentinel_response,
+    parse_sentinel_response,
+    parse_sentinels_response,
+    prepare_create_sentinel_request,
+    prepare_delete_sentinel_request,
+    prepare_get_sentinel_request,
+    prepare_get_sentinels_request,
+    prepare_heartbeat_sentinel_request,
+    prepare_search_sentinels_request,
+    prepare_update_sentinel_request,
+)
+from superwise_api.models.sentinel.sentinel import Sentinel
+
+
+class AsyncSentinelAPI:
+    def __init__(self, transport: AsyncTransport) -> None:
+        self._transport = transport
+
+    async def create(
+        self,
+        name: str | None = None,
+        description: str | None = None,
+        location: str | None = None,
+        local_guardrail_config: dict[str, Any] | None = None,
+        remote_guardrail_versions: list[str] | None = None,
+    ) -> Sentinel:
+        req = prepare_create_sentinel_request(
+            name, description, location, local_guardrail_config, remote_guardrail_versions
+        )
+        status, body = await self._transport.execute(req)
+        return parse_sentinel_response(status, body)
+
+    async def get(self, page: int | None = None, size: int | None = None) -> list[Sentinel]:
+        req = prepare_get_sentinels_request(page, size)
+        status, body = await self._transport.execute(req)
+        return parse_sentinels_response(status, body)
+
+    async def get_by_id(self, sentinel_id: str) -> Sentinel:
+        req = prepare_get_sentinel_request(sentinel_id)
+        status, body = await self._transport.execute(req)
+        return parse_sentinel_response(status, body)
+
+    async def search(
+        self,
+        filters: list[Any] | None = None,
+        search: list[str] | str | None = None,
+        sort_by: str = "updated_at",
+        sort_direction: str = "desc",
+    ) -> list[Sentinel]:
+        req = prepare_search_sentinels_request(filters, search, sort_by, sort_direction)
+        status, body = await self._transport.execute(req)
+        return parse_sentinels_response(status, body)
+
+    async def update(
+        self,
+        sentinel_id: str,
+        name: str | None = None,
+        description: str | None = None,
+        location: str | None = None,
+        local_guardrail_config: dict[str, Any] | None = None,
+        remote_guardrail_versions: list[str] | None = None,
+    ) -> Sentinel:
+        req = prepare_update_sentinel_request(
+            sentinel_id, name, description, location, local_guardrail_config, remote_guardrail_versions
+        )
+        status, body = await self._transport.execute(req)
+        return parse_sentinel_response(status, body)
+
+    async def heartbeat(self, sentinel_id: str) -> Sentinel:
+        req = prepare_heartbeat_sentinel_request(sentinel_id)
+        status, body = await self._transport.execute(req)
+        return parse_sentinel_response(status, body)
+
+    async def delete(self, sentinel_id: str) -> None:
+        req = prepare_delete_sentinel_request(sentinel_id)
+        status, body = await self._transport.execute(req)
+        return parse_delete_sentinel_response(status, body)

superwise_api-4.18.0/superwise_api/async_client/transport.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from typing import Protocol
+
+import aiohttp
+
+from superwise_api.request_builders.requests import PreparedRequest, MultipartRequest
+
+
+class AsyncTransport(Protocol):
+    async def execute(self, req: PreparedRequest) -> tuple[int, bytes]: ...
+
+
+class AiohttpTransport:
+    def __init__(
+        self,
+        base_url: str,
+        token_factory: Callable[[], Awaitable[str]],
+        session: aiohttp.ClientSession | None = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._token_factory = token_factory
+        self._token: str | None = None
+        self._token_lock = asyncio.Lock()
+        self._session = session
+        self._owns_session = session is None
+
+    async def close(self) -> None:
+        if self._owns_session and self._session is not None:
+            await self._session.__aexit__(None, None, None)
+            self._session = None
+            self._owns_session = False
+
+    async def __aenter__(self) -> AiohttpTransport:
+        if self._session is None:
+            self._session = await aiohttp.ClientSession().__aenter__()
+            self._owns_session = True
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()
+
+    async def execute(self, req: PreparedRequest) -> tuple[int, bytes]:
+        if self._token is None:
+            async with self._token_lock:
+                if self._token is None:
+                    self._token = await self._token_factory()
+        status, body = await self._execute(req)
+        if status == 401:
+            stale_token = self._token
+            async with self._token_lock:
+                if self._token == stale_token:
+                    self._token = await self._token_factory()
+            status, body = await self._execute(req)
+        return status, body
+
+    async def _execute(self, req: PreparedRequest) -> tuple[int, bytes]:
+        url = self._base_url + req.path
+        headers = {**req.headers, "Authorization": f"Bearer {self._token}"}
+        body_kwargs = {"data": self._build_form(req)} if req.is_multipart() else req.body_kwargs()
+        async with self._session.request(req.method, url, headers=headers, **body_kwargs) as resp:
+            return resp.status, await resp.read()
+
+    @staticmethod
+    def _build_form(req: MultipartRequest) -> aiohttp.FormData:
+        form = aiohttp.FormData()
+        for f in req.fields:
+            kwargs = {}
+            if f.content_type is not None:
+                kwargs["content_type"] = f.content_type
+            if f.filename is not None:
+                kwargs["filename"] = f.filename
+            form.add_field(f.name, f.data, **kwargs)
+        return form

superwise_api-4.18.0/superwise_api/auth.py

@@ -0,0 +1,40 @@
+import json
+import requests
+import aiohttp
+from dataclasses import dataclass
+
+from superwise_api.client.exceptions import UnauthorizedException
+
+
+@dataclass
+class TokenRequest:
+    url: str
+    headers: dict[str, str]
+    body: dict
+
+
+def prepare_token_request(auth_url: str, client_id: str, client_secret: str) -> TokenRequest:
+    return TokenRequest(
+        url=auth_url,
+        headers={"accept": "application/json", "content-type": "application/json"},
+        body={"clientId": client_id, "secret": client_secret},
+    )
+
+
+def parse_token_response(status_code: int, body: bytes) -> str:
+    if status_code != 200:
+        raise UnauthorizedException(status=status_code, reason=body.decode("utf-8") if body else "")
+    return json.loads(body)["accessToken"]
+
+
+def fetch_token(auth_url: str, client_id: str, client_secret: str) -> str:
+    req = prepare_token_request(auth_url, client_id, client_secret)
+    resp = requests.post(req.url, json=req.body, headers=req.headers)
+    return parse_token_response(resp.status_code, resp.content)
+
+
+async def fetch_token_async(auth_url: str, client_id: str, client_secret: str) -> str:
+    req = prepare_token_request(auth_url, client_id, client_secret)
+    async with aiohttp.ClientSession() as session:
+        async with session.post(req.url, json=req.body, headers=req.headers) as resp:
+            return parse_token_response(resp.status, await resp.read())

{superwise_api-4.16.0 → superwise_api-4.18.0}/superwise_api/client/api_client.py

@@ -7,7 +7,7 @@ import re
 import tempfile
 import uuid
 from multiprocessing.pool import ThreadPool
-from typing import Optional
+
 from urllib.parse import quote
 
 from dateutil.parser import parse
@@ -774,7 +774,7 @@ class ApiClient:
             **kwargs,
         )
 
-    def put(self, resource_path: str, data: Optional[dict] = None, **kwargs) -> BaseModel:
+    def put(self, resource_path: str, data: dict | None = None, **kwargs) -> BaseModel:
         _params = locals()
 
         _all_params = ["async_req", "_request_auth", "_content_type", "_headers", "response_types_map"]
@@ -860,11 +860,19 @@ class ApiClient:
         )
 
     def post(
-        self, resource_path: str, data: Optional[dict] = None, query_params: dict | None = None, **kwargs
+        self, resource_path: str, data: dict | None = None, query_params: dict | None = None, **kwargs
     ) -> BaseModel:
         _params = locals()
 
-        _all_params = ["files", "async_req", "_request_auth", "_content_type", "_headers", "response_types_map"]
+        _all_params = [
+            "files",
+            "async_req",
+            "_request_auth",
+            "_content_type",
+            "_headers",
+            "response_types_map",
+            "post_params",
+        ]
         if "model_name" in kwargs:
             _all_params.append("model_name")
 
@@ -884,18 +892,21 @@ class ApiClient:
         # process the header parameters
         _header_params = dict(_params.get("_headers", {}))
         # process the form parameters
-        _form_params = []
+        _form_params = _params.get("post_params", [])
         _files = kwargs.get("files", {})
         # process the body parameter
         _body_params = None
-        if data is not None:
+        if data is not None and not _form_params:
             _body_params = data
 
         # set the HTTP header `Accept`
         _header_params["Accept"] = self.select_header_accept(["application/json"])
 
         # set the HTTP header `Content-Type`
-        _content_types_list = _params.get("_content_type", self.select_header_content_type(["application/json"]))
+        if _form_params:
+            _content_types_list = "multipart/form-data"
+        else:
+            _content_types_list = _params.get("_content_type", self.select_header_content_type(["application/json"]))
         if _content_types_list:
             _header_params["Content-Type"] = _content_types_list
 
@@ -924,7 +935,7 @@ class ApiClient:
         )
 
     def delete(
-        self, resource_path: str, model_name: str, entity_id: str, query_params: Optional[dict] = None, **kwargs
+        self, resource_path: str, model_name: str, entity_id: str, query_params: dict | None = None, **kwargs
     ) -> BaseModel:
         _params = locals()
 
@@ -1151,14 +1162,16 @@ class ApiClient:
         self,
         resource_path: str,
         response_model,
-        data: Optional[dict] = None,
+        data: dict | None = None,
+        post_params: list | None = None,
         **kwargs,
     ):
         """Performs a streaming POST request and yields parsed response objects.
 
         :param resource_path: Path to method endpoint.
         :param response_model: Model class to deserialize each line to.
-        :param data: Request body data.
+        :param data: Request body data (JSON).
+        :param post_params: Multipart form-data fields (list of tuples). Mutually exclusive with data.
         :param kwargs: Additional arguments (_headers, _request_timeout, _request_auth).
         :yields: Parsed response_model instances.
         :raises StreamingError: If an error event is received in the stream.
@@ -1175,7 +1188,7 @@ class ApiClient:
 
         # Set content type and accept headers
         _header_params["Accept"] = "application/x-ndjson"
-        _header_params["Content-Type"] = "application/json"
+        _header_params["Content-Type"] = "multipart/form-data" if post_params else "application/json"
 
         # Handle authentication
         _request_auth = _params.get("_request_auth")
@@ -1196,6 +1209,7 @@ class ApiClient:
             url,
             headers=_header_params,
             body=data,
+            post_params=post_params,
             _request_timeout=_params.get("_request_timeout"),
         )
 

{superwise_api-4.16.0 → superwise_api-4.18.0}/superwise_api/client/rest.py

@@ -404,6 +404,7 @@ class RESTClientObject:
         url,
         headers=None,
         body=None,
+        post_params=None,
         _request_timeout=None,
     ):
         """Perform a streaming POST request.
@@ -411,6 +412,7 @@ class RESTClientObject:
         :param url: http request url
         :param headers: http request headers
         :param body: request json body
+        :param post_params: multipart/form-data fields (list of tuples)
         :param _request_timeout: timeout setting for this request
         :return: StreamingRESTResponse object for iterating over lines
         """
@@ -424,18 +426,30 @@ class RESTClientObject:
                 timeout = urllib3.Timeout(connect=_request_timeout[0], read=_request_timeout[1])
 
         try:
-            request_body = None
-            if body is not None:
-                request_body = json.dumps(body)
-
-            r = self.pool_manager.request(
-                "POST",
-                url,
-                body=request_body,
-                preload_content=False,
-                timeout=timeout,
-                headers=headers,
-            )
+            if post_params:
+                # Remove Content-Type so urllib3 sets it with the multipart boundary
+                headers = {k: v for k, v in headers.items() if k != "Content-Type"}
+                r = self.pool_manager.request(
+                    "POST",
+                    url,
+                    fields=post_params,
+                    encode_multipart=True,
+                    preload_content=False,
+                    timeout=timeout,
+                    headers=headers,
+                )
+            else:
+                request_body = None
+                if body is not None:
+                    request_body = json.dumps(body)
+                r = self.pool_manager.request(
+                    "POST",
+                    url,
+                    body=request_body,
+                    preload_content=False,
+                    timeout=timeout,
+                    headers=headers,
+                )
         except urllib3.exceptions.SSLError as e:
             msg = "{0}\n{1}".format(type(e).__name__, str(e))
             raise ApiException(status=0, reason=msg)