feat(models): add typed NemoClient models foundation (#993)

* feat(models): add typed NemoClient models foundation

Introduces the typed Models service client that the AIRCORE-876 consumer
migration will build on: request/response DTOs (types), PreparedRequest
endpoint builders (endpoints), and the sync/async ModelsClient surface
(client).

Purely additive: no existing code imports it yet, so it changes no runtime
behavior and carries zero risk to current consumers. Also carries the
method() descriptor fix that this client requires -- class-level attribute
access now resolves without invoking the wrapped callable, so
Mock(spec=ModelsClient) and other introspection no longer break -- plus a
response docstring note on distinguishing 202/204 deletes.

The consumer repoint, the packages/models resources rewrite, and the
vendored SDK sync land separately as the breaking, coupled steps. Covered
by endpoint-builder, client-surface, and descriptor tests.

Signed-off-by: Max Dubrinsky <mdubrinsky@nvidia.com>

* fix(models): async-mockable client, non-stale delete status, guarded provider id

Address review findings on the typed Models client foundation:

- method() class-level access returns a per-owning-class callable stub
  (async def for async clients, def for sync) instead of the raw
  descriptor, so unittest.mock classifies async endpoints as AsyncMock.
  Previously Mock(spec=AsyncModelsClient).create_model was a sync
  MagicMock and could not be awaited, and create_autospec yielded
  non-callable stubs -- defeating the typed async client's purpose.
- delete_deployment appends a DELETING entry to status_history so the
  client (which reads status_history[-1] as current) no longer sees a
  stale status after a delete request.
- get_provider_route_openai_url_for_deployment guards a model_provider_id
  that lacks the workspace/ prefix with a clear ValueError instead of an
  opaque unpack crash.

Adds regression tests for all three.

Signed-off-by: Max Dubrinsky <mdubrinsky@nvidia.com>

* test(models): use top-level imports instead of dynamic __import__

Replace two call-time __import__("...types", fromlist=[...]) lookups in
the endpoint tests with normal names added to the existing top-level
import block (CreateModelAdapterRequest, UpdateModelDeploymentConfigRequest).
Addresses a CodeRabbit maintainability nit on PR #993.

Signed-off-by: Max Dubrinsky <mdubrinsky@nvidia.com>

* fix(models): ruff-format client.py and suppress class-level ty errors

CI Lint all caught two issues from the earlier commits:

- ruff format collapses the malformed-model_provider_id message onto one
  line in client.py.
- ty reports call-non-callable / invalid-argument-type on the new
  class-level-access tests: EndpointMethod.__get__(obj=None) is typed as
  the descriptor because the overload cannot distinguish the sync vs async
  owning class, so ty cannot see the callable stub returned at runtime.
  The three tests deliberately exercise that runtime stub, so they carry
  targeted ty: ignore suppressions with an explanatory note.

Signed-off-by: Max Dubrinsky <mdubrinsky@nvidia.com>

---------

Signed-off-by: Max Dubrinsky <mdubrinsky@nvidia.com>

Author: maxdubrinsky

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

@@ -71,16 +71,92 @@ class EndpointMethod(Generic[P, SyncReturnT, AsyncReturnT]):
     the response type that ``send()`` returns for each endpoint marker.
     """
 
+    # Copied from the endpoint in __init__ so help() and autodoc describe the
+    # endpoint. Declared here so the descriptor's introspection surface is part of
+    # its type rather than something callers have to discover at runtime.
+    __wrapped__: Callable[P, PreparedRequest]
+    __name__: str
+    __qualname__: str
+    __doc__: str | None
+    __module__: str
+
     def __init__(self, endpoint_fn: Callable[P, PreparedRequest]) -> None:
         self._endpoint_fn = endpoint_fn
+        # Per-owning-class callable stubs handed out on *class*-level access, so
+        # unittest.mock / inspect can classify each endpoint (sync vs coroutine)
+        # and autospec it as callable. Keyed and cached by objtype so repeated
+        # class access is stable. See __get__.
+        self._class_stubs: dict[type | None, Callable[..., object]] = {}
+        # Carry the endpoint's name, docstring, and annotations onto the descriptor
+        # so help() and autodoc describe the endpoint rather than the descriptor.
+        # Set directly rather than via functools.update_wrapper, which expects a
+        # callable wrapper; a descriptor is not one, and which would also copy
+        # __dict__ and with it the endpoint's __isabstractmethod__ marker.
+        #
+        # inspect.signature(SomeClient.method) works because class-level access
+        # returns a functools.wraps'd stub (see __get__), not the raw descriptor.
+        self.__wrapped__ = endpoint_fn
+        for attr in functools.WRAPPER_ASSIGNMENTS:
+            try:
+                setattr(self, attr, getattr(endpoint_fn, attr))
+            except AttributeError:
+                pass
+
+    def _class_level_stub(self, objtype: type | None) -> Callable[..., object]:
+        """Callable stub returned on class-level access, matched to ``objtype``.
+
+        ``unittest.mock`` (both ``Mock(spec=...)`` and ``create_autospec``) reads
+        each attribute off the *class* and classifies it with ``callable()`` and
+        ``asyncio.iscoroutinefunction()``. A bare descriptor is neither callable
+        nor a coroutine function, so every endpoint on an async client would be
+        mocked as a sync ``MagicMock`` and could not be awaited. This hands back a
+        real function -- ``async def`` for async clients, ``def`` for sync -- that
+        wraps the endpoint (so ``inspect.signature`` works and autospec validates
+        call signatures), but refuses to run unbound: endpoints only mean anything
+        against a client instance.
+        """
+        cached = self._class_stubs.get(objtype)
+        if cached is not None:
+            return cached
+        is_async = objtype is not None and issubclass(objtype, AsyncNemoClient)
+        if is_async:
+
+            @functools.wraps(self._endpoint_fn)
+            async def stub(*args: object, **kwargs: object) -> object:
+                raise TypeError(f"{self.__name__} must be called on a client instance, not the class")
+        else:
+
+            @functools.wraps(self._endpoint_fn)
+            def stub(*args: object, **kwargs: object) -> object:
+                raise TypeError(f"{self.__name__} must be called on a client instance, not the class")
+
+        # __isabstractmethod__ rides along in the endpoint's __dict__ via wraps;
+        # drop it so the stub is never mistaken for an abstract member.
+        stub.__dict__.pop("__isabstractmethod__", None)
+        self._class_stubs[objtype] = stub
+        return stub
 
+    @property
+    def endpoint(self) -> Callable[P, PreparedRequest]:
+        """The endpoint function this descriptor binds."""
+        return self._endpoint_fn
+
+    @overload
+    def __get__(self, obj: None, objtype: type | None = None) -> EndpointMethod[P, SyncReturnT, AsyncReturnT]: ...
     @overload
     def __get__(self, obj: NemoClient, objtype: type | None = None) -> Callable[P, SyncReturnT]: ...
     @overload
     def __get__(self, obj: AsyncNemoClient, objtype: type | None = None) -> Callable[P, Awaitable[AsyncReturnT]]: ...
 
     def __get__(self, obj: NemoClient | AsyncNemoClient | None, objtype: type | None = None) -> object:
-        assert obj is not None
+        if obj is None:
+            # Class-level access. Anything that inspects a client class rather than
+            # an instance -- Mock(spec=...), autospec, inspect, help(), autodoc --
+            # lands here. Hand back a callable stub matched to the owning client
+            # type so mock classifies sync vs async correctly and autospec sees a
+            # callable. The raw descriptor is still reachable via
+            # inspect.getattr_static, which never invokes __get__.
+            return self._class_level_stub(objtype)
         if isinstance(obj, AsyncNemoClient):
 
             @functools.wraps(self._endpoint_fn)

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

@@ -79,6 +79,10 @@ class NemoResponse(Generic[ResponseT]):
         resp.http_response    # full httpx.Response
 
         user = resp.data()    # raises on non-2xx, otherwise returns body
+
+    When several 2xx codes share one typed body (e.g. a delete that returns 202
+    Accepted for async teardown or 204 No Content when already gone, both typed
+    ``None``), inspect ``resp.http_response.status_code`` to tell them apart.
     """
 
     http_response: httpx.Response