Merge main

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,8 +1,9 @@
 ---
 name: Bug report
 about: Create a report to help us improve
-title: ''
-labels: ''
+title: 'Bug: '
+labels: ["bug"]
+projects: ["semantic-kernel"]
 assignees: ''
 
 ---

.github/ISSUE_TEMPLATE/feature_graduation.md

@@ -0,0 +1,29 @@
+---
+name: Feature graduation
+about: Plan the graduation of an experimental feature
+title: 'Graduate XXX feature'
+labels: ["feature_graduation"]
+projects: ["semantic-kernel"]
+assignees: ''
+
+---
+
+---
+name: Feature graduation
+about: Plan the graduation of an experimental feature
+
+---
+
+Checklist to be completed when graduating an experimental feature
+
+- [ ] Notify PM's and EM's that feature is read for graduation
+- [ ] Contact PM for list of sample use cases
+- [ ] Verify there are sample implementations​ for each of the use cases
+- [ ] Verify telemetry and logging are complete
+- [ ] ​Verify API docs are complete and arrange to have them published
+- [ ] Make appropriate updates to Learn docs​
+- [ ] Make appropriate updates to Concept samples
+- [ ] Male appropriate updates to Blog posts
+- [ ] Verify there are no serious open Issues​​
+- [ ] Update table in EXPERIMENTS.md
+- [ ] Remove SKEXP​ flag from the experimental code

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,8 +1,9 @@
 ---
 name: Feature request
 about: Suggest an idea for this project
-title: ''
+title: 'New Feature: '
 labels: ''
+projects: ["semantic-kernel"]
 assignees: ''
 
 ---

.github/_typos.toml

@@ -15,6 +15,7 @@ extend-exclude = [
     "CodeTokenizerTests.cs",
     "test_code_tokenizer.py",
     "*response.json",
+    "test_content.txt",
 ]
 
 [default.extend-words]
@@ -28,6 +29,7 @@ ans = "ans"               # Short for answers
 arange = "arange"         # Method in Python numpy package
 prompty = "prompty"       # prompty is a format name.
 ist = "ist"               # German language
+dall = "dall"             # OpenAI model name
 
 [default.extend-identifiers]
 ags = "ags" # Azure Graph Service

.github/workflows/python-integration-tests.yml

@@ -92,13 +92,18 @@ jobs:
           AZURE_AI_SEARCH_API_KEY: ${{secrets.AZURE_AI_SEARCH_API_KEY}}
           AZURE_AI_SEARCH_ENDPOINT: ${{secrets.AZURE_AI_SEARCH_ENDPOINT}}
           MONGODB_ATLAS_CONNECTION_STRING: ${{secrets.MONGODB_ATLAS_CONNECTION_STRING}}
+          AZURE_KEY_VAULT_ENDPOINT: ${{secrets.AZURE_KEY_VAULT_ENDPOINT}}
+          AZURE_KEY_VAULT_CLIENT_ID: ${{secrets.AZURE_KEY_VAULT_CLIENT_ID}}
+          AZURE_KEY_VAULT_CLIENT_SECRET: ${{secrets.AZURE_KEY_VAULT_CLIENT_SECRET}}
+          ACA_POOL_MANAGEMENT_ENDPOINT: ${{secrets.ACA_POOL_MANAGEMENT_ENDPOINT}}
         run: |
           if ${{ matrix.os == 'ubuntu-latest' }}; then
             docker run -d --name redis-stack-server -p 6379:6379 redis/redis-stack-server:latest
           fi
 
           cd python
           poetry run pytest ./tests/integration -v
+          poetry run pytest ./tests/samples -v
 
   python-integration-tests:
     needs: paths-filter
@@ -154,13 +159,18 @@ jobs:
           AZURE_AI_SEARCH_API_KEY: ${{secrets.AZURE_AI_SEARCH_API_KEY}}
           AZURE_AI_SEARCH_ENDPOINT: ${{secrets.AZURE_AI_SEARCH_ENDPOINT}}
           MONGODB_ATLAS_CONNECTION_STRING: ${{secrets.MONGODB_ATLAS_CONNECTION_STRING}}
