Merge branch 'main' into update-modelid

dotnet/Directory.Packages.props

@@ -47,7 +47,7 @@
     <PackageVersion Include="System.Threading.Channels" Version="8.0.0" />
     <PackageVersion Include="System.Threading.Tasks.Dataflow" Version="8.0.0" />
     <PackageVersion Include="xunit" Version="2.6.3" />
-    <PackageVersion Include="xunit.runner.visualstudio" Version="2.5.5" />
+    <PackageVersion Include="xunit.runner.visualstudio" Version="2.5.6" />
     <PackageVersion Include="xretry" Version="1.9.0" />
     <PackageVersion Include="coverlet.collector" Version="6.0.0" />
     <PackageVersion Include="Polly" Version="8.2.0" />

dotnet/README.md

@@ -14,7 +14,7 @@ First, let's create a new project, targeting .NET 6 or newer, and add the
 `Microsoft.SemanticKernel` nuget package to your project from the command prompt
 in Visual Studio:
 
-    dotnet add package Microsoft.SemanticKernel --prerelease
+    dotnet add package Microsoft.SemanticKernel
 
 # Running prompts with input parameters
 
@@ -24,7 +24,7 @@ Copy and paste the following code into your project, with your Azure OpenAI key
 using Microsoft.SemanticKernel;
 using Microsoft.SemanticKernel.Connectors.OpenAI;
 
