Sync updates from Spec (#171)

* updates to doc comments and types

* deprecated

* update ChatCompletionFunctions to FunctionObject

* More type updates

* add logprobs field

* update from spec

* updated spec

* fixes suggested by cargo clippy

Author: 64bit

async-openai/src/chat.rs

@@ -9,7 +9,7 @@ use crate::{
 
 /// Given a list of messages comprising a conversation, the model will return a response.
 ///
-/// Related guide: [Chat completions](https://platform.openai.com/docs/guides/gpt)
+/// Related guide: [Chat completions](https://platform.openai.com//docs/guides/text-generation)
 pub struct Chat<'c, C: Config> {
     client: &'c Client<C>,
 }

async-openai/src/client.rs

@@ -388,7 +388,7 @@ where
                         }
 
                         let response = match serde_json::from_str::<O>(&message.data) {
-                            Err(e) => Err(map_deserialization_error(e, &message.data.as_bytes())),
+                            Err(e) => Err(map_deserialization_error(e, message.data.as_bytes())),
                             Ok(output) => Ok(output),
                         };
 

async-openai/src/download.rs

@@ -42,18 +42,12 @@ pub(crate) async fn download_url<P: AsRef<Path>>(
 
     tokio::fs::create_dir_all(dir.as_path())
         .await
-        .map_err(|e| {
-            OpenAIError::FileSaveError(format!("{}, dir: {}", e.to_string(), dir.display()))
-        })?;
+        .map_err(|e| OpenAIError::FileSaveError(format!("{}, dir: {}", e, dir.display())))?;
 
     tokio::fs::write(
         file_path.as_path(),
         response.bytes().await.map_err(|e| {
-            OpenAIError::FileSaveError(format!(
-                "{}, file path: {}",
-                e.to_string(),
-                file_path.display()
-            ))
+            OpenAIError::FileSaveError(format!("{}, file path: {}", e, file_path.display()))
         })?,
     )
     .await
@@ -80,9 +74,7 @@ pub(crate) async fn save_b64<P: AsRef<Path>>(b64: &str, dir: P) -> Result<PathBu
             .map_err(|e| OpenAIError::FileSaveError(e.to_string()))?,
     )
     .await
-    .map_err(|e| {
-        OpenAIError::FileSaveError(format!("{}, path: {}", e.to_string(), path.display()))
-    })?;
+    .map_err(|e| OpenAIError::FileSaveError(format!("{}, path: {}", e, path.display())))?;
 
     Ok(path)
 }

async-openai/src/error.rs

