Merge remote-tracking branch 'upstream/main' into feature/postgres-memory

Author: lossyrob

docs/decisions/0054-processes.md

@@ -76,8 +76,8 @@
     <!-- Plugins -->
     <PackageVersion Include="DocumentFormat.OpenXml" Version="3.1.0" />
     <PackageVersion Include="Microsoft.Data.Sqlite" Version="8.0.8" />
-    <PackageVersion Include="DuckDB.NET.Data.Full" Version="1.0.2" />
-    <PackageVersion Include="DuckDB.NET.Data" Version="1.0.1" />
+    <PackageVersion Include="DuckDB.NET.Data.Full" Version="1.1.1" />
+    <PackageVersion Include="DuckDB.NET.Data" Version="1.1.1" />
     <PackageVersion Include="MongoDB.Driver" Version="2.28.0" />
     <PackageVersion Include="Microsoft.Graph" Version="[4.51.0, 5)" />
     <PackageVersion Include="Microsoft.Identity.Client.Extensions.Msal" Version="[2.28.0, )" />

docs/decisions/diagrams/process/process_diagram_basic.png

@@ -38,17 +38,17 @@ public async Task UseSimpleProcessAsync()
 
         // Define the behavior when the process receives an external event
         process
-            .OnExternalEvent(ChatBotEvents.StartProcess)
+            .OnInputEvent(ChatBotEvents.StartProcess)
             .SendEventTo(new ProcessFunctionTargetBuilder(introStep));
 
         // When the intro is complete, notify the userInput step
         introStep
             .OnFunctionResult(nameof(IntroStep.PrintIntroMessage))
             .SendEventTo(new ProcessFunctionTargetBuilder(userInputStep));
 
-        // When the userInput step emits an exit event, send it to the end steprt
+        // When the userInput step emits an exit event, send it to the end step
         userInputStep
-            .OnFunctionResult("GetUserInput")
+            .OnEvent(ChatBotEvents.Exit)
             .StopProcess();
 
         // When the userInput step emits a user input event, send it to the assistantResponse step

dotnet/Directory.Packages.props

@@ -30,7 +30,7 @@ private KernelProcess SetupAccountOpeningProcess<TUserInputStep>() where TUserIn
         var crmRecordStep = process.AddStepFromType<CRMRecordCreationStep>();
         var welcomePacketStep = process.AddStepFromType<WelcomePacketStep>();
 
-        process.OnExternalEvent(AccountOpeningEvents.StartProcess)
+        process.OnInputEvent(AccountOpeningEvents.StartProcess)
             .SendEventTo(new ProcessFunctionTargetBuilder(newCustomerFormStep, CompleteNewCustomerFormStep.Functions.NewAccountWelcome));
 
         // When the welcome message is generated, send message to displayAssistantMessageStep

dotnet/samples/GettingStartedWithProcesses/Step01/Step01_Processes.cs

@@ -1,4 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.
+using System.Collections.Generic;
+using System.Linq;
 using System.Threading;
 using System.Threading.Tasks;
 
@@ -62,4 +64,48 @@ public abstract class KernelAgent : Agent
 
         return await this.Template.RenderAsync(kernel, arguments, cancellationToken).ConfigureAwait(false);
     }
+
+    /// <summary>
+    /// Provide a merged instance of <see cref="KernelArguments"/> with precedence for override arguments.
+    /// </summary>
+    /// <param name="arguments">The override arguments</param>
+    /// <remarks>
+    /// This merge preserves original <see cref="PromptExecutionSettings"/> and <see cref="KernelArguments"/> parameters.
+    /// and allows for incremental addition or replacement of specific parameters while also preserving the ability
+    /// to override the execution settings.
+    /// </remarks>
+    protected KernelArguments? MergeArguments(KernelArguments? arguments)
+    {
+        // Avoid merge when default arguments are not set.
+        if (this.Arguments == null)
+        {
+            return arguments;
+        }
+
+        // Avoid merge when override arguments are not set.
+        if (arguments == null)
+        {
+            return this.Arguments;
+        }
+
+        // Both instances are not null, merge with precedence for override arguments.
+
+        // Merge execution settings with precedence for override arguments.
+        Dictionary<string, PromptExecutionSettings>? settings =
+            (arguments.ExecutionSettings ?? s_emptySettings)
+                .Concat(this.Arguments.ExecutionSettings ?? s_emptySettings)
+                .GroupBy(entry => entry.Key)
+                .ToDictionary(entry => entry.Key, entry => entry.First().Value);
+
+        // Merge parameters with precedence for override arguments.
+        Dictionary<string, object?>? parameters =
+            arguments
+                .Concat(this.Arguments)
+                .GroupBy(entry => entry.Key)
+                .ToDictionary(entry => entry.Key, entry => entry.First().Value);
+
+        return new KernelArguments(parameters, settings);
+    }
+
+    private static readonly Dictionary<string, PromptExecutionSettings> s_emptySettings = [];
 }

