@soulcraft/brainy 0.38.0 → 0.40.0

package/dist/utils/cacheAutoConfig.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Intelligent cache auto-configuration system
+ * Adapts cache settings based on environment, usage patterns, and storage type
+ */
+import { SearchCacheConfig } from './searchCache.js';
+import { BrainyDataConfig } from '../brainyData.js';
+export interface CacheUsageStats {
+    totalQueries: number;
+    repeatQueries: number;
+    avgQueryTime: number;
+    memoryPressure: number;
+    storageType: 'memory' | 'opfs' | 's3' | 'filesystem';
+    isDistributed: boolean;
+    changeFrequency: number;
+    readWriteRatio: number;
+}
+export interface AutoConfigResult {
+    cacheConfig: SearchCacheConfig;
+    realtimeConfig: NonNullable<BrainyDataConfig['realtimeUpdates']>;
+    reasoning: string[];
+}
+export declare class CacheAutoConfigurator {
+    private stats;
+    private configHistory;
+    private lastOptimization;
+    /**
+     * Auto-detect optimal cache configuration based on current conditions
+     */
+    autoDetectOptimalConfig(storageConfig?: BrainyDataConfig['storage'], currentStats?: Partial<CacheUsageStats>): AutoConfigResult;
+    /**
+     * Dynamically adjust configuration based on runtime performance
+     */
+    adaptConfiguration(currentConfig: SearchCacheConfig, performanceMetrics: {
+        hitRate: number;
+        avgResponseTime: number;
+        memoryUsage: number;
+        externalChangesDetected: number;
+        timeSinceLastChange: number;
+    }): AutoConfigResult | null;
+    /**
+     * Get recommended configuration for specific use case
+     */
+    getRecommendedConfig(useCase: 'high-consistency' | 'balanced' | 'performance-first'): AutoConfigResult;
+    /**
+     * Learn from usage patterns and improve recommendations
+     */
+    learnFromUsage(usageData: {
+        queryPatterns: string[];
+        responseTime: number;
+        cacheHits: number;
+        totalQueries: number;
+        dataChanges: number;
+        timeWindow: number;
+    }): void;
+    private detectEnvironment;
+    private generateOptimalConfig;
+    private calculateRealtimeConfig;
+    private detectMemoryConstraints;
+    /**
+     * Get human-readable explanation of current configuration
+     */
+    getConfigExplanation(config: AutoConfigResult): string;
+}

package/dist/utils/cacheAutoConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cacheAutoConfig.d.ts","sourceRoot":"","sources":["../../src/utils/cacheAutoConfig.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAEnD,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB,cAAc,EAAE,MAAM,CAAA;IACtB,WAAW,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,GAAG,YAAY,CAAA;IACpD,aAAa,EAAE,OAAO,CAAA;IACtB,eAAe,EAAE,MAAM,CAAA;IACvB,cAAc,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,iBAAiB,CAAA;IAC9B,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAAC,iBAAiB,CAAC,CAAC,CAAA;IAChE,SAAS,EAAE,MAAM,EAAE,CAAA;CACpB;AAED,qBAAa,qBAAqB;IAChC,OAAO,CAAC,KAAK,CASZ;IAED,OAAO,CAAC,aAAa,CAAyB;IAC9C,OAAO,CAAC,gBAAgB,CAAI;IAE5B;;OAEG;IACI,uBAAuB,CAC5B,aAAa,CAAC,EAAE,gBAAgB,CAAC,SAAS,CAAC,EAC3C,YAAY,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GACtC,gBAAgB;IAmBnB;;OAEG;IACI,kBAAkB,CACvB,aAAa,EAAE,iBAAiB,EAChC,kBAAkB,EAAE;QAClB,OAAO,EAAE,MAAM,CAAA;QACf,eAAe,EAAE,MAAM,CAAA;QACvB,WAAW,EAAE,MAAM,CAAA;QACnB,uBAAuB,EAAE,MAAM,CAAA;QAC/B,mBAAmB,EAAE,MAAM,CAAA;KAC5B,GACA,gBAAgB,GAAG,IAAI;IAgE1B;;OAEG;IACI,oBAAoB,CAAC,OAAO,EAAE,kBAAkB,GAAG,UAAU,GAAG,mBAAmB,GAAG,gBAAgB;IAkC7G;;OAEG;IACI,cAAc,CAAC,SAAS,EAAE;QAC/B,aAAa,EAAE,MAAM,EAAE,CAAA;QACvB,YAAY,EAAE,MAAM,CAAA;QACpB,SAAS,EAAE,MAAM,CAAA;QACjB,YAAY,EAAE,MAAM,CAAA;QACpB,WAAW,EAAE,MAAM,CAAA;QACnB,UAAU,EAAE,MAAM,CAAA;KACnB,GAAG,IAAI;IAaR,OAAO,CAAC,iBAAiB;IAmBzB,OAAO,CAAC,qBAAqB;IAkE7B,OAAO,CAAC,uBAAuB;IAS/B,OAAO,CAAC,uBAAuB;IAe/B;;OAEG;IACI,oBAAoB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM;CAgB9D"}

