Documentation (64bit#11)

* modified example for documentation

* Updated readme

* updated readme

* updates to cargo.toml

* updated readme

* add badges

* add images from asset branch

* add style

* Revert "add style"

This reverts commit ad59db6.

* add assets in .github

* update examples with readme

* update links on main readme

* add widht

* add ub

* add break

* add width

* move readme to async-openai

* soft link readme

* use readme for docs as well

* documenting rust code

* update

* add doc code

* add test dependency

* let client accept &str or String

* default derive

* add default derives

* cleanup

* updated links

* fix links

* add readme

* Change links

* remove assets

* updates

Author: 64bit

.gitignore

@@ -1,13 +1,7 @@
-# Generated by Cargo
-# will have compiled files and executables
 target
-
-# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
-# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
 Cargo.lock
-
-# These are backup files generated by rustfmt
 **/*.rs.bk
+.DS_Store
 
 # directory used to store images
 data

Cargo.toml

@@ -1,2 +1,4 @@
 [workspace]
-members = ["async-openai"]
+members = [
+    "async-openai",
+]

README.md

@@ -0,0 +1 @@
+async-openai/README.md

README.md

@@ -1,13 +1,28 @@
 [package]
 name = "async-openai"
 version = "0.1.0"
+authors = [
+    "Himanshu Neema"
+]
+categories = ["api-bindings", "web-programming", "asynchronous"]
+keywords = ["openai", "async", "openapi", "ai"]
+description = "Async bindings for OpenAI REST API based on OpenAPI spec"
 edition = "2021"
+rust-version = "1.65"
 publish = false
+license = "MIT"
+readme = "README.md"
+homepage = "https://github.com/64bit/async-openai"
+repository = "https://github.com/64bit/async-openai"
+
 
 [dependencies]
 reqwest = { version = "0.11.13", features = ["json", "stream", "multipart"] }
-serde = { version = "1.0.147", features = ["derive"] }
+serde = { version = "1.0.148", features = ["derive"] }
 serde_json = "1.0.87"
 thiserror = "1.0.37"
 tokio = { version = "1.22.0", features = ["fs"] }
 tokio-util = { version = "0.7.4", features = ["codec", "io-util"] }
+
+[dev-dependencies]
+tokio-test = "0.4.2"

async-openai/Cargo.toml

@@ -0,0 +1,82 @@
+<h1 align="center"> async-openai </h1>
+<p align="center"> Async Rust library for OpenAI </p>
+<div align="center">
+    <a href="https://crates.io/crates/async-openai">
+    <img src="https://img.shields.io/crates/v/async-openai.svg" />
+    </a>
+    <a href="https://docs.rs/async-openai">
+    <img src="https://docs.rs/async-openai/badge.svg" />
+    </a>
+</div>
+
+## Overview
+
+`async-openai` is an unofficial Rust library for OpenAI REST API.
+
+- It's based on [OpenAI OpenAPI spec](https://github.com/openai/openai-openapi)
+- Current features:
+  - [ ] Microsoft Azure Endpoints / AD Authentication
+  - [x] Completions
+  - [x] Edit
+  - [ ] Embeddings
+  - [ ] Fine-Tunning
+  - [x] Image (Generation/Edit/Variation)
+  - [x] Moderation
+
+
+## Usage
+
+The library reads [API key](https://beta.openai.com/account/api-keys) from the environment variable `OPENAI_API_KEY`.
+
+```bash
+export OPENAI_API_KEY='sk-...'
+```
+
+- Visit [examples](./examples/) directory on how to use `async-openai`.
+- Visit [docs.rs/async-openai](https://docs.rs/async-openai) for docs.
+
+## Image Generation Example
+
+```rust
+use std::error::Error;
+
+use async_openai as openai;
+use openai::{
+    types::{CreateImageRequest, ImageSize, ResponseFormat},
+    Client, Image,
+};
+
+#[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 response = Image::create(&client, request).await?;
+
+    // download and save images to ./data directory
+    // (creates directory when it doesn't exist)
+    response.save("./data").await?;
+
+    Ok(())
+}
+```
+
+<div align="center">
+  <img width="315" src="https://raw.githubusercontent.com/64bit/async-openai/assets/create-image/img-1.png" />
+  <img width="315" src="https://raw.githubusercontent.com/64bit/async-openai/assets/create-image/img-2.png" />
+  <br/>
+  <sub>Scaled up for README, actual size 256x256</sub>
+</div>
+
+
+## License
+
+This project is licensed under [MIT license](./LICENSE).

async-openai/README.md

@@ -3,16 +3,20 @@ use serde::{de::DeserializeOwned, Serialize};
 use crate::error::{OpenAIError, WrappedError};
 
 #[derive(Debug, Default)]
+/// Client container for api key, base url and other metadata
+/// required to make API calls.
 pub struct Client {
     api_key: String,
     api_base: String,
     org_id: String,
     //headers: reqwest::header::HeaderMap,
 }
 
-const API_BASE: &str = "https://api.openai.com/v1";
+/// Default v1 API base url
+pub const API_BASE: &str = "https://api.openai.com/v1";
 
 impl Client {
+    /// Create client with default [API_BASE] url and default API key from OPENAI_API_KEY env var
     pub fn new() -> Self {
         Self {
             api_base: API_BASE.to_string(),
@@ -21,18 +25,20 @@ impl Client {
         }
     }
 
-    pub fn with_api_key(mut self, api_key: String) -> Self {
-        self.api_key = api_key;
+    /// To use a different API key different from default OPENAI_API_KEY env var
+    pub fn with_api_key<S: Into<String>>(mut self, api_key: S) -> Self {
+        self.api_key = api_key.into();
         self
     }
 
-    pub fn with_org_id(mut self, org_id: String) -> Self {
-        self.org_id = org_id;
+    pub fn with_org_id<S: Into<String>>(mut self, org_id: S) -> Self {
+        self.org_id = org_id.into();
         self
     }
 
-    pub fn with_api_base(mut self, api_base: String) -> Self {
-        self.api_base = api_base;
+    /// To use a API base url different from default [API_BASE]
+    pub fn with_api_base<S: Into<String>>(mut self, api_base: S) -> Self {
+        self.api_base = api_base.into();
         self
     }
 
@@ -44,6 +50,7 @@ impl Client {
         &self.api_key
     }
 
+    /// Deserialize response body from either error object or actual response object
     async fn process_response<O>(&self, response: reqwest::Response) -> Result<O, OpenAIError>
     where
         O: DeserializeOwned,
@@ -63,6 +70,7 @@ impl Client {
         Ok(response)
     }
 
+    /// Make a GET request to {path} and deserialize the response body
     pub(crate) async fn get<O>(&self, path: &str) -> Result<O, OpenAIError>
     where
         O: DeserializeOwned,
@@ -76,6 +84,7 @@ impl Client {
         self.process_response(response).await
     }
 
+    /// Make a POST request to {path} and deserialize the response body
     pub(crate) async fn post<I, O>(&self, path: &str, request: I) -> Result<O, OpenAIError>
     where
         I: Serialize,
@@ -91,6 +100,7 @@ impl Client {
         self.process_response(response).await
     }
 
+    /// POST a form at {path} and deserialize the response body
     pub(crate) async fn post_form<O>(
         &self,
         path: &str,

async-openai/src/client.rs

@@ -4,9 +4,13 @@ use crate::{
     types::{CreateCompletionRequest, CreateCompletionResponse},
 };
 
+/// 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;
 
 impl Completion {
+    /// Creates a completion for the provided prompt and parameters
     pub async fn create(
         client: &Client,
         request: CreateCompletionRequest,

async-openai/src/completion.rs

@@ -4,9 +4,12 @@ use crate::{
     Client,
 };
 
+/// Given a prompt and an instruction, the model will return
+/// an edited version of the prompt.
 pub struct Edit;
 
 impl Edit {
+    /// Creates a new edit for the provided input, instruction, and parameters
     pub async fn create(
         client: &Client,
         request: CreateEditRequest,

async-openai/src/edit.rs

@@ -1,22 +1,26 @@
+//! Errors originating from API calls, parsing responses, and reading-or-writing to the file system.
 use serde::Deserialize;
 
 #[derive(Debug, thiserror::Error)]
 pub enum OpenAIError {
+    /// Underlying error from reqwest library after an API call was made
     #[error("http error: {0}")]
     Reqwest(#[from] reqwest::Error),
+    /// OpenAI returns error object with details of API call failure
     #[error("{}: {}", .0.r#type, .0.message)]
     ApiError(ApiError),
+    /// Error when a response cannot be deserialized into a Rust type
     #[error("failed to deserialize api response: {0}")]
     JSONDeserialize(serde_json::Error),
+    /// Error on the client side when saving image to file system
     #[error("failed to save image: {0}")]
     ImageSaveError(String),
+    /// Error on the client side when reading image from file system
     #[error("failed to read image: {0}")]
     ImageReadError(String),
 }
 
-/*b"{\n    \"error\": {\n
-\"message\": \"You exceeded your current quota, please check your plan and billing details.\",\n
-     \"type\": \"insufficient_quota\",\n        \"param\": null,\n        \"code\": null\n    }\n}\n", */
+/// OpenAI API returns error object on failure
 #[derive(Debug, Deserialize)]
 pub struct ApiError {
     pub message: String,
@@ -25,6 +29,7 @@ pub struct ApiError {
     pub code: Option<serde_json::Value>,
 }
 
+/// Wrapper to deserialize the error object nested in "error" JSON key
 #[derive(Deserialize)]
 pub(crate) struct WrappedError {
     pub(crate) error: ApiError,

async-openai/src/error.rs

@@ -10,9 +10,13 @@ use crate::{
     Client,
 };
 
+/// Given a prompt and/or an input image, the model will generate a new image.
+///
+/// Related guide: [Image generation](https://beta.openai.com/docs/guides/images/introduction)
 pub struct Image;
 
 impl Image {
+    /// Creates an image given a prompt.
     pub async fn create(
         client: &Client,
         request: CreateImageRequest,
@@ -29,6 +33,7 @@ impl Image {
         Ok(body)
     }
 
+    /// Creates the part for the given image file for multipart upload.
     pub(crate) async fn create_part(
         image_input: &ImageInput,
     ) -> Result<reqwest::multipart::Part, OpenAIError> {
@@ -55,6 +60,7 @@ impl Image {
         Ok(image_part)
     }
 
+    /// Creates an edited or extended image given an original image and a prompt.
     pub async fn create_edit(
         client: &Client,
         request: CreateImageEditRequest,
@@ -89,6 +95,7 @@ impl Image {
         client.post_form("/images/edits", form).await
     }
 
+    /// Creates a variation of a given image.
     pub async fn create_variation(
         client: &Client,
         request: CreateImageVariationRequest,

async-openai/src/image.rs

@@ -1,3 +1,43 @@
+//! Async Rust library for OpenAI REST API based on OpenAPI spec.
+//!
+//! ## Creating client
+//!
+//! ```
+//! use async_openai as openai;
+//!
+//! // Create a client with api key from env var OPENAI_API_KEY and default base url.
+//! let client = openai::Client::new();
+//!
+//! // OR use API key from different source
+//! let api_key = "sk-..."; // This could be from a file, hard coding secret is not a best practice.
+//! let client = openai::Client::new().with_api_key(api_key);
+//! ```
+//!
+//! ## Making requests
+//!
+//!```
+//!# tokio_test::block_on(async {
+//! use async_openai as openai;
+//! use openai::{Client, Completion, types::{CreateCompletionRequest}};
+//!
+//! // Create client
+//! let client = Client::new();
+//! // Create request
+//! let request = CreateCompletionRequest {
+//!     model: "text-davinci-003".to_owned(),
+//!     prompt: Some("Tell me a joke about the universe".to_owned()),
+//!     ..Default::default()
+//! };
+//! // Call API
+//! let response = Completion::create(&client, request).await.unwrap();
+//!
+//! println!("{}", response.choices.first().unwrap().text);
+//! # });
+//!```
+//!
+//! ## Examples
+//! For full working examples for all supported features see [examples](https://raw.githubusercontent.com/64bit/async-openai/main/examples) directory in the repository.
+//!
 mod client;
 mod completion;
 mod download;
@@ -9,6 +49,7 @@ mod moderation;
 pub mod types;
 
 pub use client::Client;
+pub use client::API_BASE;
 pub use completion::Completion;
 pub use edit::Edit;
 pub use image::Image;

async-openai/src/lib.rs

@@ -4,13 +4,20 @@ use crate::{
     Client,
 };
 
+/// List and describe the various models available in the API.
+/// You can refer to the [Models](https://beta.openai.com/docs/models) documentation to understand what
+/// models are available and the differences between them.
 pub struct Models;
 
 impl Models {
+    /// Lists the currently available models, and provides basic information
+    /// about each one such as the owner and availability.
     pub async fn list(client: &Client) -> Result<ListModelResponse, OpenAIError> {
         client.get("/models").await
     }
 
+    /// Retrieves a model instance, providing basic information about the model
+    /// such as the owner and permissioning.
     pub async fn retrieve(client: &Client, id: &str) -> Result<Model, OpenAIError> {
         client.get(format!("/models/{id}").as_str()).await
     }