@@ -45,7 +45,7 @@ pub(crate) struct WrappedError {
 pub(crate) fn map_deserialization_error(e: serde_json::Error, bytes: &[u8]) -> OpenAIError {
     tracing::error!(
         "failed deserialization of: {}",
-        String::from_utf8_lossy(bytes.as_ref())
+        String::from_utf8_lossy(bytes)
     );
     OpenAIError::JSONDeserialize(e)
 }

async-openai/src/file.rs

@@ -15,7 +15,11 @@ impl<'c, C: Config> Files<'c, C> {
         Self { client }
     }
 
-    /// Upload a file that contains document(s) to be used across various endpoints/features. Currently, the size of all the files uploaded by one organization can be up to 1 GB. Please contact us if you need to increase the storage limit.
+    /// Upload a file that can be used across various endpoints. The size of all the files uploaded by one organization can be up to 100 GB.
+    ///
+    /// The size of individual files can be a maximum of 512 MB or 2 million tokens for Assistants. See the [Assistants Tools guide](https://platform.openai.com/docs/assistants/tools) to learn more about the types of files supported. The Fine-tuning API only supports `.jsonl` files.
+    ///
+    /// Please [contact us](https://help.openai.com/) if you need to increase these storage limits.
     pub async fn create(&self, request: CreateFileRequest) -> Result<OpenAIFile, OpenAIError> {
         self.client.post_form("/files", request).await
     }

async-openai/src/types/assistant.rs

@@ -3,7 +3,9 @@ use std::collections::HashMap;
 use derive_builder::Builder;
 use serde::{Deserialize, Serialize};
 
-use crate::{error::OpenAIError, types::ChatCompletionFunctions};
+use crate::error::OpenAIError;
+
+use super::FunctionObject;
 
 /// Represents an `assistant` that can call the model and use tools.
 #[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
@@ -46,7 +48,7 @@ pub struct AssistantToolsRetrieval {
 #[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
 pub struct AssistantToolsFunction {
     pub r#type: String,
-    pub function: ChatCompletionFunctions,
+    pub function: FunctionObject,
 }
 
 #[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
@@ -106,6 +108,7 @@ pub struct ModifyAssistantRequest {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub tools: Option<Vec<AssistantTools>>,
 
+    /// A list of [File](https://platform.openai.com/docs/api-reference/files) IDs attached to this assistant. There can be a maximum of 20 files attached to the assistant. Files are ordered by their creation date in ascending order. If a file was previously attached to the list but does not show up in the list, it will be deleted from the assistant.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub file_ids: Option<Vec<String>>,
 

async-openai/src/types/assistant_impls.rs

@@ -1,6 +1,9 @@
 use crate::types::ChatCompletionFunctions;
 
-use super::{AssistantTools, AssistantToolsCode, AssistantToolsFunction, AssistantToolsRetrieval};
+use super::{
+    AssistantTools, AssistantToolsCode, AssistantToolsFunction, AssistantToolsRetrieval,
+    FunctionObject,
+};
 
 impl From<AssistantToolsCode> for AssistantTools {
     fn from(value: AssistantToolsCode) -> Self {
@@ -45,17 +48,17 @@ impl Default for AssistantToolsFunction {
     }
 }
 
-impl From<ChatCompletionFunctions> for AssistantToolsFunction {
-    fn from(value: ChatCompletionFunctions) -> Self {
+impl From<FunctionObject> for AssistantToolsFunction {
+    fn from(value: FunctionObject) -> Self {
         Self {
             r#type: "function".into(),
             function: value,
         }
     }
 }
 
-impl From<ChatCompletionFunctions> for AssistantTools {
-    fn from(value: ChatCompletionFunctions) -> Self {
+impl From<FunctionObject> for AssistantTools {
+    fn from(value: FunctionObject) -> Self {
         Self::Function(value.into())
     }
 }

async-openai/src/types/audio.rs

@@ -101,7 +101,7 @@ pub struct CreateSpeechRequest {
     /// One of the available [TTS models](https://platform.openai.com/docs/models/tts): `tts-1` or `tts-1-hd`
     pub model: SpeechModel,
 
-    /// The voice to use when generating the audio. Supported voices are `alloy`, `echo`, `fable`, `onyx`, `nova`, and `shimmer`.
+    /// The voice to use when generating the audio. Supported voices are `alloy`, `echo`, `fable`, `onyx`, `nova`, and `shimmer`. Previews of the voices are available in the [Text to speech guide](https://platform.openai.com/docs/guides/text-to-speech/voice-options).
     pub voice: Voice,
 
     /// The format to audio in. Supported formats are mp3, opus, aac, and flac.

async-openai/src/types/chat.rs

@@ -103,7 +103,7 @@ pub struct CompletionUsage {
 #[builder(build_fn(error = "OpenAIError"))]
 pub struct ChatCompletionRequestSystemMessage {
     /// The contents of the system message.
-    pub content: Option<String>,
+    pub content: String,
     /// The role of the messages author, in this case `system`.
     #[builder(default = "Role::System")]
     pub role: Role,
@@ -142,7 +142,7 @@ pub enum ImageUrlDetail {
 pub struct ImageUrl {
     /// Either a URL of the image or the base64 encoded image data.
     pub url: String,
-    /// Specifies the detail level of the image.
+    /// Specifies the detail level of the image. Learn more in the [Vision guide](https://platform.openai.com/docs/guides/vision/low-or-high-fidelity-image-understanding).
     pub detail: ImageUrlDetail,
 }
 
@@ -184,7 +184,7 @@ pub enum ChatCompletionRequestUserMessageContent {
 #[builder(build_fn(error = "OpenAIError"))]
 pub struct ChatCompletionRequestUserMessage {
     /// The contents of the user message.
-    pub content: Option<ChatCompletionRequestUserMessageContent>,
+    pub content: ChatCompletionRequestUserMessageContent,
     /// The role of the messages author, in this case `user`.
     #[builder(default = "Role::User")]
     pub role: Role,
@@ -228,7 +228,7 @@ pub struct ChatCompletionRequestToolMessage {
     #[builder(default = "Role::Tool")]
     pub role: Role,
     /// The contents of the tool message.
-    pub content: Option<String>,
+    pub content: String,
     pub tool_call_id: String,
 }
 
@@ -292,22 +292,38 @@ pub struct ChatCompletionResponseMessage {
 #[builder(setter(into, strip_option), default)]
 #[builder(derive(Debug))]
 #[builder(build_fn(error = "OpenAIError"))]
+#[deprecated]
 pub struct ChatCompletionFunctions {
     /// The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
     pub name: String,
     /// A description of what the function does, used by the model to choose when and how to call the function.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub description: Option<String>,
-    /// The parameters the functions accepts, described as a JSON Schema object.
-    /// See the [guide](https://platform.openai.com/docs/guides/gpt/function-calling) for examples,
-    /// and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for
-    /// documentation about the format.
+    /// The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/text-generation/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format.
     ///
-    /// To describe a function that accepts no parameters, provide the
-    /// value `{\"type\": \"object\", \"properties\": {}}`.
+    /// Omitting `parameters` defines a function with an empty parameter list.
     pub parameters: serde_json::Value,
 }
 
+#[derive(Clone, Serialize, Default, Debug, Deserialize, Builder, PartialEq)]
+#[builder(name = "FunctionObjectArgs")]
+#[builder(pattern = "mutable")]
+#[builder(setter(into, strip_option), default)]
+#[builder(derive(Debug))]
+#[builder(build_fn(error = "OpenAIError"))]
+pub struct FunctionObject {
+    /// The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
+    pub name: String,
+    /// A description of what the function does, used by the model to choose when and how to call the function.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
+    /// The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/text-generation/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format.
+    ///
+    /// Omitting `parameters` defines a function with an empty parameter list.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub parameters: Option<serde_json::Value>,
+}
+
 #[derive(Debug, Deserialize, Serialize, Clone, PartialEq)]
 #[serde(rename_all = "snake_case")]
 pub enum ChatCompletionResponseFormatType {
@@ -344,7 +360,7 @@ pub enum ChatCompletionToolType {
 pub struct ChatCompletionTool {
     #[builder(default = "ChatCompletionToolType::Function")]
     pub r#type: ChatCompletionToolType,
-    pub function: ChatCompletionFunctions,
+    pub function: FunctionObject,
 }
 
 #[derive(Clone, Serialize, Default, Debug, Deserialize, PartialEq)]
@@ -407,13 +423,21 @@ pub struct CreateChatCompletionRequest {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub logit_bias: Option<HashMap<String, serde_json::Value>>, // default: null
 
-    /// The maximum number of [tokens](https://platform.openai.com/tokenizer) to generate in the chat completion.
+    /// Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the `content` of `message`. This option is currently not available on the `gpt-4-vision-preview` model.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub logprobs: Option<bool>,
+
+    /// An integer between 0 and 5 specifying the number of most likely tokens to return at each token position, each with an associated log probability. `logprobs` must be set to `true` if this parameter is used.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub top_logprobs: Option<u8>,
+
+    /// The maximum number of [tokens](https://platform.openai.com/tokenizer) that can be generated in the chat completion.
     ///
-    /// The total length of input tokens and generated tokens is limited by the model's context length. [Example Python code](https://github.com/openai/openai-cookbook/blob/main/examples/How_to_count_tokens_with_tiktoken.ipynb) for counting tokens.
+    /// The total length of input tokens and generated tokens is limited by the model's context length. [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken) for counting tokens.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub max_tokens: Option<u16>,
 
-    /// How many chat completion choices to generate for each input message.
+    /// How many chat completion choices to generate for each input message. Note that you will be charged based on the number of generated tokens across all of the choices. Keep `n` as `1` to minimize costs.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub n: Option<u8>, // min:1, max: 128, default: 1
 
@@ -423,11 +447,11 @@ pub struct CreateChatCompletionRequest {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub presence_penalty: Option<f32>, // min: -2.0, max: 2.0, default 0
 
-    /// An object specifying the format that the model must output.
+    /// An object specifying the format that the model must output. Compatible with `gpt-4-1106-preview` and `gpt-3.5-turbo-1106`.
     ///
     /// Setting to `{ "type": "json_object" }` enables JSON mode, which guarantees the message the model generates is valid JSON.
     ///
-    /// **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in increased latency and appearance of a "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length.
+    /// **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub response_format: Option<ChatCompletionResponseFormat>,
 
@@ -500,6 +524,34 @@ pub enum FinishReason {
     FunctionCall,
 }
 
+#[derive(Debug, Deserialize, Serialize, Clone, PartialEq)]
+pub struct TopLogprobs {
+    /// The token.
+    pub token: String,
+    /// The log probability of this token.
+    pub logprob: f32,
+    /// A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.
+    pub bytes: Option<Vec<u8>>,
+}
+
+#[derive(Debug, Deserialize, Serialize, Clone, PartialEq)]
+pub struct ChatCompletionTokenLogprob {
+    /// The token.
+    pub token: String,
+    /// The log probability of this token.
+    pub logprob: f32,
+    /// A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.
+    pub bytes: Option<Vec<u8>>,
+    ///  List of the most likely tokens and their log probability, at this token position. In rare cases, there may be fewer than the number of requested `top_logprobs` returned.
+    pub top_logprobs: Vec<TopLogprobs>,
+}
+
+#[derive(Debug, Deserialize, Serialize, Clone, PartialEq)]
+pub struct ChatChoiceLogprobs {
+    /// A list of message content tokens with log probability information.
+    pub content: Option<Vec<ChatCompletionTokenLogprob>>,
+}
+
 #[derive(Debug, Deserialize, Serialize, Clone, PartialEq)]
 pub struct ChatChoice {
     /// The index of the choice in the list of choices.
@@ -510,6 +562,8 @@ pub struct ChatChoice {
     /// `content_filter` if content was omitted due to a flag from our content filters,
     /// `tool_calls` if the model called a tool, or `function_call` (deprecated) if the model called a function.
     pub finish_reason: Option<FinishReason>,
+    /// Log probability information for the choice.
+    pub logprobs: Option<ChatChoiceLogprobs>,
 }
 
 /// Represents a chat completion response returned by model, based on the provided input.
@@ -573,11 +627,13 @@ pub struct ChatCompletionStreamResponseDelta {
 }
 
 #[derive(Debug, Deserialize, Serialize, Clone, PartialEq)]
-pub struct ChatCompletionResponseStreamMessage {
+pub struct ChatChoiceStream {
     /// The index of the choice in the list of choices.
     pub index: u32,
     pub delta: ChatCompletionStreamResponseDelta,
     pub finish_reason: Option<FinishReason>,
+    /// Log probability information for the choice.
+    pub logprobs: Option<ChatChoiceLogprobs>,
 }
 
 #[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
@@ -586,7 +642,7 @@ pub struct CreateChatCompletionStreamResponse {
     /// A unique identifier for the chat completion. Each chunk has the same ID.
     pub id: String,
     /// A list of chat completion choices. Can be more than one if `n` is greater than 1.
-    pub choices: Vec<ChatCompletionResponseStreamMessage>,
+    pub choices: Vec<ChatChoiceStream>,
 
     /// The Unix timestamp (in seconds) of when the chat completion was created. Each chunk has the same timestamp.
     pub created: u32,