visionai-sdk-python 2.0.0__tar.gz → 2.1.1__tar.gz

{visionai_sdk_python-2.0.0 → visionai_sdk_python-2.1.1}/PKG-INFO

@@ -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 → visionai_sdk_python-2.1.1}/README.md

@@ -9,6 +9,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
@@ -169,6 +170,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
@@ -194,6 +232,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 → visionai_sdk_python-2.1.1}/src/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-2.1.1/src/visionai_sdk_python/constants.py

@@ -0,0 +1,36 @@
+# Resolves the trusted JWT issuers for a VisionAI server base URL.
+#
+# 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"
+
+# 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",
+    ],
+}
+
+
+def resolve_allowed_issuers(auth_url: str) -> list[str]:
+    """Return the trusted issuers for the given auth_url.
+
+    Always includes the site's own Keycloak realm issuer, plus any external IdP
+    issuer the site still accepts.
+    """
+    normalized = auth_url.rstrip("/")
+    return [
+        f"{normalized}{_KEYCLOAK_REALM_PATH}",
+        *_EXTERNAL_IDP_ISSUERS.get(normalized, []),
+    ]

{visionai_sdk_python-2.0.0 → visionai_sdk_python-2.1.1}/src/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-2.1.1/src/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 → visionai_sdk_python-2.1.1}/src/visionai_sdk_python.egg-info/PKG-INFO

@@ -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 → visionai_sdk_python-2.1.1}/src/visionai_sdk_python.egg-info/SOURCES.txt

@@ -33,10 +33,12 @@ src/visionai_sdk_python/vlm/__init__.py
 src/visionai_sdk_python/vlm/_mixin.py
 src/visionai_sdk_python/vlm/async_resource.py
 src/visionai_sdk_python/vlm/models.py
+src/visionai_sdk_python/vlm/preprocess.py
 src/visionai_sdk_python/vlm/resource.py
 tests/__init__.py
 tests/constants.py
 tests/test__base.py
 tests/test_async_client.py
 tests/test_client.py
-tests/test_instrumentation.py
+tests/test_instrumentation.py
+tests/test_vlm_preprocess.py

{visionai_sdk_python-2.0.0 → visionai_sdk_python-2.1.1}/src/visionai_sdk_python.egg-info/scm_file_list.json

@@ -1,39 +1,41 @@
 {
   "files": [
-    "pyproject.toml",
-    "README.md",
-    "uv.lock",
-    ".gitignore",
     ".github/dependabot.yml",
     ".github/workflows/ci.yml",
     ".github/workflows/publish.yml",
-    "tests/test_async_client.py",
-    "tests/test_instrumentation.py",
-    "tests/__init__.py",
-    "tests/test_client.py",
-    "tests/test__base.py",
-    "tests/constants.py",
-    "src/visionai_sdk_python/_base.py",
-    "src/visionai_sdk_python/async_client.py",
-    "src/visionai_sdk_python/endpoints.py",
-    "src/visionai_sdk_python/_source_header.py",
-    "src/visionai_sdk_python/_request_attribution.py",
-    "src/visionai_sdk_python/py.typed",
+    ".gitignore",
+    "README.md",
+    "pyproject.toml",
     "src/visionai_sdk_python/__init__.py",
+    "src/visionai_sdk_python/_base.py",
     "src/visionai_sdk_python/_jwt_verifier.py",
-    "src/visionai_sdk_python/client.py",
-    "src/visionai_sdk_python/exceptions.py",
-    "src/visionai_sdk_python/instrumentation.py",
-    "src/visionai_sdk_python/constants.py",
+    "src/visionai_sdk_python/_request_attribution.py",
+    "src/visionai_sdk_python/_source_header.py",
+    "src/visionai_sdk_python/async_client.py",
     "src/visionai_sdk_python/auth/__init__.py",
+    "src/visionai_sdk_python/auth/_mixin.py",
     "src/visionai_sdk_python/auth/async_resource.py",
-    "src/visionai_sdk_python/auth/resource.py",
     "src/visionai_sdk_python/auth/models.py",
-    "src/visionai_sdk_python/auth/_mixin.py",
+    "src/visionai_sdk_python/auth/resource.py",
+    "src/visionai_sdk_python/client.py",
+    "src/visionai_sdk_python/constants.py",
+    "src/visionai_sdk_python/endpoints.py",
+    "src/visionai_sdk_python/exceptions.py",
+    "src/visionai_sdk_python/instrumentation.py",
+    "src/visionai_sdk_python/py.typed",
     "src/visionai_sdk_python/vlm/__init__.py",
+    "src/visionai_sdk_python/vlm/_mixin.py",
     "src/visionai_sdk_python/vlm/async_resource.py",
-    "src/visionai_sdk_python/vlm/resource.py",
     "src/visionai_sdk_python/vlm/models.py",
-    "src/visionai_sdk_python/vlm/_mixin.py"
+    "src/visionai_sdk_python/vlm/preprocess.py",
+    "src/visionai_sdk_python/vlm/resource.py",
+    "tests/__init__.py",
+    "tests/constants.py",
+    "tests/test__base.py",
+    "tests/test_async_client.py",
+    "tests/test_client.py",
+    "tests/test_instrumentation.py",
+    "tests/test_vlm_preprocess.py",
+    "uv.lock"
   ]
 }

