@soulcraft/brainy 3.20.1 → 3.20.3

package/dist/scripts/precomputePatternEmbeddings.js

@@ -1,100 +0,0 @@
-#!/usr/bin/env node
-/**
- * 🧠 Pre-compute Pattern Embeddings Script
- *
- * This script pre-computes embeddings for all patterns and saves them to disk.
- * Run this once after adding new patterns to avoid runtime embedding costs.
- *
- * How it works:
- * 1. Load all patterns from library.json
- * 2. Use Brainy's embedding model to encode each pattern's examples
- * 3. Average the example embeddings to get a robust pattern representation
- * 4. Save embeddings to patterns/embeddings.bin for instant loading
- *
- * Benefits:
- * - Pattern matching becomes pure math (cosine similarity)
- * - No embedding model calls during query processing
- * - Patterns load instantly with pre-computed vectors
- */
-import { BrainyData } from '../brainyData.js';
-import patternData from '../patterns/library.json' assert { type: 'json' };
-import * as fs from 'fs/promises';
-import * as path from 'path';
-async function precomputeEmbeddings() {
-    console.log('🧠 Pre-computing pattern embeddings...');
-    // Initialize Brainy with minimal config
-    const brain = new BrainyData({
-        storage: { forceMemoryStorage: true },
-        logging: { verbose: false }
-    });
-    await brain.init();
-    console.log('✅ Brainy initialized');
-    const embeddings = {};
-    let processedCount = 0;
-    const totalPatterns = patternData.patterns.length;
-    for (const pattern of patternData.patterns) {
-        console.log(`\n📝 Processing pattern: ${pattern.id} (${++processedCount}/${totalPatterns})`);
-        console.log(`   Category: ${pattern.category}`);
-        console.log(`   Examples: ${pattern.examples.length}`);
-        // Embed all examples
-        const exampleEmbeddings = [];
-        for (const example of pattern.examples) {
-            try {
-                const embedding = await brain.embed(example);
-                exampleEmbeddings.push(embedding);
-                console.log(`   ✓ Embedded: "${example.substring(0, 50)}..."`);
-            }
-            catch (error) {
-                console.error(`   ✗ Failed to embed: "${example}"`, error);
-            }
-        }
-        if (exampleEmbeddings.length === 0) {
-            console.warn(`   ⚠️ No embeddings generated for pattern ${pattern.id}`);
-            continue;
-        }
-        // Average the embeddings for a robust representation
-        const avgEmbedding = averageVectors(exampleEmbeddings);
-        embeddings[pattern.id] = {
-            patternId: pattern.id,
-            embedding: avgEmbedding,
-            examples: pattern.examples,
-            averageMethod: 'arithmetic_mean'
-        };
-        console.log(`   ✅ Generated ${avgEmbedding.length}-dimensional embedding`);
-    }
-    // Save embeddings to file
-    const outputPath = path.join(process.cwd(), 'src', 'patterns', 'embeddings.json');
-    await fs.writeFile(outputPath, JSON.stringify(embeddings, null, 2));
-    console.log(`\n✅ Saved ${Object.keys(embeddings).length} pattern embeddings to ${outputPath}`);
-    // Calculate storage size
-    const stats = await fs.stat(outputPath);
-    console.log(`📊 File size: ${(stats.size / 1024).toFixed(2)} KB`);
-    // Print statistics
-    console.log('\n📈 Embedding Statistics:');
-    console.log(`   Total patterns: ${totalPatterns}`);
-    console.log(`   Successfully embedded: ${Object.keys(embeddings).length}`);
-    console.log(`   Failed: ${totalPatterns - Object.keys(embeddings).length}`);
-    console.log(`   Embedding dimensions: ${Object.values(embeddings)[0]?.embedding.length || 0}`);
-    await brain.close();
-    console.log('\n✅ Complete!');
-}
-function averageVectors(vectors) {
-    if (vectors.length === 0)
-        return [];
-    const dim = vectors[0].length;
-    const avg = new Array(dim).fill(0);
-    // Sum all vectors
-    for (const vec of vectors) {
-        for (let i = 0; i < dim; i++) {
-            avg[i] += vec[i];
-        }
-    }
-    // Divide by count to get average
-    for (let i = 0; i < dim; i++) {
-        avg[i] /= vectors.length;
-    }
-    return avg;
-}
-// Run the script
-precomputeEmbeddings().catch(console.error);
-//# sourceMappingURL=precomputePatternEmbeddings.js.map

package/dist/utils/cacheAutoConfig.d.ts

