Skip to content

Commit e69d3e9

Browse files
KrzysztofCwalinastephentoub
KrzysztofCwalina
and
stephentoub
authored
Added conversions from AIFunction to various OpenAI tools (#6539)
* added conversions from AIFunction to various OpenAI tools * Remove duplication of tool handling across OpenAI impls --------- Co-authored-by: Stephen Toub <[email protected]>
1 parent ae446fb commit e69d3e9

File tree

7 files changed

+244
-122
lines changed

7 files changed

+244
-122
lines changed

‎src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIAssistantChatClient.cs‎

Lines changed: 19 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,6 @@
99
using System.Runtime.CompilerServices;
1010
using System.Text;
1111
using System.Text.Json;
12-
using System.Text.Json.Serialization;
1312
using System.Threading;
1413
using System.Threading.Tasks;
1514
using Microsoft.Shared.Diagnostics;
@@ -30,7 +29,7 @@ namespace Microsoft.Extensions.AI;
3029

3130
/// <summary>Represents an <see cref="IChatClient"/> for an Azure.AI.Agents.Persistent <see cref="AssistantClient"/>.</summary>
3231
[Experimental("OPENAI001")]
33-
internal sealed partial class OpenAIAssistantChatClient : IChatClient
32+
internal sealed class OpenAIAssistantChatClient : IChatClient
3433
{
3534
/// <summary>The underlying <see cref="AssistantClient" />.</summary>
3635
private readonly AssistantClient _client;
@@ -197,9 +196,9 @@ public async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
197196
{
198197
ruUpdate.Contents.Add(
199198
new FunctionCallContent(
200-
JsonSerializer.Serialize([ru.Value.Id, toolCallId], AssistantJsonContext.Default.StringArray),
199+
JsonSerializer.Serialize([ru.Value.Id, toolCallId], OpenAIJsonContext.Default.StringArray),
201200
functionName,
202-
JsonSerializer.Deserialize(rau.FunctionArguments, AssistantJsonContext.Default.IDictionaryStringObject)!));
201+
JsonSerializer.Deserialize(rau.FunctionArguments, OpenAIJsonContext.Default.IDictionaryStringObject)!));
203202
}
204203

205204
yield return ruUpdate;
@@ -237,6 +236,19 @@ void IDisposable.Dispose()
237236
// nop
238237
}
239238

239+
/// <summary>Converts an Extensions function to an OpenAI assistants function tool.</summary>
240+
internal static FunctionToolDefinition ToOpenAIAssistantsFunctionToolDefinition(AIFunction aiFunction)
241+
{
242+
(BinaryData parameters, bool? strict) = OpenAIClientExtensions.ToOpenAIFunctionParameters(aiFunction);
243+
244+
return new FunctionToolDefinition(aiFunction.Name)
245+
{
246+
Description = aiFunction.Description,
247+
Parameters = parameters,
248+
StrictParameterSchemaEnabled = strict,
249+
};
250+
}
251+
240252
/// <summary>
241253
/// Creates the <see cref="RunCreationOptions"/> to use for the request and extracts any function result contents
242254
/// that need to be submitted as tool results.
@@ -284,18 +296,7 @@ void IDisposable.Dispose()
284296
switch (tool)
285297
{
286298
case AIFunction aiFunction:
287-
bool? strict = aiFunction.AdditionalProperties.TryGetValue(OpenAIClientExtensions.StrictKey, out var strictValue) && strictValue is bool strictBool ?
288-
strictBool :
289-
null;
290-
291-
JsonElement jsonSchema = OpenAIClientExtensions.GetSchema(aiFunction, strict);
292-
293-
runOptions.ToolsOverride.Add(new FunctionToolDefinition(aiFunction.Name)
294-
{
295-
Description = aiFunction.Description,
296-
Parameters = BinaryData.FromBytes(JsonSerializer.SerializeToUtf8Bytes(jsonSchema, AssistantJsonContext.Default.JsonElement)),
297-
StrictParameterSchemaEnabled = strict,
298-
});
299+
runOptions.ToolsOverride.Add(ToOpenAIAssistantsFunctionToolDefinition(aiFunction));
299300
break;
300301

301302
case HostedCodeInterpreterTool:
@@ -340,7 +341,7 @@ void IDisposable.Dispose()
340341
case ChatResponseFormatJson jsonFormat when OpenAIClientExtensions.StrictSchemaTransformCache.GetOrCreateTransformedSchema(jsonFormat) is { } jsonSchema:
341342
runOptions.ResponseFormat = AssistantResponseFormat.CreateJsonSchemaFormat(
342343
jsonFormat.SchemaName,
343-
BinaryData.FromBytes(JsonSerializer.SerializeToUtf8Bytes(jsonSchema, AssistantJsonContext.Default.JsonElement)),
344+
BinaryData.FromBytes(JsonSerializer.SerializeToUtf8Bytes(jsonSchema, OpenAIJsonContext.Default.JsonElement)),
344345
jsonFormat.SchemaDescription);
345346
break;
346347

@@ -453,7 +454,7 @@ void AppendSystemInstructions(string? toAppend)
453454
string[]? runAndCallIDs;
454455
try
455456
{
456-
runAndCallIDs = JsonSerializer.Deserialize(frc.CallId, AssistantJsonContext.Default.StringArray);
457+
runAndCallIDs = JsonSerializer.Deserialize(frc.CallId, OpenAIJsonContext.Default.StringArray);
457458
}
458459
catch
459460
{
@@ -476,9 +477,4 @@ void AppendSystemInstructions(string? toAppend)
476477

477478
return runId;
478479
}
479-
480-
[JsonSerializable(typeof(JsonElement))]
481-
[JsonSerializable(typeof(string[]))]
482-
[JsonSerializable(typeof(IDictionary<string, object>))]
483-
private sealed partial class AssistantJsonContext : JsonSerializerContext;
484480
}

