Add ChatOptions.RawRepresentation

src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs

@@ -118,6 +118,25 @@ public string? ChatThreadId
     [JsonIgnore]
     public IList<AITool>? Tools { get; set; }
 
+    /// <summary>
+    /// Gets or sets the raw representation of the chat options from an underlying implementation.
+    /// </summary>
+    /// <remarks>
+    /// The underlying <see cref="IChatClient" /> implementation may have its own representation of options.
+    /// When <see cref="IChatClient.GetResponseAsync" /> or <see cref="IChatClient.GetStreamingResponseAsync" />
+    /// is invoked with a <see cref="ChatOptions" />, that implementation may convert the provided options into
+    /// its own representation in order to use it while performing the operation. For situations where a consumer knows
+    /// which concrete <see cref="IChatClient" /> is being used and how it represents options, an instance of that
+    /// implementation-specific options type may be stored into this <see cref="RawRepresentation" /> property, for
+    /// the <see cref="IChatClient" /> implementation to use instead of creating a new instance. Such implementations
+    /// may mutate the supplied options instance further based on other settings supplied on this <see cref="ChatOptions" /> 
+    /// instance or from other inputs, like the enumerable of <see cref="ChatMessage"/>s. This is typically used
+    /// in order to set an implementation-specific setting that isn't otherwise exposed from the strongly-typed properties
+    /// on <see cref="ChatOptions" />.
+    /// </remarks>
+    [JsonIgnore]
+    public object? RawRepresentation { get; set; }
+
     /// <summary>Gets or sets any additional properties associated with the options.</summary>
     public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
 
@@ -144,6 +163,7 @@ public virtual ChatOptions Clone()
             ModelId = ModelId,
             AllowMultipleToolCalls = AllowMultipleToolCalls,
             ToolMode = ToolMode,
+            RawRepresentation = RawRepresentation,
             AdditionalProperties = AdditionalProperties?.Clone(),
         };
 

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

@@ -2,8 +2,10 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using System;
+using System.ClientModel.Primitives;
 using System.Collections.Generic;
 using System.Diagnostics;
+using System.IO;
 using System.Linq;
 using System.Reflection;
 using System.Runtime.CompilerServices;
@@ -273,66 +275,71 @@ 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.")
+        };
+
+    private static ChatCompletionsOptions CloneRawRepresentation(IJsonModel<ChatCompletionsOptions> optionsAsModel)
+    {
+        using MemoryStream ms = new MemoryStream();
+        using Utf8JsonWriter writer = new Utf8JsonWriter(ms);
+        optionsAsModel.Write(writer, ModelReaderWriterOptions.Json);
+        writer.Flush();
+
+        var reader = new Utf8JsonReader(ms.ToArray());
+        return optionsAsModel.Create(ref reader, ModelReaderWriterOptions.Json);
+    }
+
     /// <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 is not null)
+        if (options.RawRepresentation is ChatCompletionsOptions result)
         {
-            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)
-                {
-                    result.StopSequences.Add(stopSequence);
-                }
-            }
+            // Clone the options to avoid modifying the original.
+            ////TODO: ToolChoice is not being cloned.
+            result = CloneRawRepresentation(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);
+        }
+
+        result.FrequencyPenalty ??= options.FrequencyPenalty;
+        result.MaxTokens ??= options.MaxOutputTokens;
+        result.NucleusSamplingFactor ??= options.TopP;
+        result.PresencePenalty ??= options.PresencePenalty;
+        result.Temperature ??= options.Temperature;
+        result.Seed ??= options.Seed;
 
-            // These properties are strongly typed on ChatOptions but not on ChatCompletionsOptions.
-            if (options.TopK is int topK)
+        if (options.StopSequences is { Count: > 0 } stopSequences)
+        {
+            foreach (string stopSequence in stopSequences)
             {
-                result.AdditionalProperties["top_k"] = new BinaryData(JsonSerializer.SerializeToUtf8Bytes(topK, AIJsonUtilities.DefaultOptions.GetTypeInfo(typeof(int))));
+                result.StopSequences.Add(stopSequence);
             }
+        }
 
-            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:
@@ -351,7 +358,10 @@ private ChatCompletionsOptions ToAzureAIOptions(IEnumerable<ChatMessage> chatCon
                         break;
                 }
             }
+        }
 
+        if (result.ResponseFormat is null)
+        {
             if (options.ResponseFormat is ChatResponseFormatText)
             {
                 result.ResponseFormat = ChatCompletionsResponseFormat.CreateTextFormat();