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

visionai_sdk_python/relay/protocol.py

@@ -0,0 +1,178 @@
+"""Wire format between platform-relay and platform-edge-agent.
+
+The spec is platform-service's ``docs/adr/0001-relay-protocol.md``; this module is
+the one implementation both sides import. Frames are JSON objects told apart by
+``type``. Receivers ignore unknown fields, and the string-typed ``reason`` /
+``code`` fields accept values they do not know, so either side can be upgraded
+first.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from enum import IntEnum, StrEnum
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, TypeAdapter, ValidationError
+
+SUBPROTOCOL = "platform-relay.v1"
+# The first frame after the upgrade must be `register`, this soon; else the relay closes 1008.
+REGISTER_DEADLINE_S = 10.0
+HEARTBEAT_INTERVAL_S = 30.0
+# No frame for this long: the relay closes 4001 and forgets the connection.
+STALE_AFTER_S = 90.0
+# Both sides refuse to send a larger frame; the relay refuses a larger chat body (413).
+MAX_FRAME_BYTES = 16 * 1024 * 1024
+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
+
+# 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}")
+
+
+def is_workspace_id(value: str) -> bool:
+    return UUID_RE.fullmatch(value) is not None
+
+
+class CloseCode(IntEnum):
+    NORMAL = 1000
+    GOING_AWAY = 1001
+    POLICY_VIOLATION = 1008
+    TOO_BIG = 1009
+    REPLACED = 4000
+    STALE = 4001
+
+
+class RejectReason(StrEnum):
+    INVALID_ID = "invalid_id"
+    CLUSTER_MISMATCH = "cluster_mismatch"
+    PLATFORM_UNAVAILABLE = "platform_unavailable"
+
+
+class ErrorCode(StrEnum):
+    INVALID_MESSAGE = "invalid_message"
+    UNKNOWN_WORKSPACE = "unknown_workspace"
+    PATH_NOT_ALLOWED = "path_not_allowed"
+    UPSTREAM_UNREACHABLE = "upstream_unreachable"
+    UPSTREAM_TIMEOUT = "upstream_timeout"
+
+
+class Frame(BaseModel):
+    # Receivers ignore unknown fields.
+    model_config = ConfigDict(extra="ignore")
+
+
+class ModelEntry(Frame):
+    name: str
+    version: str
+    # Required by the ADR. A receiver counts None as 0 and logs it: the sender has a bug.
+    replicas: int | None = Field(default=None, ge=0)
+
+
+class WorkspaceEntry(Frame):
+    id: str
+    models: list[ModelEntry] = Field(default_factory=list)
+
+
+class Register(Frame):
+    type: Literal["register"] = "register"
+    agent_id: str = Field(min_length=1)
+    cluster_id: str = Field(min_length=1)
+    workspaces: list[WorkspaceEntry] = Field(default_factory=list)
+
+
+class Rejected(Frame):
+    id: str
+    reason: str  # a RejectReason; a plain str so an older agent accepts new reasons
+
+
+class Registered(Frame):
+    type: Literal["registered"] = "registered"
+    accepted: list[str] = Field(default_factory=list)
+    rejected: list[Rejected] = Field(default_factory=list)
+
+
+class Heartbeat(Frame):
+    type: Literal["heartbeat"] = "heartbeat"
+
+
+class Request(Frame):
+    type: Literal["request"] = "request"
+    request_id: str
+    workspace_id: str
+    method: str
+    path: str
+    headers: dict[str, str] = Field(default_factory=dict)
+    body: dict | list | str | None = None
+    timeout_s: int = Field(gt=0)
+
+
+class Response(Frame):
+    type: Literal["response"] = "response"
+    request_id: str
+    status: int
+    headers: dict[str, str] = Field(default_factory=dict)
+    body: dict | list | str | None = None
+
+
+class Error(Frame):
+    type: Literal["error"] = "error"
+    request_id: str | None = None
+    code: str  # an ErrorCode; a plain str so an older receiver accepts new codes
+    message: str
+
+
+# What each side receives.
+AgentFrame = Register | Heartbeat | Response | Error  # agent -> relay
+RelayFrame = Registered | Request | Error  # relay -> agent
+_agent_frame = TypeAdapter(Annotated[AgentFrame, Field(discriminator="type")])
+_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``."""
+
+    def __init__(self, message: str, request_id: str | None = None) -> None:
+        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)
+
+
+def parse_relay_frame(text: str) -> RelayFrame:
+    """A frame the agent received from the relay."""
+    return _parse(text, _relay_frame)
+
+
+def _parse(text: str, adapter: TypeAdapter):
+    try:
+        data = json.loads(text)
+    except ValueError:
+        raise InvalidFrame("frame is not JSON") from None
+    if not isinstance(data, dict):
+        raise InvalidFrame("frame is not a JSON object")
+    kind = data.get("type")
+    if not isinstance(kind, str):
+        raise InvalidFrame("frame has no type")
+    request_id = data.get("request_id")
+    request_id = request_id if isinstance(request_id, str) else None
+    try:
+        return adapter.validate_python(data)
+    except ValidationError as exc:
+        if any(err["type"] == "union_tag_invalid" for err in exc.errors()):
+            raise InvalidFrame(f"unknown type {kind!r}", request_id) from None
+        fields = ", ".join(
+            ".".join(str(part) for part in err["loc"][1:]) or "body"
+            for err in exc.errors()
+        )
+        raise InvalidFrame(f"{kind} fails validation: {fields}", request_id) from None
+
+
+def dump_frame(frame: BaseModel) -> str:
+    return frame.model_dump_json(exclude_none=True)

