@soulcraft/brainy 1.5.0 → 2.0.1

package/dist/augmentations/brainyAugmentation.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Single BrainyAugmentation Interface
+ *
+ * This replaces the 7 complex interfaces with one elegant, purpose-driven design.
+ * Each augmentation knows its place and when to execute automatically.
+ *
+ * The Vision: Components that enhance Brainy's capabilities seamlessly
+ * - WAL: Adds durability to storage operations
+ * - RequestDeduplicator: Prevents duplicate concurrent requests
+ * - ConnectionPool: Optimizes cloud storage throughput
+ * - IntelligentVerbScoring: Enhances relationship analysis
+ * - StreamingPipeline: Enables unlimited data processing
+ */
+export interface BrainyAugmentation {
+    /**
+     * Unique identifier for the augmentation
+     */
+    name: string;
+    /**
+     * When this augmentation should execute
+     * - 'before': Execute before the main operation
+     * - 'after': Execute after the main operation
+     * - 'around': Wrap the main operation (like middleware)
+     * - 'replace': Replace the main operation entirely
+     */
+    timing: 'before' | 'after' | 'around' | 'replace';
+    /**
+     * Which operations this augmentation applies to
+     * Granular operation matching for precise augmentation targeting
+     */
+    operations: ('add' | 'addNoun' | 'addVerb' | 'saveNoun' | 'saveVerb' | 'updateMetadata' | 'delete' | 'deleteVerb' | 'clear' | 'get' | 'search' | 'searchText' | 'searchByNounTypes' | 'findSimilar' | 'searchWithCursor' | 'relate' | 'getConnections' | 'storage' | 'backup' | 'restore' | 'all')[];
+    /**
+     * Priority for execution order (higher numbers execute first)
+     * - 100: Critical system operations (WAL, ConnectionPool)
+     * - 50: Performance optimizations (RequestDeduplicator, Caching)
+     * - 10: Enhancement features (IntelligentVerbScoring)
+     * - 1: Optional features (Logging, Analytics)
+     */
+    priority: number;
+    /**
+     * Initialize the augmentation
+     * Called once during BrainyData initialization
+     *
+     * @param context - The BrainyData instance and storage
+     */
+    initialize(context: AugmentationContext): Promise<void>;
+    /**
+     * Execute the augmentation
+     *
+     * @param operation - The operation being performed
+     * @param params - Parameters for the operation
+     * @param next - Function to call the next augmentation or main operation
+     * @returns Result of the operation
+     */
+    execute<T = any>(operation: string, params: any, next: () => Promise<T>): Promise<T>;
+    /**
+     * Optional: Check if this augmentation should run for the given operation
+     * Return false to skip execution
+     */
+    shouldExecute?(operation: string, params: any): boolean;
+    /**
+     * Optional: Cleanup when BrainyData is destroyed
+     */
+    shutdown?(): Promise<void>;
+}
+/**
+ * Context provided to augmentations
+ */
+export interface AugmentationContext {
+    /**
+     * The BrainyData instance (for accessing methods and config)
+     */
+    brain: any;
+    /**
+     * The storage adapter
+     */
+    storage: any;
+    /**
+     * Configuration for this augmentation
+     */
+    config: any;
+    /**
+     * Logging function
+     */
+    log: (message: string, level?: 'info' | 'warn' | 'error') => void;
+}
+/**
+ * Base class for augmentations with common functionality
+ */
+export declare abstract class BaseAugmentation implements BrainyAugmentation {
+    abstract name: string;
+    abstract timing: 'before' | 'after' | 'around' | 'replace';
+    abstract operations: ('add' | 'addNoun' | 'addVerb' | 'saveNoun' | 'saveVerb' | 'updateMetadata' | 'delete' | 'deleteVerb' | 'clear' | 'get' | 'search' | 'searchText' | 'searchByNounTypes' | 'findSimilar' | 'searchWithCursor' | 'relate' | 'getConnections' | 'storage' | 'backup' | 'restore' | 'all')[];
+    abstract priority: number;
+    protected context?: AugmentationContext;
+    protected isInitialized: boolean;
+    initialize(context: AugmentationContext): Promise<void>;
+    /**
+     * Override this in subclasses for initialization logic
+     */
+    protected onInitialize(): Promise<void>;
+    abstract execute<T = any>(operation: string, params: any, next: () => Promise<T>): Promise<T>;
+    shouldExecute(operation: string, params: any): boolean;
+    shutdown(): Promise<void>;
+    /**
+     * Override this in subclasses for cleanup logic
+     */
+    protected onShutdown(): Promise<void>;
+    /**
+     * Log a message with the augmentation name
+     */
+    protected log(message: string, level?: 'info' | 'warn' | 'error'): void;
+}
+/**
+ * Registry for managing augmentations
+ */
+export declare class AugmentationRegistry {
+    private augmentations;
+    private context?;
+    /**
+     * Register an augmentation
+     */
+    register(augmentation: BrainyAugmentation): void;
+    /**
+     * Find augmentations by operation (before initialization)
+     * Used for two-phase initialization to find storage augmentations
+     */
+    findByOperation(operation: string): BrainyAugmentation | null;
+    /**
+     * Initialize all augmentations
+     */
+    initialize(context: AugmentationContext): Promise<void>;
+    /**
+     * Initialize all augmentations (alias for consistency)
+     */
+    initializeAll(context: AugmentationContext): Promise<void>;
+    /**
+     * Execute augmentations for an operation
+     */
+    execute<T = any>(operation: string, params: any, mainOperation: () => Promise<T>): Promise<T>;
+    /**
+     * Get all registered augmentations
+     */
+    getAll(): BrainyAugmentation[];
+    /**
+     * Get augmentations by name
+     */
+    get(name: string): BrainyAugmentation | undefined;
+    /**
+     * Shutdown all augmentations
+     */
+    shutdown(): Promise<void>;
+}

