visionai-sdk-python 2.2.0.dev4__tar.gz → 2.2.0.dev6__tar.gz

{visionai_sdk_python-2.2.0.dev4/src/visionai_sdk_python.egg-info → visionai_sdk_python-2.2.0.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: visionai-sdk-python
-Version: 2.2.0.dev4
+Version: 2.2.0.dev6
 Summary: VisionAI SDK for Python
 Author-email: Tony Yang <tonyyang@linkervision.com>
 Requires-Python: >=3.11
@@ -148,10 +148,18 @@ client = Client(auth_url="...", vlm_url="...", credential=cred)   # vlm.chat() u
 
 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
+# Any other HTTP call with the same token, sent to the host you name; a 401 gets one
+# fresh token and one retry
 nodes = client.request("GET", "https://vs.example.com/mgmt/nodes").json()
 ```
 
+`request()` raises on a non-2xx like the resource methods (`AuthenticationError`,
+`ClientError`, `ServerError`, ...), unlike plain httpx, and sends the token to whatever
+host `url` names, so `url` comes from configuration or code, never from a caller. A
+client built with `http_client=` (or a credential with `http=`) uses that client's TLS,
+timeout and limits; passing `verify_ssl` / `timeout` / `max_connections` /
+`max_keepalive_connections` with it raises `ValueError`.
+
 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
@@ -168,7 +176,8 @@ authentication wins. `vlm_url` is optional for clients that only authenticate.
 
 `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
+`parse_relay_frame()` (text frames only: `bytes` or `None` is an `InvalidFrame`) /
+`dump_frame()` (which refuses a frame over `MAX_FRAME_BYTES`). The spec is platform-service's
 `docs/adr/0001-relay-protocol.md`; both sides import this module instead of keeping a
 copy. The ADR's JSON examples ship with it (`visionai_sdk_python.relay.examples`:
 `example(name)` / `example_text(name)`), so every implementation tests against the same

visionai_sdk_python-2.2.0.dev4/PKG-INFO → visionai_sdk_python-2.2.0.dev6/README.md

@@ -1,21 +1,3 @@
-Metadata-Version: 2.4
-Name: visionai-sdk-python
-Version: 2.2.0.dev4
-Summary: VisionAI SDK for Python
-Author-email: Tony Yang <tonyyang@linkervision.com>
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-Requires-Dist: httpx<1,>=0.28.1
-Requires-Dist: pydantic>=2.12.5
-Requires-Dist: cryptography>=46.0.5
-Requires-Dist: PyJWT[cryptography]>=2.8.0
-Provides-Extra: requests
-Requires-Dist: requests<3,>=2.31; extra == "requests"
-Provides-Extra: aiohttp
-Requires-Dist: aiohttp<4,>=3.9; extra == "aiohttp"
-Provides-Extra: instrumentation
-Requires-Dist: wrapt<3,>=1.16; extra == "instrumentation"
-
 # VisionAI SDK for Python
 
 Python client library for VisionAI authentication and Vision Language Model (VLM) inference services.
@@ -148,10 +130,18 @@ client = Client(auth_url="...", vlm_url="...", credential=cred)   # vlm.chat() u
 
 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
+# Any other HTTP call with the same token, sent to the host you name; a 401 gets one
+# fresh token and one retry
 nodes = client.request("GET", "https://vs.example.com/mgmt/nodes").json()
 ```
 
+`request()` raises on a non-2xx like the resource methods (`AuthenticationError`,
+`ClientError`, `ServerError`, ...), unlike plain httpx, and sends the token to whatever
+host `url` names, so `url` comes from configuration or code, never from a caller. A
+client built with `http_client=` (or a credential with `http=`) uses that client's TLS,
+timeout and limits; passing `verify_ssl` / `timeout` / `max_connections` /
+`max_keepalive_connections` with it raises `ValueError`.
+
 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
@@ -168,7 +158,8 @@ authentication wins. `vlm_url` is optional for clients that only authenticate.
 
 `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
+`parse_relay_frame()` (text frames only: `bytes` or `None` is an `InvalidFrame`) /
+`dump_frame()` (which refuses a frame over `MAX_FRAME_BYTES`). The spec is platform-service's
 `docs/adr/0001-relay-protocol.md`; both sides import this module instead of keeping a
 copy. The ADR's JSON examples ship with it (`visionai_sdk_python.relay.examples`:
 `example(name)` / `example_text(name)`), so every implementation tests against the same

{visionai_sdk_python-2.2.0.dev4 → visionai_sdk_python-2.2.0.dev6}/src/visionai_sdk_python/_base.py

@@ -11,6 +11,29 @@ if TYPE_CHECKING:
     from .auth.credentials import AsyncClientCredentials, ClientCredentials
 
 
