Merged PR 48177: Update IChatClient to support multiple return messages

Update IChatClient to support multiple return messages

- IChatClient no longer bakes mutation of the messages into the contract. The messages are now an `IEnumerable<ChatMessage>` rather than an `IList<ChatMessage>`.
- The purpose for mutation was to allow for multiple messages to be generated as part of an operation. All messages generated are now returned as part of the ChatResponse, which has a Messages rather than Message property.
- Choices have been removed from the surface area, e.g. no ChatResponse.Choices and no ChatResponseUpdate.ChoiceIndex.

----
#### AI description  (iteration 1)
#### PR Classification
New feature

#### PR Summary
This pull request updates the `IChatClient` to support multiple return messages.
- `src/Libraries/Microsoft.Extensions.AI/ChatCompletion/FunctionInvokingChatClient.cs`: Refactored `GetResponseAsync` and `GetStreamingResponseAsync` methods to handle multiple return messages, aggregate usage data, and process function calls across multiple iterations.
<!-- GitOpsUserAgent=GitOps.Apps.Server.pullrequestcopilot -->

Author: stephentoub

src/Libraries/Microsoft.Extensions.AI.Abstractions/AdditionalPropertiesDictionary{TValue}.cs

@@ -201,6 +201,18 @@ public bool TryGetValue<T>(string key, [NotNullWhen(true)] out T? value)
     /// <inheritdoc />
     bool IReadOnlyDictionary<string, TValue>.TryGetValue(string key, out TValue value) => _dictionary.TryGetValue(key, out value!);
 