visionai_sdk_python-2.1.1/src/visionai_sdk_python.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "2.1.1",
+  "distance": 0,
+  "node": "gfb3ad463150fa3d6530e8390fee3865b9398d8c0",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-09-16"
+}

visionai_sdk_python-2.1.1/tests/test__base.py

@@ -0,0 +1,198 @@
+import jwt
+import pytest
+
+from visionai_sdk_python._base import _BaseClient
+from visionai_sdk_python.constants import resolve_allowed_issuers
+
+
+def test_init_stores_attributes() -> None:
+    client = _BaseClient(
+        auth_url="https://auth.example.com", vlm_url="https://vlm.example.com"
+    )
+    assert client.auth_url == "https://auth.example.com"
+    assert client.vlm_url == "https://vlm.example.com"
+    assert client.verify_ssl is True
+    assert client.timeout == 10.0
+    assert client.max_connections == 100
+    assert client.max_keepalive_connections == 20
+
+
+@pytest.mark.parametrize(
+    "base_url, path, expected",
+    [
+        # Standard case
+        ("https://auth.example.com", "token", "https://auth.example.com/token"),
+        # Trailing slash on base
+        ("https://auth.example.com/", "token", "https://auth.example.com/token"),
+        # Leading slash on path
+        ("https://auth.example.com", "/token", "https://auth.example.com/token"),
+        # Both have slashes — should not double-slash
+        ("https://auth.example.com/", "/token", "https://auth.example.com/token"),
+        # Nested path
+        ("https://vlm.example.com", "v1/infer", "https://vlm.example.com/v1/infer"),
+        # Empty path — should not raise, returns base with trailing slash
+        ("https://auth.example.com", "", "https://auth.example.com/"),
+    ],
+)
+def test_slash_normalization(base_url: str, path: str, expected: str) -> None:
+    assert _BaseClient._build_url(base_url, path) == expected
+
+
+def test_auth_header() -> None:
+    headers = _BaseClient._build_auth_header(access_token="my-token")
+    assert headers["Authorization"] == "Bearer my-token"
+
+
+@pytest.mark.parametrize("empty_url", ["", "  "])
+def test_init_raises_on_empty_auth_url(empty_url: str) -> None:
+    with pytest.raises(ValueError, match="auth_url"):
+        _BaseClient(auth_url=empty_url, vlm_url="https://vlm.example.com")
+
+
+@pytest.mark.parametrize("empty_url", ["", "  "])
+def test_init_raises_on_empty_vlm_url(empty_url: str) -> None:
+    with pytest.raises(ValueError, match="vlm_url"):
+        _BaseClient(auth_url="https://auth.example.com", vlm_url=empty_url)
+
+
+def test_auth_header_raises_on_empty_token() -> None:
+    with pytest.raises(ValueError, match="access_token"):
+        _BaseClient._build_auth_header(access_token="")
+
+
+_KEYCLOAK_SITES = [
+    "https://staging.visionai.linkervision.com",
+    "https://dev.visionai.linkervision.com",
+    "https://dev2.visionai.linkervision.com",
+    "https://dev3.visionai.linkervision.com",
+    "https://offline.visionai.linkervision.com",
+    "https://lighthouse.visionai.linkervision.ai",
+    "https://lighthouse-production.visionai.linkervision.ai",
+]
+
+
+@pytest.mark.parametrize("auth_url", _KEYCLOAK_SITES)
+def test_resolve_allowed_issuers_for_keycloak_sites(auth_url: str) -> None:
+    """Every site that has cut over to Keycloak resolves to its realm issuer."""
+    assert resolve_allowed_issuers(auth_url) == [
+        f"{auth_url}/keycloak/realms/linker-platform"
+    ]
+
+
+def test_resolve_allowed_issuers_for_production() -> None:
+    """Production accepts its Auth0 tenant and its Keycloak realm during the cutover."""
+    assert resolve_allowed_issuers("https://visionai.linkervision.com") == [
+        "https://visionai.linkervision.com/keycloak/realms/linker-platform",
+        "https://data-engine-prod.us.auth0.com",
+    ]
+
+
+def test_resolve_allowed_issuers_falls_back_to_keycloak() -> None:
+    """An unknown host is assumed to be a Keycloak deployment."""
+    assert resolve_allowed_issuers("https://somewhere.example.com") == [
+        "https://somewhere.example.com/keycloak/realms/linker-platform"
+    ]
+
+
+@pytest.mark.parametrize(
+    "auth_url",
+    [
+        "https://dev.visionai.linkervision.com/",
+        "https://dev.visionai.linkervision.com///",
+    ],
+)
+def test_resolve_allowed_issuers_ignores_trailing_slashes(auth_url: str) -> None:
+    assert resolve_allowed_issuers(auth_url) == [
+        "https://dev.visionai.linkervision.com/keycloak/realms/linker-platform"
+    ]
+
+
+def test_client_defaults_to_resolved_issuers() -> None:
+    """Omitting allowed_issuers pins the client to the site's own issuer."""
+    client = _BaseClient(
+        auth_url="https://dev.visionai.linkervision.com",
+        vlm_url="https://vlm.example.com",
+    )
+    client._jwt_verifier._validate_issuer(
+        "https://dev.visionai.linkervision.com/keycloak/realms/linker-platform"
+    )
+    with pytest.raises(jwt.InvalidIssuerError):
+        client._jwt_verifier._validate_issuer("https://data-engine-dev2.jp.auth0.com")
+
+
+def test_production_accepts_both_issuers_across_the_migration() -> None:
+    """Production keeps working whether the token comes from Auth0 or Keycloak."""
+    client = _BaseClient(
+        auth_url="https://visionai.linkervision.com",
+        vlm_url="https://vlm.example.com",
+    )
+    client._jwt_verifier._validate_issuer("https://data-engine-prod.us.auth0.com")
+    client._jwt_verifier._validate_issuer(
+        "https://visionai.linkervision.com/keycloak/realms/linker-platform"
+    )
+
+
+@pytest.mark.parametrize(
+    "issuer",
+    [
+        # Same realm path, different host.
+        "https://evil.example.com/keycloak/realms/linker-platform",
+        # Site host as a substring of an attacker-controlled one.
+        "https://dev.visionai.linkervision.com.evil.example.com/keycloak/realms/x",
+        # Right host, wrong scheme.
+        "http://dev.visionai.linkervision.com/keycloak/realms/linker-platform",
+        # Right host, different realm.
+        "https://dev.visionai.linkervision.com/keycloak/realms/another-realm",
+    ],
+)
+def test_default_issuers_reject_lookalikes(issuer: str) -> None:
+    """The derived issuer is matched exactly — near misses are not accepted."""
+    client = _BaseClient(
+        auth_url="https://dev.visionai.linkervision.com",
+        vlm_url="https://vlm.example.com",
+    )
+    with pytest.raises(jwt.InvalidIssuerError):
+        client._jwt_verifier._validate_issuer(issuer)
+
+
+_ALLOWED_ISSUERS = [
+    "https://offline.visionai.linkervision.com/keycloak/realms/linker-platform",
+    "https://data-engine-prod.us.auth0.com",
+]
+
+
+@pytest.mark.parametrize("issuer", _ALLOWED_ISSUERS)
+def test_validate_issuer_passes_for_allowed(issuer: str) -> None:
+    client = _BaseClient(
+        auth_url="https://auth.example.com",
+        vlm_url="https://vlm.example.com",
+        allowed_issuers=_ALLOWED_ISSUERS,
+    )
+    client._jwt_verifier._validate_issuer(issuer)  # should not raise
+
+
+@pytest.mark.parametrize(
+    "issuer",
+    [
+        "https://evil.com/keycloak/realms/linker-platform",
+        "https://attacker.auth0.com/",
+        "https://offline.visionai.linkervision.com/keycloak/realms/other-realm",
+    ],
+)
+def test_validate_issuer_raises_for_unknown(issuer: str) -> None:
+    client = _BaseClient(
+        auth_url="https://auth.example.com",
+        vlm_url="https://vlm.example.com",
+        allowed_issuers=_ALLOWED_ISSUERS,
+    )
+    with pytest.raises(jwt.InvalidIssuerError):
+        client._jwt_verifier._validate_issuer(issuer)
+
+
+def test_validate_issuer_raises_for_unknown_when_no_allowed_issuers() -> None:
+    client = _BaseClient(
+        auth_url="https://auth.example.com",
+        vlm_url="https://vlm.example.com",
+    )
+    with pytest.raises(jwt.InvalidIssuerError):
+        client._jwt_verifier._validate_issuer("https://anyone.com/")  # should not raise

