feat: add the models namespace to the existing client (#69)

Model operations get a namespace on the client integrators already
construct — client.models on both Comfy and AsyncComfy — instead of a
second client object, which would fork credential handling, base URL,
transport and timeout configuration.

The namespace holds the host client's transport itself rather than a copy
of its settings, so a change made on the client after construction (a
rotated key, a different timeout) applies through models with no
re-wiring. It exposes that shared configuration read-only as base_url and
timeout, backed by new read-only properties of the same names on both
comfy_low transports so the layer above does not have to reach into
private attributes.

Nothing is added to the top-level package: from comfy_sdk import Comfy
stays the only entry point and client.models is the whole surface. The
sync/async parity guard gains the new pair, and the README documents the
namespace.

Author: mattmillerai

README.md

@@ -254,6 +254,28 @@ with no API key of their own. On a self-hosted proxy it's the content endpoint
 backend and never downloads the bytes first. (`AsyncOutput` mirrors all of the
 above with `await`.)
 
+## The `models` namespace
+
+Model operations live in a namespace on the client you already constructed —
+`client.models` — rather than in a second client object:
+
+```python
+client = Comfy(api_key="comfyui-...")
+
+client.models.base_url   # the client's own base URL, where model requests go
+client.models.timeout    # the client's own HTTP timeout
+```
+
+The namespace is bound to that client's transport, so it uses the client's
+credentials, base URL, connection pool and timeout, and a configuration change
+made on the client afterwards applies through `models` as well — there is no
+second set of settings to keep in sync. `AsyncComfy` carries the same `models`
+namespace, and nothing extra is imported or constructed for it:
+`from comfy_sdk import Comfy` stays the only entry point.
+
+`base_url` and `timeout` are a read-only view of that shared configuration;
+model operations are added to this namespace as they land.
+
 ## Sync and async
 
 `Comfy` and `AsyncComfy` expose the identical surface — swap the import and

src/comfy_low/transport.py

@@ -203,6 +203,21 @@ def __init__(
         self._own_client = client is None
         self._client = client or httpx.Client(timeout=timeout, follow_redirects=True)
 
+    # -- configuration ----------------------------------------------------
+    # Read-only views of the settings this transport was built with, so a layer
+    # above (a ``comfy_sdk`` client namespace) can report the configuration it
+    # shares without reaching into private attributes. Both read through to the
+    # live objects, so a later change to either is reflected here.
+    @property
+    def base_url(self) -> str:
+        """Base URL every relative API path is resolved against."""
+        return self._p.base_url
+
+    @property
+    def timeout(self) -> httpx.Timeout:
+        """The httpx client's default timeout. A per-request ``timeout=`` still wins."""
+        return self._client.timeout
+
     # -- lifecycle --------------------------------------------------------
     def close(self) -> None:
         if self._own_client:
@@ -492,6 +507,17 @@ def __init__(
         self._own_client = client is None
         self._client = client or httpx.AsyncClient(timeout=timeout, follow_redirects=True)
 
+    # -- configuration (mirrors :class:`ComfyLow`) -------------------------
+    @property
+    def base_url(self) -> str:
+        """Base URL every relative API path is resolved against."""
+        return self._p.base_url
+
+    @property
+    def timeout(self) -> httpx.Timeout:
+        """The httpx client's default timeout. A per-request ``timeout=`` still wins."""
+        return self._client.timeout
+
     async def aclose(self) -> None:
         if self._own_client:
             await self._client.aclose()

src/comfy_sdk/client.py

@@ -1,7 +1,9 @@
 """The clients integrators import: :class:`Comfy` (sync) and :class:`AsyncComfy`.
 
 Both expose the same surface — ``assets`` / ``workflows`` / ``jobs`` constructor
-namespaces plus ``submit`` / ``run`` — over a shared sans-IO core. Only the
+namespaces, the ``models`` namespace, plus ``submit`` / ``run`` — over a shared
+sans-IO core. Every namespace is bound to the client's own transport, so they
+share its credentials, base URL, connection pool and timeout. Only the
 awaiting methods are duplicated; the rules (idempotency, 429 backoff, asset
 materialization, UI-format detection) live in ``_core`` and are called from both.
 
@@ -32,6 +34,7 @@
 from .assets import AssetFactory, AsyncAssetFactory
 from .exceptions import WorkflowFormatUi, to_sdk_error
 from .jobs import AsyncJob, AsyncJobFactory, Job, JobFactory
+from .models import AsyncModels, Models
 from .workflows import Workflow, WorkflowFactory
 
 # How long to keep retrying a full queue before giving up (seconds).
@@ -127,6 +130,9 @@ def __init__(
         self.assets = AssetFactory(self._low)
         self.workflows = WorkflowFactory()
         self.jobs = JobFactory(self._low)
+        #: ``client.models`` — the model namespace, sharing this client's
+        #: transport (credentials, base URL, connection pool, timeout).
+        self.models = Models(self._low)
 
     def close(self) -> None:
         """Release the underlying HTTP connection pool.
@@ -230,6 +236,8 @@ def __init__(
         self.assets = AsyncAssetFactory(self._low)
         self.workflows = WorkflowFactory()
         self.jobs = AsyncJobFactory(self._low)
+        #: Async counterpart of :attr:`Comfy.models`, on this client's transport.
+        self.models = AsyncModels(self._low)
 
     async def aclose(self) -> None:
         """Async :meth:`Comfy.close`. Prefer ``async with AsyncComfy(...)``."""

src/comfy_sdk/models.py

@@ -0,0 +1,60 @@
+"""The ``models`` namespace — ``client.models`` on an existing client.
+
+Reached from a client you already constructed (``Comfy().models`` /
+``AsyncComfy().models``) rather than built on its own, so it uses that client's
+credentials, base URL, transport and timeout: one connection pool, one
+credential, one place to configure both. A separate client object for model
+operations would fork all of that, which is what namespacing avoids.
+
+The namespace holds the host client's transport itself — not a copy of its
+settings — so a change made on the client after construction (a rotated key, a
+different timeout) is visible through ``models`` with no re-wiring. v1 is the
+namespace plus a read-only view of that shared configuration; model operations
+are added to this object as they land, never to a parallel client.
+
+Callers do not import anything for this: ``from comfy_sdk import Comfy`` stays
+the only entry point, and ``client.models`` is the whole surface.
+"""
+
+from __future__ import annotations
+
+import httpx
+
+from comfy_low.transport import AsyncComfyLow, ComfyLow
+
+
+class _ModelsBase:
+    """Read-only view of the configuration inherited from the host client."""
+
+    _low: ComfyLow | AsyncComfyLow
+
+    @property
+    def base_url(self) -> str:
+        """The host client's base URL — where model requests are sent."""
+        return self._low.base_url
+
+    @property
+    def timeout(self) -> httpx.Timeout:
+        """The host client's HTTP timeout, read live from its transport."""
+        return self._low.timeout
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(base_url={self.base_url!r})"
+
+
+class Models(_ModelsBase):
+    """``client.models`` on :class:`~comfy_sdk.client.Comfy`.
+
+    Constructed by the client; ``low`` is the client's own transport, which is
+    what makes the configuration shared rather than duplicated.
+    """
+
+    def __init__(self, low: ComfyLow) -> None:
+        self._low = low
+
+
+class AsyncModels(_ModelsBase):
+    """``client.models`` on :class:`~comfy_sdk.client.AsyncComfy` — mirrors :class:`Models`."""
+
+    def __init__(self, low: AsyncComfyLow) -> None:
+        self._low = low

tests/test_models_namespace.py

@@ -0,0 +1,106 @@
+"""``client.models`` — the model namespace on the existing client.
+
+What makes it a namespace rather than a second client object: it is reachable
+from a client you already constructed, and it reads that client's *live*
+configuration — credentials, base URL, transport, timeout — instead of a copy
+taken at construction. Both properties are asserted here, including a config
+change made on the client after construction being visible through ``models``.
+"""
+
+from __future__ import annotations
+
+import httpx
+
+import comfy_sdk
+from comfy_sdk import AsyncComfy, Comfy
+from comfy_sdk.models import AsyncModels, Models
+
+
+def test_models_is_reachable_from_a_constructed_client(server) -> None:
+    with Comfy() as client:
+        assert isinstance(client.models, Models)
+
+
+async def test_async_models_is_reachable_from_a_constructed_client(server) -> None:
+    async with AsyncComfy() as client:
+        assert isinstance(client.models, AsyncModels)
+
+
+def test_models_holds_the_host_clients_transport(server) -> None:
+    # Identity, not equality: the same transport object means the same
+    # connection pool, credential, base URL and timeout — nothing to keep in
+    # sync, and nothing a second client would have forked.
+    with Comfy() as client:
+        assert client.models._low is client._low
+
+
+async def test_async_models_holds_the_host_clients_transport(server) -> None:
+    async with AsyncComfy() as client:
+        assert client.models._low is client._low
+
+
+def test_models_reports_the_host_clients_base_url(server) -> None:
+    with Comfy() as client:
+        assert client.models.base_url == client._low.base_url == server.base_url
+
+
+async def test_async_models_reports_the_host_clients_base_url(server) -> None:
+    async with AsyncComfy() as client:
+        assert client.models.base_url == client._low.base_url == server.base_url
+
+
+def test_a_timeout_change_on_the_client_is_visible_through_models(server) -> None:
+    with Comfy(timeout=30.0) as client:
+        assert client.models.timeout.read == 30.0
+        # Changed on the client *after* construction: models must follow it,
+        # which a copied-config namespace would not.
+        client._low._client.timeout = httpx.Timeout(1.25)
+        assert client.models.timeout.read == 1.25
+
+
+async def test_a_timeout_change_on_the_async_client_is_visible_through_models(server) -> None:
+    async with AsyncComfy(timeout=30.0) as client:
+        assert client.models.timeout.read == 30.0
+        client._low._client.timeout = httpx.Timeout(1.25)
+        assert client.models.timeout.read == 1.25
+
+
+def test_models_sends_the_host_clients_credentials(server) -> None:
+    server.state.require_auth = True
+    with Comfy(api_key="k-first") as client:
+        # The transport a model request would go out on is the client's own,
+        # so it carries the client's bearer token to the client's base URL.
+        client.models._low.get_job("job_01")
+        assert server.state.last_auth_header == "Bearer k-first"
+
+        # And a credential rotated on the client is picked up through models.
+        client._low._p.api_key = "k-rotated"
+        client.models._low.get_job("job_01")
+        assert server.state.last_auth_header == "Bearer k-rotated"
+
+
+async def test_async_models_sends_the_host_clients_credentials(server) -> None:
+    server.state.require_auth = True
+    async with AsyncComfy(api_key="k-async") as client:
+        await client.models._low.get_job("job_01")
+        assert server.state.last_auth_header == "Bearer k-async"
+
+
+def test_two_clients_get_independent_namespaces(server) -> None:
+    with Comfy() as one, Comfy() as two:
+        assert one.models is not two.models
+        assert one.models._low is not two.models._low
+
+
+def test_models_repr_names_the_shared_base_url(server) -> None:
+    with Comfy() as client:
+        assert repr(client.models) == f"Models(base_url={server.base_url!r})"
+
+
+def test_the_namespace_adds_no_new_top_level_import_path() -> None:
+    # ``from comfy_sdk import Comfy`` stays the only path a caller needs:
+    # the namespace is reached as ``client.models``, so neither class is
+    # exported at the top level.
+    for name in ("Models", "AsyncModels"):
+        assert name not in comfy_sdk.__all__
+        assert not hasattr(comfy_sdk, name)

tests/test_sync_async_parity.py

@@ -1,4 +1,4 @@
-"""Sync/async public-surface parity across the 7 mirrored class pairs.
+"""Sync/async public-surface parity across the 8 mirrored class pairs.
 
 The README promises "swap the import and add ``await``" as the only
 difference; this asserts the public method names actually match. Regression
@@ -17,6 +17,7 @@
 from comfy_sdk.assets import Asset, AssetFactory, AsyncAsset, AsyncAssetFactory
 from comfy_sdk.client import AsyncComfy, Comfy
 from comfy_sdk.jobs import AsyncJob, AsyncJobFactory, Job, JobFactory
+from comfy_sdk.models import AsyncModels, Models
 from comfy_sdk.outputs import AsyncOutput, Output
 
 _PAIRS: list[tuple[str, type, type]] = [
@@ -26,6 +27,7 @@
     ("Job", Job, AsyncJob),
     ("JobFactory", JobFactory, AsyncJobFactory),
     ("Output", Output, AsyncOutput),
+    ("Models", Models, AsyncModels),
     ("ComfyLow", ComfyLow, AsyncComfyLow),
 ]