Add stable web_search support and separate factory for web_search_preview

[ShivangiReja]

This PR adds support for the stable web search tool and separate factory for preview web search tool.

public static WebSearchPreviewTool CreateWebSearchPreviewTool(
WebSearchToolLocation userLocation = null, WebSearchToolContextSize? searchContextSize = null);

public static WebSearchTool CreateWebSearchTool(
WebSearchToolLocation userLocation = null, WebSearchToolContextSize? searchContextSize = null, WebSearchToolFilters filters = null);

Ref issue: #811

[jsquire]

Nice! The only thing that we may want to do is ask Chris and KC their opinions on the name for usePreview. It makes perfect sense to me.

[christothes]

Nice! The only thing that we may want to do is ask Chris and KC their opinions on the name for usePreview. It makes perfect sense to me.

The only feedback I have is that we typical name bool flags something like IsPreviewEnabled

[joseharriaga]

I talked to Shivangi offline. I'm realizing now that one issue with this approach is that it doesn't fully work for outputs (or more specifically, for deserialization). That is because the following code would return an "unknown tool" instead of the WebSearchTool based on value of the discriminator:
🔗

openai-dotnet/src/Generated/Models/Responses/ResponseTool.Serialization.cs

Lines 79 to 80 in ba45b1f

	case "web_search_preview":
	return WebSearchTool.DeserializeWebSearchTool(element, data, options);

One possible fix is to customize the deserialization code to make it understand both "web_search" and "web_search_preview". However, I think it would be a little inconvenient having to maintain this code manually, especially given how common it is for new tools to be added. Based on this, I'm tempted to suggest that we should add a new WebSearchPreviewTool to support this use case side by side with the existing WebSearchTool. We will keep WebSearchPreviewTool as "experimental" forever (it is preview after all), and then, one day, we can probably remove it fully.

[ShivangiReja]

Yes, agreed. Rather than maintaining custom deserialization, I think we should generate two types WebSearchTool and WebSearchPreviewTool and add separate factory methods:

public static WebSearchTool CreateWebSearchTool(
    WebSearchToolLocation userLocation = null,
    WebSearchToolContextSize? searchContextSize = null);

public static WebSearchPreviewTool CreateWebSearchPreviewTool(
    WebSearchToolLocation userLocation = null,
    WebSearchToolContextSize? searchContextSize = null);

[jsquire]

I'd wait for @joseharriaga to be the authoritative reviewer, but it looks reasonable to me.