From 5282b4cb00ab941bce4421eaa2814c1c02ea3282 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 17 Oct 2025 10:01:03 -0700 Subject: [PATCH 1/3] doc updates --- .../ChatCompletion/ChatOptions.cs | 32 +++++++++---------- .../ChatCompletion/ChatResponse.cs | 13 ++++---- .../ChatCompletion/ChatResponseUpdate.cs | 18 +++++------ .../ChatCompletion/IChatClient.cs | 2 +- .../Embeddings/EmbeddingGenerationOptions.cs | 4 +-- .../Functions/AIFunctionFactoryOptions.cs | 2 +- .../SpeechToText/SpeechToTextOptions.cs | 2 +- .../Tools/AITool.cs | 2 +- 8 files changed, 37 insertions(+), 38 deletions(-) diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs index 1415ae68055..743ed789c67 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs @@ -133,24 +133,24 @@ protected ChatOptions(ChatOptions? other) public IList? StopSequences { get; set; } /// - /// Gets or sets a flag to indicate whether a single response is allowed to include multiple tool calls. - /// If , the is asked to return a maximum of one tool call per request. - /// If , there is no limit. - /// If , the provider may select its own default. + /// Gets or sets a value that indicates whether a single response is allowed to include multiple tool calls. /// + /// + /// for no limit. if the is asked to return a maximum of one tool call per request. If , the provider can select its own default. + /// /// /// /// 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. /// /// - /// 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. + /// The underlying provider is not guaranteed to support or honor this flag. For example it might choose to ignore it and return multiple tool calls regardless. /// /// public bool? AllowMultipleToolCalls { get; set; } /// Gets or sets the tool mode for the chat request. - /// The default value is , which is treated the same as . + /// The default is , which is treated the same as . public ChatToolMode? ToolMode { get; set; } /// Gets or sets the list of tools to include with a chat request. @@ -165,12 +165,12 @@ protected ChatOptions(ChatOptions? other) /// and polled for completion by non-streaming APIs. /// /// - /// When this property is set to true, non-streaming APIs may start a background operation and return an initial + /// When this property is set to true, non-streaming APIs can 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. /// /// - /// When this property is set to true, streaming APIs may also start a background operation and begin streaming + /// When this property is set to true, streaming APIs can 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. @@ -189,10 +189,10 @@ protected ChatOptions(ChatOptions? other) /// This property is used for background responses that can be activated via the /// property if the implementation supports them. /// Streamed background responses, such as those returned by default by , - /// can be resumed if interrupted. This means that a continuation token obtained from the + /// can be resumed if interrupted. This means that a continuation token obtained from the /// 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 , - /// can be polled for completion by obtaining the token from the property + /// can be polled for completion by obtaining the token from the property /// and passing it to this property on subsequent calls to . /// [Experimental("MEAI001")] @@ -203,17 +203,17 @@ protected ChatOptions(ChatOptions? other) /// Gets or sets a callback responsible for creating the raw representation of the chat options from an underlying implementation. /// /// - /// The underlying implementation may have its own representation of options. + /// The underlying implementation might have its own representation of options. /// When or - /// is invoked with a , that implementation may convert the provided options into + /// is invoked with a , that implementation might convert the provided options into /// its own representation in order to use it while performing the operation. For situations where a consumer knows /// which concrete is being used and how it represents options, a new instance of that - /// implementation-specific options type may be returned by this callback, for the - /// implementation to use instead of creating a new instance. Such implementations may mutate the supplied options + /// implementation-specific options type can be returned by this callback for the + /// implementation to use, instead of creating a new instance. Such implementations might mutate the supplied options /// instance further based on other settings supplied on this instance or from other inputs, - /// like the enumerable of s, therefore, it is strongly recommended to not return shared instances + /// like the enumerable of s. Therefore, it is strongly recommended to not return shared instances /// and instead make the callback return a new instance on each call. - /// This is typically used to set an implementation-specific setting that isn't otherwise exposed from the strongly-typed + /// This is typically used to set an implementation-specific setting that isn't otherwise exposed from the strongly typed /// properties on . /// [JsonIgnore] diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatResponse.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatResponse.cs index ea513d2f073..6f7ca4eeda2 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatResponse.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatResponse.cs @@ -12,10 +12,10 @@ namespace Microsoft.Extensions.AI; /// Represents the response to a chat request. /// /// 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 +/// A typical response will contain a single message, however a response might contain multiple messages /// in a variety of scenarios. For example, if automatic function calling is employed, such that a single -/// request to a may actually generate multiple roundtrips to an inner -/// it uses, all of the involved messages may be surfaced as part of the final . +/// request to a might actually generate multiple round-trips to an inner +/// it uses, all of the involved messages might be surfaced as part of the final . /// public class ChatResponse { @@ -69,8 +69,7 @@ public IList Messages /// the input messages supplied to need only be the additional messages beyond /// what's already stored. If this property is non-, it represents an identifier for that state, /// and it should be used in a subsequent instead of supplying the same messages - /// (and this 's message) as part of the messages 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 + /// (and this 's message) as part of the messages parameter. Note that the value might differ on every response, depending on whether the underlying provider uses a fixed ID for each conversation /// or updates it for each message. /// /// Stateless vs. stateful clients. @@ -95,7 +94,7 @@ public IList Messages /// 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 . /// - /// This property should be used in conjunction with to + /// This property should be used in conjunction with to /// continue to poll for the completion of the response. Pass this token to /// on subsequent calls to /// to poll for completion. @@ -121,7 +120,7 @@ public IList Messages public override string ToString() => Text; /// Creates an array of instances that represent this . - /// An array of instances that may be used to represent this . + /// An array of instances that can be used to represent this . public ChatResponseUpdate[] ToChatResponseUpdates() { ChatResponseUpdate? extra = null; diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatResponseUpdate.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatResponseUpdate.cs index 8b24b5c6b19..c4a9f8ba97c 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatResponseUpdate.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatResponseUpdate.cs @@ -22,7 +22,7 @@ namespace Microsoft.Extensions.AI; /// The relationship between and is /// codified in the and /// , which enable bidirectional conversions -/// between the two. Note, however, that the provided conversions may be lossy, for example if multiple +/// between the two. Note, however, that the provided conversions might be lossy, for example, if multiple /// updates all have different objects whereas there's only one slot for /// such an object available in . Similarly, if different /// updates provide different values for properties like , @@ -100,12 +100,12 @@ public IList Contents /// Gets or sets the ID of the message of which this update is a part. /// - /// A single streaming response may be composed of multiple messages, each of which may be represented + /// A single streaming response might be composed of multiple messages, each of which might be represented /// by multiple updates. This property is used to group those updates together into messages. /// - /// Some providers may consider streaming responses to be a single message, and in that case - /// the value of this property may be the same as the response ID. - /// + /// Some providers might consider streaming responses to be a single message, and in that case + /// the value of this property might be the same as the response ID. + /// /// This value is used when /// groups instances into instances. /// The value must be unique to each call to the underlying provider, and must be shared by @@ -119,7 +119,7 @@ public IList Contents /// the input messages supplied to need only be the additional messages beyond /// what's already stored. If this property is non-, it represents an identifier for that state, /// and it should be used in a subsequent instead of supplying the same messages - /// (and this streaming message) as part of the messages parameter. Note that the value may or may not differ on every + /// (and this streaming message) as part of the messages parameter. Note that the value might differ on every /// response, depending on whether the underlying provider uses a fixed ID for each conversation or updates it for each message. /// public string? ConversationId { get; set; } @@ -138,9 +138,9 @@ public IList Contents /// Gets or sets the continuation token for resuming the streamed chat response of which this update is a part. /// - /// implementations that support background responses will return - /// a continuation token on each update if background responses are allowed in - /// except of the last update, for which the token will be . + /// implementations that support background responses return + /// a continuation token on each update if background responses are allowed in . + /// However, for the last update, the token will be . /// /// This property should be used for stream resumption, where the continuation token of the latest received update should be /// passed to on subsequent calls to diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/IChatClient.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/IChatClient.cs index 570eb7ef497..f4e0141ac94 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/IChatClient.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/IChatClient.cs @@ -62,7 +62,7 @@ IAsyncEnumerable GetStreamingResponseAsync( /// The found object, otherwise . /// is . /// - /// The purpose of this method is to allow for the retrieval of strongly-typed services that might be provided by the , + /// The purpose of this method is to allow for the retrieval of strongly typed services that might be provided by the , /// including itself or any services it might be wrapping. For example, to access the for the instance, /// may be used to request it. /// diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Embeddings/EmbeddingGenerationOptions.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Embeddings/EmbeddingGenerationOptions.cs index db547a7b8fa..e5d8459351e 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Embeddings/EmbeddingGenerationOptions.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Embeddings/EmbeddingGenerationOptions.cs @@ -55,7 +55,7 @@ public int? Dimensions /// /// /// The underlying implementation may have its own representation of options. - /// When + /// When /// is invoked with an , that implementation may convert the provided options into /// its own representation in order to use it while performing the operation. For situations where a consumer knows /// which concrete is being used and how it represents options, a new instance of that @@ -63,7 +63,7 @@ public int? Dimensions /// implementation to use instead of creating a new instance. Such implementations may mutate the supplied options /// instance further based on other settings supplied on this instance or from other inputs, /// therefore, it is strongly recommended to not return shared instances and instead make the callback return a new instance on each call. - /// This is typically used to set an implementation-specific setting that isn't otherwise exposed from the strongly-typed + /// This is typically used to set an implementation-specific setting that isn't otherwise exposed from the strongly typed /// properties on . /// [JsonIgnore] diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Functions/AIFunctionFactoryOptions.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Functions/AIFunctionFactoryOptions.cs index 2bb9841a65e..ab49eeb7f24 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Functions/AIFunctionFactoryOptions.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Functions/AIFunctionFactoryOptions.cs @@ -90,7 +90,7 @@ public AIFunctionFactoryOptions() /// -returning methods). /// /// - /// Methods strongly-typed to return types of , , , + /// Methods strongly typed to return types of , , , /// and are special-cased. For methods typed to return or , /// will be invoked with the value after the returned task has successfully completed. /// For methods typed to return or , the delegate will be invoked with the diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/SpeechToText/SpeechToTextOptions.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/SpeechToText/SpeechToTextOptions.cs index f57dbe2dd3f..0e93a9bb1af 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/SpeechToText/SpeechToTextOptions.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/SpeechToText/SpeechToTextOptions.cs @@ -60,7 +60,7 @@ protected SpeechToTextOptions(SpeechToTextOptions? other) /// implementation to use instead of creating a new instance. Such implementations may mutate the supplied options /// instance further based on other settings supplied on this instance or from other inputs, /// therefore, it is strongly recommended to not return shared instances and instead make the callback return a new instance on each call. - /// This is typically used to set an implementation-specific setting that isn't otherwise exposed from the strongly-typed + /// This is typically used to set an implementation-specific setting that isn't otherwise exposed from the strongly typed /// properties on . /// [JsonIgnore] diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Tools/AITool.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Tools/AITool.cs index d8551fe6586..366dc66f77c 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Tools/AITool.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Tools/AITool.cs @@ -37,7 +37,7 @@ protected AITool() /// The found object, otherwise . /// is . /// - /// The purpose of this method is to allow for the retrieval of strongly-typed services that might be provided by the , + /// The purpose of this method is to allow for the retrieval of strongly typed services that might be provided by the , /// including itself or any services it might be wrapping. /// public virtual object? GetService(Type serviceType, object? serviceKey = null) From e5872268644f1f9a818ba059ad0e16eba7b83004 Mon Sep 17 00:00:00 2001 From: Stephen Toub Date: Mon, 20 Oct 2025 19:07:11 -0400 Subject: [PATCH 2/3] Update src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- .../ChatCompletion/ChatOptions.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs index 743ed789c67..9f9ef7009b0 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs @@ -170,7 +170,7 @@ protected ChatOptions(ChatOptions? other) /// the continuation token to get the final result of the operation. /// /// - /// When this property is set to true, streaming APIs can also start a background operation and begin streaming + /// When this property is set to , streaming APIs are also permitted to 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. From 308e72950d8efad448791f035e4d4510ea18a67c Mon Sep 17 00:00:00 2001 From: Stephen Toub Date: Mon, 20 Oct 2025 19:07:36 -0400 Subject: [PATCH 3/3] Update src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- .../ChatCompletion/ChatOptions.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs index 9f9ef7009b0..738f724dcd2 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs @@ -165,7 +165,7 @@ protected ChatOptions(ChatOptions? other) /// and polled for completion by non-streaming APIs. /// /// - /// When this property is set to true, non-streaming APIs can start a background operation and return an initial + /// When this property is set to , non-streaming APIs have permission to 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. ///