8000 Add see also links to conceptual docs (#6368) · dotnet/extensions@fa742c4 · GitHub
[go: up one dir, main page]
Skip to content

Commit fa742c4

Browse files
gewarrenjeffhandley
gewarren
authored and
jeffhandley
committed
Add see also links to conceptual docs (#6368)
1 parent 7da26f9 commit fa742c4

File tree

8 files changed

+32
-22
lines changed

8 files changed

+32
-22
lines changed

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
namespace Microsoft.Extensions.AI;
88

99
/// <summary>Represents the options for a chat request.</summary>
10+
/// <related type="Article" href="https://learn.microsoft.com/dotnet/ai/microsoft-extensions-ai#provide-options">Provide options.</related>
1011
public class ChatOptions
1112
{
1213
/// <summary>Gets or sets an optional identifier used to associate a request with an existing conversation.</summary>
@@ -20,6 +21,7 @@ public string? ChatThreadId
2021
}
2122

2223
/// <summary>Gets or sets an optional identifier used to associate a request with an existing conversation.</summary>
24+
/// <related type="Article" href="https://learn.microsoft.com/dotnet/ai/microsoft-extensions-ai#stateless-vs-stateful-clients">Stateless vs. stateful clients.</related>
2325
public string? ConversationId { get; set; }
2426

2527
/// <summary>Gets or sets the temperature for generating chat responses.</summary>
@@ -115,6 +117,7 @@ public string? ChatThreadId
115117
public ChatToolMode? ToolMode { get; set; }
116118

117119
/// <summary>Gets or sets the list of tools to include with a chat request.</summary>
120+
/// <related type="Article" href="https://learn.microsoft.com/dotnet/ai/microsoft-extensions-ai#tool-calling">Tool calling.</related>
118121
[JsonIgnore]
119122
public IList<AITool>? Tools { get; set; }
120123

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,7 @@ public string? ChatThreadId
9292
/// or may not differ on every response, depending on whether the underlying provider uses a fixed ID for each conversation
9393
/// or updates it for each message.
9494
/// </remarks>
95+
/// <related type="Article" href="https://learn.microsoft.com/dotnet/ai/microsoft-extensions-ai#stateless-vs-stateful-clients">Stateless vs. stateful clients.</related>
9596
public string? ConversationId { get; set; }
9697

9798
/// <summary>Gets or sets the model ID used in the creation of the chat response.</summary>

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ namespace Microsoft.Extensions.AI;
1616
/// This is recommended as a base type when building clients that can be chained around an underlying <see cref="IChatClient"/>.
1717
/// The default implementation simply passes each call to the inner client instance.
1818
/// </remarks>
19+
/// <related type="Article" href="https://learn.microsoft.com/dotnet/ai/microsoft-extensions-ai#custom-ichatclient-middleware">Custom IChatClient middleware.</related>
1920
public class DelegatingChatClient : IChatClient
2021
{
2122
/// <summary>

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ namespace Microsoft.Extensions.AI;
2424
/// </para>
2525
/// </remarks>
2626
/// <related type="Article" href="https://learn.microsoft.com/dotnet/ai/quickstarts/build-chat-app">Build an AI chat app with .NET.</related>
27+
/// <related type="Article" href="https://learn.microsoft.com/dotnet/ai/microsoft-extensions-ai#the-ichatclient-interface">The IChatClient interface.</related>
2728
public interface IChatClient : IDisposable
2829
{
2930
/// <summary>Sends chat messages and returns the response.</summary>
@@ -32,6 +33,7 @@ public interface IChatClient : IDisposable
3233
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
3334
/// <returns>The response messages generated by the client.</returns>
3435
/// <exception cref="ArgumentNullException"><paramref name="messages"/> is <see langword="null"/>.</exception>
36+
/// <related type="Article" href="https://learn.microsoft.com/dotnet/ai/microsoft-extensions-ai#request-a-chat-response">Request a chat response.</related>
3537
Task<ChatResponse> GetResponseAsync(
3638
IEnumerable<ChatMessage> messages,
3739
ChatOptions? options = null,
@@ -43,6 +45,7 @@ Task<ChatResponse> GetResponseAsync(
4345
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
4446
/// <returns>The response messages generated by the client.</returns>
4547
/// <exception cref="ArgumentNullException"><paramref name="messages"/> is <see langword="null"/>.</exception>
48+
/// <related type="Article" href="https://learn.microsoft.com/dotnet/ai/microsoft-extensions-ai#request-a-streaming-chat-response">Request a streaming chat response.</related>
4649
IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
4750
IEnumerable<ChatMessage> messages,
4851
ChatOptions? options = null,

‎src/Libraries/Microsoft.Extensions.AI.Abstractions/Embeddings/IEmbeddingGenerator{TInput,TEmbedding}.cs

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ namespace Microsoft.Extensions.AI;
2424
/// no <see cref="IEmbeddingGenerator{TInput, TEmbedding}"/> instances are used which might employ such mutation.
2525
/// </para>
2626
/// </remarks>
27+
/// <related type="Article" href="https://learn.microsoft.com/dotnet/ai/microsoft-extensions-ai#the-iembeddinggenerator-interface">The IEmbeddingGenerator interface.</related>
2728
public interface IEmbeddingGenerator<in TInput, TEmbedding> : IEmbeddingGenerator
2829
where TEmbedding : Embedding
2930
{
@@ -33,6 +34,7 @@ public interface IEmbeddingGenerator<in TInput, TEmbedding> : IEmbeddingGenerato
3334
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
3435
/// <returns>The generated embeddings.</returns>
3536
/// <exception cref="ArgumentNullException"><paramref name="values"/> is <see langword="null"/>.</exception>
37+
/// <related type="Article" href="https://learn.microsoft.com/dotnet/ai/microsoft-extensions-ai#create-embeddings">Create embeddings.</related>
3638
Task<GeneratedEmbeddings<TEmbedding>> GenerateAsync(
3739
IEnumerable<TInput> values,
3840
EmbeddingGenerationOptions? options = null,

‎src/Libraries/Microsoft.Extensions.AI/ChatCompletion/ChatClientBuilder.cs

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@ public IChatClient Build(IServiceProvider? services = null)
6666
/// <param name="clientFactory">The client factory function.</param>
6767
/// <returns>The updated <see cref="ChatClientBuilder"/> instance.</returns>
6868
/// <exception cref="ArgumentNullException"><paramref name="clientFactory"/> is <see langword="null"/>.</exception>
69+
/// <related type="Article" href="https://learn.microsoft.com/dotnet/ai/microsoft-extensions-ai#functionality-pipelines">Pipelines of functionality.</related>
6970
public ChatClientBuilder Use(Func<IChatClient, IChatClient> clientFactory)
7071
{
7172
_ = Throw.IfNull(clientFactory);
@@ -77,6 +78,7 @@ public ChatClientBuilder Use(Func<IChatClient, IChatClient> clientFactory)
7778
/// <param name="clientFactory">The client factory function.</param>
7879
/// <returns>The updated <see cref="ChatClientBuilder"/> instance.</returns>
7980
/// <exception cref="ArgumentNullException"><paramref name="clientFactory"/> is <see langword="null"/>.</exception>
81+
/// <related type="Article" href="https://learn.microsoft.com/dotnet/ai/microsoft-extensions-ai#functionality-pipelines">Pipelines of functionality.</related>
8082
public ChatClientBuilder Use(Func<IChatClient, IServiceProvider, IChatClient> clientFactory)
8183
{
8284
_ = Throw.IfNull(clientFactory);
@@ -98,10 +100,11 @@ public ChatClientBuilder Use(Func<IChatClient, IServiceProvider, IChatClient> cl
98100
/// </param>
99101
/// <returns>The updated <see cref="ChatClientBuilder"/> instance.</returns>
100102
/// <remarks>
101-
/// This overload may be used when the anonymous implementation needs to provide pre- and/or post-processing, but doesn't
103+
/// This overload can be used when the anonymous implementation needs to provide pre-processing and/or post-processing, but doesn't
102104
/// need to interact with the results of the operation, which will come from the inner client.
103105
/// </remarks>
104106
/// <exception cref="ArgumentNullException"><paramref name="sharedFunc"/> is <see langword="null"/>.</exception>
107+
/// <related type="Article" href="https://learn.microsoft.com/dotnet/ai/microsoft-extensions-ai#functionality-pipelines">Pipelines of functionality.</related>
105108
public ChatClientBuilder Use(Func<IEnumerable<ChatMessage>, ChatOptions?, Func<IEnumerable<ChatMessage>, ChatOptions?, CancellationToken, Task>, CancellationToken, Task> sharedFunc)
106109
{
107110
_ = Throw.IfNull(sharedFunc);
@@ -125,7 +128,7 @@ public ChatClientBuilder Use(Func<IEnumerable<ChatMessage>, ChatOptions?, Func<I
125128
/// </param>
126129
/// <returns>The updated <see cref="ChatClientBuilder"/> instance.</returns>
127130
/// <remarks>
128-
/// One or both delegates may be provided. If both are provided, they will be used for their respective methods:
131+
/// One or both delegates can be provided. If both are provided, they will be used for their respective methods:
129132
/// <paramref name="getResponseFunc"/> will provide the implementation of <see cref="IChatClient.GetResponseAsync"/>, and
130133
/// <paramref name="getStreamingResponseFunc"/> will provide the implementation of <see cref="IChatClient.GetStreamingResponseAsync"/>.
131134
/// If only one of the delegates is provided, it will be used for both methods. That means that if <paramref name="getResponseFunc"/>
@@ -135,6 +138,7 @@ public ChatClientBuilder Use(Func<IEnumerable<ChatMessage>, ChatOptions?, Func<I
135138
/// <see cref="IChatClient.GetResponseAsync"/> will be implemented by combining the updates from <paramref name="getStreamingResponseFunc"/>.
136139
/// </remarks>
137140
/// <exception cref="ArgumentNullException">Both <paramref name="getResponseFunc"/> and <paramref name="getStreamingResponseFunc"/> are <see langword="null"/>.</exception>
141+
/// <related type="Article" href="https://learn.microsoft.com/dotnet/ai/microsoft-extensions-ai#functionality-pipelines">Pipelines of functionality.</related>
138142
public ChatClientBuilder Use(
139143
Func<IEnumerable<ChatMessage>, ChatOptions?, IChatClient, CancellationToken, Task<ChatResponse>>? getResponseFunc,
140144
Func<IEnumerable<ChatMessage>, ChatOptions?, IChatClient, CancellationToken, IAsyncEnumerable<ChatResponseUpdate>>? getStreamingResponseFunc)

‎src/Libraries/Microsoft.Extensions.AI/ChatCompletion/ChatClientStructuredOutputExtensions.cs

Lines changed: 15 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ namespace Microsoft.Extensions.AI;
1818
/// <summary>
1919
/// Provides extension methods on <see cref="IChatClient"/> that simplify working with structured output.
2020
/// </summary>
21+
/// <related type="Article" href="https://learn.microsoft.com/dotnet/ai/quickstarts/structured-output">Request a response with structured output.</related>
2122
public static class ChatClientStructuredOutputExtensions
2223
{
2324
private static readonly AIJsonSchemaCreateOptions _inferenceOptions = new()
@@ -33,9 +34,8 @@ public static class ChatClientStructuredOutputExtensions
3334
/// <param name="messages">The chat content to send.</param>
3435
/// <param name="options">The chat options to configure the request.</param>
3536
/// <param name="useJsonSchema">
36-
/// Optionally specifies whether to set a JSON schema on the <see cref="ChatResponseFormat"/>.
37-
/// This improves reliability if the underlying model supports native structured output with a schema, but may cause an error if the model does not support it.
38-
/// If not specified, the default value is <see langword="true" />.
37+
/// <see langword="true" /> to set a JSON schema on the <see cref="ChatResponseFormat"/>; otherwise, <see langword="false" />. The default is <see langword="true" />.
38+
/// Using a JSON schema improves reliability if the underlying model supports native structured output with a schema, but might cause an error if the model does not support it.
3939
/// </param>
4040
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
4141
/// <returns>The response messages generated by the client.</returns>
@@ -53,14 +53,15 @@ public static Task<ChatResponse<T>> GetResponseAsync<T>(
5353
/// <param name="chatMessage">The text content for the chat message to send.</param>
5454
/// <param name="options">The chat options to configure the request.</param>
5555
/// <param name="useJsonSchema">
56-
/// Optionally specifies whether to set a JSON schema on the <see cref="ChatResponseFormat"/>.
57-
/// This improves reliability if the underlying model supports native structured output with a schema, but may cause an error if the model does not support it.
56+
/// <see langword="true" /> to set a JSON schema on the <see cref="ChatResponseFormat"/>; otherwise, <see langword="false" />.
57+
/// Using a JSON schema improves reliability if the underlying model supports native structured output with a schema, but might cause an error if the model does not support it.
5858
/// If not specified, the default value is determined by the implementation.
5959
/// If a specific value is required, it must be specified by the caller.
6060
/// </param>
6161
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
6262
/// <returns>The response messages generated by the client.</returns>
6363
/// <typeparam name="T">The type of structured output to request.</typeparam>
64+
/// <related type="Article" href="https://learn.microsoft.com/dotnet/ai/quickstarts/structured-output">Request a response with structured output.</related>
6465
public static Task<ChatResponse<T>> GetResponseAsync<T>(
6566
this IChatClient chatClient,
6667
string chatMessage,
@@ -74,9 +75,8 @@ public static Task<ChatResponse<T>> GetResponseAsync<T>(
7475
/// <param name="chatMessage">The chat message to send.</param>
7576
/// <param name="options">The chat options to configure the request.</param>
7677
/// <param name="useJsonSchema">
77-
/// Optionally specifies whether to set a JSON schema on the <see cref="ChatResponseFormat"/>.
78-
/// This improves reliability if the underlying model supports native structured output with a schema, but may cause an error if the model does not support it.
79-
/// If not specified, the default value is <see langword="true" />.
78+
/// <see langword="true" /> to set a JSON schema on the <see cref="ChatResponseFormat"/>; otherwise, <see langword="false" />. The default is <see langword="true" />.
79+
/// Using a JSON schema improves reliability if the underlying model supports native structured output with a schema, but might cause an error if the model does not support it.
8080
/// </param>
8181
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
8282
/// <returns>The response messages generated by the client.</returns>
@@ -95,9 +95,8 @@ public static Task<ChatResponse<T>> GetResponseAsync<T>(
9595
/// <param name="serializerOptions">The JSON serialization options to use.</param>
9696
/// <param name="options">The chat options to configure the request.</param>
9797
/// <param name="useJsonSchema">
98-
/// Optionally specifies whether to set a JSON schema on the <see cref="ChatResponseFormat"/>.
99-
/// This improves reliability if the underlying model supports native structured output with a schema, but may cause an error if the model does not support it.
100-
/// If not specified, the default value is <see langword="true" />.
98+
/// <see langword="true" /> to set a JSON schema on the <see cref="ChatResponseFormat"/>; otherwise, <see langword="false" />. The default is <see langword="true" />.
99+
/// Using a JSON schema improves reliability if the underlying model supports native structured output with a schema, but might cause an error if the model does not support it.
101100
/// </param>
102101
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
103102
/// <returns>The response messages generated by the client.</returns>
@@ -117,9 +116,8 @@ public static Task<ChatResponse<T>> GetResponseAsync<T>(
117116
/// <param name="serializerOptions">The JSON serialization options to use.</param>
118117
/// <param name="options">The chat options to configure the request.</param>
119118
/// <param name="useJsonSchema">
120-
/// Optionally specifies whether to set a JSON schema on the <see cref="ChatResponseFormat"/>.
121-
/// This improves reliability if the underlying model supports native structured output with a schema, but may cause an error if the model does not support it.
122-
/// If not specified, the default value is <see langword="true" />.
119+
/// <see langword="true" /> to set a JSON schema on the <see cref="ChatResponseFormat"/>; otherwise, <see langword="false" />. The default is <see langword="true" />.
120+
/// Using a JSON schema improves reliability if the underlying model supports native structured output with a schema, but might cause an error if the model does not support it.
123121
/// </param>
124122
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
125123
/// <returns>The response messages generated by the client.</returns>
@@ -139,16 +137,13 @@ public static Task<ChatResponse<T>> GetResponseAsync<T>(
139137
/// <param name="serializerOptions">The JSON serialization options to use.</param>
140138
/// <param name="options">The chat options to configure the request.</param>
141139
/// <param name="useJsonSchema">
142-
/// Optionally specifies whether to set a JSON schema on the <see cref="ChatResponseFormat"/>.
143-
/// This improves reliability if the underlying model supports native structured output with a schema, but may cause an error if the model does not support it.
144-
/// If not specified, the default value is <see langword="true" />.
140+
/// <see langword="true" /> to set a JSON schema on the <see cref="ChatResponseFormat"/>; otherwise, <see langword="false" />. The default is <see langword="true" />.
141+
/// Using a JSON schema improves reliability if the underlying model supports native structured output with a schema, but might cause an error if the model does not support it.
145142
/// </param>
146143
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
147144
/// <returns>The response messages generated by the client.</returns>
148145
/// <typeparam name="T">The type of structured output to request.</typeparam>
149-
/// <exception cref="ArgumentNullException"><paramref name="chatClient"/> is <see langword="null"/>.</exception>
150-
/// <exception cref="ArgumentNullException"><paramref name="messages"/> is <see langword="null"/>.</exception>
151-
/// <exception cref="ArgumentNullException"><paramref name="serializerOptions"/> is <see langword="null"/>.</exception>
146+
/// <exception cref="ArgumentNullException"><paramref name="chatClient"/> or <paramref name="messages"/> or <paramref name="serializerOptions"/> is <see langword="null"/>.</exception>
152147
public static async Task<ChatResponse<T>> GetResponseAsync<T>(
153148
this IChatClient chatClient,
154149
IEnumerable<ChatMessage> messages,

‎src/Libraries/Microsoft.Extensions.AI/ChatCompletion/ConfigureOptionsChatClientBuilderExtensions.cs

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ public static class ConfigureOptionsChatClientBuilderExtensions
2727
/// <returns>The <paramref name="builder"/>.</returns>
2828
/// <exception cref="ArgumentNullException"><paramref name="builder"/> is <see langword="null"/>.</exception>
2929
/// <exception cref="ArgumentNullException"><paramref name="configure"/> is <see langword="null"/>.</exception>
30+
/// <related type="Article" href="https://learn.microsoft.com/dotnet/ai/microsoft-extensions-ai#provide-options">Provide options.</related>
3031
public static ChatClientBuilder ConfigureOptions(
3132
this ChatClientBuilder builder, Action<ChatOptions> configure)
3233
{

0 commit comments

Comments
 (0)
0