@@ -1,63 +0,0 @@
-/**
- * Intelligent cache auto-configuration system
- * Adapts cache settings based on environment, usage patterns, and storage type
- */
-import { SearchCacheConfig } from './searchCache.js';
-import { BrainyConfig } from '../brainy.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<BrainyConfig['realtimeUpdates']>;
-    reasoning: string[];
-}
-export declare class CacheAutoConfigurator {
-    private stats;
-    private configHistory;
-    private lastOptimization;
-    /**
-     * Auto-detect optimal cache configuration based on current conditions
-     */
-    autoDetectOptimalConfig(storageConfig?: BrainyConfig['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.js

@@ -1,261 +0,0 @@
-/**
- * Intelligent cache auto-configuration system
- * Adapts cache settings based on environment, usage patterns, and storage type
- */
-export class CacheAutoConfigurator {
-    constructor() {
-        this.stats = {
-            totalQueries: 0,
-            repeatQueries: 0,
-            avgQueryTime: 50,
-            memoryPressure: 0,
-            storageType: 'memory',
-            isDistributed: false,
-            changeFrequency: 0,
-            readWriteRatio: 10,
-        };
-        this.configHistory = [];
-        this.lastOptimization = 0;
-    }
-    /**
-     * Auto-detect optimal cache configuration based on current conditions
-     */
-    autoDetectOptimalConfig(storageConfig, currentStats) {
-        // Update stats with current information
-        if (currentStats) {
-            this.stats = { ...this.stats, ...currentStats };
-        }
-        // Detect environment characteristics
-        this.detectEnvironment(storageConfig);
-        // Generate optimal configuration
-        const result = this.generateOptimalConfig();
-        // Store for learning
-        this.configHistory.push(result);
-        this.lastOptimization = Date.now();
-        return result;
-    }
-    /**
-     * Dynamically adjust configuration based on runtime performance
-     */
-    adaptConfiguration(currentConfig, performanceMetrics) {
-        const reasoning = [];
-        let needsUpdate = false;
-        // Check if we should update (don't over-optimize)
-        if (Date.now() - this.lastOptimization < 60000) {
-            return null; // Wait at least 1 minute between optimizations
-        }
-        // Analyze performance patterns
-        const adaptations = {};
-        // Low hit rate → adjust cache size or TTL
-        if (performanceMetrics.hitRate < 0.3) {
-            if (performanceMetrics.externalChangesDetected > 5) {
-                // Too many external changes → shorter TTL
-                adaptations.maxAge = Math.max(60000, currentConfig.maxAge * 0.7);
-                reasoning.push('Reduced cache TTL due to frequent external changes');
-                needsUpdate = true;
-            }
-            else {
-                // Expand cache size for better hit rate
-                adaptations.maxSize = Math.min(500, (currentConfig.maxSize || 100) * 1.5);
-                reasoning.push('Increased cache size due to low hit rate');
-                needsUpdate = true;
-            }
-        }
-        // High hit rate but slow responses → might need cache warming
-        if (performanceMetrics.hitRate > 0.8 && performanceMetrics.avgResponseTime > 100) {
-            reasoning.push('High hit rate but slow responses - consider cache warming');
-        }
-        // Memory pressure → reduce cache size
-        if (performanceMetrics.memoryUsage > 100 * 1024 * 1024) { // 100MB
-            adaptations.maxSize = Math.max(20, (currentConfig.maxSize || 100) * 0.7);
-            reasoning.push('Reduced cache size due to memory pressure');
-            needsUpdate = true;
-        }
-        // Recent external changes → adaptive TTL
-        if (performanceMetrics.timeSinceLastChange < 30000) { // 30 seconds
-            adaptations.maxAge = Math.max(30000, currentConfig.maxAge * 0.8);
-            reasoning.push('Shortened TTL due to recent external changes');
-            needsUpdate = true;
-        }
-        if (!needsUpdate) {
-            return null;
-        }
-        const newCacheConfig = {
-            ...currentConfig,
-            ...adaptations
-        };
-        const newRealtimeConfig = this.calculateRealtimeConfig();
-        return {
-            cacheConfig: newCacheConfig,
-            realtimeConfig: newRealtimeConfig,
-            reasoning
-        };
-    }
-    /**
-     * Get recommended configuration for specific use case
-     */
-    getRecommendedConfig(useCase) {
-        const configs = {
-            'high-consistency': {
-                cache: { maxAge: 120000, maxSize: 50 },
-                realtime: { interval: 15000, enabled: true },
-                reasoning: ['Optimized for data consistency and real-time updates']
-            },
-            'balanced': {
-                cache: { maxAge: 300000, maxSize: 100 },
-                realtime: { interval: 30000, enabled: true },
-                reasoning: ['Balanced performance and consistency']
-            },
-            'performance-first': {
-                cache: { maxAge: 600000, maxSize: 200 },
-                realtime: { interval: 60000, enabled: true },
-                reasoning: ['Optimized for maximum cache performance']
-            }
-        };
-        const config = configs[useCase];
-        return {
-            cacheConfig: {
-                enabled: true,
-                ...config.cache
-            },
-            realtimeConfig: {
-                updateIndex: true,
-                updateStatistics: true,
-                ...config.realtime
-            },
-            reasoning: config.reasoning
-        };
-    }
-    /**
-     * Learn from usage patterns and improve recommendations
-     */
-    learnFromUsage(usageData) {
-        // Update internal stats for better future recommendations
-        this.stats.totalQueries += usageData.totalQueries;
-        this.stats.repeatQueries += usageData.cacheHits;
-        this.stats.avgQueryTime = (this.stats.avgQueryTime + usageData.responseTime) / 2;
-        this.stats.changeFrequency = usageData.dataChanges / (usageData.timeWindow / 60000);
-        // Calculate read/write ratio
-        const writes = usageData.dataChanges;
-        const reads = usageData.totalQueries;
-        this.stats.readWriteRatio = reads > 0 ? reads / Math.max(writes, 1) : 10;
-    }
-    detectEnvironment(storageConfig) {
-        // Detect storage type
-        if (storageConfig?.s3Storage || storageConfig?.customS3Storage) {
-            this.stats.storageType = 's3';
-            this.stats.isDistributed = true;
-        }
-        else if (storageConfig?.forceFileSystemStorage) {
-            this.stats.storageType = 'filesystem';
-        }
-        else if (storageConfig?.forceMemoryStorage) {
-            this.stats.storageType = 'memory';
-        }
-        else {
-            // Auto-detect browser vs Node.js
-            this.stats.storageType = typeof window !== 'undefined' ? 'opfs' : 'filesystem';
-        }
-        // Detect distributed mode indicators
-        this.stats.isDistributed = this.stats.isDistributed ||
-            Boolean(storageConfig?.s3Storage || storageConfig?.customS3Storage);
-    }
-    generateOptimalConfig() {
-        const reasoning = [];
-        // Base configuration
-        let cacheConfig = {
-            enabled: true,
-            maxSize: 100,
-            maxAge: 300000, // 5 minutes
-            hitCountWeight: 0.3
-        };
-        let realtimeConfig = {
-            enabled: false,
-            interval: 60000,
-            updateIndex: true,
-            updateStatistics: true
-        };
-        // Adjust for storage type
-        if (this.stats.storageType === 's3' || this.stats.isDistributed) {
-            cacheConfig.maxAge = 180000; // 3 minutes for distributed
-            realtimeConfig.enabled = true;
-            realtimeConfig.interval = 30000; // 30 seconds
-            reasoning.push('Distributed storage detected - enabled real-time updates');
-            reasoning.push('Reduced cache TTL for distributed consistency');
-        }
-        // Adjust for read/write patterns
-        if (this.stats.readWriteRatio > 20) {
-            // Read-heavy workload
-            cacheConfig.maxSize = Math.min(300, (cacheConfig.maxSize || 100) * 2);
-            cacheConfig.maxAge = Math.min(900000, (cacheConfig.maxAge || 300000) * 1.5); // Up to 15 minutes
-            reasoning.push('Read-heavy workload detected - increased cache size and TTL');
-        }
-        else if (this.stats.readWriteRatio < 5) {
-            // Write-heavy workload
-            cacheConfig.maxSize = Math.max(50, (cacheConfig.maxSize || 100) * 0.7);
-            cacheConfig.maxAge = Math.max(60000, (cacheConfig.maxAge || 300000) * 0.6);
-            reasoning.push('Write-heavy workload detected - reduced cache size and TTL');
-        }
-        // Adjust for change frequency
-        if (this.stats.changeFrequency > 10) { // More than 10 changes per minute
-            realtimeConfig.interval = Math.max(10000, realtimeConfig.interval * 0.5);
-            cacheConfig.maxAge = Math.max(30000, (cacheConfig.maxAge || 300000) * 0.5);
-            reasoning.push('High change frequency detected - increased update frequency');
-        }
-        // Memory constraints
-        if (this.detectMemoryConstraints()) {
-            cacheConfig.maxSize = Math.max(20, (cacheConfig.maxSize || 100) * 0.6);
-            reasoning.push('Memory constraints detected - reduced cache size');
-        }
-        // Performance optimization
-        if (this.stats.avgQueryTime > 200) {
-            cacheConfig.maxSize = Math.min(500, (cacheConfig.maxSize || 100) * 1.5);
-            reasoning.push('Slow queries detected - increased cache size');
-        }
-        return {
-            cacheConfig,
-            realtimeConfig,
-            reasoning
-        };
-    }
-    calculateRealtimeConfig() {
-        return {
-            enabled: this.stats.isDistributed || this.stats.changeFrequency > 1,
-            interval: this.stats.isDistributed ? 30000 : 60000,
-            updateIndex: true,
-            updateStatistics: true
-        };
-    }
-    detectMemoryConstraints() {
-        // Simple heuristic for memory constraints
-        try {
-            if (typeof performance !== 'undefined' && 'memory' in performance) {
-                const memInfo = performance.memory;
-                return memInfo.usedJSHeapSize > memInfo.jsHeapSizeLimit * 0.8;
-            }
-        }
-        catch (e) {
-            // Ignore errors
-        }
-        // Default assumption for constrained environments
-        return false;
-    }
-    /**
-     * Get human-readable explanation of current configuration
-     */
-    getConfigExplanation(config) {
-        const lines = [
-            '🤖 Brainy Auto-Configuration:',
-            '',
-            `📊 Cache: ${config.cacheConfig.maxSize} queries, ${config.cacheConfig.maxAge / 1000}s TTL`,
-            `🔄 Updates: ${config.realtimeConfig.enabled ? `Every ${(config.realtimeConfig.interval || 30000) / 1000}s` : 'Disabled'}`,
-            '',
-            '🎯 Optimizations applied:'
-        ];
-        config.reasoning.forEach(reason => {
-            lines.push(`  • ${reason}`);
-        });
-        return lines.join('\n');
-    }
-}
-//# sourceMappingURL=cacheAutoConfig.js.map

package/dist/utils/hybridModelManager.d.ts

@@ -1,64 +0,0 @@
-/**
- * Hybrid Model Manager - BEST OF BOTH WORLDS
- *
- * NOW A WRAPPER AROUND SingletonModelManager
- * Maintained for backward compatibility
- *
- * Previously combined:
- * 1. Multi-source downloading strategy (GitHub → CDN → Hugging Face)
- * 2. Singleton pattern preventing multiple ONNX model loads
- * 3. Environment-specific optimizations
- * 4. Graceful fallbacks and error handling
- *
- * Now delegates all operations to SingletonModelManager for true unification
- */
-import { EmbeddingFunction } from '../coreTypes.js';
-/**
- * HybridModelManager - Now a wrapper around SingletonModelManager
- * Maintained for backward compatibility
- */
-declare class HybridModelManager {
-    private static instance;
-    private constructor();
-    static getInstance(): HybridModelManager;
-    /**
-     * Get the primary embedding model - delegates to SingletonModelManager
-     */
-    getPrimaryModel(): Promise<any>;
-    /**
-     * Get embedding function - delegates to SingletonModelManager
-     */
-    getEmbeddingFunction(): Promise<EmbeddingFunction>;
-    /**
-     * Check if model is ready - delegates to SingletonModelManager
-     */
-    isModelReady(): boolean;
-    /**
-     * Force model reload - not supported with SingletonModelManager
-     */
-    reloadModel(): Promise<void>;
-    /**
-     * Get model status - delegates to SingletonModelManager
-     */
-    getModelStatus(): {
-        loaded: boolean;
-        ready: boolean;
-        modelType: string;
-    };
-}
-export declare const hybridModelManager: HybridModelManager;
-/**
- * Get the hybrid singleton embedding function - Now delegates to SingletonModelManager
- * Maintained for backward compatibility
- */
-export declare function getHybridEmbeddingFunction(): Promise<EmbeddingFunction>;
-/**
- * Hybrid embedding function - Now delegates to SingletonModelManager
- * Maintained for backward compatibility
- */
-export declare const hybridEmbeddingFunction: EmbeddingFunction;
-/**
- * Preload model for tests or production - Now delegates to SingletonModelManager
- */
-export declare function preloadHybridModel(): Promise<void>;
-export {};

package/dist/utils/hybridModelManager.js

@@ -1,95 +0,0 @@
-/**
- * Hybrid Model Manager - BEST OF BOTH WORLDS
- *
- * NOW A WRAPPER AROUND SingletonModelManager
- * Maintained for backward compatibility
- *
- * Previously combined:
- * 1. Multi-source downloading strategy (GitHub → CDN → Hugging Face)
- * 2. Singleton pattern preventing multiple ONNX model loads
- * 3. Environment-specific optimizations
- * 4. Graceful fallbacks and error handling
- *
- * Now delegates all operations to SingletonModelManager for true unification
- */
-import { singletonModelManager, getUnifiedEmbeddingFunction } from '../embeddings/SingletonModelManager.js';
-/**
- * HybridModelManager - Now a wrapper around SingletonModelManager
- * Maintained for backward compatibility
- */
-class HybridModelManager {
-    constructor() {
-        console.log('🔄 HybridModelManager now delegates to SingletonModelManager');
-    }
-    static getInstance() {
-        if (!HybridModelManager.instance) {
-            HybridModelManager.instance = new HybridModelManager();
-        }
-        return HybridModelManager.instance;
-    }
-    /**
-     * Get the primary embedding model - delegates to SingletonModelManager
-     */
-    async getPrimaryModel() {
-        // Delegate to SingletonModelManager
-        return await singletonModelManager.getModel();
-    }
-    /**
-     * Get embedding function - delegates to SingletonModelManager
-     */
-    async getEmbeddingFunction() {
-        return await getUnifiedEmbeddingFunction();
-    }
-    /**
-     * Check if model is ready - delegates to SingletonModelManager
-     */
-    isModelReady() {
-        return singletonModelManager.isInitialized();
-    }
-    /**
-     * Force model reload - not supported with SingletonModelManager
-     */
-    async reloadModel() {
-        console.warn('⚠️ Model reload not supported with SingletonModelManager');
-        console.log('ℹ️ Singleton model persists for consistency');
-        // Just ensure model is initialized
-        await this.getPrimaryModel();
-    }
-    /**
-     * Get model status - delegates to SingletonModelManager
-     */
-    getModelStatus() {
-        const isReady = singletonModelManager.isInitialized();
-        return {
-            loaded: isReady,
-            ready: isReady,
-            modelType: 'SingletonModelManager (Unified model instance)'
-        };
-    }
-}
-HybridModelManager.instance = null;
-// Export singleton instance
-export const hybridModelManager = HybridModelManager.getInstance();
-/**
- * Get the hybrid singleton embedding function - Now delegates to SingletonModelManager
- * Maintained for backward compatibility
- */
-export async function getHybridEmbeddingFunction() {
-    return await getUnifiedEmbeddingFunction();
-}
-/**
- * Hybrid embedding function - Now delegates to SingletonModelManager
- * Maintained for backward compatibility
- */
-export const hybridEmbeddingFunction = async (data) => {
-    return await singletonModelManager.embed(data);
-};
-/**
- * Preload model for tests or production - Now delegates to SingletonModelManager
- */
-export async function preloadHybridModel() {
-    console.log('🚀 Preloading model via SingletonModelManager...');
-    await singletonModelManager.getModel();
-    console.log('✅ Singleton model preloaded and ready!');
-}
-//# sourceMappingURL=hybridModelManager.js.map

package/dist/utils/statistics.d.ts

@@ -1,28 +0,0 @@
-/**
- * Utility functions for retrieving statistics from Brainy
- */
-import { Brainy } from '../brainy.js';
-/**
- * Get statistics about the current state of a Brainy instance
- * This function provides access to statistics at the root level of the library
- *
- * @param instance A Brainy instance to get statistics from
- * @param options Additional options for retrieving statistics
- * @returns Object containing counts of nouns, verbs, metadata entries, and HNSW index size
- * @throws Error if the instance is not provided or if statistics retrieval fails
- */
-export declare function getStatistics(instance: Brainy, options?: {
-    service?: string | string[];
-}): Promise<{
-    nounCount: number;
-    verbCount: number;
-    metadataCount: number;
-    hnswIndexSize: number;
-    serviceBreakdown?: {
-        [service: string]: {
-            nounCount: number;
-            verbCount: number;
-            metadataCount: number;
-        };
-    };
-}>;

package/dist/utils/statistics.js

@@ -1,25 +0,0 @@
-/**
- * Utility functions for retrieving statistics from Brainy
- */
-/**
- * Get statistics about the current state of a Brainy instance
- * This function provides access to statistics at the root level of the library
- *
- * @param instance A Brainy instance to get statistics from
- * @param options Additional options for retrieving statistics
- * @returns Object containing counts of nouns, verbs, metadata entries, and HNSW index size
- * @throws Error if the instance is not provided or if statistics retrieval fails
- */
-export async function getStatistics(instance, options = {}) {
-    if (!instance) {
-        throw new Error('Brainy instance must be provided to getStatistics');
-    }
-    try {
-        return await instance.getStatistics(options);
-    }
-    catch (error) {
-        console.error('Failed to get statistics:', error);
-        throw new Error(`Failed to get statistics: ${error}`);
-    }
-}
-//# sourceMappingURL=statistics.js.map