‎src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIChatClient.cs‎

Lines changed: 12 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@
77
using System.Runtime.CompilerServices;
88
using System.Text;
99
using System.Text.Json;
10-
using System.Text.Json.Serialization;
1110
using System.Threading;
1211
using System.Threading.Tasks;
1312
using Microsoft.Shared.Diagnostics;
@@ -23,7 +22,7 @@
2322
namespace Microsoft.Extensions.AI;
2423

2524
/// <summary>Represents an <see cref="IChatClient"/> for an OpenAI <see cref="OpenAIClient"/> or <see cref="ChatClient"/>.</summary>
26-
internal sealed partial class OpenAIChatClient : IChatClient
25+
internal sealed class OpenAIChatClient : IChatClient
2726
{
2827
/// <summary>Metadata about the client.</summary>
2928
private readonly ChatClientMetadata _metadata;
@@ -101,6 +100,14 @@ void IDisposable.Dispose()
101100
// Nothing to dispose. Implementation required for the IChatClient interface.
102101
}
103102

103+
/// <summary>Converts an Extensions function to an OpenAI chat tool.</summary>
104+
internal static ChatTool ToOpenAIChatTool(AIFunction aiFunction)
105+
{
106+
(BinaryData parameters, bool? strict) = OpenAIClientExtensions.ToOpenAIFunctionParameters(aiFunction);
107+
108+
return ChatTool.CreateFunctionTool(aiFunction.Name, aiFunction.Description, parameters, strict);
109+
}
110+
104111
/// <summary>Converts an Extensions chat message enumerable to an OpenAI chat message enumerable.</summary>
105112
private static IEnumerable<OpenAI.Chat.ChatMessage> ToOpenAIChatMessages(IEnumerable<ChatMessage> inputs, ChatOptions? chatOptions, JsonSerializerOptions jsonOptions)
106113
{
@@ -547,8 +554,7 @@ private ChatCompletionOptions ToOpenAIOptions(ChatOptions? options)
547554
result.ResponseFormat = OpenAIClientExtensions.StrictSchemaTransformCache.GetOrCreateTransformedSchema(jsonFormat) is { } jsonSchema ?
548555
OpenAI.Chat.ChatResponseFormat.CreateJsonSchemaFormat(
549556
jsonFormat.SchemaName ?? "json_schema",
550-
BinaryData.FromBytes(
551-
JsonSerializer.SerializeToUtf8Bytes(jsonSchema, ChatClientJsonContext.Default.JsonElement)),
557+
BinaryData.FromBytes(JsonSerializer.SerializeToUtf8Bytes(jsonSchema, OpenAIJsonContext.Default.JsonElement)),
552558
jsonFormat.SchemaDescription) :
553559
OpenAI.Chat.ChatResponseFormat.CreateJsonObjectFormat();
554560
}
@@ -557,23 +563,6 @@ private ChatCompletionOptions ToOpenAIOptions(ChatOptions? options)
557563
return result;
558564
}
559565

