visionai-sdk-python 0.1.0__py3-none-any.whl

visionai_sdk_python/__init__.py

@@ -0,0 +1,30 @@
+"""VisionAI SDK for Python.
+
+A client library for interacting with VisionAI authentication and VLM services.
+"""
+
+from .async_client import AsyncClient
+from .client import Client
+from .exceptions import (
+    AuthenticationError,
+    ClientError,
+    JwksDiscoveryError,
+    NetworkError,
+    PermissionDeniedError,
+    ServerError,
+    VisionaiSDKError,
+)
+from .models import TokenResponse
+
+__all__ = [
+    "AsyncClient",
+    "Client",
+    "TokenResponse",
+    "VisionaiSDKError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "ClientError",
+    "ServerError",
+    "NetworkError",
+    "JwksDiscoveryError",
+]

visionai_sdk_python/_base.py

@@ -0,0 +1,203 @@
+import time
+import httpx
+from typing import Literal
+
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    ClientError,
+    PermissionDeniedError,
+    ServerError,
+)
+from ._jwt_verifier import JwtVerifier
+from .constants import resolve_allowed_issuers
+
+
+class _BaseClient:
+    """Base class for VisionAI SDK clients.
+
+    Holds shared connection configuration and provides
+    common URL/header builder utilities.
+    """
+
+    def __init__(
+        self,
+        auth_url: str,
+        vlm_url: str,
+        allowed_issuers: list[str] | None = None,
+        verify_ssl: bool = True,
+        timeout: float = 10.0,
+        max_connections: int = 100,
+        max_keepalive_connections: int = 20,
+    ) -> None:
+        """Initialize the client with connection settings.
+
+        Args:
+            auth_url: Base URL for the authentication service.
+            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.
+            verify_ssl: Whether to verify TLS certificates.
+            timeout: Default request timeout in seconds.
+            max_connections: Maximum number of concurrent connections in the pool.
+            max_keepalive_connections: Maximum number of idle keep-alive connections.
+        """
+        if not auth_url.strip():
+            raise ValueError("auth_url must not be empty")
+        if not vlm_url.strip():
+            raise ValueError("vlm_url must not be empty")
+        self.auth_url = auth_url.strip()
+        self.vlm_url = vlm_url.strip()
+        self.verify_ssl = verify_ssl
+        self.timeout = timeout
+        self.max_connections = max_connections
+        self.max_keepalive_connections = max_keepalive_connections
+        resolved_issuers: list[str] = allowed_issuers if allowed_issuers is not None else resolve_allowed_issuers(self.auth_url)
+        self._jwt_verifier = JwtVerifier(
+            auth_url=self.auth_url,
+            allowed_issuers=resolved_issuers,
+            verify_ssl=verify_ssl,
+            timeout=timeout,
+        )
+
+        # Token management state
+        self._access_token: str | None = None
+        self._token_expires_at: float | None = None  # monotonic time
+        self._credentials: dict | None = None
+        self._credentials_type: Literal["login", "client"] | None = None
+
+    @staticmethod
+    def _build_url(base_url: str, path: str) -> str:
+        """Join a base URL and a path, normalizing slashes."""
+        return f"{base_url.rstrip('/')}/{path.lstrip('/')}"
+
+    @staticmethod
+    def _build_auth_header(access_token: str) -> dict[str, str]:
+        """Build authorization header."""
+        if not access_token:
+            raise ValueError("access_token must not be empty")
+        return {"Authorization": f"Bearer {access_token}"}
+
+
+    def _store_token(
+        self,
+        access_token: str,
+        expires_in: int,
+        credentials: dict | None = None,
+        credentials_type: Literal["login", "client"] | None = None,
+    ) -> None:
+        """Store token and credentials for auto-refresh.
+
+        Args:
+            access_token: JWT access token.
+            expires_in: Token expiration time in seconds.
+            credentials: Optional credentials for auto-refresh.
+            credentials_type: Type of credentials ("login" or "client").
+        """
+        self._access_token = access_token
+        self._token_expires_at = time.monotonic() + expires_in
+        self._credentials = credentials
+        self._credentials_type = credentials_type
+
+    def _is_token_expiring_soon(self, buffer_seconds: int = 30) -> bool:
+        """Check if token is expiring soon.
+
+        Args:
+            buffer_seconds: Time buffer in seconds before actual expiration.
+
+        Returns:
+            True if token is expiring within buffer_seconds, False otherwise.
+        """
+        if self._token_expires_at is None:
+            return True
+        return time.monotonic() >= (self._token_expires_at - buffer_seconds)
+
+    def set_token(self, access_token: str, expires_in: int | None = None) -> None:
+        """Set externally obtained token.
+
+        Use this when you have an access token obtained through other means
+        (e.g., frontend authorization code flow). Note that tokens set this way
+        cannot be auto-refreshed since no credentials are stored.
+
+        The token will be validated locally to ensure it has a valid signature
+        and has not expired. The actual expiration time from the token's ``exp``
+        claim will be used. If ``expires_in`` is provided, the minimum of the two
+        will be used to prevent extending the token's lifetime beyond its true expiration.
+
+        Args:
+            access_token: JWT access token.
+            expires_in: Optional token expiration time in seconds. If provided,
+                the effective expiration will be min(expires_in, token's actual remaining time).
+                If None, the token's actual ``exp`` claim will be used.
+
+        Raises:
+            ValueError: If access_token is empty.
+            jwt.ExpiredSignatureError: If token has already expired.
+            jwt.InvalidSignatureError: If token signature is invalid.
+            jwt.DecodeError: If token is malformed.
+            jwt.MissingRequiredClaimError: If token is missing required claims.
+            jwt.InvalidIssuerError: If token issuer is not allowed.
+
+        Example:
+            >>> client = Client(auth_url="...", vlm_url="...")
+            >>> client.set_token("eyJhbG...")
+            >>> result = client.chat(payload)  # Token will be used automatically
+        """
+        if not access_token.strip():
+            raise ValueError("access_token must not be empty")
+
+        # Validate token and extract exp claim
+        claims = self._jwt_verifier.verify_sync(access_token)
+        jwt_exp = claims.get("exp")
+        if jwt_exp is None:
+            raise ValueError("Token missing 'exp' claim")
+
+        # Calculate remaining time from JWT exp
+        jwt_expires_in = int(jwt_exp - time.time())
+        if jwt_expires_in <= 0:
+            raise ValueError("Token has already expired")
+
+        # Use the minimum of provided expires_in and actual JWT expiration
+        if expires_in is not None:
+            effective_expires_in = min(expires_in, jwt_expires_in)
+        else:
+            effective_expires_in = jwt_expires_in
+
+        self._store_token(access_token, effective_expires_in, credentials=None, credentials_type=None)
+
+    @staticmethod
+    def _handle_response(response: httpx.Response) -> httpx.Response:
+        """Raise SDK-specific exceptions for non-2xx responses.
+
+        Raises:
+            AuthenticationError: If the server returns 401
+            PermissionDeniedError: If the server returns 403
+            ClientError: If the server returns any other 4xx
+            ServerError: If the server returns 5xx
+            APIError: If the server returns any other non-2xx status
+        """
+        try:
+            response.raise_for_status()
+        except httpx.HTTPStatusError as e:
+            body = None
+            if e.response.content:
+                try:
+                    body = e.response.json()
+                except Exception:
+                    pass
+            if isinstance(body, dict):
+                detail: str = body.get("detail") or body.get("message") or str(e)
+            else:
+                detail = str(e)
+            status = e.response.status_code
+            if status == 401:
+                raise AuthenticationError(detail) from e
+            if status == 403:
+                raise PermissionDeniedError(detail) from e
+            if 400 <= status < 500:
+                raise ClientError(status, detail) from e
+            if 500 <= status < 600:
+                raise ServerError(status, detail) from e
+            raise APIError(status, detail)
+        return response

