chore: import upstream snapshot with attribution

dotnet/samples/Concepts/Kernel/BuildingKernel.cs

@@ -0,0 +1,36 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// ==========================================================================================================
+// The easier way to instantiate the Semantic Kernel is to use KernelBuilder.
+// You can access the builder using Kernel.CreateBuilder().
+
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Plugins.Core;
+
+namespace KernelExamples;
+
+public class BuildingKernel(ITestOutputHelper output) : BaseTest(output)
+{
+    [Fact]
+    public void BuildKernelWithAzureChatCompletion()
+    {
+        // KernelBuilder provides a simple way to configure a Kernel. This constructs a kernel
+        // with logging and an Azure OpenAI chat completion service configured.
+        Kernel kernel1 = Kernel.CreateBuilder()
+            .AddAzureOpenAIChatCompletion(
+                deploymentName: TestConfiguration.AzureOpenAI.ChatDeploymentName,
+                endpoint: TestConfiguration.AzureOpenAI.Endpoint,
+                apiKey: TestConfiguration.AzureOpenAI.ApiKey,
+                modelId: TestConfiguration.AzureOpenAI.ChatModelId)
+            .Build();
+    }
+
+    [Fact]
+    public void BuildKernelWithPlugins()
+    {
+        // Plugins may also be configured via the corresponding Plugins property.
+        var builder = Kernel.CreateBuilder();
+        builder.Plugins.AddFromType<HttpPlugin>();
+        Kernel kernel3 = builder.Build();
+    }
+}

dotnet/samples/Concepts/Kernel/ConfigureExecutionSettings.cs

@@ -0,0 +1,100 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Connectors.OpenAI;
+
+namespace KernelExamples;
+
+public sealed class ConfigureExecutionSettings(ITestOutputHelper output) : BaseTest(output)
+{
+    /// <summary>
+    /// Show how to configure model execution settings
+    /// </summary>
+    [Fact]
+    public async Task RunAsync()
+    {
+        Console.WriteLine("======== ConfigureExecutionSettings ========");
+
+        string serviceId = TestConfiguration.AzureOpenAI.ServiceId;
+        string apiKey = TestConfiguration.AzureOpenAI.ApiKey;
+        string chatDeploymentName = TestConfiguration.AzureOpenAI.ChatDeploymentName;
+        string chatModelId = TestConfiguration.AzureOpenAI.ChatModelId;
+        string endpoint = TestConfiguration.AzureOpenAI.Endpoint;
+
+        if (apiKey is null || chatDeploymentName is null || endpoint is null)
+        {
+            Console.WriteLine("AzureOpenAI endpoint, apiKey, or deploymentName not found. Skipping example.");
+            return;
+        }
+
+        Kernel kernel = Kernel.CreateBuilder()
+            .AddAzureOpenAIChatCompletion(
+                deploymentName: chatDeploymentName,
+                endpoint: endpoint,
+                serviceId: serviceId,
+                apiKey: apiKey,
+                modelId: chatModelId)
+            .Build();
+
+        var prompt = "Hello AI, what can you do for me?";
+
+        // Option 1:
+        // Invoke the prompt function and pass an OpenAI specific instance containing the execution settings
+        var result = await kernel.InvokePromptAsync(
+            prompt,
+            new(new OpenAIPromptExecutionSettings()
+            {
+                MaxTokens = 60,
+                Temperature = 0.7
+            }));
+        Console.WriteLine(result.GetValue<string>());
+
+        // Option 2:
+        // Load prompt template configuration including the execution settings from a JSON payload
+        // Create the prompt functions using the prompt template and the configuration (loaded in the previous step)
+        // Invoke the prompt function using the implicitly set execution settings
+        string configPayload = """
+            {
+                "schema": 1,
+                "name": "HelloAI",
+                "description": "Say hello to an AI",
+                "type": "completion",
+                "completion": {
+                "max_tokens": 256,
+                "temperature": 0.5,
+                "top_p": 0.0,
+                "presence_penalty": 0.0,
+                "frequency_penalty": 0.0
+                }
+            }
+            """;
+        var promptConfig = JsonSerializer.Deserialize<PromptTemplateConfig>(configPayload)!;
+        promptConfig.Template = prompt;
+        var func = kernel.CreateFunctionFromPrompt(promptConfig);
+
+        result = await kernel.InvokeAsync(func);
+        Console.WriteLine(result.GetValue<string>());
+
+        /* OUTPUT (using gpt4):
+Hello! As an AI language model, I can help you with a variety of tasks, such as:
+
+1. Answering general questions and providing information on a wide range of topics.
+2. Assisting with problem-solving and brainstorming ideas.
+3. Offering recommendations for books, movies, music, and more.
+4. Providing definitions, explanations, and examples of various concepts.
+5. Helping with language-related tasks, such as grammar, vocabulary, and writing tips.
+6. Generating creative content, such as stories, poems, or jokes.
+7. Assisting with basic math and science problems.
+8. Offering advice on various topics, such as productivity, motivation, and personal development.
+
+Please feel free to ask me anything, and I'll do my best to help you!
+Hello! As an AI language model, I can help you with a variety of tasks, including:
+
+1. Answering general questions and providing information on a wide range of topics.
+2. Offering suggestions and recommendations.
+3. Assisting with problem-solving and brainstorming ideas.
+4. Providing explanations and
+         */
+    }
+}

