Add ChatOptions.RawRepresentationFactory (#6319)

* Look for OpenAI.ChatCompletionOptions in top-level additional properties and stop looking for individually specific additional properties

* Add RawRepresentation to ChatOptions and use it in OpenAI and AzureAIInference

* Remove now unused locals

* Add [JsonIgnore] and update roundtrip tests

* Overwirte properties only if the underlying model don't specify it already

* Clone RawRepresentation

* Reflection workaround for ToolChoice not being cloned

* Style changes

* AI.Inference: Bring back propagation of additional properties

* Don't use 0.1f, it doesn't roundtrip properly in .NET Framework

* Add RawRepresentationFactory instead of object? property

* Augment remarks to discourage returning shared instances

* Documentation feedback

* AI.Inference: keep passing TopK as AdditionalProperty if not already there

Author: jozkee

src/Libraries/Microsoft.Extensions.AI.AzureAIInference/AzureAIInferenceChatClient.cs

@@ -281,66 +281,74 @@ private static ChatRole ToChatRole(global::Azure.AI.Inference.ChatRole role) =>
         finishReason == CompletionsFinishReason.ToolCalls ? ChatFinishReason.ToolCalls :
         new(s);
 
+    private ChatCompletionsOptions CreateAzureAIOptions(IEnumerable<ChatMessage> chatContents, ChatOptions? options) =>
+        new(ToAzureAIInferenceChatMessages(chatContents))
+        {
+            Model = options?.ModelId ?? _metadata.DefaultModelId ??
+                throw new InvalidOperationException("No model id was provided when either constructing the client or in the chat options.")
+        };
+
     /// <summary>Converts an extensions options instance to an AzureAI options instance.</summary>
     private ChatCompletionsOptions ToAzureAIOptions(IEnumerable<ChatMessage> chatContents, ChatOptions? options)
     {
-        ChatCompletionsOptions result = new(ToAzureAIInferenceChatMessages(chatContents))
+        if (options is null)
         {
-            Model = options?.ModelId ?? _metadata.DefaultModelId ?? throw new InvalidOperationException("No model id was provided when either constructing the client or in the chat options.")
-        };
+            return CreateAzureAIOptions(chatContents, options);
+        }
+
+        if (options.RawRepresentationFactory?.Invoke(this) is ChatCompletionsOptions result)
+        {
+            result.Messages = ToAzureAIInferenceChatMessages(chatContents).ToList();
+            result.Model ??= options.ModelId ?? _metadata.DefaultModelId ??
+                throw new InvalidOperationException("No model id was provided when either constructing the client or in the chat options.");
+        }
+        else
+        {
+            result = CreateAzureAIOptions(chatContents, options);
+        }
 
-        if (options is not null)
+        result.FrequencyPenalty ??= options.FrequencyPenalty;
+        result.MaxTokens ??= options.MaxOutputTokens;
+        result.NucleusSamplingFactor ??= options.TopP;
+        result.PresencePenalty ??= options.PresencePenalty;
+        result.Temperature ??= options.Temperature;
+        result.Seed ??= options.Seed;
+
+        if (options.StopSequences is { Count: > 0 } stopSequences)
         {
-            result.FrequencyPenalty = options.FrequencyPenalty;
-            result.MaxTokens = options.MaxOutputTokens;
-            result.NucleusSamplingFactor = options.TopP;
-            result.PresencePenalty = options.PresencePenalty;
-            result.Temperature = options.Temperature;
-            result.Seed = options.Seed;
-
-            if (options.StopSequences is { Count: > 0 } stopSequences)
+            foreach (string stopSequence in stopSequences)
             {
-                foreach (string stopSequence in stopSequences)
-                {
-                    result.StopSequences.Add(stopSequence);
-                }
+                result.StopSequences.Add(stopSequence);
             }
+        }
+
+        // This property is strongly typed on ChatOptions but not on ChatCompletionsOptions.
+        if (options.TopK is int topK && !result.AdditionalProperties.ContainsKey("top_k"))
+        {
+            result.AdditionalProperties["top_k"] = new BinaryData(JsonSerializer.SerializeToUtf8Bytes(topK, AIJsonUtilities.DefaultOptions.GetTypeInfo(typeof(int))));
+        }
 
-            // These properties are strongly typed on ChatOptions but not on ChatCompletionsOptions.
-            if (options.TopK is int topK)
+        if (options.AdditionalProperties is { } props)
+        {
+            foreach (var prop in props)
             {
-                result.AdditionalProperties["top_k"] = new BinaryData(JsonSerializer.SerializeToUtf8Bytes(topK, AIJsonUtilities.DefaultOptions.GetTypeInfo(typeof(int))));
+                byte[] data = JsonSerializer.SerializeToUtf8Bytes(prop.Value, AIJsonUtilities.DefaultOptions.GetTypeInfo(typeof(object)));
+                result.AdditionalProperties[prop.Key] = new BinaryData(data);
             }
+        }
 
-            if (options.AdditionalProperties is { } props)
+        if (options.Tools is { Count: > 0 } tools)
+        {
+            foreach (AITool tool in tools)
             {
-                foreach (var prop in props)
+                if (tool is AIFunction af)
                 {
-                    switch (prop.Key)
-                    {
-                        // Propagate everything else to the ChatCompletionsOptions' AdditionalProperties.
-                        default:
-                            if (prop.Value is not null)
-                            {
-                                byte[] data = JsonSerializer.SerializeToUtf8Bytes(prop.Value, AIJsonUtilities.DefaultOptions.GetTypeInfo(typeof(object)));
-                                result.AdditionalProperties[prop.Key] = new BinaryData(data);
-                            }
-
-                            break;
-                    }
+                    result.Tools.Add(ToAzureAIChatTool(af));
                 }
             }
 
-            if (options.Tools is { Count: > 0 } tools)
+            if (result.ToolChoice is null && result.Tools.Count > 0)
             {
-                foreach (AITool tool in tools)
-                {
-                    if (tool is AIFunction af)
-                    {
-                        result.Tools.Add(ToAzureAIChatTool(af));
-                    }
-                }
-
                 switch (options.ToolMode)
                 {
                     case NoneChatToolMode:
@@ -359,7 +367,10 @@ private ChatCompletionsOptions ToAzureAIOptions(IEnumerable<ChatMessage> chatCon
                         break;
                 }
             }
+        }
 
+        if (result.ResponseFormat is null)
+        {
             if (options.ResponseFormat is ChatResponseFormatText)
             {
                 result.ResponseFormat = ChatCompletionsResponseFormat.CreateTextFormat();

src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIChatClient.cs

@@ -18,6 +18,7 @@
 #pragma warning disable EA0011 // Consider removing unnecessary conditional access operator (?)
 #pragma warning disable S1067 // Expressions should not be too complex
 #pragma warning disable S3011 // Reflection should not be used to increase accessibility of classes, methods, or fields
+#pragma warning disable SA1204 // Static elements should appear before instance elements
 
 namespace Microsoft.Extensions.AI;
 
@@ -259,7 +260,6 @@ private static async IAsyncEnumerable<ChatResponseUpdate> FromOpenAIStreamingCha
         string? responseId = null;
         DateTimeOffset? createdAt = null;
         string? modelId = null;
-        string? fingerprint = null;
 
         // Process each update as it arrives
         await foreach (StreamingChatCompletionUpdate update in updates.WithCancellation(cancellationToken).ConfigureAwait(false))
@@ -270,7 +270,6 @@ private static async IAsyncEnumerable<ChatResponseUpdate> FromOpenAIStreamingCha
             responseId ??= update.CompletionId;
             createdAt ??= update.CreatedAt;
             modelId ??= update.Model;
-            fingerprint ??= update.SystemFingerprint;
 
             // Create the response content object.
             ChatResponseUpdate responseUpdate = new()
@@ -284,22 +283,6 @@ private static async IAsyncEnumerable<ChatResponseUpdate> FromOpenAIStreamingCha
                 Role = streamedRole,
             };
 
-            // Populate it with any additional metadata from the OpenAI object.
-            if (update.ContentTokenLogProbabilities is { Count: > 0 } contentTokenLogProbs)
-            {
-                (responseUpdate.AdditionalProperties ??= [])[nameof(update.ContentTokenLogProbabilities)] = contentTokenLogProbs;
-            }
-
-            if (update.RefusalTokenLogProbabilities is { Count: > 0 } refusalTokenLogProbs)
-            {
-                (responseUpdate.AdditionalProperties ??= [])[nameof(update.RefusalTokenLogProbabilities)] = refusalTokenLogProbs;
-            }
-
-            if (fingerprint is not null)
-            {
-                (responseUpdate.AdditionalProperties ??= [])[nameof(update.SystemFingerprint)] = fingerprint;
-            }
-
             // Transfer over content update items.
             if (update.ContentUpdate is { Count: > 0 })
             {
@@ -382,12 +365,6 @@ private static async IAsyncEnumerable<ChatResponseUpdate> FromOpenAIStreamingCha
                 responseUpdate.Contents.Add(new ErrorContent(refusal.ToString()) { ErrorCode = "Refusal" });
             }
 
-            // Propagate additional relevant metadata.
-            if (fingerprint is not null)
-            {
-                (responseUpdate.AdditionalProperties ??= [])[nameof(ChatCompletion.SystemFingerprint)] = fingerprint;
-            }
-
             yield return responseUpdate;
         }
     }
@@ -426,20 +403,7 @@ private static ChatResponse FromOpenAIChatCompletion(ChatCompletion openAIComple
                 "mp3" or _ => "audio/mpeg",
             };
 
-            var dc = new DataContent(audio.AudioBytes.ToMemory(), mimeType)
-            {
-                AdditionalProperties = new() { [nameof(audio.ExpiresAt)] = audio.ExpiresAt },
-            };
-
-            if (audio.Id is string id)
-            {
-                dc.AdditionalProperties[nameof(audio.Id)] = id;
-            }
-
-            if (audio.Transcript is string transcript)
-            {
-                dc.AdditionalProperties[nameof(audio.Transcript)] = transcript;
-            }
+            var dc = new DataContent(audio.AudioBytes.ToMemory(), mimeType);
 
             returnMessage.Contents.Add(dc);
         }