560-
/// <summary>Converts an Extensions function to an OpenAI chat tool.</summary>
561-
private static ChatTool ToOpenAIChatTool(AIFunction aiFunction)
562-
{
563-
bool? strict =
564-
aiFunction.AdditionalProperties.TryGetValue(OpenAIClientExtensions.StrictKey, out object? strictObj) &&
565-
strictObj is bool strictValue ?
566-
strictValue : null;
567-
568-
// Perform transformations making the schema legal per OpenAI restrictions
569-
JsonElement jsonSchema = OpenAIClientExtensions.GetSchema(aiFunction, strict);
570-
571-
// Map to an intermediate model so that redundant properties are skipped.
572-
var tool = JsonSerializer.Deserialize(jsonSchema, ChatClientJsonContext.Default.ChatToolJson)!;
573-
var functionParameters = BinaryData.FromBytes(JsonSerializer.SerializeToUtf8Bytes(tool, ChatClientJsonContext.Default.ChatToolJson));
574-
return ChatTool.CreateFunctionTool(aiFunction.Name, aiFunction.Description, functionParameters, strict);
575-
}
576-
577566
private static UsageDetails FromOpenAIUsage(ChatTokenUsage tokenUsage)
578567
{
579568
var destination = new UsageDetails
@@ -668,27 +657,11 @@ private static ChatRole FromOpenAIChatRole(ChatMessageRole role) =>
668657

669658
private static FunctionCallContent ParseCallContentFromJsonString(string json, string callId, string name) =>
670659
FunctionCallContent.CreateFromParsedArguments(json, callId, name,
671-
argumentParser: static json => JsonSerializer.Deserialize(json, ChatClientJsonContext.Default.IDictionaryStringObject)!);
660+
argumentParser: static json => JsonSerializer.Deserialize(json, OpenAIJsonContext.Default.IDictionaryStringObject)!);
672661

673662
private static FunctionCallContent ParseCallContentFromBinaryData(BinaryData ut8Json, string callId, string name) =>
674663
FunctionCallContent.CreateFromParsedArguments(ut8Json, callId, name,
675-
argumentParser: static json => JsonSerializer.Deserialize(json, ChatClientJsonContext.Default.IDictionaryStringObject)!);
676-
677-
/// <summary>Used to create the JSON payload for an OpenAI chat tool description.</summary>
678-
private sealed class ChatToolJson
679-
{
680-
[JsonPropertyName("type")]
681-
public string Type { get; set; } = "object";
682-
683-
[JsonPropertyName("required")]
684-
public HashSet<string> Required { get; set; } = [];
685-
686-
[JsonPropertyName("properties")]
687-
public Dictionary<string, JsonElement> Properties { get; set; } = [];
688-
689-
[JsonPropertyName("additionalProperties")]
690-
public bool AdditionalProperties { get; set; }
691-
}
664+
argumentParser: static json => JsonSerializer.Deserialize(json, OpenAIJsonContext.Default.IDictionaryStringObject)!);
692665

693666
/// <summary>POCO representing function calling info. Used to concatenation information for a single function call from across multiple streaming updates.</summary>
694667
private sealed class FunctionCallInfo
@@ -697,14 +670,4 @@ private sealed class FunctionCallInfo
697670
public string? Name;
698671
public StringBuilder? Arguments;
699672
}
700-
701-
/// <summary>Source-generated JSON type information.</summary>
702-
[JsonSourceGenerationOptions(JsonSerializerDefaults.Web,
703-
UseStringEnumConverter = true,
704-
DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
705-
WriteIndented = true)]
706-
[JsonSerializable(typeof(ChatToolJson))]
707-
[JsonSerializable(typeof(IDictionary<string, object?>))]
708-
[JsonSerializable(typeof(string[]))]
709-
private sealed partial class ChatClientJsonContext : JsonSerializerContext;
710673
}

‎src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIClientExtensions.cs‎

Lines changed: 79 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,19 @@
22
// The .NET Foundation licenses this file to you under the MIT license.
33

44
using System;
5+
using System.Collections.Generic;
56
using System.Diagnostics.CodeAnalysis;
67
using System.Text;
78
using System.Text.Json;
89
using System.Text.Json.Nodes;
10+
using System.Text.Json.Serialization;
11+
using Microsoft.Shared.Diagnostics;
912
using OpenAI;
1013
using OpenAI.Assistants;
1114
using OpenAI.Audio;
1215
using OpenAI.Chat;
1316
using OpenAI.Embeddings;
17+
using OpenAI.RealtimeConversation;
1418
using OpenAI.Responses;
1519

