@soulcraft/brainy 0.47.0 → 0.49.0

package/dist/utils/embedding.js

@@ -4,6 +4,51 @@
  */
 import { isBrowser } from './environment.js';
 import { pipeline, env } from '@huggingface/transformers';
+/**
+ * Detect the best available GPU device for the current environment
+ */
+export async function detectBestDevice() {
+    // Browser environment - check for WebGPU support
+    if (isBrowser()) {
+        if (typeof navigator !== 'undefined' && 'gpu' in navigator) {
+            try {
+                const adapter = await navigator.gpu?.requestAdapter();
+                if (adapter) {
+                    return 'webgpu';
+                }
+            }
+            catch (error) {
+                // WebGPU not available or failed to initialize
+            }
+        }
+        return 'cpu';
+    }
+    // Node.js environment - check for CUDA support
+    try {
+        // Check if ONNX Runtime GPU packages are available
+        // This is a simple heuristic - in production you might want more sophisticated detection
+        const hasGpu = process.env.CUDA_VISIBLE_DEVICES !== undefined ||
+            process.env.ONNXRUNTIME_GPU_ENABLED === 'true';
+        return hasGpu ? 'cuda' : 'cpu';
+    }
+    catch (error) {
+        return 'cpu';
+    }
+}
+/**
+ * Resolve device string to actual device configuration
+ */
+export async function resolveDevice(device = 'auto') {
+    if (device === 'auto') {
+        return await detectBestDevice();
+    }
+    // Map 'gpu' to appropriate GPU type for current environment
+    if (device === 'gpu') {
+        const detected = await detectBestDevice();
+        return detected === 'cpu' ? 'cpu' : detected;
+    }
+    return device;
+}
 export class TransformerEmbedding {
     /**
      * Create a new TransformerEmbedding instance
@@ -16,9 +61,10 @@ export class TransformerEmbedding {
         this.options = {
             model: options.model || 'Xenova/all-MiniLM-L6-v2',
             verbose: this.verbose,
-            cacheDir: options.cacheDir || this.getDefaultCacheDir(),
+            cacheDir: options.cacheDir || './models', // Will be resolved async in init()
             localFilesOnly: options.localFilesOnly !== undefined ? options.localFilesOnly : !isBrowser(),
-            dtype: options.dtype || 'fp32'
+            dtype: options.dtype || 'fp32',
+            device: options.device || 'auto'
         };
         // Configure transformers.js environment
         if (!isBrowser()) {
@@ -42,7 +88,7 @@ export class TransformerEmbedding {
     /**
      * Get the default cache directory for models
      */
-    getDefaultCacheDir() {
+    async getDefaultCacheDir() {
         if (isBrowser()) {
             return './models'; // Browser default
         }
@@ -60,6 +106,9 @@ export class TransformerEmbedding {
         // Check if we're in Node.js and try to find the bundled models
         if (typeof process !== 'undefined' && process.versions?.node) {
             try {
+                // Use dynamic import instead of require for ES modules compatibility
+                const { createRequire } = await import('module');
+                const require = createRequire(import.meta.url);
                 const path = require('path');
                 const fs = require('fs');
                 // Try to resolve the package location
@@ -85,7 +134,7 @@ export class TransformerEmbedding {
                 }
             }
             catch (error) {
-                this.logger('warn', 'Could not auto-detect bundled models directory:', error);
+                // Silently fall back to default path if module detection fails
             }
         }
         // Fallback to default cache directory
@@ -115,19 +164,42 @@ export class TransformerEmbedding {
         }
         // Always use real implementation - no mocking
         try {
-            this.logger('log', `Loading Transformer model: ${this.options.model}`);
+            // Resolve device configuration and cache directory
+            const device = await resolveDevice(this.options.device);
+            const cacheDir = this.options.cacheDir === './models'
+                ? await this.getDefaultCacheDir()
+                : this.options.cacheDir;
+            this.logger('log', `Loading Transformer model: ${this.options.model} on device: ${device}`);
             const startTime = Date.now();
-            // Load the feature extraction pipeline
-            // In browsers, never use local_files_only to avoid conflicts
+            // Load the feature extraction pipeline with GPU support
             const pipelineOptions = {
-                cache_dir: this.options.cacheDir,
+                cache_dir: cacheDir,
                 local_files_only: isBrowser() ? false : this.options.localFilesOnly,
                 dtype: this.options.dtype
             };
+            // Add device configuration for GPU acceleration
+            if (device !== 'cpu') {
+                pipelineOptions.device = device;
+                this.logger('log', `🚀 GPU acceleration enabled: ${device}`);
+            }
             if (this.verbose) {
                 this.logger('log', `Pipeline options: ${JSON.stringify(pipelineOptions)}`);
             }
-            this.extractor = await pipeline('feature-extraction', this.options.model, pipelineOptions);
+            try {
+                this.extractor = await pipeline('feature-extraction', this.options.model, pipelineOptions);
+            }
+            catch (gpuError) {
+                // Fallback to CPU if GPU initialization fails
+                if (device !== 'cpu') {
+                    this.logger('warn', `GPU initialization failed, falling back to CPU: ${gpuError?.message || gpuError}`);
+                    const cpuOptions = { ...pipelineOptions };
+                    delete cpuOptions.device;
+                    this.extractor = await pipeline('feature-extraction', this.options.model, cpuOptions);
+                }
+                else {
+                    throw gpuError;
+                }
+            }
             const loadTime = Date.now() - startTime;
             this.logger('log', `✅ Model loaded successfully in ${loadTime}ms`);
             this.initialized = true;

package/dist/utils/embedding.js.map

@@ -1 +1 @@
-{"version":3,"file":"embedding.js","sourceRoot":"","sources":["../../src/utils/embedding.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"embedding.js","sourceRoot":"","sources":["../../src/utils/embedding.ts"],"names":[],"mappings":"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"}

package/dist/utils/metadataFilter.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Smart metadata filtering for vector search
+ * Filters DURING search to ensure relevant results
+ * Simple API that just works without configuration
+ */
+import { SearchResult, HNSWNoun } from '../coreTypes.js';
+/**
+ * MongoDB-style query operators
+ */
+export interface QueryOperators {
+    $eq?: any;
+    $ne?: any;
+    $gt?: any;
+    $gte?: any;
+    $lt?: any;
+    $lte?: any;
+    $in?: any[];
+    $nin?: any[];
+    $exists?: boolean;
+    $regex?: string | RegExp;
+    $includes?: any;
+    $all?: any[];
+    $size?: number;
+    $and?: MetadataFilter[];
+    $or?: MetadataFilter[];
+    $not?: MetadataFilter;
+}
+/**
+ * Metadata filter definition
+ */
+export interface MetadataFilter {
+    [key: string]: any | QueryOperators;
+}
+/**
+ * Options for metadata filtering
+ */
+export interface MetadataFilterOptions {
+    metadata?: MetadataFilter;
+    scoring?: {
+        vectorWeight?: number;
+        metadataWeight?: number;
+        metadataBoosts?: Record<string, number | ((value: any, query: any) => number)>;
+    };
+}
+/**
+ * Check if metadata matches the filter
+ */
+export declare function matchesMetadataFilter(metadata: any, filter: MetadataFilter): boolean;
+/**
+ * Calculate metadata boost score
+ */
+export declare function calculateMetadataScore(metadata: any, filter: MetadataFilter, scoring?: MetadataFilterOptions['scoring']): number;
+/**
+ * Apply compound scoring to search results
+ */
+export declare function applyCompoundScoring<T>(results: SearchResult<T>[], filter: MetadataFilter, scoring?: MetadataFilterOptions['scoring']): SearchResult<T>[];
+/**
+ * Filter search results by metadata
+ */
+export declare function filterSearchResultsByMetadata<T>(results: SearchResult<T>[], filter: MetadataFilter): SearchResult<T>[];
+/**
+ * Filter nouns by metadata before search
+ */
+export declare function filterNounsByMetadata(nouns: HNSWNoun[], filter: MetadataFilter): HNSWNoun[];
+/**
+ * Aggregate search results for faceted search
+ */
+export interface FacetConfig {
+    field: string;
+    limit?: number;
+}
+export interface FacetResult {
+    [value: string]: number;
+}
+export interface AggregationResult<T> {
+    results: SearchResult<T>[];
+    facets: Record<string, FacetResult>;
+}
+export declare function aggregateSearchResults<T>(results: SearchResult<T>[], facets: Record<string, FacetConfig>): AggregationResult<T>;

package/dist/utils/metadataFilter.js

@@ -0,0 +1,229 @@
+/**
+ * Smart metadata filtering for vector search
+ * Filters DURING search to ensure relevant results
+ * Simple API that just works without configuration
+ */
+/**
+ * Check if a value matches a query with operators
+ */
+function matchesQuery(value, query) {
+    // Direct equality check
+    if (typeof query !== 'object' || query === null || Array.isArray(query)) {
+        return value === query;
+    }
+    // Check for MongoDB-style operators
+    for (const [op, operand] of Object.entries(query)) {
+        switch (op) {
+            case '$eq':
+                if (value !== operand)
+                    return false;
+                break;
+            case '$ne':
+                if (value === operand)
+                    return false;
+                break;
+            case '$gt':
+                if (typeof value !== 'number' || typeof operand !== 'number' || !(value > operand))
+                    return false;
+                break;
+            case '$gte':
+                if (typeof value !== 'number' || typeof operand !== 'number' || !(value >= operand))
+                    return false;
+                break;
+            case '$lt':
+                if (typeof value !== 'number' || typeof operand !== 'number' || !(value < operand))
+                    return false;
+                break;
+            case '$lte':
+                if (typeof value !== 'number' || typeof operand !== 'number' || !(value <= operand))
+                    return false;
+                break;
+            case '$in':
+                if (!Array.isArray(operand) || !operand.includes(value))
+                    return false;
+                break;
+            case '$nin':
+                if (!Array.isArray(operand) || operand.includes(value))
+                    return false;
+                break;
+            case '$exists':
+                if ((value !== undefined) !== operand)
+                    return false;
+                break;
+            case '$regex':
+                const regex = typeof operand === 'string' ? new RegExp(operand) : operand;
+                if (!(regex instanceof RegExp) || !regex.test(String(value)))
+                    return false;
+                break;
+            case '$includes':
+                if (!Array.isArray(value) || !value.includes(operand))
+                    return false;
+                break;
+            case '$all':
+                if (!Array.isArray(value) || !Array.isArray(operand))
+                    return false;
+                for (const item of operand) {
+                    if (!value.includes(item))
+                        return false;
+                }
+                break;
+            case '$size':
+                if (!Array.isArray(value) || value.length !== operand)
+                    return false;
+                break;
+            default:
+                // Unknown operator, treat as field name
+                if (!matchesFieldQuery(value, op, operand))
+                    return false;
+        }
+    }
+    return true;
+}
+/**
+ * Check if a field matches a query
+ */
+function matchesFieldQuery(obj, field, query) {
+    const value = getNestedValue(obj, field);
+    return matchesQuery(value, query);
+}
+/**
+ * Get nested value from object using dot notation
+ */
+function getNestedValue(obj, path) {
+    const parts = path.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined) {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+}
+/**
+ * Check if metadata matches the filter
+ */
+export function matchesMetadataFilter(metadata, filter) {
+    if (!filter || Object.keys(filter).length === 0) {
+        return true;
+    }
+    for (const [key, query] of Object.entries(filter)) {
+        // Handle logical operators
+        if (key === '$and') {
+            if (!Array.isArray(query))
+                return false;
+            for (const subFilter of query) {
+                if (!matchesMetadataFilter(metadata, subFilter))
+                    return false;
+            }
+            continue;
+        }
+        if (key === '$or') {
+            if (!Array.isArray(query))
+                return false;
+            let matched = false;
+            for (const subFilter of query) {
+                if (matchesMetadataFilter(metadata, subFilter)) {
+                    matched = true;
+                    break;
+                }
+            }
+            if (!matched)
+                return false;
+            continue;
+        }
+        if (key === '$not') {
+            if (matchesMetadataFilter(metadata, query))
+                return false;
+            continue;
+        }
+        // Handle field queries
+        const value = getNestedValue(metadata, key);
+        if (!matchesQuery(value, query)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Calculate metadata boost score
+ */
+export function calculateMetadataScore(metadata, filter, scoring) {
+    if (!scoring || !scoring.metadataBoosts) {
+        return 0;
+    }
+    let score = 0;
+    for (const [field, boost] of Object.entries(scoring.metadataBoosts)) {
+        const value = getNestedValue(metadata, field);
+        if (typeof boost === 'function') {
+            score += boost(value, filter);
+        }
+        else if (value !== undefined) {
+            // Check if the field matches the filter
+            const fieldFilter = filter[field];
+            if (fieldFilter && matchesQuery(value, fieldFilter)) {
+                score += boost;
+            }
+        }
+    }
+    return score;
+}
+/**
+ * Apply compound scoring to search results
+ */
+export function applyCompoundScoring(results, filter, scoring) {
+    if (!scoring || (!scoring.vectorWeight && !scoring.metadataWeight)) {
+        return results;
+    }
+    const vectorWeight = scoring.vectorWeight ?? 1.0;
+    const metadataWeight = scoring.metadataWeight ?? 0.0;
+    return results.map(result => {
+        const metadataScore = calculateMetadataScore(result.metadata, filter, scoring);
+        const combinedScore = (result.score * vectorWeight) + (metadataScore * metadataWeight);
+        return {
+            ...result,
+            score: combinedScore
+        };
+    }).sort((a, b) => b.score - a.score); // Re-sort by combined score
+}
+/**
+ * Filter search results by metadata
+ */
+export function filterSearchResultsByMetadata(results, filter) {
+    if (!filter || Object.keys(filter).length === 0) {
+        return results;
+    }
+    return results.filter(result => matchesMetadataFilter(result.metadata, filter));
+}
+/**
+ * Filter nouns by metadata before search
+ */
+export function filterNounsByMetadata(nouns, filter) {
+    if (!filter || Object.keys(filter).length === 0) {
+        return nouns;
+    }
+    return nouns.filter(noun => matchesMetadataFilter(noun.metadata, filter));
+}
+export function aggregateSearchResults(results, facets) {
+    const facetResults = {};
+    for (const [facetName, config] of Object.entries(facets)) {
+        const counts = {};
+        for (const result of results) {
+            const value = getNestedValue(result.metadata, config.field);
+            if (value !== undefined) {
+                const key = String(value);
+                counts[key] = (counts[key] || 0) + 1;
+            }
+        }
+        // Sort by count and apply limit
+        const sorted = Object.entries(counts)
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, config.limit || 10);
+        facetResults[facetName] = Object.fromEntries(sorted);
+    }
+    return {
+        results,
+        facets: facetResults
+    };
+}
+//# sourceMappingURL=metadataFilter.js.map

package/dist/utils/metadataFilter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadataFilter.js","sourceRoot":"","sources":["../../src/utils/metadataFilter.ts"],"names":[],"mappings":"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"}

package/dist/utils/metadataIndex.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Metadata Index System
+ * Maintains inverted indexes for fast metadata filtering
+ * Automatically updates indexes when data changes
+ */
+import { StorageAdapter } from '../coreTypes.js';
+export interface MetadataIndexEntry {
+    field: string;
+    value: string | number | boolean;
+    ids: Set<string>;
+    lastUpdated: number;
+}
+export interface FieldIndexData {
+    values: Record<string, number>;
+    lastUpdated: number;
+}
+export interface MetadataIndexStats {
+    totalEntries: number;
+    totalIds: number;
+    fieldsIndexed: string[];
+    lastRebuild: number;
+    indexSize: number;
+}
+export interface MetadataIndexConfig {
+    maxIndexSize?: number;
+    rebuildThreshold?: number;
+    autoOptimize?: boolean;
+    indexedFields?: string[];
+    excludeFields?: string[];
+}
+/**
+ * Manages metadata indexes for fast filtering
+ * Maintains inverted indexes: field+value -> list of IDs
+ */
+export declare class MetadataIndexManager {
+    private storage;
+    private config;
+    private indexCache;
+    private dirtyEntries;
+    private isRebuilding;
+    private metadataCache;
+    private fieldIndexes;
+    private dirtyFields;
+    private lastFlushTime;
+    private autoFlushThreshold;
+    constructor(storage: StorageAdapter, config?: MetadataIndexConfig);
+    /**
+     * Get index key for field and value
+     */
+    private getIndexKey;
+    /**
+     * Generate field index filename for filter discovery
+     */
+    private getFieldIndexFilename;
+    /**
+     * Generate value chunk filename for scalable storage
+     */
+    private getValueChunkFilename;
+    /**
+     * Make a value safe for use in filenames
+     */
+    private makeSafeFilename;
+    /**
+     * Normalize value for consistent indexing
+     */
+    private normalizeValue;
+    /**
+     * Create a short hash for long values to avoid filesystem filename limits
+     */
+    private hashValue;
+    /**
+     * Check if field should be indexed
+     */
+    private shouldIndexField;
+    /**
+     * Extract indexable field-value pairs from metadata
+     */
+    private extractIndexableFields;
+    /**
+     * Add item to metadata indexes
+     */
+    addToIndex(id: string, metadata: any, skipFlush?: boolean): Promise<void>;
+    /**
+     * Update field index with value count
+     */
+    private updateFieldIndex;
+    /**
+     * Remove item from metadata indexes
+     */
+    removeFromIndex(id: string, metadata?: any): Promise<void>;
+    /**
+     * Get IDs for a specific field-value combination with caching
+     */
+    getIds(field: string, value: any): Promise<string[]>;
+    /**
+     * Get all available values for a field (for filter discovery)
+     */
+    getFilterValues(field: string): Promise<string[]>;
+    /**
+     * Get all indexed fields (for filter discovery)
+     */
+    getFilterFields(): Promise<string[]>;
+    /**
+     * Convert MongoDB-style filter to simple field-value criteria for indexing
+     */
+    private convertFilterToCriteria;
+    /**
+     * Get IDs matching MongoDB-style metadata filter using indexes where possible
+     */
+    getIdsForFilter(filter: any): Promise<string[]>;
+    /**
+     * Get IDs matching multiple criteria (intersection) - LEGACY METHOD
+     * @deprecated Use getIdsForFilter instead
+     */
+    getIdsForCriteria(criteria: Record<string, any>): Promise<string[]>;
+    /**
+     * Flush dirty entries to storage
+     */
+    flush(): Promise<void>;
+    /**
+     * Load field index from storage
+     */
+    private loadFieldIndex;
+    /**
+     * Save field index to storage
+     */
+    private saveFieldIndex;
+    /**
+     * Get index statistics
+     */
+    getStats(): Promise<MetadataIndexStats>;
+    /**
+     * Rebuild entire index from scratch using pagination
+     */
+    rebuild(): Promise<void>;
+    /**
+     * Load index entry from storage using safe filenames
+     */
+    private loadIndexEntry;
+    /**
+     * Save index entry to storage using safe filenames
+     */
+    private saveIndexEntry;
+    /**
+     * Delete index entry from storage using safe filenames
+     */
+    private deleteIndexEntry;
+}