Added embedding API (#654)

Co-authored-by: Thorsten Sommer <SommerEngineering@users.noreply.github.com>

app/MindWork AI Studio/Provider/AlibabaCloud/ProviderAlibabaCloud.cs

@@ -86,6 +86,13 @@ public sealed class ProviderAlibabaCloud() : BaseProvider(LLMProviders.ALIBABA_C
     {
         return Task.FromResult(string.Empty);
     }
+    
+    /// <inhertidoc />
+    public override async Task<IReadOnlyList<IReadOnlyList<float>>> EmbedTextAsync(Model embeddingModel, SettingsManager settingsManager, CancellationToken token = default, params List<string> texts)
+    {
+        var requestedSecret = await RUST_SERVICE.GetAPIKey(this, SecretStoreType.EMBEDDING_PROVIDER);
+        return await this.PerformStandardTextEmbeddingRequest(requestedSecret, embeddingModel, token: token, texts: texts);
+    }
 
     /// <inheritdoc />
     public override Task<IEnumerable<Model>> GetTextModels(string? apiKeyProvisional = null, CancellationToken token = default)

app/MindWork AI Studio/Provider/Anthropic/ProviderAnthropic.cs

@@ -113,6 +113,12 @@ public sealed class ProviderAnthropic() : BaseProvider(LLMProviders.ANTHROPIC, "
     {
         return Task.FromResult(string.Empty);
     }
+    
+    /// <inhertidoc />
+    public override Task<IReadOnlyList<IReadOnlyList<float>>> EmbedTextAsync(Model embeddingModel, SettingsManager settingsManager, CancellationToken token = default, params List<string> texts)
+    {
+        return Task.FromResult<IReadOnlyList<IReadOnlyList<float>>>([]);
+    }
 
     /// <inheritdoc />
     public override Task<IEnumerable<Model>> GetTextModels(string? apiKeyProvisional = null, CancellationToken token = default)

app/MindWork AI Studio/Provider/BaseProvider.cs

@@ -1,6 +1,7 @@
 using System.Net;
 using System.Net.Http.Headers;
 using System.Runtime.CompilerServices;
+using System.Text;
 using System.Text.Json;
 using System.Text.Json.Serialization;
 
@@ -98,6 +99,9 @@ public abstract class BaseProvider : IProvider, ISecretId
     /// <inheritdoc />
     public abstract Task<string> TranscribeAudioAsync(Model transcriptionModel, string audioFilePath, SettingsManager settingsManager, CancellationToken token = default);
     
+    /// <inheritdoc />
+    public abstract Task<IReadOnlyList<IReadOnlyList<float>>> EmbedTextAsync(Model embeddingModel, SettingsManager settingsManager, CancellationToken token = default, params List<string> texts);
+    
     /// <inheritdoc />
     public abstract Task<IEnumerable<Model>> GetTextModels(string? apiKeyProvisional = null, CancellationToken token = default);
     
@@ -645,6 +649,81 @@ public abstract class BaseProvider : IProvider, ISecretId
         }
     }
     
+    protected async Task<IReadOnlyList<IReadOnlyList<float>>> PerformStandardTextEmbeddingRequest(RequestedSecret requestedSecret, Model embeddingModel, Host host = Host.NONE, CancellationToken token = default, params List<string> texts)
+    {
+        try
+        {
+            //
+            // Add the model name to the form data. Ensure that a model name is always provided.
+            // Otherwise, the StringContent constructor will throw an exception.
+            //
+            var modelName = embeddingModel.Id;
+            if (string.IsNullOrWhiteSpace(modelName))
+                modelName = "placeholder";
+            
+            // Prepare the HTTP embedding request:
+            var payload = new
+            {
+                model = modelName,
+                input = texts,
+                encoding_format = "float"
+            };
+            
+            var embeddingRequest = JsonSerializer.Serialize(payload, JSON_SERIALIZER_OPTIONS);
+            using var request = new HttpRequestMessage(HttpMethod.Post, host.EmbeddingURL());
+
+            // Handle the authorization header based on the provider:
+            switch (this.Provider)
+            {
+                case LLMProviders.SELF_HOSTED:
+                    if(requestedSecret.Success)
+                        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", await requestedSecret.Secret.Decrypt(ENCRYPTION));
+                    
+                    break;
+                
+                default:
+                    if(!requestedSecret.Success)
+                    {
+                        this.logger.LogError("No valid API key available for embedding request.");
+                        return [];
+                    }
+                    
+                    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", await requestedSecret.Secret.Decrypt(ENCRYPTION));
+                    break;
+            }
+            
+            // Set the content:
+            request.Content = new StringContent(embeddingRequest, Encoding.UTF8, "application/json");
+            using var response = await this.httpClient.SendAsync(request, token);
+            var responseBody = response.Content.ReadAsStringAsync(token).Result;
+        
+            if (!response.IsSuccessStatusCode)
+            {
+                this.logger.LogError("Embedding request failed with status code {ResponseStatusCode} and body: '{ResponseBody}'.", response.StatusCode, responseBody);
+                return [];
+            }
+
+            var embeddingResponse = JsonSerializer.Deserialize<EmbeddingResponse>(responseBody, JSON_SERIALIZER_OPTIONS);
+            if (embeddingResponse is { Data: not null })
+            {
+                return embeddingResponse.Data
+                    .Select(d => d.Embedding?.ToArray() ?? [])
+                    .Cast<IReadOnlyList<float>>()
+                    .ToArray();
+            }
+            else
+            {
+                this.logger.LogError("Was not able to deserialize the embedding response.");
+                return [];
+            }
+        }
+        catch (Exception e)
+        {
+            this.logger.LogError("Failed to perform embedding request: '{Message}'.", e.Message);
+            return [];
+        }
+    }
+    
     /// <summary>
     /// Parse and convert API parameters from a provided JSON string into a dictionary,
     /// optionally merging additional parameters and removing specific keys.

app/MindWork AI Studio/Provider/DeepSeek/ProviderDeepSeek.cs

@@ -86,6 +86,12 @@ public sealed class ProviderDeepSeek() : BaseProvider(LLMProviders.DEEP_SEEK, "h
     {
         return Task.FromResult(string.Empty);
     }
+    
+    /// <inhertidoc />
+    public override Task<IReadOnlyList<IReadOnlyList<float>>> EmbedTextAsync(Model embeddingModel, SettingsManager settingsManager, CancellationToken token = default, params List<string> texts)
+    {
+        return Task.FromResult<IReadOnlyList<IReadOnlyList<float>>>([]);
+    }
 
     /// <inheritdoc />
     public override Task<IEnumerable<Model>> GetTextModels(string? apiKeyProvisional = null, CancellationToken token = default)

app/MindWork AI Studio/Provider/EmbeddingData.cs

@@ -0,0 +1,12 @@
+// ReSharper disable CollectionNeverUpdated.Global
+namespace AIStudio.Provider;
+
+// ReSharper disable once ClassNeverInstantiated.Global
+public sealed record EmbeddingData
+{
+    public string? Object { get; set; }
+    
+    public List<float>? Embedding { get; set; }
+    
+    public int? Index { get; set; }
+}

app/MindWork AI Studio/Provider/EmbeddingResponse.cs

@@ -0,0 +1,14 @@
+namespace AIStudio.Provider;
+
+public sealed record EmbeddingResponse
+{
+    public string? Id { get; init; }
+    
+    public string? Object { get; init; }
+    
+    public List<EmbeddingData>? Data { get; init; }
+    
+    public string? Model { get; init; }
+    
+    public EmbeddingUsage? Usage { get; init; }
+}

app/MindWork AI Studio/Provider/EmbeddingUsage.cs

@@ -0,0 +1,11 @@
+// ReSharper disable ClassNeverInstantiated.Global
+namespace AIStudio.Provider;
+
+public sealed record EmbeddingUsage
+{
+    public int? PromptTokens { get; set; }
+    
+    public int? TotalTokens { get; set; }
+    
+    public int? CompletionTokens { get; set; }
+}

app/MindWork AI Studio/Provider/Fireworks/ProviderFireworks.cs

@@ -88,6 +88,12 @@ public class ProviderFireworks() : BaseProvider(LLMProviders.FIREWORKS, "https:/
         var requestedSecret = await RUST_SERVICE.GetAPIKey(this, SecretStoreType.TRANSCRIPTION_PROVIDER);
         return await this.PerformStandardTranscriptionRequest(requestedSecret, transcriptionModel, audioFilePath, token: token);
     }
+    
+    /// <inhertidoc />
+    public override Task<IReadOnlyList<IReadOnlyList<float>>> EmbedTextAsync(Model embeddingModel, SettingsManager settingsManager, CancellationToken token = default, params List<string> texts)
+    {
+        return Task.FromResult<IReadOnlyList<IReadOnlyList<float>>>([]);
+    }
 
     /// <inheritdoc />
     public override Task<IEnumerable<Model>> GetTextModels(string? apiKeyProvisional = null, CancellationToken token = default)

app/MindWork AI Studio/Provider/GWDG/ProviderGWDG.cs

@@ -87,6 +87,12 @@ public sealed class ProviderGWDG() : BaseProvider(LLMProviders.GWDG, "https://ch
         var requestedSecret = await RUST_SERVICE.GetAPIKey(this, SecretStoreType.TRANSCRIPTION_PROVIDER);
         return await this.PerformStandardTranscriptionRequest(requestedSecret, transcriptionModel, audioFilePath, token: token);
     }
+    
+    /// <inhertidoc />
+    public override Task<IReadOnlyList<IReadOnlyList<float>>> EmbedTextAsync(Model embeddingModel, SettingsManager settingsManager, CancellationToken token = default, params List<string> texts)
+    {
+        return Task.FromResult<IReadOnlyList<IReadOnlyList<float>>>([]);
+    }
 
     /// <inheritdoc />
     public override async Task<IEnumerable<Model>> GetTextModels(string? apiKeyProvisional = null, CancellationToken token = default)

app/MindWork AI Studio/Provider/Google/GoogleEmbedding.cs

@@ -0,0 +1,6 @@
+namespace AIStudio.Provider.Google;
+
+public sealed record GoogleEmbedding
+{
+    public List<float>? Values { get; init; }
+}

app/MindWork AI Studio/Provider/Google/GoogleEmbeddingResponse.cs

@@ -0,0 +1,30 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace AIStudio.Provider.Google;
+
+public sealed record GoogleEmbeddingResponse
+{
+    [JsonConverter(typeof(GoogleEmbeddingListConverter))]
+    public List<GoogleEmbedding>? Embedding { get; init; }
+
+    private sealed class GoogleEmbeddingListConverter : JsonConverter<List<GoogleEmbedding>>
+    {
+        public override List<GoogleEmbedding> Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+        {
+            if (reader.TokenType == JsonTokenType.StartObject)
+            {
+                var single = JsonSerializer.Deserialize<GoogleEmbedding>(ref reader, options);
+                return single is null ? new() : new() { single };
+            }
+
+            if (reader.TokenType == JsonTokenType.StartArray)
+                return JsonSerializer.Deserialize<List<GoogleEmbedding>>(ref reader, options) ?? new();
+
+            throw new JsonException("Expected object or array for embedding.");
+        }
+
+        public override void Write(Utf8JsonWriter writer, List<GoogleEmbedding> value, JsonSerializerOptions options) =>
+            JsonSerializer.Serialize(writer, value, options);
+    }
+}

app/MindWork AI Studio/Provider/Google/ProviderGoogle.cs

@@ -87,6 +87,78 @@ public class ProviderGoogle() : BaseProvider(LLMProviders.GOOGLE, "https://gener
     {
         return Task.FromResult(string.Empty);
     }
+    
+    /// <inhertidoc />
+    public override async Task<IReadOnlyList<IReadOnlyList<float>>> EmbedTextAsync(Model embeddingModel, SettingsManager settingsManager, CancellationToken token = default, params List<string> texts)
+    {
+        var requestedSecret = await RUST_SERVICE.GetAPIKey(this, SecretStoreType.EMBEDDING_PROVIDER);
+        try
+        {
+            var modelName = embeddingModel.Id;
+            if (string.IsNullOrWhiteSpace(modelName))
+            {
+                LOGGER.LogError("No model name provided for embedding request.");
+                return [];
+            }
+
+            if (modelName.StartsWith("models/", StringComparison.OrdinalIgnoreCase))
+                modelName = modelName.Substring("models/".Length);
+
+            if (!requestedSecret.Success)
+            {
+                LOGGER.LogError("No valid API key available for embedding request.");
+                return [];
+            }
+            
+            // Prepare the Google Gemini embedding request:
+            var payload = new
+            {
+                content = new
+                {
+                    parts = texts.Select(text => new { text }).ToArray()
+                },
+                
+                taskType = "SEMANTIC_SIMILARITY"
+            };
+            
+            var embeddingRequest = JsonSerializer.Serialize(payload, JSON_SERIALIZER_OPTIONS);
+            var embedUrl = $"https://generativelanguage.googleapis.com/v1beta/models/{modelName}:embedContent";
+            using var request = new HttpRequestMessage(HttpMethod.Post, embedUrl);
+            request.Headers.Add("x-goog-api-key", await requestedSecret.Secret.Decrypt(ENCRYPTION));
+            
+            // Set the content:
+            request.Content = new StringContent(embeddingRequest, Encoding.UTF8, "application/json");
+            
+            using var response = await this.httpClient.SendAsync(request, token);
+            var responseBody = await response.Content.ReadAsStringAsync(token);
+        
+            if (!response.IsSuccessStatusCode)
+            {
+                LOGGER.LogError("Embedding request failed with status code {ResponseStatusCode} and body: '{ResponseBody}'.", response.StatusCode, responseBody);
+                return [];
+            }
+
+            var embeddingResponse = JsonSerializer.Deserialize<GoogleEmbeddingResponse>(responseBody, JSON_SERIALIZER_OPTIONS);
+            if (embeddingResponse is { Embedding: not null })
+            {
+                return embeddingResponse.Embedding
+                    .Select(d => d.Values?.ToArray() ?? [])
+                    .Cast<IReadOnlyList<float>>()
+                    .ToArray();
+            }
+            else
+            {
+                LOGGER.LogError("Was not able to deserialize the embedding response.");
+                return [];
+            }
+            
+        }
+        catch (Exception e)
+        {
+            LOGGER.LogError("Failed to perform embedding request: '{Message}'.", e.Message);
+            return [];
+        }
+    }
 
     /// <inheritdoc />
     public override async Task<IEnumerable<Model>> GetTextModels(string? apiKeyProvisional = null, CancellationToken token = default)

app/MindWork AI Studio/Provider/Groq/ProviderGroq.cs

@@ -87,6 +87,12 @@ public class ProviderGroq() : BaseProvider(LLMProviders.GROQ, "https://api.groq.
     {
         return Task.FromResult(string.Empty);
     }
+    
+    /// <inhertidoc />
+    public override Task<IReadOnlyList<IReadOnlyList<float>>> EmbedTextAsync(Model embeddingModel, SettingsManager settingsManager, CancellationToken token = default, params List<string> texts)
+    {
+        return Task.FromResult<IReadOnlyList<IReadOnlyList<float>>>([]);
+    }
 
     /// <inheritdoc />
     public override Task<IEnumerable<Model>> GetTextModels(string? apiKeyProvisional = null, CancellationToken token = default)

app/MindWork AI Studio/Provider/Helmholtz/ProviderHelmholtz.cs

@@ -86,6 +86,13 @@ public sealed class ProviderHelmholtz() : BaseProvider(LLMProviders.HELMHOLTZ, "
     {
         return Task.FromResult(string.Empty);
     }
+    
+    /// <inhertidoc />
+    public override async Task<IReadOnlyList<IReadOnlyList<float>>> EmbedTextAsync(Model embeddingModel, SettingsManager settingsManager, CancellationToken token = default, params List<string> texts)
+    {
+        var requestedSecret = await RUST_SERVICE.GetAPIKey(this, SecretStoreType.EMBEDDING_PROVIDER);
+        return await this.PerformStandardTextEmbeddingRequest(requestedSecret, embeddingModel, token: token, texts: texts);
+    }
 
     /// <inheritdoc />
     public override async Task<IEnumerable<Model>> GetTextModels(string? apiKeyProvisional = null, CancellationToken token = default)

app/MindWork AI Studio/Provider/HuggingFace/ProviderHuggingFace.cs

@@ -91,6 +91,12 @@ public sealed class ProviderHuggingFace : BaseProvider
     {
         return Task.FromResult(string.Empty);
     }
+    
+    /// <inhertidoc />
+    public override Task<IReadOnlyList<IReadOnlyList<float>>> EmbedTextAsync(Model embeddingModel, SettingsManager settingsManager, CancellationToken token = default, params List<string> texts)
+    {
+        return Task.FromResult<IReadOnlyList<IReadOnlyList<float>>>([]);
+    }
 
     /// <inheritdoc />
     public override Task<IEnumerable<Model>> GetTextModels(string? apiKeyProvisional = null, CancellationToken token = default)

app/MindWork AI Studio/Provider/IProvider.cs

@@ -59,6 +59,16 @@ public interface IProvider
     /// <param name="token">The cancellation token.</param>
     /// <returns>>The transcription result.</returns>
     public Task<string> TranscribeAudioAsync(Model transcriptionModel, string audioFilePath, SettingsManager settingsManager, CancellationToken token = default);
+        
+    /// <summary>
+    /// Embed a text file.
+    /// </summary>
+    /// <param name="embeddingModel">The model to use for embedding.</param>
+    /// <param name="settingsManager">The settings manager instance to use.</param>
+    /// <param name="token">The cancellation token.</param>
+    /// /// <param name="texts">A single string or a list of strings to embed.</param>
+    /// <returns>>The embedded text as a single vector or as a list of vectors.</returns>
+    public Task<IReadOnlyList<IReadOnlyList<float>>> EmbedTextAsync(Model embeddingModel, SettingsManager settingsManager, CancellationToken token = default, params List<string> texts);
     
     /// <summary>
     /// Load all possible text models that can be used with this provider.

app/MindWork AI Studio/Provider/Mistral/ProviderMistral.cs

@@ -89,6 +89,13 @@ public sealed class ProviderMistral() : BaseProvider(LLMProviders.MISTRAL, "http
         return await this.PerformStandardTranscriptionRequest(requestedSecret, transcriptionModel, audioFilePath, token: token);
     }
 
+    /// <inhertidoc />
+    public override async Task<IReadOnlyList<IReadOnlyList<float>>> EmbedTextAsync(Provider.Model embeddingModel, SettingsManager settingsManager, CancellationToken token = default, params List<string> texts)
+    {
+        var requestedSecret = await RUST_SERVICE.GetAPIKey(this, SecretStoreType.EMBEDDING_PROVIDER);
+        return await this.PerformStandardTextEmbeddingRequest(requestedSecret, embeddingModel, token: token, texts: texts);
+    }
+
     /// <inheritdoc />
     public override async Task<IEnumerable<Provider.Model>> GetTextModels(string? apiKeyProvisional = null, CancellationToken token = default)
     {

app/MindWork AI Studio/Provider/NoProvider.cs

@@ -40,6 +40,8 @@ public class NoProvider : IProvider
 
     public Task<string> TranscribeAudioAsync(Model transcriptionModel, string audioFilePath, SettingsManager settingsManager, CancellationToken token = default) => Task.FromResult(string.Empty);
     
+    public Task<IReadOnlyList<IReadOnlyList<float>>> EmbedTextAsync(Model embeddingModel, SettingsManager settingsManager, CancellationToken token = default, params List<string> texts) => Task.FromResult<IReadOnlyList<IReadOnlyList<float>>>([]);
+
     public IReadOnlyCollection<Capability> GetModelCapabilities(Model model) => [ Capability.NONE ];
 
     #endregion

app/MindWork AI Studio/Provider/OpenAI/ProviderOpenAI.cs

@@ -224,6 +224,13 @@ public sealed class ProviderOpenAI() : BaseProvider(LLMProviders.OPEN_AI, "https
         var requestedSecret = await RUST_SERVICE.GetAPIKey(this, SecretStoreType.TRANSCRIPTION_PROVIDER);
         return await this.PerformStandardTranscriptionRequest(requestedSecret, transcriptionModel, audioFilePath, token: token);
     }
+    
+    /// <inhertidoc />
+    public override async Task<IReadOnlyList<IReadOnlyList<float>>> EmbedTextAsync(Model embeddingModel, SettingsManager settingsManager, CancellationToken token = default, params List<string> texts)
+    {
+        var requestedSecret = await RUST_SERVICE.GetAPIKey(this, SecretStoreType.EMBEDDING_PROVIDER);
+        return await this.PerformStandardTextEmbeddingRequest(requestedSecret, embeddingModel, token: token, texts: texts);
+    }
 
     /// <inheritdoc />
     public override async Task<IEnumerable<Model>> GetTextModels(string? apiKeyProvisional = null, CancellationToken token = default)

app/MindWork AI Studio/Provider/OpenRouter/ProviderOpenRouter.cs

@@ -94,6 +94,13 @@ public sealed class ProviderOpenRouter() : BaseProvider(LLMProviders.OPEN_ROUTER
     {
         return Task.FromResult(string.Empty);
     }
+    
+    /// <inhertidoc />
+    public override async Task<IReadOnlyList<IReadOnlyList<float>>> EmbedTextAsync(Model embeddingModel, SettingsManager settingsManager, CancellationToken token = default, params List<string> texts)
+    {
+        var requestedSecret = await RUST_SERVICE.GetAPIKey(this, SecretStoreType.EMBEDDING_PROVIDER);
+        return await this.PerformStandardTextEmbeddingRequest(requestedSecret, embeddingModel, token: token, texts: texts);
+    }
 
     /// <inheritdoc />
     public override Task<IEnumerable<Model>> GetTextModels(string? apiKeyProvisional = null, CancellationToken token = default)

app/MindWork AI Studio/Provider/Perplexity/ProviderPerplexity.cs

@@ -94,6 +94,12 @@ public sealed class ProviderPerplexity() : BaseProvider(LLMProviders.PERPLEXITY,
     {
         return Task.FromResult(string.Empty);
     }
+    
+    /// <inhertidoc />
+    public override Task<IReadOnlyList<IReadOnlyList<float>>> EmbedTextAsync(Model embeddingModel, SettingsManager settingsManager, CancellationToken token = default, params List<string> texts)
+    {
+        return Task.FromResult<IReadOnlyList<IReadOnlyList<float>>>([]);
+    }
 
     /// <inheritdoc />
     public override Task<IEnumerable<Model>> GetTextModels(string? apiKeyProvisional = null, CancellationToken token = default)

app/MindWork AI Studio/Provider/SelfHosted/HostExtensions.cs

@@ -30,6 +30,11 @@ public static class HostExtensions
         _ => "audio/transcriptions",
     };
     
+    public static string EmbeddingURL(this Host host) => host switch
+    {
+        _ => "embeddings",
+    };
+    
     public static bool IsChatSupported(this Host host)
     {
         switch (host)

app/MindWork AI Studio/Provider/SelfHosted/ProviderSelfHosted.cs

@@ -95,6 +95,13 @@ public sealed class ProviderSelfHosted(Host host, string hostname) : BaseProvide
         return await this.PerformStandardTranscriptionRequest(requestedSecret, transcriptionModel, audioFilePath, host, token);
     }
     
+    /// <inhertidoc />
+    public override async Task<IReadOnlyList<IReadOnlyList<float>>> EmbedTextAsync(Provider.Model embeddingModel, SettingsManager settingsManager, CancellationToken token = default, params List<string> texts)
+    {
+        var requestedSecret = await RUST_SERVICE.GetAPIKey(this, SecretStoreType.EMBEDDING_PROVIDER);
+        return await this.PerformStandardTextEmbeddingRequest(requestedSecret, embeddingModel, token: token, texts: texts);
+    }
+    
     public override async Task<IEnumerable<Provider.Model>> GetTextModels(string? apiKeyProvisional = null, CancellationToken token = default)
     {
         try

app/MindWork AI Studio/Provider/X/ProviderX.cs

@@ -88,6 +88,12 @@ public sealed class ProviderX() : BaseProvider(LLMProviders.X, "https://api.x.ai
         return Task.FromResult(string.Empty);
     }
     
+    /// <inhertidoc />
+    public override Task<IReadOnlyList<IReadOnlyList<float>>> EmbedTextAsync(Model embeddingModel, SettingsManager settingsManager, CancellationToken token = default, params List<string> texts)
+    {
+        return Task.FromResult<IReadOnlyList<IReadOnlyList<float>>>([]);
+    }
+    
     /// <inheritdoc />
     public override async Task<IEnumerable<Model>> GetTextModels(string? apiKeyProvisional = null, CancellationToken token = default)
     {