fix: document transport param and annotate private attr chains in tests

Address Greptile P2 review comments on PR #460:
- Add docstring entry for the new `transport` parameter in
  `create_retry_transport` explaining accepted types and None default
- Add inline comments in pool-size regression tests explaining the
  private attribute chain (_sync/_async_transport → _pool → _max_connections)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Signed-off-by: Przemysław <przemekboruta@interia.pl>

Author: przemekboruta

packages/data-designer-engine/src/data_designer/engine/models/clients/retry.py

@@ -56,6 +56,12 @@ def create_retry_transport(
             AIMD feedback loop.  When ``False`` (used by the sync engine, which has
             no salvage queue), 429 is kept in the retry list so the transport layer
             retries it transparently.
+        transport: Optional pre-configured inner transport to pass directly to
+            ``RetryTransport``.  Pass ``httpx.HTTPTransport`` for sync clients or
+            ``httpx.AsyncHTTPTransport`` for async clients — typically with a custom
+            ``limits=`` — so that the connection pool is sized correctly.  When
+            ``None`` (default), ``RetryTransport`` creates its own default pools for
+            both sync and async requests.
     """
     cfg = config or RetryConfig()
     status_codes = cfg.retryable_status_codes

packages/data-designer-engine/tests/engine/models/clients/test_native_http_clients.py

@@ -308,6 +308,10 @@ def test_sync_client_pool_size_respects_max_parallel_requests() -> None:
     with patch(_SYNC_CLIENT_PATCH):
         client._get_sync_client()
 
+    # Attribute chain explained:
+    #   RetryTransport._sync_transport  → the httpx.HTTPTransport we injected
+    #   HTTPTransport._pool             → the underlying httpcore.ConnectionPool
+    #   ConnectionPool._max_connections → the hard cap configured via Limits
     # pool_max = max(32, 2 * 300) = 600
     assert client._transport._sync_transport._pool._max_connections == 600
 
@@ -325,5 +329,9 @@ async def test_async_client_pool_size_respects_max_parallel_requests() -> None:
     with patch(_ASYNC_CLIENT_PATCH):
         client._get_async_client()
 
+    # Attribute chain explained:
+    #   RetryTransport._async_transport → the httpx.AsyncHTTPTransport we injected
+    #   AsyncHTTPTransport._pool        → the underlying httpcore.AsyncConnectionPool
+    #   AsyncConnectionPool._max_connections → the hard cap configured via Limits
     # pool_max = max(32, 2 * 300) = 600
     assert client._transport._async_transport._pool._max_connections == 600