visionai-sdk-python 2.2.0.dev2__py3-none-any.whl → 2.2.0.dev4__py3-none-any.whl

visionai_sdk_python/auth/credentials.py

@@ -1,8 +1,10 @@
 """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.
+A mint is a round trip to Platform and, on sites that cap client tokens, a
+scarce one, so the token is cached until shortly before it expires, one mint
+runs at a time, a refresh that fails keeps the current token while Platform
+still accepts it, a 401 replaces a token that is old enough to have been
+revoked, and a 429 stops minting for an hour.
 """
 
 from __future__ import annotations
@@ -20,31 +22,43 @@ import httpx
 from .._base import _BaseClient
 from .._request_attribution import merge_request_attribution
 from ..endpoints import AuthEndpoint
-from ..exceptions import RateLimitedError, VisionaiSDKError
+from ..exceptions import (
+    RateLimitedError,
+    VisionaiSDKError,
+    from_transport_error,
+    raise_for_status,
+)
 from .models import TokenResponse
 
 logger = logging.getLogger(__name__)
 
-# A token counts as expired this long before Platform says so.
+# A token is refreshed this long before it expires, or at half its lifetime when
+# that is sooner, so a token is never served after Platform stops accepting it.
 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
+# After a 429 no mint is tried for this long.
+RATE_LIMIT_COOLDOWN_S = 3600
+# A 401 on a token minted less than this long ago does not replace it.
+REPLACE_COOLDOWN_S = 30 * 60
 
 _now = time.monotonic
 
 
 @dataclass(frozen=True)
 class AccessToken:
-    """A bearer token and the ``time.monotonic()`` second it expires at."""
+    """A bearer token with the ``time.monotonic()`` seconds it expires at and was issued."""
 
     token: str
     expires_on: float
+    token_type: str
+    issued_at: float
+
+    def expires_in(self) -> int:
+        """Seconds left before ``expires_on``, never negative."""
+        return max(int(self.expires_on - _now()), 0)
 
 
 class _Credentials:
-    """What the sync and async variants share: the cache, the 401 and 429 rules."""
+    """What the sync and async variants share: the cache, the refresh, 401 and 429 rules."""
 
     def __init__(self, auth_url: str, client_id: str, client_secret: str) -> None:
         if not auth_url.strip():
@@ -57,12 +71,9 @@ class _Credentials:
         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._current: AccessToken | None = None  # the token this credential holds
         self._blocked_until = 0.0
+        self._minting = False  # a mint is in flight (set under the lock)
 
     def is_for(self, client_id: str, client_secret: str) -> bool:
         """True when this credential was built for exactly these client credentials."""
@@ -70,63 +81,89 @@ class _Credentials:
             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
+    def _fresh(self) -> AccessToken | None:
+        """The current token while it is not yet due for a refresh."""
+        token = self._current
+        if token is None:
+            return None
+        buffer = min(REFRESH_BUFFER_S, (token.expires_on - token.issued_at) / 2)
+        return token if _now() < token.expires_on - buffer else None
+
+    def _valid(self) -> AccessToken | None:
+        """The current token while Platform still accepts it, due for a refresh or not."""
+        if self._current and _now() < self._current.expires_on:
+            return self._current
         return None
 
-    def _mint_request(self) -> dict[str, Any]:
-        """kwargs for the client-token POST; refuses while a 429 cooldown runs."""
+    def _begin_mint(self) -> dict[str, Any]:
+        """First half of a mint: the 429 gate, then the kwargs for the client-token POST."""
         if _now() < self._blocked_until:
             raise RateLimitedError(
-                "client-token quota used up; not minting until the cooldown ends"
+                "client-token requests are rate limited; 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:
+    def _finish_mint(self, response: httpx.Response) -> AccessToken:
+        """Second half of a mint: the response becomes the current token, or raises."""
         try:
-            _BaseClient._handle_response(response)
+            raise_for_status(response)
         except RateLimitedError:
-            self._blocked_until = _now() + QUOTA_COOLDOWN_S
+            self._blocked_until = _now() + RATE_LIMIT_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)
+        now = _now()
+        self._current = AccessToken(
+            parsed.access_token, now + parsed.expires_in, parsed.token_type, now
         )
         logger.info(
             "platform token minted",
             extra={"client_id": self.client_id, "expires_in": parsed.expires_in},
         )
