chore: import upstream snapshot with attribution

dotnet/samples/Concepts/TextGeneration/Custom_TextGenerationService.cs

@@ -0,0 +1,114 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Runtime.CompilerServices;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.TextGeneration;
+
+namespace TextGeneration;
+
+/**
+ * The following example shows how to plug a custom text generation service in SK.
+ *
+ * To do this, this example uses a text generation service stub (MyTextGenerationService) and
+ * no actual model.
+ *
+ * Using a custom text generation model within SK can be useful in a few scenarios, for example:
+ * - You are not using OpenAI or Azure OpenAI models
+ * - You are using OpenAI/Azure OpenAI models but the models are behind a web service with a different API schema
+ * - You want to use a local model
+ *
+ * Note that all OpenAI text generation models are deprecated and no longer available to new customers.
+ *
+ * Refer to example 33 for streaming chat completion.
+ */
+public class Custom_TextGenerationService(ITestOutputHelper output) : BaseTest(output)
+{
+    [Fact]
+    public async Task CustomTextGenerationWithKernelFunctionAsync()
+    {
+        Console.WriteLine("\n======== Custom LLM - Text Completion - KernelFunction ========");
+
+        IKernelBuilder builder = Kernel.CreateBuilder();
+        // Add your text generation service as a singleton instance
+        builder.Services.AddKeyedSingleton<ITextGenerationService>("myService1", new MyTextGenerationService());
+        // Add your text generation service as a factory method
+        builder.Services.AddKeyedSingleton<ITextGenerationService>("myService2", (_, _) => new MyTextGenerationService());
+        Kernel kernel = builder.Build();
+
+        const string FunctionDefinition = "Write one paragraph on {{$input}}";
+        var paragraphWritingFunction = kernel.CreateFunctionFromPrompt(FunctionDefinition);
+
+        const string Input = "Why AI is awesome";
+        Console.WriteLine($"Function input: {Input}\n");
+        var result = await paragraphWritingFunction.InvokeAsync(kernel, new() { ["input"] = Input });
+
+        Console.WriteLine(result);
+    }
+
+    [Fact]
+    public async Task CustomTextGenerationAsync()
+    {
+        Console.WriteLine("\n======== Custom LLM  - Text Completion - Raw ========");
+
+        const string Prompt = "Write one paragraph on why AI is awesome.";
+        var completionService = new MyTextGenerationService();
+
+        Console.WriteLine($"Prompt: {Prompt}\n");
+        var result = await completionService.GetTextContentAsync(Prompt);
+
+        Console.WriteLine(result);
+    }
+
+    [Fact]
+    public async Task CustomTextGenerationStreamAsync()
+    {
+        Console.WriteLine("\n======== Custom LLM  - Text Completion - Raw Streaming ========");
+
+        const string Prompt = "Write one paragraph on why AI is awesome.";
+        var completionService = new MyTextGenerationService();
+
+        Console.WriteLine($"Prompt: {Prompt}\n");
+        await foreach (var message in completionService.GetStreamingTextContentsAsync(Prompt))
+        {
+            Console.Write(message);
+        }
+
+        Console.WriteLine();
+    }
+
+    /// <summary>
+    /// Text generation service stub.
+    /// </summary>
+    private sealed class MyTextGenerationService : ITextGenerationService
+    {
+        private const string LLMResultText = @"...output from your custom model... Example:
+AI is awesome because it can help us solve complex problems, enhance our creativity,
+and improve our lives in many ways. AI can perform tasks that are too difficult,
+tedious, or dangerous for humans, such as diagnosing diseases, detecting fraud, or
+exploring space. AI can also augment our abilities and inspire us to create new forms
+of art, music, or literature. AI can also improve our well-being and happiness by
+providing personalized recommendations, entertainment, and assistance. AI is awesome.";
+
+        public IReadOnlyDictionary<string, object?> Attributes => new Dictionary<string, object?>();
+
+        public async IAsyncEnumerable<StreamingTextContent> GetStreamingTextContentsAsync(string prompt, PromptExecutionSettings? executionSettings = null, Kernel? kernel = null, [EnumeratorCancellation] CancellationToken cancellationToken = default)
+        {
+            foreach (string word in LLMResultText.Split(' ', StringSplitOptions.RemoveEmptyEntries))
+            {
+                await Task.Delay(50, cancellationToken);
+                cancellationToken.ThrowIfCancellationRequested();
+
+                yield return new StreamingTextContent($"{word} ");
+            }
+        }
+
+        public Task<IReadOnlyList<TextContent>> GetTextContentsAsync(string prompt, PromptExecutionSettings? executionSettings = null, Kernel? kernel = null, CancellationToken cancellationToken = default)
+        {
+            return Task.FromResult<IReadOnlyList<TextContent>>(
+            [
+                new(LLMResultText)
+            ]);
+        }
+    }
+}

