Merge branch 'main' of https://github.com/dotnet/extensions into connector_id

Author: jozkee

eng/Versions.props

@@ -1,7 +1,7 @@
 <Project>
   <PropertyGroup Label="Version settings">
-    <MajorVersion>9</MajorVersion>
-    <MinorVersion>10</MinorVersion>
+    <MajorVersion>10</MajorVersion>
+    <MinorVersion>0</MinorVersion>
     <PatchVersion>0</PatchVersion>
     <PreReleaseVersionLabel>preview</PreReleaseVersionLabel>
     <PreReleaseVersionIteration>1</PreReleaseVersionIteration>

src/Generators/Microsoft.Gen.Metrics/Parser.cs

@@ -574,7 +574,7 @@ private bool CheckMethodReturnType(IMethodSymbol methodSymbol)
             returnType.TypeKind != TypeKind.Error)
         {
             // Make sure return type is not from existing known type
-            Diag(DiagDescriptors.ErrorInvalidMethodReturnType, methodSymbol.ReturnType.GetLocation(), methodSymbol.Name);
+            Diag(DiagDescriptors.ErrorInvalidMethodReturnType, returnType.GetLocation(), returnType.ToDisplayString(SymbolDisplayFormat.MinimallyQualifiedFormat));
             return false;
         }
 

src/Libraries/.editorconfig

@@ -2936,7 +2936,7 @@ dotnet_diagnostic.S103.severity = suggestion
 # Title    : Files should not have too many lines of code
 # Category : Major Code Smell
 # Help Link: https://rules.sonarsource.com/csharp/RSPEC-104
-dotnet_diagnostic.S104.severity = warning
+dotnet_diagnostic.S104.severity = none
 
 # Title    : Finalizers should not throw exceptions
 # Category : Blocker Bug

src/Libraries/Microsoft.Extensions.AI.Abstractions/CHANGELOG.md

@@ -5,6 +5,7 @@
 - Added protected copy constructors to options types (e.g. `ChatOptions`).
 - Fixed `EmbeddingGeneratorOptions`/`SpeechToTextOptions` `Clone` methods to correctly copy all properties.
 - Fixed `ToChatResponse` to not overwrite `ChatMessage/ChatResponse.CreatedAt` with older timestamps during coalescing. 
+- Added `[Experimental]` support for background responses, such that non-streaming responses are allowed to be pollable, and such that responses and response updates can be tagged with continuation tokens to support later resumption.
 
 ## 9.9.1
 

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

@@ -3,6 +3,7 @@
 
 using System;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 using System.Text.Json.Serialization;
 
 namespace Microsoft.Extensions.AI;
@@ -25,8 +26,10 @@ protected ChatOptions(ChatOptions? other)
         }
 
         AdditionalProperties = other.AdditionalProperties?.Clone();
+        AllowBackgroundResponses = other.AllowBackgroundResponses;
         AllowMultipleToolCalls = other.AllowMultipleToolCalls;
         ConversationId = other.ConversationId;
+        ContinuationToken = other.ContinuationToken;
         FrequencyPenalty = other.FrequencyPenalty;
         Instructions = other.Instructions;
         MaxOutputTokens = other.MaxOutputTokens;
@@ -155,6 +158,47 @@ protected ChatOptions(ChatOptions? other)
     [JsonIgnore]
     public IList<AITool>? Tools { get; set; }
 
