Cleanup/improve docs

Author: kzu

readme.md

@@ -6,21 +6,6 @@
 [![Version](https://img.shields.io/nuget/vpre/Devlooped.Extensions.AI.svg?color=royalblue)](https://www.nuget.org/packages/Devlooped.Extensions.AI)
 [![Downloads](https://img.shields.io/nuget/dt/Devlooped.Extensions.AI.svg?color=green)](https://www.nuget.org/packages/Devlooped.Extensions.AI)
 
-Extensions for Microsoft.Extensions.AI.
-
-<!-- include https://github.com/devlooped/.github/raw/main/osmf.md -->
-## Open Source Maintenance Fee
-
-To ensure the long-term sustainability of this project, users of this package who generate 
-revenue must pay an [Open Source Maintenance Fee](https://opensourcemaintenancefee.org). 
-While the source code is freely available under the terms of the [License](license.txt), 
-this package and other aspects of the project require [adherence to the Maintenance Fee](osmfeula.txt).
-
-To pay the Maintenance Fee, [become a Sponsor](https://github.com/sponsors/devlooped) at the proper 
-OSMF tier. A single fee covers all of [Devlooped packages](https://www.nuget.org/profiles/Devlooped).
-
-<!-- https://github.com/devlooped/.github/raw/main/osmf.md -->
-
 <!-- #extensions-title -->
 Extensions for Microsoft.Extensions.AI
 <!-- #extensions-title -->
@@ -60,56 +45,109 @@ var grok = app.Services.GetRequiredKeyedService<IChatClient>("Grok");
 Changing the `appsettings.json` file will automatically update the client 
 configuration without restarting the application.
 
-## OpenAI
-
-The support for OpenAI chat clients provided in [Microsoft.Extensions.AI.OpenAI](https://www.nuget.org/packages/Microsoft.Extensions.AI.OpenAI) fall short in some scenarios:
-
-* Specifying per-chat model identifier: the OpenAI client options only allow setting 
-  a single model identifier for all requests, at the time the `OpenAIClient.GetChatClient` is 
-  invoked.
-* Setting reasoning effort: the Microsoft.Extensions.AI API does not expose a way to set reasoning 
-  effort for reasoning-capable models, which is very useful for some models like `gpt-5.2`.
-
-So solve both issues, this package provides an `OpenAIChatClient` that wraps the underlying 
-`OpenAIClient` and allows setting the model identifier and reasoning effort per request, just 
-like the above Grok examples showed:
+There's also a simpler `Chat` class for streamlined creation of chat messages, which can 
+be used instead of creating an array of `ChatMessage` using `ChatRole.[System|Assistant|User]`:
 
 ```csharp
 var messages = new Chat()
 {
     { "system", "You are a highly intelligent AI assistant." },
     { "user", "What is 101*3?" },
 };
+```
+
+## Tool Results
+
+Given the following tool:
+
+```csharp
+MyResult RunTool(string name, string description, string content) { ... }
+```
 
-IChatClient chat = new OpenAIChatClient(Environment.GetEnvironmentVariable("OPENAI_API_KEY")!, "gpt-5");
+You can use the `ToolFactory` and `FindCall<MyResult>` extension method to 
+locate the function invocation, its outcome and the typed result for inspection:
 
+```csharp
+AIFunction tool = ToolFactory.Create(RunTool);
+var options = new ChatOptions
+{
+    ToolMode = ChatToolMode.RequireSpecific(tool.Name), // 👈 forces the tool to be used
+    Tools = [tool]
+};
+
+var response = await client.GetResponseAsync(chat, options);
+// 👇 finds the expected result of the tool call
+var result = response.FindCalls<MyResult>(tool).FirstOrDefault();
+
+if (result != null)
+{
+    // Successful tool call
+    Console.WriteLine($"Args: '{result.Call.Arguments.Count}'");
+    MyResult typed = result.Result;
+}
+else
+{
+    Console.WriteLine("Tool call not found in response.");
+}
+```
+
+If the typed result is not found, you can also inspect the raw outcomes by finding 
+untyped calls to the tool and checking their `Outcome.Exception` property:
+
+```csharp
+var result = response.FindCalls(tool).FirstOrDefault();
+if (result.Outcome.Exception is not null)
+{
+    Console.WriteLine($"Tool call failed: {result.Outcome.Exception.Message}");
+}
+else
+{
+    Console.WriteLine($"Tool call succeeded: {result.Outcome.Result}");
+}
+```
+
+> [!IMPORTANT]
+> The `ToolFactory` will also automatically sanitize the tool name 
+> when using local functions to avoid invalid characters and honor 
+> its original name.
+
+## OpenAI
+
+OpenAI-specific extensions enable more seamless usage with the MS.E.AI API:
+
+* Setting reasoning effort: the Microsoft.Extensions.AI API does not expose a way to set reasoning 
+  effort for reasoning-capable models, which is very useful for some models like 
+  [`gpt-5.2`](https://platform.openai.com/docs/guides/latest-model#lower-reasoning-effort)
+* Setting output verbosity: similarly, [output verbosity](https://platform.openai.com/docs/guides/latest-model#verbosity) is not exposed in the base API.
+
+These can be used as extension properties on `ChatOptions` whenever `Devlooped.Extensions.AI.OpenAI` is imported: 
+
+```csharp
 var options = new ChatOptions
 {
-    ModelId = "gpt-5-mini",                 // 👈 can override the model on the client
     ReasoningEffort = ReasoningEffort.High, // 👈 or Medium/Low/Minimal/None, extension property
+    Verbosity = Verbosity.Low               // 👈 or Medium/High, extension property
 };
 
 var response = await chat.GetResponseAsync(messages, options);
 ```
 
-> [!TIP]
-> We provide support for the newest `Minimal` reasoning effort in the just-released
-> GPT-5 model family as well as `None` which is the new default in GPT-5.2.
+Or you can opt to use the `ChatOptions`-derived `OpenAIChatOptions` class directly:
 
 ### Web Search
 
-Similar to the Grok client, we provide the `WebSearchTool` to enable search customization 
-in OpenAI too:
+The `WebSearchTool` can be used to customize the web search behavior in a typed manner, 
+unlike the generic `HostedWebSearchTool`:
 
 ```csharp
 var options = new ChatOptions
 {
     //                          👇 search in Argentina, Bariloche region
     Tools = [new WebSearchTool("AR")
     {
-        Region = "Bariloche",                        // 👈 Bariloche region
-        TimeZone = "America/Argentina/Buenos_Aires", // 👈 IANA timezone
-        ContextSize = WebSearchToolContextSize.High      // 👈 high search context size
+        AllowedDomains = ["catedralaltapatagonia.com"], // 👈 restrict domain
+        Region = "Bariloche",                           // 👈 Bariloche region
+        TimeZone = "America/Argentina/Buenos_Aires",    // 👈 IANA timezone
     }]
 };
 ```
@@ -121,7 +159,6 @@ var options = new ChatOptions
 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
 
 The underlying HTTP pipeline provided by the Azure SDK allows setting up 
@@ -163,61 +200,6 @@ var openai = new OpenAIClient(
     OpenAIClientOptions.Observable(requests.Add, responses.Add));
 ```
 
-## Tool Results
-
-Given the following tool:
-
-```csharp
-MyResult RunTool(string name, string description, string content) { ... }
-```
-
-You can use the `ToolFactory` and `FindCall<MyResult>` extension method to 
-locate the function invocation, its outcome and the typed result for inspection:
-
-```csharp
-AIFunction tool = ToolFactory.Create(RunTool);
-var options = new ChatOptions
-{
-    ToolMode = ChatToolMode.RequireSpecific(tool.Name), // 👈 forces the tool to be used
-    Tools = [tool]
-};
-
-var response = await client.GetResponseAsync(chat, options);
-// 👇 finds the expected result of the tool call
-var result = response.FindCalls<MyResult>(tool).FirstOrDefault();
-
-if (result != null)
-{
-    // Successful tool call
-    Console.WriteLine($"Args: '{result.Call.Arguments.Count}'");
-    MyResult typed = result.Result;
-}
-else
-{
-    Console.WriteLine("Tool call not found in response.");
-}
-```
-
-If the typed result is not found, you can also inspect the raw outcomes by finding 
-untyped calls to the tool and checking their `Outcome.Exception` property:
-
-```csharp
-var result = response.FindCalls(tool).FirstOrDefault();
-if (result.Outcome.Exception is not null)
-{
-    Console.WriteLine($"Tool call failed: {result.Outcome.Exception.Message}");
-}
-else
-{
-    Console.WriteLine($"Tool call succeeded: {result.Outcome.Result}");
-}
-```
-
-> [!IMPORTANT]
-> The `ToolFactory` will also automatically sanitize the tool name 
-> when using local functions to avoid invalid characters and honor 
-> its original name.
-
 ## Console Logging
 
 Additional `UseJsonConsoleLogging` extension for rich JSON-formatted console logging of AI requests 
@@ -261,14 +243,18 @@ IChatClient chat = new OpenAIChatClient(Environment.GetEnvironmentVariable("OPEN
 ```
 <!-- #extensions -->
 
-# xAI (Grok)
+<!-- include https://github.com/devlooped/.github/raw/main/osmf.md -->
+## Open Source Maintenance Fee
+
+To ensure the long-term sustainability of this project, users of this package who generate 
+revenue must pay an [Open Source Maintenance Fee](https://opensourcemaintenancefee.org). 
+While the source code is freely available under the terms of the [License](license.txt), 
+this package and other aspects of the project require [adherence to the Maintenance Fee](osmfeula.txt).
 
-[![Version](https://img.shields.io/nuget/vpre/xAI.svg?color=royalblue)](https://www.nuget.org/packages/xAI)
-[![Downloads](https://img.shields.io/nuget/dt/xAI.svg?color=green)](https://www.nuget.org/packages/xAI)
+To pay the Maintenance Fee, [become a Sponsor](https://github.com/sponsors/devlooped) at the proper 
+OSMF tier. A single fee covers all of [Devlooped packages](https://www.nuget.org/profiles/Devlooped).
 
-For Microsoft.Extensions.AI `IChatClient` integration with Grok (xAI), see the 
-[xAI](https://nuget.org/packages/xAI) package, which provides full support for all 
-[agentic tools](https://docs.x.ai/docs/guides/tools/overview).
+<!-- https://github.com/devlooped/.github/raw/main/osmf.md -->
 
 <!-- include https://github.com/devlooped/sponsors/raw/main/footer.md -->
 # Sponsors 

src/Extensions/OpenAI/OpenAIChatOptions.cs

@@ -1,5 +1,4 @@
-using System.ComponentModel;
-using Microsoft.Extensions.AI;
+using Microsoft.Extensions.AI;
 
 namespace Devlooped.Extensions.AI.OpenAI;
 

src/Extensions/OpenAI/OpenAIExtensions.cs

@@ -1,8 +1,5 @@
-using System.ClientModel.Primitives;
-using System.ComponentModel;
-using System.Text.Json;
+using System.ComponentModel;
 using Microsoft.Extensions.AI;
-using OpenAI.Responses;
 
 namespace Devlooped.Extensions.AI.OpenAI;
 
@@ -26,6 +23,7 @@ public static class OpenAIExtensions
     /// has been set to a non-OpenAI factory.</exception>
     extension(ChatOptions options)
     {
+        /// <summary>Controls how many reasoning tokens the model generates before producing a response.</summary>
         public ReasoningEffort? ReasoningEffort
         {
             get => options.AdditionalProperties?.TryGetValue("reasoning_effort", out var value) == true && value is ReasoningEffort effort ? effort : null;