feat: Add new parallel_chat() feature (#188)

* feat: Add new parallel_chat() feature for easily submitting concurrent requests

* Update changelog

* Make tests more robust

* Fix examples

* Update function reference

* Update types

* serialized tool calling

* refactor logic

* A start on proper error handling

* Return None if request was never submitted

* Add overloads

* Undo unnecessary locking

* Attach chat to structured result

* Doctsring fixes

* Clean up error handling tests

Author: cpsievert

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### New features
 
+* Added new family of functions (`parallel_chat()`, `parallel_chat_text()`, and `parallel_chat_structured()`) for submitting multiple prompts at once with some basic rate limiting toggles. (#188)
 * Added support for systematic evaluation via [Inspect AI](https://inspect.aisi.org.uk/). This includes:
     * A new `.export_eval()` method for exporting conversation history as an Inspect eval dataset sample. This supports multi-turn conversations, tool calls, images, PDFs, and structured data.
     * A new `.to_solver()` method for translating chat instances into Inspect solvers that can be used with Inspect's evaluation framework.

chatlas/__init__.py

@@ -16,6 +16,7 @@
 from ._content_image import content_image_file, content_image_plot, content_image_url
 from ._content_pdf import content_pdf_file, content_pdf_url
 from ._interpolate import interpolate, interpolate_file
+from ._parallel import parallel_chat, parallel_chat_structured, parallel_chat_text
 from ._provider import Provider
 from ._provider_anthropic import ChatAnthropic, ChatBedrockAnthropic
 from ._provider_cloudflare import ChatCloudflare
@@ -48,6 +49,9 @@
     "batch_chat_completed",
     "batch_chat_structured",
     "batch_chat_text",
+    "parallel_chat",
+    "parallel_chat_structured",
+    "parallel_chat_text",
     "ChatAnthropic",
     "ChatAuto",
     "ChatBedrockAnthropic",

chatlas/_chat.py

@@ -1259,6 +1259,7 @@ def chat_structured(
         data_model: type[BaseModelT],
         echo: EchoOptions = "none",
         stream: bool = False,
+        kwargs: Optional[SubmitInputArgsT] = None,
     ) -> BaseModelT:
         """
         Extract structured data.
@@ -1279,6 +1280,9 @@ def chat_structured(
               - `"none"`: Do not echo any content.
         stream
             Whether to stream the response (i.e., have the response appear in chunks).
+        kwargs
+            Additional keyword arguments to pass to the method used for requesting
+            the response.
 
         Returns
         -------
@@ -1290,6 +1294,7 @@ def chat_structured(
             data_model=data_model,
             echo=echo,
             stream=stream,
+            kwargs=kwargs,
         )
         return data_model.model_validate(dat)
 
@@ -1322,6 +1327,7 @@ def _submit_and_extract_data(
         data_model: type[BaseModel],
         echo: EchoOptions = "none",
         stream: bool = False,
+        kwargs: Optional[SubmitInputArgsT] = None,
     ) -> dict[str, Any]:
         display = self._markdown_display(echo=echo)
 
@@ -1331,6 +1337,7 @@ def _submit_and_extract_data(
                 data_model=data_model,
                 echo=echo,
                 stream=stream,
+                kwargs=kwargs,
             )
         )
 
@@ -1349,6 +1356,7 @@ async def chat_structured_async(
         data_model: type[BaseModelT],
         echo: EchoOptions = "none",
         stream: bool = False,
+        kwargs: Optional[SubmitInputArgsT] = None,
     ) -> BaseModelT:
         """
         Extract structured data from the given input asynchronously.
@@ -1370,6 +1378,9 @@ async def chat_structured_async(
         stream
             Whether to stream the response (i.e., have the response appear in chunks).
             Defaults to `True` if `echo` is not "none".
+        kwargs
+            Additional keyword arguments to pass to the method used for requesting
+            the response.
 
         Returns
         -------
@@ -1381,6 +1392,7 @@ async def chat_structured_async(
             data_model=data_model,
             echo=echo,
             stream=stream,
+            kwargs=kwargs,
         )
         return data_model.model_validate(dat)
 
@@ -1390,6 +1402,7 @@ async def extract_data_async(
         data_model: type[BaseModel],
         echo: EchoOptions = "none",
         stream: bool = False,
+        kwargs: Optional[SubmitInputArgsT] = None,
     ) -> dict[str, Any]:
         """
         Deprecated: use `.chat_structured_async()` instead.
@@ -1405,6 +1418,7 @@ async def extract_data_async(
             data_model=data_model,
             echo=echo,
             stream=stream,
+            kwargs=kwargs,
         )
 
     async def _submit_and_extract_data_async(
@@ -1413,6 +1427,7 @@ async def _submit_and_extract_data_async(
         data_model: type[BaseModel],
         echo: EchoOptions = "none",
         stream: bool = False,
+        kwargs: Optional[SubmitInputArgsT] = None,
     ) -> dict[str, Any]:
         display = self._markdown_display(echo=echo)
 
@@ -1422,6 +1437,7 @@ async def _submit_and_extract_data_async(
                 data_model=data_model,
                 echo=echo,
                 stream=stream,
+                kwargs=kwargs,
             )
         )