Added IVectorTextResultItem.Similarity and marked IVectorTextResultItem.VectorComparison obsolete

Author: crpietschmann

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## vNext
+
+Add:
+
+- Added `IVectorTextResultItem.Similarity` and marked `IVectorTextResultItem.VectorComparison` obsolete. `VectorComparison` will be removed in the future.
+- Added more comment metadata to code
+
 ## v2.1.1
 
 Add:

samples/genai-rag-onnx/Program.cs

@@ -131,7 +131,7 @@ static async Task Main(string[] args)
                 ragContext += result.Text + "\n\n";
                 // Print the metadata, vector comparison, and text of the result to the console
                 Console.WriteLine($"Document: {result.Metadata}");
-                Console.WriteLine($"Vector Comparison: {result.VectorComparison}");
+                Console.WriteLine($"Vector Comparison: {result.Similarity}");
                 Console.WriteLine($"Text Chunk Length: {result.Text.Length}");
                 Console.WriteLine("");
             }

src/Build5Nines.SharpVector/VectorCompare/CosineSimilarityVectorComparerAsync.cs

@@ -59,7 +59,7 @@ public float Calculate(float[] vectorA, float[] vectorB)
 
     public IEnumerable<IVectorTextResultItem<TId, TDocument, TMetadata>> Sort<TId, TDocument, TMetadata>(IEnumerable<IVectorTextResultItem<TId, TDocument, TMetadata>> results)
     {
-        return results.OrderByDescending(s => s.VectorComparison);
+        return results.OrderByDescending(s => s.Similarity);
     }
 
     public async Task<IEnumerable<IVectorTextResultItem<TId, TDocument, TMetadata>>> SortAsync<TId, TDocument, TMetadata>(IEnumerable<IVectorTextResultItem<TId, TDocument, TMetadata>> results)

src/Build5Nines.SharpVector/VectorCompare/EuclideanDistanceVectorComparerAsync.cs

@@ -43,7 +43,7 @@ public float Calculate(float[] vectorA, float[] vectorB)
 
     public IEnumerable<IVectorTextResultItem<TId, TDocument, TMetadata>> Sort<TId, TDocument, TMetadata>(IEnumerable<IVectorTextResultItem<TId, TDocument, TMetadata>> results)
     {
-        return results.OrderBy(s => s.VectorComparison);
+        return results.OrderBy(s => s.Similarity);
     }
 
     public async Task<IEnumerable<IVectorTextResultItem<TId, TDocument, TMetadata>>> SortAsync<TId, TDocument, TMetadata>(IEnumerable<IVectorTextResultItem<TId, TDocument, TMetadata>> results)

src/Build5Nines.SharpVector/VectorTextResult.cs

@@ -5,8 +5,17 @@ namespace Build5Nines.SharpVector;
 using System.Linq;
 using System.Runtime.InteropServices;
 
+/// <summary>
+/// Represents a result of a vector text search.
+/// </summary>
+/// <typeparam name="TId">The type of the identifier.</typeparam>
+/// <typeparam name="TDocument">The type of the document.</typeparam>
+/// <typeparam name="TMetadata">The type of the metadata.</typeparam>
 public interface IVectorTextResult<TId, TDocument, TMetadata>
 {
+    /// <summary>
+    /// The list of Texts found in the search results.
+    /// </summary>
     IEnumerable<IVectorTextResultItem<TId, TDocument, TMetadata>> Texts { get; }
 
     /// <summary>
@@ -30,10 +39,20 @@ public interface IVectorTextResult<TId, TDocument, TMetadata>
     public int TotalPages { get; }
 }
 
+/// <summary>
+/// Represents a result of a vector text search.
+/// </summary>
+/// <typeparam name="TMetadata">The type of the metadata.</typeparam>
 public interface IVectorTextResult<TMetadata>
  : IVectorTextResult<int, string, TMetadata>
  { }
 