dotnet/samples/GettingStartedWithProcesses/Step02/Step02_AccountOpening.cs

@@ -50,7 +50,7 @@ public override async IAsyncEnumerable<ChatMessageContent> InvokeAsync(
         [EnumeratorCancellation] CancellationToken cancellationToken = default)
     {
         kernel ??= this.Kernel;
-        arguments ??= this.Arguments;
+        arguments = this.MergeArguments(arguments);
 
         (IChatCompletionService chatCompletionService, PromptExecutionSettings? executionSettings) = GetChatCompletionService(kernel, arguments);
 
@@ -95,7 +95,7 @@ public override async IAsyncEnumerable<StreamingChatMessageContent> InvokeStream
         [EnumeratorCancellation] CancellationToken cancellationToken = default)
     {
         kernel ??= this.Kernel;
-        arguments ??= this.Arguments;
+        arguments = this.MergeArguments(arguments);
 
         (IChatCompletionService chatCompletionService, PromptExecutionSettings? executionSettings) = GetChatCompletionService(kernel, arguments);
 

dotnet/src/Agents/Abstractions/KernelAgent.cs

@@ -26,18 +26,20 @@ internal static class AssistantToolResourcesFactory
 
         if (hasVectorStore || hasCodeInterpreterFiles)
         {
-            var fileSearch = hasVectorStore
-                ? new FileSearchToolResources
-                {
-                    VectorStoreIds = { vectorStoreId! }
-                }
-                : null;
-
-            var codeInterpreter = hasCodeInterpreterFiles
-                ? new CodeInterpreterToolResources()
-                : null;
+            FileSearchToolResources? fileSearch =
+                hasVectorStore ?
+                    new()
+                    {
+                        VectorStoreIds = { vectorStoreId! }
+                    } :
+                    null;
 
+            CodeInterpreterToolResources? codeInterpreter =
+                hasCodeInterpreterFiles ?
+                    new() :
+                    null;
             codeInterpreter?.FileIds.AddRange(codeInterpreterFileIds!);
+
             toolResources = new ToolResources
             {
                 FileSearch = fileSearch,

dotnet/src/Agents/Core/ChatCompletionAgent.cs

@@ -341,7 +341,7 @@ public async IAsyncEnumerable<ChatMessageContent> InvokeAsync(
         this.ThrowIfDeleted();
 
         kernel ??= this.Kernel;
-        arguments ??= this.Arguments;
+        arguments = this.MergeArguments(arguments);
 
         await foreach ((bool isVisible, ChatMessageContent message) in AssistantThreadActions.InvokeAsync(this, this._client, threadId, options, this.Logger, kernel, arguments, cancellationToken).ConfigureAwait(false))
         {
@@ -396,7 +396,7 @@ public IAsyncEnumerable<StreamingChatMessageContent> InvokeStreamingAsync(
         this.ThrowIfDeleted();
 
         kernel ??= this.Kernel;
-        arguments ??= this.Arguments;
+        arguments = this.MergeArguments(arguments);
 
         return AssistantThreadActions.InvokeStreamingAsync(this, this._client, threadId, messages, options, this.Logger, kernel, arguments, cancellationToken);
     }

dotnet/src/Agents/OpenAI/Internal/AssistantToolResourcesFactory.cs

@@ -0,0 +1,111 @@
+// Copyright (c) Microsoft. All rights reserved.
+using System.Linq;
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Agents;
+using Xunit;
+
+namespace SemanticKernel.Agents.UnitTests;
+
+/// <summary>
+/// Verify behavior of <see cref="KernelAgent"/> base class.
+/// </summary>
+public class KernelAgentTests
+{
+    /// <summary>
+    /// Verify ability to merge null <see cref="KernelArguments"/>.
+    /// </summary>
+    [Fact]
+    public void VerifyNullArgumentMerge()
+    {
+        // Arrange
+        MockAgent agentWithNullArguments = new();
+        // Act
+        KernelArguments? arguments = agentWithNullArguments.MergeArguments(null);
+        // Assert
+        Assert.Null(arguments);
+
+        // Arrange
+        KernelArguments overrideArguments = [];
+        // Act
+        arguments = agentWithNullArguments.MergeArguments(overrideArguments);
+        // Assert
+        Assert.NotNull(arguments);
+        Assert.StrictEqual(overrideArguments, arguments);
+
+        // Arrange
+        MockAgent agentWithEmptyArguments = new() { Arguments = new() };
+        // Act
+        arguments = agentWithEmptyArguments.MergeArguments(null);
+        // Assert
+        Assert.NotNull(arguments);
+        Assert.StrictEqual(agentWithEmptyArguments.Arguments, arguments);
+    }
+
+    /// <summary>
+    /// Verify ability to merge <see cref="KernelArguments"/> parameters.
+    /// </summary>
+    [Fact]
+    public void VerifyArgumentParameterMerge()
+    {
+        // Arrange
+        MockAgent agentWithArguments = new() { Arguments = new() { { "a", 1 } } };
+        KernelArguments overrideArguments = new() { { "b", 2 } };
+
+        // Act
+        KernelArguments? arguments = agentWithArguments.MergeArguments(overrideArguments);
+
+        // Assert
+        Assert.NotNull(arguments);
+        Assert.Equal(2, arguments.Count);
+        Assert.Equal(1, arguments["a"]);
+        Assert.Equal(2, arguments["b"]);
+
+        // Arrange
+        overrideArguments["a"] = 11;
+        overrideArguments["c"] = 3;
+
+        // Act
+        arguments = agentWithArguments.MergeArguments(overrideArguments);
+
+        // Assert
+        Assert.NotNull(arguments);
+        Assert.Equal(3, arguments.Count);
+        Assert.Equal(11, arguments["a"]);
+        Assert.Equal(2, arguments["b"]);
+        Assert.Equal(3, arguments["c"]);
+    }
+
+    /// <summary>
+    /// Verify ability to merge <see cref="KernelArguments.ExecutionSettings"/>.
+    /// </summary>
+    [Fact]
+    public void VerifyArgumentSettingsMerge()
+    {
+        // Arrange
+        FunctionChoiceBehavior autoInvoke = FunctionChoiceBehavior.Auto();
+        MockAgent agentWithSettings = new() { Arguments = new(new PromptExecutionSettings() { FunctionChoiceBehavior = autoInvoke }) };
+        KernelArguments overrideArgumentsNoSettings = new();
+
+        // Act
+        KernelArguments? arguments = agentWithSettings.MergeArguments(overrideArgumentsNoSettings);
+
+        // Assert
+        Assert.NotNull(arguments);
+        Assert.NotNull(arguments.ExecutionSettings);
+        Assert.Single(arguments.ExecutionSettings);
+        Assert.StrictEqual(autoInvoke, arguments.ExecutionSettings.First().Value.FunctionChoiceBehavior);
+
+        // Arrange
+        FunctionChoiceBehavior noInvoke = FunctionChoiceBehavior.None();
+        KernelArguments overrideArgumentsWithSettings = new(new PromptExecutionSettings() { FunctionChoiceBehavior = noInvoke });
+
+        // Act
+        arguments = agentWithSettings.MergeArguments(overrideArgumentsWithSettings);
+
+        // Assert
+        Assert.NotNull(arguments);
+        Assert.NotNull(arguments.ExecutionSettings);
+        Assert.Single(arguments.ExecutionSettings);
+        Assert.StrictEqual(noInvoke, arguments.ExecutionSettings.First().Value.FunctionChoiceBehavior);
+    }
+}