feat: Address Stainless diagnostics

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 14
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/warp-bnavetta%2Fwarp-api-a931490557d2c27bcec6b9d7cb0502913f6a3969a5907c810a3c2073ca2ca9e0.yml
-openapi_spec_hash: 632bc51224846da7edc3996983d35ff3
-config_hash: e894152aaebba5a2e65e27efaf2712e2
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/warp-bnavetta%2Fwarp-api-d9e0c6bea8d4c2414ec2bcd18c2e748b43110079c81906aa6c79b350b408f96b.yml
+openapi_spec_hash: 598927b816525740620b414c6d147184
+config_hash: 1888db8b2f33dc16874aea51a90e78f7

README.md

@@ -170,6 +170,69 @@ Nested request parameters are [TypedDicts](https://docs.python.org/3/library/typ
 
 Typed requests and responses provide autocomplete and documentation within your editor. If you would like to see type errors in VS Code to help catch bugs earlier, set `python.analysis.typeCheckingMode` to `basic`.
 
+## Pagination
+
+List methods in the Oz API API are paginated.
+
+This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:
+
+```python
+from oz_agent_sdk import OzAPI
+
+client = OzAPI()
+
+all_runs = []
+# Automatically fetches more pages as needed.
+for run in client.agent.runs.list():
+    # Do something with run here
+    all_runs.append(run)
+print(all_runs)
+```
+
+Or, asynchronously:
+
+```python
+import asyncio
+from oz_agent_sdk import AsyncOzAPI
+
+client = AsyncOzAPI()
+
+
+async def main() -> None:
+    all_runs = []
+    # Iterate through items across all pages, issuing requests as needed.
+    async for run in client.agent.runs.list():
+        all_runs.append(run)
+    print(all_runs)
+
+
+asyncio.run(main())
+```
+
+Alternatively, you can use the `.has_next_page()`, `.next_page_info()`, or `.get_next_page()` methods for more granular control working with pages:
+
+```python
+first_page = await client.agent.runs.list()
+if first_page.has_next_page():
+    print(f"will fetch next page using these details: {first_page.next_page_info()}")
+    next_page = await first_page.get_next_page()
+    print(f"number of items we just fetched: {len(next_page.runs)}")
+
+# Remove `await` for non-async usage.
+```
+
+Or just work directly with the returned data:
+
+```python
+first_page = await client.agent.runs.list()
+
+print(f"next page cursor: {first_page.page_info.next_cursor}")  # => "next page cursor: ..."
+for run in first_page.runs:
+    print(run.run_id)
+
+# Remove `await` for non-async usage.
+```
+
 ## Nested params
 
 Nested parameters are dictionaries, typed using `TypedDict`, for example:

api.md

@@ -6,9 +6,11 @@ Types:
 from oz_agent_sdk.types import (
     AgentSkill,
     AmbientAgentConfig,
+    AwsProviderConfig,
     CloudEnvironmentConfig,
     Error,
     ErrorCode,
+    GcpProviderConfig,
     McpServerConfig,
     Scope,
     UserProfile,
@@ -22,7 +24,7 @@ Methods:
 
 - <code title="get /agent">client.agent.<a href="./src/oz_agent_sdk/resources/agent/agent.py">list</a>(\*\*<a href="src/oz_agent_sdk/types/agent_list_params.py">params</a>) -> <a href="./src/oz_agent_sdk/types/agent_list_response.py">AgentListResponse</a></code>
 - <code title="get /agent/artifacts/{artifactUid}">client.agent.<a href="./src/oz_agent_sdk/resources/agent/agent.py">get_artifact</a>(artifact_uid) -> <a href="./src/oz_agent_sdk/types/agent_get_artifact_response.py">AgentGetArtifactResponse</a></code>
-- <code title="post /agent/run">client.agent.<a href="./src/oz_agent_sdk/resources/agent/agent.py">run</a>(\*\*<a href="src/oz_agent_sdk/types/agent_run_params.py">params</a>) -> <a href="./src/oz_agent_sdk/types/agent_run_response.py">AgentRunResponse</a></code>
+- <code title="post /agent/runs">client.agent.<a href="./src/oz_agent_sdk/resources/agent/agent.py">run</a>(\*\*<a href="src/oz_agent_sdk/types/agent_run_params.py">params</a>) -> <a href="./src/oz_agent_sdk/types/agent_run_response.py">AgentRunResponse</a></code>
 
 ## Runs
 
@@ -34,15 +36,14 @@ from oz_agent_sdk.types.agent import (
     RunItem,
     RunSourceType,
     RunState,
-    RunListResponse,
     RunCancelResponse,
 )
 ```
 
 Methods:
 
 - <code title="get /agent/runs/{runId}">client.agent.runs.<a href="./src/oz_agent_sdk/resources/agent/runs.py">retrieve</a>(run_id) -> <a href="./src/oz_agent_sdk/types/agent/run_item.py">RunItem</a></code>
-- <code title="get /agent/runs">client.agent.runs.<a href="./src/oz_agent_sdk/resources/agent/runs.py">list</a>(\*\*<a href="src/oz_agent_sdk/types/agent/run_list_params.py">params</a>) -> <a href="./src/oz_agent_sdk/types/agent/run_list_response.py">RunListResponse</a></code>
+- <code title="get /agent/runs">client.agent.runs.<a href="./src/oz_agent_sdk/resources/agent/runs.py">list</a>(\*\*<a href="src/oz_agent_sdk/types/agent/run_list_params.py">params</a>) -> <a href="./src/oz_agent_sdk/types/agent/run_item.py">SyncRunsCursorPage[RunItem]</a></code>
 - <code title="post /agent/runs/{runId}/cancel">client.agent.runs.<a href="./src/oz_agent_sdk/resources/agent/runs.py">cancel</a>(run_id) -> str</code>
 
 ## Schedules

src/oz_agent_sdk/_base_client.py

@@ -63,7 +63,7 @@
 )
 from ._utils import is_dict, is_list, asyncify, is_given, lru_cache, is_mapping
 from ._compat import PYDANTIC_V1, model_copy, model_dump
-from ._models import GenericModel, FinalRequestOptions, validate_type, construct_type
+from ._models import GenericModel, SecurityOptions, FinalRequestOptions, validate_type, construct_type
 from ._response import (
     APIResponse,
     BaseAPIResponse,
@@ -432,9 +432,27 @@ def _make_status_error(
     ) -> _exceptions.APIStatusError:
         raise NotImplementedError()
 
+    def _auth_headers(
+        self,
+        security: SecurityOptions,  # noqa: ARG002
+    ) -> dict[str, str]:
+        return {}
+
+    def _auth_query(
+        self,
+        security: SecurityOptions,  # noqa: ARG002
+    ) -> dict[str, str]:
+        return {}
+
+    def _custom_auth(
+        self,
+        security: SecurityOptions,  # noqa: ARG002
+    ) -> httpx.Auth | None:
+        return None
+
     def _build_headers(self, options: FinalRequestOptions, *, retries_taken: int = 0) -> httpx.Headers:
         custom_headers = options.headers or {}
-        headers_dict = _merge_mappings(self.default_headers, custom_headers)
+        headers_dict = _merge_mappings({**self._auth_headers(options.security), **self.default_headers}, custom_headers)
         self._validate_headers(headers_dict, custom_headers)
 
         # headers are case-insensitive while dictionaries are not.
@@ -506,7 +524,7 @@ def _build_request(
                 raise RuntimeError(f"Unexpected JSON data type, {type(json_data)}, cannot merge with `extra_body`")
 
         headers = self._build_headers(options, retries_taken=retries_taken)
-        params = _merge_mappings(self.default_query, options.params)
+        params = _merge_mappings({**self._auth_query(options.security), **self.default_query}, options.params)
         content_type = headers.get("Content-Type")
         files = options.files
 
@@ -671,7 +689,6 @@ def default_headers(self) -> dict[str, str | Omit]:
             "Content-Type": "application/json",
             "User-Agent": self.user_agent,
             **self.platform_headers(),
-            **self.auth_headers,
             **self._custom_headers,
         }
 
@@ -990,8 +1007,9 @@ def request(
             self._prepare_request(request)
 
             kwargs: HttpxSendArgs = {}
-            if self.custom_auth is not None:
-                kwargs["auth"] = self.custom_auth
+            custom_auth = self._custom_auth(options.security)
+            if custom_auth is not None:
+                kwargs["auth"] = custom_auth
 
             if options.follow_redirects is not None:
                 kwargs["follow_redirects"] = options.follow_redirects
@@ -1952,6 +1970,7 @@ def make_request_options(
     idempotency_key: str | None = None,
     timeout: float | httpx.Timeout | None | NotGiven = not_given,
     post_parser: PostParser | NotGiven = not_given,
+    security: SecurityOptions | None = None,
 ) -> RequestOptions:
     """Create a dict of type RequestOptions without keys of NotGiven values."""
     options: RequestOptions = {}
@@ -1977,6 +1996,9 @@ def make_request_options(
         # internal
         options["post_parser"] = post_parser  # type: ignore
 
+    if security is not None:
+        options["security"] = security
+
     return options
 
 

src/oz_agent_sdk/_client.py

@@ -21,6 +21,7 @@
 )
 from ._utils import is_given, get_async_library
 from ._compat import cached_property
+from ._models import SecurityOptions
 from ._version import __version__
 from ._streaming import Stream as Stream, AsyncStream as AsyncStream
 from ._exceptions import OzAPIError, APIStatusError
@@ -112,9 +113,14 @@ def with_streaming_response(self) -> OzAPIWithStreamedResponse:
     def qs(self) -> Querystring:
         return Querystring(array_format="repeat")
 
-    @property
     @override
-    def auth_headers(self) -> dict[str, str]:
+    def _auth_headers(self, security: SecurityOptions) -> dict[str, str]:
+        return {
+            **(self._bearer_auth if security.get("bearer_auth", False) else {}),
+        }
+
+    @property
+    def _bearer_auth(self) -> dict[str, str]:
         api_key = self.api_key
         return {"Authorization": f"Bearer {api_key}"}
 
@@ -287,9 +293,14 @@ def with_streaming_response(self) -> AsyncOzAPIWithStreamedResponse:
     def qs(self) -> Querystring:
         return Querystring(array_format="repeat")
 
-    @property
     @override
-    def auth_headers(self) -> dict[str, str]:
+    def _auth_headers(self, security: SecurityOptions) -> dict[str, str]:
+        return {
+            **(self._bearer_auth if security.get("bearer_auth", False) else {}),
+        }
+
+    @property
+    def _bearer_auth(self) -> dict[str, str]:
         api_key = self.api_key
         return {"Authorization": f"Bearer {api_key}"}
 

src/oz_agent_sdk/_models.py

@@ -791,6 +791,10 @@ def _create_pydantic_model(type_: _T) -> Type[RootModel[_T]]:
         return RootModel[type_]  # type: ignore
 
 
+class SecurityOptions(TypedDict, total=False):
+    bearer_auth: bool
+
+
 class FinalRequestOptionsInput(TypedDict, total=False):
     method: Required[str]
     url: Required[str]
@@ -804,6 +808,7 @@ class FinalRequestOptionsInput(TypedDict, total=False):
     json_data: Body
     extra_json: AnyMapping
     follow_redirects: bool
+    security: SecurityOptions
 
 
 @final
@@ -818,6 +823,7 @@ class FinalRequestOptions(pydantic.BaseModel):
     idempotency_key: Union[str, None] = None
     post_parser: Union[Callable[[Any], Any], NotGiven] = NotGiven()
     follow_redirects: Union[bool, None] = None
+    security: SecurityOptions = {"bearer_auth": True}
 
     content: Union[bytes, bytearray, IO[bytes], Iterable[bytes], AsyncIterable[bytes], None] = None
     # It should be noted that we cannot use `json` here as that would override

src/oz_agent_sdk/_types.py

@@ -36,7 +36,7 @@
 from httpx import URL, Proxy, Timeout, Response, BaseTransport, AsyncBaseTransport
 
 if TYPE_CHECKING:
-    from ._models import BaseModel
+    from ._models import BaseModel, SecurityOptions
     from ._response import APIResponse, AsyncAPIResponse
 
 Transport = BaseTransport
@@ -121,6 +121,7 @@ class RequestOptions(TypedDict, total=False):
     extra_json: AnyMapping
     idempotency_key: str
     follow_redirects: bool
+    security: SecurityOptions
 
 
 # Sentinel class used until PEP 0661 is accepted

src/oz_agent_sdk/pagination.py

@@ -0,0 +1,85 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import List, Generic, TypeVar, Optional
+from typing_extensions import override
+
+from ._models import BaseModel
+from ._base_client import BasePage, PageInfo, BaseSyncPage, BaseAsyncPage
+
+__all__ = ["RunsCursorPagePageInfo", "SyncRunsCursorPage", "AsyncRunsCursorPage"]
+
+_T = TypeVar("_T")
+
+
+class RunsCursorPagePageInfo(BaseModel):
+    has_next_page: Optional[bool] = None
+
+    next_cursor: Optional[str] = None
+
+
+class SyncRunsCursorPage(BaseSyncPage[_T], BasePage[_T], Generic[_T]):
+    runs: List[_T]
+    page_info: Optional[RunsCursorPagePageInfo] = None
+
+    @override
+    def _get_page_items(self) -> List[_T]:
+        runs = self.runs
+        if not runs:
+            return []
+        return runs
+
+    @override
+    def has_next_page(self) -> bool:
+        has_next_page = None
+        if self.page_info is not None:
+            if self.page_info.has_next_page is not None:
+                has_next_page = self.page_info.has_next_page
+        if has_next_page is not None and has_next_page is False:
+            return False
+
+        return super().has_next_page()
+
+    @override
+    def next_page_info(self) -> Optional[PageInfo]:
+        next_cursor = None
+        if self.page_info is not None:
+            if self.page_info.next_cursor is not None:
+                next_cursor = self.page_info.next_cursor
+        if not next_cursor:
+            return None
+
+        return PageInfo(params={"cursor": next_cursor})
+
+
+class AsyncRunsCursorPage(BaseAsyncPage[_T], BasePage[_T], Generic[_T]):
+    runs: List[_T]
+    page_info: Optional[RunsCursorPagePageInfo] = None
+
+    @override
+    def _get_page_items(self) -> List[_T]:
+        runs = self.runs
+        if not runs:
+            return []
+        return runs
+
+    @override
+    def has_next_page(self) -> bool:
+        has_next_page = None
+        if self.page_info is not None:
+            if self.page_info.has_next_page is not None:
+                has_next_page = self.page_info.has_next_page
+        if has_next_page is not None and has_next_page is False:
+            return False
+
+        return super().has_next_page()
+
+    @override
+    def next_page_info(self) -> Optional[PageInfo]:
+        next_cursor = None
+        if self.page_info is not None:
+            if self.page_info.next_cursor is not None:
+                next_cursor = self.page_info.next_cursor
+        if not next_cursor:
+            return None
+
+        return PageInfo(params={"cursor": next_cursor})