SingleStore.SemanticKernel 0.1.1

SingleStore connector for Microsoft Semantic Kernel

Attention: The code in this repository is intended for experimental use only and is not fully tested, documented, or supported by SingleStore. Visit the SingleStore Forums to ask questions about this repository.

Repository for SingleStore.SemanticKernel, the official SingleStore Vector Store Connector for Microsoft Semantic Kernel.

Introduction

Semantic Kernel is an SDK that integrates Large Language Models (LLMs) like OpenAI, Azure OpenAI, and Hugging Face with conventional programming languages like C#, Python, and Java. Semantic Kernel achieves this by allowing you to define plugins that can be chained together in just a few lines of code.

Semantic Kernel and .NET provide an abstraction for interacting with Vector Stores and a list of out-of-the-box connectors that implement these abstractions. Features include creating, listing, and deleting collections of records, and uploading, retrieving, and deleting records. The abstraction makes it easy to experiment with a free or locally hosted Vector Store and then switch to a service when there is a need to scale up.

This repository contains the official SingleStore Vector Store Connector implementation for Semantic Kernel.

Overview

The SingleStore Vector Store connector can be used to access and manage data in SingleStore.

The connector has the following characteristics.

Limitations

Here is an example of how to set AllowLoadLocalInfile and ConnectionAttributes.

SingleStoreDataSource dataSource = new("Host=localhost;Port=3306;Username=root;Password=example;Database=db;AllowLoadLocalInfile=true;ConnectionAttributes=_connector_name:SingleStore Semantic Kernel .NET Connector");

When using the AddSingleStoreVectorStore dependency injection registration method with a connection string, AllowLoadLocalInfile and ConnectionAttributes are set automatically.

Getting started

Add the SingleStore Vector Store connector NuGet package to your project.

dotnet add package SingleStore.SemanticKernel --prerelease

You can add the vector store to the IServiceCollection dependency injection container using extension methods provided by the connector package.

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;
using SingleStore.SemanticKernel;

var kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.Services.AddSingleStoreVectorStore("<Connection String>");

Where <Connection String> is a connection string to the SingleStore instance, in the format that SingleStore .NET Connector expects, for example Host=localhost;Port=3306;Database=db;Username=root;Password=secret.

Extension methods that take no parameters are also provided. These require an instance of SingleStoreDataSource to be separately registered with the dependency injection container. To upload records, ensure that AllowLoadLocalInfile is enabled and ConnectionAttributes is set:

using Microsoft.Extensions.DependencyInjection;
using SingleStore.SemanticKernel;
using SingleStoreConnector;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<SingleStoreDataSource>(sp =>
    new SingleStoreDataSource("<Connection String>;AllowLoadLocalInfile=true;ConnectionAttributes=_connector_name:SingleStore Semantic Kernel .NET Connector"));
builder.Services.AddSingleStoreVectorStore();

You can construct a SingleStore Vector Store instance directly with a custom data source or with a connection string.

using SingleStore.SemanticKernel;
using SingleStoreConnector;

SingleStoreDataSource dataSource = new("<Connection String>;AllowLoadLocalInfile=true;ConnectionAttributes=_connector_name:SingleStore Semantic Kernel .NET Connector");
var vectorStore = new SingleStoreVectorStore(dataSource, ownsDataSource: true);

using SingleStore.SemanticKernel;

var vectorStore = new SingleStoreVectorStore("<Connection String>");

It is possible to construct a direct reference to a named collection with a custom data source or with a connection string.

using SingleStore.SemanticKernel;
using SingleStoreConnector;

SingleStoreDataSource dataSource = new("<Connection String>;AllowLoadLocalInfile=true;ConnectionAttributes=_connector_name:SingleStore Semantic Kernel .NET Connector");

var collection = new SingleStoreCollection<int, Hotel>(dataSource, "skhotels", ownsDataSource: true);

using SingleStore.SemanticKernel;

var collection = new SingleStoreCollection<int, Hotel>("<Connection String>", "skhotels");

Data mapping

The SingleStore Vector Store connector provides a default mapper when mapping from the data model to storage. This mapper directly converts the list of properties defined in the data model to columns in SingleStore.

The following table shows the default key and data property type mapping:

Vector properties are mapped to VECTOR(dimensions, F32).

Property name override

You can specify a storage field name that differs from the corresponding property name in the data model. This allows you to match table column names even if they don't match the property names on the data model.

The property name override is done by setting the StorageName option via the data model attributes or record definition.

Here is an example of a data model with StorageName set on its attributes and how it will be represented in SingleStore as a table, assuming the Collection name is Hotels.

using System;
using Microsoft.Extensions.VectorData;

public class Hotel
{
    [VectorStoreKey(StorageName = "hotel_id")]
    public int HotelId { get; set; }

    [VectorStoreData(StorageName = "hotel_name")]
    public string HotelName { get; set; }

    [VectorStoreData(StorageName = "hotel_description")]
    public string Description { get; set; }

    [VectorStoreVector(dimensions: 4, DistanceFunction = DistanceFunction.EuclideanDistance, IndexKind = IndexKind.Hnsw, StorageName = "hotel_description_embedding")]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
}

CREATE TABLE IF NOT EXISTS `db`.`Hotels`
(
    `hotel_id` INT NOT NULL,
    `hotel_name` LONGTEXT NOT NULL,
    `hotel_description` LONGTEXT NOT NULL,
    `hotel_description_embedding` VECTOR(4, F32) NULL,
    PRIMARY KEY (`hotel_id`),
    VECTOR KEY (`hotel_description_embedding`) INDEX_OPTIONS '{ "metric_type":"EUCLIDEAN_DISTANCE", "index_type":"HNSW_FLAT" }'
);

Release process

Releasing a new version takes two steps.

1. Push a version tag

Push a version tag using semantic versioning with a v prefix (v<major>.<minor>.<patch>, for example v1.2.3):

git tag v1.0.1
git push origin v1.0.1

The package version is derived from the tag (the leading v is stripped). This triggers the CI workflow, which:

• Runs the test matrix
• Builds the connector with the release version
• Signs SingleStore.SemanticKernel.dll with Azure Artifact Signing
• Packs the signed assemblies into a NuGet package and publishes it to NuGet.org
• Creates a draft GitHub Release with auto-generated release notes and the package (SingleStore.SemanticKernel.<version>.nupkg)

2. Publish the draft release

After the workflow succeeds, open the Releases page, review the draft release for the new tag (edit the notes if needed), and click Publish release.