visionai_sdk_python/_jwt_verifier.py

@@ -0,0 +1,207 @@
+import asyncio
+import ssl
+import time
+
+import httpx
+import jwt
+from jwt import PyJWKClient
+
+from .exceptions import JwksDiscoveryError
+
+_OIDC_DISCOVERY_PATH = "/.well-known/openid-configuration"
+_JWKS_URI_TTL: float = 3600.0  # seconds; refresh OIDC discovery cache after 1 hour
+# Supported asymmetric signing algorithms:
+# - RS256/384/512: RSA signature with SHA-256/384/512
+# - ES256/384/512: ECDSA signature with SHA-256/384/512
+_ALLOWED_ALGORITHMS: list[str] = ["RS256", "RS384", "RS512", "ES256", "ES384", "ES512"]
+
+
+def _get_insecure_context() -> ssl.SSLContext:
+    ctx = ssl.create_default_context()
+    ctx.check_hostname = False
+    ctx.verify_mode = ssl.CERT_NONE
+    return ctx
+
+class JwtVerifier:
+    """Stateful JWT verifier that handles OIDC discovery and JWKS key fetching.
+
+    Maintains two internal caches:
+    - ``_jwks_uri_cache``: issuer → jwks_uri with TTL-based expiry.
+    - ``_jwks_clients``: jwks_uri → PyJWKClient (key-level caching delegated to PyJWKClient).
+    """
+
+    def __init__(
+        self,
+        auth_url: str,
+        allowed_issuers: list[str] | None = None,
+        verify_ssl: bool = True,
+        timeout: float = 10.0,
+    ) -> None:
+        self._auth_url = auth_url
+        self._allowed_issuers: frozenset[str] = frozenset(allowed_issuers) if allowed_issuers else frozenset()
+        self._verify_ssl = verify_ssl
+        self._timeout = timeout
+        # issuer -> (jwks_uri, expire_at)
+        self._jwks_uri_cache: dict[str, tuple[str, float]] = {}
+        # jwks_uri -> PyJWKClient
+        self._jwks_clients: dict[str, PyJWKClient] = {}
+
+    # ------------------------------------------------------------------
+    # Cache helpers
+    # ------------------------------------------------------------------
+
+    def _get_cached_jwks_uri(self, issuer: str) -> str | None:
+        entry = self._jwks_uri_cache.get(issuer)
+        if entry is None:
+            return None
+        jwks_uri, expire_at = entry
+        if time.monotonic() >= expire_at:
+            del self._jwks_uri_cache[issuer]
+            return None
+        return jwks_uri
+
+    def _cache_jwks_uri(self, issuer: str, jwks_uri: str) -> None:
+        self._jwks_uri_cache[issuer] = (jwks_uri, time.monotonic() + _JWKS_URI_TTL)
+
+    def _validate_issuer(self, issuer: str) -> None:
+        """Validate issuer is in the allowed issuers list.
+
+        Raises:
+            jwt.InvalidIssuerError: If allowed_issuers is set and issuer is not in the list.
+        """
+        normalized = issuer.rstrip("/")
+        if self._allowed_issuers and normalized not in self._allowed_issuers:
+            raise jwt.InvalidIssuerError(
+                f"Token issuer '{normalized}' is not in the allowed issuers list"
+            )
+
+    def _get_jwks_client(self, jwks_uri: str) -> PyJWKClient:
+        if jwks_uri not in self._jwks_clients:
+            ssl_context = None if self._verify_ssl else _get_insecure_context()
+            self._jwks_clients[jwks_uri] = PyJWKClient(
+                jwks_uri,
+                cache_keys=True,
+                timeout=self._timeout,
+                ssl_context=ssl_context,
+            )
+        return self._jwks_clients[jwks_uri]
+
+    # ------------------------------------------------------------------
+    # Pure JWT helpers (no I/O)
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _get_issuer(access_token: str) -> str:
+        """Return issuer from the token without verifying signature."""
+        claims = jwt.decode(
+            access_token,
+            options={"verify_signature": False, "verify_exp": False},
+            algorithms=_ALLOWED_ALGORITHMS,
+        )
+        issuer: str = claims.get("iss", "")
+        if not issuer:
+            raise jwt.MissingRequiredClaimError("iss")
+        return issuer
+
+    @staticmethod
+    def _decode_verified(access_token: str, signing_key: object) -> dict:
+        """Verify signature + exp and return claims."""
+        return jwt.decode(
+            access_token,
+            signing_key,  # type: ignore[arg-type]
+            algorithms=_ALLOWED_ALGORITHMS,
+            options={"verify_exp": True, "verify_aud": False},
+        )
+
+    # ------------------------------------------------------------------
+    # OIDC discovery: sync / async
+    # ------------------------------------------------------------------
+
+    def _fetch_jwks_uri_sync(self, issuer: str) -> str:
+        """Resolve jwks_uri from the OIDC discovery document (blocking).
+
+        Raises:
+            JwksDiscoveryError: If the discovery endpoint is unreachable, returns a
+                non-2xx status, or the response does not contain ``jwks_uri``.
+        """
+        cached = self._get_cached_jwks_uri(issuer)
+        if cached is not None:
+            return cached
+
+        discovery_url = f"{issuer.rstrip('/')}{_OIDC_DISCOVERY_PATH}"
+        try:
+            with httpx.Client(verify=self._verify_ssl, timeout=self._timeout) as http:
+                resp = http.get(discovery_url)
+                resp.raise_for_status()
+                jwks_uri: str = resp.json()["jwks_uri"]
+        except (httpx.RequestError, httpx.HTTPStatusError, KeyError) as e:
+            raise JwksDiscoveryError(
+                f"Failed to fetch OIDC discovery document from '{discovery_url}': {e}"
+            ) from e
+
+        self._cache_jwks_uri(issuer, jwks_uri)
+        return jwks_uri
+
+    async def _fetch_jwks_uri_async(self, issuer: str) -> str:
+        """Resolve jwks_uri from the OIDC discovery document (non-blocking).
+
+        Raises:
+            JwksDiscoveryError: If the discovery endpoint is unreachable, returns a
+                non-2xx status, or the response does not contain ``jwks_uri``.
+        """
+        cached = self._get_cached_jwks_uri(issuer)
+        if cached is not None:
+            return cached
+
+        discovery_url = f"{issuer.rstrip('/')}{_OIDC_DISCOVERY_PATH}"
+        try:
+            async with httpx.AsyncClient(verify=self._verify_ssl, timeout=self._timeout) as http:
+                resp = await http.get(discovery_url)
+                resp.raise_for_status()
+                jwks_uri: str = resp.json()["jwks_uri"]
+        except (httpx.RequestError, httpx.HTTPStatusError, KeyError) as e:
+            raise JwksDiscoveryError(
+                f"Failed to fetch OIDC discovery document from '{discovery_url}': {e}"
+            ) from e
+
+        self._cache_jwks_uri(issuer, jwks_uri)
+        return jwks_uri
+
+    # ------------------------------------------------------------------
+    # Public verify API
+    # ------------------------------------------------------------------
+
+    def verify_sync(self, access_token: str) -> dict:
+        """Validate JWT signature and expiration (blocking).
+
+        Raises:
+            jwt.ExpiredSignatureError: Token has expired.
+            jwt.InvalidSignatureError: Signature does not match.
+            jwt.DecodeError: Token is malformed.
+            jwt.MissingRequiredClaimError: Token is missing the ``iss`` claim.
+            jwt.InvalidIssuerError: Token issuer is not in the allowed issuers list.
+        """
+        issuer = self._get_issuer(access_token)
+        self._validate_issuer(issuer)
+        jwks_uri = self._fetch_jwks_uri_sync(issuer)
+        signing_key = self._get_jwks_client(jwks_uri).get_signing_key_from_jwt(access_token)
+        return self._decode_verified(access_token, signing_key.key)
+
+    async def verify_async(self, access_token: str) -> dict:
+        """Validate JWT signature and expiration (non-blocking).
+
+        Raises:
+            jwt.ExpiredSignatureError: Token has expired.
+            jwt.InvalidSignatureError: Signature does not match.
+            jwt.DecodeError: Token is malformed.
+            jwt.MissingRequiredClaimError: Token is missing the ``iss`` claim.
+            jwt.InvalidIssuerError: Token issuer is not in the allowed issuers list.
+        """
+        issuer = self._get_issuer(access_token)
+        self._validate_issuer(issuer)
+        jwks_uri = await self._fetch_jwks_uri_async(issuer)
+        # PyJWKClient.get_signing_key_from_jwt does blocking HTTP; offload to thread pool
+        signing_key = await asyncio.to_thread(
+            self._get_jwks_client(jwks_uri).get_signing_key_from_jwt, access_token
+        )
+        return self._decode_verified(access_token, signing_key.key)

