feat: support kernel memory (#11)

* feat: support kernel memory

* feat: support read config from IConfiguration

Author: ikesnowy

README.md

@@ -19,7 +19,13 @@ var response = await kernel.InvokePromptAsync(prompt);
 Console.WriteLine(response);
 ```
 
-## ASP.NET Core
+## ASP.NET Core with KernelMemory support
+
+Install Nuget package `Cnblogs.KernelMemory.AI.DashScope`
+
+Install Nuget package `Microsoft.KernelMemory.Core`
+
+Install Nuget package `Microsoft.KernelMemory.SemanticKernelPlugin`
 
 `appsettings.json`
 
@@ -35,19 +41,54 @@ Console.WriteLine(response);
 
 `Program.cs`
 ```csharp
+// Kernel Memory stuff
+var memory = new KernelMemoryBuilder(builder.Services).WithDashScope(builder.Configuration).Build();
+builder.Services.AddSingleton(memory);
+
+// SK stuff
 builder.Services.AddDashScopeChatCompletion(builder.Configuration);
-builder.Services.AddScoped<Kernel>(sp => new Kernel(sp));
+builder.Services.AddSingleton(
+    sp =>
+    {
+        var plugins = new KernelPluginCollection();
+        plugins.AddFromObject(
+            new MemoryPlugin(sp.GetRequiredService<IKernelMemory>(), waitForIngestionToComplete: true),
+            "memory");
+        return new Kernel(sp, plugins);
+    });
 ```
 
 Services
 
 ```csharp
-public class YourService(Kernel kernel)
+public class YourService(Kernel kernel, IKernelMemory memory)
 {
     public async Task<string> GetCompletionAsync(string prompt)
     {
         var chatResult = await kernel.InvokePromptAsync(prompt);
         return chatResult.ToString();
     }
+
+    public async Task ImportDocumentAsync(string filePath, string documentId)
+    {
+        await memory.ImportDocumentAsync(filePath, documentId);
+    }
+
+    public async Task<string> AskMemoryAsync(string question)
+    {
+        // use memory.ask to query kernel memory
+        var skPrompt = """
+                       Question to Kernel Memory: {{$input}}
+
+                       Kernel Memory Answer: {{memory.ask $input}}
+
+                       If the answer is empty say 'I don't know' otherwise reply with a preview of the answer, truncated to 15 words.
+                       """;
+
+        // you can bundle created functions into a singleton service to reuse them
+        var myFunction = kernel.CreateFunctionFromPrompt(skPrompt);
+        var result = await myFunction.InvokeAsync(question);
+        return result.ToString();
+    }
 }
 ```

SemanticKernel.DashScope.sln

@@ -16,6 +16,10 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "test", "test", "{DAB267DF-F
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SemanticKernel.DashScope.UnitTest", "test\SemanticKernel.DashScope.UnitTest\SemanticKernel.DashScope.UnitTest.csproj", "{648EBC1D-9409-4205-905E-DD06E4443AAA}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "KernelMemory.DashScope", "src\KernelMemory.DashScope\KernelMemory.DashScope.csproj", "{B68EBD2E-8169-4546-95CC-92D6F097C039}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "KernelMemory.DashScope.UnitTests", "test\KernelMemory.DashScope.UnitTests\KernelMemory.DashScope.UnitTests.csproj", "{A69BEA7D-6B14-4185-9696-94814F76A2DA}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -30,13 +34,23 @@ Global
 		{648EBC1D-9409-4205-905E-DD06E4443AAA}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{648EBC1D-9409-4205-905E-DD06E4443AAA}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{648EBC1D-9409-4205-905E-DD06E4443AAA}.Release|Any CPU.Build.0 = Release|Any CPU
+		{B68EBD2E-8169-4546-95CC-92D6F097C039}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{B68EBD2E-8169-4546-95CC-92D6F097C039}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{B68EBD2E-8169-4546-95CC-92D6F097C039}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{B68EBD2E-8169-4546-95CC-92D6F097C039}.Release|Any CPU.Build.0 = Release|Any CPU
+		{A69BEA7D-6B14-4185-9696-94814F76A2DA}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{A69BEA7D-6B14-4185-9696-94814F76A2DA}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{A69BEA7D-6B14-4185-9696-94814F76A2DA}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{A69BEA7D-6B14-4185-9696-94814F76A2DA}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
 		{B9EF31C7-48D7-4CA8-8D15-D6340450D3F5} = {BB73FA18-BBBE-4C34-971A-D4206FC118A2}
 		{648EBC1D-9409-4205-905E-DD06E4443AAA} = {DAB267DF-F966-4F95-AD12-56CC78D6F274}
+		{B68EBD2E-8169-4546-95CC-92D6F097C039} = {BB73FA18-BBBE-4C34-971A-D4206FC118A2}
+		{A69BEA7D-6B14-4185-9696-94814F76A2DA} = {DAB267DF-F966-4F95-AD12-56CC78D6F274}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {D0F2E9A4-9782-4C3F-B459-CFCAD4C9AD9F}

pack.sh

@@ -1,10 +1,13 @@
 #!/bin/bash
 set -e
 
-[ -z $1 ] && echo "Missing version" && exit 1
+[ -z "$1" ] && echo "Missing tag and version" && exit 1
 
-version=$1
-project=src/SemanticKernel.DashScope
+commit_tag=$1
+IFS=/ read -r tagname version <<< "$commit_tag"
+
+version=${version:1}
+project=src/${tagname}
 dotnet clean -c Release
 dotnet build -p:Version=${version-*} -c Release $project
 dotnet pack $project -c Release -p:IncludeSymbols=true -p:SymbolPackageFormat=snupkg --include-source -p:PackageVersion=$version -p:Version=${version-*} -o ./artifacts

src/KernelMemory.DashScope/DashScopeConfig.cs

@@ -0,0 +1,60 @@
+namespace Cnblogs.KernelMemory.AI.DashScope;
+
+/// <summary>
+/// DashScope Settings.
+/// </summary>
+public record DashScopeConfig
+{
+    /// <summary>
+    /// Model used for text generation. Chat models can be used too.
+    /// </summary>
+    public string ChatCompletionModelId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// The max number of tokens supported by the text model.
+    /// </summary>
+    public int TextModelMaxTokenTotal { get; set; } = 6000;
+
+    /// <summary>
+    /// Model used to embedding generation.
+    /// </summary>
+    public string TextEmbeddingModelId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// The max number of tokens supported by the embedding model.
+    /// Defaults to 2048.
+    /// </summary>
+    public int EmbeddingModelMaxTokenTotal { get; set; } = 2048;
+
+    /// <summary>
+    /// DashScope API key.
+    /// </summary>
+    public string ApiKey { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Validates the config.
+    /// </summary>
+    public void EnsureValid()
+    {
+        if (string.IsNullOrWhiteSpace(ApiKey))
+        {
+            throw new ArgumentOutOfRangeException(nameof(ApiKey), ApiKey, "Api key cannot be null or empty");
+        }
+
+        if (TextModelMaxTokenTotal < 1)
+        {
+            throw new ArgumentOutOfRangeException(
+                nameof(TextModelMaxTokenTotal),
+                TextModelMaxTokenTotal,
+                $"{nameof(TextModelMaxTokenTotal)} cannot be less than 1");
+        }
+
+        if (EmbeddingModelMaxTokenTotal < 1)
+        {
+            throw new ArgumentOutOfRangeException(
+                nameof(EmbeddingModelMaxTokenTotal),
+                EmbeddingModelMaxTokenTotal,
+                $"{nameof(EmbeddingModelMaxTokenTotal)} cannot be less than 1");
+        }
+    }
+}

src/KernelMemory.DashScope/DashScopeEmbeddedResource.cs

@@ -0,0 +1,29 @@
+using System.Reflection;
+using Microsoft.KernelMemory.Configuration;
+
+namespace Cnblogs.KernelMemory.AI.DashScope;
+
+internal static class DashScopeEmbeddedResource
+{
+    private static readonly string? Namespace = typeof(DashScopeEmbeddedResource).Namespace;
+
+    internal static Stream ReadBpeFile()
+    {
+        return Read("qwen.tiktoken");
+    }
+
+    private static Stream Read(string fileName)
+    {
+        // Get the current assembly. Note: this class is in the same assembly where the embedded resources are stored.
+        var assembly = typeof(DashScopeEmbeddedResource).GetTypeInfo().Assembly;
+        if (assembly == null) { throw new ConfigurationException($"[{Namespace}] {fileName} assembly not found"); }
+
+        // Resources are mapped like types, using the namespace and appending "." (dot) and the file name
+        var resourceName = $"{Namespace}." + fileName;
+        var resource = assembly.GetManifestResourceStream(resourceName);
+        if (resource == null) { throw new ConfigurationException($"{resourceName} resource not found"); }
+
+        // Return the resource content, in text format.
+        return resource;
+    }
+}

src/KernelMemory.DashScope/DashScopeTextEmbeddingGenerator.cs

@@ -0,0 +1,39 @@
+using Cnblogs.DashScope.Sdk;
+using Cnblogs.DashScope.Sdk.TextEmbedding;
+using Microsoft.KernelMemory;
+using Microsoft.KernelMemory.AI;
+
+namespace Cnblogs.KernelMemory.AI.DashScope;
+
+/// <summary>
+/// DashScope text embedding generator implementation.
+/// </summary>
+/// <param name="dashScopeClient">The <see cref="IDashScopeClient"/>.</param>
+/// <param name="modelId">The model id to use.</param>
+/// <param name="tokenizer">The tokenizer to use.</param>
+/// <param name="maxTokens">Maximum token limit.</param>
+public class DashScopeTextEmbeddingGenerator(
+    IDashScopeClient dashScopeClient,
+    string modelId,
+    ITextTokenizer? tokenizer = null,
+    int maxTokens = 2048)
+    : ITextEmbeddingGenerator
+{
+    /// <inheritdoc />
+    public int CountTokens(string text)
+    {
+        return tokenizer?.CountTokens(text) ?? text.Length;
+    }
+
+    /// <inheritdoc />
+    public async Task<Embedding> GenerateEmbeddingAsync(
+        string text,
+        CancellationToken cancellationToken = new())
+    {
+        var result = await dashScopeClient.GetTextEmbeddingsAsync(modelId, [text], null, cancellationToken);
+        return result.Output.Embeddings[0].Embedding;
+    }
+
+    /// <inheritdoc />
+    public int MaxTokens => maxTokens;
+}

src/KernelMemory.DashScope/DashScopeTextGenerator.cs

@@ -0,0 +1,71 @@
+using System.Runtime.CompilerServices;
+using Cnblogs.DashScope.Sdk;
+using Microsoft.Extensions.Logging;
+using Microsoft.KernelMemory.AI;
+using Microsoft.KernelMemory.Diagnostics;
+
+namespace Cnblogs.KernelMemory.AI.DashScope;
+
+/// <summary>
+/// Text generator using DashScope.
+/// </summary>
+/// <param name="dashScopeClient">The <see cref="IDashScopeClient"/>.</param>
+/// <param name="modelId">Model name.</param>
+/// <param name="loggerFactory">Logger factory to use.</param>
+/// <param name="tokenizer">Tokenizer to use.</param>
+/// <param name="maxToken">Maximum token count.</param>
+public class DashScopeTextGenerator(
+    IDashScopeClient dashScopeClient,
+    string modelId,
+    ILoggerFactory? loggerFactory = null,
+    ITextTokenizer? tokenizer = null,
+    int maxToken = 6000) : ITextGenerator
+{
+    private readonly ILogger<DashScopeTextGenerator> _logger = loggerFactory?.CreateLogger<DashScopeTextGenerator>()
+                                                                ?? DefaultLogger<DashScopeTextGenerator>.Instance;
+
+    /// <inheritdoc />
+    public int CountTokens(string text)
+    {
+        return tokenizer?.CountTokens(text) ?? QWenTokenizer.CountTokensStatic(text);
+    }
+
+    /// <inheritdoc />
+    public async IAsyncEnumerable<string> GenerateTextAsync(
+        string prompt,
+        TextGenerationOptions options,
+        [EnumeratorCancellation] CancellationToken cancellationToken = new())
+    {
+        var parameters = new TextGenerationParameters
+        {
+            TopP = options.TopP == 0 ? null : (float)options.TopP,
+            Temperature = options.Temperature == 0 ? null : (float)options.Temperature,
+            RepetitionPenalty =
+                options.FrequencyPenalty == 0 ? null : ((float)options.FrequencyPenalty + 1), // dashScope's default value is 1.0, kernel memory is 0.0
+            MaxTokens = options.MaxTokens == 0 ? null : options.MaxTokens,
+            Stop = options.StopSequences.ToArray(),
+            IncrementalOutput = true,
+            ResultFormat = ResultFormats.Text
+        };
+
+        if (options.TokenSelectionBiases.Count != 0)
+        {
+            _logger.LogWarning("TokenSelectionBiases is not supported by DashScope and will be ignored");
+        }
+
+        var request = new ModelRequest<TextGenerationInput, ITextGenerationParameters>
+        {
+            Model = modelId,
+            Input = new TextGenerationInput { Prompt = prompt },
+            Parameters = parameters
+        };
+        var tokens = dashScopeClient.GetTextCompletionStreamAsync(request, cancellationToken);
+        await foreach (var token in tokens)
+        {
+            yield return token.Output.Text!;
+        }
+    }
+
+    /// <inheritdoc />
+    public int MaxTokenTotal => maxToken;
+}