Merge branch 'main' into users/markwallace/issue_9933

.github/workflows/generate-pr-description.yml

@@ -13,7 +13,7 @@ jobs:
     if: github.event.issue.pull_request && contains(github.event.comment.body, '/sk generate-pr-description')
     steps:
       - name: Get PR branch
-        uses: xt0rted/pull-request-comment-branch@v1
+        uses: xt0rted/pull-request-comment-branch@v3
         id: comment-branch
 
       - name: Set latest commit status as pending

README.md

@@ -67,7 +67,7 @@ feature parity between our currently supported languages.
       <td>
         <img align="left" width=52px height=52px src="https://upload.wikimedia.org/wikipedia/en/3/30/Java_programming_language_logo.svg" alt="Java logo">
         <div>
-          <a href="https://github.com/microsoft/semantic-kernel/blob/main/java/README.md">Using Semantic Kernel in Java</a>
+          <a href="https://github.com/microsoft/semantic-kernel-java/blob/main/README.md">Using Semantic Kernel in Java</a>
         </div>
       </td>
     </tr>

docs/decisions/0046-java-repository-separation.md

@@ -0,0 +1,50 @@
+---
+# These are optional elements. Feel free to remove any of them.
+status: proposed
+contact: John Oliver
+date: 2024-06-18
+---
+
+# Separate Java Repository To a Separate Code Base
+
+## Context and Problem Statement
+
+Managing multiple languages within a single repository provides some challenges with respect to how different languages and their build tools
+manage repositories. Particularly with respect to how common build tooling for Java, like Apache Maven, interacts with repositories. Typically,
+while doing a Maven release you want to be able to freeze your repository so that commits are not being added while
+preparing a release. To achieve this in a shared repository we would effectively need to request all languages halt
+merging pull requests while we are in this process. The Maven release process also interacts badly with the projects
+desire for merges to be squashed which for the most part blocks a typical Maven release process that needs to push
+multiple commits into a repository.
+
+Additionally, from a discoverability standpoint, in the original repository the majority of current pull requests, issues and activity are from
+other languages. This has created some
+confusion from users about if the semantic kernel repository is the correct repository for Java. Managing git history
+when performing tasks such as looking
+at diffs or compiling release notes is also significantly harder when the majority of commits and code are unrelated to Java.
+
+Also managing repository policies that are preferred by all languages is a challenge as we have to produce a more
+complex build process to account for building multiple languages. If a user makes accidental changes to the repository outside their own language,
+or make changes to the common files, require sign off from other languages, leading to delays as we
+require review from users in other languages. Similarly common files such as GitHub Actions workflows, `.gitignore`, VS Code settings, `README.md`, `.editorconfig` etc, become
+more complex as they have to simutaniously support multiple languages.
+
+In a community point of view, having a separate repo will foster community engagement, allowing developers to contribute, share ideas, and collaborate on the Java projects only.
+Additionally, it enables transparent tracking of contributions, making it easy to identify top contributors and acknowledge their efforts. 
+Having a single repository will also provide valuable statistics on commits, pull requests, and other activities, helping maintainers monitor project progress and activity levels. 
+
+## Decision Drivers
+
+- Allow project settings that are compatible with Java tooling
+- Improve the communities' ability to discover and interact with the Java project
+- Improve the ability for the community to observe changes to the Java project in isolation
+- Simplify repository build/files to concentrate on a single language
+
+## Considered Options
+
+We have in the past run out of a separate branch within the [Semantic Kernel](https://github.co/microsoft/semantic-kernel) repository which solved 
+some of the issues however significantly hindered user discoverability as users expect to find the latest code on the main branch.
+
+## Decision Outcome
+
+Java repository has been moved to [semantic-kernel-java](https://github.com/microsoft/semantic-kernel-java)

dotnet/Directory.Packages.props

@@ -15,7 +15,7 @@
     <PackageVersion Include="Microsoft.AspNetCore.Mvc.Testing" Version="8.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.Abstractions" Version="8.0.0" />
     <PackageVersion Include="Microsoft.ML.Tokenizers.Data.Cl100kBase" Version="1.0.0" />
-    <PackageVersion Include="Microsoft.IdentityModel.JsonWebTokens" Version="6.34.0" />
+    <PackageVersion Include="Microsoft.IdentityModel.JsonWebTokens" Version="7.5.1" />
     <PackageVersion Include="Microsoft.VisualStudio.Threading" Version="17.12.19" />
     <PackageVersion Include="MSTest.TestFramework" Version="3.6.3" />
     <PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
@@ -29,12 +29,12 @@
     <PackageVersion Include="Handlebars.Net.Helpers" Version="2.4.6" />
     <PackageVersion Include="Markdig" Version="0.37.0" />
     <PackageVersion Include="Handlebars.Net" Version="2.1.6" />
-    <PackageVersion Include="HtmlAgilityPack" Version="1.11.67" />
+    <PackageVersion Include="HtmlAgilityPack" Version="1.11.71" />
     <PackageVersion Include="Microsoft.AspNet.WebApi.Client" Version="6.0.0" />
     <PackageVersion Include="JsonSchema.Net" Version="5.4.2" />
     <PackageVersion Include="Microsoft.Azure.Functions.Worker" Version="1.20.1" />
     <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.Http" Version="3.1.0" />
-    <PackageVersion Include="Microsoft.Azure.Kusto.Data" Version="12.2.7" />
+    <PackageVersion Include="Microsoft.Azure.Kusto.Data" Version="12.2.8" />
     <PackageVersion Include="Microsoft.Azure.WebJobs.Extensions.OpenApi" Version="1.5.1" />
     <PackageVersion Include="Microsoft.Bcl.HashCode" Version="1.1.1" />
     <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="8.0.0" />
@@ -49,7 +49,7 @@
     <PackageVersion Include="Pinecone.NET" Version="2.1.1" />
     <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="8.0.1" />
     <PackageVersion Include="System.Formats.Asn1" Version="8.0.1" />
-    <PackageVersion Include="System.IdentityModel.Tokens.Jwt" Version="6.34.0" />
+    <PackageVersion Include="System.IdentityModel.Tokens.Jwt" Version="7.5.1" />
     <PackageVersion Include="System.IO.Packaging" Version="8.0.1" />
     <PackageVersion Include="System.Linq.Async" Version="6.0.1" />
     <PackageVersion Include="System.Memory.Data" Version="8.0.1" />
@@ -102,7 +102,7 @@
     <PackageVersion Include="DuckDB.NET.Data" Version="1.1.2.1" />
     <PackageVersion Include="MongoDB.Driver" Version="2.30.0" />
     <PackageVersion Include="Microsoft.Graph" Version="4.51.0" />
-    <PackageVersion Include="Microsoft.Identity.Client.Extensions.Msal" Version="2.28.0" />
+    <PackageVersion Include="Microsoft.Identity.Client.Extensions.Msal" Version="4.61.3" />
     <PackageVersion Include="Microsoft.OpenApi" Version="1.6.22" />
     <PackageVersion Include="Microsoft.OpenApi.Readers" Version="1.6.22" />
     <PackageVersion Include="Microsoft.OpenApi.ApiManifest" Version="0.5.6-preview" />
@@ -134,7 +134,7 @@
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
-    <PackageVersion Include="xunit.analyzers" Version="1.16.0" />
+    <PackageVersion Include="xunit.analyzers" Version="1.17.0" />
     <PackageReference Include="xunit.analyzers">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>

dotnet/samples/Concepts/ChatCompletion/OpenAI_ChatCompletion.cs

@@ -107,6 +107,36 @@ public async Task ChatPromptWithInnerContentAsync()
         OutputInnerContent(replyInnerContent!);
     }
 
+    /// <summary>
+    /// Demonstrates how you can store the output of a chat completion request for use in the OpenAI model distillation or evals products.
+    /// </summary>
+    /// <remarks>
+    /// This sample adds metadata to the chat completion request which allows the requests to be filtered in the OpenAI dashboard.
+    /// </remarks>
+    [Fact]
+    public async Task ChatPromptStoreWithMetadataAsync()
+    {
+        Assert.NotNull(TestConfiguration.OpenAI.ChatModelId);
+        Assert.NotNull(TestConfiguration.OpenAI.ApiKey);
+
+        StringBuilder chatPrompt = new("""
+                                       <message role="system">You are a librarian, expert about books</message>
+                                       <message role="user">Hi, I'm looking for book suggestions about Artificial Intelligence</message>
+                                       """);
+
+        var kernel = Kernel.CreateBuilder()
+            .AddOpenAIChatCompletion(TestConfiguration.OpenAI.ChatModelId, TestConfiguration.OpenAI.ApiKey)
+            .Build();
+
+        var functionResult = await kernel.InvokePromptAsync(chatPrompt.ToString(),
+            new(new OpenAIPromptExecutionSettings { Store = true, Metadata = new Dictionary<string, string>() { { "concept", "chatcompletion" } } }));
+
+        var messageContent = functionResult.GetValue<ChatMessageContent>(); // Retrieves underlying chat message content from FunctionResult.
+        var replyInnerContent = messageContent!.InnerContent as OpenAI.Chat.ChatCompletion; // Retrieves inner content from ChatMessageContent.
+
+        OutputInnerContent(replyInnerContent!);
+    }
+
     private async Task StartChatAsync(IChatCompletionService chatGPT)
     {
         Console.WriteLine("Chat content:");

dotnet/samples/Concepts/FunctionCalling/AzureAIInference_FunctionCalling.cs

@@ -5,6 +5,9 @@
 namespace FunctionCalling;
 public class AzureAIInference_FunctionCalling(ITestOutputHelper output) : BaseTest(output)
 {
+    /// <summary>
+    /// This example demonstrates usage of <see cref="FunctionChoiceBehavior.Auto"/> that advertises all kernel functions to the AI model.
+    /// </summary>
     [Fact]
     public async Task FunctionCallingAsync()
     {

dotnet/samples/Concepts/README.md

@@ -39,8 +39,9 @@ dotnet test -l "console;verbosity=detailed" --filter "FullyQualifiedName=ChatCom
 
 ### FunctionCalling - Examples on `Function Calling` with function call capable models
 
-- [Gemini_FunctionCalling](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/FunctionCalling/Gemini_FunctionCalling.cs)
 - [FunctionCalling](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/FunctionCalling/FunctionCalling.cs)
+- [Gemini_FunctionCalling](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/FunctionCalling/Gemini_FunctionCalling.cs)
+- [AzureAIInference_FunctionCalling](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/FunctionCalling/AzureAIInference_FunctionCalling.cs)
 - [NexusRaven_HuggingFaceTextGeneration](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/FunctionCalling/NexusRaven_FunctionCalling.cs)
 - [MultipleFunctionsVsParameters](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/FunctionCalling/MultipleFunctionsVsParameters.cs)
 

dotnet/src/Connectors/Connectors.AzureOpenAI.UnitTests/Settings/AzureOpenAIPromptExecutionSettingsTests.cs

@@ -36,6 +36,8 @@ public void ItCreatesOpenAIExecutionSettingsWithCorrectDefaults()
         Assert.Null(executionSettings.Logprobs);
         Assert.Null(executionSettings.AzureChatDataSource);
         Assert.Equal(maxTokensSettings, executionSettings.MaxTokens);
+        Assert.Null(executionSettings.Store);
+        Assert.Null(executionSettings.Metadata);
     }
 
     [Fact]
@@ -54,13 +56,24 @@ public void ItUsesExistingOpenAIExecutionSettings()
             Logprobs = true,
             TopLogprobs = 5,
             TokenSelectionBiases = new Dictionary<int, int>() { { 1, 2 }, { 3, 4 } },
+            Seed = 123456,
+            Store = true,
+            Metadata = new Dictionary<string, string>() { { "foo", "bar" } }
         };
 
         // Act
         AzureOpenAIPromptExecutionSettings executionSettings = AzureOpenAIPromptExecutionSettings.FromExecutionSettings(actualSettings);
 
         // Assert
         Assert.Equal(actualSettings, executionSettings);
+        Assert.Equal(actualSettings, executionSettings);
+        Assert.Equal(actualSettings.MaxTokens, executionSettings.MaxTokens);
+        Assert.Equal(actualSettings.Logprobs, executionSettings.Logprobs);
+        Assert.Equal(actualSettings.TopLogprobs, executionSettings.TopLogprobs);
+        Assert.Equal(actualSettings.TokenSelectionBiases, executionSettings.TokenSelectionBiases);
+        Assert.Equal(actualSettings.Seed, executionSettings.Seed);
+        Assert.Equal(actualSettings.Store, executionSettings.Store);
+        Assert.Equal(actualSettings.Metadata, executionSettings.Metadata);
     }
 
     [Fact]
@@ -71,7 +84,9 @@ public void ItCanUseOpenAIExecutionSettings()
         {
             ExtensionData = new Dictionary<string, object>() {
                 { "max_tokens", 1000 },
-                { "temperature", 0 }
+                { "temperature", 0 },
+                { "store", true },
+                { "metadata", new Dictionary<string, string>() { { "foo", "bar" } } }
             }
         };
 
@@ -82,6 +97,8 @@ public void ItCanUseOpenAIExecutionSettings()
         Assert.NotNull(executionSettings);
         Assert.Equal(1000, executionSettings.MaxTokens);
         Assert.Equal(0, executionSettings.Temperature);
+        Assert.True(executionSettings.Store);
+        Assert.Equal(new Dictionary<string, string>() { { "foo", "bar" } }, executionSettings.Metadata);
     }
 
     [Fact]
