Add support for OpenAI web search options and Grok compat

* Add OpenAI/Grok subnamespace: helps organize functionality areas
* Adds OpenAI WebSearchTool-specific extensions under that namespace: region, city, timezone, context size.
* Cross-provider compatibility by interpreting WebSearchTool as GrokSearch(Auto) with a GrokWebSource(country).

Author: kzu

readme.md

@@ -148,19 +148,31 @@ var options = new ChatOptions
 var response = await chat.GetResponseAsync(messages, options);
 ```
 
+### Web Search
+
 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" }] 
+    Tools = [new WebSearchTool("AR")
+    {
+        Region = "Bariloche",   // 👈 Bariloche region
+        TimeZone = "America/Argentina/Buenos_Aires", // 👈 IANA timezone
+        ContextSize = WebSearchContextSize.High      // 👈 high search context size
+    }]
 };
 ```
 
-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.
+> [!NOTE]
+> This enables all features supported by the [Web search](https://platform.openai.com/docs/guides/tools-web-search) 
+> feature in OpenAI.
+
+If advanced search settings are not needed, you can use the built-in M.E.AI `HostedWebSearchTool` 
+instead, which is a more generic tool and provides the basics out of the box.
+
 
 ## Observing Request/Response
 

src/AI.Tests/GrokTests.cs

@@ -1,6 +1,8 @@
 using System.Text.Json.Nodes;
+using Devlooped.Extensions.AI.Grok;
 using Microsoft.Extensions.AI;
 using static ConfigurationExtensions;
+using OpenAIClientOptions = OpenAI.OpenAIClientOptions;
 
 namespace Devlooped.Extensions.AI;
 
@@ -51,7 +53,7 @@ public async Task GrokInvokesToolAndSearch()
         var requests = new List<JsonNode>();
         var responses = new List<JsonNode>();
 
-        var grok = new GrokChatClient(Configuration["XAI_API_KEY"]!, "grok-3", OpenAI.OpenAIClientOptions
+        var grok = new GrokChatClient(Configuration["XAI_API_KEY"]!, "grok-3", OpenAIClientOptions
                     .Observable(requests.Add, responses.Add)
                     .WriteTo(output))
             .AsBuilder()
@@ -105,7 +107,7 @@ public async Task GrokInvokesHostedSearchTool()
         var requests = new List<JsonNode>();
         var responses = new List<JsonNode>();
 
-        var grok = new GrokChatClient(Configuration["XAI_API_KEY"]!, "grok-3", OpenAI.OpenAIClientOptions
+        var grok = new GrokChatClient(Configuration["XAI_API_KEY"]!, "grok-3", OpenAIClientOptions
             .Observable(requests.Add, responses.Add)
             .WriteTo(output));
 
@@ -185,7 +187,7 @@ public async Task GrokInvokesSpecificSearchUrl()
         var requests = new List<JsonNode>();
         var responses = new List<JsonNode>();
 
-        var grok = new GrokChatClient(Configuration["XAI_API_KEY"]!, "grok-3", OpenAI.OpenAIClientOptions
+        var grok = new GrokChatClient(Configuration["XAI_API_KEY"]!, "grok-3", OpenAIClientOptions
             .Observable(requests.Add, responses.Add)
             .WriteTo(output));
 

src/AI.Tests/OpenAITests.cs

@@ -1,6 +1,8 @@
 using System.Text.Json.Nodes;
+using Devlooped.Extensions.AI.OpenAI;
 using Microsoft.Extensions.AI;
 using OpenAI;
+using OpenAI.Responses;
 using static ConfigurationExtensions;
 
 namespace Devlooped.Extensions.AI;
@@ -68,7 +70,7 @@ public async Task OpenAIThinks()
     }
 
     [SecretsFact("OPENAI_API_KEY")]
-    public async Task WebSearchCountry()
+    public async Task WebSearchCountryHighContext()
     {
         var messages = new Chat()
         {
@@ -94,23 +96,28 @@ public async Task WebSearchCountry()
 
         var options = new ChatOptions
         {
-            Tools = [new WebSearchTool("AR") { Region = "Bariloche" }]
+            Tools = [new WebSearchTool("AR")
+            {
+                Region = "Bariloche",
+                TimeZone = "America/Argentina/Buenos_Aires",
+                ContextSize = WebSearchContextSize.High
+            }]
         };
 
         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));
+        var raw = Assert.IsType<OpenAIResponse>(response.RawRepresentation);
+        Assert.NotEmpty(raw.OutputItems.OfType<WebSearchCallResponseItem>());
 
-        Assert.True(catedral, "Expected at least one citation to catedralaltapatagonia.com");
+        var assistant = raw.OutputItems.OfType<MessageResponseItem>().Where(x => x.Role == MessageRole.Assistant).FirstOrDefault();
+        Assert.NotNull(assistant);
 
-        // Uses the default model set by the client when we asked for it
-        Assert.Equal("grok-3", response.ModelId);
-    }
+        var content = Assert.Single(assistant.Content);
+        Assert.NotEmpty(content.OutputTextAnnotations);
+        Assert.Contains(content.OutputTextAnnotations,
+            x => x.Kind == ResponseMessageAnnotationKind.UriCitation &&
+                x.UriCitationUri.StartsWith("https://catedralaltapatagonia.com/tarifas/"));
 
+    }
 }

