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

{visionai_sdk_python-2.2.0.dev3 → visionai_sdk_python-2.2.0.dev5}/.gitignore

@@ -67,6 +67,8 @@ dmypy.json
 
 # Local test usage
 examples/
+# The relay protocol's ADR examples are package data, not scratch files.
+!src/visionai_sdk_python/relay/examples/
 
 # Claude
 .claude/

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: visionai-sdk-python
-Version: 2.2.0.dev3
+Version: 2.2.0.dev5
 Summary: VisionAI SDK for Python
 Author-email: Tony Yang <tonyyang@linkervision.com>
 Requires-Python: >=3.11
@@ -148,7 +148,8 @@ 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()
 ```
 
@@ -168,10 +169,11 @@ 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()` / `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, and the ADR's JSON examples are this package's tests. It is internal to the
-platform and not a public API.
+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
+frames. It is internal to the platform and not a public API.
 
 ## VLM Inference
 

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

@@ -130,7 +130,8 @@ 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()
 ```
 
@@ -150,10 +151,11 @@ 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()` / `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, and the ADR's JSON examples are this package's tests. It is internal to the
-platform and not a public API.
+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
+frames. It is internal to the platform and not a public API.
 
 ## VLM Inference
 

{visionai_sdk_python-2.2.0.dev3 → visionai_sdk_python-2.2.0.dev5}/pyproject.toml

@@ -32,6 +32,9 @@ build-backend = "setuptools.build_meta"
 
 [tool.setuptools_scm]
 
+[tool.setuptools.package-data]
+"visionai_sdk_python.relay.examples" = ["*.json"]
+
 [tool.uv]
 # Mitigate supply chain attacks. Kept in sync with
 # .github/dependabot.yml's cooldown.default-days (3 days, matching the

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

@@ -58,7 +58,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.dev3 → visionai_sdk_python-2.2.0.dev5}/src/visionai_sdk_python/auth/credentials.py

@@ -237,7 +237,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__(

{visionai_sdk_python-2.2.0.dev3 → visionai_sdk_python-2.2.0.dev5}/src/visionai_sdk_python/client.py

@@ -58,7 +58,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

{visionai_sdk_python-2.2.0.dev3 → visionai_sdk_python-2.2.0.dev5}/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.dev5/src/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-2.2.0.dev3 → visionai_sdk_python-2.2.0.dev5}/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,13 +136,30 @@ _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
 
 
+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(text: str) -> AgentFrame:
     """A frame the relay received from an agent."""
     return _parse(text, _agent_frame)
@@ -175,4 +195,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.dev3 → visionai_sdk_python-2.2.0.dev5}/src/visionai_sdk_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: visionai-sdk-python
-Version: 2.2.0.dev3
+Version: 2.2.0.dev5
 Summary: VisionAI SDK for Python
 Author-email: Tony Yang <tonyyang@linkervision.com>
 Requires-Python: >=3.11
