From 042602776558359c8a2219fbe6886ac8dc5cd02d Mon Sep 17 00:00:00 2001
From: David Snelling <david@soulcraft.com>
Date: Tue, 18 Nov 2025 15:52:41 -0800
Subject: [PATCH] fix: add validation for empty vectors in brain.similar()

Prevents using metadata-only entities with brain.similar() when vectors
are not loaded. Provides helpful error message guiding users to either:
1. Pass entity ID: brain.similar({ to: entityId })
2. Load with vectors: brain.similar({ to: await brain.get(id, { includeVectors: true }) })

This ensures brain.similar() always has valid vectors to compute similarity.
---
 src/brainy.ts | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/src/brainy.ts b/src/brainy.ts
index e9cd27ab..482bb669 100644
--- a/src/brainy.ts
+++ b/src/brainy.ts
@@ -2006,7 +2006,16 @@ export class Brainy<T = any> implements BrainyInterface<T> {
     } else if (Array.isArray(params.to)) {
       targetVector = params.to as Vector
     } else {
-      targetVector = (params.to as Entity<T>).vector
+      // v5.11.1: Entity object passed - check if vectors are loaded
+      const entityVector = (params.to as Entity<T>).vector
+      if (!entityVector || entityVector.length === 0) {
+        throw new Error(
+          'Entity passed to brain.similar() has no vector embeddings loaded. ' +
+          'Please retrieve the entity with { includeVectors: true } or pass the entity ID instead.\n\n' +
+          'Example: brain.similar({ to: entityId }) OR brain.similar({ to: await brain.get(entityId, { includeVectors: true }) })'
+        )
+      }
+      targetVector = entityVector
     }
 
     // Use find with vector