package/dist/augmentations/brainyAugmentation.js

@@ -0,0 +1,145 @@
+/**
+ * Single BrainyAugmentation Interface
+ *
+ * This replaces the 7 complex interfaces with one elegant, purpose-driven design.
+ * Each augmentation knows its place and when to execute automatically.
+ *
+ * The Vision: Components that enhance Brainy's capabilities seamlessly
+ * - WAL: Adds durability to storage operations
+ * - RequestDeduplicator: Prevents duplicate concurrent requests
+ * - ConnectionPool: Optimizes cloud storage throughput
+ * - IntelligentVerbScoring: Enhances relationship analysis
+ * - StreamingPipeline: Enables unlimited data processing
+ */
+/**
+ * Base class for augmentations with common functionality
+ */
+export class BaseAugmentation {
+    constructor() {
+        this.isInitialized = false;
+    }
+    async initialize(context) {
+        this.context = context;
+        this.isInitialized = true;
+        await this.onInitialize();
+    }
+    /**
+     * Override this in subclasses for initialization logic
+     */
+    async onInitialize() {
+        // Default: no-op
+    }
+    shouldExecute(operation, params) {
+        // Default: execute if operations match exactly or includes 'all'
+        return this.operations.includes('all') ||
+            this.operations.includes(operation) ||
+            this.operations.some(op => operation.includes(op));
+    }
+    async shutdown() {
+        await this.onShutdown();
+        this.isInitialized = false;
+    }
+    /**
+     * Override this in subclasses for cleanup logic
+     */
+    async onShutdown() {
+        // Default: no-op
+    }
+    /**
+     * Log a message with the augmentation name
+     */
+    log(message, level = 'info') {
+        if (this.context) {
+            this.context.log(`[${this.name}] ${message}`, level);
+        }
+    }
+}
+/**
+ * Registry for managing augmentations
+ */
+export class AugmentationRegistry {
+    constructor() {
+        this.augmentations = [];
+    }
+    /**
+     * Register an augmentation
+     */
+    register(augmentation) {
+        this.augmentations.push(augmentation);
+        // Sort by priority (highest first)
+        this.augmentations.sort((a, b) => b.priority - a.priority);
+    }
+    /**
+     * Find augmentations by operation (before initialization)
+     * Used for two-phase initialization to find storage augmentations
+     */
+    findByOperation(operation) {
+        return this.augmentations.find(aug => aug.operations.includes(operation) ||
+            aug.operations.includes('all')) || null;
+    }
+    /**
+     * Initialize all augmentations
+     */
+    async initialize(context) {
+        this.context = context;
+        for (const augmentation of this.augmentations) {
+            await augmentation.initialize(context);
+        }
+        context.log(`Initialized ${this.augmentations.length} augmentations`);
+    }
+    /**
+     * Initialize all augmentations (alias for consistency)
+     */
+    async initializeAll(context) {
+        return this.initialize(context);
+    }
+    /**
+     * Execute augmentations for an operation
+     */
+    async execute(operation, params, mainOperation) {
+        // Filter augmentations that should execute for this operation
+        const applicable = this.augmentations.filter(aug => aug.shouldExecute ? aug.shouldExecute(operation, params) :
+            aug.operations.includes('all') ||
+                aug.operations.includes(operation) ||
+                aug.operations.some(op => operation.includes(op)));
+        if (applicable.length === 0) {
+            // No augmentations, execute main operation directly
+            return mainOperation();
+        }
+        // Create a chain of augmentations
+        let index = 0;
+        const executeNext = async () => {
+            if (index >= applicable.length) {
+                // All augmentations processed, execute main operation
+                return mainOperation();
+            }
+            const augmentation = applicable[index++];
+            return augmentation.execute(operation, params, executeNext);
+        };
+        return executeNext();
+    }
+    /**
+     * Get all registered augmentations
+     */
+    getAll() {
+        return [...this.augmentations];
+    }
+    /**
+     * Get augmentations by name
+     */
+    get(name) {
+        return this.augmentations.find(aug => aug.name === name);
+    }
+    /**
+     * Shutdown all augmentations
+     */
+    async shutdown() {
+        for (const augmentation of this.augmentations) {
+            if (augmentation.shutdown) {
+                await augmentation.shutdown();
+            }
+        }
+        this.augmentations = [];
+    }
+}
+//# sourceMappingURL=brainyAugmentation.js.map

