Staging the MEAI 9.4.3 Release

eng/Versions.props

@@ -2,7 +2,7 @@
   <PropertyGroup Label="Version settings">
     <MajorVersion>9</MajorVersion>
     <MinorVersion>4</MinorVersion>
-    <PatchVersion>2</PatchVersion>
+    <PatchVersion>3</PatchVersion>
     <PreReleaseVersionLabel>preview</PreReleaseVersionLabel>
     <PreReleaseVersionIteration>1</PreReleaseVersionIteration>
     <VersionPrefix>$(MajorVersion).$(MinorVersion).$(PatchVersion)</VersionPrefix>

eng/packages/TestOnly.props

@@ -18,6 +18,7 @@
     <PackageVersion Include="Moq.AutoMock" Version="3.1.0" />
     <PackageVersion Include="Moq" Version="4.18.4" />
     <PackageVersion Include="OpenTelemetry.Exporter.InMemory" Version="1.9.0" />
+    <PackageVersion Include="PdfPig" Version="0.1.10-alpha-20250203-fdb88" />
     <PackageVersion Include="Polly.Testing" Version="8.4.2" />
     <PackageVersion Include="StrongNamer" Version="0.2.5" />
     <PackageVersion Include="System.Configuration.ConfigurationManager" Version="$(SystemConfigurationConfigurationManagerVersion)" />

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

@@ -1,5 +1,14 @@
 # Release History
 
+## 9.4.0-preview.1.25207.5
+
+- Added `ErrorContent` and `TextReasoningContent`.
+- Added `MessageId` to `ChatMessage` and `ChatResponseUpdate`.
+- Added `AIFunctionArguments`, changing `AIFunction.InvokeAsync` to accept one and to return a `ValueTask`.
+- Updated `AIJsonUtilities`'s schema generation to not use `default` when `RequireAllProperties` is set to `true`.
+- Added `ISpeechToTextClient` and supporting types.
+- Fixed several issues related to Native AOT support.
+
 ## 9.3.0-preview.1.25161.3
 
 - Changed `IChatClient.GetResponseAsync` and `IChatClient.GetStreamingResponseAsync` to accept an `IEnumerable<ChatMessage>` rather than an `IList<ChatMessage>`. It is no longer mutated by implementations.

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

@@ -9,8 +9,18 @@ namespace Microsoft.Extensions.AI;
 /// <summary>Represents the options for a chat request.</summary>
 public class ChatOptions
 {
-    /// <summary>Gets or sets an optional identifier used to associate a request with an existing chat thread.</summary>
-    public string? ChatThreadId { get; set; }
+    /// <summary>Gets or sets an optional identifier used to associate a request with an existing conversation.</summary>
+    /// <remarks>This property is obsolete. Use <see cref="ConversationId"/> instead.</remarks>
+    [System.Obsolete("Use ConversationId instead.")]
+    [System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)]
+    public string? ChatThreadId
+    {
+        get => ConversationId;
+        set => ConversationId = value;
+    }
+
+    /// <summary>Gets or sets an optional identifier used to associate a request with an existing conversation.</summary>
+    public string? ConversationId { get; set; }
 
     /// <summary>Gets or sets the temperature for generating chat responses.</summary>
     /// <remarks>
@@ -83,6 +93,23 @@ public class ChatOptions
     /// </remarks>
     public IList<string>? StopSequences { get; set; }
 
+    /// <summary>
+    /// Gets or sets a flag to indicate whether a single response is allowed to include multiple tool calls.
+    /// If <see langword="false"/>, the <see cref="IChatClient"/> is asked to return a maximum of one tool call per request.
+    /// If <see langword="true"/>, there is no limit.
+    /// If <see langword="null"/>, the provider may select its own default.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// When used with function calling middleware, this does not affect the ability to perform multiple function calls in sequence.
+    /// It only affects the number of function calls within a single iteration of the function calling loop.
+    /// </para>
+    /// <para>
+    /// The underlying provider is not guaranteed to support or honor this flag. For example it may choose to ignore it and return multiple tool calls regardless.
+    /// </para>
+    /// </remarks>
+    public bool? AllowMultipleToolCalls { get; set; }
+
     /// <summary>Gets or sets the tool mode for the chat request.</summary>
     /// <remarks>The default value is <see langword="null"/>, which is treated the same as <see cref="ChatToolMode.Auto"/>.</remarks>
     public ChatToolMode? ToolMode { get; set; }