visionai_sdk_python/vlm/async_resource.py

@@ -51,7 +51,9 @@ class AsyncVLMResource(VLMMixin):
         # I/O operation (async); the client adds the token and retries once on 401
         response = await self._sdk_client.request(
             "POST",
-            self._sdk_client._build_url(self._sdk_client._vlm_base(), VLMEndpoint.CHAT),
+            self._sdk_client._build_url(
+                self._sdk_client._require_vlm_url(), VLMEndpoint.CHAT
+            ),
             json=body,
         )
 
@@ -82,7 +84,7 @@ class AsyncVLMResource(VLMMixin):
         response = await self._sdk_client.request(
             "GET",
             self._sdk_client._build_url(
-                self._sdk_client._vlm_base(), f"{VLMEndpoint.CHAT}/{result_id}"
+                self._sdk_client._require_vlm_url(), f"{VLMEndpoint.CHAT}/{result_id}"
             ),
         )
 

visionai_sdk_python/vlm/resource.py

@@ -51,7 +51,9 @@ class VLMResource(VLMMixin):
         # I/O operation (sync); the client adds the token and retries once on 401
         response = self._sdk_client.request(
             "POST",
-            self._sdk_client._build_url(self._sdk_client._vlm_base(), VLMEndpoint.CHAT),
+            self._sdk_client._build_url(
+                self._sdk_client._require_vlm_url(), VLMEndpoint.CHAT
+            ),
             json=body,
         )
 
@@ -80,7 +82,7 @@ class VLMResource(VLMMixin):
         response = self._sdk_client.request(
             "GET",
             self._sdk_client._build_url(
-                self._sdk_client._vlm_base(), f"{VLMEndpoint.CHAT}/{result_id}"
+                self._sdk_client._require_vlm_url(), f"{VLMEndpoint.CHAT}/{result_id}"
             ),
         )
 

{visionai_sdk_python-2.2.0.dev2.dist-info → visionai_sdk_python-2.2.0.dev3.dist-info}/METADATA

@@ -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.dev3.dist-info/RECORD

