Address some M.E.AI API feedback (#5860)

- Remove DataContent.ContainsData. While ContainsData could be used to avoid lazily-instantiating a `ReadOnlyMemory<byte>` from a data URI, in all cases examined ContainsData was being used to guard accessing Data, in which case Data.HasValue is sufficient.
- Make ToolMode optional. We'd previously said that an implementation could use null to imply None if it wanted, but with this being optional we'd want null to be the same as auto, so I added in an explicit null options. That matches as well with what various other client libs do.
- Remove IChatClient/IEmbeddingGenerator.Metadata. GetService can be used instead, reducing what an implementer must implement and what's exposed to a consumer.
- Add Complete{Streaming}Async for a single message. We have such accelerators in other places but not here, and it provides a natural grow-up from string to ChatMessage to `IList<ChatMessage>`.
- Change UsageDetails.XxTokenCount properties from int? to long?. The AdditionalCounts is already based on longs, and in theory the token counts could exceed int, especially in a situation where UsageData is being used to sum many other call data.
- Rename GenerateEmbeddingVectorAsync's TEmbedding to TEmbeddingElement. Everywhere else TEmbedding is used where it represents an Embedding, but here it represents a numerical element in an embedding vector.
- Remove setters on FunctionCall/ResultContent for required ctor parameters. Having those setters goes against .NET design guidelines.
- Remove FunctionResultContent.Name. It's unnecessary and is actually causing us to do more work in places.

Author: stephentoub

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

@@ -42,7 +42,25 @@ public static Task<ChatCompletion> CompleteAsync(
         _ = Throw.IfNull(client);
         _ = Throw.IfNull(chatMessage);
 
-        return client.CompleteAsync([new ChatMessage(ChatRole.User, chatMessage)], options, cancellationToken);
+        return client.CompleteAsync(new ChatMessage(ChatRole.User, chatMessage), options, cancellationToken);
+    }
+
+    /// <summary>Sends a chat message to the model 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(
+        this IChatClient client,
+        ChatMessage chatMessage,
+        ChatOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        _ = Throw.IfNull(client);
+        _ = Throw.IfNull(chatMessage);
+
+        return client.CompleteAsync([chatMessage], options, cancellationToken);
     }
 
     /// <summary>Sends a user chat text message to the model and streams the response messages.</summary>
@@ -60,6 +78,24 @@ public static IAsyncEnumerable<StreamingChatCompletionUpdate> CompleteStreamingA
         _ = Throw.IfNull(client);
         _ = Throw.IfNull(chatMessage);
 
-        return client.CompleteStreamingAsync([new ChatMessage(ChatRole.User, chatMessage)], options, cancellationToken);
+        return client.CompleteStreamingAsync(new ChatMessage(ChatRole.User, chatMessage), options, cancellationToken);
+    }
+
+    /// <summary>Sends a chat message to the model 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(
+        this IChatClient client,
+        ChatMessage chatMessage,
+        ChatOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        _ = Throw.IfNull(client);
+        _ = Throw.IfNull(chatMessage);
+
+        return client.CompleteStreamingAsync([chatMessage], options, cancellationToken);
     }
 }

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

@@ -51,7 +51,8 @@ public class ChatOptions
     public IList<string>? StopSequences { get; set; }
 
     /// <summary>Gets or sets the tool mode for the chat request.</summary>
-    public ChatToolMode ToolMode { get; set; } = ChatToolMode.Auto;
+    /// <remarks>The default value is <see langword="null"/>, which is treated the same as <see cref="ChatToolMode.Auto"/>.</remarks>
+    public ChatToolMode? ToolMode { get; set; }
 
     /// <summary>Gets or sets the list of tools to include with a chat request.</summary>
     [JsonIgnore]

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

@@ -9,10 +9,11 @@ namespace Microsoft.Extensions.AI;
 /// Describes how tools should be selected by a <see cref="IChatClient"/>.
 /// </summary>
 /// <remarks>
