.Net: Tavily image search and integration tests

dotnet/src/IntegrationTests/Data/BaseTextSearchTests.cs

@@ -18,7 +18,7 @@ namespace SemanticKernel.IntegrationTests.Data;
 /// </summary>
 public abstract class BaseTextSearchTests : BaseIntegrationTest
 {
-    [Fact(Skip = "Failing in integration tests pipeline with - HTTP 429 (insufficient_quota) error.")]
+    [Fact(Skip = "For manual verification only.")]
     public virtual async Task CanSearchAsync()
     {
         // Arrange
@@ -42,7 +42,7 @@ public virtual async Task CanSearchAsync()
         }
     }
 
-    [Fact(Skip = "Failing in integration tests pipeline with - HTTP 429 (insufficient_quota) error.")]
+    [Fact(Skip = "For manual verification only.")]
     public virtual async Task CanGetTextSearchResultsAsync()
     {
         // Arrange
@@ -72,7 +72,7 @@ public virtual async Task CanGetTextSearchResultsAsync()
         }
     }
 
-    [Fact(Skip = "Failing in integration tests pipeline with - HTTP 429 (insufficient_quota) error.")]
+    [Fact(Skip = "For manual verification only.")]
     public virtual async Task CanGetSearchResultsAsync()
     {
         // Arrange
@@ -92,7 +92,7 @@ public virtual async Task CanGetSearchResultsAsync()
         Assert.True(this.VerifySearchResults(results, query));
     }
 
-    [Fact(Skip = "Failing in integration tests pipeline with - HTTP 429 (insufficient_quota) error.")]
+    [Fact(Skip = "For manual verification only.")]
     public virtual async Task UsingTextSearchWithAFilterAsync()
     {
         // Arrange
@@ -113,7 +113,7 @@ public virtual async Task UsingTextSearchWithAFilterAsync()
         Assert.True(this.VerifySearchResults(results, query, filter));
     }
 
-    [Fact(Skip = "Failing in integration tests pipeline with - HTTP 429 (insufficient_quota) error.")]
+    [Fact(Skip = "For manual verification only.")]
     public virtual async Task FunctionCallingUsingCreateWithSearchAsync()
     {
         // Arrange
@@ -142,7 +142,7 @@ public virtual async Task FunctionCallingUsingCreateWithSearchAsync()
         Assert.NotEmpty(results);
     }
 
-    [Fact(Skip = "Failing in integration tests pipeline with - HTTP 429 (insufficient_quota) error.")]
+    [Fact(Skip = "For manual verification only.")]
     public virtual async Task FunctionCallingUsingCreateWithGetSearchResultsAsync()
     {
         // Arrange
@@ -171,7 +171,7 @@ public virtual async Task FunctionCallingUsingCreateWithGetSearchResultsAsync()
         Assert.NotEmpty(results);
     }
 