+          AZURE_KEY_VAULT_ENDPOINT: ${{secrets.AZURE_KEY_VAULT_ENDPOINT}}
+          AZURE_KEY_VAULT_CLIENT_ID: ${{secrets.AZURE_KEY_VAULT_CLIENT_ID}}
+          AZURE_KEY_VAULT_CLIENT_SECRET: ${{secrets.AZURE_KEY_VAULT_CLIENT_SECRET}}
+          ACA_POOL_MANAGEMENT_ENDPOINT: ${{secrets.ACA_POOL_MANAGEMENT_ENDPOINT}}
         run: |
           if ${{ matrix.os == 'ubuntu-latest' }}; then
             docker run -d --name redis-stack-server -p 6379:6379 redis/redis-stack-server:latest
           fi
 
           cd python
           poetry run pytest ./tests/integration -v
+          poetry run pytest ./tests/samples -v
 
   # This final job is required to satisfy the merge queue. It must only run (or succeed) if no tests failed
   python-integration-tests-check:

.github/workflows/python-lint.yml

@@ -1,7 +1,7 @@
 name: Python Code Quality Checks
 on:
   workflow_dispatch:
-  pull_request_target:
+  pull_request:
     branches: [ "main", "feature*" ]
     paths:
       - 'python/**'

README.md

@@ -1,9 +1,15 @@
 # Semantic Kernel
 