src/AI.Tests/RetrievalTests.cs

@@ -11,11 +11,11 @@ public class RetrievalTests(ITestOutputHelper output)
     [InlineData("gpt-4.1-nano", "What's the battery life in an iPhone 15?", true)]
     public async Task CanRetrieveContent(string model, string question, bool empty = false)
     {
-        var client = new OpenAI.OpenAIClient(Configuration["OPENAI_API_KEY"]);
+        var client = new global::OpenAI.OpenAIClient(Configuration["OPENAI_API_KEY"]);
         var store = client.GetVectorStoreClient().CreateVectorStore(true);
         try
         {
-            var file = client.GetOpenAIFileClient().UploadFile("Content/LNS0004592.md", OpenAI.Files.FileUploadPurpose.Assistants);
+            var file = client.GetOpenAIFileClient().UploadFile("Content/LNS0004592.md", global::OpenAI.Files.FileUploadPurpose.Assistants);
             try
             {
                 client.GetVectorStoreClient().AddFileToVectorStore(store.VectorStoreId, file.Value.Id, true);

src/AI.Tests/ToolsTests.cs

@@ -1,4 +1,5 @@
 using System.ComponentModel;
+using Devlooped.Extensions.AI.OpenAI;
 using Microsoft.Extensions.AI;
 using static ConfigurationExtensions;
 
@@ -18,7 +19,7 @@ public async Task RunToolResult()
         };
 
         var client = new OpenAIChatClient(Configuration["OPENAI_API_KEY"]!, "gpt-4.1",
-            OpenAI.OpenAIClientOptions.WriteTo(output))
+            global::OpenAI.OpenAIClientOptions.WriteTo(output))
             .AsBuilder()
             .UseFunctionInvocation()
             .Build();
@@ -50,7 +51,7 @@ public async Task RunToolTerminateResult()
         };
 
         var client = new OpenAIChatClient(Configuration["OPENAI_API_KEY"]!, "gpt-4.1",
-            OpenAI.OpenAIClientOptions.WriteTo(output))
+            global::OpenAI.OpenAIClientOptions.WriteTo(output))
             .AsBuilder()
             .UseFunctionInvocation()
             .Build();
@@ -82,7 +83,7 @@ public async Task RunToolExceptionOutcome()
         };
 
         var client = new OpenAIChatClient(Configuration["OPENAI_API_KEY"]!, "gpt-4.1",
-            OpenAI.OpenAIClientOptions.WriteTo(output))
+            global::OpenAI.OpenAIClientOptions.WriteTo(output))
             .AsBuilder()
             .UseFunctionInvocation()
             .Build();

src/AI/Grok/GrokChatClient.cs

@@ -7,7 +7,7 @@
 using Microsoft.Extensions.AI;
 using OpenAI;
 
-namespace Devlooped.Extensions.AI;
+namespace Devlooped.Extensions.AI.Grok;
 
 /// <summary>
 /// An <see cref="IChatClient"/> implementation for Grok.
@@ -100,9 +100,9 @@ IChatClient GetChatClient(string modelId) => clients.GetOrAdd(modelId, model
             {
                 result.ReasoningEffortLevel = grok.ReasoningEffort switch
                 {
-                    ReasoningEffort.High => OpenAI.Chat.ChatReasoningEffortLevel.High,
+                    ReasoningEffort.High => global::OpenAI.Chat.ChatReasoningEffortLevel.High,
                     // Grok does not support Medium, so we map it to Low too
-                    _ => OpenAI.Chat.ChatReasoningEffortLevel.Low,
+                    _ => global::OpenAI.Chat.ChatReasoningEffortLevel.Low,
                 };
             }
 
@@ -119,7 +119,7 @@ void IDisposable.Dispose() { }
     // Allows creating the base OpenAIClient with a pre-created pipeline.
     class PipelineClient(ClientPipeline pipeline, OpenAIClientOptions options) : OpenAIClient(pipeline, options) { }
 
-    class GrokChatWebSearchOptions : OpenAI.Chat.ChatWebSearchOptions
+    class GrokChatWebSearchOptions : global::OpenAI.Chat.ChatWebSearchOptions
     {
         public GrokSearch Mode { get; set; } = GrokSearch.Auto;
         public DateOnly? FromDate { get; set; }
@@ -174,7 +174,7 @@ class LowercaseNamingPolicy : JsonNamingPolicy
         }
     }
 