-/// The predefined values <see cref="Auto" /> and <see cref="RequireAny"/> are provided.
+/// The predefined values <see cref="Auto" />, <see cref="None"/>, and <see cref="RequireAny"/> are provided.
 /// To nominate a specific function, use <see cref="RequireSpecific(string)"/>.
 /// </remarks>
 [JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")]
+[JsonDerivedType(typeof(NoneChatToolMode), typeDiscriminator: "none")]
 [JsonDerivedType(typeof(AutoChatToolMode), typeDiscriminator: "auto")]
 [JsonDerivedType(typeof(RequiredChatToolMode), typeDiscriminator: "required")]
 #pragma warning disable CA1052 // Static holder types should be Static or NotInheritable
@@ -32,7 +33,19 @@ private protected ChatToolMode()
     /// <see cref="ChatOptions.Tools"/> can contain zero or more <see cref="AITool"/>
     /// instances, and the <see cref="IChatClient"/> is free to invoke zero or more of them.
     /// </remarks>
-    public static AutoChatToolMode Auto { get; } = new AutoChatToolMode();
+    public static AutoChatToolMode Auto { get; } = new();
+
+    /// <summary>
+    /// Gets a predefined <see cref="ChatToolMode"/> indicating that tool usage is unsupported.
+    /// </summary>
+    /// <remarks>
+    /// <see cref="ChatOptions.Tools"/> can contain zero or more <see cref="AITool"/>
+    /// instances, but the <see cref="IChatClient"/> should not request the invocation of
+    /// any of them. This can be used when the <see cref="IChatClient"/> should know about
+    /// tools in order to provide information about them or plan out their usage, but should
+    /// not request the invocation of any of them.
+    /// </remarks>
+    public static NoneChatToolMode None { get; } = new();
 
     /// <summary>
     /// Gets a predefined <see cref="ChatToolMode"/> indicating that tool usage is required,

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

@@ -37,19 +37,6 @@ public void Dispose()
     /// <summary>Gets the inner <see cref="IChatClient" />.</summary>
     protected IChatClient InnerClient { get; }
 
-    /// <summary>Provides a mechanism for releasing unmanaged resources.</summary>
-    /// <param name="disposing"><see langword="true"/> if being called from <see cref="Dispose()"/>; otherwise, <see langword="false"/>.</param>
-    protected virtual void Dispose(bool disposing)
-    {
-        if (disposing)
-        {
-            InnerClient.Dispose();
-        }
-    }
-
-    /// <inheritdoc />
-    public virtual ChatClientMetadata Metadata => InnerClient.Metadata;
-
     /// <inheritdoc />
     public virtual Task<ChatCompletion> CompleteAsync(IList<ChatMessage> chatMessages, ChatOptions? options = null, CancellationToken cancellationToken = default)
     {
@@ -72,4 +59,14 @@ public virtual IAsyncEnumerable<StreamingChatCompletionUpdate> CompleteStreaming
             serviceKey is null && serviceType.IsInstanceOfType(this) ? this :
             InnerClient.GetService(serviceType, serviceKey);
     }
+
+    /// <summary>Provides a mechanism for releasing unmanaged resources.</summary>
+    /// <param name="disposing"><see langword="true"/> if being called from <see cref="Dispose()"/>; otherwise, <see langword="false"/>.</param>
+    protected virtual void Dispose(bool disposing)
+    {
+        if (disposing)
+        {
+            InnerClient.Dispose();
+        }
+    }
 }

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

@@ -53,9 +53,6 @@ IAsyncEnumerable<StreamingChatCompletionUpdate> CompleteStreamingAsync(
         ChatOptions? options = null,
         CancellationToken cancellationToken = default);
 
-    /// <summary>Gets metadata that describes the <see cref="IChatClient"/>.</summary>
-    ChatClientMetadata Metadata { get; }
-
     /// <summary>Asks the <see cref="IChatClient"/> for an object of the specified type <paramref name="serviceType"/>.</summary>
     /// <param name="serviceType">The type of object being requested.</param>
     /// <param name="serviceKey">An optional key that can be used to help identify the target service.</param>

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

@@ -0,0 +1,28 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Diagnostics;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Indicates that an <see cref="IChatClient"/> should not request the invocation of any tools.
+/// </summary>
+/// <remarks>
+/// Use <see cref="ChatToolMode.None"/> to get an instance of <see cref="NoneChatToolMode"/>.
+/// </remarks>
+[DebuggerDisplay("None")]
+public sealed class NoneChatToolMode : ChatToolMode
+{
+    /// <summary>Initializes a new instance of the <see cref="NoneChatToolMode"/> class.</summary>
+    /// <remarks>Use <see cref="ChatToolMode.None"/> to get an instance of <see cref="NoneChatToolMode"/>.</remarks>
+    public NoneChatToolMode()
+    {
+    } // must exist in support of polymorphic deserialization of a ChatToolMode
+
+    /// <inheritdoc/>
+    public override bool Equals(object? obj) => obj is NoneChatToolMode;
+
+    /// <inheritdoc/>
+    public override int GetHashCode() => typeof(NoneChatToolMode).GetHashCode();
+}

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

@@ -172,22 +172,13 @@ public string Uri
     [JsonPropertyOrder(1)]
     public string? MediaType { get; private set; }
 
-    /// <summary>
-    /// Gets a value indicating whether the content contains data rather than only being a reference to data.
-    /// </summary>
-    /// <remarks>
-    /// If the instance is constructed from a <see cref="ReadOnlyMemory{Byte}"/> or from a data URI, this property returns <see langword="true"/>,
-    /// as the instance actually contains all of the data it represents. If, however, the instance was constructed from another form of URI, one
-    /// that simply references where the data can be found but doesn't actually contain the data, this property returns <see langword="false"/>.
-    /// </remarks>
-    [MemberNotNullWhen(true, nameof(Data))]
-    [JsonIgnore]
-    public bool ContainsData => _dataUri is not null || _data is not null;
-
     /// <summary>Gets the data represented by this instance.</summary>
     /// <remarks>
