chore: import upstream snapshot with attribution

dotnet/samples/Demos/FunctionInvocationApproval/FunctionInvocationApproval.csproj

@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <NoWarn>$(NoWarn);VSTHRD111,CA2007,CS8618,CS1591,SKEXP0001</NoWarn>
+    <UserSecretsId>5ee045b0-aea3-4f08-8d31-32d1a6f8fed0</UserSecretsId>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
+    <ProjectReference Include="..\..\..\src\Connectors\Connectors.AzureOpenAI\Connectors.AzureOpenAI.csproj" />
+    <ProjectReference Include="..\..\..\src\SemanticKernel.Core\SemanticKernel.Core.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/Demos/FunctionInvocationApproval/Options/AzureOpenAIOptions.cs

@@ -0,0 +1,31 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace FunctionInvocationApproval.Options;
+
+/// <summary>
+/// Configuration for Azure OpenAI chat completion service.
+/// </summary>
+public class AzureOpenAIOptions
+{
+    public const string SectionName = "AzureOpenAI";
+
+    /// <summary>
+    /// Azure OpenAI deployment name, see https://learn.microsoft.com/azure/cognitive-services/openai/how-to/create-resource
+    /// </summary>
+    public string ChatDeploymentName { get; set; }
+
+    /// <summary>
+    /// Azure OpenAI deployment URL, see https://learn.microsoft.com/azure/cognitive-services/openai/quickstart
+    /// </summary>
+    public string Endpoint { get; set; }
+
+    /// <summary>
+    /// Azure OpenAI API key, see https://learn.microsoft.com/azure/cognitive-services/openai/quickstart
+    /// </summary>
+    public string ApiKey { get; set; }
+
+    public bool IsValid =>
+        !string.IsNullOrWhiteSpace(this.ChatDeploymentName) &&
+        !string.IsNullOrWhiteSpace(this.Endpoint) &&
+        !string.IsNullOrWhiteSpace(this.ApiKey);
+}

dotnet/samples/Demos/FunctionInvocationApproval/Options/OpenAIOptions.cs

@@ -0,0 +1,25 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace FunctionInvocationApproval.Options;
+
+/// <summary>
+/// Configuration for OpenAI chat completion service.
+/// </summary>
+public class OpenAIOptions
+{
+    public const string SectionName = "OpenAI";
+
+    /// <summary>
+    /// OpenAI model ID, see https://platform.openai.com/docs/models.
+    /// </summary>
+    public string ChatModelId { get; set; }
+
+    /// <summary>
+    /// OpenAI API key, see https://platform.openai.com/account/api-keys
+    /// </summary>
+    public string ApiKey { get; set; }
+
+    public bool IsValid =>
+        !string.IsNullOrWhiteSpace(this.ChatModelId) &&
+        !string.IsNullOrWhiteSpace(this.ApiKey);
+}

dotnet/samples/Demos/FunctionInvocationApproval/Program.cs

