feat: RequestOptions for individual requests (64bit#476)

* feat: RequestOptions

* cargo fmt

* cargo clippy fix

* make RequestOptions methods as pub(crate)

* remove query parameters from individual methods

* update tests and examples to use RequestOptionsBuilder trait

* cargo fmt

* remove query params from all other methods

* update examples to use query chain method

* cargo clippy fix

* cargo fmt

* handle query properly

* fix bring-your-own-type tests

* query parameters for all APIs

* updated README

* fix example:

* cargo fmt

* namespaced query param types

* fix example

* update

* fix link

* only initialize request options vector when needed

(cherry picked from commit 8b33483)

Author: 64bit

.gitignore

@@ -9,3 +9,5 @@ data
 *.mp3
 
 .idea
+
+*.py

async-openai/README.md

@@ -30,15 +30,16 @@ a `x.y.z` version.
 | **Realtime** | Realtime Calls, Client secrets, Client events, Server events |
 | **Chat Completions** | Chat Completions, Streaming |
 | **Assistants** <sub>(Beta)</sub> | Assistants, Threads, Messages, Runs, Run steps, Streaming |
-| **Administration** | Administration, Admin API Keys, Invites, Users, Projects, Project users, Project service accounts, Project API keys, Project rate limits, Audit logs, Usage, Certificates |
+| **Administration** | Admin API Keys, Invites, Users, Projects, Project users, Project service accounts, Project API keys, Project rate limits, Audit logs, Usage, Certificates |
 | **Legacy** | Completions |
 
 Features that makes `async-openai` unique:
 - Bring your own custom types for Request or Response objects.
-- SSE streaming on available APIs
+- SSE streaming on available APIs.
+- Customize query and headers per request, customize headers globally.
+- Requests (except SSE streaming) including form submissions are retried with exponential backoff when [rate limited](https://platform.openai.com/docs/guides/rate-limits).
 - Ergonomic builder pattern for all request objects.
-- Microsoft Azure OpenAI Service (only for APIs matching OpenAI spec)
-- Bring your own custom types for Request or Response objects.
+- Microsoft Azure OpenAI Service (only for APIs matching OpenAI spec).
 
 More on `async-openai-wasm`:
 - **WASM support**

async-openai/src/admin_api_keys.rs

@@ -1,34 +1,34 @@
-use serde::Serialize;
-
 use crate::{
     Client,
     config::Config,
     error::OpenAIError,
     types::admin::api_keys::{
         AdminApiKey, AdminApiKeyDeleteResponse, ApiKeyList, CreateAdminApiKeyRequest,
     },
+    Client, RequestOptions,
 };
 
 /// Admin API keys enable Organization Owners to programmatically manage various aspects of their
 /// organization, including users, projects, and API keys. These keys provide administrative capabilities,
 /// allowing you to automate organization management tasks.
 pub struct AdminAPIKeys<'c, C: Config> {
     client: &'c Client<C>,
+    pub(crate) request_options: RequestOptions,
 }
 
 impl<'c, C: Config> AdminAPIKeys<'c, C> {
     pub fn new(client: &'c Client<C>) -> Self {
-        Self { client }
+        Self {
+            client,
+            request_options: RequestOptions::new(),
+        }
     }
 
     /// List all organization and project API keys.
-    #[crate::byot(T0 = serde::Serialize, R = serde::de::DeserializeOwned)]
-    pub async fn list<Q>(&self, query: &Q) -> Result<ApiKeyList, OpenAIError>
-    where
-        Q: Serialize + ?Sized,
-    {
+    #[crate::byot(R = serde::de::DeserializeOwned)]
+    pub async fn list(&self) -> Result<ApiKeyList, OpenAIError> {
         self.client
-            .get_with_query("/organization/admin_api_keys", &query)
+            .get("/organization/admin_api_keys", &self.request_options)
             .await
     }
 
@@ -38,23 +38,33 @@ impl<'c, C: Config> AdminAPIKeys<'c, C> {
         request: CreateAdminApiKeyRequest,
     ) -> Result<AdminApiKey, OpenAIError> {
         self.client
-            .post("/organization/admin_api_keys", request)
+            .post(
+                "/organization/admin_api_keys",
+                request,
+                &self.request_options,
+            )
             .await
     }
 
     /// Retrieve a single organization API key.
     #[crate::byot(T0 = std::fmt::Display, R = serde::de::DeserializeOwned)]
     pub async fn retrieve(&self, key_id: &str) -> Result<AdminApiKey, OpenAIError> {
         self.client
-            .get(format!("/organization/admin_api_keys/{key_id}").as_str())
+            .get(
+                format!("/organization/admin_api_keys/{key_id}").as_str(),
+                &self.request_options,
+            )
             .await
     }
 
     /// Delete an organization admin API key.
     #[crate::byot(T0 = std::fmt::Display, R = serde::de::DeserializeOwned)]
     pub async fn delete(&self, key_id: &str) -> Result<AdminApiKeyDeleteResponse, OpenAIError> {
         self.client
-            .delete(format!("/organization/admin_api_keys/{key_id}").as_str())
+            .delete(
+                format!("/organization/admin_api_keys/{key_id}").as_str(),
+                &self.request_options,
+            )
             .await
     }
 }

async-openai/src/assistants.rs

@@ -1,5 +1,3 @@
-use serde::Serialize;
-
 use crate::{
     Client,
     config::Config,
@@ -8,18 +6,23 @@ use crate::{
         AssistantObject, CreateAssistantRequest, DeleteAssistantResponse, ListAssistantsResponse,
         ModifyAssistantRequest,
     },
+    Client, RequestOptions,
 };
 
 /// Build assistants that can call models and use tools to perform tasks.
 ///
 /// [Get started with the Assistants API](https://platform.openai.com/docs/assistants)
 pub struct Assistants<'c, C: Config> {
     client: &'c Client<C>,
+    pub(crate) request_options: RequestOptions,
 }
 
 impl<'c, C: Config> Assistants<'c, C> {
     pub fn new(client: &'c Client<C>) -> Self {
-        Self { client }
+        Self {
+            client,
+            request_options: RequestOptions::new(),
+        }
     }
 
     /// Create an assistant with a model and instructions.
@@ -28,14 +31,19 @@ impl<'c, C: Config> Assistants<'c, C> {
         &self,
         request: CreateAssistantRequest,
     ) -> Result<AssistantObject, OpenAIError> {
-        self.client.post("/assistants", request).await
+        self.client
+            .post("/assistants", request, &self.request_options)
+            .await
     }
 
     /// Retrieves an assistant.
     #[crate::byot(T0 = std::fmt::Display, R = serde::de::DeserializeOwned)]
     pub async fn retrieve(&self, assistant_id: &str) -> Result<AssistantObject, OpenAIError> {
         self.client
-            .get(&format!("/assistants/{assistant_id}"))
+            .get(
+                &format!("/assistants/{assistant_id}"),
+                &self.request_options,
+            )
             .await
     }
 
@@ -47,24 +55,28 @@ impl<'c, C: Config> Assistants<'c, C> {
         request: ModifyAssistantRequest,
     ) -> Result<AssistantObject, OpenAIError> {
         self.client
-            .post(&format!("/assistants/{assistant_id}"), request)
+            .post(
+                &format!("/assistants/{assistant_id}"),
+                request,
+                &self.request_options,
+            )
             .await
     }
 
     /// Delete an assistant.
     #[crate::byot(T0 = std::fmt::Display, R = serde::de::DeserializeOwned)]
     pub async fn delete(&self, assistant_id: &str) -> Result<DeleteAssistantResponse, OpenAIError> {
         self.client
-            .delete(&format!("/assistants/{assistant_id}"))
+            .delete(
+                &format!("/assistants/{assistant_id}"),
+                &self.request_options,
+            )
             .await
     }
 
     /// Returns a list of assistants.
-    #[crate::byot(T0 = serde::Serialize, R = serde::de::DeserializeOwned)]
-    pub async fn list<Q>(&self, query: &Q) -> Result<ListAssistantsResponse, OpenAIError>
-    where
-        Q: Serialize + ?Sized,
-    {
-        self.client.get_with_query("/assistants", &query).await
+    #[crate::byot(R = serde::de::DeserializeOwned)]
+    pub async fn list(&self) -> Result<ListAssistantsResponse, OpenAIError> {
+        self.client.get("/assistants", &self.request_options).await
     }
 }

async-openai/src/audio.rs

@@ -1,14 +1,18 @@
-use crate::{Client, Speech, Transcriptions, Translations, config::Config};
+use crate::{Client, RequestOptions, Speech, Transcriptions, Translations, config::Config};
 
 /// Turn audio into text or text into audio.
 /// Related guide: [Speech to text](https://platform.openai.com/docs/guides/speech-to-text)
 pub struct Audio<'c, C: Config> {
     client: &'c Client<C>,
+    pub(crate) request_options: RequestOptions,
 }
 
 impl<'c, C: Config> Audio<'c, C> {
     pub fn new(client: &'c Client<C>) -> Self {
-        Self { client }
+        Self {
+            client,
+            request_options: RequestOptions::new(),
+        }
     }
 
     /// APIs in Speech group.

async-openai/src/audit_logs.rs

@@ -1,29 +1,29 @@
-use serde::Serialize;
-
 use crate::{
-    Client, config::Config, error::OpenAIError, types::admin::audit_logs::ListAuditLogsResponse,
+    config::Config, error::OpenAIError, types::admin::audit_logs::ListAuditLogsResponse, Client,
+    RequestOptions,
 };
 
 /// Logs of user actions and configuration changes within this organization.
 /// To log events, you must activate logging in the [Organization Settings](https://platform.openai.com/settings/organization/general).
 /// Once activated, for security reasons, logging cannot be deactivated.
 pub struct AuditLogs<'c, C: Config> {
     client: &'c Client<C>,
+    pub(crate) request_options: RequestOptions,
 }
 
 impl<'c, C: Config> AuditLogs<'c, C> {
     pub fn new(client: &'c Client<C>) -> Self {
-        Self { client }
+        Self {
+            client,
+            request_options: RequestOptions::new(),
+        }
     }
 
     /// List user actions and configuration changes within this organization.
-    #[crate::byot(T0 = serde::Serialize, R = serde::de::DeserializeOwned)]
-    pub async fn get<Q>(&self, query: &Q) -> Result<ListAuditLogsResponse, OpenAIError>
-    where
-        Q: Serialize + ?Sized,
-    {
+    #[crate::byot(R = serde::de::DeserializeOwned)]
+    pub async fn get(&self) -> Result<ListAuditLogsResponse, OpenAIError> {
         self.client
-            .get_with_query("/organization/audit_logs", &query)
+            .get("/organization/audit_logs", &self.request_options)
             .await
     }
 }

async-openai/src/batches.rs

@@ -1,43 +1,47 @@
-use serde::Serialize;
-
 use crate::{
     Client,
     config::Config,
     error::OpenAIError,
     types::batches::{Batch, BatchRequest, ListBatchesResponse},
+    Client, RequestOptions,
 };
 
 /// Create large batches of API requests for asynchronous processing. The Batch API returns completions within 24 hours for a 50% discount.
 ///
 /// Related guide: [Batch](https://platform.openai.com/docs/guides/batch)
 pub struct Batches<'c, C: Config> {
     client: &'c Client<C>,
+    pub(crate) request_options: RequestOptions,
 }
 
 impl<'c, C: Config> Batches<'c, C> {
     pub fn new(client: &'c Client<C>) -> Self {
-        Self { client }
+        Self {
+            client,
+            request_options: RequestOptions::new(),
+        }
     }
 
     /// Creates and executes a batch from an uploaded file of requests
     #[crate::byot(T0 = serde::Serialize, R = serde::de::DeserializeOwned)]
     pub async fn create(&self, request: BatchRequest) -> Result<Batch, OpenAIError> {
-        self.client.post("/batches", request).await
+        self.client
+            .post("/batches", request, &self.request_options)
+            .await
     }
 
     /// List your organization's batches.
-    #[crate::byot(T0 = serde::Serialize, R = serde::de::DeserializeOwned)]
-    pub async fn list<Q>(&self, query: &Q) -> Result<ListBatchesResponse, OpenAIError>
-    where
-        Q: Serialize + ?Sized,
-    {
-        self.client.get_with_query("/batches", &query).await
+    #[crate::byot(R = serde::de::DeserializeOwned)]
+    pub async fn list(&self) -> Result<ListBatchesResponse, OpenAIError> {
+        self.client.get("/batches", &self.request_options).await
     }
 
     /// Retrieves a batch.
     #[crate::byot(T0 = std::fmt::Display, R = serde::de::DeserializeOwned)]
     pub async fn retrieve(&self, batch_id: &str) -> Result<Batch, OpenAIError> {
-        self.client.get(&format!("/batches/{batch_id}")).await
+        self.client
+            .get(&format!("/batches/{batch_id}"), &self.request_options)
+            .await
     }
 
     /// Cancels an in-progress batch. The batch will be in status `cancelling` for up to 10 minutes, before changing to `cancelled`, where it will have partial results (if any) available in the output file.
@@ -47,6 +51,7 @@ impl<'c, C: Config> Batches<'c, C> {
             .post(
                 &format!("/batches/{batch_id}/cancel"),
                 serde_json::json!({}),
+                &self.request_options,
             )
             .await
     }