package/dist/utils/searchCache.d.ts

@@ -0,0 +1,93 @@
+/**
+ * SearchCache - Caches search results for improved performance
+ */
+import { SearchResult } from '../coreTypes.js';
+export interface CacheEntry<T = any> {
+    results: SearchResult<T>[];
+    timestamp: number;
+    hits: number;
+}
+export interface SearchCacheConfig {
+    maxAge?: number;
+    maxSize?: number;
+    enabled?: boolean;
+    hitCountWeight?: number;
+}
+export declare class SearchCache<T = any> {
+    private cache;
+    private maxAge;
+    private maxSize;
+    private enabled;
+    private hitCountWeight;
+    private hits;
+    private misses;
+    private evictions;
+    constructor(config?: SearchCacheConfig);
+    /**
+     * Generate cache key from search parameters
+     */
+    getCacheKey(query: any, k: number, options?: Record<string, any>): string;
+    /**
+     * Get cached results if available and not expired
+     */
+    get(key: string): SearchResult<T>[] | null;
+    /**
+     * Cache search results
+     */
+    set(key: string, results: SearchResult<T>[]): void;
+    /**
+     * Evict the oldest entry based on timestamp and hit count
+     */
+    private evictOldest;
+    /**
+     * Clear all cached results
+     */
+    clear(): void;
+    /**
+     * Invalidate cache entries that might be affected by data changes
+     */
+    invalidate(pattern?: string | RegExp): void;
+    /**
+     * Smart invalidation for real-time data updates
+     * Only clears cache if it's getting stale or if data changes significantly
+     */
+    invalidateOnDataChange(changeType?: 'add' | 'update' | 'delete'): void;
+    /**
+     * Check if cache entries have expired and remove them
+     * This is especially important in distributed scenarios where
+     * real-time updates might be delayed or missed
+     */
+    cleanupExpiredEntries(): number;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        hits: number;
+        misses: number;
+        evictions: number;
+        hitRate: number;
+        size: number;
+        maxSize: number;
+        enabled: boolean;
+    };
+    /**
+     * Enable or disable caching
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Get memory usage estimate in bytes
+     */
+    getMemoryUsage(): number;
+    /**
+     * Get current cache configuration
+     */
+    getConfig(): SearchCacheConfig;
+    /**
+     * Update cache configuration dynamically
+     */
+    updateConfig(newConfig: Partial<SearchCacheConfig>): void;
+    /**
+     * Evict entries if cache exceeds maxSize
+     */
+    private evictIfNeeded;
+}