@@ -0,0 +1,197 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using FunctionInvocationApproval.Options;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Connectors.OpenAI;
+
+namespace FunctionInvocationApproval;
+
+internal sealed class Program
+{
+    /// <summary>
+    /// This console application shows how to use function invocation filter to invoke function only if such operation was approved.
+    /// If function invocation was rejected, the result will contain an information about this, so LLM can react accordingly.
+    /// Application uses a plugin that allows to build a software by following main development stages:
+    /// Collection of requirements, design, implementation, testing and deployment.
+    /// Each step can be approved or rejected. Based on that, LLM will decide how to proceed.
+    /// </summary>
+    public static async Task Main()
+    {
+        var builder = Kernel.CreateBuilder();
+
+        // Add LLM configuration
+        AddChatCompletion(builder);
+
+        // Add function approval service and filter
+        builder.Services.AddSingleton<IFunctionApprovalService, ConsoleFunctionApprovalService>();
+        builder.Services.AddSingleton<IFunctionInvocationFilter, FunctionInvocationFilter>();
+
+        // Add software builder plugin
+        builder.Plugins.AddFromType<SoftwareBuilderPlugin>();
+
+        var kernel = builder.Build();
+
+        // Enable automatic function calling
+        var executionSettings = new OpenAIPromptExecutionSettings
+        {
+            Temperature = 0,
+            FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
+        };
+
+        // Initialize kernel arguments.
+        var arguments = new KernelArguments(executionSettings);
+
+        // Start execution
+        // Try to reject invocation at each stage to compare LLM results.
+        var result = await kernel.InvokePromptAsync("I want to build a software. Let's start from the first step.", arguments);
+
+        Console.WriteLine(result);
+    }
+
+    #region Plugins
+
+    public sealed class SoftwareBuilderPlugin
+    {
+        [KernelFunction]
+        public string CollectRequirements()
+        {
+            Console.WriteLine("Collecting requirements...");
+            return "Requirements";
+        }
+
+        [KernelFunction]
+        public string Design(string requirements)
+        {
+            Console.WriteLine($"Designing based on: {requirements}");
+            return "Design";
+        }
+
+        [KernelFunction]
+        public string Implement(string requirements, string design)
+        {
+            Console.WriteLine($"Implementing based on {requirements} and {design}");
+            return "Implementation";
+        }
+
+        [KernelFunction]
+        public string Test(string requirements, string design, string implementation)
+        {
+            Console.WriteLine($"Testing based on {requirements}, {design} and {implementation}");
+            return "Test Results";
+        }
+
+        [KernelFunction]
+        public string Deploy(string requirements, string design, string implementation, string testResults)
+        {
+            Console.WriteLine($"Deploying based on {requirements}, {design}, {implementation} and {testResults}");
+            return "Deployment";
+        }
+    }
+
+    #endregion
+
+    #region Approval
+
+    /// <summary>
+    /// Service that verifies if function invocation is approved.
+    /// </summary>
+    public interface IFunctionApprovalService
+    {
+        bool IsInvocationApproved(KernelFunction function, KernelArguments arguments);
+    }
+
+    /// <summary>
+    /// Service that verifies if function invocation is approved using console.
+    /// </summary>
+    public sealed class ConsoleFunctionApprovalService : IFunctionApprovalService
+    {
+        public bool IsInvocationApproved(KernelFunction function, KernelArguments arguments)
+        {
+            Console.WriteLine("====================");
+            Console.WriteLine($"Function name: {function.Name}");
+            Console.WriteLine($"Plugin name: {function.PluginName ?? "N/A"}");
+
+            if (arguments.Count == 0)
+            {
+                Console.WriteLine("\nArguments: N/A");
+            }
+            else
+            {
+                Console.WriteLine("\nArguments:");
+
+                foreach (var argument in arguments)
+                {
+                    Console.WriteLine($"{argument.Key}: {argument.Value}");
+                }
+            }
+
+            Console.WriteLine("\nApprove invocation? (yes/no)");
+
+            var input = Console.ReadLine();
+
+            return input?.Equals("yes", StringComparison.OrdinalIgnoreCase) ?? false;
+        }
+    }
+
+    #endregion
+
+    #region Filter
+
+    /// <summary>
+    /// Filter to invoke function only if it's approved.
+    /// </summary>
+    public sealed class FunctionInvocationFilter(IFunctionApprovalService approvalService) : IFunctionInvocationFilter
+    {
+        private readonly IFunctionApprovalService _approvalService = approvalService;
+
+        public async Task OnFunctionInvocationAsync(FunctionInvocationContext context, Func<FunctionInvocationContext, Task> next)
+        {
+            // Invoke the function only if it's approved.
+            if (this._approvalService.IsInvocationApproved(context.Function, context.Arguments))
+            {
+                await next(context);
+            }
+            else
+            {
+                // Otherwise, return a result that operation was rejected.
+                context.Result = new FunctionResult(context.Result, "Operation was rejected.");
+            }
+        }
+    }
+
+    #endregion
+
+    #region Configuration
+
+    private static void AddChatCompletion(IKernelBuilder builder)
+    {
+        // Get configuration
+        var config = new ConfigurationBuilder()
+            .AddUserSecrets<Program>()
+            .AddEnvironmentVariables()
+            .Build();
+
+        var openAIOptions = config.GetSection(OpenAIOptions.SectionName).Get<OpenAIOptions>();
+        var azureOpenAIOptions = config.GetSection(AzureOpenAIOptions.SectionName).Get<AzureOpenAIOptions>();
+
+        if (openAIOptions is not null && openAIOptions.IsValid)
+        {
+            builder.AddOpenAIChatCompletion(openAIOptions.ChatModelId, openAIOptions.ApiKey);
+        }
+        else if (azureOpenAIOptions is not null && azureOpenAIOptions.IsValid)
+        {
+            builder.AddAzureOpenAIChatCompletion(
+                azureOpenAIOptions.ChatDeploymentName,
+                azureOpenAIOptions.Endpoint,
+                azureOpenAIOptions.ApiKey);
+        }
+        else
+        {
+            throw new Exception("OpenAI/Azure OpenAI configuration was not found.");
+        }
+    }
+
+    #endregion
+}

dotnet/samples/Demos/FunctionInvocationApproval/README.md

@@ -0,0 +1,44 @@
+# Function Invocation Approval
+
+This console application shows how to use function invocation filter (`IFunctionInvocationFilter`) to invoke a Kernel Function only if such operation was approved.
+If function invocation was rejected, the result will contain the reason why, so the LLM can respond appropriately.
+
+The application uses a sample plugin which builds software by following these development stages: collection of requirements, design, implementation, testing and deployment.
+
+Each step can be approved or rejected. Based on that, the LLM will decide how to proceed.
+
+## Configuring Secrets
+
+The example requires credentials to access OpenAI or Azure OpenAI.
+
+If you have set up those credentials as secrets within Secret Manager or through environment variables for other samples from the solution in which this project is found, they will be re-used.
+
+### To set your secrets with Secret Manager:
+
+```
+cd dotnet/samples/Demos/FunctionInvocationApproval
+
+dotnet user-secrets init
+
+dotnet user-secrets set "OpenAI:ChatModelId" "..."
+dotnet user-secrets set "OpenAI:ApiKey" "..."
+
+dotnet user-secrets set "AzureOpenAI:ChatDeploymentName" "..."
+dotnet user-secrets set "AzureOpenAI:Endpoint" "https://... .openai.azure.com/"
+dotnet user-secrets set "AzureOpenAI:ApiKey" "..."
+```
+
+### To set your secrets with environment variables
+
+Use these names:
+
+```
+# OpenAI
+OpenAI__ChatModelId
+OpenAI__ApiKey
+
+# Azure OpenAI
+AzureOpenAI__ChatDeploymentName
+AzureOpenAI__Endpoint
+AzureOpenAI__ApiKey
+```