@soulcraft/brainy 1.5.0 → 2.0.0

package/dist/augmentations/indexAugmentation.js

@@ -0,0 +1,284 @@
+/**
+ * Index Augmentation - Optional Metadata Indexing
+ *
+ * Replaces the hardcoded MetadataIndex in BrainyData with an optional augmentation.
+ * Provides O(1) metadata filtering and field lookups.
+ *
+ * Zero-config: Automatically enabled for better search performance
+ * Can be disabled or customized via augmentation registry
+ */
+import { BaseAugmentation } from './brainyAugmentation.js';
+import { MetadataIndexManager } from '../utils/metadataIndex.js';
+/**
+ * IndexAugmentation - Makes metadata indexing optional and pluggable
+ *
+ * Features:
+ * - O(1) metadata field lookups
+ * - Fast pre-filtering for searches
+ * - Automatic index maintenance
+ * - Zero-config with smart defaults
+ */
+export class IndexAugmentation extends BaseAugmentation {
+    constructor(config = {}) {
+        super();
+        this.name = 'index';
+        this.timing = 'after';
+        this.operations = ['add', 'updateMetadata', 'delete', 'clear', 'all'];
+        this.priority = 60; // Run after data operations
+        this.metadataIndex = null;
+        this.flushTimer = null;
+        this.config = {
+            enabled: true,
+            maxFieldValues: 1000,
+            autoRebuild: true,
+            rebuildThreshold: 0.3, // Rebuild if 30% inconsistent
+            flushInterval: 30000, // Flush every 30 seconds
+            ...config
+        };
+    }
+    async onInitialize() {
+        if (!this.config.enabled) {
+            this.log('Index augmentation disabled by configuration');
+            return;
+        }
+        // Get storage from context
+        const storage = this.context?.storage;
+        if (!storage) {
+            this.log('No storage available, index augmentation inactive', 'warn');
+            return;
+        }
+        // Initialize metadata index
+        this.metadataIndex = new MetadataIndexManager(storage, {
+            maxIndexSize: this.config.maxIndexSize || 10000
+        });
+        // Check if we need to rebuild
+        if (this.config.autoRebuild) {
+            const stats = await this.metadataIndex.getStats();
+            if (stats.totalEntries === 0) {
+                // Check if storage has data but index is empty
+                try {
+                    const storageStats = await storage.getStatistics?.();
+                    if (storageStats && storageStats.totalNouns > 0) {
+                        this.log('Rebuilding metadata index for existing data...');
+                        await this.metadataIndex.rebuild();
+                        const newStats = await this.metadataIndex.getStats();
+                        this.log(`Index rebuilt: ${newStats.totalEntries} entries, ${newStats.fieldsIndexed.length} fields`);
+                    }
+                }
+                catch (e) {
+                    this.log('Could not check storage statistics', 'info');
+                }
+            }
+        }
+        // Start flush timer
+        if (this.config.flushInterval && this.config.flushInterval > 0) {
+            this.startFlushTimer();
+        }
+        this.log('Index augmentation initialized');
+    }
+    async onShutdown() {
+        // Stop flush timer
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        // Flush index one last time
+        if (this.metadataIndex) {
+            try {
+                await this.metadataIndex.flush();
+            }
+            catch (error) {
+                this.log('Error flushing index during shutdown', 'warn');
+            }
+            this.metadataIndex = null;
+        }
+        this.log('Index augmentation shut down');
+    }
+    /**
+     * Execute augmentation - maintain index on data operations
+     */
+    async execute(operation, params, next) {
+        // Execute the operation first
+        const result = await next();
+        // If index is disabled, just return
+        if (!this.metadataIndex || !this.config.enabled) {
+            return result;
+        }
+        // Handle index updates after operation completes
+        switch (operation) {
+            case 'add':
+                await this.handleAdd(params);
+                break;
+            case 'updateMetadata':
+                await this.handleUpdate(params);
+                break;
+            case 'delete':
+                await this.handleDelete(params);
+                break;
+            case 'clear':
+                await this.handleClear();
+                break;
+        }
+        return result;
+    }
+    /**
+     * Handle add operation - index new metadata
+     */
+    async handleAdd(params) {
+        if (!this.metadataIndex)
+            return;
+        const { id, metadata } = params;
+        if (id && metadata) {
+            await this.metadataIndex.addToIndex(id, metadata);
+            this.log(`Indexed metadata for ${id}`, 'info');
+        }
+    }
+    /**
+     * Handle update operation - reindex metadata
+     */
+    async handleUpdate(params) {
+        if (!this.metadataIndex)
+            return;
+        const { id, oldMetadata, newMetadata } = params;
+        // Remove old metadata
+        if (id && oldMetadata) {
+            await this.metadataIndex.removeFromIndex(id, oldMetadata);
+        }
+        // Add new metadata
+        if (id && newMetadata) {
+            await this.metadataIndex.addToIndex(id, newMetadata);
+            this.log(`Reindexed metadata for ${id}`, 'info');
+        }
+    }
+    /**
+     * Handle delete operation - remove from index
+     */
+    async handleDelete(params) {
+        if (!this.metadataIndex)
+            return;
+        const { id, metadata } = params;
+        if (id && metadata) {
+            await this.metadataIndex.removeFromIndex(id, metadata);
+            this.log(`Removed ${id} from index`, 'info');
+        }
+    }
+    /**
+     * Handle clear operation - clear index
+     */
+    async handleClear() {
+        if (!this.metadataIndex)
+            return;
+        // Clear the index when all data is cleared (rebuild effectively clears it)
+        await this.metadataIndex.rebuild();
+        this.log('Index cleared due to clear operation');
+    }
+    /**
+     * Start periodic flush timer
+     */
+    startFlushTimer() {
+        if (this.flushTimer)
+            return;
+        this.flushTimer = setInterval(async () => {
+            if (this.metadataIndex) {
+                try {
+                    await this.metadataIndex.flush();
+                }
+                catch (error) {
+                    this.log('Error during periodic index flush', 'warn');
+                }
+            }
+        }, this.config.flushInterval);
+    }
+    /**
+     * Get IDs that match metadata filter (for pre-filtering)
+     */
+    async getIdsForFilter(filter) {
+        if (!this.metadataIndex)
+            return [];
+        return this.metadataIndex.getIdsForFilter(filter);
+    }
+    /**
+     * Get available values for a field
+     */
+    async getFilterValues(field) {
+        if (!this.metadataIndex)
+            return [];
+        return this.metadataIndex.getFilterValues(field);
+    }
+    /**
+     * Get all indexed fields
+     */
+    async getFilterFields() {
+        if (!this.metadataIndex)
+            return [];
+        return this.metadataIndex.getFilterFields();
+    }
+    /**
+     * Get index statistics
+     */
+    async getStats() {
+        if (!this.metadataIndex) {
+            return {
+                enabled: false,
+                totalEntries: 0,
+                fieldsIndexed: [],
+                memoryUsage: 0
+            };
+        }
+        const stats = await this.metadataIndex.getStats();
+        return {
+            enabled: true,
+            ...stats
+        };
+    }
+    /**
+     * Rebuild the index from storage
+     */
+    async rebuild() {
+        if (!this.metadataIndex) {
+            throw new Error('Index augmentation is not initialized');
+        }
+        this.log('Rebuilding metadata index...');
+        await this.metadataIndex.rebuild();
+        const stats = await this.metadataIndex.getStats();
+        this.log(`Index rebuilt: ${stats.totalEntries} entries, ${stats.fieldsIndexed.length} fields`);
+    }
+    /**
+     * Flush index to storage
+     */
+    async flush() {
+        if (this.metadataIndex) {
+            await this.metadataIndex.flush();
+            this.log('Index flushed to storage', 'info');
+        }
+    }
+    /**
+     * Add entry to index (public method for direct access)
+     */
+    async addToIndex(id, metadata) {
+        if (!this.metadataIndex)
+            return;
+        await this.metadataIndex.addToIndex(id, metadata);
+    }
+    /**
+     * Remove entry from index (public method for direct access)
+     */
+    async removeFromIndex(id, metadata) {
+        if (!this.metadataIndex)
+            return;
+        await this.metadataIndex.removeFromIndex(id, metadata);
+    }
+    /**
+     * Get the underlying MetadataIndexManager instance
+     */
+    getMetadataIndex() {
+        return this.metadataIndex;
+    }
+}
+/**
+ * Factory function for zero-config index augmentation
+ */
+export function createIndexAugmentation(config) {
+    return new IndexAugmentation(config);
+}
+//# sourceMappingURL=indexAugmentation.js.map