@@ -0,0 +1,30 @@
+visionai_sdk_python/__init__.py,sha256=EITFK0aQPAQN3BSnwTfrPAt1iu50pmuhXl0-jBSbiD4,774
+visionai_sdk_python/_base.py,sha256=q8Ybwk9uEdaAFh85IRCHvsSpXEvYFosFYGhJAeQNIr4,9390
+visionai_sdk_python/_jwt_verifier.py,sha256=h4CAK1iiDAJ-oKnXrLbCJw5rWcsVe94QNY12ne1Wzto,8442
+visionai_sdk_python/_request_attribution.py,sha256=zQk_bSLsu1RTp1Fe3MGUUX8YRzq3iqfBTmhhjM7BuRU,1907
+visionai_sdk_python/_source_header.py,sha256=DWiR-TGclET4UrqmAEO7bYPtf9XuLSE4FGQjZIgVWiY,5133
+visionai_sdk_python/async_client.py,sha256=JHx7Kz3l84PdyHvgGPhpTKprRdSabXxjqazqUVj--rY,5542
+visionai_sdk_python/client.py,sha256=0B3ut9iXsiZxveOIP8SEbTZwv3D0mDZ62D0ycIFOBC8,5352
+visionai_sdk_python/constants.py,sha256=KWhoxZdlwqXwhUJDqERStq2mrms-MA8aRDqBwbIvNO0,1471
+visionai_sdk_python/endpoints.py,sha256=CC-AoxXzg39sMAhqx1CTS3gRWKx_H7VOqBANRLVotoU,183
+visionai_sdk_python/exceptions.py,sha256=BUpcoTgILc3z68lIQGyTYs7PCvu_BTSi228YMTx7ZWs,3020
+visionai_sdk_python/instrumentation.py,sha256=tTTL5Op0fZULpmoOKW8dw8-2ReOQUEpMvHrf-R5C_yg,24512
+visionai_sdk_python/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+visionai_sdk_python/auth/__init__.py,sha256=sWtanqUos5Q8P80IvjoyvOzXv6gYNkflop9qwDwsZk8,400
+visionai_sdk_python/auth/_mixin.py,sha256=EDDhEB9jHc_7wEoLx_MprhToTVLekL5CyJuLTK8GhNM,5022
+visionai_sdk_python/auth/async_resource.py,sha256=V6O51i7KyYSBkiQeKAbmw-EIKMVZIozO1gDexTX6tXw,5535
+visionai_sdk_python/auth/credentials.py,sha256=nsZkavY8pDT39gZxFaKUcl-X_JfKKkc3Nkv9fSFFP4Y,10892
+visionai_sdk_python/auth/models.py,sha256=u6MDFYaWMyf08XCrGZzwPHv43d6AElH9XO2QSjRsb3Q,449
+visionai_sdk_python/auth/resource.py,sha256=3PgcxH8N6unKTs2jSQhMeJT_lg6bTce0hz0bzuID12U,5446
+visionai_sdk_python/relay/__init__.py,sha256=N4DuhutN8P4EWZRFIaWTqvylNsLkzRSkHMRRF2pknFk,1296
+visionai_sdk_python/relay/protocol.py,sha256=Hy7J4kgDxaKy0WOrtkmqD5xUFXgKAVXwTWX4NQ9yQHE,5561
+visionai_sdk_python/vlm/__init__.py,sha256=EDd7ZG4k7inn8qqkyIhO3xI_4MPMWJT5Npsient-tTc,571
+visionai_sdk_python/vlm/_mixin.py,sha256=TkqezNpW8QEe9pujsvx1APcylYQYr_PvHruEz4Le3JQ,1718
+visionai_sdk_python/vlm/async_resource.py,sha256=meMUfBDa0g1hk7vFZq2fDuIQ1-QUpU0BUJtbvuG8UEY,3461
+visionai_sdk_python/vlm/models.py,sha256=yDFjo4LfAxqXYBnl6ZW7YUJQoKKRkQWtqBJi2ruI6Jw,984
+visionai_sdk_python/vlm/preprocess.py,sha256=ZpJJa13h8_YKwh_P7Pn8WIXV0x-r2xJi-ETgCFsGw-Y,7892
+visionai_sdk_python/vlm/resource.py,sha256=4eMQ4ACcgd7nUfdRyADWmPd8yZ--uqQC4zwzBft68lg,3386
+visionai_sdk_python-2.2.0.dev3.dist-info/METADATA,sha256=yaMgyrv9_edbxVHgdaOFTCc2EhV1YFjjZDaxa2D3Lt4,30403
+visionai_sdk_python-2.2.0.dev3.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+visionai_sdk_python-2.2.0.dev3.dist-info/top_level.txt,sha256=79a5MCSLLv6Mbfun-8RS-G6O927hahBwDqJjeuWLdvM,20
+visionai_sdk_python-2.2.0.dev3.dist-info/RECORD,,

visionai_sdk_python-2.2.0.dev2.dist-info/RECORD