+/// <summary>
+/// Represents a result of a vector text search.
+/// </summary>
+/// <typeparam name="TId">The type of the identifier.</typeparam>
+/// <typeparam name="TDocument">The type of the document.</typeparam>
+/// <typeparam name="TMetadata">The type of the metadata.</typeparam>
 public class VectorTextResult<TId, TDocument, TMetadata>
     : IVectorTextResult<TId, TDocument, TMetadata>
 {
@@ -50,6 +69,9 @@ public VectorTextResult(int totalCount, int pageIndex, int totalPages, IEnumerab
     /// </summary>
     public IEnumerable<IVectorTextResultItem<TId, TDocument, TMetadata>> Texts { get; private set; }
 
+    /// <summary>
+    /// Returns true if the search returned no results.
+    /// </summary>
     public bool IsEmpty { get => Texts == null || !Texts.Any(); }
 
     /// <summary>
@@ -68,6 +90,10 @@ public VectorTextResult(int totalCount, int pageIndex, int totalPages, IEnumerab
     public int TotalPages { get; private set; }
 }
 
+/// <summary>
+/// Represents a result of a vector text search.
+/// </summary>
+/// <typeparam name="TMetadata">The type of the metadata.</typeparam>
 public class VectorTextResult<TMetadata>
     : VectorTextResult<int, string, TMetadata>, IVectorTextResult<TMetadata>
 {

src/Build5Nines.SharpVector/VectorTextResultItem.cs

@@ -3,46 +3,106 @@
 
 namespace Build5Nines.SharpVector;
 
+/// <summary>
+/// Represents a result item from a semantic search on a vector database.
+/// </summary>
+/// <typeparam name="TDocument">The type of the document.</typeparam>
+/// <typeparam name="TMetadata">The type of the metadata.</typeparam>
 public interface IVectorTextResultItem<TDocument, TMetadata>
 {
+    /// <summary>
+    /// The string of text that was vectorized.
+    /// </summary>
     TDocument Text{ get; }
+
+    /// <summary>
+    /// The metadata associated with the text.
+    /// </summary>
     TMetadata? Metadata { get; }
 
+    /// <summary>
+    /// The vector similarity score between the query and the text. (This is deprecated, use 'Similarity' instead)
+    /// </summary>
+    [Obsolete("Use 'Similarity' instead")]
     float VectorComparison { get; }
+
+    /// <summary>
+    /// The vector similarity score between the query and the text.
+    /// </summary>
+    float Similarity { get; }
 }
 
+/// <summary>
+/// Represents a result item from a semantic search on a vector database.
+/// </summary>
+/// <typeparam name="TId">The type of the ID.</typeparam>
+/// <typeparam name="TDocument">The type of the document.</typeparam>
+/// <typeparam name="TMetadata">The type of the metadata.</typeparam>
 public interface IVectorTextResultItem<TId, TDocument, TMetadata>
     : IVectorTextResultItem<TDocument, TMetadata>
 {
     TId Id { get; }
 }
 
+/// <summary>
+/// Represents a result item from a semantic search on a vector database.
+/// </summary>
+/// <typeparam name="TMetadata">The type of the metadata.</typeparam>
 public interface IVectorTextResultItem<TMetadata>
  : IVectorTextResultItem<string, TMetadata>, IVectorTextResultItem<int, string, TMetadata>
 { }
 
+/// <summary>
+/// Represents a result item from a semantic search on a vector database.
+/// </summary>
+/// <typeparam name="TId">The type of the ID.</typeparam>
+/// <typeparam name="TDocument">The type of the document.</typeparam>
+/// <typeparam name="TMetadata">The type of the metadata.</typeparam>
 public class VectorTextResultItem<TId, TDocument, TMetadata>
     : IVectorTextResultItem<TDocument, TMetadata>, IVectorTextResultItem<TId, TDocument, TMetadata>
 {
     private IVectorTextItem<TDocument, TMetadata> _item;
     private TId _id;
 
-    public VectorTextResultItem(TId id, IVectorTextItem<TDocument, TMetadata> item, float vectorComparison)
+    public VectorTextResultItem(TId id, IVectorTextItem<TDocument, TMetadata> item, float similarity)
     {
         _id = id;
         _item = item;
-        VectorComparison = vectorComparison;
+        Similarity = similarity;
     }
 
+    /// <summary>
+    /// The string of text that was vectorized.
+    /// </summary>
     public TDocument Text { get => _item.Text; }
+
+    /// <summary>
+    /// The metadata associated with the text.
+    /// </summary>
     public TMetadata? Metadata { get => _item.Metadata; }
     public TId Id { get => _id; }
 
+    /// <summary>
+    /// The vector representation / embeddings of the text.
+    /// </summary>
     public ImmutableArray<float> Vectors { get => ImmutableArray.Create(_item.Vector); }
 
-    public float VectorComparison { get; private set; }
+    /// <summary>
+    /// The vector similarity score between the query and the text.
+    /// </summary>
+    public float Similarity { get; private set; }
+
+    /// <summary>
+    /// The vector similarity score between the query and the text. (This is deprecated, use 'Similarity' instead)
+    /// </summary>
+    [Obsolete("Use 'Similarity' instead")]
+    public float VectorComparison { get => Similarity; }
 }
 
+/// <summary>
+/// Represents a result item from a semantic search on a vector database.
+/// </summary>
+/// <typeparam name="TMetadata">The type of the metadata.</typeparam>
 public class VectorTextResultItem<TMetadata>
  : VectorTextResultItem<int, string, TMetadata>, IVectorTextResultItem<TMetadata>
 {

src/SharpVectorTest/Data/TextDataLoaderAsyncTests.cs

@@ -46,6 +46,6 @@ public async Task TextDataLoaderAsync_Paragraphs_01()
         Assert.AreEqual(1, results.Texts.Count());
         Assert.AreEqual("The Lion King is a 1994 Disney animated film about a young lion cub named Simba who is the heir to the throne of an African savanna. ", results.Texts.First().Text);
         Assert.AreEqual("{ chuckSize: \"133\" }", results.Texts.First().Metadata);
-        Assert.AreEqual(0.3396831452846527, results.Texts.First().VectorComparison);
+        Assert.AreEqual(0.3396831452846527, results.Texts.First().Similarity);
     }
 }

src/SharpVectorTest/Regression/RegressionTests.cs

@@ -25,7 +25,7 @@ public void VectorDatabaseVersion_2_0_2_001()
         Assert.AreEqual(1, results.Texts.Count());
         Assert.IsTrue(results.Texts.First().Text.Contains("Lion King"));
         Assert.AreEqual("{ value: \"JSON Metadata Value\" }", results.Texts.First().Metadata);
-        Assert.AreEqual(0.3396831452846527, results.Texts.First().VectorComparison);
+        Assert.AreEqual(0.3396831452846527, results.Texts.First().Similarity);
     }
 
     [TestMethod]