visionai-sdk-python 2.0.0__py3-none-any.whl → 2.1.1__py3-none-any.whl

visionai_sdk_python/_base.py

@@ -38,7 +38,7 @@ class _BaseClient:
             vlm_url: Base URL for the VLM inference service.
             allowed_issuers: Optional list of allowed JWT issuers. If provided, tokens
                 whose ``iss`` claim is not in this list will be rejected. If omitted,
-                issuer validation is skipped.
+                the issuers are derived from ``auth_url``.
             verify_ssl: Whether to verify TLS certificates.
             timeout: Default request timeout in seconds.
             max_connections: Maximum number of concurrent connections in the pool.

visionai_sdk_python/constants.py

@@ -1,49 +1,36 @@
-# Maps known VisionAI server base URLs to their trusted JWT issuers.
-# Keys are normalized (no trailing slash).
-# Values are exact issuer strings as they appear in the JWT `iss` claim.
+# Resolves the trusted JWT issuers for a VisionAI server base URL.
 #
-# Long-term: replace this static table with dynamic discovery from the server's
+# Every deployment hosts its own Keycloak behind the site's public base URL, so
+# the realm issuer is derived from `auth_url` rather than kept in a table. Only
+# sites that additionally accept tokens from an external IdP need an entry here.
+#
+# Long-term: replace this with dynamic discovery from the server's
 # trusted-issuers endpoint (e.g. GET {auth_url}/api/v1/auth/trusted-issuers).
 
 _KEYCLOAK_REALM_PATH = "/keycloak/realms/linker-platform"
 