@@ -1,28 +0,0 @@
-visionai_sdk_python/__init__.py,sha256=EITFK0aQPAQN3BSnwTfrPAt1iu50pmuhXl0-jBSbiD4,774
-visionai_sdk_python/_base.py,sha256=fnvnes3i5K5CObwIROs3NM6X-PHTLS-IyK6cK9hILeA,10397
-visionai_sdk_python/_jwt_verifier.py,sha256=h4CAK1iiDAJ-oKnXrLbCJw5rWcsVe94QNY12ne1Wzto,8442
-visionai_sdk_python/_request_attribution.py,sha256=zQk_bSLsu1RTp1Fe3MGUUX8YRzq3iqfBTmhhjM7BuRU,1907
-visionai_sdk_python/_source_header.py,sha256=DWiR-TGclET4UrqmAEO7bYPtf9XuLSE4FGQjZIgVWiY,5133
-visionai_sdk_python/async_client.py,sha256=b8hMe9e3eth8B5tOIhP4Wo7ja7JvxO7fe8xQk1lSDjQ,5837
-visionai_sdk_python/client.py,sha256=urkFrMtw7qrkyfzekhF5vsYZt5LlgeJXml-jI8uWSqI,5599
-visionai_sdk_python/constants.py,sha256=KWhoxZdlwqXwhUJDqERStq2mrms-MA8aRDqBwbIvNO0,1471
-visionai_sdk_python/endpoints.py,sha256=CC-AoxXzg39sMAhqx1CTS3gRWKx_H7VOqBANRLVotoU,183
-visionai_sdk_python/exceptions.py,sha256=UExz_lx7do154RyFobcYIaD_hDD-AExvMiOSDkKxe-0,1259
-visionai_sdk_python/instrumentation.py,sha256=tTTL5Op0fZULpmoOKW8dw8-2ReOQUEpMvHrf-R5C_yg,24512
-visionai_sdk_python/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-visionai_sdk_python/auth/__init__.py,sha256=sWtanqUos5Q8P80IvjoyvOzXv6gYNkflop9qwDwsZk8,400
-visionai_sdk_python/auth/_mixin.py,sha256=qxn9wQxOtigcvbFGSmjv7Fu7-HCsIJVs1oqf-wfIN4w,5034
-visionai_sdk_python/auth/async_resource.py,sha256=FnL9c4K7VFsXXMkY2mMPESYMS5fh08WvsqlY9tuvPSI,5341
-visionai_sdk_python/auth/credentials.py,sha256=STuV_ygrvAZbqY6ElE_q612w65zRHAG8oXKBm8X0U1M,8471
-visionai_sdk_python/auth/models.py,sha256=u6MDFYaWMyf08XCrGZzwPHv43d6AElH9XO2QSjRsb3Q,449
-visionai_sdk_python/auth/resource.py,sha256=vFBf_27h2u6R1w3aXm5cDEpvS21RyiwgtDm0olZFpec,5238
-visionai_sdk_python/vlm/__init__.py,sha256=EDd7ZG4k7inn8qqkyIhO3xI_4MPMWJT5Npsient-tTc,571
-visionai_sdk_python/vlm/_mixin.py,sha256=TkqezNpW8QEe9pujsvx1APcylYQYr_PvHruEz4Le3JQ,1718
-visionai_sdk_python/vlm/async_resource.py,sha256=b878VPxVfO4xpjG-JH2XcimqywMFtEw-cyEfeSLVGRo,3417
-visionai_sdk_python/vlm/models.py,sha256=yDFjo4LfAxqXYBnl6ZW7YUJQoKKRkQWtqBJi2ruI6Jw,984
-visionai_sdk_python/vlm/preprocess.py,sha256=ZpJJa13h8_YKwh_P7Pn8WIXV0x-r2xJi-ETgCFsGw-Y,7892
-visionai_sdk_python/vlm/resource.py,sha256=qx03gOxVamtoDrLNadp1J9EtVuP95SntOuilFog_SSo,3342
-visionai_sdk_python-2.2.0.dev2.dist-info/METADATA,sha256=DWZr4KOvRRLb1IXTQtpvwSBxr4ozPzJCAm9xAlTe53Q,29654
-visionai_sdk_python-2.2.0.dev2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-visionai_sdk_python-2.2.0.dev2.dist-info/top_level.txt,sha256=79a5MCSLLv6Mbfun-8RS-G6O927hahBwDqJjeuWLdvM,20
-visionai_sdk_python-2.2.0.dev2.dist-info/RECORD,,