@soulcraft/brainy 3.8.3 → 3.9.1

package/README.md

@@ -9,7 +9,7 @@
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](https://www.typescriptlang.org/)
 
-**🧠 Brainy 3.0 - Universal Knowledge Protocol™**
+**🧠 Brainy - Universal Knowledge Protocol™**
 
 **World's first Triple Intelligence™ database** unifying vector similarity, graph relationships, and document filtering in one magical API. **Framework-friendly design** works seamlessly with Next.js, React, Vue, Angular, and any modern JavaScript framework.
 
@@ -17,7 +17,7 @@
 
 **Framework-first design.** Built for modern web development with zero configuration and automatic framework compatibility. O(log n) performance, <10ms search latency, production-ready.
 
-## 🎉 What's New in 3.0
+## 🎉 Key Features
 
 ### 🧠 **Triple Intelligence™ Engine**
 
@@ -49,7 +49,7 @@ npm install @soulcraft/brainy
 ### 🎯 **True Zero Configuration**
 
 ```javascript
-import {Brainy} from '@soulcraft/brainy'
+import { Brainy, NounType } from '@soulcraft/brainy'
 
 // Just this - auto-detects everything!
 const brain = new Brainy()
@@ -58,7 +58,7 @@ await brain.init()
 // Add entities with automatic embedding
 const jsId = await brain.add({
     data: "JavaScript is a programming language",
-    type: "concept",
+    nounType: NounType.Concept,
     metadata: {
         type: "language",
         year: 1995,
@@ -68,7 +68,7 @@ const jsId = await brain.add({
 
 const nodeId = await brain.add({
     data: "Node.js runtime environment",
-    type: "concept",
+    nounType: NounType.Concept,
     metadata: {
         type: "runtime",
         year: 2009,
@@ -100,7 +100,7 @@ const filtered = await brain.find({
 
 ## 🌐 Framework Integration
 
-**Brainy 3.0 is framework-first!** Works seamlessly with any modern JavaScript framework:
+**Brainy is framework-first!** Works seamlessly with any modern JavaScript framework:
 
 ### ⚛️ **React & Next.js**
 ```javascript
@@ -194,7 +194,7 @@ If using nvm: `nvm use` (we provide a `.nvmrc` file)
 
 **Enabled by Triple Intelligence, standardized for everyone:**
 
-- **24 Noun Types × 40 Verb Types**: 960 base combinations
+- **31 Noun Types × 40 Verb Types**: 1,240 base combinations
 - **∞ Expressiveness**: Unlimited metadata = model ANY data
 - **One Language**: All tools, augmentations, AI models speak the same types
 - **Perfect Interoperability**: Move data between any Brainy instance
@@ -211,10 +211,10 @@ await brain.find("Documentation about authentication from last month")
 
 ### 🎯 Zero Configuration Philosophy
 
-Brainy 3.0 automatically configures **everything**:
+Brainy automatically configures **everything**:
 
 ```javascript
-import {Brainy} from '@soulcraft/brainy'
+import { Brainy } from '@soulcraft/brainy'
 
 // 1. Pure zero-config - detects everything
 const brain = new Brainy()
@@ -368,6 +368,8 @@ const brain = new Brainy({
 ### Real-World Example: Social Media Firehose
 
 ```javascript
+import { Brainy, NounType } from '@soulcraft/brainy'
+
 // Ingestion nodes (optimized for writes)
 const ingestionNode = new Brainy({
     storage: {type: 's3', options: {bucket: 'social-data'}},
@@ -378,7 +380,7 @@ const ingestionNode = new Brainy({
 // Process Bluesky firehose
 blueskyStream.on('post', async (post) => {
     await ingestionNode.add(post, {
-        nounType: 'social-post',
+        nounType: NounType.Message,
         platform: 'bluesky',
         author: post.author,
         timestamp: post.createdAt
@@ -417,21 +419,19 @@ const trending = await searchNode.find('trending AI topics', {
 ```javascript
 // Store documentation with rich relationships
 const apiGuide = await brain.add("REST API Guide", {
-    nounType: 'document',
+    nounType: NounType.Document,
     title: "API Guide",
     category: "documentation",
     version: "2.0"
 })
 
 const author = await brain.add("Jane Developer", {
-    nounType: 'person',
-    type: "person",
+    nounType: NounType.Person,
     role: "tech-lead"
 })
 
 const project = await brain.add("E-commerce Platform", {
-    nounType: 'project',
-    type: "project",
+    nounType: NounType.Project,
     status: "active"
 })
 
@@ -462,21 +462,18 @@ const similar = await brain.search(existingContent, {
 ```javascript
 // Store conversation with relationships
 const userId = await brain.add("User 123", {
-    nounType: 'user',
-    type: "user",
+    nounType: NounType.User,
     tier: "premium"
 })
 
 const messageId = await brain.add(userMessage, {
-    nounType: 'message',
-    type: "message",
+    nounType: NounType.Message,
     timestamp: Date.now(),
     session: "abc"
 })
 
 const topicId = await brain.add("Product Support", {
-    nounType: 'topic',
-    type: "topic",
+    nounType: NounType.Topic,
     category: "support"
 })
 
@@ -602,7 +599,7 @@ for (const cluster of feedbackClusters) {
 }
 
 // Find related documents
-const docId = await brain.add("Machine learning guide", { nounType: 'document' })
+const docId = await brain.add("Machine learning guide", { nounType: NounType.Document })
 const similar = await neural.neighbors(docId, 5)
 // Returns 5 most similar documents
 
@@ -637,7 +634,7 @@ Brainy includes enterprise-grade capabilities at no extra cost. **No premium tie
 - **Built-in monitoring** with metrics and health checks
 - **Production ready** with circuit breakers and backpressure
 
-📖 **Enterprise features coming in Brainy 3.1** - Stay tuned!
+📖 **More enterprise features coming soon** - Stay tuned!
 
 ## 📊 Benchmarks
 
@@ -651,13 +648,14 @@ Brainy includes enterprise-grade capabilities at no extra cost. **No premium tie
 | Bulk Import (1000 items)         | 2.3s        | +8MB     |
 | **Production Scale (10M items)** | **5.8ms**   | **12GB** |
 
-## 🔄 Migration from 2.x
+## 🔄 Migration from Previous Versions
 
-Key changes for upgrading to 3.0:
+Key changes in the latest version:
 
 - Search methods consolidated into `search()` and `find()`
 - Result format now includes full objects with metadata
-- New natural language capabilities
+- Enhanced natural language capabilities
+- Distributed architecture support
 
 ## 🤝 Contributing
 
@@ -678,10 +676,10 @@ We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 ### The Math of Infinite Expressiveness
 
 ```
-24 Nouns × 40 Verbs × ∞ Metadata × Triple Intelligence = Universal Protocol
+31 Nouns × 40 Verbs × ∞ Metadata × Triple Intelligence = Universal Protocol
 ```
 
-- **960 base combinations** from standardized types
+- **1,240 base combinations** from standardized types
 - **∞ domain specificity** via unlimited metadata
 - **∞ relationship depth** via graph traversal
 - **= Model ANYTHING**: From quantum physics to social networks

package/dist/brainy.d.ts

@@ -26,6 +26,10 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
     private distance;
     private augmentationRegistry;
     private config;
+    private coordinator?;
+    private shardManager?;
+    private cacheSync?;
+    private readWriteSeparation?;
     private originalConsole?;
     private _neural?;
     private _nlp?;
@@ -111,6 +115,16 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
      * Clear all data from the database
      */
     clear(): Promise<void>;
+    /**
+     * Get total count of nouns - O(1) operation
+     * @returns Promise that resolves to the total number of nouns
+     */
+    getNounCount(): Promise<number>;
+    /**
+     * Get total count of verbs - O(1) operation
+     * @returns Promise that resolves to the total number of verbs
+     */
+    getVerbCount(): Promise<number>;
     /**
      * Neural API - Advanced AI operations
      */
@@ -353,6 +367,19 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
      * Close and cleanup
      */
     close(): Promise<void>;
+    /**
+     * Intelligently auto-detect distributed configuration
+     * Zero-config: Automatically determines best distributed settings
+     */
+    private autoDetectDistributed;
+    /**
+     * Setup distributed components with zero-config intelligence
+     */
+    private setupDistributedComponents;
+    /**
+     * Pass distributed components to storage adapter
+     */
+    private connectDistributedStorage;
 }
 export * from './types/brainy.types.js';
 export { NounType, VerbType } from './types/graphTypes.js';

package/dist/brainy.js

@@ -18,6 +18,7 @@ import { MetadataIndexManager } from './utils/metadataIndex.js';
 import { GraphAdjacencyIndex } from './graph/graphAdjacencyIndex.js';
 import { createPipeline } from './streaming/pipeline.js';
 import { configureLogger, LogLevel } from './utils/logger.js';
+import { DistributedCoordinator, ShardManager, CacheSync, ReadWriteSeparation } from './distributed/index.js';
 import { NounType } from './types/graphTypes.js';
 /**
  * The main Brainy class - Clean, Beautiful, Powerful
@@ -35,6 +36,10 @@ export class Brainy {
         this.distance = cosineDistance;
         this.embedder = this.setupEmbedder();
         this.augmentationRegistry = this.setupAugmentations();
+        // Setup distributed components if enabled
+        if (this.config.distributed?.enabled) {
+            this.setupDistributedComponents();
+        }
         // Index and storage are initialized in init() because they may need each other
     }
     /**
@@ -113,6 +118,8 @@ export class Brainy {
                     }
                 }
             });
+            // Connect distributed components to storage
+            await this.connectDistributedStorage();
             // Warm up if configured
             if (this.config.warmup) {
                 await this.warmup();
@@ -269,6 +276,10 @@ export class Brainy {
      * Delete an entity
      */
     async delete(id) {
+        // Handle invalid IDs gracefully
+        if (!id || typeof id !== 'string') {
+            return; // Silently return for invalid IDs
+        }
         await this.ensureInitialized();
         return this.augmentationRegistry.execute('delete', { id }, async () => {
             // Remove from vector index
@@ -289,6 +300,9 @@ export class Brainy {
             const targetVerbs = await this.storage.getVerbsByTarget(id);
             const allVerbs = [...verbs, ...targetVerbs];
             for (const verb of allVerbs) {
+                // Remove from graph index first
+                await this.graphIndex.removeVerb(verb.id);
+                // Then delete from storage
                 await this.storage.deleteVerb(verb.id);
             }
         });
@@ -407,10 +421,53 @@ export class Brainy {
         const startTime = Date.now();
         const result = await this.augmentationRegistry.execute('find', params, async () => {
             let results = [];
-            // Handle empty query - return paginated results from storage
-            const hasSearchCriteria = params.query || params.vector || params.where ||
-                params.type || params.service || params.near || params.connected;
-            if (!hasSearchCriteria) {
+            // Distinguish between search criteria (need vector search) and filter criteria (metadata only)
+            // Treat empty string query as no query
+            const hasVectorSearchCriteria = (params.query && params.query.trim() !== '') || params.vector || params.near;
+            const hasFilterCriteria = params.where || params.type || params.service;
+            const hasGraphCriteria = params.connected;
+            // Handle metadata-only queries (no vector search needed)
+            if (!hasVectorSearchCriteria && !hasGraphCriteria && hasFilterCriteria) {
+                // Build filter for metadata index
+                let filter = {};
+                if (params.where)
+                    Object.assign(filter, params.where);
+                if (params.service)
+                    filter.service = params.service;
+                if (params.type) {
+                    const types = Array.isArray(params.type) ? params.type : [params.type];
+                    if (types.length === 1) {
+                        filter.noun = types[0];
+                    }
+                    else {
+                        filter = {
+                            anyOf: types.map(type => ({
+                                noun: type,
+                                ...filter
+                            }))
+                        };
+                    }
+                }
+                // Get filtered IDs and paginate BEFORE loading entities
+                const filteredIds = await this.metadataIndex.getIdsForFilter(filter);
+                const limit = params.limit || 10;
+                const offset = params.offset || 0;
+                const pageIds = filteredIds.slice(offset, offset + limit);
+                // Load entities for the paginated results
+                for (const id of pageIds) {
+                    const entity = await this.get(id);
+                    if (entity) {
+                        results.push({
+                            id,
+                            score: 1.0, // All metadata-filtered results equally relevant
+                            entity
+                        });
+                    }
+                }
+                return results;
+            }
+            // Handle completely empty query - return all results paginated
+            if (!hasVectorSearchCriteria && !hasFilterCriteria && !hasGraphCriteria) {
                 const limit = params.limit || 20;
                 const offset = params.offset || 0;
                 const storageResults = await this.storage.getNouns({
@@ -803,6 +860,22 @@ export class Brainy {
             this._tripleIntelligence = undefined;
         });
     }
+    /**
+     * Get total count of nouns - O(1) operation
+     * @returns Promise that resolves to the total number of nouns
+     */
+    async getNounCount() {
+        await this.ensureInitialized();
+        return this.storage.getNounCount();
+    }
+    /**
+     * Get total count of verbs - O(1) operation
+     * @returns Promise that resolves to the total number of verbs
+     */
+    async getVerbCount() {
+        await this.ensureInitialized();
+        return this.storage.getVerbCount();
+    }
     // ============= SUB-APIS =============
     /**
      * Neural API - Advanced AI operations
@@ -1462,18 +1535,27 @@ export class Brainy {
         if (config?.index?.efSearch && (config.index.efSearch < 1 || config.index.efSearch > 1000)) {
             throw new Error(`Invalid index efSearch: ${config.index.efSearch}. Must be between 1 and 1000`);
         }
+        // Auto-detect distributed mode based on environment and configuration
+        const distributedConfig = this.autoDetectDistributed(config?.distributed);
         return {
             storage: config?.storage || { type: 'auto' },
             model: config?.model || { type: 'fast' },
             index: config?.index || {},
             cache: config?.cache ?? true,
             augmentations: config?.augmentations || {},
+            distributed: distributedConfig, // Type will be fixed when used
             warmup: config?.warmup ?? false,
             realtime: config?.realtime ?? false,
             multiTenancy: config?.multiTenancy ?? false,
             telemetry: config?.telemetry ?? false,
             verbose: config?.verbose ?? false,
-            silent: config?.silent ?? false
+            silent: config?.silent ?? false,
+            // New performance options with smart defaults
+            disableAutoRebuild: config?.disableAutoRebuild ?? false, // false = auto-decide based on size
+            disableMetrics: config?.disableMetrics ?? false,
+            disableAutoOptimize: config?.disableAutoOptimize ?? false,
+            batchWrites: config?.batchWrites ?? true,
+            maxConcurrentOperations: config?.maxConcurrentOperations ?? 10
         };
     }
     /**
@@ -1483,17 +1565,49 @@ export class Brainy {
         try {
             // Check if storage has data
             const entities = await this.storage.getNouns({ pagination: { limit: 1 } });
-            if (entities.totalCount === 0 || entities.items.length === 0) {
+            const totalCount = entities.totalCount || 0;
+            if (totalCount === 0) {
                 // No data in storage, no rebuild needed
                 return;
             }
+            // Intelligent decision: Auto-rebuild only for small datasets
+            // For large datasets, use lazy loading for optimal performance
+            const AUTO_REBUILD_THRESHOLD = 1000; // Only auto-rebuild if < 1000 items
             // Check if metadata index is empty
             const metadataStats = await this.metadataIndex.getStats();
-            if (metadataStats.totalEntries === 0) {
-                console.log('🔄 Rebuilding metadata index for existing data...');
+            if (metadataStats.totalEntries === 0 && totalCount > 0) {
+                if (totalCount < AUTO_REBUILD_THRESHOLD) {
+                    // Small dataset - rebuild for convenience
+                    if (!this.config.silent) {
+                        console.log(`🔄 Small dataset (${totalCount} items) - rebuilding index for optimal performance...`);
+                    }
+                    await this.metadataIndex.rebuild();
+                    const newStats = await this.metadataIndex.getStats();
+                    if (!this.config.silent) {
+                        console.log(`✅ Index rebuilt: ${newStats.totalEntries} entries`);
+                    }
+                }
+                else {
+                    // Large dataset - use lazy loading
+                    if (!this.config.silent) {
+                        console.log(`⚡ Large dataset (${totalCount} items) - using lazy loading for optimal startup performance`);
+                        console.log('💡 Tip: Indexes will build automatically as you use the system');
+                    }
+                }
+            }
+            // Override with explicit config if provided
+            if (this.config.disableAutoRebuild === true) {
+                if (!this.config.silent) {
+                    console.log('⚡ Auto-rebuild explicitly disabled via config');
+                }
+                return;
+            }
+            else if (this.config.disableAutoRebuild === false && metadataStats.totalEntries === 0) {
+                // Explicitly enabled - rebuild regardless of size
+                if (!this.config.silent) {
+                    console.log('🔄 Auto-rebuild explicitly enabled - rebuilding index...');
+                }
                 await this.metadataIndex.rebuild();
-                const newStats = await this.metadataIndex.getStats();
-                console.log(`✅ Metadata index rebuilt: ${newStats.totalEntries} entries`);
             }
             // Note: GraphAdjacencyIndex will rebuild itself as relationships are added
             // Vector index should already be populated if storage has data
@@ -1525,6 +1639,113 @@ export class Brainy {
         // We'll just mark as not initialized
         this.initialized = false;
     }
+    /**
+     * Intelligently auto-detect distributed configuration
+     * Zero-config: Automatically determines best distributed settings
+     */
+    autoDetectDistributed(config) {
+        // If explicitly disabled, respect that
+        if (config?.enabled === false) {
+            return config;
+        }
+        // Auto-detect based on environment variables (common in production)
+        const envEnabled = process.env.BRAINY_DISTRIBUTED === 'true' ||
+            process.env.NODE_ENV === 'production' ||
+            process.env.CLUSTER_SIZE ||
+            process.env.KUBERNETES_SERVICE_HOST; // Running in K8s
+        // Auto-detect based on storage type (S3/R2/GCS implies distributed)
+        const storageImpliesDistributed = this.config?.storage?.type === 's3' ||
+            this.config?.storage?.type === 'r2' ||
+            this.config?.storage?.type === 'gcs';
+        // If not explicitly configured but environment suggests distributed
+        if (!config && (envEnabled || storageImpliesDistributed)) {
+            return {
+                enabled: true,
+                nodeId: process.env.HOSTNAME || process.env.NODE_ID || `node-${Date.now()}`,
+                nodes: process.env.BRAINY_NODES?.split(',') || [],
+                coordinatorUrl: process.env.BRAINY_COORDINATOR || undefined,
+                shardCount: parseInt(process.env.BRAINY_SHARDS || '64'),
+                replicationFactor: parseInt(process.env.BRAINY_REPLICAS || '3'),
+                consensus: process.env.BRAINY_CONSENSUS || 'raft',
+                transport: process.env.BRAINY_TRANSPORT || 'http'
+            };
+        }
+        // Merge with provided config, applying intelligent defaults
+        return config ? {
+            ...config,
+            nodeId: config.nodeId || process.env.HOSTNAME || `node-${Date.now()}`,
+            shardCount: config.shardCount || 64,
+            replicationFactor: config.replicationFactor || 3,
+            consensus: config.consensus || 'raft',
+            transport: config.transport || 'http'
+        } : undefined;
+    }
+    /**
+     * Setup distributed components with zero-config intelligence
+     */
+    setupDistributedComponents() {
+        const distConfig = this.config.distributed;
+        if (!distConfig?.enabled)
+            return;
+        console.log('🌍 Initializing distributed mode:', {
+            nodeId: distConfig.nodeId,
+            shards: distConfig.shardCount,
+            replicas: distConfig.replicationFactor
+        });
+        // Initialize coordinator for consensus
+        this.coordinator = new DistributedCoordinator({
+            nodeId: distConfig.nodeId,
+            address: distConfig.coordinatorUrl?.split(':')[0] || 'localhost',
+            port: parseInt(distConfig.coordinatorUrl?.split(':')[1] || '8080'),
+            nodes: distConfig.nodes
+        });
+        // Start the coordinator to establish leadership
+        this.coordinator.start().catch(err => {
+            console.warn('Coordinator start failed (will retry on init):', err.message);
+        });
+        // Initialize shard manager for data distribution
+        this.shardManager = new ShardManager({
+            shardCount: distConfig.shardCount,
+            replicationFactor: distConfig.replicationFactor,
+            virtualNodes: 150, // Optimal for consistent distribution
+            autoRebalance: true
+        });
+        // Initialize cache synchronization
+        this.cacheSync = new CacheSync({
+            nodeId: distConfig.nodeId,
+            syncInterval: 1000
+        });
+        // Initialize read/write separation if we have replicas
+        // Note: Will be properly initialized after coordinator starts
+        if (distConfig.replicationFactor && distConfig.replicationFactor > 1) {
+            // Defer creation until coordinator is ready
+            setTimeout(() => {
+                this.readWriteSeparation = new ReadWriteSeparation({
+                    nodeId: distConfig.nodeId,
+                    consistencyLevel: 'eventual',
+                    role: 'replica', // Start as replica, will promote if leader
+                    syncInterval: 5000
+                }, this.coordinator, this.shardManager, this.cacheSync);
+            }, 100);
+        }
+    }
+    /**
+     * Pass distributed components to storage adapter
+     */
+    async connectDistributedStorage() {
+        if (!this.config.distributed?.enabled)
+            return;
+        // Check if storage supports distributed operations
+        if ('setDistributedComponents' in this.storage) {
+            this.storage.setDistributedComponents({
+                coordinator: this.coordinator,
+                shardManager: this.shardManager,
+                cacheSync: this.cacheSync,
+                readWriteSeparation: this.readWriteSeparation
+            });
+            console.log('✅ Distributed storage connected');
+        }
+    }
 }
 // Re-export types for convenience
 export * from './types/brainy.types.js';

package/dist/coreTypes.d.ts

@@ -512,4 +512,14 @@ export interface StorageAdapter {
      * @returns Promise that resolves to an array of changes
      */
     getChangesSince?(timestamp: number, limit?: number): Promise<any[]>;
+    /**
+     * Get total count of nouns in storage - O(1) operation
+     * @returns Promise that resolves to the total number of nouns
+     */
+    getNounCount(): Promise<number>;
+    /**
+     * Get total count of verbs in storage - O(1) operation
+     * @returns Promise that resolves to the total number of verbs
+     */
+    getVerbCount(): Promise<number>;
 }

package/dist/hnsw/hnswIndex.d.ts

@@ -7,6 +7,8 @@ export declare class HNSWIndex {
     private nouns;
     private entryPointId;
     private maxLevel;
+    private highLevelNodes;
+    private readonly MAX_TRACKED_LEVELS;
     private config;
     private distanceFunction;
     private dimension;

package/dist/hnsw/hnswIndex.js

@@ -15,6 +15,9 @@ export class HNSWIndex {
         this.nouns = new Map();
         this.entryPointId = null;
         this.maxLevel = 0;
+        // Track high-level nodes for O(1) entry point selection
+        this.highLevelNodes = new Map(); // level -> node IDs
+        this.MAX_TRACKED_LEVELS = 10; // Only track top levels for memory efficiency
         this.dimension = null;
         this.useParallelization = true; // Whether to use parallelization for performance-critical operations
         this.config = { ...DEFAULT_CONFIG, ...config };
@@ -203,6 +206,13 @@ export class HNSWIndex {
         }
         // Add noun to the index
         this.nouns.set(id, noun);
+        // Track high-level nodes for O(1) entry point selection
+        if (nounLevel >= 2 && nounLevel <= this.MAX_TRACKED_LEVELS) {
+            if (!this.highLevelNodes.has(nounLevel)) {
+                this.highLevelNodes.set(nounLevel, new Set());
+            }
+            this.highLevelNodes.get(nounLevel).add(id);
+        }
         return id;
     }
     /**

package/dist/neural/improvedNeuralAPI.d.ts

@@ -159,8 +159,21 @@ export declare class ImprovedNeuralAPI {
      * Group items by their semantic noun types
      */
     private _groupBySemanticType;
-    private _getAllItemIds;
+    /**
+     * Iterate through all items without loading them all at once
+     * This scales to millions of items without memory issues
+     */
+    private _iterateAllItems;
+    /**
+     * Get a sample of item IDs for operations that don't need all items
+     * This is O(1) for small samples
+     */
+    private _getSampleItemIds;
+    /**
+     * Get total count using the brain's O(1) counting API
+     */
     private _getTotalItemCount;
+    private _getAllItemIds;
     private _calculateTotalWeight;
     private _getNeighborCommunities;
     private _calculateModularityGain;