@soulcraft/brainy 0.38.0 → 0.39.0

package/dist/brainyData.d.ts

@@ -3,11 +3,12 @@
  * Main class that provides the vector database functionality
  */
 import { HNSWOptimizedConfig } from './hnsw/hnswIndexOptimized.js';
-import { DistanceFunction, GraphVerb, EmbeddingFunction, HNSWConfig, SearchResult, StorageAdapter, Vector, VectorDocument } from './coreTypes.js';
+import { DistanceFunction, GraphVerb, EmbeddingFunction, HNSWConfig, SearchResult, SearchCursor, PaginatedSearchResult, StorageAdapter, Vector, VectorDocument } from './coreTypes.js';
 import { NounType, VerbType } from './types/graphTypes.js';
 import { WebSocketConnection } from './types/augmentations.js';
 import { BrainyDataInterface } from './types/brainyDataInterface.js';
 import { DistributedConfig } from './types/distributedTypes.js';
+import { SearchCacheConfig } from './utils/searchCache.js';
 export interface BrainyDataConfig {
     /**
      * HNSW index configuration
@@ -122,6 +123,11 @@ export interface BrainyDataConfig {
          */
         verbose?: boolean;
     };
+    /**
+     * Search result caching configuration
+     * Improves performance for repeated queries
+     */
+    searchCache?: SearchCacheConfig;
     /**
      * Timeout configuration for async operations
      * Controls how long operations wait before timing out
@@ -285,6 +291,8 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
     private _dimensions;
     private loggingConfig;
     private defaultService;
+    private searchCache;
+    private cacheAutoConfigurator;
     private timeoutConfig;
     private retryConfig;
     private cacheConfig;
@@ -501,6 +509,7 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
     searchByNounTypes(queryVectorOrData: Vector | any, k?: number, nounTypes?: string[] | null, options?: {
         forceEmbed?: boolean;
         service?: string;
+        offset?: number;
     }): Promise<SearchResult<T>[]>;
     /**
      * Search for similar vectors
@@ -523,7 +532,28 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
         filter?: {
             domain?: string;
         };
+        offset?: number;
+        skipCache?: boolean;
     }): Promise<SearchResult<T>[]>;
+    /**
+     * Search with cursor-based pagination for better performance on large datasets
+     * @param queryVectorOrData Query vector or data to search for
+     * @param k Number of results to return
+     * @param options Additional options including cursor for pagination
+     * @returns Paginated search results with cursor for next page
+     */
+    searchWithCursor(queryVectorOrData: Vector | any, k?: number, options?: {
+        forceEmbed?: boolean;
+        nounTypes?: string[];
+        includeVerbs?: boolean;
+        service?: string;
+        searchField?: string;
+        filter?: {
+            domain?: string;
+        };
+        cursor?: SearchCursor;
+        skipCache?: boolean;
+    }): Promise<PaginatedSearchResult<T>>;
     /**
      * Search the local database for similar vectors
      * @param queryVectorOrData Query vector or data to search for
@@ -541,6 +571,8 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
         filter?: {
             domain?: string;
         };
+        offset?: number;
+        skipCache?: boolean;
     }): Promise<SearchResult<T>[]>;
     /**
      * Find entities similar to a given entity ID
@@ -715,6 +747,32 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
      * Get the number of vectors in the database
      */
     size(): number;
+    /**
+     * Get search cache statistics for performance monitoring
+     * @returns Cache statistics including hit rate and memory usage
+     */
+    getCacheStats(): {
+        search: {
+            hits: number;
+            misses: number;
+            evictions: number;
+            hitRate: number;
+            size: number;
+            maxSize: number;
+            enabled: boolean;
+        };
+        searchMemoryUsage: number;
+    };
+    /**
+     * Clear search cache manually (useful for testing or memory management)
+     */
+    clearCache(): void;
+    /**
+     * Adapt cache configuration based on current performance metrics
+     * This method analyzes usage patterns and automatically optimizes cache settings
+     * @private
+     */
+    private adaptCacheConfiguration;
     /**
      * Get the number of nouns in the database (excluding verbs)
      * This is used for statistics reporting to match the expected behavior in tests
@@ -861,6 +919,7 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
         storeResults?: boolean;
         service?: string;
         searchField?: string;
+        offset?: number;
     }): Promise<SearchResult<T>[]>;
     /**
      * Search both local and remote Brainy instances, combining the results
@@ -876,6 +935,7 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
         localFirst?: boolean;
         service?: string;
         searchField?: string;
+        offset?: number;
     }): Promise<SearchResult<T>[]>;
     /**
      * Check if the instance is connected to a remote server

package/dist/coreTypes.d.ts

@@ -22,6 +22,23 @@ export interface SearchResult<T = any> {
     vector: Vector;
     metadata?: T;
 }
+/**
+ * Cursor for pagination through search results
+ */
+export interface SearchCursor {
+    lastId: string;
+    lastScore: number;
+    position: number;
+}
+/**
+ * Paginated search result with cursor support
+ */
+export interface PaginatedSearchResult<T = any> {
+    results: SearchResult<T>[];
+    cursor?: SearchCursor;
+    hasMore: boolean;
+    totalEstimate?: number;
+}
 /**
  * Distance function for comparing vectors
  */