Release 1.9.3

LoveDoLove · web-flow · commit 8653be321a54 · 2025-11-06T21:01:28.000+08:00
* Add Gemini grounding support and config options

Introduces Google Search grounding capabilities to GeminiHelper, including new config options for enabling grounding, setting thresholds, and choosing grounding mode. Updates IGeminiHelper interface and appsettings.json to support these features. Also refactors ImagenHelper for improved type safety.

* Bump version to 1.9.3 in CommonUtilities.csproj

Updated AssemblyVersion and FileVersion to 1.9.3 to reflect new release. No other changes made.
diff --git a/CommonUtilities/CommonUtilities.csproj b/CommonUtilities/CommonUtilities.csproj
@@ -13,8 +13,8 @@
 		<Description>A modular, production-ready C#/.NET utility library and toolkit for rapid development.</Description>
 		<RepositoryUrl>https://github.com/LoveDoLove/CS_CommonUtilities</RepositoryUrl>
 		<RepositoryType>git</RepositoryType>
-		<AssemblyVersion>1.9.2</AssemblyVersion>
-		<FileVersion>1.9.2</FileVersion>
+		<AssemblyVersion>1.9.3</AssemblyVersion>
+		<FileVersion>1.9.3</FileVersion>
 		<PackageLicenseFile>LICENSE</PackageLicenseFile>
 		<PackageRequireLicenseAcceptance>True</PackageRequireLicenseAcceptance>
 	</PropertyGroup>
diff --git a/CommonUtilities/Helpers/GoogleAI/GeminiConfig.cs b/CommonUtilities/Helpers/GoogleAI/GeminiConfig.cs
@@ -30,7 +30,7 @@ public class GeminiConfig
     /// <summary>
     ///     Model name (e.g., "models/gemini-1.5-flash", "models/gemini-2.0-flash-exp").
     /// </summary>
-    public string Model { get; set; } = "models/gemini-1.5-flash";
+    public string Model { get; set; } = "models/gemini-2.5-flash-lite";
 
     /// <summary>
     ///     Optional: Project ID for Vertex AI.
@@ -53,4 +53,26 @@ public class GeminiConfig
     /// </summary>
     [DefaultValue(false)]
     public bool ExpressMode { get; set; } = false;
+
+    /// <summary>
+    ///     Optional: Enable Google Search grounding for web search capabilities (default: false).
+    ///     When enabled, Gemini can search the web to provide current and factual information.
+    /// </summary>
+    [DefaultValue(false)]
+    public bool EnableGrounding { get; set; } = false;
+
+    /// <summary>
+    ///     Optional: Dynamic retrieval threshold for grounding (0.0 to 1.0, default: 0.7).
+    ///     The model will only perform a web search if its confidence in answering from its own knowledge
+    ///     falls below this threshold. Set to 1.0 to always search, or 0.0 to never search.
+    /// </summary>
+    [DefaultValue(0.7)]
+    public double GroundingThreshold { get; set; } = 0.7;
+
+    /// <summary>
+    ///     Optional: Grounding mode ("DYNAMIC" for dynamic threshold, "ALWAYS" to always ground).
+    ///     Default: "DYNAMIC" - only searches when confidence is below threshold.
+    /// </summary>
+    [DefaultValue("DYNAMIC")]
+    public string GroundingMode { get; set; } = "DYNAMIC";
 }
diff --git a/CommonUtilities/Helpers/GoogleAI/GeminiHelper.cs b/CommonUtilities/Helpers/GoogleAI/GeminiHelper.cs
@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+using System.Text;
+using System.Text.Json;
 using GenerativeAI;
 using GenerativeAI.Types;
 
@@ -20,12 +22,15 @@ namespace CommonUtilities.Helpers.GoogleAI;
 /// <summary>
 ///     Helper for Google Gemini AI models.
 ///     Supports text generation, chat, streaming, and multimodal input (text + images/files).