@@ -103,6 +120,8 @@ public void ItCreatesOpenAIExecutionSettingsFromExtraPropertiesSnakeCase()
                 { "seed", 123456 },
                 { "logprobs", true },
                 { "top_logprobs", 5 },
+                { "store", true },
+                { "metadata", new Dictionary<string, string>() { { "foo", "bar" } } }
             }
         };
 
@@ -131,7 +150,9 @@ public void ItCreatesOpenAIExecutionSettingsFromExtraPropertiesAsStrings()
                 { "token_selection_biases", new Dictionary<string, string>() { { "1", "2" }, { "3", "4" } } },
                 { "seed", 123456 },
                 { "logprobs", true },
-                { "top_logprobs", 5 }
+                { "top_logprobs", 5 },
+                { "store", true },
+                { "metadata", new Dictionary<string, string>() { { "foo", "bar" } } }
             }
         };
 
@@ -158,7 +179,9 @@ public void ItCreatesOpenAIExecutionSettingsFromJsonSnakeCase()
               "max_tokens": 128,
               "seed": 123456,
               "logprobs": true,
-              "top_logprobs": 5
+              "top_logprobs": 5,
+              "store": true,
+              "metadata": { "foo": "bar" }
             }
             """;
         var actualSettings = JsonSerializer.Deserialize<PromptExecutionSettings>(json);
@@ -217,7 +240,9 @@ public void PromptExecutionSettingsFreezeWorksAsExpected()
             "presence_penalty": 0.0,
             "frequency_penalty": 0.0,
             "stop_sequences": [ "DONE" ],
-            "token_selection_biases": { "1": 2, "3": 4 }
+            "token_selection_biases": { "1": 2, "3": 4 },
+            "store": true,
+            "metadata": { "foo": "bar" }
         }
         """;
         var executionSettings = JsonSerializer.Deserialize<AzureOpenAIPromptExecutionSettings>(configPayload);