@@ -480,140 +444,74 @@ private static ChatResponse FromOpenAIChatCompletion(ChatCompletion openAIComple
             response.Usage = FromOpenAIUsage(tokenUsage);
         }
 
-        if (openAICompletion.ContentTokenLogProbabilities is { Count: > 0 } contentTokenLogProbs)
-        {
-            (response.AdditionalProperties ??= [])[nameof(openAICompletion.ContentTokenLogProbabilities)] = contentTokenLogProbs;
-        }
-
-        if (openAICompletion.RefusalTokenLogProbabilities is { Count: > 0 } refusalTokenLogProbs)
-        {
-            (response.AdditionalProperties ??= [])[nameof(openAICompletion.RefusalTokenLogProbabilities)] = refusalTokenLogProbs;
-        }
-
-        if (openAICompletion.SystemFingerprint is string systemFingerprint)
-        {
-            (response.AdditionalProperties ??= [])[nameof(openAICompletion.SystemFingerprint)] = systemFingerprint;
-        }
-
         return response;
     }
 
     /// <summary>Converts an extensions options instance to an OpenAI options instance.</summary>
-    private static ChatCompletionOptions ToOpenAIOptions(ChatOptions? options)
+    private ChatCompletionOptions ToOpenAIOptions(ChatOptions? options)
     {
-        ChatCompletionOptions result = new();
+        if (options is null)
+        {
+            return new ChatCompletionOptions();
+        }
 
-        if (options is not null)
+        if (options.RawRepresentationFactory?.Invoke(this) is not ChatCompletionOptions result)
         {
-            result.FrequencyPenalty = options.FrequencyPenalty;
-            result.MaxOutputTokenCount = options.MaxOutputTokens;
-            result.TopP = options.TopP;
-            result.PresencePenalty = options.PresencePenalty;
-            result.Temperature = options.Temperature;
-            result.AllowParallelToolCalls = options.AllowMultipleToolCalls;
+            result = new ChatCompletionOptions();
+        }
+
+        result.FrequencyPenalty ??= options.FrequencyPenalty;
+        result.MaxOutputTokenCount ??= options.MaxOutputTokens;
+        result.TopP ??= options.TopP;
+        result.PresencePenalty ??= options.PresencePenalty;
+        result.Temperature ??= options.Temperature;
+        result.AllowParallelToolCalls ??= options.AllowMultipleToolCalls;
 #pragma warning disable OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates.
-            result.Seed = options.Seed;
+        result.Seed ??= options.Seed;
 #pragma warning restore OPENAI001
 
-            if (options.StopSequences is { Count: > 0 } stopSequences)
+        if (options.StopSequences is { Count: > 0 } stopSequences)
+        {
+            foreach (string stopSequence in stopSequences)
             {
-                foreach (string stopSequence in stopSequences)
-                {
-                    result.StopSequences.Add(stopSequence);
-                }
+                result.StopSequences.Add(stopSequence);
             }
+        }
 
-            if (options.AdditionalProperties is { Count: > 0 } additionalProperties)
+        if (options.Tools is { Count: > 0 } tools)
+        {
+            foreach (AITool tool in tools)
             {
-                if (additionalProperties.TryGetValue(nameof(result.AudioOptions), out ChatAudioOptions? audioOptions))
+                if (tool is AIFunction af)
                 {
-                    result.AudioOptions = audioOptions;
-                }
-
-                if (additionalProperties.TryGetValue(nameof(result.EndUserId), out string? endUserId))
-                {
-                    result.EndUserId = endUserId;
-                }
-
-                if (additionalProperties.TryGetValue(nameof(result.IncludeLogProbabilities), out bool includeLogProbabilities))
-                {
-                    result.IncludeLogProbabilities = includeLogProbabilities;
-                }
-
-                if (additionalProperties.TryGetValue(nameof(result.LogitBiases), out IDictionary<int, int>? logitBiases))
-                {
-                    foreach (KeyValuePair<int, int> kvp in logitBiases!)
-                    {
-                        result.LogitBiases[kvp.Key] = kvp.Value;
-                    }
-                }
-
-                if (additionalProperties.TryGetValue(nameof(result.Metadata), out IDictionary<string, string>? metadata))
-                {
-                    foreach (KeyValuePair<string, string> kvp in metadata)
-                    {
-                        result.Metadata[kvp.Key] = kvp.Value;
-                    }
-                }
-
-                if (additionalProperties.TryGetValue(nameof(result.OutputPrediction), out ChatOutputPrediction? outputPrediction))
-                {
-                    result.OutputPrediction = outputPrediction;
-                }
-
-                if (additionalProperties.TryGetValue(nameof(result.ReasoningEffortLevel), out ChatReasoningEffortLevel reasoningEffortLevel))
-                {
-                    result.ReasoningEffortLevel = reasoningEffortLevel;
-                }
-
-                if (additionalProperties.TryGetValue(nameof(result.ResponseModalities), out ChatResponseModalities responseModalities))
-                {
-                    result.ResponseModalities = responseModalities;
-                }
-
-                if (additionalProperties.TryGetValue(nameof(result.StoredOutputEnabled), out bool storeOutputEnabled))
-                {
-                    result.StoredOutputEnabled = storeOutputEnabled;
-                }
-
-                if (additionalProperties.TryGetValue(nameof(result.TopLogProbabilityCount), out int topLogProbabilityCountInt))
-                {
-                    result.TopLogProbabilityCount = topLogProbabilityCountInt;
+                    result.Tools.Add(ToOpenAIChatTool(af));
                 }
             }
 
-            if (options.Tools is { Count: > 0 } tools)
+            if (result.ToolChoice is null && result.Tools.Count > 0)
             {
-                foreach (AITool tool in tools)
-                {
-                    if (tool is AIFunction af)
-                    {
-                        result.Tools.Add(ToOpenAIChatTool(af));
-                    }
-                }
-
-                if (result.Tools.Count > 0)
+                switch (options.ToolMode)
                 {
-                    switch (options.ToolMode)
-                    {
-                        case NoneChatToolMode:
-                            result.ToolChoice = ChatToolChoice.CreateNoneChoice();
-                            break;
-
-                        case AutoChatToolMode:
-                        case null:
-                            result.ToolChoice = ChatToolChoice.CreateAutoChoice();
-                            break;
-
-                        case RequiredChatToolMode required:
-                            result.ToolChoice = required.RequiredFunctionName is null ?
-                                ChatToolChoice.CreateRequiredChoice() :
-                                ChatToolChoice.CreateFunctionChoice(required.RequiredFunctionName);
-                            break;
-                    }
+                    case NoneChatToolMode:
+                        result.ToolChoice = ChatToolChoice.CreateNoneChoice();
+                        break;
+
+                    case AutoChatToolMode:
+                    case null:
+                        result.ToolChoice = ChatToolChoice.CreateAutoChoice();
+                        break;
+
+                    case RequiredChatToolMode required:
+                        result.ToolChoice = required.RequiredFunctionName is null ?
+                            ChatToolChoice.CreateRequiredChoice() :
+                            ChatToolChoice.CreateFunctionChoice(required.RequiredFunctionName);
+                        break;
                 }
             }
+        }
 
+        if (result.ResponseFormat is null)
+        {
             if (options.ResponseFormat is ChatResponseFormatText)
             {
                 result.ResponseFormat = OpenAI.Chat.ChatResponseFormat.CreateTextFormat();