feat: expose CosineSimilarity with robust safeguards

Author: GregorBiswanger

src/SemanticChunker.NET.Tests/SemanticChunkerNET.Tests.csproj

@@ -14,12 +14,12 @@
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
-    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
-    <PackageReference Include="Microsoft.SemanticKernel" Version="1.61.0" />
-    <PackageReference Include="OllamaApiFacade" Version="1.3.0" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.0.1" />
+    <PackageReference Include="Microsoft.SemanticKernel" Version="1.67.1" />
+    <PackageReference Include="OllamaApiFacade" Version="1.3.1" />
     <PackageReference Include="Shouldly" Version="4.3.0" />
     <PackageReference Include="xunit" Version="2.9.3" />
-    <PackageReference Include="xunit.runner.visualstudio" Version="3.1.3">
+    <PackageReference Include="xunit.runner.visualstudio" Version="3.1.5">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>

src/SemanticChunker.NET.Tests/SemanticChunkerTests.cs

@@ -183,7 +183,7 @@ public async Task E5Model_CosineSimilarities_AreWithinExpectedRange()
         {
             for (var j = i + 1; j < inputs.Length; j++)
             {
-                similarities.Add(CosineSimilarity(embeddings[i].Vector.ToArray(),
+                similarities.Add(SemanticChunker.CosineSimilarity(embeddings[i].Vector.ToArray(),
                                                   embeddings[j].Vector.ToArray()));
             }
         }
@@ -220,6 +220,55 @@ public async Task CreateChunksAsync_TwoSimilarSentences_ReturnsOneOrTwoChunksCon
         }
     }
 
+    [Fact]
+    public void Cosine_IdenticalVectors_IsOne()
+    {
+        var v = new float[] { 1, 2, 3, 4 };
+        SemanticChunker.CosineSimilarity(v, v).ShouldBe(1.0, 1e-12);
+    }
+
+    [Fact]
+    public void Cosine_OppositeVectors_IsMinusOne()
+    {
+        var a = new float[] { 1, 0, -2 };
+        var b = new float[] { -1, 0, 2 };
+        SemanticChunker.CosineSimilarity(a, b).ShouldBe(-1.0, 1e-12);
+    }
+
+    [Fact]
+    public void Cosine_Orthogonal_IsZero()
+    {
+        var a = new float[] { 1, 0 };
+        var b = new float[] { 0, 5 };
+        SemanticChunker.CosineSimilarity(a, b).ShouldBe(0.0, 1e-12);
+    }
+
+    [Fact]
+    public void Cosine_ZeroVector_ReturnsZero()
+    {
+        var a = new float[] { 0, 0, 0 };
+        var b = new float[] { 1, 2, 3 };
+        SemanticChunker.CosineSimilarity(a, b).ShouldBe(0.0, 1e-12);
+    }
+
+    [Fact]
+    public void Cosine_DifferentLengths_Throws()
+    {
+        var a = new float[] { 1, 2, 3 };
+        var b = new float[] { 1, 2 };
+        Should.Throw<ArgumentException>(() => SemanticChunker.CosineSimilarity(a, b));
+    }
+
+    [Fact]
+    public void Cosine_IsBoundedInMinusOneToOne()
+    {
+        var rnd = new Random(42);
+        var a = Enumerable.Range(0, 1000).Select(_ => (float)rnd.NextDouble()).ToArray();
+        var b = Enumerable.Range(0, 1000).Select(_ => (float)rnd.NextDouble()).ToArray();
+        var cos = SemanticChunker.CosineSimilarity(a, b);
+        cos.ShouldBeInRange(-1.0, 1.0);
+    }
+
     private static double AnalyzeSemanticCoherence(IList<Chunk> chunks)
     {
         var maxCoherence = 0.0;
@@ -245,23 +294,4 @@ private static double AnalyzeSemanticCoherence(IList<Chunk> chunks)
 
         return maxCoherence;
     }
-
-    private static double CosineSimilarity(float[] vectorA, float[] vectorB)
-    {
-        if (vectorA.Length != vectorB.Length)
-            throw new ArgumentException("Vektoren müssen gleiche Länge haben");
-
-        double dotProduct = 0.0;
-        double normA = 0.0;
-        double normB = 0.0;
-
-        for (var i = 0; i < vectorA.Length; i++)
-        {
-            dotProduct += vectorA[i] * vectorB[i];
-            normA += vectorA[i] * vectorA[i];
-            normB += vectorB[i] * vectorB[i];
-        }
-
-        return dotProduct / (Math.Sqrt(normA) * Math.Sqrt(normB));
-    }
 }

