**feat(similarity): add similarity calculation between vectors and text inputs**

- Introduced `calculateSimilarity` method in `types.d.ts` for comparing vectors or textual inputs:
  - Added support for custom options, including `forceEmbed` and a custom `distanceFunction`.
- Enhanced functionality in `embed` to convert text inputs into vector representations.
- Added new test cases in `vector-operations.test.ts`:
  - Validated similarity calculations between identical and different vectors.
  - Tested similarity scoring for similar and dissimilar text inputs.
- Updated `README.md`:
  - Documented `calculateSimilarity` usage examples, including advanced options.
  - Clarified the integration of the similarity function into workflows.

**Purpose**: Enable calculation of similarity scores for vectors and text inputs to facilitate advanced data comparison and retrieval tasks.

README.md

@@ -731,6 +731,25 @@ await threadedDb.init()
 
 // Directly embed text to vectors
 const vector = await db.embed("Some text to convert to a vector")
+
+// Calculate similarity between two texts or vectors
+const similarity = await db.calculateSimilarity(
+  "Cats are furry pets", 
+  "Felines make good companions"
+)
+console.log(`Similarity score: ${similarity}`) // Higher value means more similar
+
+// Calculate similarity with custom options
+const vectorA = await db.embed("First text")
+const vectorB = await db.embed("Second text")
+const customSimilarity = await db.calculateSimilarity(
+  vectorA, // Can use pre-computed vectors
+  vectorB,
+  {
+    forceEmbed: false, // Skip embedding if inputs are already vectors
+    distanceFunction: cosineDistance // Optional custom distance function
+  }
+)
 ```
 
 The threaded embedding function runs in a separate thread (Web Worker in browsers, Worker Thread in Node.js) to improve

cli-package/types.d.ts

@@ -15,6 +15,14 @@ declare module '@soulcraft/brainy' {
     search(query: string, limit?: number, options?: any): Promise<any[]>
 
     searchText(query: string, limit?: number, options?: any): Promise<any[]>
+    
+    embed(data: string | string[]): Promise<number[]>
+    
+    calculateSimilarity(
+      a: number[] | string | string[],
+      b: number[] | string | string[],
+      options?: { forceEmbed?: boolean, distanceFunction?: any }
+    ): Promise<number>
 
     addVerb(
       sourceId: string,

tests/vector-operations.test.ts

@@ -88,4 +88,54 @@ describe('Vector Operations', () => {
     // The closest should be the exact match
     expect(results[0].metadata.id).toBe('vec1')
   })
+
+  it('should calculate similarity between vectors correctly', async () => {
+    const brainy = await import('../dist/unified.js')
+
+    const db = new brainy.BrainyData({
+      distanceFunction: euclideanDistance
+    })
+
+    await db.init()
+
+    // Create test vectors
+    const vectorA = createTestVector(0)
+    const vectorB = createTestVector(0) // Identical to vectorA
+    const vectorC = createTestVector(1) // Different from vectorA
+
+    // Calculate similarity between identical vectors
+    const similarityIdentical = await db.calculateSimilarity(vectorA, vectorB)
+    
+    // Calculate similarity between different vectors
+    const similarityDifferent = await db.calculateSimilarity(vectorA, vectorC)
+
+    // Identical vectors should have similarity close to 1
+    expect(similarityIdentical).toBeCloseTo(1, 1)
+    
+    // Different vectors should have lower similarity
+    expect(similarityDifferent).toBeLessThan(similarityIdentical)
+  })
+
+  it('should calculate similarity between text inputs correctly', async () => {
+    const brainy = await import('../dist/unified.js')
+
+    const db = new brainy.BrainyData()
+
+    await db.init()
+
+    // Calculate similarity between similar texts
+    const similarityHigh = await db.calculateSimilarity(
+      "Cats are furry pets", 
+      "Felines make good companions"
+    )
+    
+    // Calculate similarity between different texts
+    const similarityLow = await db.calculateSimilarity(
+      "Cats are furry pets", 
+      "Python is a programming language"
+    )
+
+    // Similar texts should have higher similarity than different texts
+    expect(similarityHigh).toBeGreaterThan(similarityLow)
+  })
 })