+## Status
+
+ - Python <br/>
 [![Python package](https://img.shields.io/pypi/v/semantic-kernel)](https://pypi.org/project/semantic-kernel/)
-[![Nuget package](https://img.shields.io/nuget/vpre/Microsoft.SemanticKernel)](https://www.nuget.org/packages/Microsoft.SemanticKernel/)
-[![dotnet Docker](https://github.com/microsoft/semantic-kernel/actions/workflows/dotnet-ci-docker.yml/badge.svg?branch=main)](https://github.com/microsoft/semantic-kernel/actions/workflows/dotnet-ci-docker.yml)
-[![dotnet Windows](https://github.com/microsoft/semantic-kernel/actions/workflows/dotnet-ci-windows.yml/badge.svg?branch=main)](https://github.com/microsoft/semantic-kernel/actions/workflows/dotnet-ci-windows.yml)
+ - .NET <br/>
+[![Nuget package](https://img.shields.io/nuget/vpre/Microsoft.SemanticKernel)](https://www.nuget.org/packages/Microsoft.SemanticKernel/)[![dotnet Docker](https://github.com/microsoft/semantic-kernel/actions/workflows/dotnet-ci-docker.yml/badge.svg?branch=main)](https://github.com/microsoft/semantic-kernel/actions/workflows/dotnet-ci-docker.yml)[![dotnet Windows](https://github.com/microsoft/semantic-kernel/actions/workflows/dotnet-ci-windows.yml/badge.svg?branch=main)](https://github.com/microsoft/semantic-kernel/actions/workflows/dotnet-ci-windows.yml)
+ - Java <br/>
+[![Java CICD Builds](https://github.com/microsoft/semantic-kernel/actions/workflows/java-build.yml/badge.svg?branch=java-development)](https://github.com/microsoft/semantic-kernel/actions/workflows/java-build.yml)[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.microsoft.semantic-kernel/semantickernel-api/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.microsoft.semantic-kernel/semantickernel-api)
+
+## Overview
 [![License: MIT](https://img.shields.io/github/license/microsoft/semantic-kernel)](https://github.com/microsoft/semantic-kernel/blob/main/LICENSE)
 [![Discord](https://img.shields.io/discord/1063152441819942922?label=Discord&logo=discord&logoColor=white&color=d82679)](https://aka.ms/SKDiscord)
 
@@ -107,6 +113,7 @@ Finally, refer to our API references for more details on the C# and Python APIs:
 
 - [C# API reference](https://learn.microsoft.com/en-us/dotnet/api/microsoft.semantickernel?view=semantic-kernel-dotnet)
 - Python API reference (coming soon)
+- Java API reference (coming soon)
 
 ## Join the community
 

docs/EUCLIDEAN_DISTANCE.md

@@ -1,15 +1,15 @@
-# Euclidean distance
+# Euclidean Distance
 
 Euclidean distance is a mathematical concept that measures the straight-line distance
 between two points in a Euclidean space. It is named after the ancient Greek mathematician
 Euclid, who is often referred to as the "father of geometry". The formula for calculating
-Euclidean distance is based on the Pythagorean theorem and can be expressed as:
+Euclidean distance is based on the Pythagorean Theorem and can be expressed as:
 
-    d = √(x2 - x1)² + (y2 - y1)²
+$$d = \sqrt{(x_2 - x_1)^2 + (y_2 - y_1)^2}$$
 
-In higher dimensions, this formula can be generalized to:
+For higher dimensions, this formula can be generalized to:
 
-    d = √(x2 - x1)² + (y2 - y1)² + ... + (zn - zn-1)²
+$$d(p, q) = \sqrt{\sum\limits_{i\=1}^{n} (q_i - p_i)^2}$$
 
 Euclidean distance has many applications in computer science and artificial intelligence,
 particularly when working with [embeddings](EMBEDDINGS.md). Embeddings are numerical

docs/decisions/0045-breaking-changes-guidance.md

@@ -0,0 +1,40 @@
+---
+status: accepted
+contact: markwallace
+date: 2024-06-10
+deciders: sergeymenshykh, mbolan, rbarreto, dmytrostruk, westey
+consulted: 
+informed: 
+---
+
+# Guidance for Breaking Changes
+
+## Context and Problem Statement
+
+We must avoid breaking changes in .Net because of the well known [diamond dependency issue](https://learn.microsoft.com/en-us/dotnet/standard/library-guidance/dependencies#diamond-dependencies) where breaking changes between different versions of the same package cause bugs and exceptions at run time.
+
+## Decision Drivers
+
+Breaking changes are only allowed under the following circumstances:
+
+- Updates to an experimental feature i.e. we have learnt something new and need to modify the design of an experimental feature.
+- When one of our dependencies introduces an unavoidable breaking change.
+
+All breaking changes must be clearly documented, definitely in the release notes and possibly also via a migration guide Blog post.
+
+- Include a detailed description of the breaking change in the PR description so that it is included in the release notes.
+- Update Learn Site migration guide documentation and have this published to coincide with the release which includes the breaking change.
+
+In all other cases we must avoid breaking changes. There will be situations where we need to move to accommodate a change to one of our dependencies or introduce a new capability e.g.
+
+- When we find a security issue or a severe bug (e.g. data loss).
+- One of our dependencies introduces a major breaking change e.g. the introduction of the new OpenAI SDK.
+- When we find a severe limitation in our current implementation e.g. when the AI services introduce a new capability.
+
+In these cases we will plan to obsolete the API(s) and provide a documented migration path to the new preferred pattern.
+An example of this will be the switch to the new OpenAI .Net SDK.
+During this transition there will be a period where the new and old API's will be supported to allow customers to migrate.
+
+## Decision Outcome
+
+Chosen option: We must avoid breaking changes in .Net because of the well known diamond dependency issue.

docs/decisions/0046-azure-model-as-a-service.md

@@ -0,0 +1,44 @@
+---
+# These are optional elements. Feel free to remove any of them.
+status: { accepted }
+contact: { rogerbarreto, taochen }
+date: { 2024-06-20 }
+deciders: { alliscode, moonbox3, eavanvalkenburg }
+consulted: {}
+informed: {}
+---
+
+# Support for Azure Model-as-a-Service in SK
+
+## Context and Problem Statement
+
+There has been a demand from customers for the implementation of Model-as-a-Service (MaaS) in SK. MaaS, which is also referred to as [serverless API](https://learn.microsoft.com/en-us/azure/ai-studio/how-to/model-catalog-overview#model-deployment-managed-compute-and-serverless-api-pay-as-you-go), is available in [Azure AI Studio](https://learn.microsoft.com/en-us/azure/ai-studio/what-is-ai-studio). This mode of consumption operates on a pay-as-you-go basis, typically using tokens for billing purposes. Clients can access the service via the [Azure AI Model Inference API](https://learn.microsoft.com/en-us/azure/ai-studio/reference/reference-model-inference-api?tabs=azure-studio) or client SDKs.
+
+At present, there is no official support for MaaS in SK. The purpose of this ADR is to examine the constraints of the service and explore potential solutions to enable support for the service in SK via the development of a new AI connector.
+
+## Client SDK
+
+The Azure team will be providing a new client library, namely `Azure.AI.Inference` in .Net and `azure-ai-inference` in Python, for effectively interacting with the service. While the service API is OpenAI-compatible, it is not permissible to use the OpenAI and the Azure OpenAI client libraries for interacting with the service as they are not independent with respect to both the models and their providers. This is because Azure AI Studio features a diverse range of open-source models, other than OpenAI models.
+
+### Limitations
+
+The initial release of the client SDK will only support chat completion and text/image embedding generation, with image generation to be added later.
+
+Plans to support for text completion are currently unclear, and it is highly unlikely that the SDK will ever include support for text completion. As a result, the new AI connector will **NOT** support text completions in the initial version until we get more customer signals or the client SDK adds support.
+
+## AI Connector
+
+### Naming options
+
+- Azure
+- AzureAI
+- AzureAIInference
+- AzureAIModelInference
+
+  Decision: `AzureAIInference`
+
+### Support for model-specific parameters
+
+Models can possess supplementary parameters that are not part of the default API. The service API and the client SDK enable the provision of model-specific parameters. Users can provide model-specific settings via a dedicated argument along with other settings, such as `temperature` and `top_p`, among others.
+
+In the context of SK, execution parameters are categorized under `PromptExecutionSettings`, which is inherited by all connector-specific setting classes. The settings of the new connector will contain a member of type `dictionary`, which will group together the model-specific parameters.

dotnet/Directory.Packages.props

@@ -8,7 +8,7 @@
     <PackageVersion Include="Azure.AI.ContentSafety" Version="1.0.0" />
     <PackageVersion Include="Azure.AI.OpenAI" Version="1.0.0-beta.17" />
     <PackageVersion Include="Azure.AI.OpenAI.Assistants" Version="1.0.0-beta.3" />
-    <PackageVersion Include="Azure.Identity" Version="1.11.3" />
+    <PackageVersion Include="Azure.Identity" Version="1.12.0" />
     <PackageVersion Include="Azure.Monitor.OpenTelemetry.Exporter" Version="1.2.0" />
     <PackageVersion Include="Azure.Search.Documents" Version="11.5.1" />
     <PackageVersion Include="Handlebars.Net.Helpers" Version="2.4.1.5" />
@@ -27,8 +27,8 @@
     <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.3.0" />
     <PackageVersion Include="Microsoft.Bcl.TimeProvider" Version="8.0.1" />
     <PackageVersion Include="Microsoft.Extensions.Logging.Debug" Version="8.0.0" />
-    <PackageVersion Include="Microsoft.Identity.Client" Version="4.61.0" />
-    <PackageVersion Include="Microsoft.ML.OnnxRuntime" Version="1.17.1" />
+    <PackageVersion Include="Microsoft.Identity.Client" Version="4.61.3" />
+    <PackageVersion Include="Microsoft.ML.OnnxRuntime" Version="1.18.0" />
     <PackageVersion Include="FastBertTokenizer" Version="1.0.28" />
     <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="8.0.1" />
     <PackageVersion Include="System.Linq.Async" Version="6.0.1" />
@@ -71,16 +71,16 @@
     <!-- Plugins -->
     <PackageVersion Include="DocumentFormat.OpenXml" Version="3.0.2" />
     <PackageVersion Include="Microsoft.Data.Sqlite" Version="8.0.2" />
-    <PackageVersion Include="DuckDB.NET.Data.Full" Version="0.10.1.2" />
-    <PackageVersion Include="DuckDB.NET.Data" Version="0.10.2" />
+    <PackageVersion Include="DuckDB.NET.Data.Full" Version="1.0.0" />
+    <PackageVersion Include="DuckDB.NET.Data" Version="1.0.0" />
     <PackageVersion Include="MongoDB.Driver" Version="2.25.0" />
     <PackageVersion Include="Microsoft.Graph" Version="[4.51.0, 5)" />
     <PackageVersion Include="Microsoft.Identity.Client.Extensions.Msal" Version="[2.28.0, )" />
     <PackageVersion Include="Microsoft.OpenApi" Version="1.6.14" />
     <PackageVersion Include="Microsoft.OpenApi.Readers" Version="1.6.14" />
     <PackageVersion Include="Microsoft.OpenApi.ApiManifest" Version="0.5.4-preview" />
     <PackageVersion Include="Google.Apis.CustomSearchAPI.v1" Version="[1.60.0.3001, )" />
-    <PackageVersion Include="Grpc.Net.Client" Version="2.62.0" />
+    <PackageVersion Include="Grpc.Net.Client" Version="2.63.0" />
     <PackageVersion Include="protobuf-net" Version="3.2.30" />
     <PackageVersion Include="protobuf-net.Reflection" Version="3.2.12" />
     <PackageVersion Include="YamlDotNet" Version="15.1.4" />
@@ -110,7 +110,7 @@
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
-    <PackageVersion Include="Moq.Analyzers" Version="0.0.9" />
+    <PackageVersion Include="Moq.Analyzers" Version="0.1.0" />
     <PackageReference Include="Moq.Analyzers">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>

dotnet/nuget/nuget-package.props

@@ -1,7 +1,7 @@
 <Project>
   <PropertyGroup>
     <!-- Central version prefix - applies to all nuget packages. -->
-    <VersionPrefix>1.14.1</VersionPrefix>
+    <VersionPrefix>1.15.0</VersionPrefix>
 
     <PackageVersion Condition="'$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix)</PackageVersion>
     <PackageVersion Condition="'$(VersionSuffix)' == ''">$(VersionPrefix)</PackageVersion>

dotnet/samples/Concepts/Agents/ComplexChat_NestedShopper.cs

@@ -94,7 +94,7 @@ Select which participant will take the next turn based on the conversation histo
         """;
 
     [Fact]
-    public async Task RunAsync()
+    public async Task NestedChatWithAggregatorAgentAsync()
     {
         Console.WriteLine($"! {Model}");
 

dotnet/samples/Concepts/Agents/MixedChat_Agents.cs

@@ -33,7 +33,7 @@ Consider suggestions when refining an idea.
         """;
 
     [Fact]
-    public async Task RunAsync()
+    public async Task ChatWithOpenAIAssistantAgentAndChatCompletionAgentAsync()
     {
         // Define the agents: one of each type
         ChatCompletionAgent agentReviewer =
@@ -55,7 +55,7 @@ await OpenAIAssistantAgent.CreateAsync(
                     ModelId = this.Model,
                 });
 
-        // Create a nexus for agent interaction.
+        // Create a chat for agent interaction.
         var chat =
             new AgentGroupChat(agentWriter, agentReviewer)
             {

dotnet/samples/Concepts/Agents/OpenAIAssistant_ChartMaker.cs

@@ -21,7 +21,7 @@ public class OpenAIAssistant_ChartMaker(ITestOutputHelper output) : BaseTest(out
     private const string AgentInstructions = "Create charts as requested without explanation.";
 
     [Fact]
-    public async Task RunAsync()
+    public async Task GenerateChartWithOpenAIAssistantAgentAsync()
     {
         // Define the agent
         OpenAIAssistantAgent agent =
@@ -77,7 +77,7 @@ async Task InvokeAgentAsync(string input)
 
                 foreach (var fileReference in message.Items.OfType<FileReferenceContent>())
                 {
-                    Console.WriteLine($"# {message.Role} - {message.AuthorName ?? "*"}: #{fileReference.FileId}");
+                    Console.WriteLine($"# {message.Role} - {message.AuthorName ?? "*"}: @{fileReference.FileId}");
                 }
             }
         }

dotnet/samples/Concepts/Agents/OpenAIAssistant_CodeInterpreter.cs

@@ -11,8 +11,10 @@ namespace Agents;
 /// </summary>
 public class OpenAIAssistant_CodeInterpreter(ITestOutputHelper output) : BaseTest(output)
 {
+    protected override bool ForceOpenAI => true;
+
     [Fact]
-    public async Task RunAsync()
+    public async Task UseCodeInterpreterToolWithOpenAIAssistantAgentAsync()
     {
         // Define the agent
         OpenAIAssistantAgent agent =
@@ -31,8 +33,7 @@ await OpenAIAssistantAgent.CreateAsync(
         // Respond to user input
         try
         {
-            await InvokeAgentAsync("What is the solution to `3x + 2 = 14`?");
-            await InvokeAgentAsync("What is the fibinacci sequence until 101?");
+            await InvokeAgentAsync("Use code to determine the values in the Fibonacci sequence that that are less then the value of 101?");
         }
         finally
         {