+_TRANSPORT_DEFAULTS = {
+    "verify_ssl": True,
+    "timeout": 10.0,
+    "max_connections": 100,
+    "max_keepalive_connections": 20,
+}
+
+
+def _transport_settings(injected: object | None, **given: object) -> dict:
+    """The settings for the httpx client the SDK builds, or an error with an injected one.
+
+    An injected client brings its own TLS, timeout and limits, so none of these
+    may be given with it: silently ignoring ``verify_ssl=False`` would surprise.
+    """
+    passed = {name: value for name, value in given.items() if value is not None}
+    if injected is not None and passed:
+        raise ValueError(
+            "the injected http client has its own verify, timeout and limits; "
+            f"do not pass {', '.join(passed)} with it"
+        )
+    return {**_TRANSPORT_DEFAULTS, **passed}
+
+
 class _BaseClient:
     """Base class for VisionAI SDK clients.
 
@@ -79,8 +102,12 @@ class _BaseClient:
 
     @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)."""
+        """The credential currently in use, or None.
+
+        Set by ``credential=`` or by ``auth.get_access_token()``; dropped by
+        ``login()`` / ``set_token()``, whose token then takes over. For callers
+        that need the raw token themselves (a WebSocket upgrade, another HTTP
+        library): ``credential.get_token()`` / ``credential.invalidate(token)``."""
         return self._credential
 
     @staticmethod

{visionai_sdk_python-2.2.0.dev4 → visionai_sdk_python-2.2.0.dev6}/src/visionai_sdk_python/async_client.py

@@ -1,6 +1,6 @@
 import httpx
 
-from ._base import _BaseClient
+from ._base import _BaseClient, _transport_settings
 from ._request_attribution import merge_request_attribution
 from .auth.async_resource import AsyncAuthResource
 from .auth.credentials import AsyncClientCredentials
@@ -14,32 +14,49 @@ class AsyncClient(_BaseClient):
         auth_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,
+        verify_ssl: bool | None = None,
+        timeout: float | None = None,
+        max_connections: int | None = None,
+        max_keepalive_connections: int | None = None,
         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,
-            allowed_issuers=allowed_issuers,
+        """See ``_BaseClient``. ``http_client`` is an httpx.AsyncClient to send through
+        (tests, shared pools): its own TLS, timeout and limits apply, so
+        ``verify_ssl`` / ``timeout`` / ``max_connections`` /
+        ``max_keepalive_connections`` cannot be given with it (``ValueError``);
+        the client closes only the one it created."""
+        if credential is not None and not isinstance(
+            credential, AsyncClientCredentials
+        ):
+            raise TypeError(
+                "AsyncClient takes an AsyncClientCredentials; Client takes a ClientCredentials"
+            )
+        settings = _transport_settings(
+            http_client,
             verify_ssl=verify_ssl,
             timeout=timeout,
             max_connections=max_connections,
             max_keepalive_connections=max_keepalive_connections,
+        )
+        super().__init__(
+            auth_url=auth_url,
+            vlm_url=vlm_url,
+            allowed_issuers=allowed_issuers,
             credential=credential,
+            **settings,
         )
