From c13e124c71a4f741d0e9c3459361a5403f7a5597 Mon Sep 17 00:00:00 2001
From: David Snelling <david@soulcraft.com>
Date: Fri, 20 Jun 2025 12:28:21 -0700
Subject: [PATCH] **feat: add findSimilar method for entity similarity search**

### Changes:
- Introduced a `findSimilar` method in `src/brainyData.ts`:
  - Enables searching for entities similar to a given entity ID.
  - Supports options such as result limit, noun type filtering, verb inclusion, and search mode (local, remote, or combined).
  - Filters out the original entity in results and returns limited output based on the specified options.
- Updated `brainyDataInterface` in `src/types/brainyDataInterface.ts` to include the new `findSimilar` method definition.

### Purpose:
Added the `findSimilar` method to enhance entity retrieval capabilities by enabling similarity-based searches. This feature improves data exploration and provides a flexible API for building advanced search and recommendation functionalities.
---
 src/brainyData.ts                | 38 ++++++++++++++++++++++++++++++++
 src/types/brainyDataInterface.ts |  8 +++++++
 2 files changed, 46 insertions(+)

diff --git a/src/brainyData.ts b/src/brainyData.ts
index 623716c6..46a16df2 100644
--- a/src/brainyData.ts
+++ b/src/brainyData.ts
@@ -755,6 +755,44 @@ export class BrainyData<T = any> implements BrainyDataInterface<T> {
     return searchResults
   }
 
+  /**
+   * Find entities similar to a given entity ID
+   * @param id ID of the entity to find similar entities for
+   * @param options Additional options
+   * @returns Array of search results with similarity scores
+   */
+  public async findSimilar(
+    id: string,
+    options: {
+      limit?: number // Number of results to return
+      nounTypes?: string[] // Optional array of noun types to search within
+      includeVerbs?: boolean // Whether to include associated GraphVerbs in the results
+      searchMode?: 'local' | 'remote' | 'combined' // Where to search: local, remote, or both
+    } = {}
+  ): Promise<SearchResult<T>[]> {
+    await this.ensureInitialized()
+
+    // Get the entity by ID
+    const entity = await this.get(id)
+    if (!entity) {
+      throw new Error(`Entity with ID ${id} not found`)
+    }
+
+    // Use the entity's vector to search for similar entities
+    const k = (options.limit || 10) + 1 // Add 1 to account for the original entity
+    const searchResults = await this.search(entity.vector, k, {
+      forceEmbed: false,
+      nounTypes: options.nounTypes,
+      includeVerbs: options.includeVerbs,
+      searchMode: options.searchMode
+    })
+
+    // Filter out the original entity and limit to the requested number
+    return searchResults
+      .filter(result => result.id !== id)
+      .slice(0, options.limit || 10)
+  }
+
   /**
    * Get a vector by ID
    */
diff --git a/src/types/brainyDataInterface.ts b/src/types/brainyDataInterface.ts
index ef35d5df..414932d5 100644
--- a/src/types/brainyDataInterface.ts
+++ b/src/types/brainyDataInterface.ts
@@ -44,4 +44,12 @@ export interface BrainyDataInterface<T = unknown> {
    * @returns The ID of the created relationship
    */
   relate(sourceId: string, targetId: string, relationType: string, metadata?: unknown): Promise<string>
+
+  /**
+   * Find entities similar to a given entity ID
+   * @param id ID of the entity to find similar entities for
+   * @param options Additional options
+   * @returns Array of search results with similarity scores
+   */
+  findSimilar(id: string, options?: { limit?: number }): Promise<unknown[]>
 }