visionai_sdk_python/async_client.py

@@ -0,0 +1,301 @@
+import logging
+import httpx
+import jwt
+
+from ._base import _BaseClient
+from .endpoints import AuthEndpoint, VLMEndpoint
+from .models import TokenResponse
+from .exceptions import AuthenticationError, JwksDiscoveryError, NetworkError, VisionaiSDKError
+from .models import TokenResponse, NIMRequestModel, ResponseNormalModel, ResponseErrorModel
+
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncClient(_BaseClient):
+    def __init__(
+        self,
+        auth_url: str,
+        vlm_url: str,
+        allowed_issuers: list[str] | None = None,
+        verify_ssl: bool = True,
+        timeout: float = 10.0,
+        max_connections: int = 100,
+        max_keepalive_connections: int = 20,
+    ) -> None:
+        super().__init__(
+            auth_url=auth_url,
+            vlm_url=vlm_url,
+            allowed_issuers=allowed_issuers,
+            verify_ssl=verify_ssl,
+            timeout=timeout,
+            max_connections=max_connections,
+            max_keepalive_connections=max_keepalive_connections,
+        )
+        self._client = httpx.AsyncClient(
+            verify=self.verify_ssl,
+            timeout=self.timeout,
+            limits=httpx.Limits(
+                max_connections=self.max_connections,
+                max_keepalive_connections=self.max_keepalive_connections,
+            ),
+        )
+
+
+    async def _request(self, method: str, url: str, **kwargs) -> httpx.Response:
+        """Execute an async HTTP request, mapping httpx exceptions to SDK exceptions."""
+        try:
+            response = await self._client.request(method, url, **kwargs)
+        except httpx.TimeoutException as e:
+            raise NetworkError("Request timed out") from e
+        except httpx.NetworkError as e:
+            raise NetworkError(f"Network error: {e}") from e
+        except httpx.RequestError as e:
+            raise VisionaiSDKError(f"Request failed: {e}") from e
+        return self._handle_response(response)
+
+    async def close(self) -> None:
+        """Close the HTTP client and release connections."""
+        await self._client.aclose()
+
+
+    async def __aenter__(self) -> "AsyncClient":
+        """Async context manager entry."""
+        return self
+
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Async context manager exit - close client."""
+        await self.close()
+
+
+    async def get_access_token(self, client_id: str, client_secret: str) -> TokenResponse:
+        """Get access token using client credentials flow.
+
+        The token is stored internally and will be used automatically for subsequent
+        API calls. If the token expires, it will be automatically refreshed.
+
+        Args:
+            client_id: OAuth client ID
+            client_secret: OAuth client secret
+
+        Returns:
+            TokenResponse with access_token, expires_in, and token_type
+
+        Raises:
+            ValueError: If client_id or client_secret is empty
+            NetworkError: If the request times out or a network error occurs
+            VisionaiSDKError: If the request fails for any other reason
+        """
+        if not client_id.strip():
+            raise ValueError("client_id must not be empty")
+        if not client_secret.strip():
+            raise ValueError("client_secret must not be empty")
+
+        response = await self._request(
+            "POST",
+            self._build_url(self.auth_url, AuthEndpoint.CLIENT_TOKEN),
+            json={"client_id": client_id, "client_secret": client_secret},
+        )
+        token_response = TokenResponse(**response.json())
+
+        # Store token and credentials for auto-refresh
+        self._store_token(
+            access_token=token_response.access_token,
+            expires_in=token_response.expires_in,
+            credentials={"client_id": client_id, "client_secret": client_secret},
+            credentials_type="client",
+        )
+
+        return token_response
+
+
+    async def login(self, email: str, password: str) -> TokenResponse:
+        """Login with email and password to get JWT token.
+
+        The token is stored internally and will be used automatically for subsequent
+        API calls. If the token expires, it will be automatically refreshed.
+
+        Args:
+            email: User email address
+            password: User password
+
+        Returns:
+            TokenResponse with access_token, expires_in, and token_type
+
+        Raises:
+            ValueError: If email or password is empty
+            NetworkError: If the request times out or a network error occurs
+            VisionaiSDKError: If the request fails for any other reason
+        """
+        if not email.strip():
+            raise ValueError("email must not be empty")
+        if not password.strip():
+            raise ValueError("password must not be empty")
+
+        response = await self._request(
+            "POST",
+            self._build_url(self.auth_url, AuthEndpoint.LOGIN),
+            json={"email": email, "password": password},
+        )
+        token_response = TokenResponse(**response.json())
+
+        # Store token and credentials for auto-refresh
+        self._store_token(
+            access_token=token_response.access_token,
+            expires_in=token_response.expires_in,
+            credentials={"email": email, "password": password},
+            credentials_type="login",
+        )
+
+        return token_response
+
+    async def _refresh_token(self) -> None:
+        """Refresh token using stored credentials.
+
+        Raises:
+            AuthenticationError: If no credentials are stored or refresh fails.
+        """
+        if self._credentials is None or self._credentials_type is None:
+            raise AuthenticationError("No credentials available for token refresh")
+
+        if self._credentials_type == "login":
+            await self.login(
+                email=self._credentials["email"],
+                password=self._credentials["password"],
+            )
+        elif self._credentials_type == "client":
+            await self.get_access_token(
+                client_id=self._credentials["client_id"],
+                client_secret=self._credentials["client_secret"],
+            )
+
+    async def _ensure_token(self) -> None:
+        """Ensure a valid token is available, refreshing if necessary.
+
+        Raises:
+            AuthenticationError: If no token is available or token expired without credentials.
+        """
+        if self._access_token is None:
+            raise AuthenticationError("Not authenticated. Call login() or get_access_token() first.")
+
+        if self._is_token_expiring_soon():
+            if self._credentials is None:
+                raise AuthenticationError("Token expired and no credentials available for refresh")
+            await self._refresh_token()
+
+    async def is_token_valid(self, access_token: str) -> bool:
+        """Check whether a JWT access token is currently valid.
+
+        Validates the token's signature and expiration without raising exceptions.
+
+        Args:
+            access_token: JWT access token to validate.
+
+        Returns:
+            ``True`` if the token passes signature and expiration checks,
+            ``False`` otherwise (invalid token or JWKS service unavailable).
+
+        Note:
+            Logs token validation failures. Unexpected errors will propagate
+            to allow fail-fast behavior for programming errors.
+        """
+        try:
+            await self._jwt_verifier.verify_async(access_token)
+            return True
+        except jwt.InvalidTokenError as e:
+            # Expected: expired, malformed, invalid signature, missing claims
+            logger.warning(
+                "%s: Token validation failed",
+                type(e).__name__,
+                extra={"jwt_error_type": type(e).__name__, "jwt_error_message": str(e)}
+            )
+            return False
+        except jwt.PyJWKClientError as e:
+            # Expected: JWKS endpoint unavailable, network issues
+            logger.error(
+                "%s: JWKS client error during token validation",
+                type(e).__name__,
+                extra={"jwt_error_type": "PyJWKClientError", "jwt_error_message": str(e)}
+            )
+            return False
+        except JwksDiscoveryError as e:
+            # Expected: OIDC discovery endpoint unreachable or returned unexpected response
+            logger.error(
+                "%s: OIDC discovery failed during token validation",
+                type(e).__name__,
+                extra={"jwt_error_type": type(e).__name__, "jwt_error_message": str(e)}
+            )
+            return False
+
+    async def chat(
+        self,
+        payload: NIMRequestModel | dict,
+    ) -> ResponseNormalModel | ResponseErrorModel:
+        """Submit an inference request to the VLM service.
+
+        Uses the internally stored access token obtained from login() or get_access_token().
+        If the token is expiring soon, it will be automatically refreshed.
+
+        Args:
+            payload: Inference parameters as a NIMRequestModel instance or a dict
+                whose keys match NIMRequestModel fields (validated via model_validate).
+
+        Returns:
+            ResponseNormalModel if the request is accepted (status: pending/running/completed),
+            or ResponseErrorModel if the inference failed or timed out.
+
+        Raises:
+            ValidationError: If payload is a dict that fails NIMRequestModel validation.
+            AuthenticationError: If not authenticated or token expired without refresh credentials.
+            NetworkError: If the request times out or a network error occurs.
+            VisionaiSDKError: If the request fails for any other reason.
+        """
+        await self._ensure_token()
+
+        nim_request = (
+            NIMRequestModel.model_validate(payload)
+            if isinstance(payload, dict)
+            else payload
+        )
+        response = await self._request(
+            "POST",
+            self._build_url(self.vlm_url, VLMEndpoint.CHAT),
+            headers=self._build_auth_header(self._access_token),
+            json=nim_request.model_dump(mode="json"),
+        )
+        data = response.json()
+        if data.get("status") in ("failed", "timeout"):
+            return ResponseErrorModel(**data)
+        return ResponseNormalModel(**data)
+
+
+    async def get_chat(self, result_id: str) -> ResponseNormalModel | ResponseErrorModel:
+        """Poll the result of a previously submitted inference request.
+
+        Uses the internally stored access token obtained from login() or get_access_token().
+        If the token is expiring soon, it will be automatically refreshed.
+
+        Args:
+            result_id: Chat result ID returned from a prior chat() call.
+
+        Returns:
+            ResponseNormalModel if the result is available (status: pending/running/completed),
+            or ResponseErrorModel if the inference failed or timed out.
+
+        Raises:
+            AuthenticationError: If not authenticated or token expired without refresh credentials.
+            NetworkError: If the request times out or a network error occurs.
+            VisionaiSDKError: If the request fails for any other reason.
+        """
+        await self._ensure_token()
+
+        response = await self._request(
+            "GET",
+            self._build_url(self.vlm_url, f"{VLMEndpoint.CHAT}/{result_id}"),
+            headers=self._build_auth_header(self._access_token),
+        )
+        data = response.json()
+        if data.get("status") in ("failed", "timeout"):
+            return ResponseErrorModel(**data)
+        return ResponseNormalModel(**data)

visionai_sdk_python/client.py

@@ -0,0 +1,300 @@
+import logging
+import httpx
+import jwt
+
+from ._base import _BaseClient
+from .endpoints import AuthEndpoint, VLMEndpoint
+from .exceptions import AuthenticationError, JwksDiscoveryError, NetworkError, VisionaiSDKError
+from .models import TokenResponse, NIMRequestModel, ResponseNormalModel, ResponseErrorModel
+
+logger = logging.getLogger(__name__)
+
+
+class Client(_BaseClient):
+    def __init__(
+        self,
+        auth_url: str,
+        vlm_url: str,
+        allowed_issuers: list[str] | None = None,
+        verify_ssl: bool = True,
+        timeout: float = 10.0,
+        max_connections: int = 100,
+        max_keepalive_connections: int = 20,
+    ) -> None:
+        super().__init__(
+            auth_url=auth_url,
+            vlm_url=vlm_url,
+            allowed_issuers=allowed_issuers,
+            verify_ssl=verify_ssl,
+            timeout=timeout,
+            max_connections=max_connections,
+            max_keepalive_connections=max_keepalive_connections,
+        )
+        self._client = httpx.Client(
+            verify=self.verify_ssl,
+            timeout=self.timeout,
+            limits=httpx.Limits(
+                max_connections=self.max_connections,
+                max_keepalive_connections=self.max_keepalive_connections,
+            ),
+        )
+
+
+    def _request(self, method: str, url: str, **kwargs) -> httpx.Response:
+        """Execute an HTTP request, mapping httpx exceptions to SDK exceptions."""
+        try:
+            response = self._client.request(method, url, **kwargs)
+        except httpx.TimeoutException as e:
+            raise NetworkError("Request timed out") from e
+        except httpx.NetworkError as e:
+            raise NetworkError(f"Network error: {e}") from e
+        except httpx.RequestError as e:
+            raise VisionaiSDKError(f"Request failed: {e}") from e
+        return self._handle_response(response)
+
+    def close(self) -> None:
+        """Close the HTTP client and release connections."""
+        self._client.close()
+
+
+    def __enter__(self) -> "Client":
+        """Context manager entry."""
+        return self
+
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Context manager exit - close client."""
+        self.close()
+    
+
+    def get_access_token(self, client_id: str, client_secret: str) -> TokenResponse:
+        """Get access token using client credentials flow.
+
+        The token is stored internally and will be used automatically for subsequent
+        API calls. If the token expires, it will be automatically refreshed.
+
+        Args:
+            client_id: OAuth client ID
+            client_secret: OAuth client secret
+
+        Returns:
+            TokenResponse with access_token, expires_in, and token_type
+
+        Raises:
+            ValueError: If client_id or client_secret is empty
+            NetworkError: If the request times out or a network error occurs
+            VisionaiSDKError: If the request fails for any other reason
+        """
+        if not client_id.strip():
+            raise ValueError("client_id must not be empty")
+        if not client_secret.strip():
+            raise ValueError("client_secret must not be empty")
+
+        response = self._request(
+            "POST",
+            self._build_url(self.auth_url, AuthEndpoint.CLIENT_TOKEN),
+            json={"client_id": client_id, "client_secret": client_secret},
+        )
+        token_response = TokenResponse(**response.json())
+
+        # Store token and credentials for auto-refresh
+        self._store_token(
+            access_token=token_response.access_token,
+            expires_in=token_response.expires_in,
+            credentials={"client_id": client_id, "client_secret": client_secret},
+            credentials_type="client",
+        )
+
+        return token_response
+
+
+    def login(self, email: str, password: str) -> TokenResponse:
+        """Login with email and password to get JWT token.
+
+        The token is stored internally and will be used automatically for subsequent
+        API calls. If the token expires, it will be automatically refreshed.
+
+        Args:
+            email: User email address
+            password: User password
+
+        Returns:
+            TokenResponse with access_token, expires_in, and token_type
+
+        Raises:
+            ValueError: If email or password is empty
+            NetworkError: If the request times out or a network error occurs
+            VisionaiSDKError: If the request fails for any other reason
+        """
+        if not email.strip():
+            raise ValueError("email must not be empty")
+        if not password.strip():
+            raise ValueError("password must not be empty")
+
+        response = self._request(
+            "POST",
+            self._build_url(self.auth_url, AuthEndpoint.LOGIN),
+            json={"email": email, "password": password},
+        )
+        token_response = TokenResponse(**response.json())
+
+        # Store token and credentials for auto-refresh
+        self._store_token(
+            access_token=token_response.access_token,
+            expires_in=token_response.expires_in,
+            credentials={"email": email, "password": password},
+            credentials_type="login",
+        )
+
+        return token_response
+
+    def _refresh_token(self) -> None:
+        """Refresh token using stored credentials.
+
+        Raises:
+            AuthenticationError: If no credentials are stored or refresh fails.
+        """
+        if self._credentials is None or self._credentials_type is None:
+            raise AuthenticationError("No credentials available for token refresh")
+
+        if self._credentials_type == "login":
+            self.login(
+                email=self._credentials["email"],
+                password=self._credentials["password"],
+            )
+        elif self._credentials_type == "client":
+            self.get_access_token(
+                client_id=self._credentials["client_id"],
+                client_secret=self._credentials["client_secret"],
+            )
+
+    def _ensure_token(self) -> None:
+        """Ensure a valid token is available, refreshing if necessary.
+
+        Raises:
+            AuthenticationError: If no token is available or token expired without credentials.
+        """
+        if self._access_token is None:
+            raise AuthenticationError("Not authenticated. Call login() or get_access_token() first.")
+
+        if self._is_token_expiring_soon():
+            if self._credentials is None:
+                raise AuthenticationError("Token expired and no credentials available for refresh")
+            self._refresh_token()
+
+    def is_token_valid(self, access_token: str) -> bool:
+        """Check whether a JWT access token is currently valid.
+
+        Validates the token's signature and expiration without raising exceptions.
+
+        Args:
+            access_token: JWT access token to validate.
+
+        Returns:
+            ``True`` if the token passes signature and expiration checks,
+            ``False`` otherwise (invalid token or JWKS service unavailable).
+
+        Note:
+            Logs token validation failures. Unexpected errors will propagate
+            to allow fail-fast behavior for programming errors.
+        """
+        try:
+            self._jwt_verifier.verify_sync(access_token)
+            return True
+        except jwt.InvalidTokenError as e:
+            # Expected: expired, malformed, invalid signature, missing claims
+            logger.warning(
+                "%s: Token validation failed",
+                type(e).__name__,
+                extra={"jwt_error_type": type(e).__name__, "jwt_error_message": str(e)}
+            )
+            return False
+        except jwt.PyJWKClientError as e:
+            # Expected: JWKS endpoint unavailable, network issues
+            logger.error(
+                "%s: JWKS client error during token validation",
+                type(e).__name__,
+                extra={"jwt_error_type": "PyJWKClientError", "jwt_error_message": str(e)}
+            )
+            return False
+        except JwksDiscoveryError as e:
+            # Expected: OIDC discovery endpoint unreachable or returned unexpected response
+            logger.error(
+                "%s: OIDC discovery failed during token validation",
+                type(e).__name__,
+                extra={"jwt_error_type": type(e).__name__, "jwt_error_message": str(e)}
+            )
+            return False
+        
+    
+    def chat(
+            self,
+            payload: NIMRequestModel | dict,
+        ) -> ResponseNormalModel | ResponseErrorModel:
+        """Submit an inference request to the VLM service.
+
+        Uses the internally stored access token obtained from login() or get_access_token().
+        If the token is expiring soon, it will be automatically refreshed.
+
+        Args:
+            payload: Inference parameters as a NIMRequestModel instance or a dict
+                whose keys match NIMRequestModel fields (validated via model_validate).
+
+        Returns:
+            ResponseNormalModel if the request is accepted (status: pending/running/completed),
+            or ResponseErrorModel if the inference failed or timed out.
+
+        Raises:
+            ValidationError: If payload is a dict that fails NIMRequestModel validation.
+            AuthenticationError: If not authenticated or token expired without refresh credentials.
+            NetworkError: If the request times out or a network error occurs.
+            VisionaiSDKError: If the request fails for any other reason.
+        """
+        self._ensure_token()
+
+        nim_request = (
+            NIMRequestModel.model_validate(payload)
+            if isinstance(payload, dict)
+            else payload
+        )
+        response = self._request(
+            "POST",
+            self._build_url(self.vlm_url, VLMEndpoint.CHAT),
+            headers=self._build_auth_header(self._access_token),
+            json=nim_request.model_dump(mode="json"),
+        )
+        data = response.json()
+        if data.get("status") in ("failed", "timeout"):
+            return ResponseErrorModel(**data)
+        return ResponseNormalModel(**data)
+
+
+    def get_chat(self, result_id: str) -> ResponseNormalModel | ResponseErrorModel:
+        """Poll the result of a previously submitted inference request.
+
+        Uses the internally stored access token obtained from login() or get_access_token().
+        If the token is expiring soon, it will be automatically refreshed.
+
+        Args:
+            result_id: Chat result ID returned from a prior chat() call.
+
+        Returns:
+            ResponseNormalModel if the result is available (status: pending/running/completed),
+            or ResponseErrorModel if the inference failed or timed out.
+
+        Raises:
+            AuthenticationError: If not authenticated or token expired without refresh credentials.
+            NetworkError: If the request times out or a network error occurs.
+            VisionaiSDKError: If the request fails for any other reason.
+        """
+        self._ensure_token()
+
+        response = self._request(
+            "GET",
+            self._build_url(self.vlm_url, f"{VLMEndpoint.CHAT}/{result_id}"),
+            headers=self._build_auth_header(self._access_token),
+        )
+        data = response.json()
+        if data.get("status") in ("failed", "timeout"):
+            return ResponseErrorModel(**data)
+        return ResponseNormalModel(**data)