+///     Includes grounding with Google Search for web-based information retrieval.
 ///     Reference: https://github.com/gunpal5/google_generativeai
 /// </summary>
 public class GeminiHelper : IGeminiHelper
 {
+    private const string GeminiApiUrl = "https://generativelanguage.googleapis.com/v1beta/models";
     private readonly GeminiConfig _config;
     private readonly GoogleAi _googleAi;
+    private readonly HttpClient _httpClient;
     private readonly GenerativeModel _model;
 
     /// <summary>
@@ -36,24 +41,50 @@ public GeminiHelper(GeminiConfig config)
         _config = config ?? throw new ArgumentNullException(nameof(config));
         _googleAi = new GoogleAi(_config.ApiKey);
         _model = _googleAi.CreateGenerativeModel(_config.Model);
+        _httpClient = new HttpClient();
     }
 
     /// <summary>
     ///     Generates text content from a prompt using the configured Gemini model.
     /// </summary>
     public async Task<string> GenerateTextAsync(string prompt)
     {
-        var response = await _model.GenerateContentAsync(prompt);
+        GenerateContentResponse? response = await _model.GenerateContentAsync(prompt);
         return response?.Text() ?? string.Empty;
     }
 
+    /// <summary>
+    ///     Generates text with grounding enabled (Google Search).
+    ///     This allows the model to search the web for current and factual information.
+    /// </summary>
+    /// <param name="prompt">The prompt to send to the model</param>
+    /// <returns>Tuple of (response text, grounding metadata if available)</returns>
+    public async Task<(string responseText, GroundingMetadata? metadata)> GenerateTextWithGroundingAsync(string prompt)
+    {
+        try
+        {
+            // Only use grounding if enabled in config
+            if (!_config.EnableGrounding)
+                return (await GenerateTextAsync(prompt), null);
+
+            // Use REST API for grounding support
+            return await CallGeminiWithGroundingAsync(prompt);
+        }
+        catch (Exception ex)
+        {
+            // If grounding fails, fall back to regular generation
+            Console.WriteLine($"Grounding error: {ex.Message}. Falling back to regular generation.");
+            return (await GenerateTextAsync(prompt), null);
+        }
+    }
+
     /// <summary>
     ///     Starts a chat session and sends a message.
     /// </summary>
     public async Task<string> SendChatMessageAsync(string message)
     {
-        var chat = _model.StartChat();
-        var response = await chat.GenerateContentAsync(message);
+        ChatSession chat = _model.StartChat();
+        GenerateContentResponse? response = await chat.GenerateContentAsync(message);
         return response?.Text() ?? string.Empty;
     }
 
@@ -62,7 +93,8 @@ public async Task<string> SendChatMessageAsync(string message)
     /// </summary>
     public async IAsyncEnumerable<string> StreamTextAsync(string prompt)
     {
-        await foreach (var chunk in _model.StreamContentAsync(prompt)) yield return chunk?.Text() ?? string.Empty;
+        await foreach (GenerateContentResponse? chunk in _model.StreamContentAsync(prompt))
+            yield return chunk?.Text() ?? string.Empty;
     }
 
     /// <summary>
@@ -72,10 +104,10 @@ public async IAsyncEnumerable<string> StreamTextAsync(string prompt)
     /// </summary>
     public async Task<string> GenerateMultimodalContentAsync(string prompt, string filePath)
     {
-        var request = new GenerateContentRequest();
+        GenerateContentRequest request = new();
         request.AddText(prompt);
         request.AddInlineFile(filePath);
-        var response = await _model.GenerateContentAsync(request);
+        GenerateContentResponse? response = await _model.GenerateContentAsync(request);
         return response?.Text() ?? string.Empty;
     }
 
@@ -87,4 +119,200 @@ public Task<string> GetModelInfoAsync(string modelId)
         throw new NotSupportedException(
             "Model info retrieval is not supported by the current Google_GenerativeAI SDK.");
     }