-    /// If <see cref="ContainsData"/> is <see langword="true" />, this property returns the represented data.
-    /// If <see cref="ContainsData"/> is <see langword="false" />, this property returns <see langword="null" />.
+    /// If the instance was constructed from a <see cref="ReadOnlyMemory{Byte}"/>, this property returns that data.
+    /// If the instance was constructed from a data URI, this property the data contained within the data URI.
+    /// If, however, the instance was constructed from another form of URI, one that simply references where the
+    /// data can be found but doesn't actually contain the data, this property returns <see langword="null"/>;
+    /// no attempt is made to retrieve the data from that URI.
     /// </remarks>
     [JsonIgnore]
     public ReadOnlyMemory<byte>? Data

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

@@ -25,20 +25,20 @@ public sealed class FunctionCallContent : AIContent
     [JsonConstructor]
     public FunctionCallContent(string callId, string name, IDictionary<string, object?>? arguments = null)
     {
+        CallId = Throw.IfNull(callId);
         Name = Throw.IfNull(name);
-        CallId = callId;
         Arguments = arguments;
     }
 
     /// <summary>
-    /// Gets or sets the function call ID.
+    /// Gets the function call ID.
     /// </summary>
-    public string CallId { get; set; }
+    public string CallId { get; }
 
     /// <summary>
-    /// Gets or sets the name of the function requested.
+    /// Gets the name of the function requested.
     /// </summary>
-    public string Name { get; set; }
+    public string Name { get; }
 
     /// <summary>
     /// Gets or sets the arguments requested to be provided to the function.

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

@@ -19,33 +19,26 @@ public sealed class FunctionResultContent : AIContent
     /// Initializes a new instance of the <see cref="FunctionResultContent"/> class.
     /// </summary>
     /// <param name="callId">The function call ID for which this is the result.</param>
-    /// <param name="name">The function name that produced the result.</param>
     /// <param name="result">
     /// <see langword="null"/> if the function returned <see langword="null"/> or was void-returning
     /// and thus had no result, or if the function call failed. Typically, however, to provide meaningfully representative
     /// information to an AI service, a human-readable representation of those conditions should be supplied.
     /// </param>
     [JsonConstructor]
-    public FunctionResultContent(string callId, string name, object? result)
+    public FunctionResultContent(string callId, object? result)
     {
         CallId = Throw.IfNull(callId);
-        Name = Throw.IfNull(name);
         Result = result;
     }
 
     /// <summary>
-    /// Gets or sets the ID of the function call for which this is the result.
+    /// Gets the ID of the function call for which this is the result.
     /// </summary>
     /// <remarks>
     /// If this is the result for a <see cref="FunctionCallContent"/>, this property should contain the same
     /// <see cref="FunctionCallContent.CallId"/> value.
     /// </remarks>
-    public string CallId { get; set; }
-
-    /// <summary>
-    /// Gets or sets the name of the function that was called.
-    /// </summary>
-    public string Name { get; set; }
+    public string CallId { get; }
 
     /// <summary>
     /// Gets or sets the result of the function call, or a generic error message if the function call failed.

src/Libraries/Microsoft.Extensions.AI.Abstractions/Embeddings/DelegatingEmbeddingGenerator.cs

@@ -40,20 +40,6 @@ public void Dispose()
         GC.SuppressFinalize(this);
     }
 
-    /// <summary>Provides a mechanism for releasing unmanaged resources.</summary>
-    /// <param name="disposing"><see langword="true"/> if being called from <see cref="Dispose()"/>; otherwise, <see langword="false"/>.</param>
-    protected virtual void Dispose(bool disposing)
-    {
-        if (disposing)
-        {
-            InnerGenerator.Dispose();
-        }
-    }
-
-    /// <inheritdoc />
-    public virtual EmbeddingGeneratorMetadata Metadata =>
-        InnerGenerator.Metadata;
-
     /// <inheritdoc />
     public virtual Task<GeneratedEmbeddings<TEmbedding>> GenerateAsync(IEnumerable<TInput> values, EmbeddingGenerationOptions? options = null, CancellationToken cancellationToken = default) =>
         InnerGenerator.GenerateAsync(values, options, cancellationToken);
@@ -68,4 +54,14 @@ public virtual Task<GeneratedEmbeddings<TEmbedding>> GenerateAsync(IEnumerable<T
             serviceKey is null && serviceType.IsInstanceOfType(this) ? this :
             InnerGenerator.GetService(serviceType, serviceKey);
     }
+
+    /// <summary>Provides a mechanism for releasing unmanaged resources.</summary>
+    /// <param name="disposing"><see langword="true"/> if being called from <see cref="Dispose()"/>; otherwise, <see langword="false"/>.</param>
+    protected virtual void Dispose(bool disposing)
+    {
+        if (disposing)
+        {
+            InnerGenerator.Dispose();
+        }
+    }
 }