-# On-premise deployments backed by Keycloak (realm: linker-platform).
-# Issuer = base_url + _KEYCLOAK_REALM_PATH for all entries.
-_KEYCLOAK_BASE_URLS: list[str] = [
-    "https://offline.visionai.linkervision.com",
-    "https://lighthouse.visionai.linkervision.ai",
-    "https://lighthouse-production.visionai.linkervision.ai",
-]
-
-# Cloud deployments backed by Auth0 (one tenant per environment).
-_AUTH0_URL_TO_ISSUERS: dict[str, list[str]] = {
+# Sites whose tokens may still come from an external IdP, in addition to their
+# own Keycloak realm. Production has not cut over yet; listing both issuers lets
+# an installed SDK keep working across the migration without an upgrade.
+#
+# Drop the entry once production is confirmed migrated — a retired Auth0 tenant
+# name can be re-registered by someone else, so it should not stay trusted
+# indefinitely.
+_EXTERNAL_IDP_ISSUERS: dict[str, list[str]] = {
     "https://visionai.linkervision.com": [
         "https://data-engine-prod.us.auth0.com",
     ],
-    "https://staging.visionai.linkervision.com": [
-        "https://data-engine-staging.jp.auth0.com",
-    ],
-    "https://dev2.visionai.linkervision.com": [
-        "https://data-engine-dev2.jp.auth0.com",
-    ],
-    "https://dev.visionai.linkervision.com": [
-        "https://dev-045acunea5v1mm3l.us.auth0.com",
-    ],
-}
-
-_AUTH_URL_TO_ISSUERS: dict[str, list[str]] = {
-    **{url: [f"{url}{_KEYCLOAK_REALM_PATH}"] for url in _KEYCLOAK_BASE_URLS},
-    **_AUTH0_URL_TO_ISSUERS,
 }
 
 
 def resolve_allowed_issuers(auth_url: str) -> list[str]:
     """Return the trusted issuers for the given auth_url.
 
-    If the URL is in the known table, return its configured issuers.
-    Otherwise, assume a Keycloak deployment and derive the issuer from auth_url.
+    Always includes the site's own Keycloak realm issuer, plus any external IdP
+    issuer the site still accepts.
     """
     normalized = auth_url.rstrip("/")
-    if known := _AUTH_URL_TO_ISSUERS.get(normalized):
-        return known
-    return [f"{normalized}{_KEYCLOAK_REALM_PATH}"]
+    return [
+        f"{normalized}{_KEYCLOAK_REALM_PATH}",
+        *_EXTERNAL_IDP_ISSUERS.get(normalized, []),
+    ]

visionai_sdk_python/vlm/__init__.py

@@ -2,12 +2,24 @@
 
 from .async_resource import AsyncVLMResource
 from .models import NIMRequestModel, ResponseErrorModel, ResponseNormalModel
+from .preprocess import (
+    DEFAULT_RESIZE_SPEC,
+    Interpolation,
+    ResizeMode,
+    ResizePlan,
+    compute_resize,
+)
 from .resource import VLMResource
 
 __all__ = [
+    "DEFAULT_RESIZE_SPEC",
     "AsyncVLMResource",
-    "VLMResource",
+    "Interpolation",
     "NIMRequestModel",
-    "ResponseNormalModel",
+    "ResizeMode",
+    "ResizePlan",
     "ResponseErrorModel",
+    "ResponseNormalModel",
+    "VLMResource",
+    "compute_resize",
 ]

visionai_sdk_python/vlm/preprocess.py

@@ -0,0 +1,186 @@
+"""Image-resize planning helpers for VLM inference.
+
+This module only computes target dimensions (pure math, no image
+dependencies). The mode (``name``), ``factor``, and ``interpolation`` come
+from the model server's resize spec; ``pixels`` comes from the UI resize
+option. The actual resize is done by the caller with whatever imaging
+library its pipeline already uses, applying ``plan.interpolation``:
+
+    plan = compute_resize(
+        width=w, height=h, name="smart_resize", factor=32, pixels=768,
+        interpolation="bicubic",
+    )
+
+    # PIL client
+    PIL_INTERPOLATION = {
+        "bicubic": Image.Resampling.BICUBIC,
+        "lanczos": Image.Resampling.LANCZOS,
+    }
+    out = img.resize((plan.width, plan.height), PIL_INTERPOLATION[plan.interpolation])
+
+    # OpenCV client
+    CV2_INTERPOLATION = {
+        "bicubic": cv2.INTER_CUBIC,
+        "lanczos": cv2.INTER_LANCZOS4,
+    }
+    out = cv2.resize(
+        arr, (plan.width, plan.height), interpolation=CV2_INTERPOLATION[plan.interpolation]
+    )
+"""
+
+import math
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import Any, Literal, NamedTuple, get_args
+
+_MAX_ASPECT_RATIO = 200
+
+ResizeMode = Literal["smart_resize", "square_resize"]
+Interpolation = Literal["bicubic", "lanczos"]
+
+# Fallback resize spec for when the model server does not provide one.
+# Read-only; splat it into compute_resize alongside the UI pixels value:
+#     compute_resize(width=w, height=h, pixels=768, **DEFAULT_RESIZE_SPEC)
+DEFAULT_RESIZE_SPEC: Mapping[str, Any] = MappingProxyType(
+    {"name": "smart_resize", "factor": 32, "interpolation": "bicubic"}
+)
+
+
+class ResizePlan(NamedTuple):
+    """Target dimensions and interpolation method for a client-side resize."""
+
+    width: int
+    height: int
+    interpolation: Interpolation
+
+
+def _smart_resize(
+    height: int,
+    width: int,
+    factor: int,
+    min_pixels: int,
+    max_pixels: int,
+) -> tuple[int, int]:
+    """Compute target (height, width) — note height-first, unlike ResizePlan.
+
+    1. Both dimensions are divisible by ``factor``.
+    2. The total number of pixels is within [``min_pixels``, ``max_pixels``].
+    3. The aspect ratio is maintained as closely as possible.
+
+    Raises ValueError when the aspect ratio exceeds 200 or the constraints
+    cannot all be satisfied. Argument validation is compute_resize's job.
+    """
+    if max(height, width) / min(height, width) > _MAX_ASPECT_RATIO:
+        raise ValueError(
+            "absolute aspect ratio must be smaller than "
+            f"{_MAX_ASPECT_RATIO}, got {max(height, width) / min(height, width)}"
+        )
+    h_bar = max(factor, round(height / factor) * factor)
+    w_bar = max(factor, round(width / factor) * factor)
+    if h_bar * w_bar > max_pixels:
+        beta = math.sqrt((height * width) / max_pixels)
+        h_bar = max(factor, math.floor(height / beta / factor) * factor)
+        w_bar = max(factor, math.floor(width / beta / factor) * factor)
+    elif h_bar * w_bar < min_pixels:
+        beta = math.sqrt(min_pixels / (height * width))
+        h_bar = math.ceil(height * beta / factor) * factor
+        w_bar = math.ceil(width * beta / factor) * factor
+    if not min_pixels <= h_bar * w_bar <= max_pixels:
+        raise ValueError(
+            f"cannot satisfy min_pixels={min_pixels}, max_pixels={max_pixels} for a "
+            f"{width}x{height} image with factor={factor}"
+        )
+    return h_bar, w_bar
+
+
+def compute_resize(
+    *,
+    width: int,
+    height: int,
+    name: ResizeMode,
+    pixels: int,
+    interpolation: Interpolation,
+    factor: int | None = None,
+    min_pixels: int | None = None,
+) -> ResizePlan:
+    """Plan a VLM-input resize from the model server's resize spec.
+
+    All arguments are keyword-only — a transposed width/height cannot happen
+    silently. ``name``, ``factor``, and ``interpolation`` mirror the model
+    server's resize spec fields; ``pixels`` is the UI resize option value.
+
+    - ``name="smart_resize"`` — dimensions divisible by ``factor``, total
+      pixel count within [``min_pixels``, ``pixels * pixels``], aspect ratio
+      kept. ``factor`` is required (the model's patch size, e.g. 32 or 48);
+      ``min_pixels`` defaults to ``4 * factor * factor``.
+    - ``name="square_resize"`` — exact ``pixels`` x ``pixels``; aspect ratio
+      not preserved. ``factor`` has no meaning and is ignored, so a whole
+      server resize spec can be forwarded as-is.
+
+    Args:
+        width: Source image width in pixels.
+        height: Source image height in pixels.
+        name: Resize mode from the model server: "smart_resize" or
+            "square_resize".
+        pixels: UI pixel option — one number, but its meaning depends on
+            ``name``:
+
+            - ``"smart_resize"``: an area budget, not a side length. The
+              output area is capped at ``pixels * pixels`` while keeping the
+              source aspect ratio, so neither output side is generally equal
+              to ``pixels`` — e.g. ``pixels=768`` on a 1920x1080 frame gives
+              1024x576 (= 589,824 px, the same area as 768x768).
+            - ``"square_resize"``: the exact side length. The output is
+              always ``pixels`` x ``pixels`` — e.g. ``pixels=384`` gives
+              384x384 regardless of the source shape.
+        interpolation: Interpolation the caller should resize with,
+            from the model server: "bicubic" or "lanczos". Passed through
+            into the returned plan.
+        factor: Smart resize only: round dimensions to multiples of this.
+        min_pixels: Smart resize only: lower bound on output pixel count.
+
+    Returns:
+        ResizePlan(width, height, interpolation) — note width-first,
+        matching the (width, height) order PIL and OpenCV resize calls expect.
+
+    Raises:
+        ValueError: If height/width are not positive, ``pixels`` or ``factor``
+            is not a positive integer, ``name`` or ``interpolation`` is not a
+            supported value, ``factor`` is missing (smart), ``min_pixels`` is
+            given for square resize or exceeds the pixel budget, or the
+            constraints cannot be satisfied (extreme aspect ratio).
+    """
+    if height <= 0 or width <= 0:
+        raise ValueError(f"height and width must be positive, got {width}x{height}")
+    if name not in get_args(ResizeMode):
+        raise ValueError(f"name must be one of {get_args(ResizeMode)}, got {name!r}")
+    if interpolation not in get_args(Interpolation):
+        raise ValueError(
+            f"interpolation must be one of {get_args(Interpolation)}, "
+            f"got {interpolation!r}"
+        )
+    if isinstance(pixels, bool) or not isinstance(pixels, int) or pixels <= 0:
+        raise ValueError(f"pixels must be a positive integer, got {pixels!r}")
+
+    if name == "smart_resize":
+        if factor is None:
+            raise ValueError("smart_resize requires factor")
+        if isinstance(factor, bool) or not isinstance(factor, int) or factor <= 0:
+            raise ValueError(f"factor must be a positive integer, got {factor!r}")
+        max_pixels = pixels * pixels
+        if min_pixels is None:
+            min_pixels = 4 * factor * factor
+        if min_pixels <= 0 or min_pixels > max_pixels:
+            raise ValueError(
+                f"min_pixels must be in (0, pixels * pixels], got "
+                f"min_pixels={min_pixels}, pixels={pixels}"
+            )
+        h_bar, w_bar = _smart_resize(height, width, factor, min_pixels, max_pixels)
+    else:
+        # factor is part of the server resize spec, so a caller forwarding the
+        # whole spec may pass it; it has no meaning here, so ignore it.
+        if min_pixels is not None:
+            raise ValueError("min_pixels only applies to smart_resize")
+        w_bar = h_bar = pixels
+
+    return ResizePlan(width=w_bar, height=h_bar, interpolation=interpolation)

{visionai_sdk_python-2.0.0.dist-info → visionai_sdk_python-2.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: visionai-sdk-python
-Version: 2.0.0
+Version: 2.1.1
 Summary: VisionAI SDK for Python
 Author-email: Tony Yang <tonyyang@linkervision.com>
 Requires-Python: >=3.11
@@ -27,6 +27,7 @@ Python client library for VisionAI authentication and Vision Language Model (VLM
 - **Auto Token Management**: Automatic token refresh before expiration
 - **JWT Validation**: Built-in token signature and expiration verification
 - **VLM Inference**: Submit and poll vision-language model tasks
+- **Resize Planning**: Compute VLM input dimensions (smart / square resize) without any image dependency — the caller does the actual resize
 - **Async Support**: Full async/await support with `AsyncClient`
 - **Type Safe**: Full type hints with Pydantic validation
 - **Service Source Attribution**: Auto-attach a service-source header to every outbound `requests`/`httpx`/`aiohttp` call with a single startup call
@@ -187,6 +188,43 @@ elif result.status in ("failed", "timeout"):
 - `failed`: Error, check `error`
 - `timeout`: Request timeout
 
+### Resize Planning
+
+Compute the target dimensions for a VLM input image. Pure math, no image
+dependencies — resize with whatever library your service already uses,
+applying `plan.interpolation`. `name`, `factor`, and `interpolation` come
+from the model server's resize spec; `pixels` is the UI resize option:
+
+```python
+from visionai_sdk_python.vlm import compute_resize
+
+plan = compute_resize(
+    width=1920, height=1080, name="smart_resize", factor=32, pixels=768,
+    interpolation="bicubic",
+)
+# ResizePlan(width=1024, height=576, interpolation='bicubic')
+# smart_resize: dimensions divisible by factor, area capped at pixels * pixels
+
+compute_resize(width=w, height=h, name="square_resize", pixels=384, interpolation="lanczos")
+# square_resize: exact pixels x pixels; factor is ignored, so a whole resize
+# spec can be forwarded as-is
+
+# No resize spec from the model server? Fall back to the default
+# (smart_resize, factor 32, bicubic):
+from visionai_sdk_python.vlm import DEFAULT_RESIZE_SPEC
+plan = compute_resize(width=w, height=h, pixels=768, **DEFAULT_RESIZE_SPEC)
+
+# Apply with your own imaging library (PIL shown; see module docstring for cv2)
+interpolation = {"bicubic": Image.Resampling.BICUBIC,
+                 "lanczos": Image.Resampling.LANCZOS}[plan.interpolation]
+img = img.resize((plan.width, plan.height), interpolation)
+```
+
+Invalid input (non-positive dimensions, a non-integer or non-positive
+`pixels`/`factor`, unknown `name` or `interpolation`, missing `factor` for
+smart resize, `min_pixels` on a square resize or over the pixel budget, an
+unsatisfiable budget) raises `ValueError`.
+
 ## Token Validation
 
 ```python
@@ -212,6 +250,25 @@ client = Client(
 )
 ```
 
+### Token issuers
+
+`allowed_issuers` is optional. When you leave it out, the SDK derives the
+trusted issuers from `auth_url` and accepts a token whose `iss` claim either:
+
+- equals `{auth_url}/keycloak/realms/linker-platform`, the realm every
+  deployment hosts behind its own base URL; or
+- equals an external issuer the site is known to still accept — today only
+  production, which takes its Auth0 tenant alongside Keycloak while it migrates.
+
+That means `auth_url` has to be the site's **public base URL** — the same host
+that appears in the token's `iss` claim. Pointing it at an in-cluster or proxied
+address (for example a backend service URL) derives issuers that no token will
+ever carry, and verification fails with `jwt.InvalidIssuerError`. Pass
+`allowed_issuers` explicitly if you need to talk to a site through such an
+address.
+
+Passing `allowed_issuers` yourself replaces both rules with an exact-match list.
+
 ## Error Handling
 
 ```python

{visionai_sdk_python-2.0.0.dist-info → visionai_sdk_python-2.1.1.dist-info}/RECORD

@@ -1,11 +1,11 @@
 visionai_sdk_python/__init__.py,sha256=y2RFANz0iHxxrATkwIv9cDRkuICybgfMpTbjVX79lRw,569
-visionai_sdk_python/_base.py,sha256=6MoFyrOr4I3TkoXkBuZIlnih0xHB4QNuOWGug0vh2Ho,8117
+visionai_sdk_python/_base.py,sha256=VC4EGUqUzTkrN63ByKL_kPOckXjRfFNXWVXByGZhVfM,8130
 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=u133WD2wqaUSNz-Rq3DgHDBQuPmArHgJtoiIpke5O-M,3876
 visionai_sdk_python/client.py,sha256=7hvlq0evaPLolm1hDXS44EaaZR7OUIkEpOrUCbGaz2Y,3736
-visionai_sdk_python/constants.py,sha256=hDLdISOkrrEifLumVy0gPLO2NmUDxdfe2UIueizpbh8,1868
+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=r4bxvsQGNTVa7-ISX1JAC7VRJ-6qs3n30l3j3qxai-Y,1047
 visionai_sdk_python/instrumentation.py,sha256=tTTL5Op0fZULpmoOKW8dw8-2ReOQUEpMvHrf-R5C_yg,24512
@@ -15,12 +15,13 @@ visionai_sdk_python/auth/_mixin.py,sha256=qxn9wQxOtigcvbFGSmjv7Fu7-HCsIJVs1oqf-w
 visionai_sdk_python/auth/async_resource.py,sha256=Yz9l0MtoihNREZwx0rkImCGn_sRkx2WdPkRCZ1YKi38,4457
 visionai_sdk_python/auth/models.py,sha256=Ke0eWJwU4d1M4W5WS9EbWTQRrvnYyxccrMg3XbgbDdA,435
 visionai_sdk_python/auth/resource.py,sha256=F4d1cZ88GZrXUrgHD_sduSEJzZiO9ZPVX7m1wTeaSp0,4368
-visionai_sdk_python/vlm/__init__.py,sha256=f0G0zigVm5mn05fWvmvV6fR7UIbil2aSXhHRYwpgIVs,341
+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=pOuHpzsbw6NawGQHROcLzs_ezKg78DI1RZHA5W1ko_s,3695
 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=VaNybrunD_8eNDbAAJwaxkUrbR4amGATM4CGvQsX7Qk,3608
-visionai_sdk_python-2.0.0.dist-info/METADATA,sha256=jBJEmXCRk132qsKCSg0HmY9pFU8A2tgiflJZuNiE7fU,25936
-visionai_sdk_python-2.0.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-visionai_sdk_python-2.0.0.dist-info/top_level.txt,sha256=79a5MCSLLv6Mbfun-8RS-G6O927hahBwDqJjeuWLdvM,20
-visionai_sdk_python-2.0.0.dist-info/RECORD,,
+visionai_sdk_python-2.1.1.dist-info/METADATA,sha256=Y2oQtkae1coZFW8Ltl9NVikIKIImK01nJPh6R5bRvdc,28624
+visionai_sdk_python-2.1.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+visionai_sdk_python-2.1.1.dist-info/top_level.txt,sha256=79a5MCSLLv6Mbfun-8RS-G6O927hahBwDqJjeuWLdvM,20
+visionai_sdk_python-2.1.1.dist-info/RECORD,,

{visionai_sdk_python-2.0.0.dist-info → visionai_sdk_python-2.1.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (83.0.0)
+Generator: setuptools (84.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any