Expose OpenAI basic country/region web search parameters

This is generic so that it also works with Grok (for country limiting).

Author: kzu

readme.md

@@ -62,6 +62,25 @@ var options = new ChatOptions
 var response = await grok.GetResponseAsync(messages, options);
 ```
 
+We also provide an OpenAI-compatible `WebSearchTool` that can be used to restrict 
+the search to a specific country in a way that works with both Grok and OpenAI:
+
+```csharp
+var options = new ChatOptions
+{
+    Tools = [new WebSearchTool("AR")] // 👈 search in Argentina
+};
+```
+
+This is equivalent to the following when used with a Grok client:
+```csharp
+var options = new ChatOptions
+{
+    //                                           👇 search in Argentina
+    Tools = [new GrokSearchTool(GrokSearch.On) { Country = "AR" }] 
+};
+```
+
 ### Advanced Live Search
 
 To configure advanced live search options, beyond the `On|Auto|Off` settings 
@@ -127,9 +146,22 @@ var options = new ChatOptions
 };
 
 var response = await chat.GetResponseAsync(messages, options);
+```
+
+Similar to the Grok client, we provide the `WebSearchTool` to enable search customization 
+in OpenAI too:
 
+```csharp
+var options = new ChatOptions
+{
+    //                          👇 search in Argentina, Bariloche region
+    Tools = [new WebSearchTool("AR") { Region = "Bariloche" }] 
+};
 ```
 
+If country/region hints to the model are not needed, you can use the built-in M.E.AI 
+`HostedWebSearchTool` instead, which is a more generic tool.
+
 ## Observing Request/Response
 
 The underlying HTTP pipeline provided by the Azure SDK allows setting up 

src/AI.Tests/OpenAITests.cs

@@ -66,4 +66,51 @@ public async Task OpenAIThinks()
             Assert.Equal("medium", search["effort"]?.GetValue<string>());
         });
     }
+
+    [SecretsFact("OPENAI_API_KEY")]
+    public async Task WebSearchCountry()
+    {
+        var messages = new Chat()
+        {
+            { "system", "Sos un asistente del Cerro Catedral, usas la funcionalidad de Live Search en el sitio oficial." },
+            { "system", $"Hoy es {DateTime.Now.ToString("o")}." },
+            { "system",
+                """
+                Web search sources: 
+                https://catedralaltapatagonia.com/parte-de-nieve/
+                https://catedralaltapatagonia.com/tarifas/
+                https://catedralaltapatagonia.com/
+
+                DO NOT USE https://partediario.catedralaltapatagonia.com/partediario for web search, it's **OBSOLETE**.
+                """},
+            { "user", "Cuanto cuesta el pase diario en el Catedral hoy?" },
+        };
+
+        var requests = new List<JsonNode>();
+        var responses = new List<JsonNode>();
+
+        var chat = new OpenAIChatClient(Configuration["OPENAI_API_KEY"]!, "gpt-4.1",
+            OpenAIClientOptions.Observable(requests.Add, responses.Add).WriteTo(output));
+
+        var options = new ChatOptions
+        {
+            Tools = [new WebSearchTool("AR") { Region = "Bariloche" }]
+        };
+
+        var response = await chat.GetResponseAsync(messages, options);
+        var text = response.Text;
+
+        // Citations include catedralaltapatagonia.com at least as a web search source
+        Assert.Single(responses);
+        var node = responses[0];
+        Assert.NotNull(node);
+        var citations = Assert.IsType<JsonArray>(node["citations"], false);
+        var catedral = citations.Where(x => x != null).Any(x => x!.ToString().Contains("catedralaltapatagonia.com", StringComparison.Ordinal));
+
+        Assert.True(catedral, "Expected at least one citation to catedralaltapatagonia.com");
+
+        // Uses the default model set by the client when we asked for it
+        Assert.Equal("grok-3", response.ModelId);
+    }
+
 }

src/AI/Grok/GrokChatClient.cs

@@ -64,6 +64,14 @@ IChatClient GetChatClient(string modelId) => clients.GetOrAdd(modelId, model
                     Mode = search.Value
                 };
             }
+            else if (tool is null && options.Tools?.OfType<WebSearchTool>().FirstOrDefault() is { } web)
+            {
+                searchOptions = new GrokChatWebSearchOptions
+                {
+                    Mode = GrokSearch.Auto,
+                    Sources = [new GrokWebSource { Country = web.Country }]
+                };
+            }
             else if (tool is null && options.Tools?.OfType<HostedWebSearchTool>().FirstOrDefault() is not null)
             {
                 searchOptions = new GrokChatWebSearchOptions

src/AI/WebSearchTool.cs

@@ -0,0 +1,66 @@
+using Microsoft.Extensions.AI;
+using OpenAI.Responses;
+
+namespace Devlooped.Extensions.AI;
+
+/// <summary>
+/// Basic web search tool that can limit the search to a specific country.
+/// </summary>
+public class WebSearchTool : HostedWebSearchTool
+{
+    Dictionary<string, object?> additionalProperties;
+    string? region;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="WebSearchTool"/> class with the specified country.
+    /// </summary>
+    /// <param name="country">ISO alpha-2 country code.</param>
+    public WebSearchTool(string country)
+    {
+        Country = country;
+        additionalProperties = new Dictionary<string, object?>
+        {
+            { nameof(WebSearchToolLocation), WebSearchToolLocation.CreateApproximateLocation(country) }
+        };
+    }
+
+    /// <summary>
+    /// Sets the user's country for web search results, using the ISO alpha-2 code.
+    /// </summary>
+    public string Country { get; }
+
+    /// <summary>
+    /// Optional free text additional information about the region to be used in the search. 
+    /// Not all providers support this property. 
+    /// </summary>
+    /// <remarks>
+    /// <para>Support for the <see cref="Region"/> property:</para>
+    /// <list type="table">
+    /// <listheader>
+    /// <term>Provider</term>
+    /// <term>Supported</term>
+    /// </listheader>
+    /// <item>
+    /// <term>OpenAI</term>
+    /// <term>Yes (<see href="https://platform.openai.com/docs/guides/tools-web-search?api-mode=responses#user-location">user location</see>)</term>
+    /// </item>
+    /// <item>
+    /// <term>Grok</term>
+    /// <term>No</term>
+    /// </item>
+    /// </list>
+    /// </remarks>
+    public string? Region
+    {
+        get => region;
+        set
+        {
+            region = value;
+            additionalProperties[nameof(WebSearchToolLocation)] =
+                WebSearchToolLocation.CreateApproximateLocation(Country, value);
+        }
+    }
+
+    /// <inheritdoc/>
+    public override IReadOnlyDictionary<string, object?> AdditionalProperties => additionalProperties;
+}