visionai-sdk-python 2.1.1__tar.gz → 2.2.0.dev1__tar.gz

{visionai_sdk_python-2.1.1 → visionai_sdk_python-2.2.0.dev1}/.github/workflows/ci.yml

@@ -14,8 +14,13 @@ permissions:
 
 jobs:
   check:
-    name: Lint, test, and build
+    name: Lint, test, and build (Python ${{ matrix.python-version }})
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # The oldest supported interpreter and the newest one a consumer runs on.
+        python-version: ["3.11", "3.14"]
     steps:
       - uses: actions/checkout@v4
 
@@ -27,7 +32,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version-file: pyproject.toml
+          python-version: ${{ matrix.python-version }}
 
       - name: Install locked dependencies
         run: uv sync --locked --all-extras

{visionai_sdk_python-2.1.1 → visionai_sdk_python-2.2.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: visionai-sdk-python
-Version: 2.1.1
+Version: 2.2.0.dev1
 Summary: VisionAI SDK for Python
 Author-email: Tony Yang <tonyyang@linkervision.com>
 Requires-Python: >=3.11
@@ -134,15 +134,29 @@ token = client.auth.login("user@example.com", "password")
 
 ### OAuth Client Credentials
 
+A `ClientCredentials` (or `AsyncClientCredentials`) holds the token for one Platform
+client: it is minted on first use, cached until five minutes before it expires, and
+one instance can serve any number of clients and your own requests.
+
 ```python
-client = Client(auth_url="...", vlm_url="...")
-token = client.auth.get_access_token(
-    client_id="your-client-id",
-    client_secret="your-client-secret"
+from visionai_sdk_python import Client, ClientCredentials
+
+cred = ClientCredentials(
+    auth_url="...", client_id="your-client-id", client_secret="your-client-secret"
 )
+client = Client(auth_url="...", vlm_url="...", credential=cred)   # vlm.chat() uses it
+
+token = cred.get_token().token          # for requests the SDK does not make itself
 ```
 
-Tokens are stored internally and automatically refreshed before expiration.
+Platform mints at most 50 tokens per client per month, so the credential protects the
+quota: concurrent callers share one mint; a 401 on a cached token
+(`cred.invalidate(token)`) buys exactly one replacement, and a replacement that is
+rejected too is kept until its own refresh; after a 429 no mint is tried for an hour
+(`RateLimitedError`).
+
+`client.auth.get_access_token(client_id, client_secret)` still works and now builds a
+`ClientCredentials` underneath. `vlm_url` is optional for clients that only authenticate.
 
 ## VLM Inference
 

{visionai_sdk_python-2.1.1 → visionai_sdk_python-2.2.0.dev1}/README.md

@@ -116,15 +116,29 @@ token = client.auth.login("user@example.com", "password")
 
 ### OAuth Client Credentials
 
+A `ClientCredentials` (or `AsyncClientCredentials`) holds the token for one Platform
+client: it is minted on first use, cached until five minutes before it expires, and
+one instance can serve any number of clients and your own requests.
+
 ```python
-client = Client(auth_url="...", vlm_url="...")
-token = client.auth.get_access_token(
-    client_id="your-client-id",
-    client_secret="your-client-secret"
+from visionai_sdk_python import Client, ClientCredentials
+
+cred = ClientCredentials(
+    auth_url="...", client_id="your-client-id", client_secret="your-client-secret"
 )
+client = Client(auth_url="...", vlm_url="...", credential=cred)   # vlm.chat() uses it
+
+token = cred.get_token().token          # for requests the SDK does not make itself
 ```
 
-Tokens are stored internally and automatically refreshed before expiration.
+Platform mints at most 50 tokens per client per month, so the credential protects the
+quota: concurrent callers share one mint; a 401 on a cached token
+(`cred.invalidate(token)`) buys exactly one replacement, and a replacement that is
+rejected too is kept until its own refresh; after a 429 no mint is tried for an hour
+(`RateLimitedError`).
+
+`client.auth.get_access_token(client_id, client_secret)` still works and now builds a
+`ClientCredentials` underneath. `vlm_url` is optional for clients that only authenticate.
 
 ## VLM Inference
 

{visionai_sdk_python-2.1.1 → visionai_sdk_python-2.2.0.dev1}/src/visionai_sdk_python/__init__.py

@@ -4,6 +4,7 @@ A client library for interacting with VisionAI authentication and VLM services.
 """
 
 from .async_client import AsyncClient
+from .auth.credentials import AccessToken, AsyncClientCredentials, ClientCredentials
 from .client import Client
 from .exceptions import (
     AuthenticationError,
@@ -11,16 +12,21 @@ from .exceptions import (
     JwksDiscoveryError,
     NetworkError,
     PermissionDeniedError,
+    RateLimitedError,
     ServerError,
     VisionaiSDKError,
 )
 
 __all__ = [
+    "AccessToken",
     "AsyncClient",
+    "AsyncClientCredentials",
     "Client",
+    "ClientCredentials",
     "VisionaiSDKError",
     "AuthenticationError",
     "PermissionDeniedError",
+    "RateLimitedError",
     "ClientError",
     "ServerError",
     "NetworkError",

{visionai_sdk_python-2.1.1 → visionai_sdk_python-2.2.0.dev1}/src/visionai_sdk_python/_base.py

@@ -1,5 +1,5 @@
 import time
-from typing import Literal
+from typing import TYPE_CHECKING, Literal
 
 import httpx
 
@@ -9,10 +9,16 @@ from .exceptions import (
     APIError,
     AuthenticationError,
     ClientError,
+    NetworkError,
     PermissionDeniedError,
+    RateLimitedError,
     ServerError,
+    VisionaiSDKError,
 )
 
+if TYPE_CHECKING:
+    from .auth.credentials import AsyncClientCredentials, ClientCredentials
+
 
 class _BaseClient:
     """Base class for VisionAI SDK clients.
@@ -24,18 +30,20 @@ class _BaseClient:
     def __init__(
         self,
         auth_url: str,
-        vlm_url: str,
+        vlm_url: str | None = None,
         allowed_issuers: list[str] | None = None,
         verify_ssl: bool = True,
         timeout: float = 10.0,
         max_connections: int = 100,
         max_keepalive_connections: int = 20,
+        credential: "ClientCredentials | AsyncClientCredentials | None" = None,
     ) -> None:
         """Initialize the client with connection settings.
 
         Args:
             auth_url: Base URL for the authentication service.
-            vlm_url: Base URL for the VLM inference service.
+            vlm_url: Base URL for the VLM inference service. Optional for clients
+                that only authenticate; VLM calls then raise ``ValueError``.
             allowed_issuers: Optional list of allowed JWT issuers. If provided, tokens
                 whose ``iss`` claim is not in this list will be rejected. If omitted,
                 the issuers are derived from ``auth_url``.
@@ -43,13 +51,18 @@ class _BaseClient:
             timeout: Default request timeout in seconds.
             max_connections: Maximum number of concurrent connections in the pool.
             max_keepalive_connections: Maximum number of idle keep-alive connections.
+            credential: A ``ClientCredentials`` / ``AsyncClientCredentials`` whose
+                token every call uses; shareable between clients. Without it the
+                client keeps the token from ``auth.login()`` / ``auth.get_access_token()``
+                or ``set_token()``.
         """
         if not auth_url.strip():
             raise ValueError("auth_url must not be empty")
-        if not vlm_url.strip():
+        if vlm_url is not None and not vlm_url.strip():
             raise ValueError("vlm_url must not be empty")
         self.auth_url = auth_url.strip()
-        self.vlm_url = vlm_url.strip()
+        self.vlm_url = vlm_url.strip() if vlm_url is not None else None
+        self._credential = credential
         self.verify_ssl = verify_ssl
         self.timeout = timeout
         self.max_connections = max_connections
@@ -77,6 +90,20 @@ class _BaseClient:
         """Join a base URL and a path, normalizing slashes."""
         return f"{base_url.rstrip('/')}/{path.lstrip('/')}"
 
+    def _vlm_base(self) -> str:
+        if self.vlm_url is None:
+            raise ValueError("vlm_url is required for VLM calls; pass it to the client")
+        return self.vlm_url
+
+    @staticmethod
+    def _map_transport_error(error: httpx.RequestError) -> VisionaiSDKError:
+        """The SDK exception for an httpx request that never got a response."""
+        if isinstance(error, httpx.TimeoutException):
+            return NetworkError("Request timed out")
+        if isinstance(error, httpx.NetworkError):
+            return NetworkError(f"Network error: {error}")
+        return VisionaiSDKError(f"Request failed: {error}")
+
     @staticmethod
     def _build_auth_header(access_token: str) -> dict[str, str]:
         """Build authorization header."""
@@ -201,6 +228,8 @@ class _BaseClient:
                 raise AuthenticationError(detail) from e
             if status == 403:
                 raise PermissionDeniedError(detail) from e
+            if status == 429:
+                raise RateLimitedError(detail) from e
             if 400 <= status < 500:
                 raise ClientError(status, detail) from e
             if 500 <= status < 600:

{visionai_sdk_python-2.1.1 → visionai_sdk_python-2.2.0.dev1}/src/visionai_sdk_python/async_client.py

@@ -3,7 +3,8 @@ import httpx
 from ._base import _BaseClient
 from ._request_attribution import merge_request_attribution
 from .auth.async_resource import AsyncAuthResource
-from .exceptions import AuthenticationError, NetworkError, VisionaiSDKError
+from .auth.credentials import AsyncClientCredentials
+from .exceptions import AuthenticationError
 from .vlm.async_resource import AsyncVLMResource
 
 
@@ -11,12 +12,13 @@ class AsyncClient(_BaseClient):
     def __init__(
         self,
         auth_url: str,
-        vlm_url: str,
+        vlm_url: str | None = None,
         allowed_issuers: list[str] | None = None,
         verify_ssl: bool = True,
         timeout: float = 10.0,
         max_connections: int = 100,
         max_keepalive_connections: int = 20,
+        credential: AsyncClientCredentials | None = None,
     ) -> None:
         super().__init__(
             auth_url=auth_url,
@@ -26,6 +28,7 @@ class AsyncClient(_BaseClient):
             timeout=timeout,
             max_connections=max_connections,
             max_keepalive_connections=max_keepalive_connections,
+            credential=credential,
         )
         self._client = httpx.AsyncClient(
             verify=self.verify_ssl,
@@ -44,12 +47,8 @@ class AsyncClient(_BaseClient):
         merge_request_attribution(kwargs)
         try:
             response = await self._client.request(method, url, **kwargs)
-        except httpx.TimeoutException as e:
-            raise NetworkError("Request timed out") from e
-        except httpx.NetworkError as e:
-            raise NetworkError(f"Network error: {e}") from e
         except httpx.RequestError as e:
-            raise VisionaiSDKError(f"Request failed: {e}") from e
+            raise self._map_transport_error(e) from e
         return self._handle_response(response)
 
     async def close(self) -> None:
@@ -90,6 +89,9 @@ class AsyncClient(_BaseClient):
         Raises:
             AuthenticationError: If no token is available or token expired without credentials.
         """
+        if self._credential is not None:
+            self._access_token = (await self._credential.get_token()).token
+            return
         if self._access_token is None:
             raise AuthenticationError(
                 "Not authenticated. Call login() or get_access_token() first."

visionai_sdk_python-2.2.0.dev1/src/visionai_sdk_python/auth/__init__.py

@@ -0,0 +1,15 @@
+"""Authentication resources for VisionAI SDK."""
+
+from .async_resource import AsyncAuthResource
+from .credentials import AccessToken, AsyncClientCredentials, ClientCredentials
+from .models import TokenResponse
+from .resource import AuthResource
+
+__all__ = [
+    "AccessToken",
+    "AsyncAuthResource",
+    "AsyncClientCredentials",
+    "AuthResource",
+    "ClientCredentials",
+    "TokenResponse",
+]

{visionai_sdk_python-2.1.1 → visionai_sdk_python-2.2.0.dev1}/src/visionai_sdk_python/auth/async_resource.py

@@ -1,5 +1,6 @@
 """Authentication resource for async operations."""
 
+import time
 from typing import TYPE_CHECKING
 
 import jwt
@@ -7,6 +8,7 @@ import jwt
 from ..endpoints import AuthEndpoint
 from ..exceptions import JwksDiscoveryError
 from ._mixin import AuthMixin
+from .credentials import AsyncClientCredentials
 from .models import TokenResponse
 
 if TYPE_CHECKING:
@@ -33,6 +35,11 @@ class AsyncAuthResource(AuthMixin):
 
         The token is stored internally and will be used automatically for subsequent
         API calls. If the token expires, it will be automatically refreshed.
+        Calling this again with the same credentials returns the cached token.
+
+        New code should build a ``ClientCredentials`` / ``AsyncClientCredentials``
+        and pass it as ``credential=`` to the client instead; this method stays for
+        existing callers.
 
         Args:
             client_id: OAuth client ID
@@ -49,21 +56,30 @@ class AsyncAuthResource(AuthMixin):
         # Validate (from Mixin)
         self._validate_client_credentials(client_id, client_secret)
 
-        # I/O operation (async)
-        response = await self._sdk_client._request(
-            "POST",
-            self._sdk_client._build_url(
-                self._sdk_client.auth_url, AuthEndpoint.CLIENT_TOKEN
-            ),
-            json=self._prepare_client_token_request(client_id, client_secret),
-        )
-
-        # Parse and store (from Mixin)
-        return self._parse_and_store_token(
-            response.json(),
+        # One credential per client: cached, one mint at a time, one replacement
+        # per 401, no mint for an hour after a 429. Calling this again with the
+        # same client credentials reuses it, so it does not mint again.
+        credential = self._sdk_client._credential
+        if not (
+            isinstance(credential, AsyncClientCredentials)
+            and credential.is_for(client_id, client_secret)
+        ):
+            credential = AsyncClientCredentials(
+                self._sdk_client.auth_url,
+                client_id,
+                client_secret,
+                http=self._sdk_client._client,
+            )
+            self._sdk_client._credential = credential
+        token = await credential.get_token()
+        self._sdk_client._store_token(
+            access_token=token.token,
+            expires_in=max(int(token.expires_on - time.monotonic()), 0),
             credentials={"client_id": client_id, "client_secret": client_secret},
             credentials_type="client",
         )
+        assert credential.last_response is not None
+        return credential.last_response
 
     async def login(self, email: str, password: str) -> TokenResponse:
         """Login with email and password to get JWT token.

visionai_sdk_python-2.2.0.dev1/src/visionai_sdk_python/auth/credentials.py

@@ -0,0 +1,234 @@
+"""One client-credentials token for every client and caller in a process.
+
+Platform mints at most 50 tokens per client per month, so the token is cached
+until five minutes before it expires, one mint runs at a time, a 401 buys one
+replacement, and a 429 stops minting for an hour.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hmac
+import logging
+import threading
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from .._base import _BaseClient
+from .._request_attribution import merge_request_attribution
+from ..endpoints import AuthEndpoint
+from ..exceptions import RateLimitedError, VisionaiSDKError
+from .models import TokenResponse
+
+logger = logging.getLogger(__name__)
+
+# A token counts as expired this long before Platform says so.
+REFRESH_BUFFER_S = 300
+# Anything shorter would mint on every call; Platform issues 3-day tokens.
+MIN_EXPIRES_IN_S = 2 * REFRESH_BUFFER_S
+# After a 429 (the monthly quota is used up) no mint is tried for this long.
+QUOTA_COOLDOWN_S = 3600
+
+_now = time.monotonic
+
+
+@dataclass(frozen=True)
+class AccessToken:
+    """A bearer token and the ``time.monotonic()`` second it expires at."""
+
+    token: str
+    expires_on: float
+
+
+class _Credentials:
+    """What the sync and async variants share: the cache, the 401 and 429 rules."""
+
+    def __init__(self, auth_url: str, client_id: str, client_secret: str) -> None:
+        if not auth_url.strip():
+            raise ValueError("auth_url must not be empty")
+        if not client_id.strip():
+            raise ValueError("client_id must not be empty")
+        if not client_secret.strip():
+            raise ValueError("client_secret must not be empty")
+        self.auth_url = auth_url.strip()
+        self.client_id = client_id.strip()
+        self._client_secret = client_secret
+        self._url = _BaseClient._build_url(self.auth_url, AuthEndpoint.CLIENT_TOKEN)
+        self._token: AccessToken | None = None
+        #: The last token endpoint response, for callers that want ``token_type`` too.
+        self.last_response: TokenResponse | None = None
+        # True while the cached token is the replacement a 401 bought.
+        self._replaced = False
+        self._blocked_until = 0.0
+
+    def is_for(self, client_id: str, client_secret: str) -> bool:
+        """True when this credential was built for exactly these client credentials."""
+        return self.client_id == client_id.strip() and hmac.compare_digest(
+            self._client_secret, client_secret
+        )
+
+    def _cached(self) -> AccessToken | None:
+        if self._token and _now() < self._token.expires_on - REFRESH_BUFFER_S:
+            return self._token
+        return None
+
+    def _mint_request(self) -> dict[str, Any]:
+        """kwargs for the client-token POST; refuses while a 429 cooldown runs."""
+        if _now() < self._blocked_until:
+            raise RateLimitedError(
+                "client-token quota used up; not minting until the cooldown ends"
+            )
+        if self._token is not None:
+            # Natural refresh: the next 401 may buy one replacement again.
+            self._replaced = False
+        kwargs: dict[str, Any] = {
+            "json": {"client_id": self.client_id, "client_secret": self._client_secret}
+        }
+        merge_request_attribution(kwargs)
+        return kwargs
+
+    def _store(self, response: httpx.Response) -> AccessToken:
+        try:
+            _BaseClient._handle_response(response)
+        except RateLimitedError:
+            self._blocked_until = _now() + QUOTA_COOLDOWN_S
+            raise
+        try:
+            parsed = TokenResponse(**response.json())
+        except (ValueError, TypeError) as e:
+            raise VisionaiSDKError(f"client-token response is not a token: {e}") from e
+        self.last_response = parsed
+        self._token = AccessToken(
+            parsed.access_token, _now() + max(parsed.expires_in, MIN_EXPIRES_IN_S)
+        )
+        logger.info(
+            "platform token minted",
+            extra={"client_id": self.client_id, "expires_in": parsed.expires_in},
+        )
+        return self._token
+
+    def invalidate(self, token: str) -> bool:
+        """Report a 401 for ``token``. True: dropped, so the next ``get_token()`` mints.
+
+        A 401 for a token already replaced changes nothing. A 401 for the
+        replacement itself is not expiry but a client or allowlist problem that
+        another mint would not fix, so that token stays until its own refresh.
+        """
+        if self._token is None or token != self._token.token:
+            return False
+        if self._replaced:
+            logger.error(
+                "replacement token rejected too; keeping it until it expires",
+                extra={"client_id": self.client_id},
+            )
+            return False
+        self._token = None
+        self._replaced = True
+        return True
+
+
+class ClientCredentials(_Credentials):
+    """Client-credentials token for one Platform client, for sync code.
+
+    Pass it to ``Client(credential=...)`` and use ``get_token()`` for requests the
+    SDK does not make itself. One instance serves any number of clients and callers.
+    """
+
+    def __init__(
+        self,
+        auth_url: str,
+        client_id: str,
+        client_secret: str,
+        *,
+        http: httpx.Client | None = None,
+        verify_ssl: bool = True,
+        timeout: float = 10.0,
+    ) -> None:
+        super().__init__(auth_url, client_id, client_secret)
+        self._http = http or httpx.Client(verify=verify_ssl, timeout=timeout)
+        self._owns_http = http is None
+        self._lock = threading.Lock()
+
+    def get_token(self) -> AccessToken:
+        """The cached token, or a fresh one when it is within five minutes of expiry.
+
+        Raises:
+            AuthenticationError: Platform refused the client credentials (401).
+            RateLimitedError: The monthly mint quota is used up (429), or a 429 was
+                seen less than an hour ago.
+            NetworkError: Platform could not be reached.
+            VisionaiSDKError: Any other failure.
+        """
+        with self._lock:
+            cached = self._cached()
+            if cached is not None:
+                return cached
+            kwargs = self._mint_request()
+            try:
+                response = self._http.post(self._url, **kwargs)
+            except httpx.RequestError as e:
+                raise _BaseClient._map_transport_error(e) from e
+            return self._store(response)
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> ClientCredentials:
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()
+
+
+class AsyncClientCredentials(_Credentials):
+    """Client-credentials token for one Platform client, for asyncio code.
+
+    Pass it to ``AsyncClient(credential=...)`` and use ``await get_token()`` for
+    requests the SDK does not make itself, such as a WebSocket upgrade. One
+    instance serves any number of clients and callers.
+    """
+
+    def __init__(
+        self,
+        auth_url: str,
+        client_id: str,
+        client_secret: str,
+        *,
+        http: httpx.AsyncClient | None = None,
+        verify_ssl: bool = True,
+        timeout: float = 10.0,
+    ) -> None:
+        super().__init__(auth_url, client_id, client_secret)
+        self._http = http or httpx.AsyncClient(verify=verify_ssl, timeout=timeout)
+        self._owns_http = http is None
+        self._lock = asyncio.Lock()
+
+    async def get_token(self) -> AccessToken:
+        """The cached token, or a fresh one when it is within five minutes of expiry.
+
+        Concurrent callers wait for one mint. Raises as ``ClientCredentials.get_token``.
+        """
+        async with self._lock:
+            cached = self._cached()
+            if cached is not None:
+                return cached
+            kwargs = self._mint_request()
+            try:
+                response = await self._http.post(self._url, **kwargs)
+            except httpx.RequestError as e:
+                raise _BaseClient._map_transport_error(e) from e
+            return self._store(response)
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncClientCredentials:
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await self.aclose()

{visionai_sdk_python-2.1.1 → visionai_sdk_python-2.2.0.dev1}/src/visionai_sdk_python/auth/models.py

@@ -7,6 +7,6 @@ class TokenResponse(BaseModel):
     Used by both /api/users/jwt and /api/users/client-token endpoints.
     """
 
-    access_token: str = Field(..., description="JWT access token")
+    access_token: str = Field(..., min_length=1, description="JWT access token")
     expires_in: int = Field(..., description="Token expiration time in seconds")
     token_type: str = Field(..., description="Token type (e.g., 'Bearer')")