feat(plugins): enhance GoogleTextSearch with advanced LINQ filtering

- Add ITextSearch<GoogleWebPage> interface implementation
- Support equality, contains, NOT operations, and compound AND expressions
- Map LINQ expressions to Google Custom Search API parameters
- Add GoogleWebPage strongly-typed model for search results
- Support FileFormat filtering via Google's fileType parameter
- Add comprehensive test coverage (29 tests) for all filtering patterns
- Include practical examples demonstrating enhanced filtering capabilities
- Maintain backward compatibility with existing ITextSearch interface

Resolves enhanced LINQ filtering requirements for Google Text Search plugin.

Author: alzarei

dotnet/src/Plugins/Plugins.UnitTests/Web/Google/GoogleTextSearchTests.cs

@@ -232,7 +232,7 @@ public async Task DoesNotBuildsUriForInvalidQueryParameterAsync()
 
         // Act && Assert
         var e = await Assert.ThrowsAsync<ArgumentException>(async () => await textSearch.GetSearchResultsAsync("What is the Semantic Kernel?", searchOptions));
-        Assert.Equal("Unknown equality filter clause field name 'fooBar', must be one of cr,dateRestrict,exactTerms,excludeTerms,filter,gl,hl,linkSite,lr,orTerms,rights,siteSearch (Parameter 'searchOptions')", e.Message);
+        Assert.Equal("Unknown equality filter clause field name 'fooBar', must be one of cr,dateRestrict,exactTerms,excludeTerms,fileType,filter,gl,hl,linkSite,lr,orTerms,rights,siteSearch (Parameter 'searchOptions')", e.Message);
     }
 
     [Fact]
@@ -334,7 +334,7 @@ public async Task GenericSearchWithContainsFilterReturnsSuccessfullyAsync()
             {
                 Top = 4,
                 Skip = 0,
-                Filter = page => page.Title.Contains("Semantic")
+                Filter = page => page.Title != null && page.Title.Contains("Semantic")
             });
 
         // Assert
@@ -372,6 +372,141 @@ public async Task GenericSearchWithEqualityFilterReturnsSuccessfullyAsync()
         Assert.Equal(4, resultList.Count);
     }
 
