@soulcraft/brainy 0.48.0 → 0.49.0

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;
+}