-        return self._token
+        return self._current
+
+    def _after_failed_refresh(self, error: VisionaiSDKError) -> AccessToken:
+        """A refresh failed: keep serving the current token while it is valid, else raise."""
+        valid = self._valid()
+        if valid is None:
+            raise error
+        logger.warning(
+            "token refresh failed; using the current token until it expires",
+            extra={
+                "client_id": self.client_id,
+                "error": str(error),
+                "expires_in": valid.expires_in(),
+            },
+        )
+        return valid
 
     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.
+        A late report for a token no longer held changes nothing. A token minted
+        less than ``REPLACE_COOLDOWN_S`` ago is kept: a 401 that soon is a client or
+        allowlist problem another mint would not fix, and the cooldown bounds how
+        often a persistent 401 can mint. While a mint is in flight the report is
+        already being acted on.
         """
-        if self._token is None or token != self._token.token:
+        if self._current is None or token != self._current.token:
             return False
-        if self._replaced:
-            logger.error(
-                "replacement token rejected too; keeping it until it expires",
+        if self._minting:
+            return True
+        if _now() - self._current.issued_at < REPLACE_COOLDOWN_S:
+            logger.warning(
+                "401 on a token minted %d s ago; keeping it until the cooldown ends",
+                int(_now() - self._current.issued_at),
                 extra={"client_id": self.client_id},
             )
             return False
-        self._token = None
-        self._replaced = True
+        self._current = None
         return True
 
 
@@ -149,32 +186,43 @@ class ClientCredentials(_Credentials):
     ) -> 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._http_owner = http is None  # a client we built is ours to close
         self._lock = threading.Lock()
 
-    def get_token(self) -> AccessToken:
-        """The cached token, or a fresh one when it is within five minutes of expiry.
+    def get_token(self, *, force_refresh: bool = False) -> AccessToken:
+        """The cached token, refreshed shortly before it expires.
+
+        ``force_refresh=True`` mints even while the cached token is fresh. A refresh
+        that fails keeps serving the current token while Platform still accepts it.
 
         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.
+            RateLimitedError: Platform answered 429, or did so 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()
+            if not force_refresh:
+                fresh = self._fresh()
+                if fresh is not None:
+                    return fresh
+            self._minting = True
             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)
+                kwargs = self._begin_mint()
+                try:
+                    response = self._http.post(self._url, **kwargs)
+                except httpx.RequestError as e:
+                    raise from_transport_error(e) from e
+                return self._finish_mint(response)
+            except VisionaiSDKError as e:
+                if force_refresh:
+                    raise
+                return self._after_failed_refresh(e)
+            finally:
+                self._minting = False
 
     def close(self) -> None:
-        if self._owns_http:
+        if self._http_owner:
             self._http.close()
 
     def __enter__(self) -> ClientCredentials:
@@ -204,27 +252,37 @@ class AsyncClientCredentials(_Credentials):
     ) -> 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._http_owner = http is None  # a client we built is ours to close
         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.
+    async def get_token(self, *, force_refresh: bool = False) -> AccessToken:
+        """The cached token, refreshed shortly before it expires.
 
-        Concurrent callers wait for one mint. Raises as ``ClientCredentials.get_token``.
+        Concurrent callers wait for one mint. Behaves and raises as
+        ``ClientCredentials.get_token``.
         """
         async with self._lock:
-            cached = self._cached()
-            if cached is not None:
-                return cached
-            kwargs = self._mint_request()
+            if not force_refresh:
+                fresh = self._fresh()
+                if fresh is not None:
+                    return fresh
+            self._minting = True
             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)
+                kwargs = self._begin_mint()
+                try:
+                    response = await self._http.post(self._url, **kwargs)
+                except httpx.RequestError as e:
+                    raise from_transport_error(e) from e
+                return self._finish_mint(response)
+            except VisionaiSDKError as e:
+                if force_refresh:
+                    raise
+                return self._after_failed_refresh(e)
+            finally:
+                self._minting = False
 
     async def aclose(self) -> None:
-        if self._owns_http:
+        if self._http_owner:
             await self._http.aclose()
 
     async def __aenter__(self) -> AsyncClientCredentials:

visionai_sdk_python/auth/resource.py

@@ -1,6 +1,5 @@
 """Authentication resource for sync operations."""
 
-import time
 from typing import TYPE_CHECKING
 
 import jwt
@@ -28,12 +27,17 @@ class AuthResource(AuthMixin):
         """
         self._sdk_client = client
 