@@ -105,7 +132,7 @@ public virtual ChatOptions Clone()
     {
         ChatOptions options = new()
         {
-            ChatThreadId = ChatThreadId,
+            ConversationId = ConversationId,
             Temperature = Temperature,
             MaxOutputTokens = MaxOutputTokens,
             TopP = TopP,
@@ -115,6 +142,7 @@ public virtual ChatOptions Clone()
             Seed = Seed,
             ResponseFormat = ResponseFormat,
             ModelId = ModelId,
+            AllowMultipleToolCalls = AllowMultipleToolCalls,
             ToolMode = ToolMode,
             AdditionalProperties = AdditionalProperties?.Clone(),
         };

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

@@ -63,15 +63,36 @@ public IList<ChatMessage> Messages
     /// <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 response.</summary>
+    /// <summary>Gets or sets an identifier for the state of the conversation.</summary>
     /// <remarks>
-    /// Some <see cref="IChatClient"/> implementations are capable of storing the state for a chat thread, such that
+    /// Some <see cref="IChatClient"/> implementations are capable of storing the state for a conversation, such that
     /// 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>messages</c> parameter.
+    /// and it should be used in a subsequent <see cref="ChatOptions.ConversationId"/> instead of supplying the same messages
+    /// (and this <see cref="ChatResponse"/>'s message) as part of the <c>messages</c> parameter. Note that the value may
+    /// or may not differ on every response, depending on whether the underlying provider uses a fixed ID for each conversation
+    /// or updates it for each message.
     /// </remarks>
-    public string? ChatThreadId { get; set; }
+    /// <remarks>This method is obsolete. Use <see cref="ConversationId"/> instead.</remarks>
+    [Obsolete("Use ConversationId instead.")]
+    [System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)]
+    public string? ChatThreadId
+    {
+        get => ConversationId;
+        set => ConversationId = value;
+    }
+
+    /// <summary>Gets or sets an identifier for the state of the conversation.</summary>
+    /// <remarks>
+    /// Some <see cref="IChatClient"/> implementations are capable of storing the state for a conversation, such that
+    /// 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.ConversationId"/> instead of supplying the same messages
+    /// (and this <see cref="ChatResponse"/>'s message) as part of the <c>messages</c> parameter. Note that the value may
+    /// or may not differ on every response, depending on whether the underlying provider uses a fixed ID for each conversation
+    /// or updates it for each message.
+    /// </remarks>
+    public string? ConversationId { get; set; }
 
     /// <summary>Gets or sets the model ID used in the creation of the chat response.</summary>
     public string? ModelId { get; set; }
