Add ISpeechToTextClient support via GrokSpeechToTextClient

Implements ISpeechToTextClient for xAI's Grok models, including:

- GrokSpeechToTextClient: unary transcription via POST /v1/stt and
  streaming transcription via wss://.../v1/stt WebSocket protocol.
  Handles session handshake, chunked audio upload, interim/final
  transcript events, word-level timing, and language detection.

- GrokSpeechToTextOptions: Grok-specific options for audio format,
  sample rate, multichannel, diarization, interim results, and
  endpointing timeout.

- AsISpeechToTextClient() extension on GrokClient wires up the
  client with the correct HTTP handler and WebSocket factory.

Fix: voice REST clients (TTS and STT) were accidentally reusing the
gRPC channel's BalancerHttpHandler, which throws for plain HTTP/1.1
requests. Added GrokClient.HttpHandler, backed by a separate
httpHandlers cache using the same Polly retry pipeline but independent
of the gRPC channel. AsITextToSpeechClient and AsISpeechToTextClient
now use client.HttpHandler instead of client.ChannelHandler.Handler.
The channels dictionary now holds ChannelBase directly rather than a
tuple, since the HttpMessageHandler is no longer needed from it.

Add TextToSpeech_SpeechToText integration test that streams TTS audio
to a temp file and transcribes it back with STT, asserting the
roundtrip text matches (punctuation-insensitive via NormalizeTranscription).

Update readme with ISpeechToTextClient usage examples alongside the
existing TTS documentation.

Author: kzu

AGENTS.md

@@ -1,5 +1,8 @@
 # xAI SDK implementation notes
 
-- `GrokClient` is primarily backed by generated gRPC protocol clients, but text to speech uses xAI's documented REST/WebSocket voice endpoints because there are no generated TTS protocol types in `src\xAI.Protocol`.
+- `GrokClient` is primarily backed by generated gRPC protocol clients, but voice features use xAI's documented REST/WebSocket endpoints because there are no generated voice protocol types in `src\xAI.Protocol`.
+- Voice REST calls use `GrokClient.HttpHandler` (backed by `httpHandlers` cache) — a plain `SocketsHttpHandler`+Polly pipeline separate from the gRPC channel. `ChannelHandler` returns `ChannelBase` only; there is no `.Handler` property on it.
 - `AsITextToSpeechClient` returns an `ITextToSpeechClient` implementation that uses `POST /v1/tts` for unary audio and `wss://.../v1/tts` for streaming audio.
+- `AsISpeechToTextClient` returns an `ISpeechToTextClient` implementation that uses `POST /v1/stt` for file transcription and `wss://.../v1/stt` for raw-audio streaming transcription.
 - TTS defaults follow xAI docs: voice `eve`, language `en` when omitted by `TextToSpeechOptions`, and MP3 output when no codec is specified.
+- STT streaming defaults follow xAI docs: encoding `pcm` and sample rate `16000` when omitted; WebSocket input must be raw encoded audio, not MP3/WAV container bytes.

readme.md

@@ -51,6 +51,12 @@ var speech = new GrokClient(Environment.GetEnvironmentVariable("XAI_API_KEY")!)
 
 var audio = await speech.GetAudioAsync("Hello! Welcome to xAI text to speech.",
     new TextToSpeechOptions { VoiceId = "eve", Language = "en" });
+
+var transcription = new GrokClient(Environment.GetEnvironmentVariable("XAI_API_KEY")!)
+    .AsISpeechToTextClient();
+
+var text = await transcription.GetTextAsync(File.OpenRead("audio.mp3"),
+    new SpeechToTextOptions { TextLanguage = "en" });
 ```
 
 ## File Attachments
@@ -402,6 +408,8 @@ Console.WriteLine($"Edited image URL: {editedImage.Uri}");
 ## Text to Speech
 
 Grok supports text to speech via the `ITextToSpeechClient` abstraction from Microsoft.Extensions.AI.
+See the [xAI text to speech docs](https://docs.x.ai/developers/model-capabilities/audio/text-to-speech)
+for supported voices, formats, and streaming details.
 Use `AsITextToSpeechClient` to get a TTS client:
 
 ```csharp
