feat: Ergonomics: builder pattern for API groups and request objects (#29)

* update depedencies

* make Client cloneable

* Add derive_builder dependency

* Ergonomics: Completions API is fully supported by builder pattern

* Update all Completions example to use ergonomic builder pattern

* Ergonomics: Edits API is fully supported by builder pattern

* Update Edits example to use ergonomic builder pattern

* Ergonomics: Images group API is fully supported by builder pattern

* Update Images example to use ergonomic builder pattern

* Ergonomics: Moderations group API is fully supported by builder pattern

* Update Moderations example to use ergonomic builder pattern

* Ergonomics: Files group API is fully supported by builder pattern

* Ergonomics: FineTunes group API is fully supported by builder pattern

* Ergonomics: Embeddings group API is fully supported by builder pattern

* Update Completions Prompt macro test

* Ergonomics: Models group API is fully supported by builder pattern

* Update Models example to use ergonomic builder pattern

* update readme

* updated file test

Author: 64bit

async-openai/Cargo.toml

@@ -17,18 +17,19 @@ repository = "https://github.com/64bit/async-openai"
 
 [dependencies]
 backoff = {version = "0.4.0", features = ["tokio"] }
-base64 = "0.13.1"
+base64 = "0.20.0"
 futures = "0.3.25"
 rand = "0.8.5"
 reqwest = { version = "0.11.13", features = ["json", "stream", "multipart"] }
 reqwest-eventsource = "0.4.0"
-serde = { version = "1.0.148", features = ["derive", "rc"] }
-serde_json = "1.0.87"
-thiserror = "1.0.37"
-tokio = { version = "1.22.0", features = ["fs", "macros"] }
+serde = { version = "1.0.152", features = ["derive", "rc"] }
+serde_json = "1.0.91"
+thiserror = "1.0.38"
+tokio = { version = "1.23.0", features = ["fs", "macros"] }
 tokio-stream = "0.1.11"
 tokio-util = { version = "0.7.4", features = ["codec", "io-util"] }
 tracing = "0.1.37"
+derive_builder = "0.12.0"
 
 [dev-dependencies]
 tokio-test = "0.4.2"

async-openai/README.md

@@ -33,6 +33,7 @@
   - [x] Models
   - [x] Moderations
 - Non-streaming requests are retried with exponential backoff when [rate limited](https://help.openai.com/en/articles/5955598-is-api-usage-subject-to-any-rate-limits) by the API server.
+- Ergonomic Rust library with builder pattern for all request objects.
 
 *Being a young project there are rough edges*
 
@@ -56,31 +57,30 @@ $Env:OPENAI_API_KEY='sk-...'
 ## Image Generation Example
 
 ```rust
-use std::error::Error;
-
 use async_openai::{
-    types::{CreateImageRequest, ImageSize, ResponseFormat},
-    Client, Image,
+    types::{CreateImageRequestArgs, ImageSize, ResponseFormat},
+    Client,
 };
+use std::error::Error;
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn Error>> {
     // create client, reads OPENAI_API_KEY environment variable for API key.
     let client = Client::new();
 
-    let request = CreateImageRequest {
-        prompt: "cats on sofa and carpet in living room".to_owned(),
-        n: Some(2),
-        response_format: Some(ResponseFormat::Url),
-        size: Some(ImageSize::S256x256),
-        user: Some("async-openai".to_owned()),
-    };
+    let request = CreateImageRequestArgs::default()
+        .prompt("cats on sofa and carpet in living room")
+        .n(2)
+        .response_format(ResponseFormat::Url)
+        .size(ImageSize::S256x256)
+        .user("async-openai")
+        .build()?;
 
-    let response = Image::create(&client, request).await?;
+    let response = client.images().create(request).await?;
 
-    // Download and save images to ./data directory
-    // Each url download and save happens in dedicated Tokio task
-    // (creates directory when it doesn't exist)
+    // Download and save images to ./data directory.
+    // Each url is downloaded and saved in dedicated Tokio task.
+    // Directory is created if it doesn't exist.
     response.save("./data").await?;
 
     Ok(())

async-openai/src/client.rs

@@ -5,9 +5,16 @@ use reqwest::header::HeaderMap;
 use reqwest_eventsource::{Event, EventSource, RequestBuilderExt};
 use serde::{de::DeserializeOwned, Serialize};
 
-use crate::error::{OpenAIError, WrappedError};
-
-#[derive(Debug, Default)]
+use crate::{
+    edit::Edits,
+    error::{OpenAIError, WrappedError},
+    file::Files,
+    image::Images,
+    moderation::Moderations,
+    Completions, Embeddings, FineTunes, Models,
+};
+
+#[derive(Debug, Default, Clone)]
 /// Client is a container for api key, base url, organization id, and backoff
 /// configuration used to make API calls.
 pub struct Client {
@@ -64,6 +71,48 @@ impl Client {
         &self.api_key
     }
 
+    // API groups
+
+    /// To call [Models] group related APIs using this client.
+    pub fn models(&self) -> Models {
+        Models::new(self)
+    }
+
+    /// To call [Completions] group related APIs using this client.
+    pub fn completions(&self) -> Completions {
+        Completions::new(self)
+    }
+
+    /// To call [Edits] group related APIs using this client.
+    pub fn edits(&self) -> Edits {
+        Edits::new(self)
+    }
+
+    /// To call [Images] group related APIs using this client.
+    pub fn images(&self) -> Images {
+        Images::new(self)
+    }
+
+    /// To call [Moderations] group related APIs using this client.
+    pub fn moderations(&self) -> Moderations {
+        Moderations::new(self)
+    }
+
+    /// To call [Files] group related APIs using this client.
+    pub fn files(&self) -> Files {
+        Files::new(self)
+    }
+
+    /// To call [FineTunes] group related APIs using this client.
+    pub fn fine_tunes(&self) -> FineTunes {
+        FineTunes::new(self)
+    }
+
+    /// To call [Embeddings] group related APIs using this client.
+    pub fn embeddings(&self) -> Embeddings {
+        Embeddings::new(self)
+    }
+
     fn headers(&self) -> HeaderMap {
         let mut headers = HeaderMap::new();
         if !self.org_id.is_empty() {

async-openai/src/completion.rs

@@ -7,20 +7,26 @@ use crate::{
 /// Given a prompt, the model will return one or more predicted
 /// completions, and can also return the probabilities of alternative
 /// tokens at each position.
-pub struct Completion;
+pub struct Completions<'c> {
+    client: &'c Client,
+}
+
+impl<'c> Completions<'c> {
+    pub fn new(client: &'c Client) -> Self {
+        Self { client }
+    }
 
-impl Completion {
     /// Creates a completion for the provided prompt and parameters
     pub async fn create(
-        client: &Client,
+        &self,
         request: CreateCompletionRequest,
     ) -> Result<CreateCompletionResponse, OpenAIError> {
         if request.stream.is_some() && request.stream.unwrap() {
             return Err(OpenAIError::InvalidArgument(
                 "When stream is true, use Completion::create_stream".into(),
             ));
         }
-        client.post("/completions", request).await
+        self.client.post("/completions", request).await
     }
 
     /// Creates a completion request for the provided prompt and parameters
@@ -31,7 +37,7 @@ impl Completion {
     ///
     /// [CompletionResponseStream] is a parsed SSE stream until a \[DONE\] is received from server.
     pub async fn create_stream(
-        client: &Client,
+        &self,
         mut request: CreateCompletionRequest,
     ) -> Result<CompletionResponseStream, OpenAIError> {
         if request.stream.is_some() && !request.stream.unwrap() {
@@ -42,6 +48,6 @@ impl Completion {
 
         request.stream = Some(true);
 
-        Ok(client.post_stream("/completions", request).await)
+        Ok(self.client.post_stream("/completions", request).await)
     }
 }

async-openai/src/edit.rs

@@ -6,14 +6,20 @@ use crate::{
 
 /// Given a prompt and an instruction, the model will return
 /// an edited version of the prompt.
-pub struct Edit;
+pub struct Edits<'c> {
+    client: &'c Client,
+}
+
+impl<'c> Edits<'c> {
+    pub fn new(client: &'c Client) -> Self {
+        Self { client }
+    }
 
-impl Edit {
     /// Creates a new edit for the provided input, instruction, and parameters
     pub async fn create(
-        client: &Client,
+        &self,
         request: CreateEditRequest,
     ) -> Result<CreateEditResponse, OpenAIError> {
-        client.post("/edits", request).await
+        self.client.post("/edits", request).await
     }
 }

async-openai/src/embedding.rs

@@ -8,84 +8,100 @@ use crate::{
 /// consumed by machine learning models and algorithms.
 ///
 /// Related guide: [Embeddings](https://beta.openai.com/docs/guides/embeddings/what-are-embeddings)
-pub struct Embeddings;
+pub struct Embeddings<'c> {
+    client: &'c Client,
+}
+
+impl<'c> Embeddings<'c> {
+    pub fn new(client: &'c Client) -> Self {
+        Self { client }
+    }
 
-impl Embeddings {
     /// Creates an embedding vector representing the input text.
     pub async fn create(
-        client: &Client,
+        &self,
         request: CreateEmbeddingRequest,
     ) -> Result<CreateEmbeddingResponse, OpenAIError> {
-        client.post("/embeddings", request).await
+        self.client.post("/embeddings", request).await
     }
 }
 
 #[cfg(test)]
 mod tests {
-    use crate::{types::CreateEmbeddingRequest, Client, Embeddings};
+    use crate::{types::CreateEmbeddingRequestArgs, Client};
 
     #[tokio::test]
     async fn test_embedding_string() {
         let client = Client::new();
-        let request = CreateEmbeddingRequest {
-            model: "text-embedding-ada-002".to_owned(),
-            input: crate::types::EmbeddingInput::String(
-                "The food was delicious and the waiter...".to_owned(),
-            ),
-            ..Default::default()
-        };
 
-        let response = Embeddings::create(&client, request).await;
+        let request = CreateEmbeddingRequestArgs::default()
+            .model("text-embedding-ada-002")
+            .input("The food was delicious and the waiter...")
+            .build()
+            .unwrap();
 
-        println!("{:#?}", response);
+        let response = client.embeddings().create(request).await;
+
+        assert!(response.is_ok());
     }
 
     #[tokio::test]
     async fn test_embedding_string_array() {
         let client = Client::new();
-        let request = CreateEmbeddingRequest {
-            model: "text-embedding-ada-002".to_owned(),
-            input: crate::types::EmbeddingInput::StringArray(vec![
-                "The food was delicious".to_owned(),
-                "The waiter was good".to_owned(),
-            ]),
-            ..Default::default()
-        };
-
-        let response = Embeddings::create(&client, request).await;
-
-        println!("{:#?}", response);
+
+        let request = CreateEmbeddingRequestArgs::default()
+            .model("text-embedding-ada-002")
+            .input(["The food was delicious", "The waiter was good"])
+            .build()
+            .unwrap();
+
+        let response = client.embeddings().create(request).await;
+
+        assert!(response.is_ok());
     }
 
     #[tokio::test]
     async fn test_embedding_integer_array() {
         let client = Client::new();
-        let request = CreateEmbeddingRequest {
-            model: "text-embedding-ada-002".to_owned(),
-            input: crate::types::EmbeddingInput::IntegerArray(vec![1, 2, 3]),
-            ..Default::default()
-        };
 
-        let response = Embeddings::create(&client, request).await;
+        let request = CreateEmbeddingRequestArgs::default()
+            .model("text-embedding-ada-002")
+            .input([1, 2, 3])
+            .build()
+            .unwrap();
+
+        let response = client.embeddings().create(request).await;
+
+        assert!(response.is_ok());
+    }
+
+    #[tokio::test]
+    async fn test_embedding_array_of_integer_array_matrix() {
+        let client = Client::new();
+
+        let request = CreateEmbeddingRequestArgs::default()
+            .model("text-embedding-ada-002")
+            .input([[1, 2, 3], [4, 5, 6], [7, 8, 10]])
+            .build()
+            .unwrap();
 
-        println!("{:#?}", response);
+        let response = client.embeddings().create(request).await;
+
+        assert!(response.is_ok());
     }
 
     #[tokio::test]
     async fn test_embedding_array_of_integer_array() {
         let client = Client::new();
-        let request = CreateEmbeddingRequest {
-            model: "text-embedding-ada-002".to_owned(),
-            input: crate::types::EmbeddingInput::ArrayOfIntegerArray(vec![
-                vec![1, 2, 3],
-                vec![4, 5, 6],
-                vec![7, 8, 100257],
-            ]),
-            ..Default::default()
-        };
-
-        let response = Embeddings::create(&client, request).await;
-
-        println!("{:#?}", response);
+
+        let request = CreateEmbeddingRequestArgs::default()
+            .model("text-embedding-ada-002")
+            .input([vec![1, 2, 3], vec![4, 5, 6, 7], vec![7, 8, 10, 11, 100257]])
+            .build()
+            .unwrap();
+
+        let response = client.embeddings().create(request).await;
+
+        assert!(response.is_ok());
     }
 }

async-openai/src/error.rs

@@ -21,7 +21,8 @@ pub enum OpenAIError {
     /// Error when trying to stream completions SSE
     #[error("stream failed: {0}")]
     StreamError(String),
-    /// Error from client side validation before making API call
+    /// Error from client side validation
+    /// or when builder fails to build request before making API call
     #[error("invalid args: {0}")]
     InvalidArgument(String),
 }