+
+    /// <summary>
+    ///     Calls the Gemini API with grounding tools via REST API.
+    ///     This method bypasses the SDK to access grounding features directly.
+    /// </summary>
+    private async Task<(string responseText, GroundingMetadata? metadata)> CallGeminiWithGroundingAsync(string prompt)
+    {
+        try
+        {
+            // Build the request body with grounding tools
+            object requestBody = BuildGroundingRequest(prompt);
+
+            // Extract model name without "models/" prefix if present
+            string modelId = _config.Model.Replace("models/", "");
+            string url = $"{GeminiApiUrl}/{modelId}:generateContent?key={_config.ApiKey}";
+
+            // Make the API call
+            StringContent content = new(
+                JsonSerializer.Serialize(requestBody),
+                Encoding.UTF8,
+                "application/json"
+            );
+
+            HttpResponseMessage response = await _httpClient.PostAsync(url, content);
+            response.EnsureSuccessStatusCode();
+
+            string responseContent = await response.Content.ReadAsStringAsync();
+            JsonDocument jsonDocument = JsonDocument.Parse(responseContent);
+            JsonElement root = jsonDocument.RootElement;
+
+            // Extract the text response
+            string responseText = string.Empty;
+            if (root.TryGetProperty("candidates", out JsonElement candidates) && candidates.GetArrayLength() > 0)
+            {
+                JsonElement firstCandidate = candidates[0];
+                if (firstCandidate.TryGetProperty("content", out JsonElement contentElement) &&
+                    contentElement.TryGetProperty("parts", out JsonElement parts) && parts.GetArrayLength() > 0)
+                    if (parts[0].TryGetProperty("text", out JsonElement textElement))
+                        responseText = textElement.GetString() ?? string.Empty;
+
+                // Extract grounding metadata if available
+                GroundingMetadata? metadata = ExtractGroundingMetadata(firstCandidate);
+                return (responseText, metadata);
+            }
+
+            return (responseText, null);
+        }
+        catch (HttpRequestException ex)
+        {
+            Console.WriteLine($"HTTP error in grounding call: {ex.Message}");
+            throw;
+        }
+    }
+
+    /// <summary>
+    ///     Builds the request body for Gemini API with grounding tools.
+    /// </summary>
+    private object BuildGroundingRequest(string prompt)
+    {
+        // Build tools array based on grounding mode
+        List<object> tools = new();
+
+        if (_config.GroundingMode == "DYNAMIC")
+            // Dynamic grounding with threshold
+            tools.Add(new
+            {
+                google_search_retrieval = new
+                {
+                    dynamic_retrieval_config = new
+                    {
+                        mode = "MODE_DYNAMIC",
+                        dynamic_threshold = _config.GroundingThreshold
+                    }
+                }
+            });
+        else if (_config.GroundingMode == "ALWAYS")
+            // Always perform web search
+            tools.Add(new { google_search = new { } });
+
+        return new
+        {
+            contents = new[]
+            {
+                new
+                {
+                    parts = new[]
+                    {
+                        new { text = prompt }
+                    }
+                }
+            },
+            tools
+        };
+    }
+
+    /// <summary>
+    ///     Extracts grounding metadata from the Gemini API response.
+    /// </summary>
+    private GroundingMetadata? ExtractGroundingMetadata(JsonElement candidate)
+    {
+        if (!candidate.TryGetProperty("groundingMetadata", out JsonElement metadata))
+            return null;
+
+        GroundingMetadata groundingData = new();
+
+        // Extract search queries
+        if (metadata.TryGetProperty("searchQueries", out JsonElement queries))
+            foreach (JsonElement query in queries.EnumerateArray())
+                if (query.TryGetProperty("text", out JsonElement queryText))
+                    groundingData.SearchQueries.Add(new SearchQuery
+                    {
+                        Text = queryText.GetString() ?? string.Empty
+                    });
+
+        // Extract web results
+        if (metadata.TryGetProperty("webResults", out JsonElement results))
+            foreach (JsonElement result in results.EnumerateArray())
+            {
+                WebResult webResult = new();
+                if (result.TryGetProperty("url", out JsonElement url))
+                    webResult.Url = url.GetString() ?? string.Empty;
+                if (result.TryGetProperty("title", out JsonElement title))
+                    webResult.Title = title.GetString() ?? string.Empty;
+                if (result.TryGetProperty("snippet", out JsonElement snippet))
+                    webResult.Snippet = snippet.GetString() ?? string.Empty;
+                groundingData.WebResults.Add(webResult);
+            }
+
+        // Extract citations
+        if (metadata.TryGetProperty("citations", out JsonElement citations))
+            foreach (JsonElement citation in citations.EnumerateArray())
+            {
+                Citation citationData = new();
+                if (citation.TryGetProperty("startIndex", out JsonElement startIndex))
+                    citationData.StartIndex = startIndex.GetInt32();
+                if (citation.TryGetProperty("endIndex", out JsonElement endIndex))
+                    citationData.EndIndex = endIndex.GetInt32();
+                if (citation.TryGetProperty("uri", out JsonElement uri))
+                    citationData.Uri = uri.GetString() ?? string.Empty;
+                groundingData.Citations.Add(citationData);
+            }
+
+        return groundingData.SearchQueries.Count > 0 || groundingData.WebResults.Count > 0
+            ? groundingData
+            : null;
+    }
+}
+
+/// <summary>
+///     Represents grounding metadata returned from Gemini when using grounding tools.
+///     Contains information about web search queries, results, and citations.
+/// </summary>
+public class GroundingMetadata
+{
+    /// <summary>
+    ///     Search queries generated and executed by the model.
+    /// </summary>
+    public List<SearchQuery> SearchQueries { get; set; } = new();
+
+    /// <summary>
+    ///     Web search results retrieved for grounding.
+    /// </summary>
+    public List<WebResult> WebResults { get; set; } = new();
+
+    /// <summary>
+    ///     Citation information embedded in the response.
+    /// </summary>
+    public List<Citation> Citations { get; set; } = new();
+}
+
+/// <summary>
+///     Represents a search query generated by the model for grounding.
+/// </summary>
+public class SearchQuery
+{
+    public string Text { get; set; } = string.Empty;
+}
+
+/// <summary>
+///     Represents a web search result used for grounding.
+/// </summary>
+public class WebResult
+{
+    public string Url { get; set; } = string.Empty;
+    public string Title { get; set; } = string.Empty;
+    public string Snippet { get; set; } = string.Empty;
+}
+
+/// <summary>
+///     Represents a citation in the grounded response.
+/// </summary>
+public class Citation
+{
+    public int StartIndex { get; set; }
+    public int EndIndex { get; set; }
+    public string Uri { get; set; } = string.Empty;
 }