+    /// <summary>Gets or sets a value indicating whether the background responses are allowed.</summary>
+    /// <remarks>
+    /// <para>
+    /// Background responses allow running long-running operations or tasks asynchronously in the background that can be resumed by streaming APIs
+    /// and polled for completion by non-streaming APIs.
+    /// </para>
+    /// <para>
+    /// When this property is set to true, non-streaming APIs may start a background operation and return an initial
+    /// response with a continuation token. Subsequent calls to the same API should be made in a polling manner with
+    /// the continuation token to get the final result of the operation.
+    /// </para>
+    /// <para>
+    /// When this property is set to true, streaming APIs may also start a background operation and begin streaming
+    /// response updates until the operation is completed. If the streaming connection is interrupted, the
+    /// continuation token obtained from the last update that has one should be supplied to a subsequent call to the same streaming API
+    /// to resume the stream from the point of interruption and continue receiving updates until the operation is completed.
+    /// </para>
+    /// <para>
+    /// This property only takes effect if the implementation it's used with supports background responses.
+    /// If the implementation does not support background responses, this property will be ignored.
+    /// </para>
+    /// </remarks>
+    [Experimental("MEAI001")]
+    [JsonIgnore]
+    public bool? AllowBackgroundResponses { get; set; }
+
+    /// <summary>Gets or sets the continuation token for resuming and getting the result of the chat response identified by this token.</summary>
+    /// <remarks>
+    /// This property is used for background responses that can be activated via the <see cref="AllowBackgroundResponses"/>
+    /// property if the <see cref="IChatClient"/> implementation supports them.
+    /// Streamed background responses, such as those returned by default by <see cref="IChatClient.GetStreamingResponseAsync"/>,
+    /// can be resumed if interrupted. This means that a continuation token obtained from the <see cref="ChatResponseUpdate.ContinuationToken"/> 
+    /// of an update just before the interruption occurred can be passed to this property to resume the stream from the point of interruption.
+    /// Non-streamed background responses, such as those returned by <see cref="IChatClient.GetResponseAsync"/>,
+    /// can be polled for completion by obtaining the token from the <see cref="ChatResponse.ContinuationToken"/> property 
+    /// and passing it to this property on subsequent calls to <see cref="IChatClient.GetResponseAsync"/>.
+    /// </remarks>
+    [Experimental("MEAI001")]
+    [JsonIgnore]
+    public object? ContinuationToken { get; set; }
+
     /// <summary>
     /// Gets or sets a callback responsible for creating the raw representation of the chat options from an underlying implementation.
     /// </summary>

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

@@ -88,6 +88,23 @@ public IList<ChatMessage> Messages
     /// <summary>Gets or sets usage details for the chat response.</summary>
     public UsageDetails? Usage { get; set; }
 
+    /// <summary>Gets or sets the continuation token for getting result of the background chat response.</summary>
+    /// <remarks>
+    /// <see cref="IChatClient"/> implementations that support background responses will return
+    /// a continuation token if background responses are allowed in <see cref="ChatOptions.AllowBackgroundResponses"/>
+    /// and the result of the response has not been obtained yet. If the response has completed and the result has been obtained,
+    /// the token will be <see langword="null"/>.
+    /// <para>
+    /// This property should be used in conjunction with <see cref="ChatOptions.ContinuationToken"/> to 
+    /// continue to poll for the completion of the response. Pass this token to
+    /// <see cref="ChatOptions.ContinuationToken"/> on subsequent calls to <see cref="IChatClient.GetResponseAsync"/>
+    /// to poll for completion.
+    /// </para>
+    /// </remarks>
+    [Experimental("MEAI001")]
+    [JsonIgnore]
+    public object? ContinuationToken { get; set; }
+
     /// <summary>Gets or sets the raw representation of the chat response from an underlying implementation.</summary>
     /// <remarks>
     /// If a <see cref="ChatResponse"/> is created to represent some underlying object from another object
@@ -143,6 +160,7 @@ public ChatResponseUpdate[] ToChatResponseUpdates()
                 ResponseId = ResponseId,
 
                 CreatedAt = message.CreatedAt ?? CreatedAt,
+                ContinuationToken = ContinuationToken,
             };
         }
 

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