-    [Fact(Skip = "Failing in integration tests pipeline with - HTTP 429 (insufficient_quota) error.")]
+    [Fact(Skip = "For manual verification only.")]
     public virtual async Task FunctionCallingUsingGetTextSearchResultsAsync()
     {
         // Arrange

dotnet/src/IntegrationTests/Plugins/Web/Tavily/TavilyTextSearchTests.cs

@@ -0,0 +1,48 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Threading.Tasks;
+using Microsoft.Extensions.Configuration;
+using Microsoft.SemanticKernel.Data;
+using Microsoft.SemanticKernel.Plugins.Web.Tavily;
+using SemanticKernel.IntegrationTests.Data;
+using SemanticKernel.IntegrationTests.TestSettings;
+using Xunit;
+
+namespace SemanticKernel.IntegrationTests.Plugins.Web.Tavily;
+
+/// <summary>
+/// Integration tests for <see cref="TavilyTextSearch"/>.
+/// </summary>
+public class TavilyTextSearchTests : BaseTextSearchTests
+{
+    /// <inheritdoc/>
+    public override Task<ITextSearch> CreateTextSearchAsync()
+    {
+        var configuration = this.Configuration.GetSection("Tavily").Get<TavilyConfiguration>();
+        Assert.NotNull(configuration);
+        Assert.NotNull(configuration.ApiKey);
+
+        return Task.FromResult<ITextSearch>(new TavilyTextSearch(apiKey: configuration.ApiKey));
+    }
+
+    /// <inheritdoc/>
+    public override string GetQuery() => "What is the Semantic Kernel?";
+
+    /// <inheritdoc/>
+    public override TextSearchFilter GetTextSearchFilter() => new TextSearchFilter().Equality("include_domain", "devblogs.microsoft.com");
+
+    /// <inheritdoc/>
+    public override bool VerifySearchResults(object[] results, string query, TextSearchFilter? filter = null)
+    {
+        Assert.NotNull(results);
+        Assert.NotEmpty(results);
+        Assert.Equal(4, results.Length);
+        foreach (var result in results)
+        {
+            Assert.NotNull(result);
+            Assert.IsType<TavilySearchResult>(result);
+        }
+
+        return true;
+    }
+}

dotnet/src/IntegrationTests/TestSettings/TavilyConfiguration.cs

@@ -0,0 +1,13 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+
+namespace SemanticKernel.IntegrationTests.TestSettings;
+
+[SuppressMessage("Performance", "CA1812:Internal class that is apparently never instantiated",
+    Justification = "Configuration classes are instantiated through IConfiguration.")]
+
+internal sealed class TavilyConfiguration(string apiKey)
+{
+    public string ApiKey { get; init; } = apiKey;
+}

dotnet/src/Plugins/Plugins.UnitTests/Web/Tavily/TavilyTextSearchTests.cs

@@ -172,6 +172,106 @@ public async Task GetTextSearchResultsWithCustomResultMapperReturnsSuccessfullyA
         }
     }
 