package/dist/augmentations/cacheAugmentation.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Cache Augmentation - Optional Search Result Caching
+ *
+ * Replaces the hardcoded SearchCache in BrainyData with an optional augmentation.
+ * This reduces core size and allows custom cache implementations.
+ *
+ * Zero-config: Automatically enabled with sensible defaults
+ * Can be disabled or customized via augmentation registry
+ */
+import { BaseAugmentation } from './brainyAugmentation.js';
+import { SearchCache } from '../utils/searchCache.js';
+import type { GraphNoun } from '../types/graphTypes.js';
+export interface CacheConfig {
+    maxSize?: number;
+    ttl?: number;
+    enabled?: boolean;
+    invalidateOnWrite?: boolean;
+}
+/**
+ * CacheAugmentation - Makes search caching optional and pluggable
+ *
+ * Features:
+ * - Transparent search result caching
+ * - Automatic invalidation on data changes
+ * - Memory-aware cache management
+ * - Zero-config with smart defaults
+ */
+export declare class CacheAugmentation extends BaseAugmentation {
+    readonly name = "cache";
+    readonly timing: "around";
+    operations: ("search" | "add" | "delete" | "clear" | "all")[];
+    readonly priority = 50;
+    private searchCache;
+    private config;
+    constructor(config?: CacheConfig);
+    protected onInitialize(): Promise<void>;
+    protected onShutdown(): Promise<void>;
+    /**
+     * Execute augmentation - wrap operations with caching logic
+     */
+    execute<T = any>(operation: string, params: any, next: () => Promise<T>): Promise<T>;
+    /**
+     * Handle search operation with caching
+     */
+    private handleSearch;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        enabled: boolean;
+        hits: number;
+        misses: number;
+        size: number;
+        memoryUsage: number;
+    } | {
+        memoryUsage: number;
+        hits: number;
+        misses: number;
+        evictions: number;
+        hitRate: number;
+        size: number;
+        maxSize: number;
+        enabled: boolean;
+    };
+    /**
+     * Clear the cache manually
+     */
+    clear(): void;
+    /**
+     * Update cache configuration
+     */
+    updateConfig(config: Partial<CacheConfig>): void;
+    /**
+     * Clean up expired entries
+     */
+    cleanupExpiredEntries(): number;
+    /**
+     * Invalidate cache when data changes
+     */
+    invalidateOnDataChange(operation: 'add' | 'update' | 'delete'): void;
+    /**
+     * Get cache key for a query
+     */
+    getCacheKey(query: any, options?: any): string;
+    /**
+     * Direct cache get
+     */
+    get(key: string): any;
+    /**
+     * Direct cache set
+     */
+    set(key: string, value: any): void;
+    /**
+     * Get the underlying SearchCache instance (for compatibility)
+     */
+    getSearchCache(): SearchCache<GraphNoun> | null;
+    /**
+     * Get memory usage
+     */
+    getMemoryUsage(): number;
+}
+/**
+ * Factory function for zero-config cache augmentation
+ */
+export declare function createCacheAugmentation(config?: CacheConfig): CacheAugmentation;