+    /// <summary>Copies all of the entries from <paramref name="items"/> into the dictionary, overwriting any existing items in the dictionary with the same key.</summary>
+    /// <param name="items">The items to add.</param>
+    internal void SetAll(IEnumerable<KeyValuePair<string, TValue>> items)
+    {
+        _ = Throw.IfNull(items);
+
+        foreach (var item in items)
+        {
+            _dictionary[item.Key] = item.Value;
+        }
+    }
+
     /// <summary>Enumerates the elements of an <see cref="AdditionalPropertiesDictionary{TValue}"/>.</summary>
     public struct Enumerator : IEnumerator<KeyValuePair<string, TValue>>
     {

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

@@ -1,11 +1,11 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using System;
 using System.Collections.Generic;
 using System.Diagnostics;
 using System.Diagnostics.CodeAnalysis;
 using System.Text.Json.Serialization;
-using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Extensions.AI;
 
@@ -17,14 +17,15 @@ public class ChatMessage
     private string? _authorName;
 
     /// <summary>Initializes a new instance of the <see cref="ChatMessage"/> class.</summary>
+    /// <remarks>The instance defaults to having a role of <see cref="ChatRole.User"/>.</remarks>
     [JsonConstructor]
     public ChatMessage()
     {
     }
 
     /// <summary>Initializes a new instance of the <see cref="ChatMessage"/> class.</summary>
     /// <param name="role">The role of the author of the message.</param>
-    /// <param name="content">The contents of the message.</param>
+    /// <param name="content">The text content of the message.</param>
     public ChatMessage(ChatRole role, string? content)
         : this(role, content is null ? [] : [new TextContent(content)])
     {
@@ -33,12 +34,10 @@ public ChatMessage(ChatRole role, string? content)
     /// <summary>Initializes a new instance of the <see cref="ChatMessage"/> class.</summary>
     /// <param name="role">The role of the author of the message.</param>
     /// <param name="contents">The contents for this message.</param>
-    public ChatMessage(
-        ChatRole role,
-        IList<AIContent> contents)
+    public ChatMessage(ChatRole role, IList<AIContent>? contents)
     {
         Role = role;
-        _contents = Throw.IfNull(contents);
+        _contents = contents;
     }
 
     /// <summary>Clones the <see cref="ChatMessage"/> to a new <see cref="ChatMessage"/> instance.</summary>
@@ -67,29 +66,12 @@ public string? AuthorName
     /// <summary>Gets or sets the role of the author of the message.</summary>
     public ChatRole Role { get; set; } = ChatRole.User;
 
-    /// <summary>
-    /// Gets or sets the text of the first <see cref="TextContent"/> instance in <see cref="Contents" />.
-    /// </summary>
+    /// <summary>Gets the text of this message.</summary>
     /// <remarks>
-    /// If there is no <see cref="TextContent"/> instance in <see cref="Contents" />, then the getter returns <see langword="null" />,
-    /// and the setter adds a new <see cref="TextContent"/> instance with the provided value.
+    /// This property concatenates the text of all <see cref="TextContent"/> objects in <see cref="Contents"/>.
     /// </remarks>
     [JsonIgnore]
-    public string? Text
-    {
-        get => Contents.FindFirst<TextContent>()?.Text;
-        set
-        {
-            if (Contents.FindFirst<TextContent>() is { } textContent)
-            {
-                textContent.Text = value;
-            }
-            else if (value is not null)
-            {
-                Contents.Add(new TextContent(value));
-            }
-        }
-    }
+    public string Text => Contents.ConcatText();
 
     /// <summary>Gets or sets the chat message content items.</summary>
     [AllowNull]
@@ -112,7 +94,7 @@ public IList<AIContent> Contents
     public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
 
     /// <inheritdoc/>
-    public override string ToString() => Contents.ConcatText();
+    public override string ToString() => Text;
 
     /// <summary>Gets a <see cref="AIContent"/> object to display in the debugger display.</summary>
     [DebuggerBrowsable(DebuggerBrowsableState.Never)]

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

@@ -3,60 +3,62 @@
 
 using System;
 using System.Collections.Generic;
-using System.Text;
+using System.Diagnostics.CodeAnalysis;
 using System.Text.Json.Serialization;
 using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Extensions.AI;
 
 /// <summary>Represents the response to a chat request.</summary>
+/// <remarks>
+/// <see cref="ChatResponse"/> provides one or more response messages and metadata about the response.
+/// A typical response will contain a single message, however a response may contain multiple messages
+/// in a variety of scenarios. For example, if automatic function calling is employed, such that a single
+/// request to a <see cref="IChatClient"/> may actually generate multiple roundtrips to an inner <see cref="IChatClient"/>
+/// it uses, all of the involved messages may be surfaced as part of the final <see cref="ChatResponse"/>.
+/// </remarks>
 public class ChatResponse
 {
-    /// <summary>The list of choices in the response.</summary>
-    private IList<ChatMessage> _choices;
+    /// <summary>The response messages.</summary>
+    private IList<ChatMessage>? _messages;
 
     /// <summary>Initializes a new instance of the <see cref="ChatResponse"/> class.</summary>
-    /// <param name="choices">The list of choices in the response, one message per choice.</param>
-    [JsonConstructor]
-    public ChatResponse(IList<ChatMessage> choices)
+    public ChatResponse()
     {
-        _choices = Throw.IfNull(choices);
     }
 
     /// <summary>Initializes a new instance of the <see cref="ChatResponse"/> class.</summary>
-    /// <param name="message">The chat message representing the singular choice in the response.</param>
+    /// <param name="message">The response message.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="message"/> is <see langword="null"/>.</exception>
     public ChatResponse(ChatMessage message)
     {
         _ = Throw.IfNull(message);
-        _choices = [message];
+
+        Messages.Add(message);
+    }
+
+    /// <summary>Initializes a new instance of the <see cref="ChatResponse"/> class.</summary>
+    /// <param name="messages">The response messages.</param>
+    public ChatResponse(IList<ChatMessage>? messages)
+    {
+        _messages = messages;
     }
 
-    /// <summary>Gets or sets the list of chat response choices.</summary>
-    public IList<ChatMessage> Choices
+    /// <summary>Gets or sets the chat response messages.</summary>
+    [AllowNull]
+    public IList<ChatMessage> Messages
     {
-        get => _choices;
-        set => _choices = Throw.IfNull(value);
+        get => _messages ??= new List<ChatMessage>(1);
+        set => _messages = value;
     }
 
-    /// <summary>Gets the chat response message.</summary>
+    /// <summary>Gets the text of the response.</summary>
     /// <remarks>
-    /// If there are multiple choices, this property returns the first choice.
-    /// If <see cref="Choices"/> is empty, this property will throw. Use <see cref="Choices"/> to access all choices directly.
+    /// This property concatenates the <see cref="ChatMessage.Text"/> of all <see cref="ChatMessage"/>
+    /// instances in <see cref="Messages"/>.
     /// </remarks>
     [JsonIgnore]
-    public ChatMessage Message
-    {
-        get
-        {
-            var choices = Choices;
-            if (choices.Count == 0)
-            {
-                throw new InvalidOperationException($"The {nameof(ChatResponse)} instance does not contain any {nameof(ChatMessage)} choices.");
-            }
-
-            return choices[0];
-        }
-    }
+    public string Text => _messages?.ConcatText() ?? string.Empty;
 
     /// <summary>Gets or sets the ID of the chat response.</summary>
     public string? ResponseId { get; set; }
@@ -67,7 +69,7 @@ public ChatMessage Message
     /// the input messages supplied to <see cref="IChatClient.GetResponseAsync"/> need only be the additional messages beyond
     /// what's already stored. If this property is non-<see langword="null"/>, it represents an identifier for that state,
     /// and it should be used in a subsequent <see cref="ChatOptions.ChatThreadId"/> instead of supplying the same messages
-    /// (and this <see cref="ChatResponse"/>'s message) as part of the <c>chatMessages</c> parameter.
+    /// (and this <see cref="ChatResponse"/>'s message) as part of the <c>messages</c> parameter.
     /// </remarks>
     public string? ChatThreadId { get; set; }
 
@@ -96,26 +98,7 @@ public ChatMessage Message
     public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
 
     /// <inheritdoc />
-    public override string ToString()
-    {
-        if (Choices.Count == 1)
-        {
-            return Choices[0].ToString();
-        }
-
-        StringBuilder sb = new();
-        for (int i = 0; i < Choices.Count; i++)
-        {
-            if (i > 0)
-            {
-                _ = sb.AppendLine().AppendLine();
-            }
-
-            _ = sb.Append("Choice ").Append(i).AppendLine(":").Append(Choices[i]);
-        }
-
-        return sb.ToString();
-    }
+    public override string ToString() => Text;
 
     /// <summary>Creates an array of <see cref="ChatResponseUpdate" /> instances that represent this <see cref="ChatResponse" />.</summary>
     /// <returns>An array of <see cref="ChatResponseUpdate" /> instances that may be used to represent this <see cref="ChatResponse" />.</returns>
@@ -135,22 +118,22 @@ public ChatResponseUpdate[] ToChatResponseUpdates()
             }
         }
 
-        int choicesCount = Choices.Count;
-        var updates = new ChatResponseUpdate[choicesCount + (extra is null ? 0 : 1)];
+        int messageCount = _messages?.Count ?? 0;
+        var updates = new ChatResponseUpdate[messageCount + (extra is not null ? 1 : 0)];
 
-        for (int choiceIndex = 0; choiceIndex < choicesCount; choiceIndex++)
+        int i;
+        for (i = 0; i < messageCount; i++)
         {
-            ChatMessage choice = Choices[choiceIndex];
-            updates[choiceIndex] = new ChatResponseUpdate
+            ChatMessage message = _messages![i];
+            updates[i] = new ChatResponseUpdate
             {
                 ChatThreadId = ChatThreadId,
-                ChoiceIndex = choiceIndex,
 
-                AdditionalProperties = choice.AdditionalProperties,
-                AuthorName = choice.AuthorName,
-                Contents = choice.Contents,
-                RawRepresentation = choice.RawRepresentation,
-                Role = choice.Role,
+                AdditionalProperties = message.AdditionalProperties,
+                AuthorName = message.AuthorName,
+                Contents = message.Contents,
+                RawRepresentation = message.RawRepresentation,
+                Role = message.Role,
 
                 ResponseId = ResponseId,
                 CreatedAt = CreatedAt,
@@ -161,7 +144,7 @@ public ChatResponseUpdate[] ToChatResponseUpdates()
 
         if (extra is not null)
         {
-            updates[choicesCount] = extra;
+            updates[i] = extra;
         }
 
         return updates;