diff --git a/CommonUtilities/Helpers/GoogleAI/IGeminiHelper.cs b/CommonUtilities/Helpers/GoogleAI/IGeminiHelper.cs
@@ -17,6 +17,7 @@ namespace CommonUtilities.Helpers.GoogleAI;
 /// <summary>
 ///     Interface for Google Gemini helper.
 ///     Gemini models support text generation, chat, streaming, and multimodal input (text + images/files).
+///     Includes support for grounding with Google Search for web-based information.
 ///     Reference: https://github.com/gunpal5/google_generativeai#usage
 /// </summary>
 public interface IGeminiHelper
@@ -26,6 +27,14 @@ public interface IGeminiHelper
     /// </summary>
     Task<string> GenerateTextAsync(string prompt);
 
+    /// <summary>
+    ///     Generates text with grounding enabled (Google Search).
+    ///     This allows the model to search the web for current and factual information.
+    /// </summary>
+    /// <param name="prompt">The prompt to send to the model</param>
+    /// <returns>Tuple of (response text, grounding metadata if available)</returns>
+    Task<(string responseText, GroundingMetadata? metadata)> GenerateTextWithGroundingAsync(string prompt);
+
     /// <summary>
     ///     Starts a chat session and sends a message.
     /// </summary>
diff --git a/CommonUtilities/Helpers/GoogleAI/ImagenHelper.cs b/CommonUtilities/Helpers/GoogleAI/ImagenHelper.cs
diff --git a/CommonUtilities/appsettings.json b/CommonUtilities/appsettings.json