package/dist/augmentations/intelligentVerbScoringAugmentation.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Intelligent Verb Scoring Augmentation
+ *
+ * Enhances relationship quality through intelligent semantic scoring
+ * Provides context-aware relationship weights based on:
+ * - Semantic proximity of connected entities
+ * - Frequency-based amplification
+ * - Temporal decay modeling
+ * - Adaptive learning from usage patterns
+ *
+ * Critical for enterprise knowledge graphs with millions of relationships
+ */
+import { BaseAugmentation } from './brainyAugmentation.js';
+interface VerbScoringConfig {
+    enabled?: boolean;
+    enableSemanticScoring?: boolean;
+    semanticThreshold?: number;
+    semanticWeight?: number;
+    enableFrequencyAmplification?: boolean;
+    frequencyDecay?: number;
+    maxFrequencyBoost?: number;
+    enableTemporalDecay?: boolean;
+    temporalDecayRate?: number;
+    temporalWindow?: number;
+    enableAdaptiveLearning?: boolean;
+    learningRate?: number;
+    confidenceThreshold?: number;
+    minWeight?: number;
+    maxWeight?: number;
+    baseWeight?: number;
+}
+interface RelationshipMetrics {
+    count: number;
+    totalWeight: number;
+    averageWeight: number;
+    lastUpdated: number;
+    semanticScore: number;
+    frequencyScore: number;
+    temporalScore: number;
+    confidenceScore: number;
+}
+interface ScoringMetrics {
+    relationshipsScored: number;
+    averageSemanticScore: number;
+    averageFrequencyScore: number;
+    averageTemporalScore: number;
+    averageConfidenceScore: number;
+    adaptiveAdjustments: number;
+    computationTimeMs: number;
+}
+export declare class IntelligentVerbScoringAugmentation extends BaseAugmentation {
+    name: string;
+    timing: "around";
+    operations: ("addVerb" | "relate")[];
+    priority: number;
+    get enabled(): boolean;
+    private config;
+    private relationshipStats;
+    private metrics;
+    private scoringInstance;
+    constructor(config?: VerbScoringConfig);
+    protected onInitialize(): Promise<void>;
+    /**
+     * Get this augmentation instance for API compatibility
+     * Used by BrainyData to access scoring methods
+     */
+    getScoring(): IntelligentVerbScoringAugmentation;
+    shouldExecute(operation: string, params: any): boolean;
+    execute<T = any>(operation: string, params: any, next: () => Promise<T>): Promise<T>;
+    private calculateIntelligentWeight;
+    private calculateSemanticScore;
+    /**
+     * Detect noun type using neural taxonomy matching
+     */
+    private detectNounType;
+    /**
+     * Calculate taxonomy-based similarity boost
+     */
+    private calculateTaxonomyBoost;
+    private calculateCosineSimilarity;
+    private calculateFrequencyScore;
+    private calculateTemporalScore;
+    private calculateContextScore;
+    private updateRelationshipLearning;
+    private getConfidenceScore;
+    private getScoringMethodsUsed;
+    private storeDetailedScoring;
+    private updateMetrics;
+    /**
+     * Get intelligent verb scoring statistics
+     */
+    getStats(): ScoringMetrics & {
+        totalRelationships: number;
+        averageConfidence: number;
+        highConfidenceRelationships: number;
+        learningEfficiency: number;
+    };
+    /**
+     * Export relationship statistics for analysis
+     */
+    exportRelationshipStats(): Array<{
+        relationship: string;
+        metrics: RelationshipMetrics;
+    }>;
+    /**
+     * Import relationship statistics from previous sessions
+     */
+    importRelationshipStats(stats: Array<{
+        relationship: string;
+        metrics: RelationshipMetrics;
+    }>): void;
+    /**
+     * Get learning statistics for monitoring and debugging
+     * Required for BrainyData.getVerbScoringStats()
+     */
+    getLearningStats(): {
+        totalRelationships: number;
+        averageConfidence: number;
+        feedbackCount: number;
+        topRelationships: Array<{
+            relationship: string;
+            count: number;
+            averageWeight: number;
+        }>;
+    };
+    /**
+     * Export learning data for backup or analysis
+     * Required for BrainyData.exportVerbScoringLearningData()
+     */
+    exportLearningData(): string;
+    /**
+     * Import learning data from backup
+     * Required for BrainyData.importVerbScoringLearningData()
+     */
+    importLearningData(jsonData: string): void;
+    /**
+     * Provide feedback on a relationship's weight
+     * Required for BrainyData.provideVerbScoringFeedback()
+     */
+    provideFeedback(sourceId: string, targetId: string, relationType: string, feedback: number, feedbackType?: 'correction' | 'validation' | 'enhancement'): Promise<void>;
+    /**
+     * Compute intelligent scores for a verb relationship
+     * Used internally during verb creation
+     */
+    computeVerbScores(sourceNoun: any, targetNoun: any, relationType: string): Promise<{
+        weight: number;
+        confidence: number;
+        reasoning: string[];
+    }>;
+    protected onShutdown(): Promise<void>;
+}
+export {};