diff --git a/src/Generators/Shared/RoslynExtensions.cs b/src/Generators/Shared/RoslynExtensions.cs index a4b9a2ec65d..82860a09f59 100644 --- a/src/Generators/Shared/RoslynExtensions.cs +++ b/src/Generators/Shared/RoslynExtensions.cs @@ -38,7 +38,7 @@ internal static class RoslynExtensions /// /// /// The to consider for analysis. - /// The fully-qualified metadata type name to find. + /// The fully qualified metadata type name to find. /// The symbol to use for code analysis; otherwise, . // Copied from: https://github.com/dotnet/roslyn/blob/af7b0ebe2b0ed5c335a928626c25620566372dd1/src/Workspaces/SharedUtilitiesAndExtensions/Compiler/Core/Extensions/CompilationExtensions.cs public static INamedTypeSymbol? GetBestTypeByMetadataName(this Compilation compilation, string fullyQualifiedMetadataName) @@ -94,7 +94,7 @@ internal static class RoslynExtensions /// /// A thin wrapper over , - /// but taking the type itself rather than the fully-qualified metadata type name. + /// but taking the type itself rather than the fully qualified metadata type name. /// /// The to consider for analysis. /// The type to find. diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/AITool.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/AITool.cs index 0cdcd60e63e..ebbc6751c04 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/AITool.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/AITool.cs @@ -3,7 +3,7 @@ namespace Microsoft.Extensions.AI; -/// Represents a tool that may be specified to an AI service. +/// Represents a tool that can be specified to an AI service. public class AITool { /// Initializes a new instance of the class. diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatClientExtensions.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatClientExtensions.cs index 9e2019d9e52..655b9f3a281 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatClientExtensions.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatClientExtensions.cs @@ -14,10 +14,10 @@ public static class ChatClientExtensions /// Asks the for an object of type . /// The type of the object to be retrieved. /// The client. - /// An optional key that may be used to help identify the target service. + /// An optional key that can be used to help identify the target service. /// The found object, otherwise . /// - /// The purpose of this method is to allow for the retrieval of strongly-typed services that may be provided by the , + /// The purpose of this method is to allow for the retrieval of strongly typed services that may be provided by the , /// including itself or any services it might be wrapping. /// public static TService? GetService(this IChatClient client, object? serviceKey = null) diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatClientMetadata.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatClientMetadata.cs index b98455daf2a..d21d3b20585 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatClientMetadata.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatClientMetadata.cs @@ -11,7 +11,7 @@ public class ChatClientMetadata /// Initializes a new instance of the class. /// The name of the chat completion provider, if applicable. /// The URL for accessing the chat completion provider, if applicable. - /// The id of the chat completion model used, if applicable. + /// The ID of the chat completion model used, if applicable. public ChatClientMetadata(string? providerName = null, Uri? providerUri = null, string? modelId = null) { ModelId = modelId; @@ -25,7 +25,7 @@ public ChatClientMetadata(string? providerName = null, Uri? providerUri = null, /// Gets the URL for accessing the chat completion provider. public Uri? ProviderUri { get; } - /// Gets the id of the model used by this chat completion provider. - /// This may be null if either the name is unknown or there are multiple possible models associated with this instance. + /// Gets the ID of the model used by this chat completion provider. + /// This value can be null if either the name is unknown or there are multiple possible models associated with this instance. public string? ModelId { get; } } diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatCompletion.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatCompletion.cs index 0d3d28bd86b..89182e26165 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatCompletion.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatCompletion.cs @@ -40,7 +40,7 @@ public IList Choices /// Gets the chat completion message. /// /// If there are multiple choices, this property returns the first choice. - /// If is empty, this will throw. Use to access all choices directly."/>. + /// If is empty, this property will throw. Use to access all choices directly. /// [JsonIgnore] public ChatMessage Message diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatFinishReason.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatFinishReason.cs index 08a5630c51b..5ccd99af718 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatFinishReason.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatFinishReason.cs @@ -42,9 +42,9 @@ public ChatFinishReason(string value) /// /// Compares two instances. /// - /// Left argument of the comparison. - /// Right argument of the comparison. - /// when equal, otherwise. + /// The left argument of the comparison. + /// The right argument of the comparison. + /// if the two instances are equal; if they aren't equal. public static bool operator ==(ChatFinishReason left, ChatFinishReason right) { return left.Equals(right); @@ -53,9 +53,9 @@ public ChatFinishReason(string value) /// /// Compares two instances. /// - /// Left argument of the comparison. - /// Right argument of the comparison. - /// when not equal, otherwise. + /// The left argument of the comparison. + /// The right argument of the comparison. + /// if the two instances aren't equal; if they are equal. public static bool operator !=(ChatFinishReason left, ChatFinishReason right) { return !(left == right); diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatMessage.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatMessage.cs index 4fdb138b615..ccbc1cae97b 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatMessage.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatMessage.cs @@ -55,7 +55,7 @@ public string? AuthorName /// /// /// If there is no instance in , then the getter returns , - /// and the setter will add a new instance with the provided value. + /// and the setter adds a new instance with the provided value. /// [JsonIgnore] public string? Text diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs index 0a4f6f58296..63ccb69031a 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs @@ -35,12 +35,12 @@ public class ChatOptions /// /// /// If null, no response format is specified and the client will use its default. - /// This may be set to to specify that the response should be unstructured text, + /// This property can be set to to specify that the response should be unstructured text, /// to to specify that the response should be structured JSON data, or /// an instance of constructed with a specific JSON schema to request that the /// response be structured JSON data according to that schema. It is up to the client implementation if or how /// to honor the request. If the client implementation doesn't recognize the specific kind of , - /// it may be ignored. + /// it can be ignored. /// public ChatResponseFormat? ResponseFormat { get; set; } diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatResponseFormat.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatResponseFormat.cs index 6f1574fe400..006acfe835c 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatResponseFormat.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatResponseFormat.cs @@ -29,7 +29,7 @@ private protected ChatResponseFormat() /// Creates a representing structured JSON data with the specified schema. /// The JSON schema. - /// An optional name of the schema, e.g. if the schema represents a particular class, this could be the name of the class. + /// An optional name of the schema. For example, if the schema represents a particular class, this could be the name of the class. /// An optional description of the schema. /// The instance. public static ChatResponseFormatJson ForJsonSchema( diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatRole.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatRole.cs index f898bb58892..0b5f72adfa5 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatRole.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatRole.cs @@ -32,7 +32,7 @@ namespace Microsoft.Extensions.AI; /// Gets the value associated with this . /// /// - /// The value is what will be serialized into the "role" message field of the Chat Message format. + /// The value will be serialized into the "role" message field of the Chat Message format. /// public string Value { get; } @@ -50,9 +50,9 @@ public ChatRole(string value) /// Returns a value indicating whether two instances are equivalent, as determined by a /// case-insensitive comparison of their values. /// - /// the first instance to compare. - /// the second instance to compare. - /// true if left and right are both null or have equivalent values; false otherwise. + /// The first instance to compare. + /// The second instance to compare. + /// if left and right are both null or have equivalent values; otherwise, . public static bool operator ==(ChatRole left, ChatRole right) { return left.Equals(right); @@ -62,9 +62,9 @@ public ChatRole(string value) /// Returns a value indicating whether two instances are not equivalent, as determined by a /// case-insensitive comparison of their values. /// - /// the first instance to compare. - /// the second instance to compare. - /// false if left and right are both null or have equivalent values; true otherwise. + /// The first instance to compare. + /// The second instance to compare. + /// if left and right have different values; if they have equivalent values or are both null. public static bool operator !=(ChatRole left, ChatRole right) { return !(left == right); diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatToolMode.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatToolMode.cs index 27b8c70e804..0e279042abd 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatToolMode.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatToolMode.cs @@ -29,14 +29,14 @@ private protected ChatToolMode() /// Gets a predefined indicating that tool usage is optional. /// /// - /// may contain zero or more + /// can contain zero or more /// instances, and the is free to invoke zero or more of them. /// public static AutoChatToolMode Auto { get; } = new AutoChatToolMode(); /// /// Gets a predefined indicating that tool usage is required, - /// but that any tool may be selected. At least one tool must be provided in . + /// but that any tool can be selected. At least one tool must be provided in . /// public static RequiredChatToolMode RequireAny { get; } = new(requiredFunctionName: null); diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/DelegatingChatClient.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/DelegatingChatClient.cs index d92590bad92..941ffeb722b 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/DelegatingChatClient.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/DelegatingChatClient.cs @@ -38,7 +38,7 @@ public void Dispose() protected IChatClient InnerClient { get; } /// Provides a mechanism for releasing unmanaged resources. - /// true if being called from ; otherwise, false. + /// if being called from ; otherwise, . protected virtual void Dispose(bool disposing) { if (disposing) diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/IChatClient.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/IChatClient.cs index 4e3fd126b37..54e1dd9da98 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/IChatClient.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/IChatClient.cs @@ -15,7 +15,7 @@ namespace Microsoft.Extensions.AI; /// It is expected that all implementations of support being used by multiple requests concurrently. /// /// -/// However, implementations of may mutate the arguments supplied to and +/// However, implementations of might mutate the arguments supplied to and /// , such as by adding additional messages to the messages list or configuring the options /// instance. Thus, consumers of the interface either should avoid using shared instances of these arguments for concurrent /// invocations or should otherwise ensure by construction that no instances are used which might employ @@ -31,8 +31,8 @@ public interface IChatClient : IDisposable /// The to monitor for cancellation requests. The default is . /// The response messages generated by the client. /// - /// The returned messages will not have been added to . However, any intermediate messages generated implicitly - /// by the client, including any messages for roundtrips to the model as part of the implementation of this request, will be included. + /// The returned messages aren't added to . However, any intermediate messages generated implicitly + /// by the client, including any messages for roundtrips to the model as part of the implementation of this request, are included. /// Task CompleteAsync( IList chatMessages, @@ -45,8 +45,8 @@ Task CompleteAsync( /// The to monitor for cancellation requests. The default is . /// The response messages generated by the client. /// - /// The returned messages will not have been added to . However, any intermediate messages generated implicitly - /// by the client, including any messages for roundtrips to the model as part of the implementation of this request, will be included. + /// The returned messages aren't added to . However, any intermediate messages generated implicitly + /// by the client, including any messages for roundtrips to the model as part of the implementation of this request, are included. /// IAsyncEnumerable CompleteStreamingAsync( IList chatMessages, @@ -58,10 +58,10 @@ IAsyncEnumerable CompleteStreamingAsync( /// Asks the for an object of the specified type . /// The type of object being requested. - /// An optional key that may be used to help identify the target service. + /// An optional key that can be used to help identify the target service. /// The found object, otherwise . /// - /// The purpose of this method is to allow for the retrieval of strongly-typed services that may 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. /// object? GetService(Type serviceType, object? serviceKey = null); diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/RequiredChatToolMode.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/RequiredChatToolMode.cs index a920afaef17..ef410ba24db 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/RequiredChatToolMode.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/RequiredChatToolMode.cs @@ -8,8 +8,8 @@ namespace Microsoft.Extensions.AI; /// -/// Indicates that a chat tool must be called. It may optionally nominate a specific function, -/// or if not, indicates that any of them may be selected. +/// Represents a mode where a chat tool must be called. This class can optionally nominate a specific function +/// or indicate that any of the functions can be selected. /// [DebuggerDisplay("{DebuggerDisplay,nq}")] public sealed class RequiredChatToolMode : ChatToolMode @@ -18,7 +18,7 @@ public sealed class RequiredChatToolMode : ChatToolMode /// Gets the name of a specific that must be called. /// /// - /// If the value is , any available function may be selected (but at least one must be). + /// If the value is , any available function can be selected (but at least one must be). /// public string? RequiredFunctionName { get; } @@ -27,8 +27,8 @@ public sealed class RequiredChatToolMode : ChatToolMode /// /// The name of the function that must be called. /// - /// may be . However, it is preferable to use - /// when any function may be selected. + /// can be . However, it's preferable to use + /// when any function can be selected. /// public RequiredChatToolMode(string? requiredFunctionName) { diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/AudioContent.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/AudioContent.cs index 84354a95b1d..356cce78413 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/AudioContent.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/AudioContent.cs @@ -15,7 +15,7 @@ public class AudioContent : DataContent /// /// Initializes a new instance of the class. /// - /// The URI of the content. This may be a data URI. + /// The URI of the content. This can be a data URI. /// The media type (also known as MIME type) represented by the content. public AudioContent(Uri uri, string? mediaType = null) : base(uri, mediaType) @@ -25,7 +25,7 @@ public AudioContent(Uri uri, string? mediaType = null) /// /// Initializes a new instance of the class. /// - /// The URI of the content. This may be a data URI. + /// The URI of the content. This can be a data URI. /// The media type (also known as MIME type) represented by the content. [JsonConstructor] public AudioContent([StringSyntax(StringSyntaxAttribute.Uri)] string uri, string? mediaType = null) diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/DataContent.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/DataContent.cs index 5ed17aae1b5..8eb0afea4d6 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/DataContent.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/DataContent.cs @@ -34,7 +34,7 @@ public class DataContent : AIContent /// The string-based representation of the URI, including any data in the instance. private string? _uri; - /// The data, lazily-initialized if the data is provided in a data URI. + /// The data, lazily initialized if the data is provided in a data URI. private ReadOnlyMemory? _data; /// Parsed data URI information. @@ -43,7 +43,7 @@ public class DataContent : AIContent /// /// Initializes a new instance of the class. /// - /// The URI of the content. This may be a data URI. + /// The URI of the content. This can be a data URI. /// The media type (also known as MIME type) represented by the content. public DataContent(Uri uri, string? mediaType = null) : this(Throw.IfNull(uri).ToString(), mediaType) @@ -53,7 +53,7 @@ public DataContent(Uri uri, string? mediaType = null) /// /// Initializes a new instance of the class. /// - /// The URI of the content. This may be a data URI. + /// The URI of the content. This can be a data URI. /// The media type (also known as MIME type) represented by the content. [JsonConstructor] public DataContent([StringSyntax(StringSyntaxAttribute.Uri)] string uri, string? mediaType = null) @@ -116,7 +116,7 @@ private static void ValidateMediaType(ref string? mediaType) /// Gets the URI for this . /// /// The returned URI is always a valid URI string, even if the instance was constructed from a - /// or from a . In the case of a , this will return a data URI containing + /// or from a . In the case of a , this property returns a data URI containing /// that data. /// [StringSyntax(StringSyntaxAttribute.Uri)] @@ -155,10 +155,10 @@ public string Uri /// Gets the media type (also known as MIME type) of the content. /// - /// If the media type was explicitly specified, this property will return that value. + /// If the media type was explicitly specified, this property returns that value. /// If the media type was not explicitly specified, but a data URI was supplied and that data URI contained a non-default - /// media type, that media type will be returned. - /// Otherwise, this will return null. + /// media type, that media type is returned. + /// Otherwise, this property returns null. /// [JsonPropertyOrder(1)] public string? MediaType { get; private set; } @@ -167,17 +167,17 @@ public string Uri /// Gets a value indicating whether the content contains data rather than only being a reference to data. /// /// - /// If the instance is constructed from a or from a data URI, this property will return , + /// If the instance is constructed from a or from a data URI, this property returns , /// 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 will return . + /// that simply references where the data can be found but doesn't actually contain the data, this property returns . /// [JsonIgnore] public bool ContainsData => _dataUri is not null || _data is not null; /// Gets the data represented by this instance. /// - /// If is , this property will return the represented data. - /// If is , this property will return . + /// If is , this property returns the represented data. + /// If is , this property returns . /// [MemberNotNullWhen(true, nameof(ContainsData))] [JsonIgnore] diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/FunctionResultContent.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/FunctionResultContent.cs index 731716e5427..b05553f16b8 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/FunctionResultContent.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/FunctionResultContent.cs @@ -21,8 +21,8 @@ public sealed class FunctionResultContent : AIContent /// The function call ID for which this is the result. /// The function name that produced the result. /// - /// This may be if the function returned , if the function was void-returning - /// and thus had no result, or if the function call failed. Typically, however, in order to provide meaningfully representative + /// if the function returned 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. /// [JsonConstructor] @@ -37,7 +37,7 @@ public FunctionResultContent(string callId, string name, object? result) /// Gets or sets the ID of the function call for which this is the result. /// /// - /// If this is the result for a , this should contain the same + /// If this is the result for a , this property should contain the same /// value. /// public string CallId { get; set; } @@ -51,8 +51,8 @@ public FunctionResultContent(string callId, string name, object? result) /// Gets or sets the result of the function call, or a generic error message if the function call failed. /// /// - /// This may be if the function returned , if the function was void-returning - /// and thus had no result, or if the function call failed. Typically, however, in order to provide meaningfully representative + /// if the function returned 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. /// public object? Result { get; set; } @@ -61,9 +61,9 @@ public FunctionResultContent(string callId, string name, object? result) /// Gets or sets an exception that occurred if the function call failed. /// /// - /// This property is for information purposes only. The is not serialized as part of serializing - /// instances of this class with ; as such, upon deserialization, this property will be . - /// Consumers should not rely on indicating success. + /// This property is for informational purposes only. The is not serialized as part of serializing + /// instances of this class with . As such, upon deserialization, this property will be . + /// Consumers should not rely on indicating success. /// [JsonIgnore] public Exception? Exception { get; set; } diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/ImageContent.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/ImageContent.cs index d376586c993..df559152412 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/ImageContent.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/ImageContent.cs @@ -15,7 +15,7 @@ public class ImageContent : DataContent /// /// Initializes a new instance of the class. /// - /// The URI of the content. This may be a data URI. + /// The URI of the content. This can be a data URI. /// The media type (also known as MIME type) represented by the content. public ImageContent(Uri uri, string? mediaType = null) : base(uri, mediaType) @@ -25,7 +25,7 @@ public ImageContent(Uri uri, string? mediaType = null) /// /// Initializes a new instance of the class. /// - /// The URI of the content. This may be a data URI. + /// The URI of the content. This can be a data URI. /// The media type (also known as MIME type) represented by the content. [JsonConstructor] public ImageContent([StringSyntax(StringSyntaxAttribute.Uri)] string uri, string? mediaType = null) diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Embeddings/DelegatingEmbeddingGenerator.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Embeddings/DelegatingEmbeddingGenerator.cs index 590817d4e11..7edbe7cf5bd 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Embeddings/DelegatingEmbeddingGenerator.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Embeddings/DelegatingEmbeddingGenerator.cs @@ -12,10 +12,10 @@ namespace Microsoft.Extensions.AI; /// /// Provides an optional base class for an that passes through calls to another instance. /// -/// Specifies the type of the input passed to the generator. -/// Specifies the type of the embedding instance produced by the generator. +/// The type of the input passed to the generator. +/// The type of the embedding instance produced by the generator. /// -/// This is recommended as a base type when building generators that can be chained in any order around an underlying . +/// This type is recommended as a base type when building generators that can be chained in any order around an underlying . /// The default implementation simply passes each call to the inner generator instance. /// public class DelegatingEmbeddingGenerator : IEmbeddingGenerator @@ -41,7 +41,7 @@ public void Dispose() } /// Provides a mechanism for releasing unmanaged resources. - /// true if being called from ; otherwise, false. + /// if being called from ; otherwise, . protected virtual void Dispose(bool disposing) { if (disposing) diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Embeddings/EmbeddingGeneratorExtensions.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Embeddings/EmbeddingGeneratorExtensions.cs index 8a388d361b9..1593cdd33a8 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Embeddings/EmbeddingGeneratorExtensions.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Embeddings/EmbeddingGeneratorExtensions.cs @@ -20,10 +20,10 @@ public static class EmbeddingGeneratorExtensions /// The numeric type of the embedding data. /// The type of the object to be retrieved. /// The generator. - /// An optional key that may be used to help identify the target service. + /// An optional key that can be used to help identify the target service. /// The found object, otherwise . /// - /// The purpose of this method is to allow for the retrieval of strongly-typed services that may be provided by the + /// The purpose of this method is to allow for the retrieval of strongly typed services that may be provided by the /// , including itself or any services it might be wrapping. /// public static TService? GetService(this IEmbeddingGenerator generator, object? serviceKey = null) @@ -43,10 +43,10 @@ public static class EmbeddingGeneratorExtensions /// Asks the for an object of type . /// The type of the object to be retrieved. /// The generator. - /// An optional key that may be used to help identify the target service. + /// An optional key that can be used to help identify the target service. /// The found object, otherwise . /// - /// The purpose of this method is to allow for the retrieval of strongly-typed services that may be provided by the + /// The purpose of this method is to allow for the retrieval of strongly typed services that may be provided by the /// , including itself or any services it might be wrapping. /// public static TService? GetService(this IEmbeddingGenerator> generator, object? serviceKey = null) => diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Embeddings/EmbeddingGeneratorMetadata.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Embeddings/EmbeddingGeneratorMetadata.cs index 39bdd61d3ae..0f2f7b23af5 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Embeddings/EmbeddingGeneratorMetadata.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Embeddings/EmbeddingGeneratorMetadata.cs @@ -11,7 +11,7 @@ public class EmbeddingGeneratorMetadata /// Initializes a new instance of the class. /// The name of the embedding generation provider, if applicable. /// The URL for accessing the embedding generation provider, if applicable. - /// The id of the embedding generation model used, if applicable. + /// The ID of the embedding generation model used, if applicable. /// The number of dimensions in vectors produced by this generator, if applicable. public EmbeddingGeneratorMetadata(string? providerName = null, Uri? providerUri = null, string? modelId = null, int? dimensions = null) { @@ -27,8 +27,8 @@ public EmbeddingGeneratorMetadata(string? providerName = null, Uri? providerUri /// Gets the URL for accessing the embedding generation provider. public Uri? ProviderUri { get; } - /// Gets the id of the model used by this embedding generation provider. - /// This may be null if either the name is unknown or there are multiple possible models associated with this instance. + /// Gets the ID of the model used by this embedding generation provider. + /// This value can be null if either the name is unknown or there are multiple possible models associated with this instance. public string? ModelId { get; } /// Gets the number of dimensions in the embeddings produced by this instance. diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Embeddings/IEmbeddingGenerator.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Embeddings/IEmbeddingGenerator.cs index 9f9c9f1325f..84d02c0de34 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Embeddings/IEmbeddingGenerator.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Embeddings/IEmbeddingGenerator.cs @@ -42,10 +42,10 @@ Task> GenerateAsync( /// Asks the for an object of the specified type . /// The type of object being requested. - /// An optional key that may be used to help identify the target service. + /// An optional key that can be used to help identify the target service. /// The found object, otherwise . /// - /// The purpose of this method is to allow for the retrieval of strongly-typed services that may 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. /// object? GetService(Type serviceType, object? serviceKey = null); diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Functions/AIFunctionMetadata.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Functions/AIFunctionMetadata.cs index 03dac25d15f..528212c4b2b 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Functions/AIFunctionMetadata.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Functions/AIFunctionMetadata.cs @@ -73,7 +73,7 @@ public string Description } /// Gets the metadata for the parameters to the function. - /// If the function has no parameters, the returned list will be empty. + /// If the function has no parameters, the returned list is empty. public IReadOnlyList Parameters { get => _parameters; @@ -93,7 +93,7 @@ public IReadOnlyList Parameters } /// Gets parameter metadata for the return parameter. - /// If the function has no return parameter, the returned value will be a default instance of a . + /// If the function has no return parameter, the value is a default instance of an . public AIFunctionReturnParameterMetadata ReturnParameter { get => _returnParameter; @@ -107,6 +107,6 @@ public AIFunctionReturnParameterMetadata ReturnParameter init => _additionalProperties = Throw.IfNull(value); } - /// Gets a that may be used to marshal function parameters. + /// Gets a that can be used to marshal function parameters. public JsonSerializerOptions? JsonSerializerOptions { get; init; } } diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Functions/AIFunctionParameterMetadata.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Functions/AIFunctionParameterMetadata.cs index b9bd4d83841..b2e77f619db 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Functions/AIFunctionParameterMetadata.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Functions/AIFunctionParameterMetadata.cs @@ -7,7 +7,7 @@ namespace Microsoft.Extensions.AI; /// -/// Provides read-only metadata for a parameter. +/// Provides read-only metadata for an parameter. /// public sealed class AIFunctionParameterMetadata { @@ -24,7 +24,7 @@ public AIFunctionParameterMetadata(string name) /// Initializes a new instance of the class as a copy of another . /// The was null. - /// This creates a shallow clone of . + /// This constructor creates a shallow clone of . public AIFunctionParameterMetadata(AIFunctionParameterMetadata metadata) { _ = Throw.IfNull(metadata); diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Functions/AIFunctionReturnParameterMetadata.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Functions/AIFunctionReturnParameterMetadata.cs index 17aec4d2fdb..e96e67d4806 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Functions/AIFunctionReturnParameterMetadata.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Functions/AIFunctionReturnParameterMetadata.cs @@ -7,7 +7,7 @@ namespace Microsoft.Extensions.AI; /// -/// Provides read-only metadata for a 's return parameter. +/// Provides read-only metadata for an 's return parameter. /// public sealed class AIFunctionReturnParameterMetadata { diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Utilities/AIJsonSchemaCreateOptions.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Utilities/AIJsonSchemaCreateOptions.cs index afa2f236c69..150673560df 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Utilities/AIJsonSchemaCreateOptions.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Utilities/AIJsonSchemaCreateOptions.cs @@ -4,7 +4,7 @@ namespace Microsoft.Extensions.AI; /// -/// An options class for configuring the behavior of JSON schema creation functionality. +/// Provides options for configuring the behavior of JSON schema creation functionality. /// public sealed class AIJsonSchemaCreateOptions { diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Utilities/AIJsonUtilities.Schema.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Utilities/AIJsonUtilities.Schema.cs index b555148df8b..fa893450d0f 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Utilities/AIJsonUtilities.Schema.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Utilities/AIJsonUtilities.Schema.cs @@ -95,7 +95,7 @@ public static JsonElement ResolveParameterJsonSchema( /// The type of the parameter. /// The name of the parameter. /// The description of the parameter. - /// Whether the parameter is optional. + /// if the parameter is optional; otherwise, . /// The default value of the optional parameter, if applicable. /// The options used to extract the schema from the specified type. /// The options controlling schema inference. @@ -130,7 +130,7 @@ public static JsonElement CreateParameterJsonSchema( /// Creates a JSON schema for the specified type. /// The type for which to generate the schema. /// The description of the parameter. - /// Whether the parameter is optional. + /// if the parameter is optional; otherwise, . /// The default value of the optional parameter, if applicable. /// The options used to extract the schema from the specified type. /// The options controlling schema inference. diff --git a/src/Libraries/Microsoft.Extensions.AI.AzureAIInference/AzureAIInferenceChatClient.cs b/src/Libraries/Microsoft.Extensions.AI.AzureAIInference/AzureAIInferenceChatClient.cs index 143d5928106..5c4e630da1a 100644 --- a/src/Libraries/Microsoft.Extensions.AI.AzureAIInference/AzureAIInferenceChatClient.cs +++ b/src/Libraries/Microsoft.Extensions.AI.AzureAIInference/AzureAIInferenceChatClient.cs @@ -18,7 +18,7 @@ namespace Microsoft.Extensions.AI; -/// An for an Azure AI Inference . +/// Represents an for an Azure AI Inference . public sealed class AzureAIInferenceChatClient : IChatClient { /// A default schema to use when a parameter lacks a pre-defined schema. @@ -29,7 +29,7 @@ public sealed class AzureAIInferenceChatClient : IChatClient /// Initializes a new instance of the class for the specified . /// The underlying client. - /// The id of the model to use. If null, it may be provided per request via . + /// The ID of the model to use. If null, it can be provided per request via . public AzureAIInferenceChatClient(ChatCompletionsClient chatCompletionsClient, string? modelId = null) { _ = Throw.IfNull(chatCompletionsClient); @@ -301,7 +301,7 @@ private ChatCompletionsOptions ToAzureAIOptions(IList chatContents, } } - // These properties are strongly-typed on ChatOptions but not on ChatCompletionsOptions. + // These properties are strongly typed on ChatOptions but not on ChatCompletionsOptions. if (options.TopK is int topK) { result.AdditionalProperties["top_k"] = new BinaryData(JsonSerializer.SerializeToUtf8Bytes(topK, JsonContext.Default.Int32)); diff --git a/src/Libraries/Microsoft.Extensions.AI.AzureAIInference/AzureAIInferenceEmbeddingGenerator.cs b/src/Libraries/Microsoft.Extensions.AI.AzureAIInference/AzureAIInferenceEmbeddingGenerator.cs index 3f8f2adb3ff..0c785cbbd6d 100644 --- a/src/Libraries/Microsoft.Extensions.AI.AzureAIInference/AzureAIInferenceEmbeddingGenerator.cs +++ b/src/Libraries/Microsoft.Extensions.AI.AzureAIInference/AzureAIInferenceEmbeddingGenerator.cs @@ -21,7 +21,7 @@ namespace Microsoft.Extensions.AI; -/// An for an Azure.AI.Inference . +/// Represents an for an Azure.AI.Inference . public sealed class AzureAIInferenceEmbeddingGenerator : IEmbeddingGenerator> { @@ -34,8 +34,8 @@ public sealed class AzureAIInferenceEmbeddingGenerator : /// Initializes a new instance of the class. /// The underlying client. /// - /// The id of the model to use. This may also be overridden per request via . - /// Either this parameter or must provide a valid model id. + /// The ID of the model to use. This can also be overridden per request via . + /// Either this parameter or must provide a valid model ID. /// /// The number of dimensions to generate in each embedding. public AzureAIInferenceEmbeddingGenerator( diff --git a/src/Libraries/Microsoft.Extensions.AI.AzureAIInference/AzureAIInferenceExtensions.cs b/src/Libraries/Microsoft.Extensions.AI.AzureAIInference/AzureAIInferenceExtensions.cs index 05a6c87b33b..117a416b30a 100644 --- a/src/Libraries/Microsoft.Extensions.AI.AzureAIInference/AzureAIInferenceExtensions.cs +++ b/src/Libraries/Microsoft.Extensions.AI.AzureAIInference/AzureAIInferenceExtensions.cs @@ -10,17 +10,17 @@ public static class AzureAIInferenceExtensions { /// Gets an for use with this . /// The client. - /// The id of the model to use. If null, it may be provided per request via . - /// An that may be used to converse via the . + /// The ID of the model to use. If null, it can be provided per request via . + /// An that can be used to converse via the . public static IChatClient AsChatClient( this ChatCompletionsClient chatCompletionsClient, string? modelId = null) => new AzureAIInferenceChatClient(chatCompletionsClient, modelId); /// Gets an for use with this . /// The client. - /// The id of the model to use. If null, it may be provided per request via . + /// The ID of the model to use. If null, it can be provided per request via . /// The number of dimensions to generate in each embedding. - /// An that may be used to generate embeddings via the . + /// An that can be used to generate embeddings via the . public static IEmbeddingGenerator> AsEmbeddingGenerator( this EmbeddingsClient embeddingsClient, string? modelId = null, int? dimensions = null) => new AzureAIInferenceEmbeddingGenerator(embeddingsClient, modelId, dimensions); diff --git a/src/Libraries/Microsoft.Extensions.AI.Ollama/OllamaChatClient.cs b/src/Libraries/Microsoft.Extensions.AI.Ollama/OllamaChatClient.cs index e6084e94ab6..780b334cd93 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Ollama/OllamaChatClient.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Ollama/OllamaChatClient.cs @@ -19,7 +19,7 @@ namespace Microsoft.Extensions.AI; -/// An for Ollama. +/// Represents an for Ollama. public sealed class OllamaChatClient : IChatClient { private static readonly JsonElement _defaultParameterSchema = JsonDocument.Parse("{}").RootElement; @@ -33,8 +33,8 @@ public sealed class OllamaChatClient : IChatClient /// Initializes a new instance of the class. /// The endpoint URI where Ollama is hosted. /// - /// The id of the model to use. This may also be overridden per request via . - /// Either this parameter or must provide a valid model id. + /// The ID of the model to use. This ID can also be overridden per request via . + /// Either this parameter or must provide a valid model ID. /// /// An instance to use for HTTP operations. public OllamaChatClient(string endpoint, string? modelId = null, HttpClient? httpClient = null) @@ -45,8 +45,8 @@ public OllamaChatClient(string endpoint, string? modelId = null, HttpClient? htt /// Initializes a new instance of the class. /// The endpoint URI where Ollama is hosted. /// - /// The id of the model to use. This may also be overridden per request via . - /// Either this parameter or must provide a valid model id. + /// The ID of the model to use. This ID can also be overridden per request via . + /// Either this parameter or must provide a valid model ID. /// /// An instance to use for HTTP operations. public OllamaChatClient(Uri endpoint, string? modelId = null, HttpClient? httpClient = null) diff --git a/src/Libraries/Microsoft.Extensions.AI.Ollama/OllamaEmbeddingGenerator.cs b/src/Libraries/Microsoft.Extensions.AI.Ollama/OllamaEmbeddingGenerator.cs index ea273c31b4c..288971d3534 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Ollama/OllamaEmbeddingGenerator.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Ollama/OllamaEmbeddingGenerator.cs @@ -12,7 +12,7 @@ namespace Microsoft.Extensions.AI; -/// An for Ollama. +/// Represents an for Ollama. public sealed class OllamaEmbeddingGenerator : IEmbeddingGenerator> { /// The api/embeddings endpoint URI. @@ -24,8 +24,8 @@ public sealed class OllamaEmbeddingGenerator : IEmbeddingGeneratorInitializes a new instance of the class. /// The endpoint URI where Ollama is hosted. /// - /// The id of the model to use. This may also be overridden per request via . - /// Either this parameter or must provide a valid model id. + /// The ID of the model to use. This ID can also be overridden per request via . + /// Either this parameter or must provide a valid model ID. /// /// An instance to use for HTTP operations. public OllamaEmbeddingGenerator(string endpoint, string? modelId = null, HttpClient? httpClient = null) @@ -36,8 +36,8 @@ public OllamaEmbeddingGenerator(string endpoint, string? modelId = null, HttpCli /// Initializes a new instance of the class. /// The endpoint URI where Ollama is hosted. /// - /// The id of the model to use. This may also be overridden per request via . - /// Either this parameter or must provide a valid model id. + /// The ID of the model to use. This ID can also be overridden per request via . + /// Either this parameter or must provide a valid model ID. /// /// An instance to use for HTTP operations. public OllamaEmbeddingGenerator(Uri endpoint, string? modelId = null, HttpClient? httpClient = null) diff --git a/src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIChatClient.cs b/src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIChatClient.cs index 5490466b66a..6e4a8d8ec9b 100644 --- a/src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIChatClient.cs +++ b/src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIChatClient.cs @@ -24,7 +24,7 @@ namespace Microsoft.Extensions.AI; -/// An for an OpenAI or . +/// Represents an for an OpenAI or . public sealed partial class OpenAIChatClient : IChatClient { private static readonly JsonElement _defaultParameterSchema = JsonDocument.Parse("{}").RootElement; diff --git a/src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIClientExtensions.cs b/src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIClientExtensions.cs index a33fd34e1ea..2bea9264730 100644 --- a/src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIClientExtensions.cs +++ b/src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIClientExtensions.cs @@ -13,13 +13,13 @@ public static class OpenAIClientExtensions /// Gets an for use with this . /// The client. /// The model. - /// An that may be used to converse via the . + /// An that can be used to converse via the . public static IChatClient AsChatClient(this OpenAIClient openAIClient, string modelId) => new OpenAIChatClient(openAIClient, modelId); /// Gets an for use with this . /// The client. - /// An that may be used to converse via the . + /// An that can be used to converse via the . public static IChatClient AsChatClient(this ChatClient chatClient) => new OpenAIChatClient(chatClient); @@ -27,14 +27,14 @@ public static IChatClient AsChatClient(this ChatClient chatClient) => /// The client. /// The model to use. /// The number of dimensions to generate in each embedding. - /// An that may be used to generate embeddings via the . + /// An that can be used to generate embeddings via the . public static IEmbeddingGenerator> AsEmbeddingGenerator(this OpenAIClient openAIClient, string modelId, int? dimensions = null) => new OpenAIEmbeddingGenerator(openAIClient, modelId, dimensions); /// Gets an for use with this . /// The client. /// The number of dimensions to generate in each embedding. - /// An that may be used to generate embeddings via the . + /// An that can be used to generate embeddings via the . public static IEmbeddingGenerator> AsEmbeddingGenerator(this EmbeddingClient embeddingClient, int? dimensions = null) => new OpenAIEmbeddingGenerator(embeddingClient, dimensions); } diff --git a/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/ChatCompletion{T}.cs b/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/ChatCompletion{T}.cs index 7166f04e744..182ab378b12 100644 --- a/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/ChatCompletion{T}.cs +++ b/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/ChatCompletion{T}.cs @@ -45,9 +45,11 @@ public ChatCompletion(ChatCompletion completion, JsonSerializerOptions serialize /// /// Gets the result of the chat completion as an instance of . + /// + /// /// If the response did not contain JSON, or if deserialization fails, this property will throw. /// To avoid exceptions, use instead. - /// + /// public T Result { get @@ -66,7 +68,7 @@ public T Result /// /// Attempts to deserialize the result to produce an instance of . /// - /// The result. + /// When this method returns, contains the result. /// if the result was produced, otherwise . public bool TryGetResult([NotNullWhen(true)] out T? result) { @@ -106,8 +108,10 @@ public bool TryGetResult([NotNullWhen(true)] out T? result) /// /// Gets or sets a value indicating whether the JSON schema has an extra object wrapper. - /// This is required for any non-JSON-object-typed values such as numbers, enum values, or arrays. /// + /// + /// The wrapper is required for any non-JSON-object-typed values such as numbers, enum values, and arrays. + /// internal bool IsWrappedInObject { get; set; } private string? GetResultAsJson() diff --git a/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/ConfigureOptionsChatClient.cs b/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/ConfigureOptionsChatClient.cs index cdcbb283f12..ce2fe3ca29d 100644 --- a/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/ConfigureOptionsChatClient.cs +++ b/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/ConfigureOptionsChatClient.cs @@ -10,7 +10,7 @@ namespace Microsoft.Extensions.AI; -/// A delegating chat client that configures a instance used by the remainder of the pipeline. +/// Represents a delegating chat client that configures a instance used by the remainder of the pipeline. public sealed class ConfigureOptionsChatClient : DelegatingChatClient { /// The callback delegate used to configure options. @@ -20,7 +20,7 @@ public sealed class ConfigureOptionsChatClient : DelegatingChatClient /// The inner client. /// /// The delegate to invoke to configure the instance. It is passed a clone of the caller-supplied instance - /// (or a newly-constructed instance if the caller-supplied instance is ). + /// (or a newly constructed instance if the caller-supplied instance is ). /// /// /// The delegate is passed either a new instance of if diff --git a/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/ConfigureOptionsChatClientBuilderExtensions.cs b/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/ConfigureOptionsChatClientBuilderExtensions.cs index c0ad600440b..5c160794a9f 100644 --- a/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/ConfigureOptionsChatClientBuilderExtensions.cs +++ b/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/ConfigureOptionsChatClientBuilderExtensions.cs @@ -17,7 +17,7 @@ public static class ConfigureOptionsChatClientBuilderExtensions /// The . /// /// The delegate to invoke to configure the instance. - /// It is passed a clone of the caller-supplied instance (or a newly-constructed instance if the caller-supplied instance is ). + /// It is passed a clone of the caller-supplied instance (or a newly constructed instance if the caller-supplied instance is ). /// /// /// This can be used to set default options. The delegate is passed either a new instance of diff --git a/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/FunctionInvokingChatClient.cs b/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/FunctionInvokingChatClient.cs index 09846198802..1366422b8ea 100644 --- a/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/FunctionInvokingChatClient.cs +++ b/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/FunctionInvokingChatClient.cs @@ -29,7 +29,7 @@ namespace Microsoft.Extensions.AI; /// /// The provided implementation of is thread-safe for concurrent use so long as the /// instances employed as part of the supplied are also safe. -/// The property may be used to control whether multiple function invocation +/// The property can be used to control whether multiple function invocation /// requests as part of the same request are invocable concurrently, but even with that set to /// (the default), multiple concurrent requests to this same instance and using the same tools could result in those /// tools being used concurrently (one per request). For example, a function that accesses the HttpContext of a specific @@ -65,23 +65,17 @@ public FunctionInvokingChatClient(IChatClient innerClient, ILogger? logger = nul /// /// Gets or sets a value indicating whether to handle exceptions that occur during function calls. /// - /// - /// - /// If the value is , then if a function call fails with an exception, the + /// + /// if the /// underlying will be instructed to give a response without invoking - /// any further functions. - /// - /// - /// If the value is , the underlying will be allowed + /// any further functions if a function call fails with an exception. + /// if the underlying is allowed /// to continue attempting function calls until is reached. - /// - /// - /// Changing the value of this property while the client is in use may result in inconsistencies - /// as to whether errors are retried during an in-flight request. - /// - /// /// The default value is . - /// + /// + /// + /// Changing the value of this property while the client is in use might result in inconsistencies + /// as to whether errors are retried during an in-flight request. /// public bool RetryOnError { get; set; } @@ -89,23 +83,27 @@ public FunctionInvokingChatClient(IChatClient innerClient, ILogger? logger = nul /// Gets or sets a value indicating whether detailed exception information should be included /// in the chat history when calling the underlying . /// + /// + /// if the full exception message is added to the chat history + /// when calling the underlying . + /// if a generic error message is included in the chat history. + /// The default value is . + /// /// /// - /// The default value is , meaning that only a generic error message will - /// be included in the chat history. This prevents the underlying language model from disclosing - /// raw exception details to the end user, since it does not receive that information. Even in this + /// Setting the value to prevents the underlying language model from disclosing + /// raw exception details to the end user, since it doesn't receive that information. Even in this /// case, the raw object is available to application code by inspecting /// the property. /// /// - /// If set to , the full exception message will be added to the chat history - /// when calling the underlying . This can help it to bypass problems on - /// its own, for example by retrying the function call with different arguments. However it may - /// result in disclosing the raw exception information to external users, which may be a security + /// Setting the value to can help the underlying bypass problems on + /// its own, for example by retrying the function call with different arguments. However it might + /// result in disclosing the raw exception information to external users, which can be a security /// concern depending on the application scenario. /// /// - /// Changing the value of this property while the client is in use may result in inconsistencies + /// Changing the value of this property while the client is in use might result in inconsistencies /// as to whether detailed errors are provided during an in-flight request. /// /// @@ -114,21 +112,27 @@ public FunctionInvokingChatClient(IChatClient innerClient, ILogger? logger = nul /// /// Gets or sets a value indicating whether to allow concurrent invocation of functions. /// + /// + /// if multiple function calls can execute in parallel. + /// if function calls are processed serially. + /// The default value is . + /// /// - /// - /// An individual response from the inner client may contain multiple function call requests. + /// An individual response from the inner client might contain multiple function call requests. /// By default, such function calls are processed serially. Set to - /// to enable concurrent invocation such that multiple function calls may execute in parallel. - /// - /// - /// The default value is . - /// + /// to enable concurrent invocation such that multiple function calls can execute in parallel. /// public bool ConcurrentInvocation { get; set; } /// /// Gets or sets a value indicating whether to keep intermediate messages in the chat history. /// + /// + /// if intermediate messages persist in the list provided + /// to and by the caller. + /// if intermediate messages are removed prior to completing the operation. + /// The default value is . + /// /// /// /// When the inner returns to the @@ -136,13 +140,12 @@ public FunctionInvokingChatClient(IChatClient innerClient, ILogger? logger = nul /// those messages to the list of messages, along with instances /// it creates with the results of invoking the requested functions. The resulting augmented /// list of messages is then passed to the inner client in order to send the results back. - /// By default, is , and those - /// messages will persist in the list provided to + /// By default, those messages persist in the list provided to /// and by the caller. Set /// to to remove those messages prior to completing the operation. /// /// - /// Changing the value of this property while the client is in use may result in inconsistencies + /// Changing the value of this property while the client is in use might result in inconsistencies /// as to whether function calling messages are kept during an in-flight request. /// /// @@ -151,22 +154,23 @@ public FunctionInvokingChatClient(IChatClient innerClient, ILogger? logger = nul /// /// Gets or sets the maximum number of iterations per request. /// + /// + /// The maximum number of iterations per request. + /// The default value is . + /// /// /// - /// Each request to this may end up making + /// Each request to this might end up making /// multiple requests to the inner client. Each time the inner client responds with - /// a function call request, this client may perform that invocation and send the results + /// a function call request, this client might perform that invocation and send the results /// back to the inner client in a new request. This property limits the number of times /// such a roundtrip is performed. If null, there is no limit applied. If set, the value /// must be at least one, as it includes the initial request. /// /// - /// Changing the value of this property while the client is in use may result in inconsistencies + /// Changing the value of this property while the client is in use might result in inconsistencies /// as to how many iterations are allowed for an in-flight request. /// - /// - /// The default value is . - /// /// public int? MaximumIterationsPerRequest { @@ -575,7 +579,7 @@ FunctionResultContent CreateFunctionResultContent(FunctionInvocationResult resul /// The function invocation context detailing the function to be invoked and its arguments along with additional request information. /// /// The to monitor for cancellation requests. The default is . - /// The result of the function invocation. This may be null if the function invocation returned null. + /// The result of the function invocation, or if the function invocation returned . protected virtual async Task InvokeFunctionAsync(FunctionInvocationContext context, CancellationToken cancellationToken) { _ = Throw.IfNull(context); @@ -707,15 +711,15 @@ internal FunctionInvocationContext( /// Gets or sets the total number of function call requests within the iteration. /// - /// The response from the underlying client may include multiple function call requests. + /// The response from the underlying client might include multiple function call requests. /// This count indicates how many there were. /// public int FunctionCount { get; set; } /// Gets or sets a value indicating whether to terminate the request. /// - /// In response to a function call request, the function may be invoked, its result added to the chat contents, - /// and a new request issued to the wrapped client. If this property is set to true, that subsequent request + /// In response to a function call request, the function might be invoked, its result added to the chat contents, + /// and a new request issued to the wrapped client. If this property is set to , that subsequent request /// will not be issued and instead the loop immediately terminated rather than continuing until there are no /// more function call requests in responses. /// diff --git a/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/OpenTelemetryChatClient.cs b/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/OpenTelemetryChatClient.cs index 6274c39419b..3913d33145c 100644 --- a/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/OpenTelemetryChatClient.cs +++ b/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/OpenTelemetryChatClient.cs @@ -21,9 +21,9 @@ namespace Microsoft.Extensions.AI; -/// A delegating chat client that implements the OpenTelemetry Semantic Conventions for Generative AI systems. +/// Represents a delegating chat client that implements the OpenTelemetry Semantic Conventions for Generative AI systems. /// -/// The draft specification this follows is available at https://opentelemetry.io/docs/specs/semconv/gen-ai/. +/// The draft specification this follows is available at . /// The specification is still experimental and subject to change; as such, the telemetry output by this client is also subject to change. /// public sealed partial class OpenTelemetryChatClient : DelegatingChatClient @@ -102,9 +102,14 @@ protected override void Dispose(bool disposing) /// /// Gets or sets a value indicating whether potentially sensitive information should be included in telemetry. /// + /// + /// if potentially sensitive information should be included in telemetry; + /// if telemetry shouldn't include raw inputs and outputs. + /// The default value is . + /// /// - /// The value is by default, meaning that telemetry will include metadata such as token counts but not raw inputs - /// and outputs such as message content, function call arguments, and function call results. + /// By default, telemetry includes metadata, such as token counts, but not raw inputs + /// and outputs, such as message content, function call arguments, and function call results. /// public bool EnableSensitiveData { get; set; } diff --git a/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/OpenTelemetryChatClientBuilderExtensions.cs b/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/OpenTelemetryChatClientBuilderExtensions.cs index 6e04e16f507..59c5c81a84d 100644 --- a/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/OpenTelemetryChatClientBuilderExtensions.cs +++ b/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/OpenTelemetryChatClientBuilderExtensions.cs @@ -15,7 +15,7 @@ public static class OpenTelemetryChatClientBuilderExtensions /// Adds OpenTelemetry support to the chat client pipeline, following the OpenTelemetry Semantic Conventions for Generative AI systems. /// /// - /// The draft specification this follows is available at https://opentelemetry.io/docs/specs/semconv/gen-ai/. + /// The draft specification this follows is available at . /// The specification is still experimental and subject to change; as such, the telemetry output by this client is also subject to change. /// /// The . diff --git a/src/Libraries/Microsoft.Extensions.AI/Embeddings/CachingEmbeddingGenerator.cs b/src/Libraries/Microsoft.Extensions.AI/Embeddings/CachingEmbeddingGenerator.cs index 8438d467eb6..d632431102c 100644 --- a/src/Libraries/Microsoft.Extensions.AI/Embeddings/CachingEmbeddingGenerator.cs +++ b/src/Libraries/Microsoft.Extensions.AI/Embeddings/CachingEmbeddingGenerator.cs @@ -11,7 +11,7 @@ namespace Microsoft.Extensions.AI; -/// A delegating embedding generator that caches the results of embedding generation calls. +/// Represents a delegating embedding generator that caches the results of embedding generation calls. /// The type from which embeddings will be generated. /// The type of embeddings to generate. public abstract class CachingEmbeddingGenerator : DelegatingEmbeddingGenerator diff --git a/src/Libraries/Microsoft.Extensions.AI/Embeddings/ConfigureOptionsEmbeddingGenerator.cs b/src/Libraries/Microsoft.Extensions.AI/Embeddings/ConfigureOptionsEmbeddingGenerator.cs index d4125ef9aa0..c956a0bfe9b 100644 --- a/src/Libraries/Microsoft.Extensions.AI/Embeddings/ConfigureOptionsEmbeddingGenerator.cs +++ b/src/Libraries/Microsoft.Extensions.AI/Embeddings/ConfigureOptionsEmbeddingGenerator.cs @@ -25,7 +25,7 @@ public sealed class ConfigureOptionsEmbeddingGenerator : Del /// The inner generator. /// /// The delegate to invoke to configure the instance. It is passed a clone of the caller-supplied - /// instance (or a newly-constructed instance if the caller-supplied instance is ). + /// instance (or a newly constructed instance if the caller-supplied instance is ). /// /// /// The delegate is passed either a new instance of if diff --git a/src/Libraries/Microsoft.Extensions.AI/Embeddings/ConfigureOptionsEmbeddingGeneratorBuilderExtensions.cs b/src/Libraries/Microsoft.Extensions.AI/Embeddings/ConfigureOptionsEmbeddingGeneratorBuilderExtensions.cs index be469786247..4bf0a7b9e6e 100644 --- a/src/Libraries/Microsoft.Extensions.AI/Embeddings/ConfigureOptionsEmbeddingGeneratorBuilderExtensions.cs +++ b/src/Libraries/Microsoft.Extensions.AI/Embeddings/ConfigureOptionsEmbeddingGeneratorBuilderExtensions.cs @@ -19,7 +19,7 @@ public static class ConfigureOptionsEmbeddingGeneratorBuilderExtensions /// The . /// /// The delegate to invoke to configure the instance. It is passed a clone of the caller-supplied - /// instance (or a newly-constructed instance if the caller-supplied instance is ). + /// instance (or a new constructed instance if the caller-supplied instance is ). /// /// /// This can be used to set default options. The delegate is passed either a new instance of diff --git a/src/Libraries/Microsoft.Extensions.AI/Embeddings/DistributedCachingEmbeddingGenerator.cs b/src/Libraries/Microsoft.Extensions.AI/Embeddings/DistributedCachingEmbeddingGenerator.cs index a2cf2315b8a..ecec409a1b3 100644 --- a/src/Libraries/Microsoft.Extensions.AI/Embeddings/DistributedCachingEmbeddingGenerator.cs +++ b/src/Libraries/Microsoft.Extensions.AI/Embeddings/DistributedCachingEmbeddingGenerator.cs @@ -11,7 +11,7 @@ namespace Microsoft.Extensions.AI; /// -/// A delegating embedding generator that caches the results of embedding generation calls, +/// Represents a delegating embedding generator that caches the results of embedding generation calls, /// storing them as JSON in an . /// /// The type from which embeddings will be generated. diff --git a/src/Libraries/Microsoft.Extensions.AI/Embeddings/OpenTelemetryEmbeddingGenerator.cs b/src/Libraries/Microsoft.Extensions.AI/Embeddings/OpenTelemetryEmbeddingGenerator.cs index 2dce06620a8..09f762d33d0 100644 --- a/src/Libraries/Microsoft.Extensions.AI/Embeddings/OpenTelemetryEmbeddingGenerator.cs +++ b/src/Libraries/Microsoft.Extensions.AI/Embeddings/OpenTelemetryEmbeddingGenerator.cs @@ -13,9 +13,9 @@ namespace Microsoft.Extensions.AI; -/// A delegating embedding generator that implements the OpenTelemetry Semantic Conventions for Generative AI systems. +/// Represents a delegating embedding generator that implements the OpenTelemetry Semantic Conventions for Generative AI systems. /// -/// The draft specification this follows is available at https://opentelemetry.io/docs/specs/semconv/gen-ai/. +/// The draft specification this follows is available at . /// The specification is still experimental and subject to change; as such, the telemetry output by this generator is also subject to change. /// /// The type of input used to produce embeddings. diff --git a/src/Libraries/Microsoft.Extensions.AI/Embeddings/OpenTelemetryEmbeddingGeneratorBuilderExtensions.cs b/src/Libraries/Microsoft.Extensions.AI/Embeddings/OpenTelemetryEmbeddingGeneratorBuilderExtensions.cs index bffb9087abf..5f40f884bc4 100644 --- a/src/Libraries/Microsoft.Extensions.AI/Embeddings/OpenTelemetryEmbeddingGeneratorBuilderExtensions.cs +++ b/src/Libraries/Microsoft.Extensions.AI/Embeddings/OpenTelemetryEmbeddingGeneratorBuilderExtensions.cs @@ -15,7 +15,7 @@ public static class OpenTelemetryEmbeddingGeneratorBuilderExtensions /// Adds OpenTelemetry support to the embedding generator pipeline, following the OpenTelemetry Semantic Conventions for Generative AI systems. /// /// - /// The draft specification this follows is available at https://opentelemetry.io/docs/specs/semconv/gen-ai/. + /// The draft specification this follows is available at . /// The specification is still experimental and subject to change; as such, the telemetry output by this generator is also subject to change. /// /// The type of input used to produce embeddings. diff --git a/src/Libraries/Microsoft.Extensions.AI/Functions/AIFunctionContext.cs b/src/Libraries/Microsoft.Extensions.AI/Functions/AIFunctionContext.cs index 25f239f8883..3dcfa2215f7 100644 --- a/src/Libraries/Microsoft.Extensions.AI/Functions/AIFunctionContext.cs +++ b/src/Libraries/Microsoft.Extensions.AI/Functions/AIFunctionContext.cs @@ -8,9 +8,9 @@ namespace Microsoft.Extensions.AI; /// Provides additional context to the invocation of an created by . /// -/// A delegate or passed to methods may represent a method that has a parameter +/// A delegate or passed to methods can represent a method that has a parameter /// of type . Whereas all other parameters are passed by name from the supplied collection of arguments, -/// a parameter is passed specially by the implementation, in order to pass relevant +/// an parameter is passed specially by the implementation to pass relevant /// context into the method's invocation. For example, any passed to the /// method is available from the property. /// diff --git a/src/Libraries/Microsoft.Extensions.AI/Functions/AIFunctionFactory.cs b/src/Libraries/Microsoft.Extensions.AI/Functions/AIFunctionFactory.cs index b4b022b4a39..a19608a2977 100644 --- a/src/Libraries/Microsoft.Extensions.AI/Functions/AIFunctionFactory.cs +++ b/src/Libraries/Microsoft.Extensions.AI/Functions/AIFunctionFactory.cs @@ -18,7 +18,7 @@ namespace Microsoft.Extensions.AI; -/// Provides factory methods for creating commonly-used implementations of . +/// Provides factory methods for creating commonly used implementations of . public static partial class AIFunctionFactory { /// Holds the default options instance used when creating function. diff --git a/src/Libraries/Microsoft.Extensions.AI/Functions/AIFunctionFactoryCreateOptions.cs b/src/Libraries/Microsoft.Extensions.AI/Functions/AIFunctionFactoryCreateOptions.cs index 7dbfc6821e8..6483b83c0ad 100644 --- a/src/Libraries/Microsoft.Extensions.AI/Functions/AIFunctionFactoryCreateOptions.cs +++ b/src/Libraries/Microsoft.Extensions.AI/Functions/AIFunctionFactoryCreateOptions.cs @@ -11,7 +11,7 @@ namespace Microsoft.Extensions.AI; /// -/// Options that can be provided when creating an from a method. +/// Represents options that can be provided when creating an from a method. /// public sealed class AIFunctionFactoryCreateOptions { @@ -32,35 +32,35 @@ public JsonSerializerOptions SerializerOptions } /// Gets or sets the name to use for the function. - /// - /// If , it will default to one derived from the method represented by the passed or . - /// + /// + /// The name to use for the function. The default value is a name derived from the method represented by the passed or . + /// public string? Name { get; set; } /// Gets or sets the description to use for the function. - /// - /// If , it will default to one derived from the passed or , if possible - /// (e.g. via a on the method). - /// + /// + /// The description for the function. The default value is a description derived from the passed or , if possible + /// (for example, via a on the method). + /// public string? Description { get; set; } /// Gets or sets metadata for the parameters of the function. - /// - /// If , it will default to metadata derived from the passed or . - /// + /// + /// Metadata for the function's parameters. The default value is metadata derived from the passed or . + /// public IReadOnlyList? Parameters { get; set; } /// Gets or sets metadata for function's return parameter. - /// - /// If , it will default to one derived from the passed or . - /// + /// + /// Metadata for the function's return parameter. The default value is metadata derived from the passed or . + /// public AIFunctionReturnParameterMetadata? ReturnParameter { get; set; } /// - /// Gets or sets additional values that will be stored on the resulting property. + /// Gets or sets additional values to store on the resulting property. /// /// - /// This can be used to provide arbitrary information about the function. + /// This property can be used to provide arbitrary information about the function. /// public IReadOnlyDictionary? AdditionalProperties { get; set; } }