Update naming

Author: hinthornw

libs/sdk-py/langgraph_sdk/client.py

@@ -1067,7 +1067,7 @@ async def search(
         sort_by: AssistantSortBy | None = None,
         sort_order: SortOrder | None = None,
         select: list[AssistantSelectField] | None = None,
-        include_pagination: Literal[True],
+        response_format: Literal["object"],
         headers: Mapping[str, str] | None = None,
         params: QueryParamTypes | None = None,
     ) -> AssistantsSearchResponse: ...
@@ -1084,7 +1084,7 @@ async def search(
         sort_by: AssistantSortBy | None = None,
         sort_order: SortOrder | None = None,
         select: list[AssistantSelectField] | None = None,
-        include_pagination: Literal[False] = False,
+        response_format: Literal["array"] = "array",
         headers: Mapping[str, str] | None = None,
         params: QueryParamTypes | None = None,
     ) -> list[Assistant]: ...
@@ -1100,7 +1100,7 @@ async def search(
         sort_by: AssistantSortBy | None = None,
         sort_order: SortOrder | None = None,
         select: list[AssistantSelectField] | None = None,
-        include_pagination: bool = False,
+        response_format: Literal["array", "object"] = "array",
         headers: Mapping[str, str] | None = None,
         params: QueryParamTypes | None = None,
     ) -> AssistantsSearchResponse | list[Assistant]:
@@ -1117,13 +1117,16 @@ async def search(
             sort_by: The field to sort by.
             sort_order: The order to sort by.
             select: Specific assistant fields to include in the response.
-            include_pagination: When True, include the ``X-Pagination-Next`` header in the return value.
+            response_format: Controls the response shape. Use ``"array"`` (default)
+                to return a bare list of assistants, or ``"object"`` to return
+                a mapping containing assistants plus pagination metadata.
             headers: Optional custom headers to include with the request.
             params: Optional query parameters to include with the request.
 
         Returns:
-            A list of assistants or, when ``include_pagination`` is True, a mapping
-            with the assistants and the next pagination cursor.
+            A list of assistants (when ``response_format=\"array\"``) or a mapping
+            with the assistants and the next pagination cursor (when
+            ``response_format=\"object\"``).
 
         ???+ example "Example Usage"
 
@@ -1137,15 +1140,16 @@ async def search(
             )
             ```
 
-        ???+ example "Include pagination metadata"
+        ???+ example "Return object with pagination metadata"
 
             ```python
             client = get_client(url="http://localhost:2024")
-            result = await client.assistants.search(include_pagination=True)
+            result = await client.assistants.search(response_format="object")
             next_cursor = result["next"]
             assistants = result["assistants"]
             ```
         """
+        effective_format: Literal["array", "object"] = response_format
         payload: dict[str, Any] = {
             "limit": limit,
             "offset": offset,
@@ -1175,10 +1179,12 @@ def capture_pagination(response: httpx.Response) -> None:
                 json=payload,
                 headers=headers,
                 params=params,
-                on_response=capture_pagination if include_pagination else None,
+                on_response=capture_pagination
+                if effective_format == "object"
+                else None,
             ),
         )
-        if include_pagination:
+        if effective_format == "object":
             return {"assistants": assistants, "next": next_cursor}
         return assistants
 
@@ -4401,7 +4407,7 @@ def search(
         sort_by: AssistantSortBy | None = None,
         sort_order: SortOrder | None = None,
         select: list[AssistantSelectField] | None = None,
-        include_pagination: Literal[True],
+        response_format: Literal["object"],
         headers: Mapping[str, str] | None = None,
         params: QueryParamTypes | None = None,
     ) -> AssistantsSearchResponse: ...
@@ -4418,7 +4424,7 @@ def search(
         sort_by: AssistantSortBy | None = None,
         sort_order: SortOrder | None = None,
         select: list[AssistantSelectField] | None = None,
-        include_pagination: Literal[False] = False,
+        response_format: Literal["array"] = "array",
         headers: Mapping[str, str] | None = None,
         params: QueryParamTypes | None = None,
     ) -> list[Assistant]: ...
@@ -4434,7 +4440,7 @@ def search(
         sort_by: AssistantSortBy | None = None,
         sort_order: SortOrder | None = None,
         select: list[AssistantSelectField] | None = None,
-        include_pagination: bool = False,
+        response_format: Literal["array", "object"] = "array",
         headers: Mapping[str, str] | None = None,
         params: QueryParamTypes | None = None,
     ) -> AssistantsSearchResponse | list[Assistant]:
@@ -4451,12 +4457,15 @@ def search(
             sort_by: The field to sort by.
             sort_order: The order to sort by.
             select: Specific assistant fields to include in the response.
-            include_pagination: When True, include the ``X-Pagination-Next`` header in the return value.
+            response_format: Controls the response shape. Use ``"array"`` (default)
+                to return a bare list of assistants, or ``"object"`` to return
+                a mapping containing assistants plus pagination metadata.
             headers: Optional custom headers to include with the request.
 
         Returns:
-            A list of assistants or, when ``include_pagination`` is True, a mapping
-            with the assistants and the next pagination cursor.
+            A list of assistants (when ``response_format=\"array\"``) or a mapping
+            with the assistants and the next pagination cursor (when
+            ``response_format=\"object\"``).
 
         ???+ example "Example Usage"
 
@@ -4470,15 +4479,16 @@ def search(
             )
             ```
 
-        ???+ example "Include pagination metadata"
+        ???+ example "Return object with pagination metadata"
 
             ```python
             client = get_sync_client(url="http://localhost:2024")
-            result = client.assistants.search(include_pagination=True)
+            result = client.assistants.search(response_format="object")
             next_cursor = result["next"]
             assistants = result["assistants"]
             ```
         """
+        effective_format: Literal["array", "object"] = response_format
         payload: dict[str, Any] = {
             "limit": limit,
             "offset": offset,
@@ -4508,10 +4518,12 @@ def capture_pagination(response: httpx.Response) -> None:
                 json=payload,
                 headers=headers,
                 params=params,
-                on_response=capture_pagination if include_pagination else None,
+                on_response=capture_pagination
+                if effective_format == "object"
+                else None,
             ),
         )
-        if include_pagination:
+        if effective_format == "object":
             return {"assistants": assistants, "next": next_cursor}
         return assistants
 

libs/sdk-py/tests/test_assistants_client.py

@@ -47,7 +47,7 @@ async def handler(request: httpx.Request) -> httpx.Response:
 
 
 @pytest.mark.asyncio
-async def test_assistants_search_can_include_pagination_metadata():
+async def test_assistants_search_can_return_object_with_pagination_metadata():
     assistant = _assistant_payload()
 
     async def handler(request: httpx.Request) -> httpx.Response:
@@ -65,12 +65,12 @@ async def handler(request: httpx.Request) -> httpx.Response:
     ) as client:
         http_client = HttpClient(client)
         assistants_client = AssistantsClient(http_client)
-        result = await assistants_client.search(include_pagination=True)
+        result = await assistants_client.search(response_format="object")
 
     assert result == {"assistants": [assistant], "next": "42"}
 
 
-def test_sync_assistants_search_can_include_pagination_metadata():
+def test_sync_assistants_search_can_return_object_with_pagination_metadata():
     assistant = _assistant_payload()
 
     def handler(request: httpx.Request) -> httpx.Response:
@@ -86,6 +86,6 @@ def handler(request: httpx.Request) -> httpx.Response:
     with httpx.Client(transport=transport, base_url="https://example.com") as client:
         http_client = SyncHttpClient(client)
         assistants_client = SyncAssistantsClient(http_client)
-        result = assistants_client.search(include_pagination=True)
+        result = assistants_client.search(response_format="object")
 
     assert result == {"assistants": [assistant], "next": "84"}