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

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

@@ -14,13 +14,8 @@ permissions:
 
 jobs:
   check:
-    name: Lint, test, and build (Python ${{ matrix.python-version }})
+    name: Lint, test, and build
     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
 
@@ -32,7 +27,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version-file: pyproject.toml
 
       - name: Install locked dependencies
         run: uv sync --locked --all-extras

{visionai_sdk_python-2.2.0.dev1 → 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.dev1
+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
@@ -146,17 +146,32 @@ cred = ClientCredentials(
 )
 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
+token = cred.get_token().token          # for a WebSocket upgrade or another library
+
+# Any other HTTP call with the same token; a 401 gets one fresh token and one retry
+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.dev1 → 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
@@ -128,17 +128,32 @@ cred = ClientCredentials(
 )
 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
+token = cred.get_token().token          # for a WebSocket upgrade or another library
+
+# Any other HTTP call with the same token; a 401 gets one fresh token and one retry
+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.dev1 → 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,27 +75,49 @@ 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":
+        """The credential this client was built with, for callers that need the
+        raw token themselves (a WebSocket upgrade, another HTTP library)."""
+        return self._credential
 
     @staticmethod
     def _build_url(base_url: str, path: str) -> str:
         """Join a base URL and a path, normalizing slashes."""
         return f"{base_url.rstrip('/')}/{path.lstrip('/')}"
 
-    def _vlm_base(self) -> str:
+    @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 = httpx.Headers(kwargs.get("headers"))
+        headers["Authorization"] = f"Bearer {token}"  # case-insensitive: one header
+        return {**kwargs, "headers": headers}
+
+    @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."""
@@ -116,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
@@ -201,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.dev1 → 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
 
 
@@ -19,7 +19,10 @@ class AsyncClient(_BaseClient):
         max_connections: int = 100,
         max_keepalive_connections: int = 20,
         credential: AsyncClientCredentials | None = None,
+        http_client: httpx.AsyncClient | None = None,
     ) -> None:
+        """See ``_BaseClient``; ``http_client`` is an httpx.AsyncClient to send through
+        (tests, shared pools); the client closes only the one it created."""
         super().__init__(
             auth_url=auth_url,
             vlm_url=vlm_url,
@@ -30,7 +33,7 @@ class AsyncClient(_BaseClient):
             max_keepalive_connections=max_keepalive_connections,
             credential=credential,
         )
-        self._client = httpx.AsyncClient(
+        self._client = http_client or httpx.AsyncClient(
             verify=self.verify_ssl,
             timeout=self.timeout,
             limits=httpx.Limits(
@@ -38,6 +41,7 @@ class AsyncClient(_BaseClient):
                 max_keepalive_connections=self.max_keepalive_connections,
             ),
         )
+        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)
@@ -48,12 +52,42 @@ 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 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._full_url(url)
+        token = await self._ensure_token()
+        try:
+            return await self._request(method, url, **self._with_auth(kwargs, token))
+        except AuthenticationError:
+            if self._credential is None or not self._resendable(kwargs):
+                raise
+            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 and release connections."""
-        await self._client.aclose()
+        """Close the HTTP client this client created and release its connections."""
+        if self._http_owner:
+            await self._client.aclose()
 
     async def __aenter__(self) -> "AsyncClient":
         """Async context manager entry."""
@@ -64,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.
@@ -72,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."
@@ -103,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.dev1 → 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.dev1 → 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.