visionai_sdk_python-2.1.1/tests/test_vlm_preprocess.py

@@ -0,0 +1,213 @@
+"""Tests for VLM image-resize planning helpers."""
+
+import pytest
+
+from visionai_sdk_python.vlm import compute_resize
+
+
+def smart(width, height, **overrides):
+    kwargs = {
+        "width": width,
+        "height": height,
+        "name": "smart_resize",
+        "factor": 32,
+        "pixels": 768,
+        "interpolation": "bicubic",
+    }
+    kwargs.update(overrides)
+    return compute_resize(**kwargs)
+
+
+@pytest.mark.parametrize("factor", [32, 48])
+@pytest.mark.parametrize(
+    "width,height",
+    [
+        (1920, 1080),  # downscale (over the pixel budget)
+        (32, 32),  # tiny, upscale to min_pixels
+        (375, 500),  # within bounds, snap to factor
+        (4000, 3000),  # large downscale
+    ],
+)
+def test_smart_constraints(width, height, factor):
+    plan = smart(width, height, factor=factor)
+    assert plan.width % factor == 0
+    assert plan.height % factor == 0
+    assert 4 * factor * factor <= plan.width * plan.height <= 768 * 768
+
+
+@pytest.mark.parametrize(
+    "width,height,expected",
+    [
+        (1920, 1080, (1024, 576)),  # README example
+        (1280, 8, (1280, 32)),  # thin strip: short side snaps up, long side kept
+        (1000, 17, (992, 32)),  # ...and does not jump at the factor/2 boundary
+        (1000, 16, (992, 32)),
+        (224, 2, (224, 32)),  # already inside the budget — no upscale
+    ],
+)
+def test_smart_golden_dimensions(width, height, expected):
+    # Pins parity with the model server's smart_resize; the constraint-only
+    # tests above pass for wrong-but-legal plans.
+    plan = smart(width, height)
+    assert (plan.width, plan.height) == expected
+
+
+def test_smart_keeps_aspect_ratio():
+    plan = smart(1920, 1080)
+    assert plan.width / plan.height == pytest.approx(1920 / 1080, rel=0.1)
+
+
+def test_smart_orientation_not_transposed():
+    # Landscape in, landscape out — catches any width/height swap regression.
+    plan = smart(1920, 1080)
+    assert plan.width > plan.height
+
+
+def test_smart_rejects_extreme_aspect_ratio():
+    with pytest.raises(ValueError, match="aspect ratio"):
+        smart(2010, 10)
+
+
+def test_smart_rejects_unsatisfiable_max_pixels():
+    # Elongated strip: aspect ratio passes the <=200 check, but the factor
+    # floor cannot fit the pixel budget. Must raise, not silently overshoot.
+    with pytest.raises(ValueError, match="cannot satisfy"):
+        smart(40000, 200, factor=48, pixels=384)
+
+
+def test_smart_rejects_unsatisfiable_min_pixels():
+    # Tight budget + extreme shape floors below min_pixels.
+    with pytest.raises(ValueError, match="cannot satisfy"):
+        smart(20000, 10000, pixels=64)
+
+
+def test_smart_min_pixels_defaults_to_four_patches():
+    plan = smart(32, 32)
+    assert plan.width * plan.height >= 4 * 32 * 32
+    assert plan == smart(32, 32, min_pixels=4 * 32 * 32)
+
+
+def test_smart_requires_factor():
+    with pytest.raises(ValueError, match="requires factor"):
+        compute_resize(
+            width=1920,
+            height=1080,
+            name="smart_resize",
+            pixels=768,
+            interpolation="bicubic",
+        )
+
+
+def test_smart_rejects_min_pixels_over_budget():
+    with pytest.raises(ValueError, match="min_pixels"):
+        smart(1920, 1080, min_pixels=100000, pixels=64)
+    # Implicit default min_pixels (4 * 48 * 48 = 9216) exceeds 64 * 64.
+    with pytest.raises(ValueError, match="min_pixels"):
+        smart(1920, 1080, factor=48, pixels=64)
+
+
+@pytest.mark.parametrize(
+    "kwargs",
+    [{"factor": 0}, {"factor": -32}, {"factor": 32.5}, {"min_pixels": 0}],
+)
+def test_smart_rejects_bad_params(kwargs):
+    with pytest.raises(ValueError):
+        smart(1920, 1080, **kwargs)
+
+
+def test_square():
+    plan = compute_resize(
+        width=1920,
+        height=1080,
+        name="square_resize",
+        pixels=384,
+        interpolation="lanczos",
+    )
+    assert (plan.width, plan.height) == (384, 384)
+    assert plan.interpolation == "lanczos"
+
+
+def test_square_ignores_factor():
+    # factor comes from the server resize spec, so forwarding the whole spec
+    # must not blow up on a square model.
+    plan = compute_resize(
+        width=1920,
+        height=1080,
+        name="square_resize",
+        pixels=384,
+        factor=32,
+        interpolation="bicubic",
+    )
+    assert (plan.width, plan.height) == (384, 384)
+
+
+def test_square_rejects_min_pixels():
+    with pytest.raises(ValueError, match="only applies to smart_resize"):
+        compute_resize(
+            width=1920,
+            height=1080,
+            name="square_resize",
+            pixels=384,
+            min_pixels=100,
+            interpolation="bicubic",
+        )
+
+
+def test_positional_arguments_rejected():
+    with pytest.raises(TypeError):
+        compute_resize(
+            1920, 1080, name="square_resize", pixels=384, interpolation="lanczos"
+        )  # type: ignore[misc]
+
+
+@pytest.mark.parametrize("width,height", [(0, 1080), (1920, 0), (0, 0), (-1, 100)])
+def test_rejects_non_positive_dimensions(width, height):
+    with pytest.raises(ValueError, match="height and width"):
+        smart(width, height)
+
+
+@pytest.mark.parametrize("pixels", [0, -384, 384.0, True, "384"])
+def test_rejects_bad_pixels(pixels):
+    # 384.0 is what a JSON-decoded UI option looks like; no imaging library
+    # accepts float dimensions, so reject at the boundary, not downstream.
+    with pytest.raises(ValueError, match="pixels must be a positive integer"):
+        compute_resize(
+            width=1920,
+            height=1080,
+            name="square_resize",
+            pixels=pixels,
+            interpolation="bicubic",
+        )
+
+
+def test_rejects_unknown_name():
+    with pytest.raises(ValueError, match="name must be one of"):
+        compute_resize(
+            width=1920,
+            height=1080,
+            name="longest_edge",
+            pixels=768,
+            interpolation="bicubic",
+        )
+
+
+def test_rejects_unknown_interpolation():
+    # bilinear is no longer a supported value.
+    with pytest.raises(ValueError, match="interpolation must be one of"):
+        smart(1920, 1080, interpolation="bilinear")
+
+
+def test_default_resize_spec():
+    from visionai_sdk_python.vlm import DEFAULT_RESIZE_SPEC
+
+    plan = compute_resize(width=1920, height=1080, pixels=768, **DEFAULT_RESIZE_SPEC)
+    assert plan == compute_resize(
+        width=1920,
+        height=1080,
+        pixels=768,
+        name="smart_resize",
+        factor=32,
+        interpolation="bicubic",
+    )
+    with pytest.raises(TypeError):
+        DEFAULT_RESIZE_SPEC["factor"] = 48  # type: ignore[index]