dotnet/samples/Concepts/Kernel/CustomAIServiceSelector.cs

@@ -0,0 +1,118 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Connectors.OpenAI;
+using Microsoft.SemanticKernel.Services;
+
+namespace KernelExamples;
+
+/// <summary>
+/// This sample shows how to use a custom AI service selector to select a specific model by matching the model id.
+/// </summary>
+public class CustomAIServiceSelector(ITestOutputHelper output) : BaseTest(output)
+{
+    [Fact]
+    public async Task UsingCustomSelectToSelectServiceByMatchingModelId()
+    {
+        Console.WriteLine($"======== {nameof(UsingCustomSelectToSelectServiceByMatchingModelId)} ========");
+
+        // Use the custom AI service selector to select any registered service starting with "gpt" on it's model id
+        var customSelector = new GptAIServiceSelector(modelNameStartsWith: "gpt", this.Output);
+
+        // Build a kernel with multiple chat services
+        var builder = Kernel.CreateBuilder()
+            .AddAzureOpenAIChatCompletion(
+                deploymentName: TestConfiguration.AzureOpenAI.ChatDeploymentName,
+                endpoint: TestConfiguration.AzureOpenAI.Endpoint,
+                apiKey: TestConfiguration.AzureOpenAI.ApiKey,
+                serviceId: "AzureOpenAIChat",
+                modelId: "o1-mini")
+            .AddOpenAIChatCompletion(
+                modelId: "o1-mini",
+                apiKey: TestConfiguration.OpenAI.ApiKey,
+                serviceId: "OpenAIChat");
+
+        // The kernel also allows you to use a IChatClient chat service as well
+        builder.Services
+            .AddSingleton<IAIServiceSelector>(customSelector)
+            .AddKeyedChatClient("OpenAIChatClient", new OpenAI.OpenAIClient(TestConfiguration.OpenAI.ApiKey)
+                .GetChatClient("gpt-4o")
+                .AsIChatClient()); // Add a IChatClient to the kernel
+
+        Kernel kernel = builder.Build();
+
+        // This invocation is done with the model selected by the custom selector
+        var prompt = "Hello AI, what can you do for me?";
+        var result = await kernel.InvokePromptAsync(prompt);
+        Console.WriteLine(result.GetValue<string>());
+    }
+
+    /// <summary>
+    /// Custom AI service selector that selects a GPT model.
+    /// This selector just naively selects the first service that provides
+    /// a completion model whose name starts with "gpt". But this logic could
+    /// be as elaborate as needed to apply your own selection criteria.
+    /// </summary>
+    private sealed class GptAIServiceSelector(string modelNameStartsWith, ITestOutputHelper output) : IAIServiceSelector, IChatClientSelector
+    {
+        private readonly ITestOutputHelper _output = output;
+        private readonly string _modelNameStartsWith = modelNameStartsWith;
+
+        private bool TrySelect<T>(
+            Kernel kernel, KernelFunction function, KernelArguments arguments,
+            [NotNullWhen(true)] out T? service, out PromptExecutionSettings? serviceSettings) where T : class
+        {
+            foreach (var serviceToCheck in kernel.GetAllServices<T>())
+            {
+                string? serviceModelId = null;
+                string? endpoint = null;
+
+                if (serviceToCheck is IAIService aiService)
+                {
+                    serviceModelId = aiService.GetModelId();
+                    endpoint = aiService.GetEndpoint();
+                }
+                else if (serviceToCheck is IChatClient chatClient)
+                {
+                    var metadata = chatClient.GetService<ChatClientMetadata>();
+                    serviceModelId = metadata?.DefaultModelId;
+                    endpoint = metadata?.ProviderUri?.ToString();
+                }
+
+                // Find the first service that has a model id that starts with "gpt"
+                if (!string.IsNullOrEmpty(serviceModelId) && serviceModelId.StartsWith(this._modelNameStartsWith, StringComparison.OrdinalIgnoreCase))
+                {
+                    this._output.WriteLine($"Selected model: {serviceModelId} {endpoint}");
+                    service = serviceToCheck;
+                    serviceSettings = new OpenAIPromptExecutionSettings();
+                    return true;
+                }
+            }
+
+            service = null;
+            serviceSettings = null;
+            return false;
+        }
+
+        /// <inheritdoc/>
+        public bool TrySelectAIService<T>(
+            Kernel kernel,
+            KernelFunction function,
+            KernelArguments arguments,
+            [NotNullWhen(true)] out T? service,
+            out PromptExecutionSettings? serviceSettings) where T : class, IAIService
+            => this.TrySelect(kernel, function, arguments, out service, out serviceSettings);
+
+        /// <inheritdoc/>
+        public bool TrySelectChatClient<T>(
+            Kernel kernel,
+            KernelFunction function,
+            KernelArguments arguments,
+            [NotNullWhen(true)] out T? service,
+            out PromptExecutionSettings? serviceSettings) where T : class, IChatClient
+            => this.TrySelect(kernel, function, arguments, out service, out serviceSettings);
+    }
+}