visionai-sdk-python 2.2.0.dev2__tar.gz → 2.2.0.dev3__tar.gz

{visionai_sdk_python-2.2.0.dev2 → visionai_sdk_python-2.2.0.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: visionai-sdk-python
-Version: 2.2.0.dev2
+Version: 2.2.0.dev3
 Summary: VisionAI SDK for Python
 Author-email: Tony Yang <tonyyang@linkervision.com>
 Requires-Python: >=3.11
@@ -135,8 +135,8 @@ 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.
+client: it is minted on first use, cached until shortly before it expires, and one
+instance can serve any number of clients and your own requests.
 
 ```python
 from visionai_sdk_python import Client, ClientCredentials
@@ -152,14 +152,26 @@ token = cred.get_token().token          # for a WebSocket upgrade or another lib
 nodes = client.request("GET", "https://vs.example.com/mgmt/nodes").json()
 ```
 
-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`).
+A mint is a Platform round trip and, on sites that cap client tokens, a scarce one:
+concurrent callers share one mint, a refresh that fails keeps the current token while
+Platform still accepts it, a 401 on a token minted more than 30 minutes ago buys a
+replacement (`cred.invalidate(token)`; a younger one is kept, so a persistent 401
+mints at most twice an hour), and after a 429 no mint is tried for an hour
+(`RateLimitedError`). `get_token(force_refresh=True)` mints on demand.
 
 `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.
+`ClientCredentials` underneath; it returns the cached token unless `force_refresh=True`.
+A later `login()` or `set_token()` replaces the credential: the last explicit
+authentication wins. `vlm_url` is optional for clients that only authenticate.
+
+## Relay protocol (internal)
+
+`visionai_sdk_python.relay` holds the wire format between platform-relay and
+platform-edge-agent: the frame models, the constants and `parse_agent_frame()` /
+`parse_relay_frame()` / `dump_frame()`. The spec is platform-service's
+`docs/adr/0001-relay-protocol.md`; both sides import this module instead of keeping a
+copy, and the ADR's JSON examples are this package's tests. It is internal to the
+platform and not a public API.
 
 ## VLM Inference
 

{visionai_sdk_python-2.2.0.dev2 → visionai_sdk_python-2.2.0.dev3}/README.md

@@ -117,8 +117,8 @@ 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.
+client: it is minted on first use, cached until shortly before it expires, and one
+instance can serve any number of clients and your own requests.
 
 ```python
 from visionai_sdk_python import Client, ClientCredentials
@@ -134,14 +134,26 @@ token = cred.get_token().token          # for a WebSocket upgrade or another lib
 nodes = client.request("GET", "https://vs.example.com/mgmt/nodes").json()
 ```
 
-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`).
+A mint is a Platform round trip and, on sites that cap client tokens, a scarce one:
+concurrent callers share one mint, a refresh that fails keeps the current token while
+Platform still accepts it, a 401 on a token minted more than 30 minutes ago buys a
+replacement (`cred.invalidate(token)`; a younger one is kept, so a persistent 401
+mints at most twice an hour), and after a 429 no mint is tried for an hour
+(`RateLimitedError`). `get_token(force_refresh=True)` mints on demand.
 
 `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.
+`ClientCredentials` underneath; it returns the cached token unless `force_refresh=True`.
+A later `login()` or `set_token()` replaces the credential: the last explicit
+authentication wins. `vlm_url` is optional for clients that only authenticate.
+
+## Relay protocol (internal)
+
+`visionai_sdk_python.relay` holds the wire format between platform-relay and
+platform-edge-agent: the frame models, the constants and `parse_agent_frame()` /
+`parse_relay_frame()` / `dump_frame()`. The spec is platform-service's
+`docs/adr/0001-relay-protocol.md`; both sides import this module instead of keeping a
+copy, and the ADR's JSON examples are this package's tests. It is internal to the
+platform and not a public API.
 
 ## VLM Inference
 

{visionai_sdk_python-2.2.0.dev2 → visionai_sdk_python-2.2.0.dev3}/src/visionai_sdk_python/_base.py

@@ -5,16 +5,7 @@ import httpx
 
 from ._jwt_verifier import JwtVerifier
 from .constants import resolve_allowed_issuers
-from .exceptions import (
-    APIError,
-    AuthenticationError,
-    ClientError,
-    NetworkError,
-    PermissionDeniedError,
-    RateLimitedError,
-    ServerError,
-    VisionaiSDKError,
-)
+from .exceptions import raise_for_status
 
 if TYPE_CHECKING:
     from .auth.credentials import AsyncClientCredentials, ClientCredentials
@@ -53,8 +44,9 @@ class _BaseClient:
             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()``.
+                client keeps the token from ``auth.login()`` or ``set_token()``;
+                ``auth.get_access_token()`` installs a credential. The last explicit
+                authentication wins.
         """
         if not auth_url.strip():
             raise ValueError("auth_url must not be empty")
@@ -83,7 +75,7 @@ class _BaseClient:
         self._access_token: str | None = None
         self._token_expires_at: float | None = None  # monotonic time
         self._credentials: dict | None = None
-        self._credentials_type: Literal["login", "client"] | None = None
+        self._credentials_type: Literal["login"] | None = None
 
     @property
     def credential(self) -> "ClientCredentials | AsyncClientCredentials | None":
@@ -96,32 +88,36 @@ class _BaseClient:
         """Join a base URL and a path, normalizing slashes."""
         return f"{base_url.rstrip('/')}/{path.lstrip('/')}"
 
-    def _absolute(self, url: str) -> str:
-        """``url`` as given when absolute, else a path under ``auth_url``."""
-        return url if "://" in url else self._build_url(self.auth_url, url)
+    @staticmethod
+    def _full_url(url: str) -> str:
+        """``request()`` takes a full URL: the client has two bases (``auth_url``,
+        ``vlm_url``), so a bare path would not say which one is meant."""
+        if "://" not in url:
+            raise ValueError(f"request() needs a full URL, got {url!r}")
+        return url
 
     def _with_auth(self, kwargs: dict, token: str) -> dict:
         """``kwargs`` for httpx with the bearer header; the client's token wins."""
-        headers = {
-            **dict(kwargs.get("headers") or {}),
-            **self._build_auth_header(token),
-        }
+        headers = httpx.Headers(kwargs.get("headers"))
+        headers["Authorization"] = f"Bearer {token}"  # case-insensitive: one header
         return {**kwargs, "headers": headers}
 
-    def _vlm_base(self) -> str:
+    @staticmethod
+    def _resendable(kwargs: dict) -> bool:
+        """Whether the body can be sent a second time (streams and files cannot)."""
+        content = kwargs.get("content")
+        if content is not None and not isinstance(content, (bytes, str)):
+            return False
+        if kwargs.get("files") is not None:
+            return False
+        data = kwargs.get("data")
+        return data is None or isinstance(data, dict)
+
+    def _require_vlm_url(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."""
@@ -134,16 +130,20 @@ class _BaseClient:
         access_token: str,
         expires_in: int,
         credentials: dict | None = None,
-        credentials_type: Literal["login", "client"] | None = None,
+        credentials_type: Literal["login"] | None = None,
     ) -> None:
-        """Store token and credentials for auto-refresh.
+        """Use this token from now on; a credential set earlier is dropped.
+
+        The last explicit authentication wins, in both directions.
 
         Args:
             access_token: JWT access token.
             expires_in: Token expiration time in seconds.
             credentials: Optional credentials for auto-refresh.
-            credentials_type: Type of credentials ("login" or "client").
+            credentials_type: "login" for email / password credentials; client
+                credentials live in a ``ClientCredentials`` on the client instead.
         """
+        self._credential = None
         self._access_token = access_token
         self._token_expires_at = time.monotonic() + expires_in
         self._credentials = credentials
@@ -219,38 +219,5 @@ class _BaseClient:
 
     @staticmethod
     def _handle_response(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
+        """Raise the SDK exception for a non-2xx response (``exceptions.raise_for_status``)."""
+        return raise_for_status(response)

{visionai_sdk_python-2.2.0.dev2 → visionai_sdk_python-2.2.0.dev3}/src/visionai_sdk_python/async_client.py

@@ -4,7 +4,7 @@ from ._base import _BaseClient
 from ._request_attribution import merge_request_attribution
 from .auth.async_resource import AsyncAuthResource
 from .auth.credentials import AsyncClientCredentials
-from .exceptions import AuthenticationError
+from .exceptions import AuthenticationError, from_transport_error
 from .vlm.async_resource import AsyncVLMResource
 
 
@@ -41,7 +41,7 @@ class AsyncClient(_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 = AsyncAuthResource(self)
         self.vlm = AsyncVLMResource(self)
@@ -52,48 +52,41 @@ class AsyncClient(_BaseClient):
         try:
             response = await 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)
 
     async 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)
-        await self._ensure_token()
-        token = self._access_token
+        url = self._full_url(url)
+        token = await self._ensure_token()
         try:
             return await self._request(method, url, **self._with_auth(kwargs, token))
         except AuthenticationError:
-            if not await self._renew_rejected(token):
+            if self._credential is None or not self._resendable(kwargs):
                 raise
-        return await self._request(
-            method, url, **self._with_auth(kwargs, self._access_token)
-        )
-
-    async 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 = (await self._credential.get_token()).token
-            return True
-        if self._credentials is None or self._access_token != token:
-            return False
-        await self._refresh_token()
-        return self._access_token != token
+            self._credential.invalidate(token)
+            replacement = (await self._credential.get_token()).token
+            if replacement == token:
+                raise
+        return await self._request(method, url, **self._with_auth(kwargs, replacement))
 
     async def close(self) -> None:
         """Close the HTTP client this client created and release its connections."""
-        if self._owns_http:
+        if self._http_owner:
             await self._client.aclose()
 
     async def __aenter__(self) -> "AsyncClient":
@@ -105,7 +98,9 @@ class AsyncClient(_BaseClient):
         await self.close()
 
     async 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.
@@ -113,26 +108,19 @@ class AsyncClient(_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":
-            await self.auth.login(
-                email=self._credentials["email"],
-                password=self._credentials["password"],
-            )
-        elif self._credentials_type == "client":
-            await self.auth.get_access_token(
-                client_id=self._credentials["client_id"],
-                client_secret=self._credentials["client_secret"],
-            )
+        await self.auth.login(
+            email=self._credentials["email"],
+            password=self._credentials["password"],
+        )
 
-    async def _ensure_token(self) -> None:
-        """Ensure a valid token is available, refreshing if necessary.
+    async 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 = (await self._credential.get_token()).token
-            return
+            return (await self._credential.get_token()).token
         if self._access_token is None:
             raise AuthenticationError(
                 "Not authenticated. Call login() or get_access_token() first."
@@ -144,3 +132,4 @@ class AsyncClient(_BaseClient):
                     "Token expired and no credentials available for refresh"
                 )
             await self._refresh_token()
+        return self._access_token

{visionai_sdk_python-2.2.0.dev2 → visionai_sdk_python-2.2.0.dev3}/src/visionai_sdk_python/auth/_mixin.py

@@ -97,7 +97,7 @@ class AuthMixin:
         Args:
             response_data: Response JSON data
             credentials: Credentials dict for auto-refresh
-            credentials_type: Type of credentials ("login" or "client")
+            credentials_type: Type of credentials ("login")
 
         Returns:
             Parsed TokenResponse

{visionai_sdk_python-2.2.0.dev2 → visionai_sdk_python-2.2.0.dev3}/src/visionai_sdk_python/auth/async_resource.py

@@ -1,6 +1,5 @@
 """Authentication resource for async operations."""
 
-import time
 from typing import TYPE_CHECKING
 
 import jwt
@@ -29,13 +28,16 @@ class AsyncAuthResource(AuthMixin):
         self._sdk_client = client
 
     async def get_access_token(
-        self, client_id: str, client_secret: str
+        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
@@ -44,6 +46,7 @@ class AsyncAuthResource(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
@@ -70,16 +73,15 @@ class AsyncAuthResource(AuthMixin):
                 client_secret,
                 http=self._sdk_client._client,
             )
-            self._sdk_client._credential = credential
-        token = await credential.get_token()
-        self._sdk_client._store_token(
+        token = await 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
 
     async def login(self, email: str, password: str) -> TokenResponse:
         """Login with email and password to get JWT token.