Rename IChatClient members and corresponding types

After great feedback on usage of the APIs, re-reviewing the state of the ecosystem, and length discussions, we're renaming the members of IChatClient to destress the notion of "completions" and instead focus just on getting back a {streaming} response.

Author: stephentoub

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

@@ -27,13 +27,13 @@ public static class ChatClientExtensions
         return (TService?)client.GetService(typeof(TService), serviceKey);
     }
 
-    /// <summary>Sends a user chat text message to the model and returns the response messages.</summary>
+    /// <summary>Sends a user chat text message and returns the response messages.</summary>
     /// <param name="client">The chat client.</param>
     /// <param name="chatMessage">The text content for the chat message to send.</param>
     /// <param name="options">The chat options to configure the request.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
     /// <returns>The response messages generated by the client.</returns>
-    public static Task<ChatCompletion> CompleteAsync(
+    public static Task<ChatResponse> GetResponseAsync(
         this IChatClient client,
         string chatMessage,
         ChatOptions? options = null,
@@ -42,16 +42,16 @@ public static Task<ChatCompletion> CompleteAsync(
         _ = Throw.IfNull(client);
         _ = Throw.IfNull(chatMessage);
 
-        return client.CompleteAsync(new ChatMessage(ChatRole.User, chatMessage), options, cancellationToken);
+        return client.GetResponseAsync(new ChatMessage(ChatRole.User, chatMessage), options, cancellationToken);
     }
 
-    /// <summary>Sends a chat message to the model and returns the response messages.</summary>
+    /// <summary>Sends a chat message and returns the response messages.</summary>
     /// <param name="client">The chat client.</param>
     /// <param name="chatMessage">The chat message to send.</param>
     /// <param name="options">The chat options to configure the request.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
     /// <returns>The response messages generated by the client.</returns>
-    public static Task<ChatCompletion> CompleteAsync(
+    public static Task<ChatResponse> GetResponseAsync(
         this IChatClient client,
         ChatMessage chatMessage,
         ChatOptions? options = null,
@@ -60,16 +60,16 @@ public static Task<ChatCompletion> CompleteAsync(
         _ = Throw.IfNull(client);
         _ = Throw.IfNull(chatMessage);
 
-        return client.CompleteAsync([chatMessage], options, cancellationToken);
+        return client.GetResponseAsync([chatMessage], options, cancellationToken);
     }
 
-    /// <summary>Sends a user chat text message to the model and streams the response messages.</summary>
+    /// <summary>Sends a user chat text message and streams the response messages.</summary>
     /// <param name="client">The chat client.</param>
     /// <param name="chatMessage">The text content for the chat message to send.</param>
     /// <param name="options">The chat options to configure the request.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
     /// <returns>The response messages generated by the client.</returns>
-    public static IAsyncEnumerable<StreamingChatCompletionUpdate> CompleteStreamingAsync(
+    public static IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
         this IChatClient client,
         string chatMessage,
         ChatOptions? options = null,
@@ -78,16 +78,16 @@ public static IAsyncEnumerable<StreamingChatCompletionUpdate> CompleteStreamingA
         _ = Throw.IfNull(client);
         _ = Throw.IfNull(chatMessage);
 
-        return client.CompleteStreamingAsync(new ChatMessage(ChatRole.User, chatMessage), options, cancellationToken);
+        return client.GetStreamingResponseAsync(new ChatMessage(ChatRole.User, chatMessage), options, cancellationToken);
     }
 
-    /// <summary>Sends a chat message to the model and streams the response messages.</summary>
+    /// <summary>Sends a chat message and streams the response messages.</summary>
     /// <param name="client">The chat client.</param>
     /// <param name="chatMessage">The chat message to send.</param>
     /// <param name="options">The chat options to configure the request.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
     /// <returns>The response messages generated by the client.</returns>
-    public static IAsyncEnumerable<StreamingChatCompletionUpdate> CompleteStreamingAsync(
+    public static IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
         this IChatClient client,
         ChatMessage chatMessage,
         ChatOptions? options = null,
@@ -96,6 +96,6 @@ public static IAsyncEnumerable<StreamingChatCompletionUpdate> CompleteStreamingA
         _ = Throw.IfNull(client);
         _ = Throw.IfNull(chatMessage);
 
-        return client.CompleteStreamingAsync([chatMessage], options, cancellationToken);
+        return client.GetStreamingResponseAsync([chatMessage], options, cancellationToken);
     }
 }

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

@@ -10,29 +10,29 @@ public class ChatClientMetadata
 {
     /// <summary>Initializes a new instance of the <see cref="ChatClientMetadata"/> class.</summary>
     /// <param name="providerName">
-    /// The name of the chat completion provider, if applicable. Where possible, this should map to the
+    /// The name of the chat provider, if applicable. Where possible, this should map to the
     /// appropriate name defined in the OpenTelemetry Semantic Conventions for Generative AI systems.
     /// </param>
-    /// <param name="providerUri">The URL for accessing the chat completion provider, if applicable.</param>
-    /// <param name="modelId">The ID of the chat completion model used, if applicable.</param>
+    /// <param name="providerUri">The URL for accessing the chat provider, if applicable.</param>
+    /// <param name="modelId">The ID of the chat model used, if applicable.</param>
     public ChatClientMetadata(string? providerName = null, Uri? providerUri = null, string? modelId = null)
     {
         ModelId = modelId;
         ProviderName = providerName;
         ProviderUri = providerUri;
     }
 
-    /// <summary>Gets the name of the chat completion provider.</summary>
+    /// <summary>Gets the name of the chat provider.</summary>
     /// <remarks>
     /// Where possible, this maps to the appropriate name defined in the
     /// OpenTelemetry Semantic Conventions for Generative AI systems.
     /// </remarks>
     public string? ProviderName { get; }
 
-    /// <summary>Gets the URL for accessing the chat completion provider.</summary>
+    /// <summary>Gets the URL for accessing the chat provider.</summary>
     public Uri? ProviderUri { get; }
 
-    /// <summary>Gets the ID of the model used by this chat completion provider.</summary>
+    /// <summary>Gets the ID of the model used by this chat provider.</summary>
     /// <remarks>
     /// This value can be null if either the name is unknown or there are multiple possible models associated with this instance.
     /// An individual request may override this value via <see cref="ChatOptions.ModelId"/>.

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

@@ -9,36 +9,36 @@
 
 namespace Microsoft.Extensions.AI;
 
-/// <summary>Represents the result of a chat completion request.</summary>
-public class ChatCompletion
+/// <summary>Represents the response to a chat request.</summary>
+public class ChatResponse
 {
-    /// <summary>The list of choices in the completion.</summary>
+    /// <summary>The list of choices in the response.</summary>
     private IList<ChatMessage> _choices;
 
-    /// <summary>Initializes a new instance of the <see cref="ChatCompletion"/> class.</summary>
-    /// <param name="choices">The list of choices in the completion, one message per choice.</param>
+    /// <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 ChatCompletion(IList<ChatMessage> choices)
+    public ChatResponse(IList<ChatMessage> choices)
     {
         _choices = Throw.IfNull(choices);
     }
 
-    /// <summary>Initializes a new instance of the <see cref="ChatCompletion"/> class.</summary>
-    /// <param name="message">The chat message representing the singular choice in the completion.</param>
-    public ChatCompletion(ChatMessage message)
+    /// <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>
+    public ChatResponse(ChatMessage message)
     {
         _ = Throw.IfNull(message);
         _choices = [message];
     }
 
-    /// <summary>Gets or sets the list of chat completion choices.</summary>
+    /// <summary>Gets or sets the list of chat response choices.</summary>
     public IList<ChatMessage> Choices
     {
         get => _choices;
         set => _choices = Throw.IfNull(value);
     }
 
-    /// <summary>Gets the chat completion message.</summary>
+    /// <summary>Gets the chat response message.</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.
@@ -51,48 +51,48 @@ public ChatMessage Message
             var choices = Choices;
             if (choices.Count == 0)
             {
-                throw new InvalidOperationException($"The {nameof(ChatCompletion)} instance does not contain any {nameof(ChatMessage)} choices.");
+                throw new InvalidOperationException($"The {nameof(ChatResponse)} instance does not contain any {nameof(ChatMessage)} choices.");
             }
 
             return choices[0];
         }
     }
 
-    /// <summary>Gets or sets the ID of the chat completion.</summary>
-    public string? CompletionId { get; set; }
+    /// <summary>Gets or sets the ID of the chat response.</summary>
+    public string? ResponseId { get; set; }
 
-    /// <summary>Gets or sets the chat thread ID associated with this chat completion.</summary>
+    /// <summary>Gets or sets the chat thread ID associated with this chat response.</summary>
     /// <remarks>
     /// Some <see cref="IChatClient"/> implementations are capable of storing the state for a chat thread, such that
-    /// the input messages supplied to <see cref="IChatClient.CompleteAsync"/> need only be the additional messages beyond
+    /// 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="ChatCompletion"/>'s message) as part of the <c>chatMessages</c> parameter.
+    /// (and this <see cref="ChatResponse"/>'s message) as part of the <c>chatMessages</c> parameter.
     /// </remarks>
     public string? ChatThreadId { get; set; }
 
-    /// <summary>Gets or sets the model ID used in the creation of the chat completion.</summary>
+    /// <summary>Gets or sets the model ID used in the creation of the chat response.</summary>
     public string? ModelId { get; set; }
 
-    /// <summary>Gets or sets a timestamp for the chat completion.</summary>
+    /// <summary>Gets or sets a timestamp for the chat response.</summary>
     public DateTimeOffset? CreatedAt { get; set; }
 
-    /// <summary>Gets or sets the reason for the chat completion.</summary>
+    /// <summary>Gets or sets the reason for the chat response.</summary>
     public ChatFinishReason? FinishReason { get; set; }
 
-    /// <summary>Gets or sets usage details for the chat completion.</summary>
+    /// <summary>Gets or sets usage details for the chat response.</summary>
     public UsageDetails? Usage { get; set; }
 
-    /// <summary>Gets or sets the raw representation of the chat completion from an underlying implementation.</summary>
+    /// <summary>Gets or sets the raw representation of the chat response from an underlying implementation.</summary>
     /// <remarks>
-    /// If a <see cref="ChatCompletion"/> is created to represent some underlying object from another object
+    /// If a <see cref="ChatResponse"/> is created to represent some underlying object from another object
     /// model, this property can be used to store that original object. This can be useful for debugging or
     /// for enabling a consumer to access the underlying object model if needed.
     /// </remarks>
     [JsonIgnore]
     public object? RawRepresentation { get; set; }
 
-    /// <summary>Gets or sets any additional properties associated with the chat completion.</summary>
+    /// <summary>Gets or sets any additional properties associated with the chat response.</summary>
     public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
 
     /// <inheritdoc />
@@ -117,14 +117,14 @@ public override string ToString()
         return sb.ToString();
     }
 
-    /// <summary>Creates an array of <see cref="StreamingChatCompletionUpdate" /> instances that represent this <see cref="ChatCompletion" />.</summary>
-    /// <returns>An array of <see cref="StreamingChatCompletionUpdate" /> instances that may be used to represent this <see cref="ChatCompletion" />.</returns>
-    public StreamingChatCompletionUpdate[] ToStreamingChatCompletionUpdates()
+    /// <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>
+    public ChatResponseUpdate[] ToChatResponseUpdates()
     {
-        StreamingChatCompletionUpdate? extra = null;
+        ChatResponseUpdate? extra = null;
         if (AdditionalProperties is not null || Usage is not null)
         {
-            extra = new StreamingChatCompletionUpdate
+            extra = new ChatResponseUpdate
             {
                 AdditionalProperties = AdditionalProperties
             };
@@ -136,12 +136,12 @@ public StreamingChatCompletionUpdate[] ToStreamingChatCompletionUpdates()
         }
 
         int choicesCount = Choices.Count;
-        var updates = new StreamingChatCompletionUpdate[choicesCount + (extra is null ? 0 : 1)];
+        var updates = new ChatResponseUpdate[choicesCount + (extra is null ? 0 : 1)];
 
         for (int choiceIndex = 0; choiceIndex < choicesCount; choiceIndex++)
         {
             ChatMessage choice = Choices[choiceIndex];
-            updates[choiceIndex] = new StreamingChatCompletionUpdate
+            updates[choiceIndex] = new ChatResponseUpdate
             {
                 ChatThreadId = ChatThreadId,
                 ChoiceIndex = choiceIndex,
@@ -152,7 +152,7 @@ public StreamingChatCompletionUpdate[] ToStreamingChatCompletionUpdates()
                 RawRepresentation = choice.RawRepresentation,
                 Role = choice.Role,
 
-                CompletionId = CompletionId,
+                ResponseId = ResponseId,
                 CreatedAt = CreatedAt,
                 FinishReason = FinishReason,
                 ModelId = ModelId