@@ -232,6 +257,8 @@ public void PromptExecutionSettingsFreezeWorksAsExpected()
         Assert.Throws<InvalidOperationException>(() => executionSettings.TopP = 1);
         Assert.Throws<NotSupportedException>(() => executionSettings.StopSequences?.Add("STOP"));
         Assert.Throws<NotSupportedException>(() => executionSettings.TokenSelectionBiases?.Add(5, 6));
+        Assert.Throws<InvalidOperationException>(() => executionSettings.Store = false);
+        Assert.Throws<NotSupportedException>(() => executionSettings.Metadata?.Add("bar", "foo"));
 
         executionSettings!.Freeze(); // idempotent
         Assert.True(executionSettings.IsFrozen);
@@ -267,7 +294,9 @@ public void ItCanCreateAzureOpenAIPromptExecutionSettingsFromOpenAIPromptExecuti
             Logprobs = true,
             Seed = 123456,
             TopLogprobs = 5,
-            ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions
+            ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions,
+            Store = true,
+            Metadata = new Dictionary<string, string>() { { "foo", "bar" } }
         };
 
         // Act
@@ -307,5 +336,7 @@ private static void AssertExecutionSettings(AzureOpenAIPromptExecutionSettings e
         Assert.Equal(123456, executionSettings.Seed);
         Assert.Equal(true, executionSettings.Logprobs);
         Assert.Equal(5, executionSettings.TopLogprobs);
+        Assert.Equal(true, executionSettings.Store);
+        Assert.Equal(new Dictionary<string, string>() { { "foo", "bar" } }, executionSettings.Metadata);
     }
 }

dotnet/src/Connectors/Connectors.AzureOpenAI/Core/AzureClientCore.ChatCompletion.cs

@@ -49,6 +49,7 @@ protected override ChatCompletionOptions CreateChatCompletionOptions(
             EndUserId = executionSettings.User,
             TopLogProbabilityCount = executionSettings.TopLogprobs,
             IncludeLogProbabilities = executionSettings.Logprobs,
+            StoredOutputEnabled = executionSettings.Store,
         };
 
         var responseFormat = GetResponseFormat(executionSettings);
@@ -90,6 +91,14 @@ protected override ChatCompletionOptions CreateChatCompletionOptions(
             }
         }
 
+        if (executionSettings.Metadata is not null)
+        {
+            foreach (var kvp in executionSettings.Metadata)
+            {
+                options.Metadata.Add(kvp.Key, kvp.Value);
+            }
+        }
+
         if (toolCallingConfig.Options?.AllowParallelCalls is not null)
         {
             options.AllowParallelToolCalls = toolCallingConfig.Options.AllowParallelCalls;