Added docs for models and renamed methods

sdk/openai/inference/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "azure_openai_inference"
-version = "0.1.0"
+version = "1.0.0-beta.1"
 description = "Rust client SDK for Azure OpenAI Inference"
 readme = "README.md"
 authors.workspace = true
@@ -16,7 +16,6 @@ workspace = true
 
 [dependencies]
 azure_core = { workspace = true }
-tokio = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
 async-trait = { workspace = true }

sdk/openai/inference/README.md

@@ -4,6 +4,8 @@
 
 This SDK provides Rust types to interact with both OpenAI and Azure OpenAI services.
 
+Note: Currently request and response models have as few fields as possible, leveraging the server side defaults wherever it can.
+
 ### Features
 
 All features are showcased in the `example` folder of this crate. The following is a list of what is currently supported:

sdk/openai/inference/examples/azure_chat_completions.rs

@@ -23,7 +23,7 @@ pub async fn main() -> Result<()> {
     )?
     .chat_completions_client();
 
-    let chat_completions_request = CreateChatCompletionsRequest::new_with_user_message(
+    let chat_completions_request = CreateChatCompletionsRequest::with_user_message(
         "gpt-4-1106-preview",
         "Tell me a joke about pineapples",
     );

sdk/openai/inference/examples/azure_chat_completions_aad.rs

@@ -25,7 +25,7 @@ async fn main() -> Result<()> {
     )?
     .chat_completions_client();
 
-    let chat_completions_request = CreateChatCompletionsRequest::new_with_user_message(
+    let chat_completions_request = CreateChatCompletionsRequest::with_user_message(
         "gpt-4-1106-preview",
         "Tell me a joke about pineapples",
     );

sdk/openai/inference/examples/azure_chat_completions_stream.rs

@@ -25,7 +25,7 @@ async fn main() -> Result<()> {
     )?
     .chat_completions_client();
 
-    let chat_completions_request = CreateChatCompletionsRequest::new_stream_with_user_message(
+    let chat_completions_request = CreateChatCompletionsRequest::with_user_message_and_stream(
         "gpt-4-1106-preview",
         "Write me an essay that is at least 200 words long on the nutritional values (or lack thereof) of fast food.
         Start the essay by stating 'this essay will be x many words long' where x is the number of words in the essay.",);

sdk/openai/inference/examples/chat_completions.rs

@@ -11,7 +11,7 @@ pub async fn main() -> azure_core::Result<()> {
     let chat_completions_client =
         OpenAIClient::with_key_credential(secret, None)?.chat_completions_client();
 
-    let chat_completions_request = CreateChatCompletionsRequest::new_with_user_message(
+    let chat_completions_request = CreateChatCompletionsRequest::with_user_message(
         "gpt-3.5-turbo-1106",
         "Tell me a joke about pineapples",
     );

sdk/openai/inference/examples/chat_completions_stream.rs

@@ -14,7 +14,7 @@ async fn main() -> Result<()> {
     let chat_completions_client =
         OpenAIClient::with_key_credential(secret, None)?.chat_completions_client();
 
-    let chat_completions_request = CreateChatCompletionsRequest::new_stream_with_user_message(
+    let chat_completions_request = CreateChatCompletionsRequest::with_user_message_and_stream(
         "gpt-3.5-turbo-1106",
         "Write me an essay that is at least 200 words long on the nutritional values (or lack thereof) of fast food.
         Start the essay by stating 'this essay will be x many words long' where x is the number of words in the essay.",);

sdk/openai/inference/src/models/chat_completions.rs

@@ -2,72 +2,115 @@ pub mod request {
 
     use serde::Serialize;
 
+    /// The configuration information for a chat completions request.
+    /// Completions support a wide variety of tasks and generate text that continues from or "completes"
+    /// provided prompt data.
     #[derive(Serialize, Debug, Clone, Default)]
     #[non_exhaustive]
     pub struct CreateChatCompletionsRequest {
         pub messages: Vec<ChatCompletionRequestMessage>,
         pub model: String,
         pub stream: Option<bool>,
-        // pub frequency_penalty: f64,
-        // pub logit_bias: Option<HashMap<String, f64>>,
-        // pub logprobs: Option<bool>,
-        // pub top_logprobs: Option<i32>,
-        // pub max_tokens: Option<i32>,
     }
 
+    /// An abstract representation of  a chat message as provided in a request.
     #[derive(Serialize, Debug, Clone, Default)]
     #[non_exhaustive]
     pub struct ChatCompletionRequestMessageBase {
+        /// An optional name for the participant.
         #[serde(skip)]
         pub name: Option<String>,
+        /// The contents of the message.
         pub content: String, // TODO this should be either a string or ChatCompletionRequestMessageContentPart (a polymorphic type)
     }
 
+    /// A description of the intended purpose of a message within a chat completions interaction.
     #[derive(Serialize, Debug, Clone)]
     #[non_exhaustive]
     #[serde(tag = "role")]
     pub enum ChatCompletionRequestMessage {
+        /// The role that instructs or sets the behavior of the assistant."
         #[serde(rename = "system")]
         System(ChatCompletionRequestMessageBase),
+
+        /// The role that provides input for chat completions.
         #[serde(rename = "user")]
         User(ChatCompletionRequestMessageBase),
     }
 
     impl ChatCompletionRequestMessage {
-        pub fn new_user(content: impl Into<String>) -> Self {
+        /// Creates a new [`ChatCompletionRequestMessage`] with a single `user` message.
+        pub fn with_user_role(content: impl Into<String>) -> Self {
             Self::User(ChatCompletionRequestMessageBase {
                 content: content.into(),
                 name: None,
             })
         }
 
-        pub fn new_system(content: impl Into<String>) -> Self {
+        /// Creates a new [`ChatCompletionRequestMessage`] with a single `system` message.
+        pub fn with_system_role(content: impl Into<String>) -> Self {
             Self::System(ChatCompletionRequestMessageBase {
                 content: content.into(),
                 name: None,
             })
         }
     }
+
     impl CreateChatCompletionsRequest {
-        pub fn new_with_user_message(model: &str, prompt: &str) -> Self {
+        /// Creates a new [`CreateChatCompletionsRequest`] with a single `user` message.
+        ///
+        /// # Example
+        ///
+        /// ```rust
+        /// let request = azure_openai_inference::request::CreateChatCompletionsRequest::with_user_message("gpt-3.5-turbo-1106", "Why couldn't the eagles take Frodo directly to mount doom?");
+        /// ```
+        pub fn with_user_message(model: &str, prompt: &str) -> Self {
             Self {
                 model: model.to_string(),
-                messages: vec![ChatCompletionRequestMessage::new_user(prompt)],
+                messages: vec![ChatCompletionRequestMessage::with_user_role(prompt)],
                 ..Default::default()
             }
         }
 
-        pub fn new_stream_with_user_message(
+        /// Creates a new [`CreateChatCompletionsRequest`] with a single `system` message whose response will be streamed.
+        ///
+        /// # Example
+        ///
+        /// ```rust
+        /// let request = azure_openai_inference::request::CreateChatCompletionsRequest::with_user_message_and_stream("gpt-3.5-turbo-1106", "Why couldn't the eagles take Frodo directly to mount doom?");
+        /// ```
+        pub fn with_user_message_and_stream(
             model: impl Into<String>,
             prompt: impl Into<String>,
         ) -> Self {
             Self {
                 model: model.into(),
-                messages: vec![ChatCompletionRequestMessage::new_user(prompt)],
+                messages: vec![ChatCompletionRequestMessage::with_user_role(prompt)],
                 stream: Some(true),
                 ..Default::default()
             }
         }
+
+        /// Creates a new [`CreateChatCompletionsRequest`] with a list of messages.
+        ///
+        /// # Example
+        /// ```rust
+        /// let request = azure_openai_inference::request::CreateChatCompletionsRequest::with_messages(
+        ///     "gpt-3.5-turbo-1106",
+        ///     vec![
+        ///         azure_openai_inference::request::ChatCompletionRequestMessage::with_system_role("You are a good math tutor who explains things briefly."),
+        ///         azure_openai_inference::request::ChatCompletionRequestMessage::with_user_role("What is the value of 'x' in the equation: '2x + 3 = 11'?"),
+        ///    ]);
+        pub fn with_messages(
+            model: impl Into<String>,
+            messages: Vec<ChatCompletionRequestMessage>,
+        ) -> Self {
+            Self {
+                model: model.into(),
+                messages,
+                ..Default::default()
+            }
+        }
     }
 }
 
@@ -76,44 +119,66 @@ pub mod response {
     use azure_core::Model;
     use serde::Deserialize;
 
+    /// Representation of the response data from a chat completions request.
+    /// Completions support a wide variety of tasks and generate text that continues from or "completes"
+    /// provided prompt data.
     #[derive(Debug, Clone, Deserialize, Model)]
     #[non_exhaustive]
     pub struct CreateChatCompletionsResponse {
+        /// The collection of completions choices associated with this completions response.
+        /// Generally, `n` choices are generated per provided prompt with a default value of 1.
+        /// Token limits and other settings may limit the number of choices generated.
         pub choices: Vec<ChatCompletionChoice>,
     }
 
+    /// The representation of a single prompt completion as part of an overall chat completions request.
+    /// Generally, `n` choices are generated per provided prompt with a default value of 1.
+    /// Token limits and other settings may limit the number of choices generated.
     #[derive(Debug, Clone, Deserialize)]
     #[non_exhaustive]
     pub struct ChatCompletionChoice {
+        /// The chat message for a given chat completions prompt.
         pub message: ChatCompletionResponseMessage,
     }
 
     #[derive(Debug, Clone, Deserialize)]
     #[non_exhaustive]
     pub struct ChatCompletionResponseMessage {
+        /// The content of the message.
         pub content: Option<String>,
+
+        /// The chat role associated with the message.
         pub role: String,
     }
 
     // region: --- Streaming
+    /// Represents a streamed chunk of a chat completion response returned by model, based on the provided input.
     #[derive(Debug, Clone, Deserialize)]
     #[non_exhaustive]
     pub struct CreateChatCompletionsStreamResponse {
+        /// A list of chat completion choices. Can contain more than one elements if `n` is greater than 1.
         pub choices: Vec<ChatCompletionStreamChoice>,
     }
 
+    /// A chat completion delta generated by streamed model responses.
     #[derive(Debug, Clone, Deserialize)]
     #[non_exhaustive]
     pub struct ChatCompletionStreamChoice {
+        /// The delta message content for a streaming response.
         pub delta: Option<ChatCompletionStreamResponseMessage>,
     }
 
+    /// A chat completion delta generated by streamed model responses.
+    ///
+    /// Note: all fields are optional because in a streaming scenario there is no guarantee of what is present in the model.
     #[derive(Debug, Clone, Deserialize)]
     #[non_exhaustive]
     pub struct ChatCompletionStreamResponseMessage {
+        /// The content of the chunk message.
         pub content: Option<String>,
+
+        /// The chat role associated with the message.
         pub role: Option<String>,
     }
-
     // endregion: Streaming
 }