visionai_sdk_python/constants.py

@@ -0,0 +1,49 @@
+# 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/endpoints.py

@@ -0,0 +1,10 @@
+from enum import StrEnum
+
+
+class AuthEndpoint(StrEnum):
+    CLIENT_TOKEN = "/api/users/client-token"
+    LOGIN = "/api/users/jwt"
+
+
+class VLMEndpoint(StrEnum):
+    CHAT = "/api/chat"

visionai_sdk_python/exceptions.py

@@ -0,0 +1,40 @@
+class VisionaiSDKError(Exception):
+    """Base exception for all SDK errors."""
+
+
+class APIError(VisionaiSDKError):
+    """Base exception for all HTTP API errors (has status_code)."""
+
+    def __init__(self, status_code: int, message: str) -> None:
+        self.status_code = status_code
+        super().__init__(f"[{status_code}] {message}")
+
+
+class ClientError(APIError):
+    """4xx - Client-side error."""
+
+
+class AuthenticationError(ClientError):
+    """401 - Invalid credentials/password."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(401, message)
+
+
+class PermissionDeniedError(ClientError):
+    """403 - Insufficient permissions."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(403, message)
+
+
+class ServerError(APIError):
+    """5xx - Server-side failure, consider retry."""
+
+
+class NetworkError(VisionaiSDKError):
+    """Connection or timeout failure."""
+
+
+class JwksDiscoveryError(VisionaiSDKError):
+    """Failed to fetch or parse the OIDC discovery document or JWKS endpoint."""

