feat(files): migrate filesets package to NemoClient typed HTTP client

packages/nemo_platform/pyproject.toml

@@ -313,6 +313,7 @@ nemo-guardrails-plugin = [
 nemo-platform-plugin = [
   "anthropic>=0.88.0",
   "fastapi>=0.115.4",
+  "jsonschema>=4.0.0",
   "lark>=1.1.0",
   "nemo-platform-sdk",
   "openai>=1.109.1",

packages/nemo_platform_plugin/pyproject.toml

@@ -20,6 +20,7 @@ classifiers = [
 dependencies = [
     "anthropic>=0.88.0",
     "fastapi>=0.115.4",
+    "jsonschema>=4.0.0",
     "lark>=1.1.0",
     "nemo-platform-sdk",
     "openai>=1.109.1",

packages/nemo_platform_plugin/src/nemo_platform_plugin/client/adapter.py

@@ -43,5 +43,6 @@ def client_from_platform(
     return client_cls(
         base_url=str(platform.base_url).rstrip("/"),
         workspace=platform.workspace,
+        default_headers=platform._custom_headers,  # type: ignore[arg-type]
         http_client=platform._client,  # type: ignore[arg-type]
     )

packages/nemo_platform_plugin/src/nemo_platform_plugin/client/client.py

@@ -19,6 +19,7 @@
 from typing import TypeVar, get_args, get_origin, overload
 
 import httpx
+from nemo_platform_plugin.client.errors import raise_for_status
 from nemo_platform_plugin.client.response import (
     AsyncNemoBinaryResponse,
     AsyncNemoStreamResponse,
@@ -49,9 +50,12 @@ class BaseNemoClient:
     Subclasses provide the actual HTTP transport (sync or async).
     """
 
-    def __init__(self, *, base_url: str, workspace: str | None = None) -> None:
+    def __init__(
+        self, *, base_url: str, workspace: str | None = None, default_headers: Mapping[str, str] | None = None
+    ) -> None:
         self._base_url = base_url.rstrip("/")
         self._workspace = workspace
+        self._default_headers = dict(default_headers) if default_headers else {}
 
     @property
     def base_url(self) -> str:
@@ -65,13 +69,19 @@ def _resolve_path(self, request: PreparedRequest) -> str:
         """Resolve path template with client defaults and explicit params.
 
         Client-level defaults (e.g. workspace) are merged under explicit
-        params — explicit always wins.  Raises ``ValueError`` if any
+        params — explicit always wins.  Path parameter values are
+        percent-encoded so reserved characters (``#``, ``?``, etc.) in
+        file paths don't break the URL.  Raises ``ValueError`` if any
         placeholders remain unresolved.
         """
+        from urllib.parse import quote
+
         params: dict[str, str] = {}
         if self._workspace:
             params["workspace"] = self._workspace
-        params.update(request.path_params)
+        # Percent-encode values so reserved chars in file paths don't break URLs.
+        # safe="/" preserves path separators within {path} placeholders.
+        params.update({k: quote(v, safe="/") for k, v in request.path_params.items()})
         try:
             path = request.path_template.format_map(params)
         except KeyError as exc:
@@ -80,6 +90,8 @@ def _resolve_path(self, request: PreparedRequest) -> str:
 
     def _request_headers(self, request: PreparedRequest) -> dict[str, str] | None:
         headers: dict[str, str] = {}
+        if self._default_headers:
+            headers.update(self._default_headers)
         if request.content_type is not None:
             headers["Content-Type"] = request.content_type
         if request.extra_headers:
@@ -93,10 +105,19 @@ def _is_stream(self, request: PreparedRequest) -> bool:
         return get_origin(request.response_type) is Stream
 
     def _resolve_query_params(self, request: PreparedRequest) -> dict[str, str | int | bool] | None:
-        """Filter out None values from query params for httpx."""
+        """Filter out None values and JSON-serialize dicts/lists in query params."""
         if request.query_params is None:
             return None
-        filtered = {k: v for k, v in request.query_params.items() if v is not None}
+        import json
+
+        filtered = {}
+        for k, v in request.query_params.items():
+            if v is None:
+                continue
+            if isinstance(v, (dict, list)):
+                filtered[k] = json.dumps(v)
+            else:
+                filtered[k] = v
         return filtered or None
 
 
@@ -112,7 +133,7 @@ def __init__(
         timeout: float = DEFAULT_TIMEOUT,
         http_client: httpx.Client | None = None,
     ) -> None:
-        super().__init__(base_url=base_url, workspace=workspace)
+        super().__init__(base_url=base_url, workspace=workspace, default_headers=default_headers)
         self._http = http_client or httpx.Client(
             headers=dict(default_headers) if default_headers else None,
             timeout=timeout,
@@ -157,22 +178,31 @@ def send(
         params = self._resolve_query_params(request)
 
         if self._is_binary(request):
-            stream_ctx = self._http.stream(
-                request.method, url, content=request.content, headers=req_headers, params=params
-            )
-            return NemoBinaryResponse(stream_ctx, request)
+            kwargs = {
+                "method": request.method,
+                "url": url,
+                "content": request.content,
+                "headers": req_headers,
+                "params": params,
+            }
+            return NemoBinaryResponse(self._http, kwargs, request)
 
         if self._is_stream(request):
             assert request.response_type is not None
-            stream_ctx = self._http.stream(
-                request.method, url, content=request.content, headers=req_headers, params=params
-            )
+            kwargs = {
+                "method": request.method,
+                "url": url,
+                "content": request.content,
+                "headers": req_headers,
+                "params": params,
+            }
             model_type = _get_stream_model_type(request.response_type)
-            return NemoStreamResponse(stream_ctx, model_type, request)
+            return NemoStreamResponse(self._http, kwargs, model_type, request)
 
         raw = self._http.request(request.method, url, content=request.content, headers=req_headers, params=params)
+        raise_for_status(raw)
         body = None
-        if raw.is_success and request.response_type is not None:
+        if request.response_type is not None:
             body = request.response_type.model_validate(raw.json())
         return NemoResponse(http_response=raw, body=body, request=request)
 
@@ -192,7 +222,7 @@ def __init__(
         timeout: float = DEFAULT_TIMEOUT,
         http_client: httpx.AsyncClient | None = None,
     ) -> None:
-        super().__init__(base_url=base_url, workspace=workspace)
+        super().__init__(base_url=base_url, workspace=workspace, default_headers=default_headers)
         self._http = http_client or httpx.AsyncClient(
             headers=dict(default_headers) if default_headers else None,
             timeout=timeout,
@@ -226,21 +256,30 @@ async def send(
         params = self._resolve_query_params(request)
 
         if self._is_binary(request):
-            stream_ctx = self._http.stream(
-                request.method, url, content=request.content, headers=req_headers, params=params
-            )
-            return AsyncNemoBinaryResponse(stream_ctx, request)
+            kwargs = {
+                "method": request.method,
+                "url": url,
+                "content": request.content,
+                "headers": req_headers,
+                "params": params,
+            }
+            return AsyncNemoBinaryResponse(self._http, kwargs, request)
 
         if self._is_stream(request):
             assert request.response_type is not None
-            stream_ctx = self._http.stream(
-                request.method, url, content=request.content, headers=req_headers, params=params
-            )
+            kwargs = {
+                "method": request.method,
+                "url": url,
+                "content": request.content,
+                "headers": req_headers,
+                "params": params,
+            }
             model_type = _get_stream_model_type(request.response_type)
-            return AsyncNemoStreamResponse(stream_ctx, model_type, request)
+            return AsyncNemoStreamResponse(self._http, kwargs, model_type, request)
 
         raw = await self._http.request(request.method, url, content=request.content, headers=req_headers, params=params)
+        raise_for_status(raw)
         body = None
-        if raw.is_success and request.response_type is not None:
+        if request.response_type is not None:
             body = request.response_type.model_validate(raw.json())
         return NemoResponse(http_response=raw, body=body, request=request)

packages/nemo_platform_plugin/src/nemo_platform_plugin/client/endpoint.py

@@ -74,7 +74,7 @@ def _build_prepared_request(
         elif name == "body":
             if not isinstance(value, BaseModel):
                 raise TypeError(f"body must be a BaseModel instance, got {type(value).__name__}")
-            content = value.model_dump_json().encode()
+            content = value.model_dump_json(exclude_unset=True).encode()
             content_type = "application/json"
         elif name == "content":
             content = value

packages/nemo_platform_plugin/src/nemo_platform_plugin/client/errors.py

@@ -0,0 +1,125 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""HTTP error hierarchy for the NemoClient.
+
+Status-code-specific subclasses also inherit from the corresponding
+Stainless SDK exception so that existing ``except ConflictError``
+(imported from ``nemo_platform``) catches our exceptions too.
+
+TODO: Once all consumers import from ``nemo_platform_plugin.client.errors``,
+remove the Stainless base classes.
+"""
+
+from __future__ import annotations
+
+import httpx
+
+
+class NemoHTTPError(Exception):
+    """Raised on non-2xx HTTP responses.
+
+    Attributes:
+        http_response: The raw httpx response.
+        status_code: The HTTP status code.
+        detail: A human-readable error message extracted from the response
+            body (``{"detail": "..."}`` convention used by FastAPI / NeMo
+            Platform), or the raw response text as a fallback.
+        body: The parsed JSON response body, or None.
+    """
+
+    def __init__(self, http_response: httpx.Response) -> None:
+        self.http_response = http_response
+        self.status_code = http_response.status_code
+        self.detail = self._extract_detail(http_response)
+        self.body = self._extract_body(http_response)
+        # Call Exception.__init__ directly to avoid Stainless APIStatusError.__init__
+        # which expects different arguments.  Our subclasses inherit from both
+        # NemoHTTPError and the Stainless exception for isinstance() compatibility.
+        Exception.__init__(self, f"HTTP {self.status_code}: {self.detail}")
+
+    @staticmethod
+    def _extract_body(resp: httpx.Response) -> object | None:
+        try:
+            return resp.json()
+        except Exception:
+            return None
+
+    @staticmethod
+    def _extract_detail(resp: httpx.Response) -> str:
+        try:
+            body = resp.json()
+            if isinstance(body, dict) and isinstance(body.get("detail"), str):
+                return body["detail"]
+        except Exception:
+            pass
+        return resp.text
+
+
+# ---------------------------------------------------------------------------
+# Status-code-specific errors
+# ---------------------------------------------------------------------------
+
+
+def _stainless_base(name: str) -> type:
+    """Import a Stainless SDK exception by name, falling back to NemoHTTPError."""
+    try:
+        import nemo_platform._exceptions as exc
+
+        return getattr(exc, name)
+    except (ImportError, AttributeError):
+        return NemoHTTPError
+
+
+class BadRequestError(NemoHTTPError, _stainless_base("BadRequestError")):  # type: ignore[misc]
+    """HTTP 400"""
+
+
+class AuthenticationError(NemoHTTPError, _stainless_base("AuthenticationError")):  # type: ignore[misc]
+    """HTTP 401"""
+
+
+class PermissionDeniedError(NemoHTTPError, _stainless_base("PermissionDeniedError")):  # type: ignore[misc]
+    """HTTP 403"""
+
+
+class NotFoundError(NemoHTTPError, _stainless_base("NotFoundError")):  # type: ignore[misc]
+    """HTTP 404"""
+
+
+class ConflictError(NemoHTTPError, _stainless_base("ConflictError")):  # type: ignore[misc]
+    """HTTP 409"""
+
+
+class UnprocessableEntityError(NemoHTTPError, _stainless_base("UnprocessableEntityError")):  # type: ignore[misc]
+    """HTTP 422"""
+
+
+class RateLimitError(NemoHTTPError, _stainless_base("RateLimitError")):  # type: ignore[misc]
+    """HTTP 429"""
+
+
+class InternalServerError(NemoHTTPError, _stainless_base("InternalServerError")):  # type: ignore[misc]
+    """HTTP 500+"""
+
+
+_STATUS_CODE_TO_ERROR: dict[int, type[NemoHTTPError]] = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: UnprocessableEntityError,
+    429: RateLimitError,
+    500: InternalServerError,
+}
+
+
+def raise_for_status(http_response: httpx.Response) -> None:
+    """Raise status-code-specific NemoHTTPError subclass for non-2xx responses."""
+    if 200 <= http_response.status_code < 300:
+        return
+    error_cls = _STATUS_CODE_TO_ERROR.get(http_response.status_code, NemoHTTPError)
+    if error_cls is NemoHTTPError and http_response.status_code >= 500:
+        error_cls = InternalServerError
+    raise error_cls(http_response)