src/SemanticChunker.NET/SemanticChunker.cs

@@ -100,6 +100,50 @@ public async Task<IList<Chunk>> CreateChunksAsync(string text, CancellationToken
         return await AssembleChunksAsync(sentences, breakpoints, minChunkChars, cancellationToken);
     }
 
+    /// <summary>
+    /// Calculates the cosine similarity between two vectors of equal length.
+    /// </summary>
+    /// <param name="vectorA">The first vector.</param>
+    /// <param name="vectorB">The second vector.</param>
+    /// <returns>
+    /// A value between -1 and1 representing the cosine similarity:
+    ///1 indicates identical direction,0 indicates orthogonality, and -1 indicates opposite direction.
+    /// Returns0 if either vector has zero magnitude.
+    /// </returns>
+    /// <exception cref="ArgumentNullException">
+    /// Thrown if <paramref name="vectorA"/> or <paramref name="vectorB"/> is null.
+    /// </exception>
+    /// <exception cref="ArgumentException">
+    /// Thrown if the vectors do not have the same length.
+    /// </exception>
+    public static double CosineSimilarity(IReadOnlyList<float> vectorA, IReadOnlyList<float> vectorB)
+    {
+        if (vectorA is null) throw new ArgumentNullException(nameof(vectorA));
+        if (vectorB is null) throw new ArgumentNullException(nameof(vectorB));
+        if (vectorA.Count != vectorB.Count) throw new ArgumentException("Vectors must have the same length.");
+
+        double dot = 0, na = 0, nb = 0;
+
+        for (int i = 0; i < vectorA.Count; i++)
+        {
+            var ai = vectorA[i];
+            var bi = vectorB[i];
+            dot += ai * bi;
+            na += ai * ai;
+            nb += bi * bi;
+        }
+
+        var denom = Math.Sqrt(na) * Math.Sqrt(nb);
+        if (denom == 0) return 0;
+
+        var cos = dot / denom;
+
+        if (cos > 1) return 1;
+        if (cos < -1) return -1;
+
+        return cos;
+    }
+
     private static IList<string> SplitIntoSentences(string text)
     {
         var result = new List<string>();
@@ -235,8 +279,6 @@ private static double ThresholdFromTargetCount(IReadOnlyList<double> distances,
         return Percentile(distances, percentile);
     }
 
-    // ---------- Statistics helpers ----------
-
     private static double Percentile(IReadOnlyList<double> sequence, double p)
     {
         double[] sorted = sequence.OrderBy(v => v).ToArray();
@@ -270,20 +312,4 @@ private static double[] Gradient(IReadOnlyList<double> sequence)
 
         return g;
     }
-
-    private static double CosineSimilarity(IReadOnlyList<float> a, IReadOnlyList<float> b)
-    {
-        double dot = 0;
-        double magnitudeA = 0;
-        double magnitudeB = 0;
-
-        for (int i = 0; i < a.Count; i++)
-        {
-            dot += a[i] * b[i];
-            magnitudeA += a[i] * a[i];
-            magnitudeB += b[i] * b[i];
-        }
-
-        return dot / (Math.Sqrt(magnitudeA) * Math.Sqrt(magnitudeB));
-    }
 }

src/SemanticChunker.NET/SemanticChunkerNET.csproj

@@ -8,7 +8,7 @@
 
   <PropertyGroup>
     <PackageId>SemanticChunker.NET</PackageId>
-    <Version>1.0.1</Version>
+    <Version>1.1.0</Version>
     <Authors>Gregor Biswanger</Authors>
     <Description>
       SemanticChunker.NET delivers automatic Semantic Chunking for Retrieval‑Augmented Generation in .NET. The library splits long documents into embedding‑aware, context‑preserving chunks that fit your LLM’s token budget. Compatible with Microsoft.Extensions.AI and Semantic Kernel, featuring four breakpoint strategies, target‑chunk mode, multilingual sentence detection and token‑limit safety.
@@ -36,7 +36,7 @@
 
   <ItemGroup>
     <PackageReference Include="ICU4N" Version="60.1.0-alpha.438" />
-    <PackageReference Include="Microsoft.Extensions.AI.Abstractions" Version="9.7.1" />
+    <PackageReference Include="Microsoft.Extensions.AI.Abstractions" Version="10.0.0" />
   </ItemGroup>
 
   <ItemGroup>