feat(api): update via SDK Studio

Author: stainless-app[bot]

.stats.yml

@@ -1,2 +1,2 @@
-configured_endpoints: 30
+configured_endpoints: 33
 openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/contextual-ai%2Fsunrise-017875f5f67473ff4fe764239419149714a7941e4e670101078926b06414ea8d.yml

CONTRIBUTING.md

@@ -37,7 +37,7 @@ $ pip install -r requirements-dev.lock
 
 Most of the SDK is generated code. Modifications to code will be persisted between generations, but may
 result in merge conflicts between manual patches and changes from the generator. The generator will never
-modify the contents of the `src/contextual/lib/` and `examples/` directories.
+modify the contents of the `src/contextual_sdk/lib/` and `examples/` directories.
 
 ## Adding and running examples
 

README.md

@@ -1,6 +1,6 @@
 # Contextual AI Python API library
 
-[![PyPI version](https://img.shields.io/pypi/v/contextual.svg)](https://pypi.org/project/contextual/)
+[![PyPI version](https://img.shields.io/pypi/v/contextual-sdk.svg)](https://pypi.org/project/contextual-sdk/)
 
 The Contextual AI Python library provides convenient access to the Contextual AI REST API from any Python 3.8+
 application. The library includes type definitions for all request params and response fields,
@@ -20,15 +20,15 @@ pip install git+ssh://git@github.com/stainless-sdks/sunrise-python.git
 ```
 
 > [!NOTE]
-> Once this package is [published to PyPI](https://app.stainlessapi.com/docs/guides/publish), this will become: `pip install --pre contextual`
+> Once this package is [published to PyPI](https://app.stainlessapi.com/docs/guides/publish), this will become: `pip install --pre contextual-sdk`
 
 ## Usage
 
 The full API of this library can be found in [api.md](api.md).
 
 ```python
 import os
-from contextual import ContextualAI
+from contextual_sdk import ContextualAI
 
 client = ContextualAI(
     api_key=os.environ.get("CONTEXTUAL_API_KEY"),  # This is the default and can be omitted
@@ -52,7 +52,7 @@ Simply import `AsyncContextualAI` instead of `ContextualAI` and use `await` with
 ```python
 import os
 import asyncio
-from contextual import AsyncContextualAI
+from contextual_sdk import AsyncContextualAI
 
 client = AsyncContextualAI(
     api_key=os.environ.get("CONTEXTUAL_API_KEY"),  # This is the default and can be omitted
@@ -80,31 +80,94 @@ 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 Contextual AI 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 contextual_sdk import ContextualAI
+
+client = ContextualAI()
+
+all_datastores = []
+# Automatically fetches more pages as needed.
+for datastore in client.datastores.list():
+    # Do something with datastore here
+    all_datastores.append(datastore)
+print(all_datastores)
+```
+
+Or, asynchronously:
+
+```python
+import asyncio
+from contextual_sdk import AsyncContextualAI
+
+client = AsyncContextualAI()
+
+
+async def main() -> None:
+    all_datastores = []
+    # Iterate through items across all pages, issuing requests as needed.
+    async for datastore in client.datastores.list():
+        all_datastores.append(datastore)
+    print(all_datastores)
+
+
+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.datastores.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.datastores)}")
+
+# Remove `await` for non-async usage.
+```
+
+Or just work directly with the returned data:
+
+```python
+first_page = await client.datastores.list()
+
+print(f"next page cursor: {first_page.next_cursor}")  # => "next page cursor: ..."
+for datastore in first_page.datastores:
+    print(datastore.id)
+
+# Remove `await` for non-async usage.
+```
+
 ## Handling errors
 
-When the library is unable to connect to the API (for example, due to network connection problems or a timeout), a subclass of `contextual.APIConnectionError` is raised.
+When the library is unable to connect to the API (for example, due to network connection problems or a timeout), a subclass of `contextual_sdk.APIConnectionError` is raised.
 
 When the API returns a non-success status code (that is, 4xx or 5xx
-response), a subclass of `contextual.APIStatusError` is raised, containing `status_code` and `response` properties.
+response), a subclass of `contextual_sdk.APIStatusError` is raised, containing `status_code` and `response` properties.
 
-All errors inherit from `contextual.APIError`.
+All errors inherit from `contextual_sdk.APIError`.
 
 ```python
-import contextual
-from contextual import ContextualAI
+import contextual_sdk
+from contextual_sdk import ContextualAI
 
 client = ContextualAI()
 
 try:
     client.datastores.create(
         name="name",
     )
-except contextual.APIConnectionError as e:
+except contextual_sdk.APIConnectionError as e:
     print("The server could not be reached")
     print(e.__cause__)  # an underlying Exception, likely raised within httpx.
-except contextual.RateLimitError as e:
+except contextual_sdk.RateLimitError as e:
     print("A 429 status code was received; we should back off a bit.")
-except contextual.APIStatusError as e:
+except contextual_sdk.APIStatusError as e:
     print("Another non-200-range status code was received")
     print(e.status_code)
     print(e.response)
@@ -132,7 +195,7 @@ Connection errors (for example, due to a network connectivity problem), 408 Requ
 You can use the `max_retries` option to configure or disable retry settings:
 
 ```python
-from contextual import ContextualAI
+from contextual_sdk import ContextualAI
 
 # Configure the default for all requests:
 client = ContextualAI(
@@ -152,7 +215,7 @@ By default requests time out after 1 minute. You can configure this with a `time
 which accepts a float or an [`httpx.Timeout`](https://www.python-httpx.org/advanced/#fine-tuning-the-configuration) object:
 
 ```python
-from contextual import ContextualAI
+from contextual_sdk import ContextualAI
 
 # Configure the default for all requests:
 client = ContextualAI(
@@ -206,7 +269,7 @@ if response.my_field is None:
 The "raw" Response object can be accessed by prefixing `.with_raw_response.` to any HTTP method call, e.g.,
 
 ```py
-from contextual import ContextualAI
+from contextual_sdk import ContextualAI
 
 client = ContextualAI()
 response = client.datastores.with_raw_response.create(
@@ -218,9 +281,9 @@ datastore = response.parse()  # get the object that `datastores.create()` would
 print(datastore.id)
 ```
 
-These methods return an [`APIResponse`](https://github.com/stainless-sdks/sunrise-python/tree/main/src/contextual/_response.py) object.
+These methods return an [`APIResponse`](https://github.com/stainless-sdks/sunrise-python/tree/main/src/contextual_sdk/_response.py) object.
 
-The async client returns an [`AsyncAPIResponse`](https://github.com/stainless-sdks/sunrise-python/tree/main/src/contextual/_response.py) with the same structure, the only difference being `await`able methods for reading the response content.
+The async client returns an [`AsyncAPIResponse`](https://github.com/stainless-sdks/sunrise-python/tree/main/src/contextual_sdk/_response.py) with the same structure, the only difference being `await`able methods for reading the response content.
 
 #### `.with_streaming_response`
 
@@ -285,7 +348,7 @@ You can directly override the [httpx client](https://www.python-httpx.org/api/#c
 
 ```python
 import httpx
-from contextual import ContextualAI, DefaultHttpxClient
+from contextual_sdk import ContextualAI, DefaultHttpxClient
 
 client = ContextualAI(
     # Or use the `CONTEXTUAL_AI_BASE_URL` env var
@@ -308,7 +371,7 @@ client.with_options(http_client=DefaultHttpxClient(...))
 By default the library closes underlying HTTP connections whenever the client is [garbage collected](https://docs.python.org/3/reference/datamodel.html#object.__del__). You can manually close the client using the `.close()` method if desired, or with a context manager that closes when exiting.
 
 ```py
-from contextual import ContextualAI
+from contextual_sdk import ContextualAI
 
 with ContextualAI() as client:
   # make requests here
@@ -336,8 +399,8 @@ If you've upgraded to the latest version but aren't seeing any new features you
 You can determine the version that is being used at runtime with:
 
 ```py
-import contextual
-print(contextual.__version__)
+import contextual_sdk
+print(contextual_sdk.__version__)
 ```
 
 ## Requirements