package/dist/utils/searchCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"searchCache.d.ts","sourceRoot":"","sources":["../../src/utils/searchCache.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAE9C,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,GAAG;IACjC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,CAAA;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,qBAAa,WAAW,CAAC,CAAC,GAAG,GAAG;IAC9B,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,cAAc,CAAQ;IAG9B,OAAO,CAAC,IAAI,CAAI;IAChB,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,SAAS,CAAI;gBAET,MAAM,GAAE,iBAAsB;IAO1C;;OAEG;IACH,WAAW,CACT,KAAK,EAAE,GAAG,EACV,CAAC,EAAE,MAAM,EACT,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,GAChC,MAAM;IAkBT;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI;IAsB1C;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI;IAelD;;OAEG;IACH,OAAO,CAAC,WAAW;IAwBnB;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb;;OAEG;IACH,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAqB3C;;;OAGG;IACH,sBAAsB,CAAC,UAAU,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,IAAI;IAOtE;;;;OAIG;IACH,qBAAqB,IAAI,MAAM;IAc/B;;OAEG;IACH,QAAQ;;;;;;;;;IAaR;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAOlC;;OAEG;IACH,cAAc,IAAI,MAAM;IAexB;;OAEG;IACH,SAAS,IAAI,iBAAiB;IAS9B;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,IAAI;IAmBzD;;OAEG;IACH,OAAO,CAAC,aAAa;CA6BtB"}

package/dist/utils/statisticsCollector.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Lightweight statistics collector for Brainy
+ * Designed to have minimal performance impact even with millions of entries
+ */
+import { StatisticsData } from '../coreTypes.js';
+export declare class StatisticsCollector {
+    private contentTypes;
+    private oldestTimestamp;
+    private newestTimestamp;
+    private updateTimestamps;
+    private searchMetrics;
+    private verbTypes;
+    private storageSizeCache;
+    private readonly MAX_TIMESTAMPS;
+    private readonly MAX_SEARCH_TERMS;
+    private readonly SIZE_UPDATE_INTERVAL;
+    /**
+     * Track content type (very lightweight)
+     */
+    trackContentType(type: string): void;
+    /**
+     * Track data update timestamp (lightweight)
+     */
+    trackUpdate(timestamp?: number): void;
+    /**
+     * Track search performance (lightweight)
+     */
+    trackSearch(searchTerm: string, durationMs: number): void;
+    /**
+     * Track verb type (lightweight)
+     */
+    trackVerbType(type: string): void;
+    /**
+     * Update storage size estimates (called periodically, not on every operation)
+     */
+    updateStorageSizes(sizes: {
+        nouns: number;
+        verbs: number;
+        metadata: number;
+        index: number;
+    }): void;
+    /**
+     * Get comprehensive statistics
+     */
+    getStatistics(): Partial<StatisticsData>;
+    /**
+     * Merge statistics from storage (for distributed systems)
+     */
+    mergeFromStorage(stored: Partial<StatisticsData>): void;
+    /**
+     * Reset statistics (for testing)
+     */
+    reset(): void;
+    private pruneSearchTerms;
+}

package/dist/utils/statisticsCollector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statisticsCollector.d.ts","sourceRoot":"","sources":["../../src/utils/statisticsCollector.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAOhD,qBAAa,mBAAmB;IAE9B,OAAO,CAAC,YAAY,CAAiC;IAGrD,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,gBAAgB,CAAuB;IAG/C,OAAO,CAAC,aAAa,CAKpB;IAGD,OAAO,CAAC,SAAS,CAAiC;IAGlD,OAAO,CAAC,gBAAgB,CAQvB;IAED,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAO;IACtC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAM;IACvC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAQ;IAE7C;;OAEG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIpC;;OAEG;IACH,WAAW,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IAgBrC;;OAEG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAyBzD;;OAEG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIjC;;OAEG;IACH,kBAAkB,CAAC,KAAK,EAAE;QACxB,KAAK,EAAE,MAAM,CAAA;QACb,KAAK,EAAE,MAAM,CAAA;QACb,QAAQ,EAAE,MAAM,CAAA;QAChB,KAAK,EAAE,MAAM,CAAA;KACd,GAAG,IAAI;IAOR;;OAEG;IACH,aAAa,IAAI,OAAO,CAAC,cAAc,CAAC;IAmFxC;;OAEG;IACH,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI;IA4BvD;;OAEG;IACH,KAAK,IAAI,IAAI;IAcb,OAAO,CAAC,gBAAgB;CAWzB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "A vector graph database using HNSW indexing with Origin Private File System storage",
   "main": "dist/unified.js",
   "module": "dist/unified.js",