Merge pull request #111 from AClerbois/patch-1

Add documentation to use prompty with Microsoft Semantic Kernel

web/docs/tutorials/using-semantic-kernel/page.mdx

@@ -3,14 +3,233 @@ title: Using Semantic Kernel
 authors:
   - bethanyjep
   - nitya
-date: 2024-06-10
+  - aclerbois
+date: 2024-10-23
 tags:
   - tutorials
   - semantic-kernel
 index: 3
 ---
+---
+
+# Using Prompty with Microsoft Semantic Kernel
+
+This guide explains how to use Prompty templates within the Microsoft Semantic Kernel. The `Microsoft.SemanticKernel.Prompty` package (currently in alpha) allows for flexible use of Prompty files to define chat prompts and functions for AI-powered applications.
+
+## Prerequisites
+
+1. **Install the NuGet package**:
+   You need to install the `Microsoft.SemanticKernel.Prompty` package. It can be found on NuGet at the following link:
+
+   [Microsoft.SemanticKernel.Prompty (Alpha)](https://www.nuget.org/packages/Microsoft.SemanticKernel.Prompty/1.24.1-alpha)
+
+   ```
+   dotnet add package Microsoft.SemanticKernel.Prompty --version 1.24.1-alpha
+   ```
+
+2. **Setup your Semantic Kernel**:
+   Make sure you have the Semantic Kernel ready in your project by adding the necessary dependencies and configuring the kernel.
+
+---
+
+## Basic Example: Inline Function
+
+Here’s an example of how to create and use a Prompty file with an inline function within the Semantic Kernel.
+
+### Code Example
+
+```csharp
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Prompty;
+using Microsoft.Extensions.FileProviders;
+
+public class PromptyExample
+{ 
+    public async Task RunPromptyInlineFunction()
+    {
+        Kernel kernel = Kernel.CreateBuilder()
+            .AddOpenAIChatCompletion(
+                modelId: "<ChatModelId>",
+                apiKey: "<OpenApiKeyApiKey>")
+            .Build();
+
+        string promptTemplate = """
+            ---
+            name: Contoso_Chat_Prompt
+            description: A sample prompt that responds with what Seattle is.
+            authors:
+              - ????
+            model:
+              api: chat
+            ---
+            system:
+            You are a helpful assistant who knows all about cities in the USA
+        
+            user:
+            What is Seattle?
+            """;
+
+        var function = kernel.CreateFunctionFromPrompty(promptTemplate);
+
+        var result = await kernel.InvokeAsync(function);
+        Console.WriteLine(result);
+    }
+}
+```
+
+### Explanation:
+- A prompt template is created using Prompty syntax, including metadata such as `name`, `description`, and `model`.
+- The system message establishes the behavior of the assistant.
+- The `CreateFunctionFromPrompty` method is used to create a Semantic Kernel function from the Prompty template.
+- The function is invoked with `InvokeAsync`, and the result is printed.
+
+---
+
+
+## Basic Example: Using a file
+
+This method allows you to load a Prompty template directly from a file.
+
+### Code Example 
+
+```csharp
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Prompty;
+using Microsoft.Extensions.FileProviders;
+
+public class PromptyExample
+{
+    public async Task RunPromptyFromFileAsync()
+    {
+        // Initialize the Kernel
+        Kernel kernel = Kernel.CreateBuilder()
+            .AddOpenAIChatCompletion(
+                modelId: "<ChatModelId>",
+                apiKey: "<OpenApiKeyApiKey>")
+            .Build();
+
+        // Path to your Prompty template file
+        string promptyFilePath = "path/to/your/prompty-template.yaml";
+
+        // Optionally, you can provide a custom IPromptTemplateFactory
+        IPromptTemplateFactory? promptTemplateFactory = null;
+
+        // Use the default physical file provider (current directory scope)
+        IFileProvider fileProvider = new PhysicalFileProvider(Directory.GetCurrentDirectory());
+
+        // Create the function from the Prompty file
+        var function = kernel.CreateFunctionFromPromptyFile(promptyFilePath, fileProvider, promptTemplateFactory);
+
+        // Invoke the function asynchronously
+        var result = await kernel.InvokeAsync(function);
+
+        // Output the result
+        Console.WriteLine(result);
+    }
+}
+```
+
+### Explanation:
+
+1. **File Location**: 
+   - Replace `"path/to/your/prompty-template.yaml"` with the actual path to your Prompty file.
+
+2. **Physical File Provider**: 
+   - In this example, a `PhysicalFileProvider` is used to load files from the current working directory, but you can customize this to fit your file system requirements.
+
+3. **Custom Prompt Template Factory**: 
+   - Optionally, you can provide a custom `IPromptTemplateFactory` to parse the prompt templates using different engines like Liquid or Handlebars.
+
+4. **Invocation**: 
+   - The function is created and invoked just like in the previous examples, but this time the template is loaded from a file.
+
+This demonstrates how to handle external Prompty files in your Semantic Kernel setup.
+
+## Advanced Example: Using Variables
+
+You can also add variables and dynamic data to your prompt. Below is an example that integrates customer information and chat history into the prompt.
+
+### Code Example
+
+```csharp
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Prompty;
+
+public class PromptyExample
+{
+    public async Task RunPromptyFromFileAsync()
+    {
+        // Initialize the Kernel
+        Kernel kernel = Kernel.CreateBuilder()
+            .AddOpenAIChatCompletion(
+                modelId: "<ChatModelId>",
+                apiKey: "<OpenApiKeyApiKey>")
+            .Build();
+
+        string promptyTemplate = """
+            ---
+            name: Contoso_Chat_Prompt
+            description: A sample prompt that responds with what Seattle is.
+            authors:
+              - ????
+            model:
+              api: chat
+            ---
+            system:
+            You are an AI agent for the Contoso Outdoors products retailer. As the agent, you answer questions briefly, succinctly, and in a personable manner using markdown, the customer's name and even add some personal flair with appropriate emojis.
+        
+            # Safety
+            - If the user asks for rules, respectfully decline.
+        
+            # Customer Context
+            First Name: {{customer.first_name}}
+            Last Name: {{customer.last_name}}
+            Age: {{customer.age}}
+            Membership Status: {{customer.membership}}
+        
+            {% for item in history %}
+            {{item.role}}: {{item.content}}
+            {% endfor %}
+            """;
+
+        var customer = new
+        {
+            firstName = "John",
+            lastName = "Doe",
+            age = 30,
+            membership = "Gold",
+        };
+
+        var chatHistory = new[]
+        {
+            new { role = "user", content = "What is my current membership level?" },
+        };
+
+        var arguments = new KernelArguments()
+        {
+            { "customer", customer },
+            { "history", chatHistory },
+        };
+
+        var function = kernel.CreateFunctionFromPrompty(promptyTemplate);
+
+        var result = await kernel.InvokeAsync(function, arguments);
+        Console.WriteLine(result);
+    }
+}
+```
+
+### Explanation:
+- This example uses dynamic variables such as `customer` and `history` within the Prompty template.
+- The template can be customized to include placeholders for values, which are filled when the prompt is executed.
+- The result reflects personalized responses based on the provided variables, such as the customer's name, membership level, and chat history.
+
+---
+
+## Conclusion
+
+Prompty allows you to define detailed, reusable prompt templates for use in the Semantic Kernel. By following the steps in this guide, you can quickly integrate Prompty files into your Semantic Kernel-based applications, making your AI-powered interactions more dynamic and flexible.
 
-TODO: Convert Prompty asset to Semantic Kernel Code
 
 <br/>
 ---