+    [Fact]
+    public async Task SearchWithAnswerReturnsSuccessfullyAsync()
+    {
+        // Arrange
+        this._messageHandlerStub.AddJsonResponse(File.ReadAllText(WhatIsTheSKResponseJson));
+
+        // Create an ITextSearch instance using Tavily search
+        var textSearch = new TavilyTextSearch(apiKey: "ApiKey", options: new() { HttpClient = this._httpClient, IncludeAnswer = true });
+
+        // Act
+        KernelSearchResults<string> result = await textSearch.SearchAsync("What is the Semantic Kernel?", new() { Top = 4, Skip = 0 });
+
+        // Assert
+        Assert.NotNull(result);
+        Assert.NotNull(result.Results);
+        var resultList = await result.Results.ToListAsync();
+        Assert.NotNull(resultList);
+        Assert.Equal(5, resultList.Count);
+        foreach (var stringResult in resultList)
+        {
+            Assert.NotEmpty(stringResult);
+        }
+    }
+
+    [Fact]
+    public async Task SearchWithImagesReturnsSuccessfullyAsync()
+    {
+        // Arrange
+        this._messageHandlerStub.AddJsonResponse(File.ReadAllText(WhatIsTheSKResponseJson));
+
+        // Create an ITextSearch instance using Tavily search
+        var textSearch = new TavilyTextSearch(apiKey: "ApiKey", options: new() { HttpClient = this._httpClient, IncludeImages = true });
+
+        // Act
+        KernelSearchResults<string> result = await textSearch.SearchAsync("What is the Semantic Kernel?", new() { Top = 4, Skip = 0 });
+
+        // Assert
+        Assert.NotNull(result);
+        Assert.NotNull(result.Results);
+        var resultList = await result.Results.ToListAsync();
+        Assert.NotNull(resultList);
+        Assert.Equal(9, resultList.Count);
+        foreach (var stringResult in resultList)
+        {
+            Assert.NotEmpty(stringResult);
+        }
+    }
+
+    [Fact]
+    public async Task GetTextSearchResultsWithAnswerReturnsSuccessfullyAsync()
+    {
+        // Arrange
+        this._messageHandlerStub.AddJsonResponse(File.ReadAllText(WhatIsTheSKResponseJson));
+
+        // Create an ITextSearch instance using Tavily search
+        var textSearch = new TavilyTextSearch(apiKey: "ApiKey", options: new() { HttpClient = this._httpClient, IncludeAnswer = true });
+
+        // Act
+        KernelSearchResults<TextSearchResult> result = await textSearch.GetTextSearchResultsAsync("What is the Semantic Kernel?", new() { Top = 4, Skip = 0 });
+
+        // Assert
+        Assert.NotNull(result);
+        Assert.NotNull(result.Results);
+        var resultList = await result.Results.ToListAsync();
+        Assert.NotNull(resultList);
+        Assert.Equal(4, resultList.Count);
+        foreach (var textSearchResult in resultList)
+        {
+            Assert.NotNull(textSearchResult.Name);
+            Assert.NotNull(textSearchResult.Value);
+            Assert.NotNull(textSearchResult.Link);
+        }
+    }
+
+    [Fact]
+    public async Task GetTextSearchResultsWithImagesReturnsSuccessfullyAsync()
+    {
+        // Arrange
+        this._messageHandlerStub.AddJsonResponse(File.ReadAllText(WhatIsTheSKResponseJson));
+
+        // Create an ITextSearch instance using Tavily search
+        var textSearch = new TavilyTextSearch(apiKey: "ApiKey", options: new() { HttpClient = this._httpClient, IncludeImages = true, IncludeImageDescriptions = true });
+
+        // Act
+        KernelSearchResults<TextSearchResult> result = await textSearch.GetTextSearchResultsAsync("What is the Semantic Kernel?", new() { Top = 4, Skip = 0 });
+
+        // Assert
+        Assert.NotNull(result);
+        Assert.NotNull(result.Results);
+        var resultList = await result.Results.ToListAsync();
+        Assert.NotNull(resultList);
+        Assert.Equal(9, resultList.Count);
+        foreach (var textSearchResult in resultList)
+        {
+            Assert.NotNull(textSearchResult.Name);
+            Assert.NotNull(textSearchResult.Value);
+            Assert.NotNull(textSearchResult.Link);
+        }
+    }
+
     [Theory]
     [InlineData("topic", "general", "{\"query\":\"What is the Semantic Kernel?\",\"topic\":\"general\",\"max_results\":4}")]
     [InlineData("topic", "news", "{\"query\":\"What is the Semantic Kernel?\",\"topic\":\"news\",\"max_results\":4}")]

dotnet/src/Plugins/Plugins.Web/Tavily/TavilyTextSearch.cs

@@ -164,6 +164,15 @@ private async IAsyncEnumerable<object> GetSearchResultsAsync(TavilySearchRespons
             yield return result;
             await Task.Yield();
         }
+
+        if (this._searchOptions?.IncludeImages ?? false && searchResponse.Images is not null)
+        {
+            foreach (var image in searchResponse.Images!)
+            {
+                yield return image;
+                await Task.Yield();
+            }
+        }
     }
 
     /// <summary>
@@ -183,6 +192,15 @@ private async IAsyncEnumerable<TextSearchResult> GetResultsAsTextSearchResultAsy
             yield return this._resultMapper.MapFromResultToTextSearchResult(result);
             await Task.Yield();
         }
+
+        if (this._searchOptions?.IncludeImages ?? false && searchResponse.Images is not null)
+        {
+            foreach (var image in searchResponse.Images!)
+            {
+                yield return this._resultMapper.MapFromResultToTextSearchResult(image);
+                await Task.Yield();
+            }
+        }
     }
 
     /// <summary>
@@ -208,6 +226,15 @@ private async IAsyncEnumerable<string> GetResultsAsStringAsync(TavilySearchRespo
             yield return this._stringMapper.MapFromResultToString(result);
             await Task.Yield();
         }
+
+        if (this._searchOptions?.IncludeImages ?? false && searchResponse.Images is not null)
+        {
+            foreach (var image in searchResponse.Images!)
+            {
+                yield return this._stringMapper.MapFromResultToString(image);
+                await Task.Yield();
+            }
+        }
     }
 
     /// <summary>