-    def get_access_token(self, client_id: str, client_secret: str) -> TokenResponse:
+    def get_access_token(
+        self, client_id: str, client_secret: str, *, force_refresh: bool = False
+    ) -> TokenResponse:
         """Get access token using client credentials flow.
 
-        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.
+        The client keeps the resulting credential and uses it for subsequent API
+        calls, minting a new token when the current one expires. Calling this
+        again with the same client credentials returns the cached token;
+        ``force_refresh=True`` mints a new one. A later ``login()`` or
+        ``set_token()`` replaces the credential: the last explicit
+        authentication wins.
 
         New code should build a ``ClientCredentials`` / ``AsyncClientCredentials``
         and pass it as ``credential=`` to the client instead; this method stays for
@@ -42,6 +46,7 @@ class AuthResource(AuthMixin):
         Args:
             client_id: OAuth client ID
             client_secret: OAuth client secret
+            force_refresh: Mint a new token even if a fresh one is cached.
 
         Returns:
             TokenResponse with access_token, expires_in, and token_type
@@ -68,16 +73,15 @@ class AuthResource(AuthMixin):
                 client_secret,
                 http=self._sdk_client._client,
             )
-            self._sdk_client._credential = credential
-        token = credential.get_token()
-        self._sdk_client._store_token(
+        token = credential.get_token(force_refresh=force_refresh)
+        # Installed only once it works, and over a login() / set_token() token:
+        # the last explicit authentication wins.
+        self._sdk_client._credential = credential
+        return TokenResponse(
             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",
+            expires_in=token.expires_in(),
+            token_type=token.token_type,
         )
-        assert credential.last_response is not None
-        return credential.last_response
 
     def login(self, email: str, password: str) -> TokenResponse:
         """Login with email and password to get JWT token.

visionai_sdk_python/client.py

@@ -4,7 +4,7 @@ from ._base import _BaseClient
 from ._request_attribution import merge_request_attribution
 from .auth.credentials import ClientCredentials
 from .auth.resource import AuthResource
-from .exceptions import AuthenticationError
+from .exceptions import AuthenticationError, from_transport_error
 from .vlm.resource import VLMResource
 
 
@@ -41,7 +41,7 @@ class Client(_BaseClient):
                 max_keepalive_connections=self.max_keepalive_connections,
             ),
         )
-        self._owns_http = http_client is None
+        self._http_owner = http_client is None  # a client we built is ours to close
         # Register the different function resource
         self.auth = AuthResource(self)
         self.vlm = VLMResource(self)
@@ -52,46 +52,41 @@ class Client(_BaseClient):
         try:
             response = self._client.request(method, url, **kwargs)
         except httpx.RequestError as e:
-            raise self._map_transport_error(e) from e
+            raise from_transport_error(e) from e
         return self._handle_response(response)
 
     def request(self, method: str, url: str, **kwargs) -> httpx.Response:
         """Send any request with this client's bearer token.
 
-        ``url`` is absolute, or a path under ``auth_url``; ``kwargs`` go to httpx.
-        A 401 buys one fresh token (from ``credential`` or the stored login) and
-        one retry, so a token revoked server-side costs one extra request.
+        ``url`` is a full URL (the client has two bases); ``kwargs`` go to httpx.
+        With a ``credential``, a 401 buys one retry with the credential's current
+        token, which it replaces when the rejected one is old enough to have been
+        revoked (``REPLACE_COOLDOWN_S``); a 401 on the retry raises. Without a
+        credential, or with a body that cannot be sent twice (a stream or a
+        file), a 401 raises.
 
         Raises:
+            ValueError: ``url`` is not a full URL.
             AuthenticationError: No token, or the fresh one was refused too.
             RateLimitedError, NetworkError, ServerError, ClientError: As the
                 resource methods.
         """