-var builder = new KernelBuilder();
+var builder = Kernel.CreateBuilder();
 
 builder.AddAzureOpenAIChatCompletion(
          "gpt-35-turbo",                      // Azure OpenAI Deployment Name
@@ -54,9 +54,9 @@ string text2 = @"
 2. The acceleration of an object depends on the mass of the object and the amount of force applied.
 3. Whenever one object exerts a force on another object, the second object exerts an equal and opposite on the first.";
 
-Console.WriteLine(await kernel.InvokeAsync(summarize, new KernelArguments(text1)));
+Console.WriteLine(await kernel.InvokeAsync(summarize, new() { ["input"] = text1 }));
 
-Console.WriteLine(await kernel.InvokeAsync(summarize, new KernelArguments(text2)));
+Console.WriteLine(await kernel.InvokeAsync(summarize, new() { ["input"] = text2 }));
 
 // Output:
 //   Energy conserved, entropy increases, zero entropy at 0K.
@@ -102,13 +102,13 @@ Packages included in **Microsoft.SemanticKernel**:
    engineering, semantic memory and semantic functions definition and orchestration.
 1. **Microsoft.SemanticKernel.Connectors.OpenAI**: connectors to OpenAI and Azure
    OpenAI, allowing to run semantic functions, chats, text to image with GPT3,
-   GPT3.5, GPT4, DALL-E2.
+   GPT3.5, GPT4, DALL-E3.
 
 Other SK packages available at nuget.org:
 
-1. **Microsoft.SemanticKernel.Connectors.Memory.Qdrant**: Qdrant connector for
+1. **Microsoft.SemanticKernel.Connectors.Qdrant**: Qdrant connector for
    plugins and semantic memory.
-2. **Microsoft.SemanticKernel.Connectors.Memory.Sqlite**: SQLite connector for
+2. **Microsoft.SemanticKernel.Connectors.Sqlite**: SQLite connector for
    plugins and semantic memory
 3. **Microsoft.SemanticKernel.Plugins.Document**: Document Plugin: Word processing,
    OpenXML, etc.
@@ -117,4 +117,3 @@ Other SK packages available at nuget.org:
 5. **Microsoft.SemanticKernel.Plugins.OpenApi**: OpenAPI Plugin.
 6. **Microsoft.SemanticKernel.Plugins.Web**: Web Plugin: search the web, download
    files, etc.
-7. **Microsoft.SemanticKernel.Reliability.Polly**: Extension for http resiliency.

dotnet/src/Connectors/Connectors.OpenAI/AzureSdk/ClientCore.cs

@@ -755,6 +755,28 @@ private static ChatCompletionsOptions CreateChatCompletionsOptions(
             Seed = executionSettings.Seed,
         };
 
+        switch (executionSettings.ResponseFormat)
+        {
+            case ChatCompletionsResponseFormat formatObject:
+                // If the response format is an Azure SDK ChatCompletionsResponseFormat, just pass it along.
+                options.ResponseFormat = formatObject;
+                break;
+
+            case string formatString:
+                // If the response format is a string, map the ones we know about, and ignore the rest.
+                switch (formatString)
+                {
+                    case "json_object":
+                        options.ResponseFormat = ChatCompletionsResponseFormat.JsonObject;
+                        break;
+
+                    case "text":
+                        options.ResponseFormat = ChatCompletionsResponseFormat.Text;
+                        break;
+                }
+                break;
+        }
+
         executionSettings.ToolCallBehavior?.ConfigureOptions(kernel, options);
         if (executionSettings.TokenSelectionBiases is not null)
         {

dotnet/src/Connectors/Connectors.OpenAI/OpenAIPromptExecutionSettings.cs

@@ -76,6 +76,13 @@ public sealed class OpenAIPromptExecutionSettings : PromptExecutionSettings
     [JsonPropertyName("seed")]
     public long? Seed { get; set; }
 
+    /// <summary>
+    /// Gets or sets the response format to use for the completion.
+    /// </summary>
+    [Experimental("SKEXP0013")]
+    [JsonPropertyName("response_format")]
+    public object? ResponseFormat { get; set; }
+
     /// <summary>
     /// The system prompt to use when generating text using a chat model.
     /// Defaults to "Assistant is a large language model."

dotnet/src/Planners/Planners.Handlebars/Handlebars/Extensions/KernelParameterMetadataExtensions.cs

@@ -5,16 +5,12 @@
 using System.Linq;
 using System.Reflection;
 using System.Text.Json;
+using Microsoft.SemanticKernel.Text;
 
 namespace Microsoft.SemanticKernel.Planning.Handlebars;
 
 internal static class KernelParameterMetadataExtensions
 {
-    private static readonly JsonSerializerOptions s_jsonOptionsCache = new()
-    {
-        WriteIndented = true,
-    };
-
     /// <summary>
     /// Checks if type is primitive or string
     /// </summary>
@@ -128,7 +124,7 @@ public static KernelParameterMetadata ParseJsonSchema(this KernelParameterMetada
 
     public static string ToJsonString(this JsonElement jsonProperties)
     {
-        return JsonSerializer.Serialize(jsonProperties, s_jsonOptionsCache);
+        return JsonSerializer.Serialize(jsonProperties, JsonOptionsCache.WriteIndented);
     }
 
     public static string GetSchemaTypeName(this KernelParameterMetadata parameter)

dotnet/src/SemanticKernel.Abstractions/Functions/KernelFunctionAttribute.cs

@@ -10,11 +10,11 @@
 namespace Microsoft.SemanticKernel;
 
 /// <summary>
-/// Specifies that a method on a class imported as a plugin with should be included as a <see cref="KernelFunction"/>.
+/// Specifies that a method on a class imported as a plugin should be included as a <see cref="KernelFunction"/> in the resulting <see cref="KernelPlugin"/>.
 /// </summary>
 /// <remarks>
 /// <para>
-/// When the system imports functions from an object, it searches all public methods tagged with this attribute.
+/// When the system imports functions from an object, it searches for all public methods tagged with this attribute.
 /// If a method is not tagged with this attribute, it may still be imported directly via a <see cref="Delegate"/>
 /// or <see cref="MethodInfo"/> referencing the method directly.
 /// </para>
@@ -26,18 +26,52 @@ namespace Microsoft.SemanticKernel;
 /// by an LLM or embedding.
 /// </para>
 /// <para>
-/// Functions may have any number of parameters. A given method function may declare at
-/// most one parameter of each of these types - <see cref="Kernel"/>, <see cref="KernelArguments"/>,
-/// <see cref="CancellationToken"/>, <see cref="CultureInfo"/>, <see cref="ILogger"/> or <see cref="ILoggerFactory"/>.
-/// Parameters are populated based on a arguments of the same name. If no argument of the given name is present, but
-/// a default value was specified via either a <see cref="DefaultValueAttribute"/> or an optional value in the signature,
-/// that default value is used instead. If no default value was specified and it's the first parameter, the "input"
-/// argument will be used.  Otherwise, if no value is available, the invocation will fail.
+/// Functions may have any number of parameters. In general, arguments to parameters are supplied via the <see cref="KernelArguments"/>
+/// used to invoke the function, with the arguments matched by name to the parameters of the method. If no argument of the given name
+/// is present, but a default value was specified in the method's definition, that default value will be used. If the argument value in
+/// <see cref="KernelArguments"/> is not of the same type as the parameter, the system will attempt to convert the value to the parameter's
+/// type using a <see cref="TypeConverter"/>.
 /// </para>
 /// <para>
-/// For non-string parameters, the argument value is automatically converted to the appropriate type to be passed
-/// in based on the <see cref="TypeConverter"/> for the specified type. Similarly, return values are automatically converted
-/// back to strings via the associated <see cref="TypeConverter"/>.
+/// However, parameters of the following types are treated specially and are supplied from a source other than from the arguments dictionary:
+/// <list type="table">
+/// <item>
+/// <term><see cref="Kernel"/></term>
+/// <description>The <see cref="Kernel"/> supplied when invoking the function.</description>
+/// </item>
+/// <item>
+/// <term><see cref="KernelArguments"/></term>
+/// <description>The <see cref="KernelArguments"/> supplied when invoking the function.</description>
+/// </item>
+/// <item>
+/// <term><see cref="KernelFunction"/></term>
+/// <description>The <see cref="KernelFunction"/> that represents this function being invoked.</description>
+/// </item>
+/// <item>
+/// <term><see cref="CancellationToken"/></term>
+/// <description>The <see cref="CancellationToken"/> supplied when invoking the function.</description>
+/// </item>
+/// <item>
+/// <term><see cref="CultureInfo"/> or <see cref="IFormatProvider"/></term>
+/// <description>The result of <see cref="Kernel.Culture"/> from the <see cref="Kernel"/> used when invoking the function.</description>
+/// </item>
+/// <item>
+/// <term><see cref="ILoggerFactory"/> or <see cref="ILogger"/></term>
+/// <description>The result of <see cref="Kernel.LoggerFactory"/> from the <see cref="Kernel"/> (or an <see cref="ILogger"/> created from it) used when invoking the function.</description>
+/// </item>
+/// <item>
+/// <term><see cref="IAIServiceSelector"/></term>
+/// <description>The result of <see cref="Kernel.ServiceSelector"/> from the <see cref="Kernel"/> used when invoking the function.</description>
+/// </item>
+/// </list>
+/// </para>
+/// <para>
+/// Arguments may also be fulfilled from the associated <see cref="Kernel"/>'s <see cref="Kernel.Services"/> service provider. If a parameter is attributed
+/// with <see cref="FromKernelServicesAttribute"/>, the system will attempt to resolve the parameter by querying the service provider for a service of the
+/// parameter's type. If the service provider does not contain a service of the parameter's type and the parameter is not optional, the invocation will fail.
+/// </para>
+/// <para>
+/// If no value can be derived from any of these means for all parameters, the invocation will fail.
 /// </para>
 /// </remarks>
 [AttributeUsage(AttributeTargets.Method, AllowMultiple = false)]