package/dist/augmentations/cacheAugmentation.js

@@ -0,0 +1,238 @@
+/**
+ * Cache Augmentation - Optional Search Result Caching
+ *
+ * Replaces the hardcoded SearchCache in BrainyData with an optional augmentation.
+ * This reduces core size and allows custom cache implementations.
+ *
+ * Zero-config: Automatically enabled with sensible defaults
+ * Can be disabled or customized via augmentation registry
+ */
+import { BaseAugmentation } from './brainyAugmentation.js';
+import { SearchCache } from '../utils/searchCache.js';
+/**
+ * CacheAugmentation - Makes search caching optional and pluggable
+ *
+ * Features:
+ * - Transparent search result caching
+ * - Automatic invalidation on data changes
+ * - Memory-aware cache management
+ * - Zero-config with smart defaults
+ */
+export class CacheAugmentation extends BaseAugmentation {
+    constructor(config = {}) {
+        super();
+        this.name = 'cache';
+        this.timing = 'around';
+        this.operations = ['search', 'add', 'delete', 'clear', 'all'];
+        this.priority = 50; // Mid-priority, runs after data operations
+        this.searchCache = null;
+        this.config = {
+            maxSize: 1000,
+            ttl: 300000, // 5 minutes default
+            enabled: true,
+            invalidateOnWrite: true,
+            ...config
+        };
+    }
+    async onInitialize() {
+        if (!this.config.enabled) {
+            this.log('Cache augmentation disabled by configuration');
+            return;
+        }
+        // Initialize search cache with config
+        this.searchCache = new SearchCache({
+            maxSize: this.config.maxSize,
+            maxAge: this.config.ttl, // SearchCache uses maxAge, not ttl
+            enabled: true
+        });
+        this.log(`Cache augmentation initialized (maxSize: ${this.config.maxSize}, ttl: ${this.config.ttl}ms)`);
+    }
+    async onShutdown() {
+        if (this.searchCache) {
+            this.searchCache.clear();
+            this.searchCache = null;
+        }
+        this.log('Cache augmentation shut down');
+    }
+    /**
+     * Execute augmentation - wrap operations with caching logic
+     */
+    async execute(operation, params, next) {
+        // If cache is disabled, just pass through
+        if (!this.searchCache || !this.config.enabled) {
+            return next();
+        }
+        switch (operation) {
+            case 'search':
+                return this.handleSearch(params, next);
+            case 'add':
+            case 'update':
+            case 'delete':
+                // Invalidate cache on data changes
+                if (this.config.invalidateOnWrite) {
+                    const result = await next();
+                    this.searchCache.invalidateOnDataChange(operation);
+                    this.log(`Cache invalidated due to ${operation} operation`);
+                    return result;
+                }
+                return next();
+            case 'clear':
+                // Clear cache when all data is cleared
+                const result = await next();
+                this.searchCache.clear();
+                this.log('Cache cleared due to clear operation');
+                return result;
+            default:
+                return next();
+        }
+    }
+    /**
+     * Handle search operation with caching
+     */
+    async handleSearch(params, next) {
+        if (!this.searchCache)
+            return next();
+        // Extract search parameters
+        const { query, k, options = {} } = params;
+        // Skip cache if explicitly disabled or has complex filters
+        if (options.skipCache || options.metadata) {
+            return next();
+        }
+        // Generate cache key
+        const cacheKey = this.searchCache.getCacheKey(query, k, options);
+        // Check cache
+        const cachedResult = this.searchCache.get(cacheKey);
+        if (cachedResult) {
+            this.log('Cache hit for search query');
+            // Update metrics if available
+            if (this.context?.brain) {
+                const metrics = this.context.brain.augmentations?.get('metrics');
+                if (metrics) {
+                    metrics.recordCacheHit?.();
+                }
+            }
+            return cachedResult;
+        }
+        // Execute search
+        const result = await next();
+        // Cache the result
+        this.searchCache.set(cacheKey, result);
+        this.log('Search result cached');
+        // Update metrics if available
+        if (this.context?.brain) {
+            const metrics = this.context.brain.augmentations?.get('metrics');
+            if (metrics) {
+                metrics.recordCacheMiss?.();
+            }
+        }
+        return result;
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        if (!this.searchCache) {
+            return {
+                enabled: false,
+                hits: 0,
+                misses: 0,
+                size: 0,
+                memoryUsage: 0
+            };
+        }
+        const stats = this.searchCache.getStats();
+        return {
+            ...stats,
+            memoryUsage: this.searchCache.getMemoryUsage()
+        };
+    }
+    /**
+     * Clear the cache manually
+     */
+    clear() {
+        if (this.searchCache) {
+            this.searchCache.clear();
+            this.log('Cache manually cleared');
+        }
+    }
+    /**
+     * Update cache configuration
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+        if (this.searchCache && this.config.enabled) {
+            this.searchCache.updateConfig({
+                maxSize: this.config.maxSize,
+                maxAge: this.config.ttl, // SearchCache uses maxAge
+                enabled: this.config.enabled
+            });
+            this.log('Cache configuration updated');
+        }
+    }
+    /**
+     * Clean up expired entries
+     */
+    cleanupExpiredEntries() {
+        if (!this.searchCache)
+            return 0;
+        const cleaned = this.searchCache.cleanupExpiredEntries();
+        if (cleaned > 0) {
+            this.log(`Cleaned ${cleaned} expired cache entries`);
+        }
+        return cleaned;
+    }
+    /**
+     * Invalidate cache when data changes
+     */
+    invalidateOnDataChange(operation) {
+        if (!this.searchCache)
+            return;
+        this.searchCache.invalidateOnDataChange(operation);
+        this.log(`Cache invalidated due to ${operation} operation`);
+    }
+    /**
+     * Get cache key for a query
+     */
+    getCacheKey(query, options) {
+        if (!this.searchCache)
+            return '';
+        return this.searchCache.getCacheKey(query, options);
+    }
+    /**
+     * Direct cache get
+     */
+    get(key) {
+        if (!this.searchCache)
+            return null;
+        return this.searchCache.get(key);
+    }
+    /**
+     * Direct cache set
+     */
+    set(key, value) {
+        if (!this.searchCache)
+            return;
+        this.searchCache.set(key, value);
+    }
+    /**
+     * Get the underlying SearchCache instance (for compatibility)
+     */
+    getSearchCache() {
+        return this.searchCache;
+    }
+    /**
+     * Get memory usage
+     */
+    getMemoryUsage() {
+        if (!this.searchCache)
+            return 0;
+        return this.searchCache.getMemoryUsage();
+    }
+}
+/**
+ * Factory function for zero-config cache augmentation
+ */
+export function createCacheAugmentation(config) {
+    return new CacheAugmentation(config);
+}
+//# sourceMappingURL=cacheAugmentation.js.map