dotnet/samples/Concepts/TextGeneration/HuggingFace_TextGeneration.cs

@@ -0,0 +1,106 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Connectors.HuggingFace;
+using xRetry;
+
+#pragma warning disable format // Format item can be simplified
+#pragma warning disable CA1861 // Avoid constant arrays as arguments
+
+namespace TextGeneration;
+
+// The following example shows how to use Semantic Kernel with HuggingFace API.
+public class HuggingFace_TextGeneration(ITestOutputHelper helper) : BaseTest(helper)
+{
+    private const string DefaultModel = "HuggingFaceH4/zephyr-7b-beta";
+
+    /// <summary>
+    /// This example uses HuggingFace Inference API to access hosted models.
+    /// More information here: <see href="https://huggingface.co/inference-api"/>
+    /// </summary>
+    [Fact]
+    public async Task RunInferenceApiExampleAsync()
+    {
+        Console.WriteLine("\n======== HuggingFace Inference API example ========\n");
+
+        Kernel kernel = Kernel.CreateBuilder()
+            .AddHuggingFaceTextGeneration(
+                model: TestConfiguration.HuggingFace.ModelId ?? DefaultModel,
+                apiKey: TestConfiguration.HuggingFace.ApiKey)
+            .Build();
+
+        var questionAnswerFunction = kernel.CreateFunctionFromPrompt("Question: {{$input}}; Answer:");
+
+        var result = await kernel.InvokeAsync(questionAnswerFunction, new() { ["input"] = "What is New York?" });
+
+        Console.WriteLine(result.GetValue<string>());
+    }
+
+    /// <summary>
+    /// Some Hugging Face models support streaming responses, configure using the HuggingFace ModelId setting.
+    /// </summary>
+    /// <remarks>
+    /// Tested with HuggingFaceH4/zephyr-7b-beta model.
+    /// </remarks>
+    [RetryFact(typeof(HttpOperationException))]
+    public async Task RunStreamingExampleAsync()
+    {
+        string model = TestConfiguration.HuggingFace.ModelId ?? DefaultModel;
+
+        Console.WriteLine($"\n======== HuggingFace {model} streaming example ========\n");
+
+        Kernel kernel = Kernel.CreateBuilder()
+            .AddHuggingFaceTextGeneration(
+                model: model,
+                apiKey: TestConfiguration.HuggingFace.ApiKey)
+            .Build();
+
+        var settings = new HuggingFacePromptExecutionSettings { UseCache = false };
+
+        var questionAnswerFunction = kernel.CreateFunctionFromPrompt("Question: {{$input}}; Answer:", new HuggingFacePromptExecutionSettings
+        {
+            UseCache = false
+        });
+
+        await foreach (string text in kernel.InvokePromptStreamingAsync<string>("Question: {{$input}}; Answer:", new(settings) { ["input"] = "What is New York?" }))
+        {
+            Console.Write(text);
+        }
+    }
+
+    /// <summary>
+    /// This example uses HuggingFace Llama 2 model and local HTTP server from Semantic Kernel repository.
+    /// How to setup local HTTP server: <see href="https://github.com/microsoft/semantic-kernel/blob/main/samples/apps/hugging-face-http-server/README.md"/>.
+    /// <remarks>
+    /// Additional access is required to download Llama 2 model and run it locally.
+    /// How to get access:
+    /// 1. Visit <see href="https://ai.meta.com/resources/models-and-libraries/llama-downloads/"/> and complete request access form.
+    /// 2. Visit <see href="https://huggingface.co/meta-llama/Llama-2-7b-hf"/> and complete form "Access Llama 2 on Hugging Face".
+    /// Note: Your Hugging Face account email address MUST match the email you provide on the Meta website, or your request will not be approved.
+    /// </remarks>
+    /// </summary>
+    [Fact(Skip = "Requires local model or Huggingface Pro subscription")]
+    public async Task RunLlamaExampleAsync()
+    {
+        Console.WriteLine("\n======== HuggingFace Llama 2 example ========\n");
+
+        // HuggingFace Llama 2 model: https://huggingface.co/meta-llama/Llama-2-7b-hf
+        const string Model = "meta-llama/Llama-2-7b-hf";
+
+        // HuggingFace local HTTP server endpoint
+        // const string Endpoint = "http://localhost:5000/completions";
+
+        Kernel kernel = Kernel.CreateBuilder()
+            .AddHuggingFaceTextGeneration(
+                model: Model,
+                //endpoint: Endpoint,
+                apiKey: TestConfiguration.HuggingFace.ApiKey)
+            .Build();
+
+        var questionAnswerFunction = kernel.CreateFunctionFromPrompt("Question: {{$input}}; Answer:");
+
+        var result = await kernel.InvokeAsync(questionAnswerFunction, new() { ["input"] = "What is New York?" });
+
+        Console.WriteLine(result.GetValue<string>());
+    }
+}