+    [Fact]
+    public async Task GenericSearchWithNotEqualFilterReturnsSuccessfullyAsync()
+    {
+        // Arrange
+        this._messageHandlerStub.AddJsonResponse(File.ReadAllText(WhatIsTheSKResponseJson));
+
+        using var textSearch = new GoogleTextSearch(
+            initializer: new() { ApiKey = "ApiKey", HttpClientFactory = this._clientFactory },
+            searchEngineId: "SearchEngineId");
+
+        // Act - Use generic interface with NOT EQUAL filtering (excludes terms)
+        KernelSearchResults<string> result = await textSearch.SearchAsync("What is the Semantic Kernel?",
+            new TextSearchOptions<GoogleWebPage>
+            {
+                Top = 4,
+                Skip = 0,
+                Filter = page => page.Title != "Deprecated"
+            });
+
+        // Assert
+        Assert.NotNull(result);
+        Assert.NotNull(result.Results);
+        var resultList = await result.Results.ToListAsync();
+        Assert.NotNull(resultList);
+        Assert.Equal(4, resultList.Count);
+    }
+
+    [Fact]
+    public async Task GenericSearchWithNotContainsFilterReturnsSuccessfullyAsync()
+    {
+        // Arrange
+        this._messageHandlerStub.AddJsonResponse(File.ReadAllText(WhatIsTheSKResponseJson));
+
+        using var textSearch = new GoogleTextSearch(
+            initializer: new() { ApiKey = "ApiKey", HttpClientFactory = this._clientFactory },
+            searchEngineId: "SearchEngineId");
+
+        // Act - Use generic interface with NOT Contains filtering (excludes terms)
+        KernelSearchResults<string> result = await textSearch.SearchAsync("What is the Semantic Kernel?",
+            new TextSearchOptions<GoogleWebPage>
+            {
+                Top = 4,
+                Skip = 0,
+                Filter = page => page.Title != null && !page.Title.Contains("deprecated")
+            });
+
+        // Assert
+        Assert.NotNull(result);
+        Assert.NotNull(result.Results);
+        var resultList = await result.Results.ToListAsync();
+        Assert.NotNull(resultList);
+        Assert.Equal(4, resultList.Count);
+    }
+
+    [Fact]
+    public async Task GenericSearchWithFileFormatFilterReturnsSuccessfullyAsync()
+    {
+        // Arrange
+        this._messageHandlerStub.AddJsonResponse(File.ReadAllText(WhatIsTheSKResponseJson));
+
+        using var textSearch = new GoogleTextSearch(
+            initializer: new() { ApiKey = "ApiKey", HttpClientFactory = this._clientFactory },
+            searchEngineId: "SearchEngineId");
+
+        // Act - Use generic interface with FileFormat filtering
+        KernelSearchResults<string> result = await textSearch.SearchAsync("What is the Semantic Kernel?",
+            new TextSearchOptions<GoogleWebPage>
+            {
+                Top = 4,
+                Skip = 0,
+                Filter = page => page.FileFormat == "pdf"
+            });
+
+        // Assert
+        Assert.NotNull(result);
+        Assert.NotNull(result.Results);
+        var resultList = await result.Results.ToListAsync();
+        Assert.NotNull(resultList);
+        Assert.Equal(4, resultList.Count);
+    }
+
+    [Fact]
+    public async Task GenericSearchWithCompoundAndFilterReturnsSuccessfullyAsync()
+    {
+        // Arrange
+        this._messageHandlerStub.AddJsonResponse(File.ReadAllText(WhatIsTheSKResponseJson));
+
+        using var textSearch = new GoogleTextSearch(
+            initializer: new() { ApiKey = "ApiKey", HttpClientFactory = this._clientFactory },
+            searchEngineId: "SearchEngineId");
+
+        // Act - Use generic interface with compound AND filtering
+        KernelSearchResults<string> result = await textSearch.SearchAsync("What is the Semantic Kernel?",
+            new TextSearchOptions<GoogleWebPage>
+            {
+                Top = 4,
+                Skip = 0,
+                Filter = page => page.Title != null && page.Title.Contains("Semantic") && page.DisplayLink != null && page.DisplayLink.Contains("microsoft")
+            });
+
+        // Assert
+        Assert.NotNull(result);
+        Assert.NotNull(result.Results);
+        var resultList = await result.Results.ToListAsync();
+        Assert.NotNull(resultList);
+        Assert.Equal(4, resultList.Count);
+    }
+
+    [Fact]
+    public async Task GenericSearchWithComplexCompoundFilterReturnsSuccessfullyAsync()
+    {
+        // Arrange
+        this._messageHandlerStub.AddJsonResponse(File.ReadAllText(WhatIsTheSKResponseJson));
+
+        using var textSearch = new GoogleTextSearch(
+            initializer: new() { ApiKey = "ApiKey", HttpClientFactory = this._clientFactory },
+            searchEngineId: "SearchEngineId");
+
+        // Act - Use generic interface with complex compound filtering (equality + contains + exclusion)
+        KernelSearchResults<string> result = await textSearch.SearchAsync("What is the Semantic Kernel?",
+            new TextSearchOptions<GoogleWebPage>
+            {
+                Top = 4,
+                Skip = 0,
+                Filter = page => page.FileFormat == "pdf" && page.Title != null && page.Title.Contains("AI") && page.Snippet != null && !page.Snippet.Contains("deprecated")
+            });
+
+        // Assert
+        Assert.NotNull(result);
+        Assert.NotNull(result.Results);
+        var resultList = await result.Results.ToListAsync();
+        Assert.NotNull(resultList);
+        Assert.Equal(4, resultList.Count);
+    }
+
     /// <inheritdoc/>
     public void Dispose()
     {

dotnet/src/Plugins/Plugins.Web/Google/GoogleTextSearch.cs

@@ -148,13 +148,22 @@ private static TextSearchOptions ConvertToLegacyOptions(TextSearchOptions<Google
 
     /// <summary>
     /// Converts a LINQ expression to a TextSearchFilter compatible with Google Custom Search API.
-    /// Supports property equality expressions and string Contains operations that map to Google's filter capabilities.
+    /// Supports property equality expressions, string Contains operations, NOT operations (inequality and negation),
+    /// and compound AND expressions that map to Google's filter capabilities.
     /// </summary>
     /// <param name="linqExpression">The LINQ expression to convert.</param>
     /// <returns>A TextSearchFilter with equivalent filtering.</returns>
     /// <exception cref="NotSupportedException">Thrown when the expression cannot be converted to Google filters.</exception>
     private static TextSearchFilter ConvertLinqExpressionToGoogleFilter<TRecord>(Expression<Func<TRecord, bool>> linqExpression)
     {
+        // Handle compound AND expressions: expr1 && expr2
+        if (linqExpression.Body is BinaryExpression andExpr && andExpr.NodeType == ExpressionType.AndAlso)
+        {
+            var filter = new TextSearchFilter();
+            CollectAndCombineFilters(andExpr, filter);
+            return filter;
+        }
+
         // Handle simple equality: record.PropertyName == "value"
         if (linqExpression.Body is BinaryExpression binaryExpr && binaryExpr.NodeType == ExpressionType.Equal)
         {
@@ -171,6 +180,45 @@ private static TextSearchFilter ConvertLinqExpressionToGoogleFilter<TRecord>(Exp
             }
         }
 
+        // Handle inequality (NOT): record.PropertyName != "value"
+        if (linqExpression.Body is BinaryExpression notEqualExpr && notEqualExpr.NodeType == ExpressionType.NotEqual)
+        {
+            if (notEqualExpr.Left is MemberExpression memberExpr && notEqualExpr.Right is ConstantExpression constExpr)
+            {
+                string propertyName = memberExpr.Member.Name;
+                object? value = constExpr.Value;
+
+                // Map to excludeTerms for text fields
+                if (propertyName.ToUpperInvariant() is "TITLE" or "SNIPPET" && value != null)
+                {
+                    return new TextSearchFilter().Equality("excludeTerms", value);
+                }
+            }
+        }
+
+        // Handle NOT expressions: !record.PropertyName.Contains("value")
+        if (linqExpression.Body is UnaryExpression unaryExpr && unaryExpr.NodeType == ExpressionType.Not)
+        {
+            if (unaryExpr.Operand is MethodCallExpression notMethodCall &&
+                notMethodCall.Method.Name == "Contains" &&
+                notMethodCall.Method.DeclaringType == typeof(string))
+            {
+                if (notMethodCall.Object is MemberExpression memberExpr &&
+                    notMethodCall.Arguments.Count == 1 &&
+                    notMethodCall.Arguments[0] is ConstantExpression constExpr)
+                {
+                    string propertyName = memberExpr.Member.Name;
+                    object? value = constExpr.Value;
+
+                    // Map to excludeTerms for text fields
+                    if (propertyName.ToUpperInvariant() is "TITLE" or "SNIPPET" && value != null)
+                    {
+                        return new TextSearchFilter().Equality("excludeTerms", value);
+                    }
+                }
+            }
+        }
+
         // Handle string Contains: record.PropertyName.Contains("value")
         if (linqExpression.Body is MethodCallExpression methodCall &&
             methodCall.Method.Name == "Contains" &&
@@ -200,7 +248,10 @@ private static TextSearchFilter ConvertLinqExpressionToGoogleFilter<TRecord>(Exp
         var supportedPatterns = new[]
         {
             "page.Property == \"value\" (exact match)",
-            "page.Property.Contains(\"text\") (partial match)"
+            "page.Property != \"value\" (exclude)",
+            "page.Property.Contains(\"text\") (partial match)",
+            "!page.Property.Contains(\"text\") (exclude partial)",
+            "page.Prop1 == \"val1\" && page.Prop2.Contains(\"val2\") (compound AND)"
         };
 
         var supportedProperties = s_queryParameters.Select(p =>
@@ -212,6 +263,93 @@ private static TextSearchFilter ConvertLinqExpressionToGoogleFilter<TRecord>(Exp
             $"Supported properties: {string.Join(", ", supportedProperties)}.");
     }
 
+    /// <summary>
+    /// Recursively collects and combines filters from compound AND expressions.
+    /// </summary>
+    /// <param name="expression">The expression to process.</param>
+    /// <param name="filter">The filter to accumulate results into.</param>
+    private static void CollectAndCombineFilters(Expression expression, TextSearchFilter filter)
+    {
+        if (expression is BinaryExpression binaryExpr && binaryExpr.NodeType == ExpressionType.AndAlso)
+        {
+            // Recursively process both sides of the AND
+            CollectAndCombineFilters(binaryExpr.Left, filter);
+            CollectAndCombineFilters(binaryExpr.Right, filter);
+        }
+        else if (expression is BinaryExpression equalExpr && equalExpr.NodeType == ExpressionType.Equal)
+        {
+            // Handle equality
+            if (equalExpr.Left is MemberExpression memberExpr && equalExpr.Right is ConstantExpression constExpr)
+            {
+                string propertyName = memberExpr.Member.Name;
+                object? value = constExpr.Value;
+                string? googleFilterName = MapPropertyToGoogleFilter(propertyName);
+                if (googleFilterName != null && value != null)
+                {
+                    filter.Equality(googleFilterName, value);
+                }
+            }
+        }
+        else if (expression is BinaryExpression notEqualExpr && notEqualExpr.NodeType == ExpressionType.NotEqual)
+        {
+            // Handle inequality (exclusion)
+            if (notEqualExpr.Left is MemberExpression memberExpr && notEqualExpr.Right is ConstantExpression constExpr)
+            {
+                string propertyName = memberExpr.Member.Name;
+                object? value = constExpr.Value;
+                if (propertyName.ToUpperInvariant() is "TITLE" or "SNIPPET" && value != null)
+                {
+                    filter.Equality("excludeTerms", value);
+                }
+            }
+        }
+        else if (expression is MethodCallExpression methodCall &&
+                 methodCall.Method.Name == "Contains" &&
+                 methodCall.Method.DeclaringType == typeof(string))
+        {
+            // Handle Contains
+            if (methodCall.Object is MemberExpression memberExpr &&
+                methodCall.Arguments.Count == 1 &&
+                methodCall.Arguments[0] is ConstantExpression constExpr)
+            {
+                string propertyName = memberExpr.Member.Name;
+                object? value = constExpr.Value;
+                string? googleFilterName = MapPropertyToGoogleFilter(propertyName);
+                if (googleFilterName != null && value != null)
+                {
+                    if (googleFilterName == "exactTerms")
+                    {
+                        filter.Equality("orTerms", value);
+                    }
+                    else
+                    {
+                        filter.Equality(googleFilterName, value);
+                    }
+                }
+            }
+        }
+        else if (expression is UnaryExpression unaryExpr && unaryExpr.NodeType == ExpressionType.Not)
+        {
+            // Handle NOT Contains
+            if (unaryExpr.Operand is MethodCallExpression notMethodCall &&
+                notMethodCall.Method.Name == "Contains" &&
+                notMethodCall.Method.DeclaringType == typeof(string))
+            {
+                if (notMethodCall.Object is MemberExpression memberExpr &&
+                    notMethodCall.Arguments.Count == 1 &&
+                    notMethodCall.Arguments[0] is ConstantExpression constExpr)
+                {
+                    string propertyName = memberExpr.Member.Name;
+                    object? value = constExpr.Value;
+                    if (propertyName.ToUpperInvariant() is "TITLE" or "SNIPPET" && value != null)
+                    {
+                        filter.Equality("excludeTerms", value);
+                    }
+                }
+            }
+        }
+    }
+
     /// <summary>
     /// Maps GoogleWebPage property names to Google Custom Search API filter field names.
     /// </summary>
@@ -228,7 +366,7 @@ private static TextSearchFilter ConvertLinqExpressionToGoogleFilter<TRecord>(Exp
             "SNIPPET" => "exactTerms",        // Exact content match
 
             // Direct API parameters mapped from GoogleWebPage metadata properties
-            "FILEFORMAT" => "filter",         // File format filtering
+            "FILEFORMAT" => "fileType",       // File type/extension filtering
             "MIME" => "filter",               // MIME type filtering
 
             // Locale/Language parameters (if we extend GoogleWebPage)
@@ -253,7 +391,10 @@ private static TextSearchFilter ConvertLinqExpressionToGoogleFilter<TRecord>(Exp
         {
             "siteSearch" => "DisplayLink",
             "exactTerms" => "Title",
-            "filter" => "FileFormat",
+            "orTerms" => "Title",
+            "excludeTerms" => "Title",
+            "fileType" => "FileFormat",
+            "filter" => "Mime",
             "hl" => "HL",
             "gl" => "GL",
             "cr" => "CR",
@@ -284,7 +425,7 @@ public void Dispose()
     private static readonly ITextSearchResultMapper s_defaultResultMapper = new DefaultTextSearchResultMapper();
 
     // See https://developers.google.com/custom-search/v1/reference/rest/v1/cse/list
-    private static readonly string[] s_queryParameters = ["cr", "dateRestrict", "exactTerms", "excludeTerms", "filter", "gl", "hl", "linkSite", "lr", "orTerms", "rights", "siteSearch"];
+    private static readonly string[] s_queryParameters = ["cr", "dateRestrict", "exactTerms", "excludeTerms", "fileType", "filter", "gl", "hl", "linkSite", "lr", "orTerms", "rights", "siteSearch"];
 
     private delegate void SetSearchProperty(CseResource.ListRequest search, string value);
 
@@ -293,6 +434,7 @@ public void Dispose()
         { "DATERESTRICT", (search, value) => search.DateRestrict = value },
         { "EXACTTERMS", (search, value) => search.ExactTerms = value },
         { "EXCLUDETERMS", (search, value) => search.ExcludeTerms = value },
+        { "FILETYPE", (search, value) => search.FileType = value },
         { "FILTER", (search, value) => search.Filter = value },
         { "GL", (search, value) => search.Gl = value },
         { "HL", (search, value) => search.Hl = value },