feat: Modernize TavilyTextSearch and BraveTextSearch with ITextSearch<TRecord> interface

- Add TavilyWebPage and BraveWebPage model classes for type-safe LINQ filtering
- Implement dual interface support (ITextSearch + ITextSearch<TRecord>) in both connectors
- Add LINQ-to-API conversion logic for Tavily and Brave search parameters
- Maintain 100% backward compatibility with existing ITextSearch usage
- Enable compile-time type safety and IntelliSense support for web search filters

Addresses #10456

Author: alzarei

dotnet/src/Plugins/Plugins.Web/Brave/BraveTextSearch.cs

@@ -3,6 +3,7 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
+using System.Linq.Expressions;
 using System.Net.Http;
 using System.Runtime.CompilerServices;
 using System.Text;
@@ -20,7 +21,7 @@ namespace Microsoft.SemanticKernel.Plugins.Web.Brave;
 /// <summary>
 /// A Brave Text Search implementation that can be used to perform searches using the Brave Web Search API.
 /// </summary>
-public sealed class BraveTextSearch : ITextSearch
+public sealed class BraveTextSearch : ITextSearch, ITextSearch<BraveWebPage>
 {
     /// <summary>
     /// Create an instance of the <see cref="BraveTextSearch"/> with API key authentication.
@@ -78,7 +79,265 @@ public async Task<KernelSearchResults<object>> GetSearchResultsAsync(string quer
         return new KernelSearchResults<object>(this.GetResultsAsWebPageAsync(searchResponse, cancellationToken), totalCount, GetResultsMetadata(searchResponse));
     }
 
-    #region private
+    #region Generic ITextSearch<BraveWebPage> Implementation
+
+    /// <inheritdoc/>
+    async Task<KernelSearchResults<string>> ITextSearch<BraveWebPage>.SearchAsync(string query, TextSearchOptions<BraveWebPage>? searchOptions, CancellationToken cancellationToken)
+    {
+        var legacyOptions = this.ConvertToLegacyOptions(searchOptions);
+        BraveSearchResponse<BraveWebResult>? searchResponse = await this.ExecuteSearchAsync(query, legacyOptions, cancellationToken).ConfigureAwait(false);
+
+        long? totalCount = legacyOptions.IncludeTotalCount ? searchResponse?.Web?.Results.Count : null;
+
+        return new KernelSearchResults<string>(this.GetResultsAsStringAsync(searchResponse, cancellationToken), totalCount, GetResultsMetadata(searchResponse));
+    }
+
+    /// <inheritdoc/>
+    async Task<KernelSearchResults<TextSearchResult>> ITextSearch<BraveWebPage>.GetTextSearchResultsAsync(string query, TextSearchOptions<BraveWebPage>? searchOptions, CancellationToken cancellationToken)
+    {
+        var legacyOptions = this.ConvertToLegacyOptions(searchOptions);
+        BraveSearchResponse<BraveWebResult>? searchResponse = await this.ExecuteSearchAsync(query, legacyOptions, cancellationToken).ConfigureAwait(false);
+
+        long? totalCount = legacyOptions.IncludeTotalCount ? searchResponse?.Web?.Results.Count : null;
+
+        return new KernelSearchResults<TextSearchResult>(this.GetResultsAsTextSearchResultAsync(searchResponse, cancellationToken), totalCount, GetResultsMetadata(searchResponse));
+    }
+
+    /// <inheritdoc/>
+    async Task<KernelSearchResults<object>> ITextSearch<BraveWebPage>.GetSearchResultsAsync(string query, TextSearchOptions<BraveWebPage>? searchOptions, CancellationToken cancellationToken)
+    {
+        var legacyOptions = this.ConvertToLegacyOptions(searchOptions);
+        BraveSearchResponse<BraveWebResult>? searchResponse = await this.ExecuteSearchAsync(query, legacyOptions, cancellationToken).ConfigureAwait(false);
+
+        long? totalCount = legacyOptions.IncludeTotalCount ? searchResponse?.Web?.Results.Count : null;
+
+        return new KernelSearchResults<object>(this.GetResultsAsBraveWebPageAsync(searchResponse, cancellationToken), totalCount, GetResultsMetadata(searchResponse));
+    }
+
+    #endregion
+
+    #region LINQ-to-Brave Conversion Logic
+
+    /// <summary>
+    /// Converts generic TextSearchOptions with LINQ filtering to legacy TextSearchOptions.
+    /// </summary>
+    /// <param name="options">The generic search options with LINQ filter.</param>
+    /// <returns>Legacy TextSearchOptions with converted filters.</returns>
+    private TextSearchOptions ConvertToLegacyOptions<TRecord>(TextSearchOptions<TRecord>? options)
+    {
+        if (options == null)
+        {
+            return new TextSearchOptions();
+        }
+
+        var legacyOptions = new TextSearchOptions
+        {
+            Top = options.Top,
+            Skip = options.Skip,
+            IncludeTotalCount = options.IncludeTotalCount
+        };
+
+        // Convert LINQ expression to TextSearchFilter if present
+        if (options.Filter != null)
+        {
+            try
+            {
+                var convertedFilter = ConvertLinqExpressionToBraveFilter(options.Filter);
+                legacyOptions = new TextSearchOptions
+                {
+                    Top = options.Top,
+                    Skip = options.Skip,
+                    IncludeTotalCount = options.IncludeTotalCount,
+                    Filter = convertedFilter
+                };
+            }
+            catch (NotSupportedException ex)
+            {
+                this._logger.LogWarning("LINQ expression not fully supported by Brave API, performing search without some filters: {Message}", ex.Message);
+                // Continue with basic search - graceful degradation
+            }
+        }
+
+        return legacyOptions;
+    }
+
+    /// <summary>
+    /// Converts a LINQ expression to Brave-compatible TextSearchFilter.
+    /// </summary>
+    /// <param name="linqExpression">The LINQ expression to convert.</param>
+    /// <returns>A TextSearchFilter with Brave-compatible filter clauses.</returns>
+    private static TextSearchFilter ConvertLinqExpressionToBraveFilter<TRecord>(Expression<Func<TRecord, bool>> linqExpression)
+    {
+        var filter = new TextSearchFilter();
+        var filterClauses = new List<FilterClause>();
+
+        // Analyze the LINQ expression and convert to filter clauses
+        AnalyzeExpression(linqExpression.Body, filterClauses);
+
+        // Validate and add clauses that are supported by Brave
+        foreach (var clause in filterClauses)
+        {
+            if (clause is EqualToFilterClause equalityClause)
+            {
+                var mappedFieldName = MapPropertyToBraveFilter(equalityClause.FieldName);
+                if (mappedFieldName != null)
+                {
+                    filter.Equality(mappedFieldName, equalityClause.Value);
+                }
+                else
+                {
+                    throw new NotSupportedException($"Property '{equalityClause.FieldName}' cannot be mapped to Brave API filters. Supported properties: {string.Join(", ", s_queryParameters)}");
+                }
+            }
+        }
+
+        return filter;
+    }
+
+    /// <summary>
+    /// Maps BraveWebPage property names to Brave API filter parameter names.
+    /// </summary>
+    /// <param name="propertyName">The property name from BraveWebPage.</param>
+    /// <returns>The corresponding Brave API parameter name, or null if not mappable.</returns>
+    private static string? MapPropertyToBraveFilter(string propertyName) =>
+        propertyName.ToUpperInvariant() switch
+        {
+            "COUNTRY" => "country",
+            "SEARCHLANG" => "search_lang",
+            "UILANG" => "ui_lang",
+            "SAFESEARCH" => "safesearch",
+            "TEXTDECORATIONS" => "text_decorations",
+            "SPELLCHECK" => "spellcheck",
+            "RESULTFILTER" => "result_filter",
+            "UNITS" => "units",
+            "EXTRASNIPPETS" => "extra_snippets",
+            _ => null // Property not mappable to Brave filters
+        };
+
+    /// <summary>
+    /// Analyzes a LINQ expression and extracts filter clauses.
+    /// </summary>
+    /// <param name="expression">The expression to analyze.</param>
+    /// <param name="filterClauses">The list to add extracted filter clauses to.</param>
+    private static void AnalyzeExpression(Expression expression, List<FilterClause> filterClauses)
+    {
+        switch (expression)
+        {
+            case BinaryExpression binaryExpr:
+                if (binaryExpr.NodeType == ExpressionType.AndAlso)
+                {
+                    // Handle AND expressions by recursively analyzing both sides
+                    AnalyzeExpression(binaryExpr.Left, filterClauses);
+                    AnalyzeExpression(binaryExpr.Right, filterClauses);
+                }
+                else if (binaryExpr.NodeType == ExpressionType.Equal)
+                {
+                    // Handle equality expressions
+                    ExtractEqualityClause(binaryExpr, filterClauses);
+                }
+                else
+                {
+                    throw new NotSupportedException($"Binary expression type '{binaryExpr.NodeType}' is not supported. Only AndAlso and Equal are supported.");
+                }
+                break;
+
+            case MethodCallExpression methodCall:
+                // Handle method calls like Contains, StartsWith, etc.
+                ExtractMethodCallClause(methodCall, filterClauses);
+                break;
+
+            default:
+                throw new NotSupportedException($"Expression type '{expression.NodeType}' is not supported in Brave search filters.");
+        }
+    }
+
+    /// <summary>
+    /// Extracts an equality filter clause from a binary equality expression.
+    /// </summary>
+    /// <param name="binaryExpr">The binary equality expression.</param>
+    /// <param name="filterClauses">The list to add the extracted clause to.</param>
+    private static void ExtractEqualityClause(BinaryExpression binaryExpr, List<FilterClause> filterClauses)
+    {
+        string? propertyName = null;
+        object? value = null;
+
+        // Determine which side is the property and which is the value
+        if (binaryExpr.Left is MemberExpression leftMember)
+        {
+            propertyName = leftMember.Member.Name;
+            value = ExtractValue(binaryExpr.Right);
+        }
+        else if (binaryExpr.Right is MemberExpression rightMember)
+        {
+            propertyName = rightMember.Member.Name;
+            value = ExtractValue(binaryExpr.Left);
+        }
+
+        if (propertyName != null && value != null)
+        {
+            filterClauses.Add(new EqualToFilterClause(propertyName, value));
+        }
+        else
+        {
+            throw new NotSupportedException("Unable to extract property name and value from equality expression.");
+        }
+    }
+
+    /// <summary>
+    /// Extracts a filter clause from a method call expression (e.g., Contains, StartsWith).
+    /// </summary>
+    /// <param name="methodCall">The method call expression.</param>
+    /// <param name="filterClauses">The list to add the extracted clause to.</param>
+    private static void ExtractMethodCallClause(MethodCallExpression methodCall, List<FilterClause> filterClauses)
+    {
+        if (methodCall.Method.Name == "Contains" && methodCall.Object is MemberExpression member)
+        {
+            var propertyName = member.Member.Name;
+            var value = ExtractValue(methodCall.Arguments[0]);
+
+            if (value != null)
+            {
+                // For Contains, we'll map it to equality for certain properties
+                if (propertyName.Equals("ResultFilter", StringComparison.OrdinalIgnoreCase))
+                {
+                    filterClauses.Add(new EqualToFilterClause(propertyName, value));
+                }
+                else
+                {
+                    throw new NotSupportedException($"Contains method is only supported for ResultFilter property, not '{propertyName}'.");
+                }
+            }
+        }
+        else
+        {
+            throw new NotSupportedException($"Method '{methodCall.Method.Name}' is not supported in Brave search filters.");
+        }
+    }
+
+    /// <summary>
+    /// Extracts a constant value from an expression.
+    /// </summary>
+    /// <param name="expression">The expression to extract the value from.</param>
+    /// <returns>The extracted value, or null if extraction failed.</returns>
+    private static object? ExtractValue(Expression expression)
+    {
+        return expression switch
+        {
+            ConstantExpression constant => constant.Value,
+            MemberExpression member when member.Expression is ConstantExpression constantExpr =>
+                member.Member switch
+                {
+                    System.Reflection.FieldInfo field => field.GetValue(constantExpr.Value),
+                    System.Reflection.PropertyInfo property => property.GetValue(constantExpr.Value),
+                    _ => null
+                },
+            _ => Expression.Lambda(expression).Compile().DynamicInvoke()
+        };
+    }
+
+    #endregion
+
+    #region Private Methods
 
     private readonly ILogger _logger;
     private readonly HttpClient _httpClient;
@@ -178,6 +437,25 @@ private async IAsyncEnumerable<object> GetResultsAsWebPageAsync(BraveSearchRespo
         }
     }
 
+    /// <summary>
+    /// Return the search results as instances of <see cref="BraveWebPage"/>.
+    /// </summary>
+    /// <param name="searchResponse">Response containing the web pages matching the query.</param>
+    /// <param name="cancellationToken">Cancellation token</param>
+    private async IAsyncEnumerable<object> GetResultsAsBraveWebPageAsync(BraveSearchResponse<BraveWebResult>? searchResponse, [EnumeratorCancellation] CancellationToken cancellationToken)
+    {
+        if (searchResponse is null) { yield break; }
+
+        if (searchResponse.Web?.Results is { Count: > 0 } webResults)
+        {
+            foreach (var webPage in webResults)
+            {
+                yield return BraveWebPage.FromWebResult(webPage);
+                await Task.Yield();
+            }
+        }
+    }
+
     /// <summary>
     /// Return the search results as instances of <see cref="TextSearchResult"/>.
     /// </summary>