@@ -230,12 +257,15 @@ private sealed class DefaultTextSearchStringMapper : ITextSearchStringMapper
         /// <inheritdoc />
         public string MapFromResultToString(object result)
         {
-            if (result is not TavilySearchResult searchResult)
+            if (result is TavilySearchResult searchResult)
             {
-                throw new ArgumentException("Result must be a TavilySearchResult", nameof(result));
+                return searchResult.RawContent ?? searchResult.Content ?? string.Empty;
             }
-
-            return searchResult.RawContent ?? searchResult.Content ?? string.Empty;
+            else if (result is TavilyImageResult imageResult)
+            {
+                return imageResult.Description ?? string.Empty;
+            }
+            throw new ArgumentException("Result must be a TavilySearchResult", nameof(result));
         }
     }
 
@@ -247,12 +277,17 @@ private sealed class DefaultTextSearchResultMapper : ITextSearchResultMapper
         /// <inheritdoc />
         public TextSearchResult MapFromResultToTextSearchResult(object result)
         {
-            if (result is not TavilySearchResult searchResult)
+            if (result is TavilySearchResult searchResult)
             {
-                throw new ArgumentException("Result must be a TavilySearchResult", nameof(result));
+                return new TextSearchResult(searchResult.RawContent ?? searchResult.Content ?? string.Empty) { Name = searchResult.Title, Link = searchResult.Url };
             }
-
-            return new TextSearchResult(searchResult.RawContent ?? searchResult.Content ?? string.Empty) { Name = searchResult.Title, Link = searchResult.Url };
+            else if (result is TavilyImageResult imageResult)
+            {
+                var uri = new Uri(imageResult.Url);
+                var name = uri.Segments[^1];
+                return new TextSearchResult(imageResult.Description ?? string.Empty) { Name = name, Link = imageResult.Url };
+            }
+            throw new ArgumentException("Result must be a TavilySearchResult", nameof(result));
         }
     }
 
@@ -316,7 +351,9 @@ private TavilySearchRequest BuildRequestContent(string query, TextSearchOptions
             topic,
             timeRange,
             days,
-            this._searchOptions?.SearchDepth,
+#pragma warning disable CA1308 // Lower is preferred over uppercase
+            this._searchOptions?.SearchDepth?.ToString()?.ToLowerInvariant(),
+#pragma warning restore CA1308
             this._searchOptions?.ChunksPerSource,
             this._searchOptions?.IncludeImages,
             this._searchOptions?.IncludeImageDescriptions,

dotnet/src/Plugins/Plugins.Web/Tavily/TavilyTextSearchOptions.cs

@@ -8,7 +8,7 @@
 namespace Microsoft.SemanticKernel.Plugins.Web.Tavily;
 
 /// <summary>
-/// Options used to construct an instance of <see cref="TavilyTextSearch"/>
+/// Options used to construct an instance of <see cref="TavilyTextSearch"/>.
 /// </summary>
 public sealed class TavilyTextSearchOptions
 {
@@ -24,8 +24,7 @@ public sealed class TavilyTextSearchOptions
     /// A basic search costs 1 API Credit, while an advanced search costs 2 API Credits.
     /// Available options: basic, advanced
     /// </summary>
-    // TODO Create an enum
-    public string? SearchDepth { get; set; }
+    public SearchDepth? SearchDepth { get; set; }
 
     /// <summary>
     /// The number of content chunks to retrieve from each source.
@@ -76,3 +75,20 @@ public sealed class TavilyTextSearchOptions
     /// </summary>
     public ITextSearchResultMapper? ResultMapper { get; init; } = null;
 }
+
+/// <summary>
+/// The depth of the search. advanced search is tailored to retrieve
+/// the most relevant sources and content snippets for your query,
+/// while basic search provides generic content snippets from each source.
+/// </summary>
+public enum SearchDepth
+{
+    /// <summary>
+    /// Basic search costs 1 API Credit.
+    /// </summary>
+    Basic,
+    /// <summary>
+    /// Advanced search costs 2 API Credits.
+    /// </summary>
+    Advanced
+}