1620
#pragma warning disable S103 // Lines should not be too long
@@ -24,7 +28,7 @@ namespace Microsoft.Extensions.AI;
2428
public static class OpenAIClientExtensions
2529
{
2630
/// <summary>Key into AdditionalProperties used to store a strict option.</summary>
27-
internal const string StrictKey = "strictJsonSchema";
31+
private const string StrictKey = "strictJsonSchema";
2832

2933
/// <summary>Gets the default OpenAI endpoint.</summary>
3034
internal static Uri DefaultOpenAIEndpoint { get; } = new("https://api.openai.com/v1");
@@ -106,12 +110,14 @@ static void AppendLine(ref StringBuilder? sb, string propName, JsonNode propNode
106110
/// <summary>Gets an <see cref="IChatClient"/> for use with this <see cref="ChatClient"/>.</summary>
107111
/// <param name="chatClient">The client.</param>
108112
/// <returns>An <see cref="IChatClient"/> that can be used to converse via the <see cref="ChatClient"/>.</returns>
113+
/// <exception cref="ArgumentNullException"><paramref name="chatClient"/> is <see langword="null"/>.</exception>
109114
public static IChatClient AsIChatClient(this ChatClient chatClient) =>
110115
new OpenAIChatClient(chatClient);
111116

112117
/// <summary>Gets an <see cref="IChatClient"/> for use with this <see cref="OpenAIResponseClient"/>.</summary>
113118
/// <param name="responseClient">The client.</param>
114119
/// <returns>An <see cref="IChatClient"/> that can be used to converse via the <see cref="OpenAIResponseClient"/>.</returns>
120+
/// <exception cref="ArgumentNullException"><paramref name="responseClient"/> is <see langword="null"/>.</exception>
115121
public static IChatClient AsIChatClient(this OpenAIResponseClient responseClient) =>
116122
new OpenAIResponseChatClient(responseClient);
117123

@@ -124,13 +130,17 @@ public static IChatClient AsIChatClient(this OpenAIResponseClient responseClient
124130
/// property. If no thread ID is provided via either mechanism, a new thread will be created for the request.
125131
/// </param>
126132
/// <returns>An <see cref="IChatClient"/> instance configured to interact with the specified agent and thread.</returns>
127-
[Experimental("OPENAI001")]
133+
/// <exception cref="ArgumentNullException"><paramref name="assistantClient"/> is <see langword="null"/>.</exception>
134+
/// <exception cref="ArgumentNullException"><paramref name="assistantId"/> is <see langword="null"/>.</exception>
135+
/// <exception cref="ArgumentException"><paramref name="assistantId"/> is empty or composed entirely of whitespace.</exception>
136+
[Experimental("OPENAI001")] // AssistantClient itself is experimental with this ID
128137
public static IChatClient AsIChatClient(this AssistantClient assistantClient, string assistantId, string? threadId = null) =>
129138
new OpenAIAssistantChatClient(assistantClient, assistantId, threadId);
130139

131140
/// <summary>Gets an <see cref="ISpeechToTextClient"/> for use with this <see cref="AudioClient"/>.</summary>
132141
/// <param name="audioClient">The client.</param>
133142
/// <returns>An <see cref="ISpeechToTextClient"/> that can be used to transcribe audio via the <see cref="AudioClient"/>.</returns>
143+
/// <exception cref="ArgumentNullException"><paramref name="audioClient"/> is <see langword="null"/>.</exception>
134144
[Experimental("MEAI001")]
135145
public static ISpeechToTextClient AsISpeechToTextClient(this AudioClient audioClient) =>
136146
new OpenAISpeechToTextClient(audioClient);
@@ -139,12 +149,74 @@ public static ISpeechToTextClient AsISpeechToTextClient(this AudioClient audioCl
139149
/// <param name="embeddingClient">The client.</param>
140150
/// <param name="defaultModelDimensions">The number of dimensions to generate in each embedding.</param>
141151
/// <returns>An <see cref="IEmbeddingGenerator{String, Embedding}"/> that can be used to generate embeddings via the <see cref="EmbeddingClient"/>.</returns>
152+
/// <exception cref="ArgumentNullException"><paramref name="embeddingClient"/> is <see langword="null"/>.</exception>
142153
public static IEmbeddingGenerator<string, Embedding<float>> AsIEmbeddingGenerator(this EmbeddingClient embeddingClient, int? defaultModelDimensions = null) =>
143154
new OpenAIEmbeddingGenerator(embeddingClient, defaultModelDimensions);
144155

145-
/// <summary>Gets the JSON schema to use from the function.</summary>
146-
internal static JsonElement GetSchema(AIFunction function, bool? strict) =>
147-
strict is true ?
148-
StrictSchemaTransformCache.GetOrCreateTransformedSchema(function) :
149-
function.JsonSchema;
156+
/// <summary>Creates an OpenAI <see cref="ChatTool"/> from an <see cref="AIFunction"/>.</summary>
157+
/// <param name="function">The function to convert.</param>
158+
/// <returns>An OpenAI <see cref="ChatTool"/> representing <paramref name="function"/>.</returns>
159+
/// <exception cref="ArgumentNullException"><paramref name="function"/> is <see langword="null"/>.</exception>
160+
public static ChatTool AsOpenAIChatTool(this AIFunction function) =>
161+
OpenAIChatClient.ToOpenAIChatTool(Throw.IfNull(function));
162+
163+
/// <summary>Creates an OpenAI <see cref="FunctionToolDefinition"/> from an <see cref="AIFunction"/>.</summary>
164+
/// <param name="function">The function to convert.</param>
165+
/// <returns>An OpenAI <see cref="FunctionToolDefinition"/> representing <paramref name="function"/>.</returns>
166+
/// <exception cref="ArgumentNullException"><paramref name="function"/> is <see langword="null"/>.</exception>
167+
[Experimental("OPENAI001")] // AssistantClient itself is experimental with this ID
168+
public static FunctionToolDefinition AsOpenAIAssistantsFunctionToolDefinition(this AIFunction function) =>
169+
OpenAIAssistantChatClient.ToOpenAIAssistantsFunctionToolDefinition(Throw.IfNull(function));
170+
171+
/// <summary>Creates an OpenAI <see cref="ResponseTool"/> from an <see cref="AIFunction"/>.</summary>
172+
/// <param name="function">The function to convert.</param>
173+
/// <returns>An OpenAI <see cref="ResponseTool"/> representing <paramref name="function"/>.</returns>
174+
/// <exception cref="ArgumentNullException"><paramref name="function"/> is <see langword="null"/>.</exception>
175+
public static ResponseTool AsOpenAIResponseTool(this AIFunction function) =>
176+
OpenAIResponseChatClient.ToResponseTool(Throw.IfNull(function));
177+
178+
/// <summary>Creates an OpenAI <see cref="ConversationFunctionTool"/> from an <see cref="AIFunction"/>.</summary>
179+
/// <param name="function">The function to convert.</param>
180+
/// <returns>An OpenAI <see cref="ConversationFunctionTool"/> representing <paramref name="function"/>.</returns>
181+
/// <exception cref="ArgumentNullException"><paramref name="function"/> is <see langword="null"/>.</exception>
182+
public static ConversationFunctionTool AsOpenAIConversationFunctionTool(this AIFunction function) =>
183+
OpenAIRealtimeConversationClient.ToOpenAIConversationFunctionTool(Throw.IfNull(function));
184+
185+
/// <summary>Extracts from an <see cref="AIFunction"/> the parameters and strictness setting for use with OpenAI's APIs.</summary>
186+
internal static (BinaryData Parameters, bool? Strict) ToOpenAIFunctionParameters(AIFunction aiFunction)
187+
{
188+
// Extract any strict setting from AdditionalProperties.
189+
bool? strict =
190+
aiFunction.AdditionalProperties.TryGetValue(OpenAIClientExtensions.StrictKey, out object? strictObj) &&
191+
strictObj is bool strictValue ?
192+
strictValue : null;
193+
194+
// Perform any desirable transformations on the function's JSON schema, if it'll be used in a strict setting.
195+
JsonElement jsonSchema = strict is true ?
196+
StrictSchemaTransformCache.GetOrCreateTransformedSchema(aiFunction) :
197+
aiFunction.JsonSchema;
198+
199+
// Roundtrip the schema through the ToolJson model type to remove extra properties
200+
// and force missing ones into existence, then return the serialized UTF8 bytes as BinaryData.
201+
var tool = JsonSerializer.Deserialize(jsonSchema, OpenAIJsonContext.Default.ToolJson)!;
202+
var functionParameters = BinaryData.FromBytes(JsonSerializer.SerializeToUtf8Bytes(tool, OpenAIJsonContext.Default.ToolJson));
203+
204+
return (functionParameters, strict);
205+
}
206+
207+
/// <summary>Used to create the JSON payload for an OpenAI tool description.</summary>
208+
internal sealed class ToolJson
209+
{
210+
[JsonPropertyName("type")]
211+
public string Type { get; set; } = "object";
212+
213+
[JsonPropertyName("required")]
214+
public HashSet<string> Required { get; set; } = [];
215+
216+
[JsonPropertyName("properties")]
217+
public Dictionary<string, JsonElement> Properties { get; set; } = [];
218+
219+
[JsonPropertyName("additionalProperties")]
220+
public bool AdditionalProperties { get; set; }
221+
}
150222
}

0 commit comments

Comments
 (0)