[Completions API] Add web search options (#370)

* [Completons API] Add web search options

* Update async-openai/src/types/chat.rs

* Update async-openai/src/types/chat.rs

* Update async-openai/src/types/chat.rs

* Update async-openai/src/types/chat.rs

* Update async-openai/src/types/chat.rs

* Update async-openai/src/types/chat.rs

* Update async-openai/src/types/chat.rs

* Update async-openai/src/types/chat.rs

* Update async-openai/src/types/chat.rs

* Update examples/completions-web-search/src/main.rs

* Update examples/completions-web-search/src/main.rs

---------

Co-authored-by: Himanshu Neema <himanshun.iitkgp@gmail.com>

Author: adambenali

async-openai/src/types/chat.rs

@@ -554,6 +554,57 @@ pub enum ChatCompletionToolChoiceOption {
     Named(ChatCompletionNamedToolChoice),
 }
 
+#[derive(Clone, Serialize, Debug, Deserialize, PartialEq, Default)]
+#[serde(rename_all = "lowercase")]
+/// The amount of context window space to use for the search.
+pub enum WebSearchContextSize {
+    Low,
+    #[default]
+    Medium,
+    High,
+}
+
+
+#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
+#[serde(rename_all = "lowercase")]
+pub enum WebSearchUserLocationType {
+
+    Approximate,
+}
+
+/// Approximate location parameters for the search.
+#[derive(Clone, Serialize, Debug, Default, Deserialize, PartialEq)]
+pub struct WebSearchLocation {
+    ///  The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`.
+    pub country: Option<String>,
+    /// Free text input for the region of the user, e.g. `California`.
+    pub region: Option<String>,
+    /// Free text input for the city of the user, e.g. `San Francisco`.
+    pub city: Option<String>,
+    /// The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`.
+    pub timezone: Option<String>,
+}
+
+
+#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
+pub struct WebSearchUserLocation {
+    //  The type of location approximation. Always `approximate`.
+    pub r#type: WebSearchUserLocationType,
+
+    pub approximate: WebSearchLocation,
+}
+
+/// Options for the web search tool.
+#[derive(Clone, Serialize, Debug, Default, Deserialize, PartialEq)]
+pub struct WebSearchOptions {
+    /// High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default.
+
+    pub search_context_size: Option<WebSearchContextSize>,
+
+    /// Approximate location parameters for the search.
+    pub user_location: Option<WebSearchUserLocation>,
+}
+
 #[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
 #[serde(rename_all = "lowercase")]
 pub enum ServiceTier {
@@ -798,6 +849,11 @@ pub struct CreateChatCompletionRequest {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub user: Option<String>,
 
+    /// This tool searches the web for relevant results to use in a response.
+    /// Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat).
+
+    pub web_search_options: Option<WebSearchOptions>,
+
     /// Deprecated in favor of `tool_choice`.
     ///
     /// Controls which (if any) function is called by the model.

examples/completions-web-search/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "completions-web-search"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+
+[dependencies]
+async-openai = {path = "../../async-openai"}
+tokio = { version = "1.43.0", features = ["full"] }

examples/completions-web-search/src/main.rs

@@ -0,0 +1,47 @@
+use async_openai::types::{
+    ChatCompletionRequestUserMessageArgs, WebSearchContextSize, WebSearchOptions,
+    WebSearchUserLocation, WebSearchLocation,
+    WebSearchUserLocationType,
+};
+use async_openai::{types::CreateChatCompletionRequestArgs, Client};
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let client = Client::new();
+    let user_prompt = "What is the weather like today? Be concise.";
+
+    let request = CreateChatCompletionRequestArgs::default()
+        .max_tokens(256u32)
+        .model("gpt-4o-mini-search-preview")
+        .messages([ChatCompletionRequestUserMessageArgs::default()
+            .content(user_prompt)
+            .build()?
+            .into()])
+        .web_search_options(WebSearchOptions {
+            search_context_size: Some(WebSearchContextSize::Low),
+            user_location: Some(WebSearchUserLocation {
+                r#type: WebSearchUserLocationType::Approximate,
+                approximate: WebSearchLocation {
+                    city: Some("Paris".to_string()),
+                    ..Default::default()
+                },
+            }),
+        })
+        .build()?;
+
+    let response_message = client
+        .chat()
+        .create(request)
+        .await?
+        .choices
+        .first()
+        .unwrap()
+        .message
+        .clone();
+
+    if let Some(content) = response_message.content {
+        println!("Response: {}", content);
+    }
+
+    Ok(())
+}