@soulcraft/brainy 0.48.0 → 0.49.0

package/dist/brainyData.d.ts

@@ -2,8 +2,10 @@
  * BrainyData
  * Main class that provides the vector database functionality
  */
-import { HNSWOptimizedConfig } from './hnsw/hnswIndexOptimized.js';
+import { HNSWIndex } from './hnsw/hnswIndex.js';
+import { HNSWIndexOptimized, HNSWOptimizedConfig } from './hnsw/hnswIndexOptimized.js';
 import { DistanceFunction, GraphVerb, EmbeddingFunction, HNSWConfig, SearchResult, SearchCursor, PaginatedSearchResult, StorageAdapter, Vector, VectorDocument } from './coreTypes.js';
+import { MetadataIndexManager, MetadataIndexConfig } from './utils/metadataIndex.js';
 import { NounType, VerbType } from './types/graphTypes.js';
 import { WebSocketConnection } from './types/augmentations.js';
 import { BrainyDataInterface } from './types/brainyDataInterface.js';
@@ -80,8 +82,16 @@ export interface BrainyDataConfig {
     /**
      * Set the database to read-only mode
      * When true, all write operations will throw an error
+     * Note: Statistics and index optimizations are still allowed unless frozen is also true
      */
     readOnly?: boolean;
+    /**
+     * Completely freeze the database, preventing all changes including statistics and index optimizations
+     * When true, the database is completely immutable (no data changes, no index rebalancing, no statistics updates)
+     * This is useful for forensic analysis, testing with deterministic state, or compliance scenarios
+     * Default: false (allows optimizations even in readOnly mode)
+     */
+    frozen?: boolean;
     /**
      * Enable lazy loading in read-only mode
      * When true and in read-only mode, the index is not fully loaded during initialization
@@ -123,6 +133,10 @@ export interface BrainyDataConfig {
          */
         verbose?: boolean;
     };
+    /**
+     * Metadata indexing configuration
+     */
+    metadataIndex?: MetadataIndexConfig;
     /**
      * Search result caching configuration
      * Improves performance for repeated queries
@@ -276,17 +290,20 @@ export interface BrainyDataConfig {
     };
 }
 export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
-    private index;
+    index: HNSWIndex | HNSWIndexOptimized;
     private storage;
+    metadataIndex: MetadataIndexManager | null;
     private isInitialized;
     private isInitializing;
     private embeddingFunction;
     private distanceFunction;
     private requestPersistentStorage;
     private readOnly;
+    private frozen;
     private lazyLoadInReadOnlyMode;
     private writeOnly;
     private storageConfig;
+    private config;
     private useOptimizedIndex;
     private _dimensions;
     private loggingConfig;
@@ -298,6 +315,7 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
     private cacheConfig;
     private realtimeUpdateConfig;
     private updateTimerId;
+    private maintenanceIntervals;
     private lastUpdateTime;
     private lastKnownNounCount;
     private remoteServerConfig;
@@ -331,6 +349,11 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
      * @throws Error if the database is in read-only mode
      */
     private checkReadOnly;
+    /**
+     * Check if the database is frozen and throw an error if it is
+     * @throws Error if the database is frozen
+     */
+    private checkFrozen;
     /**
      * Check if the database is in write-only mode and throw an error if it is
      * @param allowExistenceChecks If true, allows existence checks (get operations) in write-only mode
@@ -356,6 +379,10 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
      * @param config Configuration for real-time updates
      */
     enableRealtimeUpdates(config?: Partial<BrainyDataConfig['realtimeUpdates']>): void;
+    /**
+     * Start metadata index maintenance
+     */
+    private startMetadataIndexMaintenance;
     /**
      * Disable real-time updates
      */
@@ -510,6 +537,7 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
     searchByNounTypes(queryVectorOrData: Vector | any, k?: number, nounTypes?: string[] | null, options?: {
         forceEmbed?: boolean;
         service?: string;
+        metadata?: any;
         offset?: number;
     }): Promise<SearchResult<T>[]>;
     /**
@@ -533,6 +561,7 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
         filter?: {
             domain?: string;
         };
+        metadata?: any;
         offset?: number;
         skipCache?: boolean;
     }): Promise<SearchResult<T>[]>;
@@ -572,6 +601,7 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
         filter?: {
             domain?: string;
         };
+        metadata?: any;
         offset?: number;
         skipCache?: boolean;
     }): Promise<SearchResult<T>[]>;
@@ -828,6 +858,17 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
             };
         };
     }>;
+    /**
+     * List all services that have written data to the database
+     * @returns Array of service statistics
+     */
+    listServices(): Promise<import('./coreTypes.js').ServiceStatistics[]>;
+    /**
+     * Get statistics for a specific service
+     * @param service The service name to get statistics for
+     * @returns Service statistics or null if service not found
+     */
+    getServiceStatistics(service: string): Promise<import('./coreTypes.js').ServiceStatistics | null>;
     /**
      * Check if the database is in read-only mode
      * @returns True if the database is in read-only mode, false otherwise
@@ -838,6 +879,17 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
      * @param readOnly True to set the database to read-only mode, false to allow writes
      */
     setReadOnly(readOnly: boolean): void;
+    /**
+     * Check if the database is frozen (completely immutable)
+     * @returns True if the database is frozen, false otherwise
+     */
+    isFrozen(): boolean;
+    /**
+     * Set the database to frozen mode (completely immutable)
+     * When frozen, no changes are allowed including statistics updates and index optimizations
+     * @param frozen True to freeze the database, false to allow optimizations
+     */
+    setFrozen(frozen: boolean): void;
     /**
      * Check if the database is in write-only mode
      * @returns True if the database is in write-only mode, false otherwise
@@ -896,6 +948,34 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
         verbTypes?: string[];
         direction?: 'outgoing' | 'incoming' | 'both';
     }): Promise<SearchResult<T>[]>;
+    /**
+     * Get available filter values for a field
+     * Useful for building dynamic filter UIs
+     *
+     * @param field The field name to get values for
+     * @returns Array of available values for that field
+     */
+    getFilterValues(field: string): Promise<string[]>;
+    /**
+     * Get all available filter fields
+     * Useful for discovering what metadata fields are indexed
+     *
+     * @returns Array of indexed field names
+     */
+    getFilterFields(): Promise<string[]>;
+    /**
+     * Search within a specific set of items
+     * This is useful when you've pre-filtered items and want to search only within them
+     *
+     * @param queryVectorOrData Query vector or data to search for
+     * @param itemIds Array of item IDs to search within
+     * @param k Number of results to return
+     * @param options Additional options
+     * @returns Array of search results
+     */
+    searchWithinItems(queryVectorOrData: Vector | any, itemIds: string[], k?: number, options?: {
+        forceEmbed?: boolean;
+    }): Promise<SearchResult<T>[]>;
     /**
      * Search for similar documents using a text query
      * This is a convenience method that embeds the query text and performs a search
@@ -909,6 +989,7 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
         nounTypes?: string[];
         includeVerbs?: boolean;
         searchMode?: 'local' | 'remote' | 'combined';
+        metadata?: any;
     }): Promise<SearchResult<T>[]>;
     /**
      * Search a remote Brainy server for similar vectors