@@ -127,7 +148,7 @@ public ChatResponseUpdate[] ToChatResponseUpdates()
             ChatMessage message = _messages![i];
             updates[i] = new ChatResponseUpdate
             {
-                ChatThreadId = ChatThreadId,
+                ConversationId = ConversationId,
 
                 AdditionalProperties = message.AdditionalProperties,
                 AuthorName = message.AuthorName,

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

@@ -320,9 +320,9 @@ private static void ProcessUpdate(ChatResponseUpdate update, ChatResponse respon
             response.ResponseId = update.ResponseId;
         }
 
-        if (update.ChatThreadId is not null)
+        if (update.ConversationId is not null)
         {
-            response.ChatThreadId = update.ChatThreadId;
+            response.ConversationId = update.ConversationId;
         }
 
         if (update.CreatedAt is not null)

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

@@ -116,15 +116,34 @@ public IList<AIContent> Contents
     /// </remarks>
     public string? MessageId { get; set; }
 
-    /// <summary>Gets or sets the chat thread ID associated with the chat response of which this update is a part.</summary>
+    /// <summary>Gets or sets an identifier for the state of the conversation of which this update is a part.</summary>
     /// <remarks>
-    /// Some <see cref="IChatClient"/> implementations are capable of storing the state for a chat thread, such that
+    /// Some <see cref="IChatClient"/> implementations are capable of storing the state for a conversation, such that
     /// the input messages supplied to <see cref="IChatClient.GetStreamingResponseAsync"/> 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 streaming message) as part of the <c>messages</c> parameter.
+    /// and it should be used in a subsequent <see cref="ChatOptions.ConversationId"/> instead of supplying the same messages
+    /// (and this streaming message) as part of the <c>messages</c> parameter. Note that the value may or may not differ on every
+    /// response, depending on whether the underlying provider uses a fixed ID for each conversation or updates it for each message.
     /// </remarks>
-    public string? ChatThreadId { get; set; }
+    /// <remarks>This method is obsolete. Use <see cref="ConversationId"/> instead.</remarks>
+    [Obsolete("Use ConversationId instead.")]
+    [System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)]
+    public string? ChatThreadId
+    {
+        get => ConversationId;
+        set => ConversationId = value;
+    }
+
+    /// <summary>Gets or sets an identifier for the state of the conversation of which this update is a part.</summary>
+    /// <remarks>
+    /// Some <see cref="IChatClient"/> implementations are capable of storing the state for a conversation, such that
+    /// the input messages supplied to <see cref="IChatClient.GetStreamingResponseAsync"/> 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.ConversationId"/> instead of supplying the same messages
+    /// (and this streaming message) as part of the <c>messages</c> parameter. Note that the value may or may not differ on every
+    /// response, depending on whether the underlying provider uses a fixed ID for each conversation or updates it for each message.
+    /// </remarks>
+    public string? ConversationId { get; set; }
 
     /// <summary>Gets or sets a timestamp for the response update.</summary>
     public DateTimeOffset? CreatedAt { get; set; }

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

@@ -5,7 +5,7 @@
 
 namespace Microsoft.Extensions.AI;
 
