ci(release): v0.10.0

* add the 'system' and 'tool' message roles (see: https://docs.mistral.ai/capabilities/completion/ )

* docs(chat): add offical doc link in ChatMessageRole

* ci(github): listen to pull_request event in Test workflow

---------

Co-authored-by: Ivan Gabriele <ivan.gabriele@protonmail.com>

.github/workflows/test.yml

@@ -1,6 +1,8 @@
 name: Test
 
-on: push
+on:
+  pull_request:
+  push:
 
 jobs:
   test:

CHANGELOG.md

@@ -1,3 +1,20 @@
+## [0.10.0](https://github.com/ivangabriele/mistralai-client-rs/compare/v0.9.0...v) (2024-06-07)
+
+### ⚠ BREAKING CHANGES
+
+* **chat:** - `Chat::ChatParams.safe_prompt` & `Chat::ChatRequest.safe_prompt` are now `bool` instead of `Option<bool>`. Default is `false`.
+- `Chat::ChatParams.temperature` & `Chat::ChatRequest.temperature` are now `f32` instead of `Option<f32>`. Default is `0.7`.
+- `Chat::ChatParams.top_p` & `Chat::ChatRequest.top_p` are now `f32` instead of `Option<f32>`. Default is `1.0`.
+
+### Features
+
+* **chat:** add response_format for JSON return values ([85c3611](https://github.com/ivangabriele/mistralai-client-rs/commit/85c3611afbbe8df30dfc7512cc381ed304ce4024))
+* **chat:** add the 'system' and 'tool' message roles ([#10](https://github.com/ivangabriele/mistralai-client-rs/issues/10)) ([2fc0642](https://github.com/ivangabriele/mistralai-client-rs/commit/2fc0642a5e4c024b15710acaab7735480e8dfe6a))
+* **chat:** change safe_prompt, temperature & top_p to non-Option types ([cf68a77](https://github.com/ivangabriele/mistralai-client-rs/commit/cf68a773201ebe0e802face52af388711acf0c27))
+
+### Bug Fixes
+
+* **chat:** skip serializing tool_calls if null, to avoid 422 error ([da5fe54](https://github.com/ivangabriele/mistralai-client-rs/commit/da5fe54115ce622379776661a440e2708b24810c))
 ## [0.9.0](https://github.com/ivangabriele/mistralai-client-rs/compare/v0.8.0...v) (2024-04-13)
 
 

Cargo.toml

@@ -2,7 +2,7 @@
 name = "mistralai-client"
 description = "Mistral AI API client library for Rust (unofficial)."
 license = "Apache-2.0"
-version = "0.9.0"
+version = "0.10.0"
 
 edition = "2021"
 rust-version = "1.76.0"

Makefile

@@ -53,20 +53,20 @@ release-major:
 	$(call RELEASE_TEMPLATE,major)
 
 test:
-	@$(source_env_if_not_ci)
+	@$(source_env_if_not_ci) && \
 	cargo test --no-fail-fast
 test-cover:
-	@$(source_env_if_not_ci)
+	@$(source_env_if_not_ci) && \
 	cargo llvm-cov
 test-doc:
-	@$(source_env_if_not_ci)
+	@$(source_env_if_not_ci) && \
 	cargo test --doc --no-fail-fast
 test-examples:
-	@$(source_env_if_not_ci)
-	@for example in $$(ls examples/*.rs | sed 's/examples\/\(.*\)\.rs/\1/'); do \
+	@$(source_env_if_not_ci) && \
+	for example in $$(ls examples/*.rs | sed 's/examples\/\(.*\)\.rs/\1/'); do \
 		echo "Running $$example"; \
 		cargo run --example $$example; \
 	done
 test-watch:
-	@source ./.env
+	@source ./.env && \
 	cargo watch -x "test -- --nocapture"

README.md

@@ -7,6 +7,10 @@
 
 Rust client for the Mistral AI API.
 
+> [!IMPORTANT]  
+> While we are in v0, minor versions may introduce breaking changes.  
+> Please, refer to the [CHANGELOG.md](./CHANGELOG.md) for more information.
+
 ---
 
 - [Supported APIs](#supported-apis)
@@ -102,7 +106,7 @@ fn main() {
         tool_calls: None,
     }];
     let options = ChatParams {
-        temperature: Some(0.0),
+        temperature: 0.0,
         random_seed: Some(42),
         ..Default::default()
     };
@@ -134,7 +138,7 @@ async fn main() {
         tool_calls: None,
     }];
     let options = ChatParams {
-        temperature: Some(0.0),
+        temperature: 0.0,
         random_seed: Some(42),
         ..Default::default()
     };
@@ -174,7 +178,7 @@ async fn main() {
         tool_calls: None,
     }];
     let options = ChatParams {
-        temperature: Some(0.0),
+        temperature: 0.0,
         random_seed: Some(42),
         ..Default::default()
     };
@@ -259,7 +263,7 @@ fn main() {
         tool_calls: None,
     }];
     let options = ChatParams {
-        temperature: Some(0.0),
+        temperature: 0.0,
         random_seed: Some(42),
         tool_choice: Some(ToolChoice::Auto),
         tools: Some(tools),
@@ -336,7 +340,7 @@ async fn main() {
         tool_calls: None,
     }];
     let options = ChatParams {
-        temperature: Some(0.0),
+        temperature: 0.0,
         random_seed: Some(42),
         tool_choice: Some(ToolChoice::Auto),
         tools: Some(tools),

README.template.md

@@ -7,6 +7,10 @@
 
 Rust client for the Mistral AI API.
 
+> [!IMPORTANT]  
+> While we are in v0, minor versions may introduce breaking changes.  
+> Please, refer to the [CHANGELOG.md](./CHANGELOG.md) for more information.
+
 ---
 
 - [Supported APIs](#supported-apis)

examples/chat.rs

@@ -15,7 +15,7 @@ fn main() {
         tool_calls: None,
     }];
     let options = ChatParams {
-        temperature: Some(0.0),
+        temperature: 0.0,
         random_seed: Some(42),
         ..Default::default()
     };

examples/chat_async.rs

@@ -16,7 +16,7 @@ async fn main() {
         tool_calls: None,
     }];
     let options = ChatParams {
-        temperature: Some(0.0),
+        temperature: 0.0,
         random_seed: Some(42),
         ..Default::default()
     };

examples/chat_with_function_calling.rs

@@ -53,7 +53,7 @@ fn main() {
         tool_calls: None,
     }];
     let options = ChatParams {
-        temperature: Some(0.0),
+        temperature: 0.0,
         random_seed: Some(42),
         tool_choice: Some(ToolChoice::Auto),
         tools: Some(tools),

examples/chat_with_function_calling_async.rs

@@ -54,7 +54,7 @@ async fn main() {
         tool_calls: None,
     }];
     let options = ChatParams {
-        temperature: Some(0.0),
+        temperature: 0.0,
         random_seed: Some(42),
         tool_choice: Some(ToolChoice::Auto),
         tools: Some(tools),

examples/chat_with_streaming.rs

@@ -18,7 +18,7 @@ async fn main() {
         tool_calls: None,
     }];
     let options = ChatParams {
-        temperature: Some(0.0),
+        temperature: 0.0,
         random_seed: Some(42),
         ..Default::default()
     };

src/v1/chat.rs

@@ -9,6 +9,7 @@ use crate::v1::{common, constants, tool};
 pub struct ChatMessage {
     pub role: ChatMessageRole,
     pub content: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub tool_calls: Option<Vec<tool::ToolCall>>,
 }
 impl ChatMessage {
@@ -29,37 +30,101 @@ impl ChatMessage {
     }
 }
 
+/// See the [Mistral AI API documentation](https://docs.mistral.ai/capabilities/completion/#chat-messages) for more information.
 #[derive(Clone, Debug, Eq, PartialEq, Deserialize, Serialize)]
 pub enum ChatMessageRole {
+    #[serde(rename = "system")]
+    System,
     #[serde(rename = "assistant")]
     Assistant,
     #[serde(rename = "user")]
     User,
+    #[serde(rename = "tool")]
+    Tool,
+}
+
+/// The format that the model must output.
+///
+/// See the [API documentation](https://docs.mistral.ai/api/#operation/createChatCompletion) for more information.
+#[derive(Debug, Serialize, Deserialize)]
+pub struct ResponseFormat {
+    #[serde(rename = "type")]
+    pub type_: String,
+}
+impl ResponseFormat {
+    pub fn json_object() -> Self {
+        Self {
+            type_: "json_object".to_string(),
+        }
+    }
 }
 
 // -----------------------------------------------------------------------------
 // Request
 
+/// The parameters for the chat request.
+///
+/// See the [API documentation](https://docs.mistral.ai/api/#operation/createChatCompletion) for more information.
 #[derive(Debug)]
 pub struct ChatParams {
+    /// The maximum number of tokens to generate in the completion.
+    ///
+    /// Defaults to `None`.
     pub max_tokens: Option<u32>,
+    /// The seed to use for random sampling. If set, different calls will generate deterministic results.
+    ///
+    /// Defaults to `None`.
     pub random_seed: Option<u32>,
-    pub safe_prompt: Option<bool>,
-    pub temperature: Option<f32>,
+    /// The format that the model must output.
+    ///
+    /// Defaults to `None`.
+    pub response_format: Option<ResponseFormat>,
+    /// Whether to inject a safety prompt before all conversations.
+    ///
+    /// Defaults to `false`.
+    pub safe_prompt: bool,
+    /// What sampling temperature to use, between `Some(0.0)` and `Some(1.0)`.
+    ///
+    /// Defaults to `0.7`.
+    pub temperature: f32,
+    /// Specifies if/how functions are called.
+    ///
+    /// Defaults to `None`.
     pub tool_choice: Option<tool::ToolChoice>,
+    /// A list of available tools for the model.
+    ///
+    /// Defaults to `None`.
     pub tools: Option<Vec<tool::Tool>>,
-    pub top_p: Option<f32>,
+    /// Nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass.
+    ///
+    /// Defaults to `1.0`.
+    pub top_p: f32,
 }
 impl Default for ChatParams {
     fn default() -> Self {
         Self {
             max_tokens: None,
             random_seed: None,
-            safe_prompt: None,
-            temperature: None,
+            safe_prompt: false,
+            response_format: None,
+            temperature: 0.7,
             tool_choice: None,
             tools: None,
-            top_p: None,
+            top_p: 1.0,
+        }
+    }
+}
+impl ChatParams {
+    pub fn json_default() -> Self {
+        Self {
+            max_tokens: None,
+            random_seed: None,
+            safe_prompt: false,
+            response_format: None,
+            temperature: 0.7,
+            tool_choice: None,
+            tools: None,
+            top_p: 1.0,
         }
     }
 }
@@ -74,20 +139,15 @@ pub struct ChatRequest {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub random_seed: Option<u32>,
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub safe_prompt: Option<bool>,
+    pub response_format: Option<ResponseFormat>,
+    pub safe_prompt: bool,
     pub stream: bool,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub temperature: Option<f32>,
+    pub temperature: f32,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub tool_choice: Option<tool::ToolChoice>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub tools: Option<Vec<tool::Tool>>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub top_p: Option<f32>,
-    // TODO Check this prop (seen in official Python client but not in API doc).
-    // pub tool_choice: Option<String>,
-    // TODO Check this prop (seen in official Python client but not in API doc).
-    // pub response_format: Option<String>,
+    pub top_p: f32,
 }
 impl ChatRequest {
     pub fn new(
@@ -104,6 +164,7 @@ impl ChatRequest {
             tool_choice,
             tools,
             top_p,
+            response_format,
         } = options.unwrap_or_default();
 
         Self {
@@ -118,6 +179,7 @@ impl ChatRequest {
             tool_choice,
             tools,
             top_p,
+            response_format,
         }
     }
 }

src/v1/tool.rs

@@ -115,12 +115,16 @@ pub enum ToolType {
     Function,
 }
 
+/// An enum representing how functions should be called.
 #[derive(Clone, Debug, Eq, PartialEq, Deserialize, Serialize)]
 pub enum ToolChoice {
+    /// The model is forced to call a function.
     #[serde(rename = "any")]
     Any,
+    /// The model can choose to either generate a message or call a function.
     #[serde(rename = "auto")]
     Auto,
+    /// The model won't call a function and will generate a message instead.
     #[serde(rename = "none")]
     None,
 }

tests/v1_client_chat_async_test.rs

@@ -16,10 +16,10 @@ async fn test_client_chat_async() {
 
     let model = Model::OpenMistral7b;
     let messages = vec![ChatMessage::new_user_message(
-        "Just guess the next word: \"Eiffel ...\"?",
+        "Guess the next word: \"Eiffel ...\"?",
     )];
     let options = ChatParams {
-        temperature: Some(0.0),
+        temperature: 0.0,
         random_seed: Some(42),
         ..Default::default()
     };
@@ -37,8 +37,12 @@ async fn test_client_chat_async() {
     expect!(response.choices[0].finish_reason.clone()).to_be(ChatResponseChoiceFinishReason::Stop);
 
     expect!(response.choices[0].message.role.clone()).to_be(ChatMessageRole::Assistant);
-    expect!(response.choices[0].message.content.clone())
-        .to_be("Tower. The Eiffel Tower is a famous landmark in Paris, France.".to_string());
+    expect!(response.choices[0]
+        .message
+        .content
+        .clone()
+        .contains("Tower"))
+    .to_be(true);
 
     expect!(response.usage.prompt_tokens).to_be_greater_than(0);
     expect!(response.usage.completion_tokens).to_be_greater_than(0);
@@ -66,7 +70,7 @@ async fn test_client_chat_async_with_function_calling() {
         "What's the current temperature in Paris?",
     )];
     let options = ChatParams {
-        temperature: Some(0.0),
+        temperature: 0.0,
         random_seed: Some(42),
         tool_choice: Some(ToolChoice::Any),
         tools: Some(tools),

tests/v1_client_chat_test.rs

@@ -16,10 +16,10 @@ fn test_client_chat() {
 
     let model = Model::OpenMistral7b;
     let messages = vec![ChatMessage::new_user_message(
-        "Just guess the next word: \"Eiffel ...\"?",
+        "Guess the next word: \"Eiffel ...\"?",
     )];
     let options = ChatParams {
-        temperature: Some(0.0),
+        temperature: 0.0,
         random_seed: Some(42),
         ..Default::default()
     };
@@ -31,8 +31,12 @@ fn test_client_chat() {
     expect!(response.choices.len()).to_be(1);
     expect!(response.choices[0].index).to_be(0);
     expect!(response.choices[0].message.role.clone()).to_be(ChatMessageRole::Assistant);
-    expect!(response.choices[0].message.content.clone())
-        .to_be("Tower. The Eiffel Tower is a famous landmark in Paris, France.".to_string());
+    expect!(response.choices[0]
+        .message
+        .content
+        .clone()
+        .contains("Tower"))
+    .to_be(true);
     expect!(response.choices[0].finish_reason.clone()).to_be(ChatResponseChoiceFinishReason::Stop);
     expect!(response.usage.prompt_tokens).to_be_greater_than(0);
     expect!(response.usage.completion_tokens).to_be_greater_than(0);
@@ -60,7 +64,7 @@ fn test_client_chat_with_function_calling() {
         "What's the current temperature in Paris?",
     )];
     let options = ChatParams {
-        temperature: Some(0.0),
+        temperature: 0.0,
         random_seed: Some(42),
         tool_choice: Some(ToolChoice::Auto),
         tools: Some(tools),