@@ -306,26 +306,19 @@ private static void FinalizeResponse(ChatResponse response)
     private static void ProcessUpdate(ChatResponseUpdate update, ChatResponse response)
     {
         // If there is no message created yet, or if the last update we saw had a different
-        // message ID or role than the newest update, create a new message.
-        ChatMessage message;
-        var isNewMessage = false;
-        if (response.Messages.Count == 0)
-        {
-            isNewMessage = true;
-        }
-        else if (update.MessageId is { Length: > 0 } updateMessageId
-            && response.Messages[response.Messages.Count - 1].MessageId is string lastMessageId
-            && updateMessageId != lastMessageId)
-        {
-            isNewMessage = true;
-        }
-        else if (update.Role is { } updateRole
-            && response.Messages[response.Messages.Count - 1].Role is { } lastRole
-            && updateRole != lastRole)
+        // identifying parts, create a new message.
+        bool isNewMessage = true;
+        if (response.Messages.Count != 0)
         {
-            isNewMessage = true;
+            var lastMessage = response.Messages[response.Messages.Count - 1];
+            isNewMessage =
+                NotEmptyOrEqual(update.AuthorName, lastMessage.AuthorName) ||
+                NotEmptyOrEqual(update.MessageId, lastMessage.MessageId) ||
+                NotNullOrEqual(update.Role, lastMessage.Role);
         }
 
+        // Get the message to target, either a new one or the last ones.
+        ChatMessage message;
         if (isNewMessage)
         {
             message = new(ChatRole.Assistant, []);
@@ -418,4 +411,12 @@ private static void ProcessUpdate(ChatResponseUpdate update, ChatResponse respon
             }
         }
     }
+
+    /// <summary>Gets whether both strings are not null/empty and not the same as each other.</summary>
+    private static bool NotEmptyOrEqual(string? s1, string? s2) =>
+        s1 is { Length: > 0 } str1 && s2 is { Length: > 0 } str2 && str1 != str2;
+
+    /// <summary>Gets whether two roles are not null and not the same as each other.</summary>
+    private static bool NotNullOrEqual(ChatRole? r1, ChatRole? r2) =>
+        r1.HasValue && r2.HasValue && r1.Value != r2.Value;
 }

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

@@ -136,6 +136,21 @@ public IList<AIContent> Contents
     /// <inheritdoc/>
     public override string ToString() => Text;
 
+    /// <summary>Gets or sets the continuation token for resuming the streamed chat response of which this update is a part.</summary>
+    /// <remarks>
+    /// <see cref="IChatClient"/> implementations that support background responses will return
+    /// a continuation token on each update if background responses are allowed in <see cref="ChatOptions.AllowBackgroundResponses"/>
+    /// except of the last update, for which the token will be <see langword="null"/>.
+    /// <para>
+    /// This property should be used for stream resumption, where the continuation token of the latest received update should be
+    /// passed to <see cref="ChatOptions.ContinuationToken"/> on subsequent calls to <see cref="IChatClient.GetStreamingResponseAsync"/>
+    /// to resume streaming from the point of interruption.
+    /// </para>
+    /// </remarks>
+    [Experimental("MEAI001")]
+    [JsonIgnore]
+    public object? ContinuationToken { get; set; }
+
     /// <summary>Gets a <see cref="AIContent"/> object to display in the debugger display.</summary>
     [DebuggerBrowsable(DebuggerBrowsableState.Never)]
     private AIContent? ContentForDebuggerDisplay

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/AIContent.cs

@@ -21,7 +21,9 @@ namespace Microsoft.Extensions.AI;
 
 // These should be added in once they're no longer [Experimental]. If they're included while still
 // experimental, any JsonSerializerContext that includes AIContent will incur errors about using
-// experimental types in its source generated files.
+// experimental types in its source generated files. When [Experimental] is removed from these types,
+// these lines should be uncommented and the corresponding lines in AIJsonUtilities.CreateDefaultOptions
+// as well as the [JsonSerializable] attributes for them on the JsonContext should be removed.
 // [JsonDerivedType(typeof(FunctionApprovalRequestContent), typeDiscriminator: "functionApprovalRequest")]
 // [JsonDerivedType(typeof(FunctionApprovalResponseContent), typeDiscriminator: "functionApprovalResponse")]
 // [JsonDerivedType(typeof(McpServerToolCallContent), typeDiscriminator: "mcpServerToolCall")]

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