-        url = self._absolute(url)
-        self._ensure_token()
-        token = self._access_token
+        url = self._full_url(url)
+        token = self._ensure_token()
         try:
             return self._request(method, url, **self._with_auth(kwargs, token))
         except AuthenticationError:
-            if not self._renew_rejected(token):
+            if self._credential is None or not self._resendable(kwargs):
                 raise
-        return self._request(method, url, **self._with_auth(kwargs, self._access_token))
-
-    def _renew_rejected(self, token: str) -> bool:
-        """A 401 for ``token``: get a different one, once; False when none would help."""
-        if self._credential is not None:
-            if not self._credential.invalidate(token):
-                return False
-            self._access_token = self._credential.get_token().token
-            return True
-        if self._credentials is None or self._access_token != token:
-            return False
-        self._refresh_token()
-        return self._access_token != token
+            self._credential.invalidate(token)
+            replacement = (self._credential.get_token()).token
+            if replacement == token:
+                raise
+        return self._request(method, url, **self._with_auth(kwargs, replacement))
 
     def close(self) -> None:
         """Close the HTTP client this client created and release its connections."""
-        if self._owns_http:
+        if self._http_owner:
             self._client.close()
 
     def __enter__(self) -> "Client":
@@ -103,7 +98,9 @@ class Client(_BaseClient):
         self.close()
 
     def _refresh_token(self) -> None:
-        """Refresh token using stored credentials.
+        """Refresh the token with the stored login credentials.
+
+        Client credentials refresh through the credential object instead.
 
         Raises:
             AuthenticationError: If no credentials are stored or refresh fails.
@@ -111,26 +108,19 @@ class Client(_BaseClient):
         if self._credentials is None or self._credentials_type is None:
             raise AuthenticationError("No credentials available for token refresh")
 
-        if self._credentials_type == "login":
-            self.auth.login(
-                email=self._credentials["email"],
-                password=self._credentials["password"],
-            )
-        elif self._credentials_type == "client":
-            self.auth.get_access_token(
-                client_id=self._credentials["client_id"],
-                client_secret=self._credentials["client_secret"],
-            )
+        self.auth.login(
+            email=self._credentials["email"],
+            password=self._credentials["password"],
+        )
 
