Enhance Function Invocation Extensibility for Microsoft.Extensions.AI (#6325)

Author: rogerbarreto

src/Libraries/Microsoft.Extensions.AI.Abstractions/Functions/AIFunctionArguments.cs

@@ -8,6 +8,10 @@
 #pragma warning disable SA1111 // Closing parenthesis should be on line of last parameter
 #pragma warning disable SA1112 // Closing parenthesis should be on line of opening parenthesis
 #pragma warning disable SA1114 // Parameter list should follow declaration
+#pragma warning disable S3358 // Extract this nested ternary operation into an independent statement.
+#pragma warning disable S1067 // Expressions should not be too complex
+#pragma warning disable S4039 // Make 'AIFunctionArguments' sealed
+#pragma warning disable CA1033 // Make 'AIFunctionArguments' sealed
 #pragma warning disable CA1710 // Identifiers should have correct suffix
 
 namespace Microsoft.Extensions.AI;
@@ -20,15 +24,16 @@ namespace Microsoft.Extensions.AI;
 /// an <see cref="AIFunction"/> if it needs to resolve any services from a dependency injection
 /// container.
 /// </remarks>
-public sealed class AIFunctionArguments : IDictionary<string, object?>, IReadOnlyDictionary<string, object?>
+public class AIFunctionArguments : IDictionary<string, object?>, IReadOnlyDictionary<string, object?>
 {
     /// <summary>The nominal arguments.</summary>
     private readonly Dictionary<string, object?> _arguments;
 
-    /// <summary>Initializes a new instance of the <see cref="AIFunctionArguments"/> class.</summary>
+    /// <summary>Initializes a new instance of the <see cref="AIFunctionArguments"/> class, and uses the default comparer for key comparisons.</summary>
+    /// <remarks>The <see cref="IEqualityComparer{T}"/> is ordinal by default.</remarks>
     public AIFunctionArguments()
+        : this(null, null)
     {
-        _arguments = [];
     }
 
     /// <summary>
@@ -42,14 +47,44 @@ public AIFunctionArguments()
     /// operations on this instance will be routed directly to that instance. If <paramref name="arguments"/>
     /// is not a dictionary, a shallow clone of its data will be used to populate this
     /// instance. A <see langword="null"/> <paramref name="arguments"/> is treated as an
-    /// empty dictionary.
+    /// empty parameters dictionary.
+    /// The <see cref="IEqualityComparer{T}"/> is ordinal by default.
     /// </remarks>
     public AIFunctionArguments(IDictionary<string, object?>? arguments)
+        : this(arguments, null)
+    {
+    }
+
+    /// <summary>Initializes a new instance of the <see cref="AIFunctionArguments"/> class.</summary>
+    /// <param name="comparer">The <see cref="IEqualityComparer{T}"/> to use for key comparisons.</param>
+    public AIFunctionArguments(IEqualityComparer<string>? comparer)
+        : this(null, comparer)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AIFunctionArguments"/> class containing
+    /// the specified <paramref name="arguments"/>.
+    /// </summary>
+    /// <param name="arguments">The arguments represented by this instance.</param>
+    /// <param name="comparer">The <see cref="IEqualityComparer{T}"/> to be used.</param>
+    /// <remarks>
+    /// The <paramref name="arguments"/> reference will be stored if the instance is already a
+    /// <see cref="Dictionary{TKey, TValue}"/> with the same <see cref="IEqualityComparer{T}"/> or if
+    /// <paramref name="arguments"/> is <see langword="null" /> in which case all dictionary operations
+    /// on this instance will be routed directly to that instance otherwise a shallow clone of the provided <paramref name="arguments"/>.
+    /// A <see langword="null"/> <paramref name="arguments"/> is will be treated as an empty parameters dictionary.
+    /// </remarks>
+    public AIFunctionArguments(IDictionary<string, object?>? arguments, IEqualityComparer<string>? comparer)
     {
+#pragma warning disable S1698 // Consider using 'Equals' if value comparison is intended.
         _arguments =
-            arguments is null ? [] :
-            arguments as Dictionary<string, object?> ??
-            new Dictionary<string, object?>(arguments);
+            arguments is null
+                ? new Dictionary<string, object?>(comparer)
+                : (arguments is Dictionary<string, object?> dc) && (comparer is null || dc.Comparer == comparer)
+                    ? dc
+                    : new Dictionary<string, object?>(arguments, comparer);
+#pragma warning restore S1698 // Consider using 'Equals' if value comparison is intended.
     }
 
     /// <summary>Gets or sets services optionally associated with these arguments.</summary>

src/Libraries/Microsoft.Extensions.AI/ChatCompletion/FunctionInvocationContext.cs

@@ -9,7 +9,7 @@
 namespace Microsoft.Extensions.AI;
 
 /// <summary>Provides context for an in-flight function invocation.</summary>
-public sealed class FunctionInvocationContext
+public class FunctionInvocationContext
 {
     /// <summary>
     /// A nop function used to allow <see cref="Function"/> to be non-nullable. Default instances of
@@ -92,6 +92,16 @@ public IList<ChatMessage> Messages
     /// and a new request issued to the wrapped client. If this property is set to <see langword="true"/>, that subsequent request
     /// will not be issued and instead the loop immediately terminated rather than continuing until there are no
     /// more function call requests in responses.
+    /// <para>
+    /// If multiple function call requests are issued as part of a single iteration (a single response from the inner <see cref="IChatClient"/>),
+    /// setting <see cref="Terminate" /> to <see langword="true" /> may also prevent subsequent requests within that same iteration from being processed.
+    /// </para>
     /// </remarks>
     public bool Terminate { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the function invocation is occurring as part of a
+    /// <see cref="IChatClient.GetStreamingResponseAsync"/> call as opposed to a <see cref="IChatClient.GetResponseAsync"/> call.
+    /// </summary>
+    public bool IsStreaming { get; set; }
 }