Repository navigation
Expand file tree
/
Copy pathAIFunctionFactory.cs
More file actions
1478 lines (1338 loc) · 86.9 KB
/
Copy pathAIFunctionFactory.cs
File metadata and controls
1478 lines (1338 loc) · 86.9 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
using System;
using System.Buffers;
using System.Collections.Concurrent;
using System.Collections.Generic;
using System.ComponentModel;
using System.Diagnostics;
using System.IO;
#if !NET
using System.Linq;
#endif
using System.Reflection;
using System.Runtime.CompilerServices;
using System.Text.Json;
using System.Text.Json.Nodes;
using System.Text.Json.Serialization;
using System.Text.Json.Serialization.Metadata;
using System.Text.RegularExpressions;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Shared.Collections;
using Microsoft.Shared.Diagnostics;
#pragma warning disable S3011 // Reflection should not be used to increase accessibility of classes, methods, or fields
namespace Microsoft.Extensions.AI;
/// <summary>Provides factory methods for creating commonly-used implementations of <see cref="AIFunction"/>.</summary>
/// <remarks>
/// <para>
/// The <see cref="AIFunctionFactory"/> class creates <see cref="AIFunction"/> instances that wrap .NET methods
/// (specified as <see cref="Delegate"/> or <see cref="MethodInfo"/>). As part of this process, JSON schemas are
/// automatically derived for both the function's input parameters (exposed via <see cref="AIFunctionDeclaration.JsonSchema"/>)
/// and, by default, the function's return type (exposed via <see cref="AIFunctionDeclaration.ReturnJsonSchema"/>).
/// These schemas are produced using the <see cref="AIFunctionFactoryOptions.SerializerOptions"/> and
/// <see cref="AIFunctionFactoryOptions.JsonSchemaCreateOptions"/>, and enable AI services to understand and
/// interact with the function. Return value serialization and schema derivation behavior can be customized
/// via <see cref="AIFunctionFactoryOptions.MarshalResult"/> and <see cref="AIFunctionFactoryOptions.ExcludeResultSchema"/>,
/// respectively.
/// </para>
/// </remarks>
/// <related type="Article" href="https://learn.microsoft.com/dotnet/ai/quickstarts/use-function-calling">Invoke .NET functions using an AI model.</related>
public static partial class AIFunctionFactory
{
// NOTE:
// Unlike most library code, AIFunctionFactory uses ConfigureAwait(true) rather than ConfigureAwait(false). This is to
// enable AIFunctionFactory to be used with methods that might be context-aware, such as those employing a UI framework.
/// <summary>Holds the default options instance used when creating function.</summary>
private static readonly AIFunctionFactoryOptions _defaultOptions = new();
/// <summary>Creates an <see cref="AIFunction"/> instance for a method, specified via a delegate.</summary>
/// <param name="method">The method to be represented via the created <see cref="AIFunction"/>.</param>
/// <param name="options">Metadata to use to override defaults inferred from <paramref name="method"/>.</param>
/// <returns>The created <see cref="AIFunction"/> for invoking <paramref name="method"/>.</returns>
/// <remarks>
/// <para>
/// By default, any parameters to <paramref name="method"/> are sourced from the <see cref="AIFunctionArguments"/>'s dictionary
/// of key/value pairs and are represented in the JSON schema for the function, as exposed in the returned <see cref="AIFunction"/>'s
/// <see cref="AIFunctionDeclaration.JsonSchema"/>. There are a few exceptions to this:
/// <list type="bullet">
/// <item>
/// <see cref="CancellationToken"/> parameters are automatically bound to the <see cref="CancellationToken"/> passed into
/// the invocation via <see cref="AIFunction.InvokeAsync"/>'s <see cref="CancellationToken"/> parameter. The parameter is
/// not included in the generated JSON schema. The behavior of <see cref="CancellationToken"/> parameters can't be overridden.
/// </item>
/// <item>
/// By default, <see cref="IServiceProvider"/> parameters are bound from the <see cref="AIFunctionArguments.Services"/> property
/// and are not included in the JSON schema. If the parameter is optional, such that a default value is provided,
/// <see cref="AIFunctionArguments.Services"/> is allowed to be <see langword="null"/>; otherwise, <see cref="AIFunctionArguments.Services"/>
/// must be non-<see langword="null"/>, or else the invocation will fail with an exception due to the required nature of the parameter.
/// The handling of <see cref="IServiceProvider"/> parameters can be overridden via <see cref="AIFunctionFactoryOptions.ConfigureParameterBinding"/>.
/// </item>
/// <item>
/// By default, <see cref="AIFunctionArguments"/> parameters are bound directly to <see cref="AIFunctionArguments"/> instance
/// passed into <see cref="AIFunction.InvokeAsync"/> and are not included in the JSON schema. If the <see cref="AIFunctionArguments"/>
/// instance passed to <see cref="AIFunction.InvokeAsync"/> is <see langword="null"/>, the <see cref="AIFunction"/> implementation
/// manufactures an empty instance, such that parameters of type <see cref="AIFunctionArguments"/> can always be satisfied, whether
/// optional or not. The handling of <see cref="AIFunctionArguments"/> parameters can be overridden via
/// <see cref="AIFunctionFactoryOptions.ConfigureParameterBinding"/>.
/// </item>
/// </list>
/// All other parameter types are, by default, bound from the <see cref="AIFunctionArguments"/> dictionary passed into <see cref="AIFunction.InvokeAsync"/>
/// and are included in the generated JSON schema. This can be overridden by the <see cref="AIFunctionFactoryOptions.ConfigureParameterBinding"/> provided
/// via the <paramref name="options"/> parameter; for every parameter, the delegate is enabled to choose if the parameter should be included in the
/// generated schema and how its value should be bound, including handling of optionality (by default, required parameters that are not included in the
/// <see cref="AIFunctionArguments"/> dictionary will result in an exception being thrown). Loosely-typed additional context information can be passed
/// into <see cref="AIFunction.InvokeAsync"/> via the <see cref="AIFunctionArguments"/>'s <see cref="AIFunctionArguments.Context"/> dictionary; the default
/// binding ignores this collection, but a custom binding supplied via <see cref="AIFunctionFactoryOptions.ConfigureParameterBinding"/> can choose to
/// source arguments from this data.
/// </para>
/// <para>
/// The default marshaling of parameters from the <see cref="AIFunctionArguments"/> dictionary permits values to be passed into the <paramref name="method"/>'s
/// invocation directly if the object is already of a compatible type. Otherwise, if the argument is a <see cref="JsonElement"/>, <see cref="JsonDocument"/>,
/// or <see cref="JsonNode"/>, it is deserialized into the parameter type, utilizing <see cref="AIFunctionFactoryOptions.SerializerOptions"/> if provided,
/// or else using <see cref="AIJsonUtilities.DefaultOptions"/>. If the argument is anything else, it is round-tripped through JSON, serializing the object as JSON
/// and then deserializing it to the expected type.
/// </para>
/// <para>
/// In general, the data supplied via an <see cref="AIFunctionArguments"/>'s dictionary is supplied from an AI service and should be considered
/// unvalidated and untrusted. To provide validated and trusted data to the invocation of <paramref name="method"/>, consider having <paramref name="method"/>
/// point to an instance method on an instance configured to hold the appropriate state. An <see cref="IServiceProvider"/> parameter can also be
/// used to resolve services from a dependency injection container.
/// </para>
/// <para>
/// By default, return values are serialized to <see cref="JsonElement"/> using <paramref name="options"/>'s
/// <see cref="AIFunctionFactoryOptions.SerializerOptions"/> if provided, or else using <see cref="AIJsonUtilities.DefaultOptions"/>.
/// However, return values whose declared type is <see cref="AIContent"/>, a derived type of <see cref="AIContent"/>, or
/// any type assignable from <see cref="IEnumerable{AIContent}"/> (e.g. <c>AIContent[]</c>, <c>List<AIContent></c>) are
/// special-cased and are not serialized: the created function returns the original instance(s) directly to enable
/// callers (such as an <c>IChatClient</c>) to perform type tests and implement specialized handling. If
/// <see cref="AIFunctionFactoryOptions.MarshalResult"/> is supplied, that delegate governs the behavior instead.
/// </para>
/// <para>
/// In addition to the parameter schema, a JSON schema is also derived from the method's return type and exposed via the
/// returned <see cref="AIFunction"/>'s <see cref="AIFunctionDeclaration.ReturnJsonSchema"/>. For methods returning
/// <see cref="void"/>, <see cref="Task"/>, or <see cref="ValueTask"/>, no return schema is produced (the property is <see langword="null"/>).
/// For methods returning <see cref="Task{TResult}"/> or <see cref="ValueTask{TResult}"/>, the schema is derived from the
/// unwrapped result type. Return schema generation can be excluded via <see cref="AIFunctionFactoryOptions.ExcludeResultSchema"/>,
/// and its generation is governed by <paramref name="options"/>'s <see cref="AIFunctionFactoryOptions.JsonSchemaCreateOptions"/>.
/// </para>
/// </remarks>
/// <exception cref="ArgumentNullException"><paramref name="method"/> is <see langword="null"/>.</exception>
/// <exception cref="JsonException">A parameter to <paramref name="method"/> is not serializable.</exception>
public static AIFunction Create(Delegate method, AIFunctionFactoryOptions? options)
{
_ = Throw.IfNull(method);
return ReflectionAIFunction.Build(method.Method, method.Target, options ?? _defaultOptions);
}
/// <summary>Creates an <see cref="AIFunction"/> instance for a method, specified via a delegate.</summary>
/// <param name="method">The method to be represented via the created <see cref="AIFunction"/>.</param>
/// <param name="name">
/// The name to use for the <see cref="AIFunction"/>. If <see langword="null"/>, the name will be derived from
/// any <see cref="AIFunctionNameAttribute"/> on <paramref name="method"/>, then from any <see cref="DisplayNameAttribute"/>
/// on <paramref name="method"/>, if available, or else from the name of <paramref name="method"/>.
/// </param>
/// <param name="description">
/// The description to use for the <see cref="AIFunction"/>. If <see langword="null"/>, a description will be derived from
/// any <see cref="DescriptionAttribute"/> on <paramref name="method"/>, if available.
/// </param>
/// <param name="serializerOptions">The <see cref="JsonSerializerOptions"/> used to marshal function parameters and any return value.</param>
/// <returns>The created <see cref="AIFunction"/> for invoking <paramref name="method"/>.</returns>
/// <remarks>
/// <para>
/// Any parameters to <paramref name="method"/> are sourced from the <see cref="AIFunctionArguments"/>'s dictionary
/// of key/value pairs and are represented in the JSON schema for the function, as exposed in the returned <see cref="AIFunction"/>'s
/// <see cref="AIFunctionDeclaration.JsonSchema"/>. There are a few exceptions to this:
/// <list type="bullet">
/// <item>
/// <see cref="CancellationToken"/> parameters are automatically bound to the <see cref="CancellationToken"/> passed into
/// the invocation via <see cref="AIFunction.InvokeAsync"/>'s <see cref="CancellationToken"/> parameter. The parameter is
/// not included in the generated JSON schema.
/// </item>
/// <item>
/// By default, <see cref="IServiceProvider"/> parameters are bound from the <see cref="AIFunctionArguments.Services"/> property
/// and are not included in the JSON schema. If the parameter is optional, such that a default value is provided,
/// <see cref="AIFunctionArguments.Services"/> is allowed to be <see langword="null"/>; otherwise, <see cref="AIFunctionArguments.Services"/>
/// must be non-<see langword="null"/>, or else the invocation will fail with an exception due to the required nature of the parameter.
/// </item>
/// <item>
/// By default, <see cref="AIFunctionArguments"/> parameters are bound directly to <see cref="AIFunctionArguments"/> instance
/// passed into <see cref="AIFunction.InvokeAsync"/> and are not included in the JSON schema. If the <see cref="AIFunctionArguments"/>
/// instance passed to <see cref="AIFunction.InvokeAsync"/> is <see langword="null"/>, the <see cref="AIFunction"/> implementation
/// manufactures an empty instance, such that parameters of type <see cref="AIFunctionArguments"/> can always be satisfied, whether
/// optional or not.
/// </item>
/// </list>
/// All other parameter types are bound from the <see cref="AIFunctionArguments"/> dictionary passed into <see cref="AIFunction.InvokeAsync"/>
/// and are included in the generated JSON schema.
/// </para>
/// <para>
/// The marshaling of parameters from the <see cref="AIFunctionArguments"/> dictionary permits values to be passed into the <paramref name="method"/>'s
/// invocation directly if the object is already of a compatible type. Otherwise, if the argument is a <see cref="JsonElement"/>, <see cref="JsonDocument"/>,
/// or <see cref="JsonNode"/>, it is deserialized into the parameter type, utilizing <paramref name="serializerOptions"/> if provided, or else
/// <see cref="AIJsonUtilities.DefaultOptions"/>. If the argument is anything else, it is round-tripped through JSON, serializing the object as JSON
/// and then deserializing it to the expected type.
/// </para>
/// <para>
/// In general, the data supplied via an <see cref="AIFunctionArguments"/>'s dictionary is supplied from an AI service and should be considered
/// unvalidated and untrusted. To provide validated and trusted data to the invocation of <paramref name="method"/>, consider having <paramref name="method"/>
/// point to an instance method on an instance configured to hold the appropriate state. An <see cref="IServiceProvider"/> parameter can also be
/// used to resolve services from a dependency injection container.
/// </para>
/// <para>
/// Return values are serialized to <see cref="JsonElement"/> using <paramref name="serializerOptions"/> if provided,
/// or else using <see cref="AIJsonUtilities.DefaultOptions"/>. However, return values whose declared type is <see cref="AIContent"/>, a
/// derived type of <see cref="AIContent"/>, or any type assignable from <see cref="IEnumerable{AIContent}"/> are not serialized;
/// they are returned as-is to facilitate specialized handling.
/// </para>
/// <para>
/// A JSON schema is also derived from the method's return type and exposed via <see cref="AIFunctionDeclaration.ReturnJsonSchema"/>.
/// For methods returning <see cref="void"/>, <see cref="Task"/>, or <see cref="ValueTask"/>, no return schema is produced.
/// For methods returning <see cref="Task{TResult}"/> or <see cref="ValueTask{TResult}"/>, the schema is derived from the unwrapped result type.
/// </para>
/// </remarks>
/// <exception cref="ArgumentNullException"><paramref name="method"/> is <see langword="null"/>.</exception>
/// <exception cref="JsonException">A parameter to <paramref name="method"/> is not serializable.</exception>
public static AIFunction Create(Delegate method, string? name = null, string? description = null, JsonSerializerOptions? serializerOptions = null)
{
_ = Throw.IfNull(method);
AIFunctionFactoryOptions createOptions = serializerOptions is null && name is null && description is null
? _defaultOptions
: new()
{
Name = name,
Description = description,
SerializerOptions = serializerOptions,
};
return ReflectionAIFunction.Build(method.Method, method.Target, createOptions);
}
/// <summary>
/// Creates an <see cref="AIFunction"/> instance for a method, specified via an <see cref="MethodInfo"/> instance
/// and an optional target object if the method is an instance method.
/// </summary>
/// <param name="method">The method to be represented via the created <see cref="AIFunction"/>.</param>
/// <param name="target">
/// The target object for the <paramref name="method"/> if it represents an instance method.
/// This should be <see langword="null"/> if and only if <paramref name="method"/> is a static method.
/// </param>
/// <param name="options">Metadata to use to override defaults inferred from <paramref name="method"/>.</param>
/// <returns>The created <see cref="AIFunction"/> for invoking <paramref name="method"/>.</returns>
/// <remarks>
/// <para>
/// By default, any parameters to <paramref name="method"/> are sourced from the <see cref="AIFunctionArguments"/>'s dictionary
/// of key/value pairs and are represented in the JSON schema for the function, as exposed in the returned <see cref="AIFunction"/>'s
/// <see cref="AIFunctionDeclaration.JsonSchema"/>. There are a few exceptions to this:
/// <list type="bullet">
/// <item>
/// <see cref="CancellationToken"/> parameters are automatically bound to the <see cref="CancellationToken"/> passed into
/// the invocation via <see cref="AIFunction.InvokeAsync"/>'s <see cref="CancellationToken"/> parameter. The parameter is
/// not included in the generated JSON schema. The behavior of <see cref="CancellationToken"/> parameters can't be overridden.
/// </item>
/// <item>
/// By default, <see cref="IServiceProvider"/> parameters are bound from the <see cref="AIFunctionArguments.Services"/> property
/// and are not included in the JSON schema. If the parameter is optional, such that a default value is provided,
/// <see cref="AIFunctionArguments.Services"/> is allowed to be <see langword="null"/>; otherwise, <see cref="AIFunctionArguments.Services"/>
/// must be non-<see langword="null"/>, or else the invocation will fail with an exception due to the required nature of the parameter.
/// The handling of <see cref="IServiceProvider"/> parameters can be overridden via <see cref="AIFunctionFactoryOptions.ConfigureParameterBinding"/>.
/// </item>
/// <item>
/// By default, <see cref="AIFunctionArguments"/> parameters are bound directly to <see cref="AIFunctionArguments"/> instance
/// passed into <see cref="AIFunction.InvokeAsync"/> and are not included in the JSON schema. If the <see cref="AIFunctionArguments"/>
/// instance passed to <see cref="AIFunction.InvokeAsync"/> is <see langword="null"/>, the <see cref="AIFunction"/> implementation
/// manufactures an empty instance, such that parameters of type <see cref="AIFunctionArguments"/> can always be satisfied, whether
/// optional or not. The handling of <see cref="AIFunctionArguments"/> parameters can be overridden via
/// <see cref="AIFunctionFactoryOptions.ConfigureParameterBinding"/>.
/// </item>
/// </list>
/// All other parameter types are, by default, bound from the <see cref="AIFunctionArguments"/> dictionary passed into <see cref="AIFunction.InvokeAsync"/>
/// and are included in the generated JSON schema. This can be overridden by the <see cref="AIFunctionFactoryOptions.ConfigureParameterBinding"/> provided
/// via the <paramref name="options"/> parameter; for every parameter, the delegate is enabled to choose if the parameter should be included in the
/// generated schema and how its value should be bound, including handling of optionality (by default, required parameters that are not included in the
/// <see cref="AIFunctionArguments"/> dictionary will result in an exception being thrown). Loosely typed additional context information can be passed
/// into <see cref="AIFunction.InvokeAsync"/> via the <see cref="AIFunctionArguments"/>'s <see cref="AIFunctionArguments.Context"/> dictionary; the default
/// binding ignores this collection, but a custom binding supplied via <see cref="AIFunctionFactoryOptions.ConfigureParameterBinding"/> can choose to
/// source arguments from this data.
/// </para>
/// <para>
/// The default marshaling of parameters from the <see cref="AIFunctionArguments"/> dictionary permits values to be passed into the <paramref name="method"/>'s
/// invocation directly if the object is already of a compatible type. Otherwise, if the argument is a <see cref="JsonElement"/>, <see cref="JsonDocument"/>,
/// or <see cref="JsonNode"/>, it is deserialized into the parameter type, utilizing <see cref="AIFunctionFactoryOptions.SerializerOptions"/> if provided,
/// or else using <see cref="AIJsonUtilities.DefaultOptions"/>. If the argument is anything else, it is round-tripped through JSON, serializing the object as JSON
/// and then deserializing it to the expected type.
/// </para>
/// <para>
/// In general, the data supplied via an <see cref="AIFunctionArguments"/>'s dictionary is supplied from an AI service and should be considered
/// unvalidated and untrusted. To provide validated and trusted data to the invocation of <paramref name="method"/>, consider having <paramref name="method"/>
/// point to an instance method on an instance configured to hold the appropriate state. An <see cref="IServiceProvider"/> parameter can also be
/// used to resolve services from a dependency injection container.
/// </para>
/// <para>
/// By default, return values are serialized to <see cref="JsonElement"/> using <paramref name="options"/>'s
/// <see cref="AIFunctionFactoryOptions.SerializerOptions"/> if provided, or else using <see cref="AIJsonUtilities.DefaultOptions"/>.
/// However, return values whose declared type is <see cref="AIContent"/>, a derived type of <see cref="AIContent"/>, or
/// any type assignable from <see cref="IEnumerable{AIContent}"/> are not serialized and are instead returned directly.
/// Handling of return values can be overridden via <see cref="AIFunctionFactoryOptions.MarshalResult"/>.
/// </para>
/// <para>
/// In addition to the parameter schema, a JSON schema is also derived from the method's return type and exposed via the
/// returned <see cref="AIFunction"/>'s <see cref="AIFunctionDeclaration.ReturnJsonSchema"/>. For methods returning
/// <see cref="void"/>, <see cref="Task"/>, or <see cref="ValueTask"/>, no return schema is produced (the property is <see langword="null"/>).
/// For methods returning <see cref="Task{TResult}"/> or <see cref="ValueTask{TResult}"/>, the schema is derived from the
/// unwrapped result type. Return schema generation can be excluded via <see cref="AIFunctionFactoryOptions.ExcludeResultSchema"/>,
/// and its generation is governed by <paramref name="options"/>'s <see cref="AIFunctionFactoryOptions.JsonSchemaCreateOptions"/>.
/// </para>
/// </remarks>
/// <exception cref="ArgumentNullException"><paramref name="method"/> is <see langword="null"/>.</exception>
/// <exception cref="ArgumentNullException"><paramref name="method"/> represents an instance method but <paramref name="target"/> is null.</exception>
/// <exception cref="ArgumentException"><paramref name="method"/> represents an open generic method.</exception>
/// <exception cref="ArgumentException"><paramref name="method"/> contains a parameter without a parameter name.</exception>
/// <exception cref="JsonException">A parameter to <paramref name="method"/> or its return type is not serializable.</exception>
public static AIFunction Create(MethodInfo method, object? target, AIFunctionFactoryOptions? options)
{
_ = Throw.IfNull(method);
return ReflectionAIFunction.Build(method, target, options ?? _defaultOptions);
}
/// <summary>
/// Creates an <see cref="AIFunction"/> instance for a method, specified via an <see cref="MethodInfo"/> instance
/// and an optional target object if the method is an instance method.
/// </summary>
/// <param name="method">The method to be represented via the created <see cref="AIFunction"/>.</param>
/// <param name="target">
/// The target object for the <paramref name="method"/> if it represents an instance method.
/// This should be <see langword="null"/> if and only if <paramref name="method"/> is a static method.
/// </param>
/// <param name="name">
/// The name to use for the <see cref="AIFunction"/>. If <see langword="null"/>, the name will be derived from
/// any <see cref="AIFunctionNameAttribute"/> on <paramref name="method"/>, then from any <see cref="DisplayNameAttribute"/>
/// on <paramref name="method"/>, if available, or else from the name of <paramref name="method"/>.
/// </param>
/// <param name="description">
/// The description to use for the <see cref="AIFunction"/>. If <see langword="null"/>, a description will be derived from
/// any <see cref="DescriptionAttribute"/> on <paramref name="method"/>, if available.
/// </param>
/// <param name="serializerOptions">The <see cref="JsonSerializerOptions"/> used to marshal function parameters and return value.</param>
/// <returns>The created <see cref="AIFunction"/> for invoking <paramref name="method"/>.</returns>
/// <remarks>
/// <para>
/// Any parameters to <paramref name="method"/> are sourced from the <see cref="AIFunctionArguments"/>'s dictionary
/// of key/value pairs and are represented in the JSON schema for the function, as exposed in the returned <see cref="AIFunction"/>'s
/// <see cref="AIFunctionDeclaration.JsonSchema"/>. There are a few exceptions to this:
/// <list type="bullet">
/// <item>
/// <see cref="CancellationToken"/> parameters are automatically bound to the <see cref="CancellationToken"/> passed into
/// the invocation via <see cref="AIFunction.InvokeAsync"/>'s <see cref="CancellationToken"/> parameter. The parameter is
/// not included in the generated JSON schema.
/// </item>
/// <item>
/// By default, <see cref="IServiceProvider"/> parameters are bound from the <see cref="AIFunctionArguments.Services"/> property
/// and are not included in the JSON schema. If the parameter is optional, such that a default value is provided,
/// <see cref="AIFunctionArguments.Services"/> is allowed to be <see langword="null"/>; otherwise, <see cref="AIFunctionArguments.Services"/>
/// must be non-<see langword="null"/>, or else the invocation will fail with an exception due to the required nature of the parameter.
/// </item>
/// <item>
/// By default, <see cref="AIFunctionArguments"/> parameters are bound directly to <see cref="AIFunctionArguments"/> instance
/// passed into <see cref="AIFunction.InvokeAsync"/> and are not included in the JSON schema. If the <see cref="AIFunctionArguments"/>
/// instance passed to <see cref="AIFunction.InvokeAsync"/> is <see langword="null"/>, the <see cref="AIFunction"/> implementation
/// manufactures an empty instance, such that parameters of type <see cref="AIFunctionArguments"/> can always be satisfied, whether
/// optional or not.
/// </item>
/// </list>
/// All other parameter types are bound from the <see cref="AIFunctionArguments"/> dictionary passed into <see cref="AIFunction.InvokeAsync"/>
/// and are included in the generated JSON schema.
/// </para>
/// <para>
/// The marshaling of parameters from the <see cref="AIFunctionArguments"/> dictionary permits values to be passed into the <paramref name="method"/>'s
/// invocation directly if the object is already of a compatible type. Otherwise, if the argument is a <see cref="JsonElement"/>, <see cref="JsonDocument"/>,
/// or <see cref="JsonNode"/>, it is deserialized into the parameter type, utilizing <paramref name="serializerOptions"/> if provided, or else
/// <see cref="AIJsonUtilities.DefaultOptions"/>. If the argument is anything else, it is round-tripped through JSON, serializing the object as JSON
/// and then deserializing it to the expected type.
/// </para>
/// <para>
/// In general, the data supplied via an <see cref="AIFunctionArguments"/>'s dictionary is supplied from an AI service and should be considered
/// unvalidated and untrusted. To provide validated and trusted data to the invocation of <paramref name="method"/>, consider having <paramref name="method"/>
/// point to an instance method on an instance configured to hold the appropriate state. An <see cref="IServiceProvider"/> parameter can also be
/// used to resolve services from a dependency injection container.
/// </para>
/// <para>
/// Return values are serialized to <see cref="JsonElement"/> using <paramref name="serializerOptions"/> if provided,
/// or else using <see cref="AIJsonUtilities.DefaultOptions"/>. However, return values whose declared type is <see cref="AIContent"/>, a
/// derived type of <see cref="AIContent"/>, or any type assignable from <see cref="IEnumerable{AIContent}"/> are returned
/// without serialization to enable specialized handling.
/// </para>
/// <para>
/// A JSON schema is also derived from the method's return type and exposed via <see cref="AIFunctionDeclaration.ReturnJsonSchema"/>.
/// For methods returning <see cref="void"/>, <see cref="Task"/>, or <see cref="ValueTask"/>, no return schema is produced.
/// For methods returning <see cref="Task{TResult}"/> or <see cref="ValueTask{TResult}"/>, the schema is derived from the unwrapped result type.
/// </para>
/// </remarks>
/// <exception cref="ArgumentNullException"><paramref name="method"/> is <see langword="null"/>.</exception>
/// <exception cref="ArgumentNullException"><paramref name="method"/> represents an instance method but <paramref name="target"/> is null.</exception>
/// <exception cref="ArgumentException"><paramref name="method"/> represents an open generic method.</exception>
/// <exception cref="ArgumentException"><paramref name="method"/> contains a parameter without a parameter name.</exception>
/// <exception cref="JsonException">A parameter to <paramref name="method"/> or its return type is not serializable.</exception>
public static AIFunction Create(MethodInfo method, object? target, string? name = null, string? description = null, JsonSerializerOptions? serializerOptions = null)
{
_ = Throw.IfNull(method);
AIFunctionFactoryOptions createOptions = serializerOptions is null && name is null && description is null
? _defaultOptions
: new()
{
Name = name,
Description = description,
SerializerOptions = serializerOptions,
};
return ReflectionAIFunction.Build(method, target, createOptions);
}
/// <summary>
/// Creates an <see cref="AIFunction"/> instance for a method, specified via a <see cref="MethodInfo"/> for
/// an instance method and a <see cref="Func{AIFunctionArguments,Object}"/> for constructing an instance of
/// the receiver object each time the <see cref="AIFunction"/> is invoked.
/// </summary>
/// <param name="method">The instance method to be represented via the created <see cref="AIFunction"/>.</param>
/// <param name="createInstanceFunc">
/// Callback used on each function invocation to create an instance of the type on which the instance method <paramref name="method"/>
/// will be invoked. If the returned instance is <see cref="IAsyncDisposable"/> or <see cref="IDisposable"/>, it will be disposed of
/// after <paramref name="method"/> completes its invocation.
/// </param>
/// <param name="options">Metadata to use to override defaults inferred from <paramref name="method"/>.</param>
/// <returns>The created <see cref="AIFunction"/> for invoking <paramref name="method"/>.</returns>
/// <remarks>
/// <para>
/// Return values are serialized to <see cref="JsonElement"/> using <paramref name="options"/>'s
/// <see cref="AIFunctionFactoryOptions.SerializerOptions"/>. Arguments that are not already of the expected type are
/// marshaled to the expected type via JSON and using <paramref name="options"/>'s
/// <see cref="AIFunctionFactoryOptions.SerializerOptions"/>. If the argument is a <see cref="JsonElement"/>,
/// <see cref="JsonDocument"/>, or <see cref="JsonNode"/>, it is deserialized directly. If the argument is anything else unknown,
/// it is round-tripped through JSON, serializing the object as JSON and then deserializing it to the expected type.
/// </para>
/// <para>
/// By default, any parameters to <paramref name="method"/> are sourced from the <see cref="AIFunctionArguments"/>'s dictionary
/// of key/value pairs and are represented in the JSON schema for the function, as exposed in the returned <see cref="AIFunction"/>'s
/// <see cref="AIFunctionDeclaration.JsonSchema"/>. There are a few exceptions to this:
/// <list type="bullet">
/// <item>
/// <see cref="CancellationToken"/> parameters are automatically bound to the <see cref="CancellationToken"/> passed into
/// the invocation via <see cref="AIFunction.InvokeAsync"/>'s <see cref="CancellationToken"/> parameter. The parameter is
/// not included in the generated JSON schema. The behavior of <see cref="CancellationToken"/> parameters can't be overridden.
/// </item>
/// <item>
/// By default, <see cref="IServiceProvider"/> parameters are bound from the <see cref="AIFunctionArguments.Services"/> property
/// and are not included in the JSON schema. If the parameter is optional, such that a default value is provided,
/// <see cref="AIFunctionArguments.Services"/> is allowed to be <see langword="null"/>; otherwise, <see cref="AIFunctionArguments.Services"/>
/// must be non-<see langword="null"/>, or else the invocation will fail with an exception due to the required nature of the parameter.
/// The handling of <see cref="IServiceProvider"/> parameters can be overridden via <see cref="AIFunctionFactoryOptions.ConfigureParameterBinding"/>.
/// </item>
/// <item>
/// By default, <see cref="AIFunctionArguments"/> parameters are bound directly to <see cref="AIFunctionArguments"/> instance
/// passed into <see cref="AIFunction.InvokeAsync"/> and are not included in the JSON schema. If the <see cref="AIFunctionArguments"/>
/// instance passed to <see cref="AIFunction.InvokeAsync"/> is <see langword="null"/>, the <see cref="AIFunction"/> implementation
/// manufactures an empty instance, such that parameters of type <see cref="AIFunctionArguments"/> can always be satisfied, whether
/// optional or not. The handling of <see cref="AIFunctionArguments"/> parameters can be overridden via
/// <see cref="AIFunctionFactoryOptions.ConfigureParameterBinding"/>.
/// </item>
/// </list>
/// All other parameter types are, by default, bound from the <see cref="AIFunctionArguments"/> dictionary passed into <see cref="AIFunction.InvokeAsync"/>
/// and are included in the generated JSON schema. This can be overridden by the <see cref="AIFunctionFactoryOptions.ConfigureParameterBinding"/> provided
/// via the <paramref name="options"/> parameter; for every parameter, the delegate is enabled to choose if the parameter should be included in the
/// generated schema and how its value should be bound, including handling of optionality (by default, required parameters that are not included in the
/// <see cref="AIFunctionArguments"/> dictionary will result in an exception being thrown). Loosely-typed additional context information can be passed
/// into <see cref="AIFunction.InvokeAsync"/> via the <see cref="AIFunctionArguments"/>'s <see cref="AIFunctionArguments.Context"/> dictionary; the default
/// binding ignores this collection, but a custom binding supplied via <see cref="AIFunctionFactoryOptions.ConfigureParameterBinding"/> can choose to
/// source arguments from this data.
/// </para>
/// <para>
/// The default marshaling of parameters from the <see cref="AIFunctionArguments"/> dictionary permits values to be passed into the <paramref name="method"/>'s
/// invocation directly if the object is already of a compatible type. Otherwise, if the argument is a <see cref="JsonElement"/>, <see cref="JsonDocument"/>,
/// or <see cref="JsonNode"/>, it is deserialized into the parameter type, utilizing <see cref="AIFunctionFactoryOptions.SerializerOptions"/> if provided,
/// or else using <see cref="AIJsonUtilities.DefaultOptions"/>. If the argument is anything else, it is round-tripped through JSON, serializing the object as JSON
/// and then deserializing it to the expected type.
/// </para>
/// <para>
/// In general, the data supplied via an <see cref="AIFunctionArguments"/>'s dictionary is supplied from an AI service and should be considered
/// unvalidated and untrusted. To provide validated and trusted data to the invocation of <paramref name="method"/>, the instance constructed
/// for each invocation can contain that data in it, such that it's then available to <paramref name="method"/> as instance data.
/// An <see cref="IServiceProvider"/> parameter can also be used to resolve services from a dependency injection container.
/// </para>
/// <para>
/// By default, return values are serialized to <see cref="JsonElement"/> using <paramref name="options"/>'s
/// <see cref="AIFunctionFactoryOptions.SerializerOptions"/> if provided, or else using <see cref="AIJsonUtilities.DefaultOptions"/>.
/// However, return values whose declared type is <see cref="AIContent"/>, a derived type of <see cref="AIContent"/>, or any type
/// assignable from <see cref="IEnumerable{AIContent}"/> are returned directly without serialization.
/// Handling of return values can be overridden via <see cref="AIFunctionFactoryOptions.MarshalResult"/>.
/// </para>
/// <para>
/// In addition to the parameter schema, a JSON schema is also derived from the method's return type and exposed via the
/// returned <see cref="AIFunction"/>'s <see cref="AIFunctionDeclaration.ReturnJsonSchema"/>. For methods returning
/// <see cref="void"/>, <see cref="Task"/>, or <see cref="ValueTask"/>, no return schema is produced (the property is <see langword="null"/>).
/// For methods returning <see cref="Task{TResult}"/> or <see cref="ValueTask{TResult}"/>, the schema is derived from the
/// unwrapped result type. Return schema generation can be excluded via <see cref="AIFunctionFactoryOptions.ExcludeResultSchema"/>,
/// and its generation is governed by <paramref name="options"/>'s <see cref="AIFunctionFactoryOptions.JsonSchemaCreateOptions"/>.
/// </para>
/// </remarks>
/// <exception cref="ArgumentNullException"><paramref name="method"/> is <see langword="null"/>.</exception>
/// <exception cref="ArgumentNullException"><paramref name="createInstanceFunc"/> is <see langword="null"/>.</exception>
/// <exception cref="ArgumentException"><paramref name="method"/> represents a static method.</exception>
/// <exception cref="ArgumentException"><paramref name="method"/> represents an open generic method.</exception>
/// <exception cref="ArgumentException"><paramref name="method"/> contains a parameter without a parameter name.</exception>
/// <exception cref="JsonException">A parameter to <paramref name="method"/> or its return type is not serializable.</exception>
public static AIFunction Create(
MethodInfo method,
Func<AIFunctionArguments, object> createInstanceFunc,
AIFunctionFactoryOptions? options = null) =>
ReflectionAIFunction.Build(method, createInstanceFunc, options ?? _defaultOptions);
/// <summary>Creates an <see cref="AIFunctionDeclaration"/> using the specified parameters as the implementation of its corresponding properties.</summary>
/// <param name="name">The name of the function.</param>
/// <param name="description">A description of the function, suitable for use in describing the purpose to a model.</param>
/// <param name="jsonSchema">A JSON schema describing the function and its input parameters.</param>
/// <param name="returnJsonSchema">A JSON schema describing the function's return value.</param>
/// <returns>The created <see cref="AIFunctionDeclaration"/> that describes a function.</returns>
/// <exception cref="ArgumentNullException"><paramref name="name"/> is <see langword="null"/>.</exception>
/// <remarks>
/// <see cref="CreateDeclaration"/> creates an <see cref="AIFunctionDeclaration"/> that can be used to describe a function
/// but not invoke it. To create an invocable <see cref="AIFunction"/>, use Create. A non-invocable <see cref="AIFunctionDeclaration"/>
/// can also be created from an invocable <see cref="AIFunction"/> using that function's <see cref="AIFunction.AsDeclarationOnly"/> method.
/// </remarks>
public static AIFunctionDeclaration CreateDeclaration(
string name,
string? description,
JsonElement jsonSchema,
JsonElement? returnJsonSchema = null) =>
new DefaultAIFunctionDeclaration(
Throw.IfNullOrEmpty(name),
description ?? string.Empty,
jsonSchema,
returnJsonSchema);
private sealed class DefaultAIFunctionDeclaration(
string name, string description, JsonElement jsonSchema, JsonElement? returnJsonSchema) :
AIFunctionDeclaration
{
public override string Name => name;
public override string Description => description;
public override JsonElement JsonSchema => jsonSchema;
public override JsonElement? ReturnJsonSchema => returnJsonSchema;
}
private sealed class ReflectionAIFunction : AIFunction
{
public static ReflectionAIFunction Build(MethodInfo method, object? target, AIFunctionFactoryOptions options)
{
_ = Throw.IfNull(method);
if (method.ContainsGenericParameters)
{
Throw.ArgumentException(nameof(method), "Open generic methods are not supported");
}
if (!method.IsStatic && target is null)
{
Throw.ArgumentNullException(nameof(target), "Target must not be null for an instance method.");
}
var functionDescriptor = ReflectionAIFunctionDescriptor.GetOrCreate(method, options);
if (target is null && options.AdditionalProperties is null)
{
// We can use a cached value for static methods not specifying additional properties.
return functionDescriptor.CachedDefaultInstance ??= new(functionDescriptor, target, options);
}
return new(functionDescriptor, target, options);
}
public static ReflectionAIFunction Build(
MethodInfo method,
Func<AIFunctionArguments, object> createInstanceFunc,
AIFunctionFactoryOptions options)
{
_ = Throw.IfNull(method);
_ = Throw.IfNull(createInstanceFunc);
if (method.ContainsGenericParameters)
{
Throw.ArgumentException(nameof(method), "Open generic methods are not supported");
}
if (method.IsStatic)
{
Throw.ArgumentException(nameof(method), "The method must be an instance method.");
}
return new(ReflectionAIFunctionDescriptor.GetOrCreate(method, options), createInstanceFunc, options);
}
private ReflectionAIFunction(ReflectionAIFunctionDescriptor functionDescriptor, object? target, AIFunctionFactoryOptions options)
{
FunctionDescriptor = functionDescriptor;
Target = target;
AdditionalProperties = options.AdditionalProperties ?? EmptyReadOnlyDictionary<string, object?>.Instance;
}
private ReflectionAIFunction(
ReflectionAIFunctionDescriptor functionDescriptor,
Func<AIFunctionArguments, object> createInstanceFunc,
AIFunctionFactoryOptions options)
{
FunctionDescriptor = functionDescriptor;
CreateInstanceFunc = createInstanceFunc;
AdditionalProperties = options.AdditionalProperties ?? EmptyReadOnlyDictionary<string, object?>.Instance;
}
public ReflectionAIFunctionDescriptor FunctionDescriptor { get; }
public object? Target { get; }
public Func<AIFunctionArguments, object>? CreateInstanceFunc { get; }
public override IReadOnlyDictionary<string, object?> AdditionalProperties { get; }
public override string Name => FunctionDescriptor.Name;
public override string Description => FunctionDescriptor.Description;
public override MethodInfo UnderlyingMethod => FunctionDescriptor.Method;
public override JsonElement JsonSchema => FunctionDescriptor.JsonSchema;
public override JsonElement? ReturnJsonSchema => FunctionDescriptor.ReturnJsonSchema;
public override JsonSerializerOptions JsonSerializerOptions => FunctionDescriptor.JsonSerializerOptions;
protected override async ValueTask<object?> InvokeCoreAsync(
AIFunctionArguments arguments,
CancellationToken cancellationToken)
{
bool disposeTarget = false;
object? target = Target;
try
{
if (CreateInstanceFunc is { } func)
{
Debug.Assert(target is null, "Expected target to be null when we have a non-null target type");
Debug.Assert(!FunctionDescriptor.Method.IsStatic, "Expected an instance method");
target = func(arguments);
if (target is null)
{
Throw.InvalidOperationException("Unable to create an instance of the target type.");
}
disposeTarget = true;
}
var paramMarshallers = FunctionDescriptor.ParameterMarshallers;
object?[] args = paramMarshallers.Length != 0 ? new object?[paramMarshallers.Length] : [];
// If the configured serializer options request strict handling of unmapped members,
// verify that every argument key corresponds to a declared parameter name. This mirrors
// JsonSerializerOptions.UnmappedMemberHandling behavior for object deserialization by
// applying the same policy to top-level AIFunction argument binding. Argument name matching
// honors the comparer of the supplied AIFunctionArguments dictionary (ordinal by default).
//
// Validation is skipped when custom ParameterBindingOptions.BindParameter callbacks are in
// use, since those may legitimately source values from argument keys that do not correspond
// to the .NET parameter names.
if (FunctionDescriptor.JsonSerializerOptions.UnmappedMemberHandling is JsonUnmappedMemberHandling.Disallow &&
arguments.Count > 0 &&
!FunctionDescriptor.HasCustomParameterBinding)
{
HashSet<string> expectedNames = FunctionDescriptor.ExpectedArgumentNames;
int matched = 0;
foreach (string name in expectedNames)
{
if (arguments.ContainsKey(name))
{
matched++;
}
}
if (matched != arguments.Count)
{
foreach (KeyValuePair<string, object?> kvp in arguments)
{
if (!expectedNames.Contains(kvp.Key))
{
Throw.ArgumentException(
nameof(arguments),
$"The arguments dictionary contains an unexpected key '{kvp.Key}' that does not correspond to any parameter of '{Name}'.");
}
}
// Fallback for comparer mismatches (e.g. case-insensitive arguments dictionary
// with duplicate-casing keys aliasing to the same parameter).
Throw.ArgumentException(
nameof(arguments),
$"The arguments dictionary contains keys that do not correspond to any parameter of '{Name}'.");
}
}
for (int i = 0; i < args.Length; i++)
{
args[i] = paramMarshallers[i](arguments, cancellationToken);
}
return await FunctionDescriptor.ReturnParameterMarshaller(
ReflectionInvoke(FunctionDescriptor.Method, target, args), cancellationToken).ConfigureAwait(true);
}
finally
{
if (disposeTarget)
{
if (target is IAsyncDisposable ad)
{
await ad.DisposeAsync().ConfigureAwait(true);
}
else if (target is IDisposable d)
{
d.Dispose();
}
}
}
}
}
/// <summary>
/// A descriptor for a .NET method-backed AIFunction that precomputes its marshalling delegates and JSON schema.
/// </summary>
private sealed class ReflectionAIFunctionDescriptor
{
private const int InnerCacheSoftLimit = 512;
private static readonly ConditionalWeakTable<JsonSerializerOptions, ConcurrentDictionary<DescriptorKey, ReflectionAIFunctionDescriptor>> _descriptorCache = new();
/// <summary>A boxed <see cref="CancellationToken.None"/>.</summary>
private static readonly object? _boxedDefaultCancellationToken = default(CancellationToken);
/// <summary>
/// Gets or creates a descriptor using the specified method and options.
/// </summary>
public static ReflectionAIFunctionDescriptor GetOrCreate(MethodInfo method, AIFunctionFactoryOptions options)
{
JsonSerializerOptions serializerOptions = options.SerializerOptions ?? AIJsonUtilities.DefaultOptions;
AIJsonSchemaCreateOptions schemaOptions = options.JsonSchemaCreateOptions ?? AIJsonSchemaCreateOptions.Default;
serializerOptions.MakeReadOnly();
ConcurrentDictionary<DescriptorKey, ReflectionAIFunctionDescriptor> innerCache = _descriptorCache.GetOrCreateValue(serializerOptions);
DescriptorKey key = new(method, options.Name, options.Description, options.ConfigureParameterBinding, options.MarshalResult, options.ExcludeResultSchema, schemaOptions);
if (innerCache.TryGetValue(key, out ReflectionAIFunctionDescriptor? descriptor))
{
return descriptor;
}
descriptor = new(key, serializerOptions);
return innerCache.Count < InnerCacheSoftLimit
? innerCache.GetOrAdd(key, descriptor)
: descriptor;
}
private ReflectionAIFunctionDescriptor(DescriptorKey key, JsonSerializerOptions serializerOptions)
{
ParameterInfo[] parameters = key.Method.GetParameters();
// Determine how each parameter should be bound. This is keyed on the parameter's position
// rather than the ParameterInfo instance: MethodInfo.GetParameters() does not guarantee the
// same ParameterInfo instances across concurrent first calls on a cold MethodInfo, and the
// schema generator invokes IncludeParameter with ParameterInfo instances from its own
// GetParameters() call. Keying on identity would race and silently drop ExcludeFromSchema.
AIFunctionFactoryOptions.ParameterBindingOptions[]? boundParameters = null;
if (parameters.Length != 0 && key.GetBindParameterOptions is not null)
{
boundParameters = new AIFunctionFactoryOptions.ParameterBindingOptions[parameters.Length];
for (int i = 0; i < parameters.Length; i++)
{
boundParameters[i] = key.GetBindParameterOptions(parameters[i]);
}
}
// Use that binding information to impact the schema generation.
AIJsonSchemaCreateOptions schemaOptions = key.SchemaOptions with
{
IncludeParameter = parameterInfo =>
{
// AIFunctionArguments and IServiceProvider parameters are always excluded from the schema.
if (parameterInfo.ParameterType == typeof(AIFunctionArguments) ||
parameterInfo.ParameterType == typeof(IServiceProvider))
{
return false;
}
// If the parameter is marked as excluded by GetBindParameterOptions, exclude it.
// Look up by position because the ParameterInfo passed here may be a different
// instance than the one boundParameters was built from (see comment above).
if (boundParameters is not null &&
(uint)parameterInfo.Position < (uint)boundParameters.Length &&
boundParameters[parameterInfo.Position].ExcludeFromSchema)
{
return false;
}
// If there was an existing IncludeParameter delegate, now defer to it as we've
// excluded everything we need to exclude.
if (key.SchemaOptions.IncludeParameter is { } existingIncludeParameter)
{
return existingIncludeParameter(parameterInfo);
}
// Everything else is included.
return true;
},
};
// Get marshaling delegates for parameters.
ParameterMarshallers = parameters.Length > 0 ? new Func<AIFunctionArguments, CancellationToken, object?>[parameters.Length] : [];
HashSet<string> expectedArgumentNames = new(StringComparer.Ordinal);
bool hasCustomParameterBinding = false;
for (int i = 0; i < parameters.Length; i++)
{
AIFunctionFactoryOptions.ParameterBindingOptions options =
boundParameters is not null ? boundParameters[i] : default;
ParameterMarshallers[i] = GetParameterMarshaller(serializerOptions, options, parameters[i]);
if (options.BindParameter is not null)
{
// Custom BindParameter callbacks can legally source their value from arbitrary keys in the
// AIFunctionArguments dictionary, so we cannot know in advance which keys are "expected".
// Note this down so that strict unmapped-member validation is skipped in InvokeCoreAsync.
hasCustomParameterBinding = true;
}
// Collect the set of parameter names that are potentially sourced from the arguments dictionary.
// Infrastructure parameters (CancellationToken, AIFunctionArguments, IServiceProvider) are always
// bound from dedicated sources and are never resolved by argument name, so they are excluded from
// the permitted set.
Type pType = parameters[i].ParameterType;
if (pType != typeof(CancellationToken) &&
pType != typeof(AIFunctionArguments) &&
pType != typeof(IServiceProvider) &&
!string.IsNullOrEmpty(parameters[i].Name))
{
string effectiveName = AIJsonUtilities.GetParameterSchemaName(parameters[i]);
if (!expectedArgumentNames.Add(effectiveName))
{
Throw.ArgumentException("method", $"Multiple parameters are mapped to the same name '{effectiveName}'. Ensure that any {nameof(AIParameterNameAttribute)} values do not collide with each other or with other parameter names.");
}
}
}
ExpectedArgumentNames = expectedArgumentNames;
HasCustomParameterBinding = hasCustomParameterBinding;
ReturnParameterMarshaller = GetReturnParameterMarshaller(key, serializerOptions, out Type? returnType);
Method = key.Method;
Name = key.Name ?? key.Method.GetCustomAttribute<AIFunctionNameAttribute>(inherit: true)?.Name ?? key.Method.GetCustomAttribute<DisplayNameAttribute>(inherit: true)?.DisplayName ?? GetFunctionName(key.Method);
Description = key.Description ?? key.Method.GetCustomAttribute<DescriptionAttribute>(inherit: true)?.Description ?? string.Empty;
JsonSerializerOptions = serializerOptions;
ReturnJsonSchema = returnType is null || key.ExcludeResultSchema ? null : AIJsonUtilities.CreateJsonSchema(
NormalizeReturnType(returnType, serializerOptions),
description: GetReturnParameterDescription(key.Method),
serializerOptions: serializerOptions,
inferenceOptions: schemaOptions);
JsonSchema = AIJsonUtilities.CreateFunctionJsonSchema(
key.Method,
title: string.Empty, // Forces skipping of the title keyword
description: string.Empty, // Forces skipping of the description keyword
serializerOptions: serializerOptions,
inferenceOptions: schemaOptions);
}
public string Name { get; }
public string Description { get; }
public MethodInfo Method { get; }
public JsonSerializerOptions JsonSerializerOptions { get; }
public JsonElement JsonSchema { get; }
public JsonElement? ReturnJsonSchema { get; }
public Func<AIFunctionArguments, CancellationToken, object?>[] ParameterMarshallers { get; }
public Func<object?, CancellationToken, ValueTask<object?>> ReturnParameterMarshaller { get; }
public HashSet<string> ExpectedArgumentNames { get; }
public bool HasCustomParameterBinding { get; }
public ReflectionAIFunction? CachedDefaultInstance { get; set; }
private static string GetFunctionName(MethodInfo method)
{
// Get the function name to use.
string name = SanitizeMemberName(method.Name);
const string AsyncSuffix = "Async";
if (IsAsyncMethod(method))
{
// If the method ends in "Async" or contains "Async_", remove the "Async".
int asyncIndex = name.LastIndexOf(AsyncSuffix, StringComparison.Ordinal);
if (asyncIndex > 0 &&
(asyncIndex + AsyncSuffix.Length == name.Length ||
((asyncIndex + AsyncSuffix.Length < name.Length) && (name[asyncIndex + AsyncSuffix.Length] == '_'))))
{
name =
#if NET
string.Concat(name.AsSpan(0, asyncIndex), name.AsSpan(asyncIndex + AsyncSuffix.Length));
#else
string.Concat(name.Substring(0, asyncIndex), name.Substring(asyncIndex + AsyncSuffix.Length));
#endif
}
}
return name;
static bool IsAsyncMethod(MethodInfo method)
{
Type t = method.ReturnType;
if (t == typeof(Task) || t == typeof(ValueTask))
{
return true;
}
if (t.IsGenericType)
{
t = t.GetGenericTypeDefinition();
if (t == typeof(Task<>) || t == typeof(ValueTask<>) || t == typeof(IAsyncEnumerable<>))
{
return true;
}
}
return false;
}
}
/// <summary>
/// Gets a delegate for handling the marshaling of a parameter.
/// </summary>
private static Func<AIFunctionArguments, CancellationToken, object?> GetParameterMarshaller(
JsonSerializerOptions serializerOptions,
AIFunctionFactoryOptions.ParameterBindingOptions bindingOptions,
ParameterInfo parameter)
{
if (string.IsNullOrWhiteSpace(parameter.Name))
{
Throw.ArgumentException(nameof(parameter), "Parameter is missing a name.");
}
Type parameterType = parameter.ParameterType;
// For CancellationToken parameters, we always bind to the token passed directly to InvokeAsync.
if (parameterType == typeof(CancellationToken))
{
return static (_, cancellationToken) =>
cancellationToken == default ? _boxedDefaultCancellationToken : // optimize common case of a default CT to avoid boxing
cancellationToken;
}
// CancellationToken is the only parameter type that's handled exclusively by the implementation.
// Now that it's been processed, check to see if the parameter should be handled via BindParameter.
if (bindingOptions.BindParameter is { } bindParameter)
{
return (arguments, _) => bindParameter(parameter, arguments);
}
// We're now into default handling of everything else.
// For AIFunctionArgument parameters, we bind to the arguments passed to InvokeAsync.
if (parameterType == typeof(AIFunctionArguments))
{
return static (arguments, _) => arguments;
}
// For IServiceProvider parameters, we bind to the services passed to InvokeAsync via AIFunctionArguments.
if (parameterType == typeof(IServiceProvider))
{
bool hasDefault = AIJsonUtilities.TryGetEffectiveDefaultValue(parameter, out _);
return (arguments, _) =>
{
IServiceProvider? services = arguments.Services;
if (!hasDefault && services is null)
{
ThrowNullServices(parameter.Name);
}
return services;
};
}
// For all other parameters, create a marshaller that tries to extract the value from the arguments dictionary.
// Resolve the contract used to marshal the value from JSON -- can throw if not supported or not found.
JsonTypeInfo? typeInfo = serializerOptions.GetTypeInfo(parameterType);
bool hasDefaultValue = AIJsonUtilities.TryGetEffectiveDefaultValue(parameter, out object? effectiveDefaultValue);
string argumentName = AIJsonUtilities.GetParameterSchemaName(parameter);
return (arguments, _) =>
{
// If the parameter has an argument specified in the dictionary, return that argument.
if (arguments.TryGetValue(argumentName, out object? value))
{
return value switch
{
null => null, // Return as-is if null -- if the parameter is a struct this will be handled by MethodInfo.Invoke
_ when parameterType.IsInstanceOfType(value) => value, // Do nothing if value is assignable to parameter type
JsonElement element => JsonSerializer.Deserialize(element, typeInfo),
JsonDocument doc => JsonSerializer.Deserialize(doc, typeInfo),
JsonNode node => JsonSerializer.Deserialize(node, typeInfo),
_ => MarshallViaJsonRoundtrip(value),
};
object? MarshallViaJsonRoundtrip(object value)
{
try
{
if (value is string text && IsPotentiallyJson(text))
{
Debug.Assert(typeInfo.Type != typeof(string), "string parameters should not enter this branch.");
// Account for the parameter potentially being a JSON string.
// The value is a string but the type is not. Try to deserialize it under the assumption that it's JSON.
// If it's not, we'll fall through to the default path that makes it valid JSON and then tries to deserialize.
try
{
return JsonSerializer.Deserialize(text, typeInfo);
}
catch (JsonException)
{
// If the string is not valid JSON, fall through to the round-trip.
}
}
string json = JsonSerializer.Serialize(value, serializerOptions.GetTypeInfo(value.GetType()));