visionai_sdk_python-2.0.0/src/visionai_sdk_python/constants.py

@@ -1,49 +0,0 @@
-# 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.
-#
-# Long-term: replace this static table 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]] = {
-    "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.
-    """
-    normalized = auth_url.rstrip("/")
-    if known := _AUTH_URL_TO_ISSUERS.get(normalized):
-        return known
-    return [f"{normalized}{_KEYCLOAK_REALM_PATH}"]

visionai_sdk_python-2.0.0/src/visionai_sdk_python.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "2.0.0",
-  "distance": 0,
-  "node": "ge6183ee40ad92d5fc80df4dd82c92fa4843d782a",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-08-07"
-}

visionai_sdk_python-2.0.0/tests/test__base.py

@@ -1,102 +0,0 @@
-import jwt
-import pytest
-
-from visionai_sdk_python._base import _BaseClient
-
-
-def test_init_stores_attributes() -> None:
-    client = _BaseClient(
-        auth_url="https://auth.example.com", vlm_url="https://vlm.example.com"
-    )
-    assert client.auth_url == "https://auth.example.com"
-    assert client.vlm_url == "https://vlm.example.com"
-    assert client.verify_ssl is True
-    assert client.timeout == 10.0
-    assert client.max_connections == 100
-    assert client.max_keepalive_connections == 20
-
-
-@pytest.mark.parametrize(
-    "base_url, path, expected",
-    [
-        # Standard case
-        ("https://auth.example.com", "token", "https://auth.example.com/token"),
-        # Trailing slash on base
-        ("https://auth.example.com/", "token", "https://auth.example.com/token"),
-        # Leading slash on path
-        ("https://auth.example.com", "/token", "https://auth.example.com/token"),
-        # Both have slashes — should not double-slash
-        ("https://auth.example.com/", "/token", "https://auth.example.com/token"),
-        # Nested path
-        ("https://vlm.example.com", "v1/infer", "https://vlm.example.com/v1/infer"),
-        # Empty path — should not raise, returns base with trailing slash
-        ("https://auth.example.com", "", "https://auth.example.com/"),
-    ],
-)
-def test_slash_normalization(base_url: str, path: str, expected: str) -> None:
-    assert _BaseClient._build_url(base_url, path) == expected
-
-
-def test_auth_header() -> None:
-    headers = _BaseClient._build_auth_header(access_token="my-token")
-    assert headers["Authorization"] == "Bearer my-token"
-
-
-@pytest.mark.parametrize("empty_url", ["", "  "])
-def test_init_raises_on_empty_auth_url(empty_url: str) -> None:
-    with pytest.raises(ValueError, match="auth_url"):
-        _BaseClient(auth_url=empty_url, vlm_url="https://vlm.example.com")
-
-
-@pytest.mark.parametrize("empty_url", ["", "  "])
-def test_init_raises_on_empty_vlm_url(empty_url: str) -> None:
-    with pytest.raises(ValueError, match="vlm_url"):
-        _BaseClient(auth_url="https://auth.example.com", vlm_url=empty_url)
-
-
-def test_auth_header_raises_on_empty_token() -> None:
-    with pytest.raises(ValueError, match="access_token"):
-        _BaseClient._build_auth_header(access_token="")
-
-
-_ALLOWED_ISSUERS = [
-    "https://offline.visionai.linkervision.com/keycloak/realms/linker-platform",
-    "https://data-engine-staging.jp.auth0.com",
-]
-
-
-@pytest.mark.parametrize("issuer", _ALLOWED_ISSUERS)
-def test_validate_issuer_passes_for_allowed(issuer: str) -> None:
-    client = _BaseClient(
-        auth_url="https://auth.example.com",
-        vlm_url="https://vlm.example.com",
-        allowed_issuers=_ALLOWED_ISSUERS,
-    )
-    client._jwt_verifier._validate_issuer(issuer)  # should not raise
-
-
-@pytest.mark.parametrize(
-    "issuer",
-    [
-        "https://evil.com/keycloak/realms/linker-platform",
-        "https://attacker.auth0.com/",
-        "https://offline.visionai.linkervision.com/keycloak/realms/other-realm",
-    ],
-)
-def test_validate_issuer_raises_for_unknown(issuer: str) -> None:
-    client = _BaseClient(
-        auth_url="https://auth.example.com",
-        vlm_url="https://vlm.example.com",
-        allowed_issuers=_ALLOWED_ISSUERS,
-    )
-    with pytest.raises(jwt.InvalidIssuerError):
-        client._jwt_verifier._validate_issuer(issuer)
-
-
-def test_validate_issuer_raises_for_unknown_when_no_allowed_issuers() -> None:
-    client = _BaseClient(
-        auth_url="https://auth.example.com",
-        vlm_url="https://vlm.example.com",
-    )
-    with pytest.raises(jwt.InvalidIssuerError):
-        client._jwt_verifier._validate_issuer("https://anyone.com/")  # should not raise