-    class GrokCompletionOptions : OpenAI.Chat.ChatCompletionOptions
+    class GrokCompletionOptions : global::OpenAI.Chat.ChatCompletionOptions
     {
         protected override void JsonModelWriteCore(Utf8JsonWriter writer, ModelReaderWriterOptions? options)
         {

src/AI/Grok/GrokChatOptions.cs

@@ -1,6 +1,6 @@
 using Microsoft.Extensions.AI;
 
-namespace Devlooped.Extensions.AI;
+namespace Devlooped.Extensions.AI.Grok;
 
 /// <summary>
 /// Grok-specific chat options that extend the base <see cref="ChatOptions"/>

src/AI/Grok/GrokClient.cs

@@ -4,7 +4,7 @@
 using Microsoft.Extensions.AI;
 using OpenAI;
 
-namespace Devlooped.Extensions.AI;
+namespace Devlooped.Extensions.AI.Grok;
 
 /// <summary>
 /// Provides an OpenAI compability client for Grok. It's recommended you 
@@ -26,7 +26,7 @@ public class GrokClient(string apiKey, OpenAIClientOptions? options = null)
     /// Returns an adapter that surfaces an <see cref="IChatClient"/> interface that 
     /// can be used directly in the <see cref="ChatClientBuilder"/> pipeline builder.
     /// </summary>
-    public override OpenAI.Chat.ChatClient GetChatClient(string model) => new GrokChatClientAdapter(this, model);
+    public override global::OpenAI.Chat.ChatClient GetChatClient(string model) => new GrokChatClientAdapter(this, model);
 
     static OpenAIClientOptions EnsureEndpoint(OpenAIClientOptions? options)
     {
@@ -39,7 +39,7 @@ static OpenAIClientOptions EnsureEndpoint(OpenAIClientOptions? options)
     // OpenAI in MEAI docs. Most typical case would be to just create an <see cref="GrokChatClient"/> directly.
     // This throws on any non-IChatClient invoked methods in the AsIChatClient adapter, and 
     // forwards the IChatClient methods to the GrokChatClient implementation which is cached per client.
-    class GrokChatClientAdapter(GrokClient client, string model) : OpenAI.Chat.ChatClient, IChatClient
+    class GrokChatClientAdapter(GrokClient client, string model) : global::OpenAI.Chat.ChatClient, IChatClient
     {
         void IDisposable.Dispose() { }
 
@@ -60,36 +60,36 @@ IAsyncEnumerable<ChatResponseUpdate> IChatClient.GetStreamingResponseAsync(IEnum
             => client.GetChatClientImpl(options?.ModelId ?? model).GetStreamingResponseAsync(messages, options, cancellation);
 
         // These are the only two methods actually invoked by the AsIChatClient adapter from M.E.AI.OpenAI
-        public override Task<ClientResult<OpenAI.Chat.ChatCompletion>> CompleteChatAsync(IEnumerable<OpenAI.Chat.ChatMessage>? messages, OpenAI.Chat.ChatCompletionOptions? options = null, CancellationToken cancellationToken = default)
+        public override Task<ClientResult<global::OpenAI.Chat.ChatCompletion>> CompleteChatAsync(IEnumerable<global::OpenAI.Chat.ChatMessage>? messages, global::OpenAI.Chat.ChatCompletionOptions? options = null, CancellationToken cancellationToken = default)
             => throw new NotSupportedException($"Consume directly as an {nameof(IChatClient)} instead of invoking {nameof(OpenAIClientExtensions.AsIChatClient)} on this instance.");
 
-        public override AsyncCollectionResult<OpenAI.Chat.StreamingChatCompletionUpdate> CompleteChatStreamingAsync(IEnumerable<OpenAI.Chat.ChatMessage>? messages, OpenAI.Chat.ChatCompletionOptions? options = null, CancellationToken cancellationToken = default)
+        public override AsyncCollectionResult<global::OpenAI.Chat.StreamingChatCompletionUpdate> CompleteChatStreamingAsync(IEnumerable<global::OpenAI.Chat.ChatMessage>? messages, global::OpenAI.Chat.ChatCompletionOptions? options = null, CancellationToken cancellationToken = default)
             => throw new NotSupportedException($"Consume directly as an {nameof(IChatClient)} instead of invoking {nameof(OpenAIClientExtensions.AsIChatClient)} on this instance.");
 
         #region Unsupported
 
         public override ClientResult CompleteChat(BinaryContent? content, RequestOptions? options = null)
             => throw new NotSupportedException($"Consume directly as an {nameof(IChatClient)}.");
 
-        public override ClientResult<OpenAI.Chat.ChatCompletion> CompleteChat(IEnumerable<OpenAI.Chat.ChatMessage>? messages, OpenAI.Chat.ChatCompletionOptions? options = null, CancellationToken cancellationToken = default)
+        public override ClientResult<global::OpenAI.Chat.ChatCompletion> CompleteChat(IEnumerable<global::OpenAI.Chat.ChatMessage>? messages, global::OpenAI.Chat.ChatCompletionOptions? options = null, CancellationToken cancellationToken = default)
             => throw new NotSupportedException($"Consume directly as an {nameof(IChatClient)}.");
 
-        public override ClientResult<OpenAI.Chat.ChatCompletion> CompleteChat(params OpenAI.Chat.ChatMessage[] messages)
+        public override ClientResult<global::OpenAI.Chat.ChatCompletion> CompleteChat(params global::OpenAI.Chat.ChatMessage[] messages)
             => throw new NotSupportedException($"Consume directly as an {nameof(IChatClient)}.");
 
         public override Task<ClientResult> CompleteChatAsync(BinaryContent? content, RequestOptions? options = null)
             => throw new NotSupportedException($"Consume directly as an {nameof(IChatClient)}.");
 
-        public override Task<ClientResult<OpenAI.Chat.ChatCompletion>> CompleteChatAsync(params OpenAI.Chat.ChatMessage[] messages)
+        public override Task<ClientResult<global::OpenAI.Chat.ChatCompletion>> CompleteChatAsync(params global::OpenAI.Chat.ChatMessage[] messages)
             => throw new NotSupportedException($"Consume directly as an {nameof(IChatClient)}.");
 
-        public override CollectionResult<OpenAI.Chat.StreamingChatCompletionUpdate> CompleteChatStreaming(IEnumerable<OpenAI.Chat.ChatMessage>? messages, OpenAI.Chat.ChatCompletionOptions? options = null, CancellationToken cancellationToken = default)
+        public override CollectionResult<global::OpenAI.Chat.StreamingChatCompletionUpdate> CompleteChatStreaming(IEnumerable<global::OpenAI.Chat.ChatMessage>? messages, global::OpenAI.Chat.ChatCompletionOptions? options = null, CancellationToken cancellationToken = default)
             => throw new NotSupportedException($"Consume directly as an {nameof(IChatClient)}.");
 
-        public override CollectionResult<OpenAI.Chat.StreamingChatCompletionUpdate> CompleteChatStreaming(params OpenAI.Chat.ChatMessage[] messages)
+        public override CollectionResult<global::OpenAI.Chat.StreamingChatCompletionUpdate> CompleteChatStreaming(params global::OpenAI.Chat.ChatMessage[] messages)
             => throw new NotSupportedException($"Consume directly as an {nameof(IChatClient)}.");
 
-        public override AsyncCollectionResult<OpenAI.Chat.StreamingChatCompletionUpdate> CompleteChatStreamingAsync(params OpenAI.Chat.ChatMessage[] messages)
+        public override AsyncCollectionResult<global::OpenAI.Chat.StreamingChatCompletionUpdate> CompleteChatStreamingAsync(params global::OpenAI.Chat.ChatMessage[] messages)
             => throw new NotSupportedException($"Consume directly as an {nameof(IChatClient)}.");
 
         #endregion

src/AI/Grok/GrokSearchTool.cs

@@ -1,7 +1,7 @@
 using System.Text.Json.Serialization;
 using Microsoft.Extensions.AI;
 
-namespace Devlooped.Extensions.AI;
+namespace Devlooped.Extensions.AI.Grok;
 
 /// <summary>
 /// Enables or disables Grok's live search capabilities.

src/AI/OpenAI/OpenAIChatClient.cs

@@ -5,7 +5,7 @@
 using OpenAI;
 using OpenAI.Responses;
 
-namespace Devlooped.Extensions.AI;
+namespace Devlooped.Extensions.AI.OpenAI;
 
 /// <summary>
 /// An <see cref="IChatClient"/> implementation for OpenAI.