dotnet/samples/Concepts/TextGeneration/Ollama_TextGeneration.cs

@@ -0,0 +1,76 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.TextGeneration;
+using xRetry;
+
+#pragma warning disable format // Format item can be simplified
+#pragma warning disable CA1861 // Avoid constant arrays as arguments
+
+namespace TextGeneration;
+
+// The following example shows how to use Semantic Kernel with Ollama Text Generation API.
+public class Ollama_TextGeneration(ITestOutputHelper helper) : BaseTest(helper)
+{
+    [Fact]
+    public async Task KernelPromptAsync()
+    {
+        Assert.NotNull(TestConfiguration.Ollama.ModelId);
+
+        Console.WriteLine("\n======== Ollama Text Generation example ========\n");
+
+        Kernel kernel = Kernel.CreateBuilder()
+            .AddOllamaTextGeneration(
+                endpoint: new Uri(TestConfiguration.Ollama.Endpoint),
+                modelId: TestConfiguration.Ollama.ModelId)
+            .Build();
+
+        var questionAnswerFunction = kernel.CreateFunctionFromPrompt("Question: {{$input}}; Answer:");
+
+        var result = await kernel.InvokeAsync(questionAnswerFunction, new() { ["input"] = "What is New York?" });
+
+        Console.WriteLine(result.GetValue<string>());
+    }
+
+    [Fact]
+    public async Task ServicePromptAsync()
+    {
+        Assert.NotNull(TestConfiguration.Ollama.ModelId);
+
+        Console.WriteLine("\n======== Ollama Text Generation example ========\n");
+
+        Kernel kernel = Kernel.CreateBuilder()
+            .AddOllamaTextGeneration(
+                endpoint: new Uri(TestConfiguration.Ollama.Endpoint),
+                modelId: TestConfiguration.Ollama.ModelId)
+            .Build();
+
+        var service = kernel.GetRequiredService<ITextGenerationService>();
+        var result = await service.GetTextContentAsync("Question: What is New York?; Answer:");
+
+        Console.WriteLine(result);
+    }
+
+    [RetryFact(typeof(HttpOperationException))]
+    public async Task RunStreamingExampleAsync()
+    {
+        Assert.NotNull(TestConfiguration.Ollama.ModelId);
+
+        string model = TestConfiguration.Ollama.ModelId;
+
+        Console.WriteLine($"\n======== HuggingFace {model} streaming example ========\n");
+
+        Kernel kernel = Kernel.CreateBuilder()
+            .AddOllamaTextGeneration(
+                endpoint: new Uri(TestConfiguration.Ollama.Endpoint),
+                modelId: TestConfiguration.Ollama.ModelId)
+            .Build();
+
+        var questionAnswerFunction = kernel.CreateFunctionFromPrompt("Question: {{$input}}; Answer:");
+
+        await foreach (string text in kernel.InvokePromptStreamingAsync<string>("Question: {{$input}}; Answer:", new() { ["input"] = "What is New York?" }))
+        {
+            Console.Write(text);
+        }
+    }
+}

dotnet/samples/Concepts/TextGeneration/Ollama_TextGenerationStreaming.cs

