#4 - Image Generation Tool

#5 - Reasoning Tool
#6 - Refactor tools to use IGrokTool instead of GrokToolDefinition

Author: TWhidden

README.md

@@ -1,12 +1,14 @@
 # GrokSdk 🚀
 
+If you find this tool helpful or are able to use it in your projects, please drop me a note on [X](https://x.com/twhidden) to let me know—it encourages me to keep it going! 
+
 [![NuGet](https://img.shields.io/nuget/v/GrokSdk.svg)](https://www.nuget.org/packages/GrokSdk/)
 [![NuGet Downloads](https://img.shields.io/nuget/dt/GrokSdk.svg)](https://www.nuget.org/packages/GrokSdk/)
 [![Build Status](https://github.com/twhidden/grok/actions/workflows/ci.yml/badge.svg)](https://github.com/twhidden/grok/actions/workflows/ci.yml)
 [![.NET 8.0](https://img.shields.io/badge/.NET-8.0-blue.svg)](https://dotnet.microsoft.com/)
 [![.NET Standard 2.0](https://img.shields.io/badge/.NET%20Standard-2.0-blue.svg)](https://dotnet.microsoft.com/en-us/platform/dotnet-standard)
 
-An unofficial .NET library for interacting with Grok's API, with `GrokThread` as its centerpiece. This library streamlines conversation management, tool integration (e.g., image generation), and real-time streaming in .NET applications.
+An unofficial .NET library for interacting with Grok's API, with `GrokThread` as its centerpiece. This library streamlines conversation management, tool integration (e.g., image generation and reasoning), and real-time streaming in .NET applications.
 
 ## Installation
 
@@ -46,12 +48,18 @@ internal class Program
         // Show welcome message
         Console.WriteLine("Welcome to the Grok Chat Console. Type your questions below. Type 'quit' to exit.");
 
-        // Register an image generation tool
+        // Register your own tool (Generic)
         thread.RegisterTool(new GrokToolDefinition(
-            ImageGeneratorHelper.GrokToolName,
-            "Generate images based on user input request;",
-            ImageGeneratorHelper.GrokArgsRequest,
-            ImageGeneratorHelper.ProcessGrokRequestForImage));
+            "Tool Name",
+            "Tool Instruction",
+            "Tool Arguments",
+            <ToolExecutionFunctionCallback()>));
+        
+        // Built in Grok Image Generation Tool
+        thread.RegisterTool(new GrokToolImageGeneration(sdk))
+
+        // Built in Grok Reasoning Tool
+        thread.RegisterTool(new GrokToolReasoning(sdk))
 
         // Preload context with neutral discussion (non-API processed)
         thread.AddUserMessage("Alex Said: I tried a new coffee shop today.");
@@ -98,6 +106,10 @@ internal class Program
                                 Console.ForegroundColor = ConsoleColor.Red;
                                 Console.WriteLine("Error Processing...");
                                 break;
+                            case StreamState.CallingTool:
+                                Console.ForegroundColor = ConsoleColor.Magenta;
+                                Console.WriteLine("Calling Tool...");
+                                break;                                
                         }
                         Console.ResetColor();
                     }
@@ -197,6 +209,44 @@ internal static class ImageGeneratorHelper
 - **Compression**: Shrinks history with `CompressHistoryAsync` to optimize tokens.
 - **State Tracking**: Monitors states (`Thinking`, `Streaming`, etc.) for feedback.
 
+## New Built-in Tools
+
+### Image Generation Tool
+The `GrokToolImageGeneration` tool allows Grok to generate images based on a text prompt. Users can specify the number of images and the response format (`url` or `base64`).
+
+#### Usage Example
+```csharp
+var thread = new GrokThread(client);
+thread.RegisterTool(new GrokToolImageGeneration(client));
+thread.AddSystemInstruction("You can generate images using the 'generate_image' tool.");
+
+await foreach (var message in thread.AskQuestion("Generate an image of a sunset"))
+{
+    if (message is GrokToolResponse toolResponse && toolResponse.ToolName == "generate_image")
+    {
+        Console.WriteLine($"Image URL: {toolResponse.ToolResponse}");
+    }
+}
+```
+
+### Reasoning Tool
+The `GrokReasoningTool` enables Grok to perform complex reasoning on a given problem, with configurable effort levels ("low" or "high").
+
+#### Usage Example
+```csharp
+var thread = new GrokThread(client);
+thread.RegisterTool(new GrokReasoningTool(client));
+thread.AddSystemInstruction("You can perform reasoning using the 'reason' tool.");
+
+await foreach (var message in thread.AskQuestion("Explain why the sky is blue with high effort"))
+{
+    if (message is GrokToolResponse toolResponse && toolResponse.ToolName == "reason")
+    {
+        Console.WriteLine($"Reasoning: {toolResponse.ToolResponse}");
+    }
+}
+```
+
 ## Additional Examples
 
 ### Simple Chat
@@ -245,4 +295,4 @@ Visit [GitHub](https://github.com/twhidden/grok):
 
 ## License
 
-This project is licensed under the MIT License, free for everyone to use, modify, and distribute with no cost or warranty
+This project is licensed under the MIT License, free for everyone to use, modify, and distribute with no cost or warranty.

src/GrokSdk.ConsoleDemo/Program.cs

@@ -1,17 +1,22 @@
 using GrokSdk;
+using GrokSdk.Tools;
 
 internal class Program
 {
     private static async Task Main(string[] args)
     {
         // Initialize the HTTP client and GrokClient
+        string apiKey = GetApiKey();
         var httpClient = new HttpClient();
-        var sdk = new GrokClient(httpClient,
-            "xai-Key-Here");
+        var sdk = new GrokClient(httpClient, apiKey);
 
         // Create a GrokThread instance to manage the conversation
         var thread = new GrokThread(sdk);
 
+        // Register some pre-made tools
+        thread.RegisterTool(new GrokToolImageGeneration(sdk));
+        thread.RegisterTool(new GrokToolReasoning(sdk));
+
         // Welcome message
         Console.WriteLine("Welcome to the Grok Chat Console. Type your questions below. Type 'quit' to exit.");
 
@@ -54,6 +59,10 @@ private static async Task Main(string[] args)
                                 Console.ForegroundColor = ConsoleColor.Red;
                                 Console.WriteLine("Error Processing...");
                                 break;
+                            case StreamState.CallingTool:
+                                Console.ForegroundColor = ConsoleColor.Magenta;
+                                Console.WriteLine("Calling Tool...");
+                                break;
                         }
 
                         Console.ResetColor();
@@ -78,4 +87,32 @@ private static async Task Main(string[] args)
         // Farewell message
         Console.WriteLine("Goodbye!");
     }
+
+    /// <summary>
+    /// Retrieves the xAI API key, either from a stored file in the current directory or by prompting the user.
+    /// </summary>
+    /// <returns>The xAI API key.</returns>
+    private static string GetApiKey()
+    {
+        string filePath = Path.Combine(Directory.GetCurrentDirectory(), ".xai_key");
+        if (File.Exists(filePath))
+        {
+            string key = File.ReadAllText(filePath).Trim();
+            if (!string.IsNullOrEmpty(key))
+            {
+                return key;
+            }
+        }
+
+        Console.WriteLine("Please enter your xAI API key:");
+        string enteredKey = Console.ReadLine().Trim();
+        while (string.IsNullOrEmpty(enteredKey))
+        {
+            Console.WriteLine("API key cannot be empty. Please enter a valid key:");
+            enteredKey = Console.ReadLine().Trim();
+        }
+
+        File.WriteAllText(filePath, enteredKey);
+        return enteredKey;
+    }
 }

src/GrokSdk.Tests/GrokToolTests.cs

@@ -0,0 +1,210 @@
+using GrokSdk.Tools;
+using Newtonsoft.Json;
+
+namespace GrokSdk.Tests;
+
+[TestClass]
+public class GrokToolTests : GrokClientTestBaseClass
+{
+    [ClassInitialize]
+    public static void ClassInitialize(TestContext context)
+    {
+        ApiToken = GetApiKeyFromFileOrEnv();
+    }
+
+    [TestMethod]
+    [TestCategory("Live")]
+    public async Task ExecuteAsync_LiveImageGeneration_ReturnsImageData()
+    {
+        using var httpClient = new HttpClient();
+        var client = new GrokClient(httpClient, ApiToken ?? throw new Exception("API Token not set"));
+
+        // Test with 'url' response format
+        var toolUrl = new GrokToolImageGeneration(client);
+        var argsUrl = JsonConvert.SerializeObject(new
+            { prompt = "A serene mountain landscape", n = 1, response_format = "url" });
+        await WaitForRateLimitAsync();
+        string? resultUrl = null;
+        try
+        {
+            resultUrl = await toolUrl.ExecuteAsync(argsUrl);
+        }
+        catch (GrokSdkException ex)
+        {
+            Assert.Fail($"API call failed with status {ex.StatusCode}: {ex.Message}\nResponse: {ex.Response}");
+        }
+
+        Assert.IsNotNull(resultUrl, "Response should not be null.");
+        var responseUrl = JsonConvert.DeserializeObject<dynamic>(resultUrl);
+        Assert.IsNull(responseUrl.error, "Error should be null.");
+        Assert.IsNotNull(responseUrl.images, "Images should not be null.");
+        Assert.AreEqual(1, responseUrl.images.Count, "Expected 1 image.");
+        Assert.IsTrue(Uri.IsWellFormedUriString(responseUrl.images[0].url.ToString(), UriKind.Absolute),
+            "Image URL should be valid.");
+
+        // Test with 'base64' response format
+        var toolBase64 = new GrokToolImageGeneration(client);
+        var argsBase64 =
+            JsonConvert.SerializeObject(new { prompt = "A futuristic robot", n = 1, response_format = "base64" });
+        await WaitForRateLimitAsync();
+        string resultBase64 = null;
+        try
+        {
+            resultBase64 = await toolBase64.ExecuteAsync(argsBase64);
+        }
+        catch (GrokSdkException ex)
+        {
+            Assert.Fail($"API call failed with status {ex.StatusCode}: {ex.Message}\nResponse: {ex.Response}");
+        }
+
+        Assert.IsNotNull(resultBase64, "Response should not be null.");
+        var responseBase64 = JsonConvert.DeserializeObject<dynamic>(resultBase64);
+        Assert.IsNull(responseBase64.error, "Error should be null.");
+        Assert.IsNotNull(responseBase64.images, "Images should not be null.");
+        Assert.AreEqual(1, responseBase64.images.Count, "Expected 1 image.");
+        Assert.IsNotNull(responseBase64.images[0].b64_json, "Base64 image data should not be null.");
+
+        // Safety Check for Live Unit Tests to prevent API exhaustion
+        await WaitForRateLimitAsync();
+    }
+
+    [TestMethod]
+    [TestCategory("Live")]
+    public async Task GrokThread_WithImageTool_GeneratesTwoImageUrls()
+    {
+        // Arrange
+        using var httpClient = new HttpClient();
+        var client = new GrokClient(httpClient, ApiToken ?? throw new Exception("API Token not set"));
+
+        var thread = new GrokThread(client);
+        thread.RegisterTool(new GrokToolImageGeneration(client));
+
+        thread.AddSystemInstruction(
+            "You are an assistant that can generate images using the 'generate_image' tool. " +
+            "When the user asks to generate images, use the tool with the specified prompt and number of images, " +
+            "and include the image URLs in your response."
+        );
+
+        var userMessage =
+            "Use the generate_image tool to generate two images of a sunset with response_format 'url' and return their URLs.";
+
+        // Act
+        await WaitForRateLimitAsync();
+
+        var toolCalled = false;
+        string toolResponseJson = null;
+
+        await foreach (var message in thread.AskQuestion(userMessage))
+            if (message is GrokToolResponse { ToolName: "generate_image" } toolResponse1)
+            {
+                toolCalled = true;
+                toolResponseJson = toolResponse1.ToolResponse;
+                break; // Assuming only one tool call for simplicity
+            }
+
+        // Assert
+        Assert.IsTrue(toolCalled, "The 'generate_image' tool was not called.");
+
+        var toolResponse = JsonConvert.DeserializeObject<dynamic>(toolResponseJson);
+        if (toolResponse.error != null) Assert.Fail($"Tool returned an error: {toolResponse.error}");
+
+        var images = toolResponse.images;
+        Assert.IsNotNull(images, "Images array is missing.");
+        Assert.AreEqual(2, images.Count, "Expected two images.");
+
+        foreach (var image in images)
+        {
+            Assert.IsNotNull(image.url, "Image URL is missing.");
+            Assert.IsTrue(Uri.IsWellFormedUriString(image.url.ToString(), UriKind.Absolute), "Image URL is invalid.");
+        }
+
+        await WaitForRateLimitAsync();
+    }
+
+    [TestMethod]
+    [TestCategory("Live")]
+    public async Task ExecuteAsync_LiveReasoning_ReturnsReasoningResult()
+    {
+        using var httpClient = new HttpClient();
+        var client = new GrokClient(httpClient, ApiToken ?? throw new Exception("API Token not set"));
+
+        // Test with effort "low"
+        var tool = new GrokToolReasoning(client);
+        var argsLow = JsonConvert.SerializeObject(new { problem = "Why is the sky blue?", effort = "low" });
+        await WaitForRateLimitAsync();
+        string? resultLow = null;
+        try
+        {
+            resultLow = await tool.ExecuteAsync(argsLow);
+        }
+        catch (GrokSdkException ex)
+        {
+            Assert.Fail($"API call failed with status {ex.StatusCode}: {ex.Message}\nResponse: {ex.Response}");
+        }
+
+        Assert.IsNotNull(resultLow, "Response should not be null.");
+        var responseLow = JsonConvert.DeserializeObject<dynamic>(resultLow);
+        Assert.IsNull(responseLow.error, "Error should be null for valid request.");
+        Assert.IsNotNull(responseLow.reasoning, "Reasoning should not be null.");
+        Assert.IsTrue(responseLow.reasoning.ToString().Length > 0, "Reasoning should not be empty.");
+
+        // Test with effort "high"
+        var argsHigh =
+            JsonConvert.SerializeObject(new { problem = "Explain quantum mechanics briefly.", effort = "high" });
+        await WaitForRateLimitAsync();
+        string resultHigh = null;
+        try
+        {
+            resultHigh = await tool.ExecuteAsync(argsHigh);
+        }
+        catch (GrokSdkException ex)
+        {
+            Assert.Fail($"API call failed with status {ex.StatusCode}: {ex.Message}\nResponse: {ex.Response}");
+        }
+
+        Assert.IsNotNull(resultHigh, "Response should not be null.");
+        var responseHigh = JsonConvert.DeserializeObject<dynamic>(resultHigh);
+        Assert.IsNull(responseHigh.error, "Error should be null for valid request.");
+        Assert.IsNotNull(responseHigh.reasoning, "Reasoning should not be null.");
+        Assert.IsTrue(responseHigh.reasoning.ToString().Length > 0, "Reasoning should not be empty.");
+
+        // Test with invalid effort
+        var argsInvalidEffort = JsonConvert.SerializeObject(new { problem = "Some problem", effort = "medium" });
+        await WaitForRateLimitAsync();
+        string resultInvalidEffort = null;
+        try
+        {
+            resultInvalidEffort = await tool.ExecuteAsync(argsInvalidEffort);
+        }
+        catch (GrokSdkException ex)
+        {
+            Assert.Fail($"API call failed with status {ex.StatusCode}: {ex.Message}\nResponse: {ex.Response}");
+        }
+
+        Assert.IsNotNull(resultInvalidEffort, "Response should not be null.");
+        var responseInvalidEffort = JsonConvert.DeserializeObject<dynamic>(resultInvalidEffort);
+        Assert.IsNotNull(responseInvalidEffort.error, "Error should not be null for invalid effort.");
+        Assert.AreEqual("Invalid effort level. Must be 'low' or 'high'.", responseInvalidEffort.error.ToString());
+
+        // Test with missing problem
+        var argsMissingProblem = JsonConvert.SerializeObject(new { effort = "low" });
+        await WaitForRateLimitAsync();
+        string resultMissingProblem = null;
+        try
+        {
+            resultMissingProblem = await tool.ExecuteAsync(argsMissingProblem);
+        }
+        catch (GrokSdkException ex)
+        {
+            Assert.Fail($"API call failed with status {ex.StatusCode}: {ex.Message}\nResponse: {ex.Response}");
+        }
+
+        Assert.IsNotNull(resultMissingProblem, "Response should not be null.");
+        var responseMissingProblem = JsonConvert.DeserializeObject<dynamic>(resultMissingProblem);
+        Assert.IsNotNull(responseMissingProblem.error, "Error should not be null for missing problem.");
+        Assert.AreEqual("Problem cannot be empty.", responseMissingProblem.error.ToString());
+
+        // Safety Check for Live Unit Tests to prevent API exhaustion
+        await WaitForRateLimitAsync();
+    }
+}

src/GrokSdk/GrokSdk.csproj

@@ -9,7 +9,7 @@
 		<!-- NuGet Metadata -->
 		<NuspecFile>GrokSdk.nuspec</NuspecFile>
 		<PackageId>Grok</PackageId>
-		<Version>0.5.0</Version>
+		<Version>1.0.0</Version>
 		<Authors>TWhidden</Authors>
 		<Description>xAI Grok dotnet integration</Description>
 		<PackageTags>xAI;Grok;dotnet</PackageTags>