-    def _ensure_token(self) -> None:
-        """Ensure a valid token is available, refreshing if necessary.
+    def _ensure_token(self) -> str:
+        """The token to send: the credential's, else the stored one, refreshed if expiring.
 
         Raises:
             AuthenticationError: If no token is available or token expired without credentials.
         """
         if self._credential is not None:
-            self._access_token = (self._credential.get_token()).token
-            return
+            return (self._credential.get_token()).token
         if self._access_token is None:
             raise AuthenticationError(
                 "Not authenticated. Call login() or get_access_token() first."
@@ -142,3 +132,4 @@ class Client(_BaseClient):
                     "Token expired and no credentials available for refresh"
                 )
             self._refresh_token()
+        return self._access_token

visionai_sdk_python/exceptions.py

@@ -1,3 +1,6 @@
+import httpx
+
+
 class VisionaiSDKError(Exception):
     """Base exception for all SDK errors."""
 
@@ -29,7 +32,7 @@ class PermissionDeniedError(ClientError):
 
 
 class RateLimitedError(ClientError):
-    """429 - Too many requests; on client-token, the monthly mint quota is used up."""
+    """429 - Too many requests; on client-token, Platform is rate limiting mints."""
 
     def __init__(self, message: str) -> None:
         super().__init__(429, message)
@@ -45,3 +48,50 @@ class NetworkError(VisionaiSDKError):
 
 class JwksDiscoveryError(VisionaiSDKError):
     """Failed to fetch or parse the OIDC discovery document or JWKS endpoint."""
+
+
+def from_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}")
+
+
+def raise_for_status(response: httpx.Response) -> httpx.Response:
+    """Raise SDK-specific exceptions for non-2xx responses.
+
+    Raises:
+        AuthenticationError: If the server returns 401
+        PermissionDeniedError: If the server returns 403
+        ClientError: If the server returns any other 4xx
+        ServerError: If the server returns 5xx
+        APIError: If the server returns any other non-2xx status
+    """
+    try:
+        response.raise_for_status()
+    except httpx.HTTPStatusError as e:
+        body = None
+        if e.response.content:
+            try:
+                body = e.response.json()
+            except Exception:
+                pass
+        if isinstance(body, dict):
+            detail: str = body.get("detail") or body.get("message") or str(e)
+        else:
+            detail = str(e)
+        status = e.response.status_code
+        if status == 401:
+            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:
+            raise ServerError(status, detail) from e
+        raise APIError(status, detail) from e
+    return response

visionai_sdk_python/relay/__init__.py

@@ -0,0 +1,67 @@
+"""The platform-relay wire protocol, shared by platform-relay and platform-edge-agent.
+
+Internal to the platform; the spec is platform-service's
+``docs/adr/0001-relay-protocol.md``. See :mod:`.protocol`.
+"""
+
+from .protocol import (
+    AGENT_TIMEOUT_S,
+    HEARTBEAT_INTERVAL_S,
+    MAX_BODY_BYTES,
+    MAX_FRAME_BYTES,
+    REGISTER_DEADLINE_S,
+    RELAY_TIMEOUT_S,
+    STALE_AFTER_S,
+    SUBPROTOCOL,
+    AgentFrame,
+    CloseCode,
+    Error,
+    ErrorCode,
+    Frame,
+    Heartbeat,
+    InvalidFrame,
+    ModelEntry,
+    Register,
+    Registered,
+    Rejected,
+    RejectReason,
+    RelayFrame,
+    Request,
+    Response,
+    WorkspaceEntry,
+    dump_frame,
+    is_workspace_id,
+    parse_agent_frame,
+    parse_relay_frame,
+)
+
+__all__ = [
+    "AGENT_TIMEOUT_S",
+    "HEARTBEAT_INTERVAL_S",
+    "MAX_BODY_BYTES",
+    "MAX_FRAME_BYTES",
+    "REGISTER_DEADLINE_S",
+    "RELAY_TIMEOUT_S",
+    "STALE_AFTER_S",
+    "SUBPROTOCOL",
+    "AgentFrame",
+    "CloseCode",
+    "Error",
+    "ErrorCode",
+    "Frame",
+    "Heartbeat",
+    "InvalidFrame",
+    "ModelEntry",
+    "Register",
+    "Registered",
+    "Rejected",
+    "RejectReason",
+    "RelayFrame",
+    "Request",
+    "Response",
+    "WorkspaceEntry",
+    "dump_frame",
+    "is_workspace_id",
+    "parse_agent_frame",
+    "parse_relay_frame",
+]

visionai_sdk_python/relay/examples/__init__.py

@@ -0,0 +1,28 @@
+"""The ADR's JSON examples, shipped so every implementation tests against the same frames.
+
+``example("register")`` is the parsed object, ``example_text("register")`` the wire text.
+"""
+
+import json
+from importlib.resources import files
+
+NAMES = (
+    "register",
+    "registered",
+    "heartbeat",
+    "request",
+    "response",
+    "response_text",
+    "error_request",
+    "error_connection",
+)
+
+
+def example_text(name: str) -> str:
+    """One ADR example as the text that goes over the wire."""
+    return (files(__package__) / f"{name}.json").read_text(encoding="utf-8")
+
+
+def example(name: str) -> dict:
+    """One ADR example as a dict, for building or comparing frames in tests."""
+    return json.loads(example_text(name))

visionai_sdk_python/relay/examples/error_connection.json

@@ -0,0 +1,3 @@
+{"type": "error",
+ "code": "invalid_message",
+ "message": "unknown type 'ping'"}