-        self._client = http_client or httpx.AsyncClient(
-            verify=self.verify_ssl,
-            timeout=self.timeout,
-            limits=httpx.Limits(
-                max_connections=self.max_connections,
-                max_keepalive_connections=self.max_keepalive_connections,
-            ),
+        self._client = (
+            http_client
+            if http_client is not None
+            else httpx.AsyncClient(
+                verify=self.verify_ssl,
+                timeout=self.timeout,
+                limits=httpx.Limits(
+                    max_connections=self.max_connections,
+                    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
@@ -58,7 +75,11 @@ class AsyncClient(_BaseClient):
     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.
+        ``url`` is a full URL (the client has two bases); ``kwargs`` go to httpx. The
+        bearer token goes to whatever host ``url`` names, so ``url`` must come from
+        configuration or code, never from a caller's input; redirects are not
+        followed unless asked, and httpx drops the header on a cross-origin redirect.
+
         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

{visionai_sdk_python-2.2.0.dev4 → visionai_sdk_python-2.2.0.dev6}/src/visionai_sdk_python/auth/credentials.py

@@ -19,10 +19,12 @@ from typing import Any
 
 import httpx
 
-from .._base import _BaseClient
+from .._base import _BaseClient, _transport_settings
 from .._request_attribution import merge_request_attribution
 from ..endpoints import AuthEndpoint
 from ..exceptions import (
+    AuthenticationError,
+    PermissionDeniedError,
     RateLimitedError,
     VisionaiSDKError,
     from_transport_error,
@@ -37,6 +39,8 @@ logger = logging.getLogger(__name__)
 REFRESH_BUFFER_S = 300
 # After a 429 no mint is tried for this long.
 RATE_LIMIT_COOLDOWN_S = 3600
+# After a failed refresh the current token is served and no mint is tried for this long.
+REFRESH_RETRY_S = 30
 # A 401 on a token minted less than this long ago does not replace it.
 REPLACE_COOLDOWN_S = 30 * 60
 
@@ -73,12 +77,13 @@ class _Credentials:
         self._url = _BaseClient._build_url(self.auth_url, AuthEndpoint.CLIENT_TOKEN)
         self._current: AccessToken | None = None  # the token this credential holds
         self._blocked_until = 0.0
+        self._retry_after = 0.0  # set by a failed refresh
         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."""
         return self.client_id == client_id.strip() and hmac.compare_digest(
-            self._client_secret, client_secret
+            self._client_secret.encode(), client_secret.encode()
         )
 
     def _fresh(self) -> AccessToken | None:
@@ -129,12 +134,22 @@ class _Credentials:
         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."""
+        """A refresh failed: keep serving the current token while it is valid, else raise.
+
+        No mint is tried again for ``REFRESH_RETRY_S``. A refusal (401 / 403) is kept
+        too, because the issued token stays valid until it expires; it is logged as an
+        error since only the client credentials can be wrong.
+        """
         valid = self._valid()
         if valid is None:
             raise error
-        logger.warning(
-            "token refresh failed; using the current token until it expires",
+        self._retry_after = _now() + REFRESH_RETRY_S
+        refused = isinstance(error, (AuthenticationError, PermissionDeniedError))
+        logger.log(
+            logging.ERROR if refused else logging.WARNING,
+            "token refresh refused; check the client credentials"
+            if refused
+            else "token refresh failed; using the current token until it expires",
             extra={
                 "client_id": self.client_id,
                 "error": str(error),
@@ -143,8 +158,8 @@ class _Credentials:
         )
         return valid
 
-    def invalidate(self, token: str) -> bool:
-        """Report a 401 for ``token``. True: dropped, so the next ``get_token()`` mints.
+    def _invalidate(self, token: str) -> bool:
+        """Behind both ``invalidate()``; the sync class calls it under its lock.
 
         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
@@ -152,14 +167,16 @@ class _Credentials:
         often a persistent 401 can mint. While a mint is in flight the report is
         already being acted on.
         """
-        if self._current is None or token != self._current.token:
+        current = self._current
+        if current is None or token != current.token:
             return False
         if self._minting:
             return True
-        if _now() - self._current.issued_at < REPLACE_COOLDOWN_S:
+        age = _now() - current.issued_at
+        if age < 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),
+                int(age),
                 extra={"client_id": self.client_id},
             )
             return False
@@ -181,19 +198,35 @@ class ClientCredentials(_Credentials):
         client_secret: str,
         *,
         http: httpx.Client | None = None,
-        verify_ssl: bool = True,
-        timeout: float = 10.0,
+        verify_ssl: bool | None = None,
+        timeout: float | None = None,
     ) -> None:
         super().__init__(auth_url, client_id, client_secret)
-        self._http = http or httpx.Client(verify=verify_ssl, timeout=timeout)
+        own = _transport_settings(http, verify_ssl=verify_ssl, timeout=timeout)
+        self._http = (
+            http
+            if http is not None
+            else httpx.Client(verify=own["verify_ssl"], timeout=own["timeout"])
+        )
         self._http_owner = http is None  # a client we built is ours to close
         self._lock = threading.Lock()
 
+    def invalidate(self, token: str) -> bool:
+        """Report a 401 for ``token``. True: dropped, so the next ``get_token()`` mints.
+
+        Under the credential's lock: a report that arrives while another thread
+        mints waits for it, then finds the fresh token and leaves it alone.
+        """
+        with self._lock:
+            return self._invalidate(token)
+
     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.
+        that fails keeps serving the current token while Platform still accepts it
+        and is not retried for ``REFRESH_RETRY_S``; a refused one (401 / 403) is kept
+        too, logged as an error.
 
         Raises:
             AuthenticationError: Platform refused the client credentials (401).
@@ -206,6 +239,10 @@ class ClientCredentials(_Credentials):
                 fresh = self._fresh()
                 if fresh is not None:
                     return fresh
+                if _now() < self._retry_after:
+                    valid = self._valid()
+                    if valid is not None:
+                        return valid  # a refresh just failed; not again yet
             self._minting = True
             try:
                 kwargs = self._begin_mint()
@@ -237,7 +274,8 @@ class AsyncClientCredentials(_Credentials):
 
     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.
+    instance serves any number of clients and callers on one event loop; its
+    lock and ``httpx.AsyncClient`` bind to that loop.
     """
 
     def __init__(
@@ -247,14 +285,27 @@ class AsyncClientCredentials(_Credentials):
         client_secret: str,
         *,
         http: httpx.AsyncClient | None = None,
-        verify_ssl: bool = True,
-        timeout: float = 10.0,
+        verify_ssl: bool | None = None,
+        timeout: float | None = None,
     ) -> None:
         super().__init__(auth_url, client_id, client_secret)
-        self._http = http or httpx.AsyncClient(verify=verify_ssl, timeout=timeout)
+        own = _transport_settings(http, verify_ssl=verify_ssl, timeout=timeout)
+        self._http = (
+            http
+            if http is not None
+            else httpx.AsyncClient(verify=own["verify_ssl"], timeout=own["timeout"])
+        )
         self._http_owner = http is None  # a client we built is ours to close
         self._lock = asyncio.Lock()
 
+    def invalidate(self, token: str) -> bool:
+        """Report a 401 for ``token``. True: dropped, so the next ``get_token()`` mints.
+
+        No lock: there is no ``await`` here, so the check and the drop are one step
+        on the event loop; a mint in flight shows through ``_minting``.
+        """
+        return self._invalidate(token)
+
     async def get_token(self, *, force_refresh: bool = False) -> AccessToken:
         """The cached token, refreshed shortly before it expires.
 
@@ -266,6 +317,10 @@ class AsyncClientCredentials(_Credentials):
                 fresh = self._fresh()
                 if fresh is not None:
                     return fresh
+                if _now() < self._retry_after:
+                    valid = self._valid()
+                    if valid is not None:
+                        return valid  # a refresh just failed; not again yet
             self._minting = True
             try:
                 kwargs = self._begin_mint()

{visionai_sdk_python-2.2.0.dev4 → visionai_sdk_python-2.2.0.dev6}/src/visionai_sdk_python/client.py

@@ -1,6 +1,6 @@
 import httpx
 
-from ._base import _BaseClient
+from ._base import _BaseClient, _transport_settings
 from ._request_attribution import merge_request_attribution
 from .auth.credentials import ClientCredentials
 from .auth.resource import AuthResource
@@ -14,32 +14,47 @@ class Client(_BaseClient):
         auth_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,
+        verify_ssl: bool | None = None,
+        timeout: float | None = None,
+        max_connections: int | None = None,
+        max_keepalive_connections: int | None = None,
         credential: ClientCredentials | None = None,
         http_client: httpx.Client | None = None,
     ) -> None:
-        """See ``_BaseClient``; ``http_client`` is an httpx.Client to send through
-        (tests, shared pools); the client closes only the one it created."""
-        super().__init__(
-            auth_url=auth_url,
-            vlm_url=vlm_url,
-            allowed_issuers=allowed_issuers,
+        """See ``_BaseClient``. ``http_client`` is an httpx.Client to send through
+        (tests, shared pools): its own TLS, timeout and limits apply, so
+        ``verify_ssl`` / ``timeout`` / ``max_connections`` /
+        ``max_keepalive_connections`` cannot be given with it (``ValueError``);
+        the client closes only the one it created."""
+        if credential is not None and not isinstance(credential, ClientCredentials):
+            raise TypeError(
+                "Client takes a ClientCredentials; AsyncClient takes an AsyncClientCredentials"
+            )
+        settings = _transport_settings(
+            http_client,
             verify_ssl=verify_ssl,
             timeout=timeout,
             max_connections=max_connections,
             max_keepalive_connections=max_keepalive_connections,
+        )
+        super().__init__(
+            auth_url=auth_url,
+            vlm_url=vlm_url,
+            allowed_issuers=allowed_issuers,
             credential=credential,
+            **settings,
         )
-        self._client = http_client or httpx.Client(
-            verify=self.verify_ssl,
-            timeout=self.timeout,
-            limits=httpx.Limits(
-                max_connections=self.max_connections,
-                max_keepalive_connections=self.max_keepalive_connections,
-            ),
+        self._client = (
+            http_client
+            if http_client is not None
+            else httpx.Client(
+                verify=self.verify_ssl,
+                timeout=self.timeout,
+                limits=httpx.Limits(
+                    max_connections=self.max_connections,
+                    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
@@ -58,7 +73,11 @@ class Client(_BaseClient):
     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.
+        ``url`` is a full URL (the client has two bases); ``kwargs`` go to httpx. The
+        bearer token goes to whatever host ``url`` names, so ``url`` must come from
+        configuration or code, never from a caller's input; redirects are not
+        followed unless asked, and httpx drops the header on a cross-origin redirect.
+
         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
@@ -79,7 +98,7 @@ class Client(_BaseClient):
             if self._credential is None or not self._resendable(kwargs):
                 raise
             self._credential.invalidate(token)
-            replacement = (self._credential.get_token()).token
+            replacement = self._credential.get_token().token
             if replacement == token:
                 raise
         return self._request(method, url, **self._with_auth(kwargs, replacement))
@@ -120,7 +139,7 @@ class Client(_BaseClient):
             AuthenticationError: If no token is available or token expired without credentials.
         """
         if self._credential is not None:
-            return (self._credential.get_token()).token
+            return self._credential.get_token().token
         if self._access_token is None:
             raise AuthenticationError(
                 "Not authenticated. Call login() or get_access_token() first."

{visionai_sdk_python-2.2.0.dev4 → visionai_sdk_python-2.2.0.dev6}/src/visionai_sdk_python/relay/__init__.py

@@ -9,6 +9,7 @@ from .protocol import (
     HEARTBEAT_INTERVAL_S,
     MAX_BODY_BYTES,
     MAX_FRAME_BYTES,
+    MAX_MESSAGE_CHARS,
     REGISTER_DEADLINE_S,
     RELAY_TIMEOUT_S,
     STALE_AFTER_S,
@@ -18,6 +19,7 @@ from .protocol import (
     Error,
     ErrorCode,
     Frame,
+    FrameTooLarge,
     Heartbeat,
     InvalidFrame,
     ModelEntry,
@@ -40,6 +42,7 @@ __all__ = [
     "HEARTBEAT_INTERVAL_S",
     "MAX_BODY_BYTES",
     "MAX_FRAME_BYTES",
+    "MAX_MESSAGE_CHARS",
     "REGISTER_DEADLINE_S",
     "RELAY_TIMEOUT_S",
     "STALE_AFTER_S",
@@ -49,6 +52,7 @@ __all__ = [
     "Error",
     "ErrorCode",
     "Frame",
+    "FrameTooLarge",
     "Heartbeat",
     "InvalidFrame",
     "ModelEntry",

{visionai_sdk_python-2.2.0.dev4 → visionai_sdk_python-2.2.0.dev6}/src/visionai_sdk_python/relay/protocol.py

@@ -28,6 +28,8 @@ MAX_BODY_BYTES = 15 * 1024 * 1024
 # Timeouts nest: the agent waits for VS, the relay waits a little longer for the agent.
 AGENT_TIMEOUT_S = 100
 RELAY_TIMEOUT_S = 110.0
+# An `error` echoes parts of the peer's frame; cut them so the error fits a frame.
+MAX_MESSAGE_CHARS = 200
 
 # Platform workspace ids: lowercase hyphenated UUIDs.
 UUID_RE = re.compile(r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}")
@@ -58,6 +60,7 @@ class ErrorCode(StrEnum):
     PATH_NOT_ALLOWED = "path_not_allowed"
     UPSTREAM_UNREACHABLE = "upstream_unreachable"
     UPSTREAM_TIMEOUT = "upstream_timeout"
+    UPSTREAM_TOO_LARGE = "upstream_too_large"
 
 
 class Frame(BaseModel):
@@ -133,26 +136,51 @@ _relay_frame = TypeAdapter(Annotated[RelayFrame, Field(discriminator="type")])
 
 
 class InvalidFrame(ValueError):
-    """A frame the receiver cannot read; the text is safe to send back in an ``error``."""
+    """A frame the receiver cannot read; the text is safe to send back in an ``error``.
+
+    Parts of the text come from the peer's frame, so it is cut at ``MAX_MESSAGE_CHARS``
+    and a ``request_id`` longer than that is dropped.
+    """
 
     def __init__(self, message: str, request_id: str | None = None) -> None:
+        if len(message) > MAX_MESSAGE_CHARS:
+            message = message[: MAX_MESSAGE_CHARS - 1] + "…"
+        if request_id is not None and len(request_id) > MAX_MESSAGE_CHARS:
+            request_id = None
+            message += " (request_id too long, dropped)"
         super().__init__(message)
         self.request_id = request_id
 
 
-def parse_agent_frame(text: str) -> AgentFrame:
-    """A frame the relay received from an agent."""
-    return _parse(text, _agent_frame)
+class FrameTooLarge(ValueError):
+    """The encoded frame exceeds ``MAX_FRAME_BYTES``; the receiver would close with 1009."""
+
+    def __init__(self, size: int) -> None:
+        super().__init__(f"frame is {size} bytes; the limit is {MAX_FRAME_BYTES}")
+        self.size = size
+
+
+def parse_agent_frame(message: str | bytes | None) -> AgentFrame:
+    """A frame the relay received from an agent.
+
+    ``message`` is what the WebSocket library handed over: ``str`` for a text frame,
+    ``bytes`` (or Starlette's ``None``) for a binary one, which the protocol does
+    not use and is an ``InvalidFrame`` like any other unreadable frame.
+    """
+    return _parse(message, _agent_frame)
 
 
-def parse_relay_frame(text: str) -> RelayFrame:
-    """A frame the agent received from the relay."""
-    return _parse(text, _relay_frame)
+def parse_relay_frame(message: str | bytes | None) -> RelayFrame:
+    """A frame the agent received from the relay; see ``parse_agent_frame``."""
+    return _parse(message, _relay_frame)
 
 
-def _parse(text: str, adapter: TypeAdapter):
+def _parse(message: str | bytes | None, adapter: TypeAdapter):
+    if not isinstance(message, str):
+        # json.loads() would happily read JSON out of a binary frame; say no once here.
+        raise InvalidFrame("binary frames are not used")
     try:
-        data = json.loads(text)
+        data = json.loads(message)
     except ValueError:
         raise InvalidFrame("frame is not JSON") from None
     if not isinstance(data, dict):
@@ -175,4 +203,9 @@ def _parse(text: str, adapter: TypeAdapter):
 
 
 def dump_frame(frame: BaseModel) -> str:
-    return frame.model_dump_json(exclude_none=True)
+    """The frame as JSON text, or ``FrameTooLarge`` when a receiver would refuse it."""
+    text = frame.model_dump_json(exclude_none=True)
+    size = len(text.encode())
+    if size > MAX_FRAME_BYTES:
+        raise FrameTooLarge(size)
+    return text

visionai_sdk_python-2.2.0.dev4/README.md → visionai_sdk_python-2.2.0.dev6/src/visionai_sdk_python.egg-info/PKG-INFO

@@ -1,3 +1,21 @@
+Metadata-Version: 2.4
+Name: visionai-sdk-python
+Version: 2.2.0.dev6
+Summary: VisionAI SDK for Python
+Author-email: Tony Yang <tonyyang@linkervision.com>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.28.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: cryptography>=46.0.5
+Requires-Dist: PyJWT[cryptography]>=2.8.0
+Provides-Extra: requests
+Requires-Dist: requests<3,>=2.31; extra == "requests"
+Provides-Extra: aiohttp
+Requires-Dist: aiohttp<4,>=3.9; extra == "aiohttp"
+Provides-Extra: instrumentation
+Requires-Dist: wrapt<3,>=1.16; extra == "instrumentation"
+
 # VisionAI SDK for Python
 
 Python client library for VisionAI authentication and Vision Language Model (VLM) inference services.
@@ -130,10 +148,18 @@ client = Client(auth_url="...", vlm_url="...", credential=cred)   # vlm.chat() u
 
 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
+# Any other HTTP call with the same token, sent to the host you name; a 401 gets one
+# fresh token and one retry
 nodes = client.request("GET", "https://vs.example.com/mgmt/nodes").json()
 ```
 
+`request()` raises on a non-2xx like the resource methods (`AuthenticationError`,
+`ClientError`, `ServerError`, ...), unlike plain httpx, and sends the token to whatever
+host `url` names, so `url` comes from configuration or code, never from a caller. A
+client built with `http_client=` (or a credential with `http=`) uses that client's TLS,
+timeout and limits; passing `verify_ssl` / `timeout` / `max_connections` /
+`max_keepalive_connections` with it raises `ValueError`.
+
 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
@@ -150,7 +176,8 @@ authentication wins. `vlm_url` is optional for clients that only authenticate.
 
 `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
+`parse_relay_frame()` (text frames only: `bytes` or `None` is an `InvalidFrame`) /
+`dump_frame()` (which refuses a frame over `MAX_FRAME_BYTES`). The spec is platform-service's
 `docs/adr/0001-relay-protocol.md`; both sides import this module instead of keeping a
 copy. The ADR's JSON examples ship with it (`visionai_sdk_python.relay.examples`:
 `example(name)` / `example_text(name)`), so every implementation tests against the same

{visionai_sdk_python-2.2.0.dev4 → visionai_sdk_python-2.2.0.dev6}/src/visionai_sdk_python.egg-info/SOURCES.txt

@@ -55,6 +55,7 @@ tests/test_client.py
 tests/test_credentials.py
 tests/test_instrumentation.py
 tests/test_request.py
+tests/test_transport_options.py
 tests/test_vlm_preprocess.py
 tests/relay/__init__.py
 tests/relay/test_protocol.py

{visionai_sdk_python-2.2.0.dev4 → visionai_sdk_python-2.2.0.dev6}/src/visionai_sdk_python.egg-info/scm_file_list.json

@@ -51,6 +51,7 @@
     "tests/test_credentials.py",
     "tests/test_instrumentation.py",
     "tests/test_request.py",
+    "tests/test_transport_options.py",
     "tests/test_vlm_preprocess.py",
     "uv.lock"
   ]

visionai_sdk_python-2.2.0.dev6/src/visionai_sdk_python.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "2.2.0.dev6",
+  "distance": 0,
+  "node": "g87a0a05ee801b6dfe5be6f6fe205b2917d9363ad",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-27"
+}

{visionai_sdk_python-2.2.0.dev4 → visionai_sdk_python-2.2.0.dev6}/tests/relay/test_protocol.py

@@ -5,7 +5,10 @@ import json
 import pytest
 
 from visionai_sdk_python.relay import (
+    MAX_FRAME_BYTES,
+    MAX_MESSAGE_CHARS,
     Error,
+    FrameTooLarge,
     Heartbeat,
     InvalidFrame,
     Register,
@@ -101,6 +104,13 @@ def test_unknown_reasons_and_codes_are_accepted_as_strings():
 @pytest.mark.parametrize(
     ("parse", "text", "message", "request_id"),
     [
+        (
+            parse_agent_frame,
+            b'{"type": "heartbeat"}',
+            "binary frames are not used",
+            None,
+        ),
+        (parse_relay_frame, None, "binary frames are not used", None),
         (parse_agent_frame, "not json", "frame is not JSON", None),
         (parse_agent_frame, "[1, 2]", "frame is not a JSON object", None),
         (parse_agent_frame, '{"agent_id": "a"}', "frame has no type", None),
@@ -173,3 +183,30 @@ def test_workspace_id_format(value, ok):
 def test_every_shipped_example_is_valid_json_with_a_type():
     for name in NAMES:
         assert isinstance(json.loads(example(name))["type"], str), name
+
+
+def test_an_error_message_is_cut_so_it_fits_a_frame():
+    with pytest.raises(InvalidFrame) as exc:
+        parse_agent_frame(json.dumps({"type": "x" * 1_000_000}))
+
+    assert len(str(exc.value)) == MAX_MESSAGE_CHARS
+    assert str(exc.value).endswith("…")
+
+
+def test_an_oversized_request_id_is_dropped_from_the_error():
+    frame = {"type": "request", "request_id": "r" * 1_000_000}
+    with pytest.raises(InvalidFrame) as exc:
+        parse_relay_frame(json.dumps(frame))
+
+    assert exc.value.request_id is None
+    assert str(exc.value).endswith("(request_id too long, dropped)")
+
+
+def test_dump_frame_refuses_a_frame_the_receiver_would_close_on():
+    frame = Response(request_id="r1", status=200, body="x" * MAX_FRAME_BYTES)
+
+    with pytest.raises(FrameTooLarge) as exc:
+        dump_frame(frame)
+
+    assert exc.value.size > MAX_FRAME_BYTES
+    assert dump_frame(Response(request_id="r1", status=200, body="x"))

{visionai_sdk_python-2.2.0.dev4 → visionai_sdk_python-2.2.0.dev6}/tests/test_credentials.py

@@ -1,4 +1,5 @@
 import asyncio
+import threading
 
 import httpx
 import pytest
@@ -22,6 +23,7 @@ from visionai_sdk_python.auth import credentials as credentials_module
 from visionai_sdk_python.auth.credentials import (
     RATE_LIMIT_COOLDOWN_S,
     REFRESH_BUFFER_S,
+    REFRESH_RETRY_S,
     REPLACE_COOLDOWN_S,
 )
 from visionai_sdk_python.exceptions import (
@@ -266,6 +268,12 @@ async def test_get_access_token_keeps_its_result_and_refreshes_through_a_credent
     assert await client._ensure_token() == "tok-2"
 
 
+def test_is_for_compares_non_ascii_secrets_too():
+    cred = ClientCredentials(AUTH_URL, "cid", "pässwörd")
+    assert cred.is_for("cid", "pässwörd")
+    assert not cred.is_for("cid", "pässword")
+
+
 async def test_repeated_get_access_token_reuses_the_credential(platform, clock):
     client = AsyncClient(AUTH_URL, VLM_URL)
     client._client = httpx.AsyncClient(transport=httpx.MockTransport(platform.handler))
@@ -370,6 +378,42 @@ async def test_get_access_token_force_refresh_mints_again(platform, clock):
     assert await client._ensure_token() == "tok-2"
 
 
+async def test_a_failed_refresh_is_not_retried_for_a_while(platform, cred, clock):
+    assert (await cred.get_token()).token == "tok-1"
+    clock[0] += EXPIRES_IN - 100  # inside the refresh window, token still valid
+    platform.status = 503
+
+    assert (await cred.get_token()).token == "tok-1"
+    assert (await cred.get_token()).token == "tok-1"  # inside the backoff: no attempt
+    assert len(platform.requests) == 2
+
+    clock[0] += REFRESH_RETRY_S + 1
+    platform.status = None
+    assert (await cred.get_token()).token == "tok-2"
+    assert len(platform.requests) == 3
+
+
+async def test_a_refused_refresh_is_an_error_but_the_token_is_kept(
+    platform, cred, clock, caplog
+):
+    assert (await cred.get_token()).token == "tok-1"
+    clock[0] += EXPIRES_IN - 100
+    platform.status = 401
+
+    with caplog.at_level("ERROR"):
+        assert (await cred.get_token()).token == "tok-1"
+
+    assert "token refresh refused" in caplog.text
+    assert caplog.records[-1].levelname == "ERROR"
+
+
+def test_a_credential_of_the_other_flavour_is_rejected_at_construction():
+    with pytest.raises(TypeError):
+        Client(AUTH_URL, credential=AsyncClientCredentials(AUTH_URL, "id", "secret"))
+    with pytest.raises(TypeError):
+        AsyncClient(AUTH_URL, credential=ClientCredentials(AUTH_URL, "id", "secret"))
+
+
 async def test_a_401_reported_during_a_refresh_leaves_the_refresh_alone(
     platform, clock
 ):
@@ -400,3 +444,41 @@ async def test_a_401_reported_during_a_refresh_leaves_the_refresh_alone(
     clock[0] += REPLACE_COOLDOWN_S + 1
     assert cred.invalidate("tok-2") is True
     assert platform.minted == 2
+
+
+def test_sync_invalidate_waits_for_a_mint_in_another_thread():
+    """Without the lock the report would drop the token the other thread just minted."""
+    entered, release = threading.Event(), threading.Event()
+    tokens = iter(["old", "new"])
+
+    def platform(request: httpx.Request) -> httpx.Response:
+        token = next(tokens)
+        if token == "new":
+            entered.set()
+            release.wait(5)
+        return httpx.Response(
+            200,
+            json={"access_token": token, "expires_in": 3600, "token_type": "Bearer"},
+        )
+
+    cred = ClientCredentials(
+        "http://platform.test",
+        "cid",
+        "secret",
+        http=httpx.Client(transport=httpx.MockTransport(platform)),
+    )
+    old = cred.get_token().token
+    minter = threading.Thread(target=cred.get_token, kwargs={"force_refresh": True})
+    minter.start()
+    assert entered.wait(5)
+    result: list[bool] = []
+    reporter = threading.Thread(target=lambda: result.append(cred.invalidate(old)))
+    reporter.start()
+    reporter.join(0.2)
+
+    assert reporter.is_alive()  # blocked behind the mint, not racing it
+    release.set()
+    minter.join(5)
+    reporter.join(5)
+    assert result == [False]
+    assert cred.get_token().token == "new"

visionai_sdk_python-2.2.0.dev6/tests/test_transport_options.py

@@ -0,0 +1,57 @@
+"""An injected http client brings its own transport settings; the SDK refuses to take more."""
+
+import httpx
+import pytest
+
+from visionai_sdk_python import (
+    AsyncClient,
+    AsyncClientCredentials,
+    Client,
+    ClientCredentials,
+)
+
+
+def _sync_http() -> httpx.Client:
+    return httpx.Client(transport=httpx.MockTransport(lambda r: httpx.Response(200)))
+
+
+def _async_http() -> httpx.AsyncClient:
+    return httpx.AsyncClient(
+        transport=httpx.MockTransport(lambda r: httpx.Response(200))
+    )
+
+
+@pytest.mark.parametrize(
+    "build",
+    [
+        lambda: Client("http://a", http_client=_sync_http(), timeout=1.0),
+        lambda: Client("http://a", http_client=_sync_http(), verify_ssl=False),
+        lambda: Client("http://a", http_client=_sync_http(), max_connections=5),
+        lambda: AsyncClient(
+            "http://a", http_client=_async_http(), max_keepalive_connections=5
+        ),
+        lambda: ClientCredentials(
+            "http://a", "id", "s", http=_sync_http(), timeout=1.0
+        ),
+        lambda: AsyncClientCredentials(
+            "http://a", "id", "s", http=_async_http(), verify_ssl=False
+        ),
+    ],
+)
+def test_transport_options_are_refused_with_an_injected_client(build):
+    with pytest.raises(ValueError, match="has its own verify, timeout and limits"):
+        build()
+
+
+def test_defaults_apply_when_the_sdk_builds_the_client():
+    client = Client("http://a")
+
+    assert (client.verify_ssl, client.timeout) == (True, 10.0)
+    assert (client.max_connections, client.max_keepalive_connections) == (100, 20)
+    assert Client("http://a", timeout=3.0, verify_ssl=False).timeout == 3.0
+
+
+def test_an_injected_client_is_used_as_is():
+    http = _sync_http()
+
+    assert Client("http://a", http_client=http)._client is http

visionai_sdk_python-2.2.0.dev4/src/visionai_sdk_python.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "2.2.0.dev4",
-  "distance": 0,
-  "node": "gc851da12b0ae901b04a22a963d81b8fba6fe5f26",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-10-21"
-}