visionai_sdk_python/models.py

@@ -0,0 +1,39 @@
+from pydantic import AnyHttpUrl, BaseModel, Field
+from typing import Literal
+
+class TokenResponse(BaseModel):
+    """Response model for authentication token endpoints.
+
+    Used by both /api/users/jwt and /api/users/client-token endpoints.
+    """
+    access_token: str = Field(..., description="JWT access token")
+    expires_in: int = Field(..., description="Token expiration time in seconds")
+    token_type: str = Field(..., description="Token type (e.g., 'Bearer')")
+
+
+class NIMRequestModel(BaseModel):
+    img: str | list[str]
+    prompt: str
+    temperature: float | None = 0.2
+    max_tokens: int | None = 500
+    top_p: float | None = 0.7
+    stream: bool = False
+    use_cache: bool = True
+    num_beams: int | None = 1
+    api_endpoint: AnyHttpUrl | None = None
+    hook: AnyHttpUrl | None = None
+    # Will only work within hook (will not validated though)
+    use_response_postprocess: bool = False
+
+
+class ResponseNormalModel(BaseModel):
+    chat_id: str
+    status: Literal["pending", "running", "completed"]
+    message: str | None = None
+
+
+class ResponseErrorModel(BaseModel):
+    chat_id: str
+    status: Literal["failed", "timeout"]
+    error: str
+    message: str | None = None

