|
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
using System.Collections.Generic;
using System.ComponentModel;
using System.Reflection;
using System.Text.Json;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Shared.Diagnostics;
namespace Microsoft.Extensions.AI;
/// <summary>
/// Provides extension methods on <see cref="IChatClient"/> that simplify working with structured output.
/// </summary>
public static class ChatClientStructuredOutputExtensions
{
private static readonly AIJsonSchemaCreateOptions _inferenceOptions = new()
{
IncludeSchemaKeyword = true,
DisallowAdditionalProperties = true,
IncludeTypeInEnumSchemas = true
};
/// <summary>Sends chat messages to the model, requesting a response matching the type <typeparamref name="T"/>.</summary>
/// <param name="chatClient">The <see cref="IChatClient"/>.</param>
/// <param name="chatMessages">The chat content to send.</param>
/// <param name="options">The chat options to configure the request.</param>
/// <param name="useNativeJsonSchema">
/// Optionally specifies whether to set a JSON schema on the <see cref="ChatResponseFormat"/>.
/// 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.
/// If not specified, the underlying provider's default will be used.
/// </param>
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
/// <returns>The response messages generated by the client.</returns>
/// <remarks>
/// The returned messages will not have been added to <paramref name="chatMessages"/>. 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.
/// </remarks>
/// <typeparam name="T">The type of structured output to request.</typeparam>
public static Task<ChatCompletion<T>> CompleteAsync<T>(
this IChatClient chatClient,
IList<ChatMessage> chatMessages,
ChatOptions? options = null,
bool? useNativeJsonSchema = null,
CancellationToken cancellationToken = default)
where T : class =>
CompleteAsync<T>(chatClient, chatMessages, AIJsonUtilities.DefaultOptions, options, useNativeJsonSchema, cancellationToken);
/// <summary>Sends a user chat text message to the model, requesting a response matching the type <typeparamref name="T"/>.</summary>
/// <param name="chatClient">The <see cref="IChatClient"/>.</param>
/// <param name="chatMessage">The text content for the chat message to send.</param>
/// <param name="options">The chat options to configure the request.</param>
/// <param name="useNativeJsonSchema">
/// Optionally specifies whether to set a JSON schema on the <see cref="ChatResponseFormat"/>.
/// 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.
/// If not specified, the underlying provider's default will be used.
/// </param>
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
/// <returns>The response messages generated by the client.</returns>
/// <typeparam name="T">The type of structured output to request.</typeparam>
public static Task<ChatCompletion<T>> CompleteAsync<T>(
this IChatClient chatClient,
string chatMessage,
ChatOptions? options = null,
bool? useNativeJsonSchema = null,
CancellationToken cancellationToken = default)
where T : class =>
CompleteAsync<T>(chatClient, [new ChatMessage(ChatRole.User, chatMessage)], options, useNativeJsonSchema, cancellationToken);
/// <summary>Sends a user chat text message to the model, requesting a response matching the type <typeparamref name="T"/>.</summary>
/// <param name="chatClient">The <see cref="IChatClient"/>.</param>
/// <param name="chatMessage">The text content for the chat message to send.</param>
/// <param name="serializerOptions">The JSON serialization options to use.</param>
/// <param name="options">The chat options to configure the request.</param>
/// <param name="useNativeJsonSchema">
/// Optionally specifies whether to set a JSON schema on the <see cref="ChatResponseFormat"/>.
/// 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.
/// If not specified, the underlying provider's default will be used.
/// </param>
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
/// <returns>The response messages generated by the client.</returns>
/// <typeparam name="T">The type of structured output to request.</typeparam>
public static Task<ChatCompletion<T>> CompleteAsync<T>(
this IChatClient chatClient,
string chatMessage,
JsonSerializerOptions serializerOptions,
ChatOptions? options = null,
bool? useNativeJsonSchema = null,
CancellationToken cancellationToken = default)
where T : class =>
CompleteAsync<T>(chatClient, [new ChatMessage(ChatRole.User, chatMessage)], serializerOptions, options, useNativeJsonSchema, cancellationToken);
/// <summary>Sends chat messages to the model, requesting a response matching the type <typeparamref name="T"/>.</summary>
/// <param name="chatClient">The <see cref="IChatClient"/>.</param>
/// <param name="chatMessages">The chat content to send.</param>
/// <param name="serializerOptions">The JSON serialization options to use.</param>
/// <param name="options">The chat options to configure the request.</param>
/// <param name="useNativeJsonSchema">
/// Optionally specifies whether to set a JSON schema on the <see cref="ChatResponseFormat"/>.
/// 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.
/// If not specified, the underlying provider's default will be used.
/// </param>
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
/// <returns>The response messages generated by the client.</returns>
/// <remarks>
/// The returned messages will not have been added to <paramref name="chatMessages"/>. 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.
/// </remarks>
/// <typeparam name="T">The type of structured output to request.</typeparam>
public static async Task<ChatCompletion<T>> CompleteAsync<T>(
this IChatClient chatClient,
IList<ChatMessage> chatMessages,
JsonSerializerOptions serializerOptions,
ChatOptions? options = null,
bool? useNativeJsonSchema = null,
CancellationToken cancellationToken = default)
where T : class
{
_ = Throw.IfNull(chatClient);
_ = Throw.IfNull(chatMessages);
_ = Throw.IfNull(serializerOptions);
serializerOptions.MakeReadOnly();
var schemaNode = AIJsonUtilities.CreateJsonSchema(
type: typeof(T),
serializerOptions: serializerOptions,
inferenceOptions: _inferenceOptions);
var schema = JsonSerializer.Serialize(schemaNode, AIJsonUtilities.DefaultOptions.GetTypeInfo(typeof(JsonElement)));
ChatMessage? promptAugmentation = null;
options = (options ?? new()).Clone();
// Currently there's no way for the inner IChatClient to specify whether structured output
// is supported, so we always default to false. In the future, some mechanism of declaring
// capabilities may be added (e.g., on ChatClientMetadata).
if (useNativeJsonSchema.GetValueOrDefault(false))
{
// When using native structured output, we don't add any additional prompt, because
// the LLM backend is meant to do whatever's needed to explain the schema to the LLM.
options.ResponseFormat = ChatResponseFormat.ForJsonSchema(
schema,
schemaName: AIFunctionFactory.SanitizeMemberName(typeof(T).Name),
schemaDescription: typeof(T).GetCustomAttribute<DescriptionAttribute>()?.Description);
}
else
{
options.ResponseFormat = ChatResponseFormat.Json;
// When not using native structured output, augment the chat messages with a schema prompt
#pragma warning disable SA1118 // Parameter should not span multiple lines
promptAugmentation = new ChatMessage(ChatRole.System, $$"""
Respond with a JSON value conforming to the following schema:
```
{{schema}}
```
""");
#pragma warning restore SA1118 // Parameter should not span multiple lines
chatMessages.Add(promptAugmentation);
}
try
{
var result = await chatClient.CompleteAsync(chatMessages, options, cancellationToken).ConfigureAwait(false);
return new ChatCompletion<T>(result, serializerOptions);
}
finally
{
if (promptAugmentation is not null)
{
_ = chatMessages.Remove(promptAugmentation);
}
}
}
}
|