@@ -148,7 +148,8 @@ 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()
 ```
 
@@ -168,10 +169,11 @@ 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()` / `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, and the ADR's JSON examples are this package's tests. It is internal to the
-platform and not a public API.
+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
+frames. It is internal to the platform and not a public API.
 
 ## VLM Inference
 

{visionai_sdk_python-2.2.0.dev3 → visionai_sdk_python-2.2.0.dev5}/src/visionai_sdk_python.egg-info/SOURCES.txt

@@ -32,6 +32,15 @@ src/visionai_sdk_python/auth/models.py
 src/visionai_sdk_python/auth/resource.py
 src/visionai_sdk_python/relay/__init__.py
 src/visionai_sdk_python/relay/protocol.py
+src/visionai_sdk_python/relay/examples/__init__.py
+src/visionai_sdk_python/relay/examples/error_connection.json
+src/visionai_sdk_python/relay/examples/error_request.json
+src/visionai_sdk_python/relay/examples/heartbeat.json
+src/visionai_sdk_python/relay/examples/register.json
+src/visionai_sdk_python/relay/examples/registered.json
+src/visionai_sdk_python/relay/examples/request.json
+src/visionai_sdk_python/relay/examples/response.json
+src/visionai_sdk_python/relay/examples/response_text.json
 src/visionai_sdk_python/vlm/__init__.py
 src/visionai_sdk_python/vlm/_mixin.py
 src/visionai_sdk_python/vlm/async_resource.py
@@ -48,12 +57,4 @@ tests/test_instrumentation.py
 tests/test_request.py
 tests/test_vlm_preprocess.py
 tests/relay/__init__.py
-tests/relay/test_protocol.py
-tests/relay/fixtures/adr/error_connection.json
-tests/relay/fixtures/adr/error_request.json
-tests/relay/fixtures/adr/heartbeat.json
-tests/relay/fixtures/adr/register.json
-tests/relay/fixtures/adr/registered.json
-tests/relay/fixtures/adr/request.json
-tests/relay/fixtures/adr/response.json
-tests/relay/fixtures/adr/response_text.json
+tests/relay/test_protocol.py

{visionai_sdk_python-2.2.0.dev3 → visionai_sdk_python-2.2.0.dev5}/src/visionai_sdk_python.egg-info/scm_file_list.json

@@ -25,6 +25,15 @@
     "src/visionai_sdk_python/instrumentation.py",
     "src/visionai_sdk_python/py.typed",
     "src/visionai_sdk_python/relay/__init__.py",
+    "src/visionai_sdk_python/relay/examples/__init__.py",
+    "src/visionai_sdk_python/relay/examples/error_connection.json",
+    "src/visionai_sdk_python/relay/examples/error_request.json",
+    "src/visionai_sdk_python/relay/examples/heartbeat.json",
+    "src/visionai_sdk_python/relay/examples/register.json",
+    "src/visionai_sdk_python/relay/examples/registered.json",
+    "src/visionai_sdk_python/relay/examples/request.json",
+    "src/visionai_sdk_python/relay/examples/response.json",
+    "src/visionai_sdk_python/relay/examples/response_text.json",
     "src/visionai_sdk_python/relay/protocol.py",
     "src/visionai_sdk_python/vlm/__init__.py",
     "src/visionai_sdk_python/vlm/_mixin.py",
@@ -35,14 +44,6 @@
     "tests/__init__.py",
     "tests/constants.py",
     "tests/relay/__init__.py",
-    "tests/relay/fixtures/adr/error_connection.json",
-    "tests/relay/fixtures/adr/error_request.json",
-    "tests/relay/fixtures/adr/heartbeat.json",
-    "tests/relay/fixtures/adr/register.json",
-    "tests/relay/fixtures/adr/registered.json",
-    "tests/relay/fixtures/adr/request.json",
-    "tests/relay/fixtures/adr/response.json",
-    "tests/relay/fixtures/adr/response_text.json",
     "tests/relay/test_protocol.py",
     "tests/test__base.py",
     "tests/test_async_client.py",

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

@@ -0,0 +1,8 @@
+{
+  "tag": "2.2.0.dev5",
+  "distance": 0,
+  "node": "g300feb4397722a72a04551325a2fc4d0d8c0e3f3",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-22"
+}

{visionai_sdk_python-2.2.0.dev3 → visionai_sdk_python-2.2.0.dev5}/tests/relay/test_protocol.py

@@ -1,12 +1,14 @@
 """The relay wire format: the ADR's JSON examples parse on both sides, bad frames say why."""
 
 import json
-from pathlib import Path
 
 import pytest
 
 from visionai_sdk_python.relay import (
+    MAX_FRAME_BYTES,
+    MAX_MESSAGE_CHARS,
     Error,
+    FrameTooLarge,
     Heartbeat,
     InvalidFrame,
     Register,
@@ -18,13 +20,8 @@ from visionai_sdk_python.relay import (
     parse_agent_frame,
     parse_relay_frame,
 )
-
-FIXTURES = Path(__file__).parent / "fixtures" / "adr"
-
-
-def example(name: str) -> str:
-    """One of the ADR's JSON examples, as the text that goes over the wire."""
-    return (FIXTURES / f"{name}.json").read_text()
+from visionai_sdk_python.relay.examples import NAMES
+from visionai_sdk_python.relay.examples import example_text as example
 
 
 @pytest.mark.parametrize(
@@ -174,3 +171,35 @@ def test_dump_frame_drops_none_fields():
 )
 def test_workspace_id_format(value, ok):
     assert is_workspace_id(value) is 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.dev3/src/visionai_sdk_python.egg-info/scm_version.json

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