@@ -749,11 +749,21 @@ private static string GetFunctionName(MethodInfo method)
             string name = SanitizeMemberName(method.Name);
 
             const string AsyncSuffix = "Async";
-            if (IsAsyncMethod(method) &&
-                name.EndsWith(AsyncSuffix, StringComparison.Ordinal) &&
-                name.Length > AsyncSuffix.Length)
+            if (IsAsyncMethod(method))
             {
-                name = name.Substring(0, name.Length - AsyncSuffix.Length);
+                // If the method ends in "Async" or contains "Async_", remove the "Async".
+                int asyncIndex = name.LastIndexOf(AsyncSuffix, StringComparison.Ordinal);
+                if (asyncIndex > 0 &&
+                    (asyncIndex + AsyncSuffix.Length == name.Length ||
+                     ((asyncIndex + AsyncSuffix.Length < name.Length) && (name[asyncIndex + AsyncSuffix.Length] == '_'))))
+                {
+                    name =
+#if NET
+                        string.Concat(name.AsSpan(0, asyncIndex), name.AsSpan(asyncIndex + AsyncSuffix.Length));
+#else
+                        string.Concat(name.Substring(0, asyncIndex), name.Substring(asyncIndex + AsyncSuffix.Length));
+#endif
+                }
             }
 
             return name;
@@ -1105,16 +1115,37 @@ private record struct DescriptorKey(
     /// Replaces non-alphanumeric characters in the identifier with the underscore character.
     /// Primarily intended to remove characters produced by compiler-generated method name mangling.
     /// </returns>
-    private static string SanitizeMemberName(string memberName) =>
-        InvalidNameCharsRegex().Replace(memberName, "_");
+    private static string SanitizeMemberName(string memberName)
+    {
+        // Handle compiler-generated names (local functions and lambdas)
+        // Local functions: <ContainingMethod>g__LocalFunctionName|ordinal_depth -> ContainingMethod_LocalFunctionName_ordinal_depth
+        // Lambdas: <ContainingMethod>b__ordinal_depth -> ContainingMethod_ordinal_depth
+        if (CompilerGeneratedNameRegex().Match(memberName) is { Success: true } match)
+        {
+            memberName = $"{match.Groups[1].Value}_{match.Groups[2].Value}";
+        }
+
+        // Replace all non-alphanumeric characters with underscores.
+        return InvalidNameCharsRegex().Replace(memberName, "_");
+    }
+
+    /// <summary>Regex that matches compiler-generated names (local functions and lambdas).</summary>
+#if NET
+    [GeneratedRegex(@"^<([^>]+)>\w__(.+)")]
+    private static partial Regex CompilerGeneratedNameRegex();
+#else
+    private static Regex CompilerGeneratedNameRegex() => _compilerGeneratedNameRegex;
+    private static readonly Regex _compilerGeneratedNameRegex = new(@"^<([^>]+)>\w__(.+)", RegexOptions.Compiled);
+#endif
 
-    /// <summary>Regex that flags any character other than ASCII digits or letters or the underscore.</summary>
+    /// <summary>Regex that flags any character other than ASCII digits or letters.</summary>
+    /// <remarks>Underscore isn't included so that sequences of underscores are replaced by a single one.</remarks>
 #if NET
-    [GeneratedRegex("[^0-9A-Za-z_]")]
+    [GeneratedRegex("[^0-9A-Za-z]+")]
     private static partial Regex InvalidNameCharsRegex();
 #else
     private static Regex InvalidNameCharsRegex() => _invalidNameCharsRegex;
-    private static readonly Regex _invalidNameCharsRegex = new("[^0-9A-Za-z_]", RegexOptions.Compiled);
+    private static readonly Regex _invalidNameCharsRegex = new("[^0-9A-Za-z]+", RegexOptions.Compiled);
 #endif
 
     /// <summary>Invokes the MethodInfo with the specified target object and arguments.</summary>