@@ -465,6 +473,87 @@ var options = new GrokTextToSpeechOptions
 var response = await speech.GetAudioAsync("Streaming at 24 kHz, 128 kbps.", options);
 ```
 
+## Speech to Text
+
+Grok supports speech to text via the `ISpeechToTextClient` abstraction from Microsoft.Extensions.AI.
+See the [xAI speech to text docs](https://docs.x.ai/developers/model-capabilities/audio/speech-to-text)
+for supported languages, audio formats, diarization, multichannel audio, and streaming details.
+Use `AsISpeechToTextClient` to get an STT client:
+
+```csharp
+var transcription = new GrokClient(Environment.GetEnvironmentVariable("XAI_API_KEY")!)
+    .AsISpeechToTextClient();
+```
+
+### Unary (single response)
+
+Call `GetTextAsync` to transcribe an audio file in a single request. The result contains transcript 
+text, timing information, and the raw xAI response:
+
+```csharp
+await using var audio = File.OpenRead("meeting.mp3");
+
+var response = await transcription.GetTextAsync(audio,
+    new GrokSpeechToTextOptions
+    {
+        TextLanguage = "en",
+        Format = true,
+    });
+
+Console.WriteLine(response.Text);
+```
+
+Set `Format = true` with `TextLanguage` to enable xAI's inverse text normalization, such as converting 
+spoken numbers and currencies into written form.
+
+### Streaming
+
+Call `GetStreamingTextAsync` to stream raw audio and receive transcript updates as speech is processed. 
+The xAI streaming endpoint expects raw encoded audio such as PCM, µ-law, or A-law rather than MP3/WAV 
+container bytes:
+
+```csharp
+await using var audio = File.OpenRead("audio.pcm");
+
+await foreach (var update in transcription.GetStreamingTextAsync(audio,
+    new GrokSpeechToTextOptions
+    {
+        AudioFormat = "pcm",
+        SpeechSampleRate = 16000,
+        TextLanguage = "en",
+        InterimResults = true,
+    }))
+{
+    if (update.Kind is SpeechToTextResponseUpdateKind.TextUpdating or
+        SpeechToTextResponseUpdateKind.TextUpdated)
+    {
+        Console.WriteLine(update.Text);
+    }
+}
+```
+
+### Grok-Specific Options
+
+Use `GrokSpeechToTextOptions` to control xAI transcription behavior beyond the base 
+`SpeechToTextOptions`:
+
+```csharp
+var options = new GrokSpeechToTextOptions
+{
+    TextLanguage = "en",
+    SpeechSampleRate = 16000,
+    Format = true,          // normalize spoken numbers, currencies, and units
+    AudioFormat = "pcm",    // pcm | mulaw | alaw for raw audio
+    Diarize = true,         // include speaker IDs on words when available
+    Multichannel = true,    // transcribe each channel independently
+    Channels = 2,
+    InterimResults = true,  // streaming only
+    Endpointing = 10,       // streaming silence duration in milliseconds
+};
+
+var response = await transcription.GetTextAsync(File.OpenRead("call.pcm"), options);
+```
+
 <!-- #xai -->
 
 # xAI.Protocol

src/xAI.Tests/SanityChecks.cs

@@ -1,13 +1,8 @@
 using System.Text.Json;
-using Devlooped.Extensions.AI;
-using DotNetEnv;
-using Grpc.Core;
-using Grpc.Net.Client.Configuration;
 using Microsoft.Extensions.AI;
 using Microsoft.Extensions.DependencyInjection;
 using xAI.Protocol;
-using Xunit.Abstractions;
-using Xunit.Sdk;
+using static ConfigurationExtensions;
 using ChatConversation = Devlooped.Extensions.AI.Chat;
 
 namespace xAI.Tests;
@@ -18,7 +13,7 @@ public class SanityChecks(ITestOutputHelper output)
     public async Task NoEmbeddingModels()
     {
         var services = new ServiceCollection()
-            .AddxAIProtocol(Environment.GetEnvironmentVariable("CI_XAI_API_KEY")!)
+            .AddxAIProtocol(Configuration["CI_XAI_API_KEY"]!)
             .BuildServiceProvider();
 
         var client = services.GetRequiredService<Models.ModelsClient>();
@@ -33,7 +28,7 @@ public async Task NoEmbeddingModels()
     public async Task ListModelsAsync()
     {
         var services = new ServiceCollection()
-            .AddxAIProtocol(Environment.GetEnvironmentVariable("CI_XAI_API_KEY")!)
+            .AddxAIProtocol(Configuration["CI_XAI_API_KEY"]!)
             .BuildServiceProvider();
 
         var client = services.GetRequiredService<Models.ModelsClient>();
@@ -50,7 +45,7 @@ public async Task ListModelsAsync()
     public async Task ExecuteLocalFunctionWithWebSearch()
     {
         var services = new ServiceCollection()
-            .AddxAIProtocol(Environment.GetEnvironmentVariable("CI_XAI_API_KEY")!)
+            .AddxAIProtocol(Configuration["CI_XAI_API_KEY"]!)
             .BuildServiceProvider();
 
         var client = services.GetRequiredService<xAI.Protocol.Chat.ChatClient>();
@@ -161,7 +156,7 @@ public async Task ExecuteLocalFunctionWithWebSearch()
     public async Task ClientSideFunction(bool streaming)
     {
         var getDateCalls = 0;
-        var grok = new GrokClient(Env.GetString("CI_XAI_API_KEY")!)
+        var grok = new GrokClient(Configuration["CI_XAI_API_KEY"]!)
             .AsIChatClient("grok-4-1-fast")
             .AsBuilder()
             .UseFunctionInvocation()
@@ -203,7 +198,7 @@ What is today's date? Use the get_date tool.
     [InlineData(true)]
     public async Task AgenticWebSearch(bool streaming)
     {
-        var grok = new GrokClient(Env.GetString("CI_XAI_API_KEY")!)
+        var grok = new GrokClient(Configuration["CI_XAI_API_KEY"]!)
             .AsIChatClient("grok-4-1-fast");
 
         var options = new GrokChatOptions
@@ -249,7 +244,7 @@ What is the current price of Tesla (TSLA) stock? Use web search (Yahoo Finance o
     [InlineData(true)]
     public async Task AgenticXSearch(bool streaming)
     {
-        var grok = new GrokClient(Env.GetString("CI_XAI_API_KEY")!)
+        var grok = new GrokClient(Configuration["CI_XAI_API_KEY"]!)
             .AsIChatClient("grok-4-1-fast");
 
         var options = new GrokChatOptions
@@ -288,7 +283,7 @@ What is the top news from Tesla on X? Use the X search tool.
     [InlineData(true)]
     public async Task AgenticMcpServer(bool streaming)
     {
-        var grok = new GrokClient(Env.GetString("CI_XAI_API_KEY")!)
+        var grok = new GrokClient(Configuration["CI_XAI_API_KEY"]!)
             .AsIChatClient("grok-4-1-fast");
 
         var options = new GrokChatOptions
@@ -299,7 +294,7 @@ public async Task AgenticMcpServer(bool streaming)
             [
                 new HostedMcpServerTool("GitHub", "https://api.githubcopilot.com/mcp/")
                 {
-                    Headers = new Dictionary < string, string > {["Authorization"] = Env.GetString("GITHUB_TOKEN") ! },
+                    Headers = new Dictionary < string, string > {["Authorization"] = Configuration["GITHUB_TOKEN"] ! },
                     AllowedTools = ["list_releases", "get_release_by_tag"],
                 }
             ]
@@ -340,7 +335,7 @@ What is the latest release version of the {{ThisAssembly.Git.Url}} repository? U
     [InlineData(true)]
     public async Task AgenticFileSearch(bool streaming)
     {
-        var grok = new GrokClient(Env.GetString("CI_XAI_API_KEY")!)
+        var grok = new GrokClient(Configuration["CI_XAI_API_KEY"]!)
             .AsIChatClient("grok-4-1-fast");
 
         var options = new GrokChatOptions
@@ -406,7 +401,7 @@ Use the collection search tool.
     [InlineData(true)]
     public async Task AgenticCodeInterpreter(bool streaming)
     {
-        var client = new GrokClient(Env.GetString("CI_XAI_API_KEY")!);
+        var client = new GrokClient(Configuration["CI_XAI_API_KEY"]!);
 
         var grok = client.AsIChatClient("grok-4-1-fast");
 
@@ -451,6 +446,72 @@ parseable by a decimal parser.
         output.WriteLine($"Code interpreter calls: {codeInterpreterCalls.Count}");
     }
 
+    [SecretsTheory("CI_XAI_API_KEY")]
+    [InlineData("rex")]
+    public async Task TextToSpeech_SpeechToText(string voiceId)
+    {
+        using var client = new GrokClient(Configuration["CI_XAI_API_KEY"]!);
+        using var tts = client.AsITextToSpeechClient();
+
+        var expected = "El que cree en mí, en realidad no cree en mí, sino en aquel que me envió.";
+        var tempFile = System.IO.Path.Combine(System.IO.Path.GetTempPath(), $"xai-tts-{Guid.NewGuid():N}.pcm");
+
+        try
+        {
+            await using (var fileStream = System.IO.File.Create(tempFile))
+            {
+                await foreach (var update in tts.GetStreamingAudioAsync(
+                    expected,
+                    new TextToSpeechOptions
+                    {
+                        VoiceId = voiceId,
+                        Language = "es-ES",
+                        // uses mp3 by default
+                    }))
+                {
+                    if (update.Kind == TextToSpeechResponseUpdateKind.AudioUpdating)
+                    {
+                        foreach (var content in update.Contents)
+                        {
+                            if (content is DataContent data)
+                            {
+                                await fileStream.WriteAsync(data.Data);
+                            }
+                        }
+                    }
+                }
+            }
+
+            Assert.True(System.IO.File.Exists(tempFile));
+            Assert.True(new System.IO.FileInfo(tempFile).Length > 0);
+
+            using var stt = client.AsISpeechToTextClient();
+            await using var audioStream = System.IO.File.OpenRead(tempFile);
+
+            // auto-detect format from content
+            var transcription = await stt.GetTextAsync(audioStream);
+
+            Assert.Equal(
+                NormalizeTranscription(expected),
+                NormalizeTranscription(transcription.Text),
+                ignoreCase: true);
+        }
+        finally
+        {
+            if (System.IO.File.Exists(tempFile))
+                System.IO.File.Delete(tempFile);
+        }
+    }
+
+    static string NormalizeTranscription(string? text)
+    {
+        var withoutPunctuation = new string((text ?? string.Empty)
+            .Select(character => char.IsPunctuation(character) ? ' ' : character)
+            .ToArray());
+
+        return string.Join(" ", withoutPunctuation.Split((char[]?)null, StringSplitOptions.RemoveEmptyEntries));
+    }
+
     static async Task<ChatResponse> GetResponseAsync(IChatClient client, ChatConversation chat, GrokChatOptions options, bool streaming)
     {
         if (!streaming)