-/// <summary>Provides a base class for all content used with AI services.</summary>
+/// <summary>Represents content used by AI services.</summary>
 [JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")]
 [JsonDerivedType(typeof(DataContent), typeDiscriminator: "data")]
 [JsonDerivedType(typeof(ErrorContent), typeDiscriminator: "error")]
@@ -20,15 +20,15 @@ public class AIContent
     /// <summary>
     /// Initializes a new instance of the <see cref="AIContent"/> class.
     /// </summary>
-    protected AIContent()
+    public AIContent()
     {
     }
 
     /// <summary>Gets or sets the raw representation of the content from an underlying implementation.</summary>
     /// <remarks>
     /// If an <see cref="AIContent"/> 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.
+    /// for enabling a consumer to access the underlying object model, if needed.
     /// </remarks>
     [JsonIgnore]
     public object? RawRepresentation { get; set; }

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

@@ -99,16 +99,45 @@ public static TService GetRequiredService<TService>(
     /// <exception cref="ArgumentNullException"><paramref name="value"/> is <see langword="null"/>.</exception>
     /// <exception cref="InvalidOperationException">The generator did not produce exactly one embedding.</exception>
     /// <remarks>
-    /// This operation is equivalent to using <see cref="GenerateEmbeddingAsync"/> and returning the
+    /// This operation is equivalent to using <see cref="GenerateAsync"/> and returning the
     /// resulting <see cref="Embedding{T}"/>'s <see cref="Embedding{T}.Vector"/> property.
     /// </remarks>
+    /// <remarks>
+    /// This method is obsolete. Use <see cref="GenerateVectorAsync{TInput, TEmbeddingElement}"/> instead.
+    /// </remarks>
+    [Obsolete("Use GenerateVectorAsync<TInput, TEmbeddingElement> instead.")]
+    [System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)]
     public static async Task<ReadOnlyMemory<TEmbeddingElement>> GenerateEmbeddingVectorAsync<TInput, TEmbeddingElement>(
         this IEmbeddingGenerator<TInput, Embedding<TEmbeddingElement>> generator,
         TInput value,
         EmbeddingGenerationOptions? options = null,
         CancellationToken cancellationToken = default)
     {
-        var embedding = await GenerateEmbeddingAsync(generator, value, options, cancellationToken).ConfigureAwait(false);
+        return await GenerateVectorAsync(generator, value, options, cancellationToken).ConfigureAwait(false);
+    }
+
+    /// <summary>Generates an embedding vector from the specified <paramref name="value"/>.</summary>
+    /// <typeparam name="TInput">The type from which embeddings will be generated.</typeparam>
+    /// <typeparam name="TEmbeddingElement">The numeric type of the embedding data.</typeparam>
+    /// <param name="generator">The embedding generator.</param>
+    /// <param name="value">A value from which an embedding will be generated.</param>
+    /// <param name="options">The embedding generation 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 generated embedding for the specified <paramref name="value"/>.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="generator"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentNullException"><paramref name="value"/> is <see langword="null"/>.</exception>
+    /// <exception cref="InvalidOperationException">The generator did not produce exactly one embedding.</exception>
+    /// <remarks>
+    /// This operation is equivalent to using <see cref="GenerateAsync"/> and returning the
+    /// resulting <see cref="Embedding{T}"/>'s <see cref="Embedding{T}.Vector"/> property.
+    /// </remarks>
+    public static async Task<ReadOnlyMemory<TEmbeddingElement>> GenerateVectorAsync<TInput, TEmbeddingElement>(
+        this IEmbeddingGenerator<TInput, Embedding<TEmbeddingElement>> generator,
+        TInput value,
+        EmbeddingGenerationOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        var embedding = await GenerateAsync(generator, value, options, cancellationToken).ConfigureAwait(false);
         return embedding.Vector;
     }
 
@@ -130,12 +159,45 @@ public static async Task<ReadOnlyMemory<TEmbeddingElement>> GenerateEmbeddingVec
     /// collection composed of the single <paramref name="value"/> and then returning the first embedding element from the
     /// resulting <see cref="GeneratedEmbeddings{TEmbedding}"/> collection.
     /// </remarks>
+    /// <remarks>
+    /// This method is obsolete. Use <see cref="GenerateAsync{TInput, TEmbedding}"/> instead.
+    /// </remarks>
+    [Obsolete("Use GenerateAsync<TInput, TEmbedding> instead.")]
+    [System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)]
     public static async Task<TEmbedding> GenerateEmbeddingAsync<TInput, TEmbedding>(
         this IEmbeddingGenerator<TInput, TEmbedding> generator,
         TInput value,
         EmbeddingGenerationOptions? options = null,
         CancellationToken cancellationToken = default)
         where TEmbedding : Embedding
+    {
+        return await GenerateAsync(generator, value, options, cancellationToken).ConfigureAwait(false);
+    }
+
+    /// <summary>Generates an embedding from the specified <paramref name="value"/>.</summary>
+    /// <typeparam name="TInput">The type from which embeddings will be generated.</typeparam>
+    /// <typeparam name="TEmbedding">The type of embedding to generate.</typeparam>
+    /// <param name="generator">The embedding generator.</param>
+    /// <param name="value">A value from which an embedding will be generated.</param>
+    /// <param name="options">The embedding generation 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 generated embedding for the specified <paramref name="value"/>.
+    /// </returns>
+    /// <exception cref="ArgumentNullException"><paramref name="generator"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentNullException"><paramref name="value"/> is <see langword="null"/>.</exception>
+    /// <exception cref="InvalidOperationException">The generator did not produce exactly one embedding.</exception>
+    /// <remarks>
+    /// This operations is equivalent to using <see cref="IEmbeddingGenerator{TInput, TEmbedding}.GenerateAsync"/> with a
+    /// collection composed of the single <paramref name="value"/> and then returning the first embedding element from the
+    /// resulting <see cref="GeneratedEmbeddings{TEmbedding}"/> collection.
+    /// </remarks>
+    public static async Task<TEmbedding> GenerateAsync<TInput, TEmbedding>(
+        this IEmbeddingGenerator<TInput, TEmbedding> generator,
+        TInput value,
+        EmbeddingGenerationOptions? options = null,
+        CancellationToken cancellationToken = default)
+        where TEmbedding : Embedding
     {
         _ = Throw.IfNull(generator);
         _ = Throw.IfNull(value);