.Net: Add Updated Memory Connector ADR and IMemoryRecordService interface with related classes.

dotnet/src/SemanticKernel.Abstractions/Memory/IVectorDBRecordService{TKey,TDataModel}.cs

@@ -0,0 +1,80 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Microsoft.SemanticKernel.Memory;
+
+/// <summary>
+/// An interface for adding, updating, deleting and retrieving records from a vector store.
+/// </summary>
+/// <typeparam name="TKey">The data type of the record key.</typeparam>
+/// <typeparam name="TDataModel">The data model to use for adding, updating and retrieving data from storage.</typeparam>
+[Experimental("SKEXP0001")]
+public interface IVectorDBRecordService<TKey, TDataModel>
+    where TDataModel : class
+{
+    /// <summary>
+    /// Gets a vector record from the data store. Does not guarantee that the collection exists.
+    /// Throws if the record is not found.
+    /// </summary>
+    /// <param name="key">The unique id associated with the vector record to get.</param>
+    /// <param name="options">Optional options for retrieving the record.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>The vector record if found, otherwise null.</returns>
+    Task<TDataModel?> GetAsync(TKey key, GetRecordOptions? options = default, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Gets a batch of vector records from the data store. Does not guarantee that the collection exists.
+    /// Throws if any of the records are not found.
+    /// Gets will be made in a single request or in a single parallel batch depending on the available store functionality.
+    /// </summary>
+    /// <param name="keys">The unique ids associated with the vector record to get.</param>
+    /// <param name="options">Optional options for retrieving the records.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>The vector records associated with the unique keys provided.</returns>
+    IAsyncEnumerable<TDataModel?> GetBatchAsync(IEnumerable<TKey> keys, GetRecordOptions? options = default, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Removes a vector record from the data store. Does not guarantee that the collection exists.
+    /// </summary>
+    /// <param name="key">The unique id associated with the vector record to remove.</param>
+    /// <param name="options">Optional options for removing the record.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>The unique identifier for the vector record.</returns>
+    Task RemoveAsync(TKey key, RemoveRecordOptions? options = default, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Removes a batch of vector records from the data store. Does not guarantee that the collection exists.
+    /// Removes will be made in a single request or in a single parallel batch depending on the available store functionality.
+    /// </summary>
+    /// <param name="keys">The unique ids associated with the vector records to remove.</param>
+    /// <param name="options">Optional options for removing the records.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    Task RemoveBatchAsync(IEnumerable<TKey> keys, RemoveRecordOptions? options = default, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Upserts a vector record into the data store. Does not guarantee that the collection exists.
+    ///     If the record already exists, it will be updated.
+    ///     If the record does not exist, it will be created.
+    /// </summary>
+    /// <param name="record">The vector record to upsert.</param>
+    /// <param name="options">Optional options for upserting the record.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>The unique identifier for the vector record.</returns>
+    Task<TKey> UpsertAsync(TDataModel record, UpsertRecordOptions? options = default, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Upserts a group of vector records into the data store. Does not guarantee that the collection exists.
+    ///     If the record already exists, it will be updated.
+    ///     If the record does not exist, it will be created.
+    /// Upserts will be made in a single request or in a single parallel batch depending on the available store functionality.
+    /// </summary>
+    /// <param name="records">The vector records to upsert.</param>
+    /// <param name="options">Optional options for upserting the records.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>The unique identifiers for the vector records.</returns>
+    IAsyncEnumerable<TKey> UpsertBatchAsync(IEnumerable<TDataModel> records, UpsertRecordOptions? options = default, CancellationToken cancellationToken = default);
+}

dotnet/src/SemanticKernel.Abstractions/Memory/RecordOptions/GetRecordOptions.cs

@@ -0,0 +1,39 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+
+namespace Microsoft.SemanticKernel.Memory;
+
+/// <summary>
+/// Optional options when calling <see cref="IVectorDBRecordService{TKey, TDataModel}.GetAsync"/>.
+/// </summary>
+[Experimental("SKEXP0001")]
+public class GetRecordOptions
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="GetRecordOptions"/> class.
+    /// </summary>
+    public GetRecordOptions()
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="GetRecordOptions"/> class by cloning the given options.
+    /// </summary>
+    /// <param name="source">The options to clone</param>
+    public GetRecordOptions(GetRecordOptions source)
+    {
+        this.CollectionName = source.CollectionName;
+        this.IncludeVectors = source.IncludeVectors;
+    }
+
+    /// <summary>
+    /// Get or sets an optional collection name to use for this operation that is different to the default.
+    /// </summary>
+    public string? CollectionName { get; init; }
+
+    /// <summary>
+    /// Get or sets a value indicating whether to include vectors in the retrieval result.
+    /// </summary>
+    public bool IncludeVectors { get; init; } = false;
+}

dotnet/src/SemanticKernel.Abstractions/Memory/RecordOptions/RemoveRecordOptions.cs

@@ -0,0 +1,33 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+
+namespace Microsoft.SemanticKernel.Memory;
+
+/// <summary>
+/// Optional options when calling <see cref="IVectorDBRecordService{TKey, TDataModel}.RemoveAsync"/>.
+/// </summary>
+[Experimental("SKEXP0001")]
+public class RemoveRecordOptions
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="RemoveRecordOptions"/> class.
+    /// </summary>
+    public RemoveRecordOptions()
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="RemoveRecordOptions"/> class by cloning the given options.
+    /// </summary>
+    /// <param name="source">The options to clone</param>
+    public RemoveRecordOptions(RemoveRecordOptions source)
+    {
+        this.CollectionName = source.CollectionName;
+    }
+
+    /// <summary>
+    /// Get or sets an optional collection name to use for this operation that is different to the default.
+    /// </summary>
+    public string? CollectionName { get; init; }
+}

dotnet/src/SemanticKernel.Abstractions/Memory/RecordOptions/UpsertRecordOptions.cs

@@ -0,0 +1,33 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+
+namespace Microsoft.SemanticKernel.Memory;
+
+/// <summary>
+/// Optional options when calling <see cref="IVectorDBRecordService{TKey, TDataModel}.UpsertAsync"/>.
+/// </summary>
+[Experimental("SKEXP0001")]
+public class UpsertRecordOptions
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="UpsertRecordOptions"/> class.
+    /// </summary>
+    public UpsertRecordOptions()
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="UpsertRecordOptions"/> class by cloning the given options.
+    /// </summary>
+    /// <param name="source">The options to clone</param>
+    public UpsertRecordOptions(UpsertRecordOptions source)
+    {
+        this.CollectionName = source.CollectionName;
+    }
+
+    /// <summary>
+    /// Get or sets an optional collection name to use for this operation that is different to the default.
+    /// </summary>
+    public string? CollectionName { get; init; }
+}

dotnet/src/SemanticKernel.Abstractions/Memory/VectorDBRecordAttributes/DataAttribute.cs

@@ -0,0 +1,15 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+
+namespace Microsoft.SemanticKernel.Memory;
+
+/// <summary>
+/// Attribute to mark a property on a vector model class as the data that is being indexed.
+/// </summary>
+[Experimental("SKEXP0001")]
+[AttributeUsage(AttributeTargets.Property, AllowMultiple = false)]
+public sealed class DataAttribute : Attribute
+{
+}

dotnet/src/SemanticKernel.Abstractions/Memory/VectorDBRecordAttributes/KeyAttribute.cs

@@ -0,0 +1,15 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+
+namespace Microsoft.SemanticKernel.Memory;
+
+/// <summary>
+/// Attribute to mark a property on a class as the key under which data is stored in a vector store.
+/// </summary>
+[Experimental("SKEXP0001")]
+[AttributeUsage(AttributeTargets.Property, AllowMultiple = false)]
+public sealed class KeyAttribute : Attribute
+{
+}

dotnet/src/SemanticKernel.Abstractions/Memory/VectorDBRecordAttributes/MetadataAttribute.cs

@@ -0,0 +1,15 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+
+namespace Microsoft.SemanticKernel.Memory;
+
+/// <summary>
+/// Attribute to mark a property on a vector model class as metadata about the record.
+/// </summary>
+[Experimental("SKEXP0001")]
+[AttributeUsage(AttributeTargets.Property, AllowMultiple = false)]
+public sealed class MetadataAttribute : Attribute
+{
+}

dotnet/src/SemanticKernel.Abstractions/Memory/VectorDBRecordAttributes/VectorAttribute.cs

@@ -0,0 +1,19 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+
+namespace Microsoft.SemanticKernel.Memory;
+
+/// <summary>
+/// Attribute to mark a property on a vector model class as the vector.
+/// </summary>
+[Experimental("SKEXP0001")]
+[AttributeUsage(AttributeTargets.Property, AllowMultiple = false)]
+public sealed class VectorAttribute : Attribute
+{
+    /// <summary>
+    /// Gets or sets the name of a related property in the data model that is storing the data that this vector is indexing.
+    /// </summary>
+    public string? DataPropertyName { get; set; }
+}