@@ -0,0 +1,57 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.TextGeneration;
+
+#pragma warning disable format // Format item can be simplified
+#pragma warning disable CA1861 // Avoid constant arrays as arguments
+
+namespace TextGeneration;
+
+// The following example shows how to use Semantic Kernel with Ollama Text Generation API.
+public class Ollama_TextGenerationStreaming(ITestOutputHelper helper) : BaseTest(helper)
+{
+    [Fact]
+    public async Task RunKernelStreamingExampleAsync()
+    {
+        Assert.NotNull(TestConfiguration.Ollama.ModelId);
+
+        string model = TestConfiguration.Ollama.ModelId;
+
+        Console.WriteLine($"\n======== Ollama {model} streaming example ========\n");
+
+        Kernel kernel = Kernel.CreateBuilder()
+            .AddOllamaTextGeneration(
+                endpoint: new Uri(TestConfiguration.Ollama.Endpoint),
+                modelId: model)
+            .Build();
+
+        await foreach (string text in kernel.InvokePromptStreamingAsync<string>("Question: {{$input}}; Answer:", new() { ["input"] = "What is New York?" }))
+        {
+            Console.Write(text);
+        }
+    }
+
+    [Fact]
+    public async Task RunServiceStreamingExampleAsync()
+    {
+        Assert.NotNull(TestConfiguration.Ollama.ModelId);
+
+        string model = TestConfiguration.Ollama.ModelId;
+
+        Console.WriteLine($"\n======== Ollama {model} streaming example ========\n");
+
+        Kernel kernel = Kernel.CreateBuilder()
+            .AddOllamaTextGeneration(
+                endpoint: new Uri(TestConfiguration.Ollama.Endpoint),
+                modelId: model)
+            .Build();
+
+        var service = kernel.GetRequiredService<ITextGenerationService>();
+
+        await foreach (var content in service.GetStreamingTextContentsAsync("Question: What is New York?; Answer:"))
+        {
+            Console.Write(content);
+        }
+    }
+}

dotnet/samples/Concepts/TextGeneration/OpenAI_TextGenerationStreaming.cs

@@ -0,0 +1,66 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.SemanticKernel.Connectors.AzureOpenAI;
+using Microsoft.SemanticKernel.Connectors.OpenAI;
+using Microsoft.SemanticKernel.TextGeneration;
+
+namespace TextGeneration;
+
+/**
+ * The following example shows how to use Semantic Kernel with streaming text generation.
+ *
+ * This example will NOT work with regular chat completion models. It will only work with
+ * text completion models.
+ *
+ * Note that all text generation models are deprecated by OpenAI and will be removed in a future release.
+ *
+ * Refer to example 33 for streaming chat completion.
+ */
+public class OpenAI_TextGenerationStreaming(ITestOutputHelper output) : BaseTest(output)
+{
+    [Fact]
+    public Task AzureOpenAITextGenerationStreamAsync()
+    {
+        Console.WriteLine("======== Azure OpenAI - Text Generation - Raw Streaming ========");
+
+        var textGeneration = new AzureOpenAIChatCompletionService(
+            deploymentName: TestConfiguration.AzureOpenAI.ChatDeploymentName,
+            endpoint: TestConfiguration.AzureOpenAI.Endpoint,
+            apiKey: TestConfiguration.AzureOpenAI.ApiKey,
+            modelId: TestConfiguration.AzureOpenAI.ChatModelId);
+
+        return this.TextGenerationStreamAsync(textGeneration);
+    }
+
+    [Fact]
+    public Task OpenAITextGenerationStreamAsync()
+    {
+        Console.WriteLine("======== Open AI - Text Generation - Raw Streaming ========");
+
+        var textGeneration = new OpenAIChatCompletionService(TestConfiguration.OpenAI.ChatModelId, TestConfiguration.OpenAI.ApiKey);
+
+        return this.TextGenerationStreamAsync(textGeneration);
+    }
+
+    private async Task TextGenerationStreamAsync(ITextGenerationService textGeneration)
+    {
+        var executionSettings = new OpenAIPromptExecutionSettings()
+        {
+            MaxTokens = 100,
+            FrequencyPenalty = 0,
+            PresencePenalty = 0,
+            Temperature = 1,
+            TopP = 0.5
+        };
+
+        var prompt = "Write one paragraph why AI is awesome";
+
+        Console.WriteLine("Prompt: " + prompt);
+        await foreach (var content in textGeneration.GetStreamingTextContentsAsync(prompt, executionSettings))
+        {
+            Console.Write(content);
+        }
+
+        Console.WriteLine();
+    }
+}