visionai_sdk_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,14 @@
+Metadata-Version: 2.3
+Name: visionai-sdk-python
+Version: 0.1.0
+Summary: VisionAI SDK for Python
+Author: Tony Yang
+Author-email: Tony Yang <tonyyang@linkervision.com>
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: cryptography>=46.0.5
+Requires-Dist: pyjwt[cryptography]>=2.8.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# README

visionai_sdk_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+visionai_sdk_python/__init__.py,sha256=FjhwCuJI-nI2sv3xxBp1mAXmtAefelZZj7fhFIQy9X0,624
+visionai_sdk_python/_base.py,sha256=gr-4Sb9i7kI1UMZueQXu57_7PvlBbEJh8PlA0EoljNo,8040
+visionai_sdk_python/_jwt_verifier.py,sha256=gFnm5mMoEAGdamIHYZ8wwPXP2itnfCm5Z4_8_SPzlwM,8365
+visionai_sdk_python/async_client.py,sha256=CS_GRf6cxIG8vZTOuOPp5Hf86UdJMCXsHHmTrcYB8eA,11601
+visionai_sdk_python/client.py,sha256=l8VnNXMINton247U7MsFYg-itRN1OJjXAhDsUD9c3jE,11414
+visionai_sdk_python/constants.py,sha256=hDLdISOkrrEifLumVy0gPLO2NmUDxdfe2UIueizpbh8,1868
+visionai_sdk_python/endpoints.py,sha256=CC-AoxXzg39sMAhqx1CTS3gRWKx_H7VOqBANRLVotoU,183
+visionai_sdk_python/exceptions.py,sha256=r4bxvsQGNTVa7-ISX1JAC7VRJ-6qs3n30l3j3qxai-Y,1047
+visionai_sdk_python/models.py,sha256=RJcN3dS-5tFR8_NhyWEc8ANMBmPDNEI7ZbPf5ZxcfcU,1198
+visionai_sdk_python/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+visionai_sdk_python-0.1.0.dist-info/WHEEL,sha256=s_zqWxHFEH8b58BCtf46hFCqPaISurdB9R1XJ8za6XI,80
+visionai_sdk_python-0.1.0.dist-info/METADATA,sha256=Hm46dTeS6xx5Z-ydjF24hegGFAqY4orip_K0awOpWwM,379
+visionai_sdk_python-0.1.0.dist-info/RECORD,,

visionai_sdk_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.6
+Root-Is-Purelib: true
+Tag: py3-none-any