@soulcraft/brainy 2.5.0 → 2.7.0

package/README.md

@@ -71,6 +71,18 @@ const filtered = await brain.find({
 })
 ```
 
+## 📋 System Requirements
+
+**Node.js Version:** 22 LTS or later (recommended)
+
+- ✅ **Node.js 22 LTS** - Fully supported and recommended for production
+- ✅ **Node.js 20 LTS** - Compatible (maintenance mode)
+- ❌ **Node.js 24** - Not supported (known ONNX runtime compatibility issues)
+
+> **Important:** Brainy uses ONNX runtime for AI embeddings. Node.js 24 has known compatibility issues that cause crashes during inference operations. We recommend Node.js 22 LTS for maximum stability.
+
+If using nvm: `nvm use` (we provide a `.nvmrc` file)
+
 ## 🚀 Key Features
 
 ### World's First Triple Intelligence™ Engine
@@ -294,6 +306,66 @@ brainy chat
 brainy export --format json > backup.json
 ```
 
+## 🧠 Neural API - Advanced AI Features
+
+Brainy includes a powerful Neural API for advanced semantic analysis:
+
+### Clustering & Analysis
+```javascript
+// Access via brain.neural
+const neural = brain.neural
+
+// Automatic semantic clustering
+const clusters = await neural.clusters()
+// Returns groups of semantically similar items
+
+// Cluster with options
+const clusters = await neural.clusters({
+  algorithm: 'kmeans',     // or 'hierarchical', 'sample'
+  maxClusters: 5,          // Maximum number of clusters
+  threshold: 0.8           // Similarity threshold
+})
+
+// Calculate similarity between any items
+const similarity = await neural.similar('item1', 'item2')
+// Returns 0-1 score
+
+// Find nearest neighbors
+const neighbors = await neural.neighbors('item-id', 10)
+
+// Build semantic hierarchy
+const hierarchy = await neural.hierarchy('item-id')
+
+// Detect outliers
+const outliers = await neural.outliers(0.3)
+
+// Generate visualization data for D3/Cytoscape
+const vizData = await neural.visualize({
+  maxNodes: 100,
+  dimensions: 3,
+  algorithm: 'force'
+})
+```
+
+### Real-World Examples
+```javascript
+// Group customer feedback into themes
+const feedbackClusters = await neural.clusters()
+for (const cluster of feedbackClusters) {
+  console.log(`Theme: ${cluster.label}`)
+  console.log(`Items: ${cluster.members.length}`)
+}
+
+// Find related documents
+const docId = await brain.addNoun("Machine learning guide")
+const similar = await neural.neighbors(docId, 5)
+// Returns 5 most similar documents
+
+// Detect anomalies in data
+const anomalies = await neural.outliers(0.2)
+console.log(`Found ${anomalies.length} outliers`)
+```
+
 ## 🔌 Augmentations
 
 Extend Brainy with powerful augmentations:

package/dist/augmentations/brainyAugmentation.d.ts

@@ -130,6 +130,9 @@ export declare abstract class BaseAugmentation implements BrainyAugmentation {
     abstract metadata: 'none' | 'readonly' | MetadataAccess;
     abstract operations: ('add' | 'addNoun' | 'addVerb' | 'saveNoun' | 'saveVerb' | 'updateMetadata' | 'delete' | 'deleteVerb' | 'clear' | 'get' | 'search' | 'searchText' | 'searchByNounTypes' | 'findSimilar' | 'searchWithCursor' | 'relate' | 'getConnections' | 'storage' | 'backup' | 'restore' | 'all')[];
     abstract priority: number;
+    category: 'internal' | 'core' | 'premium' | 'community' | 'external';
+    description: string;
+    enabled: boolean;
     protected context?: AugmentationContext;
     protected isInitialized: boolean;
     initialize(context: AugmentationContext): Promise<void>;
@@ -199,6 +202,17 @@ export declare class AugmentationRegistry {
      * Get all registered augmentations
      */
     getAll(): BrainyAugmentation[];
+    /**
+     * Get augmentation info for listing
+     */
+    getInfo(): Array<{
+        name: string;
+        type: string;
+        enabled: boolean;
+        description: string;
+        category: string;
+        priority: number;
+    }>;
     /**
      * Get augmentations by name
      */

package/dist/augmentations/brainyAugmentation.js

@@ -16,6 +16,10 @@
  */
 export class BaseAugmentation {
     constructor() {
+        // Metadata for augmentation listing and management
+        this.category = 'core';
+        this.description = '';
+        this.enabled = true;
         this.isInitialized = false;
     }
     async initialize(context) {
@@ -124,6 +128,22 @@ export class AugmentationRegistry {
     getAll() {
         return [...this.augmentations];
     }
+    /**
+     * Get augmentation info for listing
+     */
+    getInfo() {
+        return this.augmentations.map(aug => {
+            const baseAug = aug;
+            return {
+                name: aug.name,
+                type: baseAug.category || 'core',
+                enabled: baseAug.enabled !== false,
+                description: baseAug.description || `${aug.name} augmentation`,
+                category: baseAug.category || 'core',
+                priority: aug.priority
+            };
+        });
+    }
     /**
      * Get augmentations by name
      */

package/dist/augmentations/cacheAugmentation.d.ts

@@ -31,6 +31,8 @@ export declare class CacheAugmentation extends BaseAugmentation {
     readonly metadata: "none";
     operations: ("search" | "add" | "delete" | "clear" | "all")[];
     readonly priority = 50;
+    readonly category: "core";
+    readonly description = "Transparent search result caching with automatic invalidation";
     private searchCache;
     private config;
     constructor(config?: CacheConfig);

package/dist/augmentations/cacheAugmentation.js

@@ -26,6 +26,9 @@ export class CacheAugmentation extends BaseAugmentation {
         this.metadata = 'none'; // Cache doesn't access metadata
         this.operations = ['search', 'add', 'delete', 'clear', 'all'];
         this.priority = 50; // Mid-priority, runs after data operations
+        // Augmentation metadata
+        this.category = 'core';
+        this.description = 'Transparent search result caching with automatic invalidation';
         this.searchCache = null;
         this.config = {
             maxSize: 1000,

package/dist/augmentations/indexAugmentation.d.ts

@@ -32,6 +32,8 @@ export declare class IndexAugmentation extends BaseAugmentation {
     readonly timing: "after";
     operations: ("add" | "updateMetadata" | "delete" | "clear" | "all")[];
     readonly priority = 60;
+    readonly category: "core";
+    readonly description = "Fast metadata field indexing for O(1) filtering and lookups";
     private metadataIndex;
     private config;
     private flushTimer;

package/dist/augmentations/indexAugmentation.js

@@ -26,6 +26,9 @@ export class IndexAugmentation extends BaseAugmentation {
         this.timing = 'after';
         this.operations = ['add', 'updateMetadata', 'delete', 'clear', 'all'];
         this.priority = 60; // Run after data operations
+        // Augmentation metadata
+        this.category = 'core';
+        this.description = 'Fast metadata field indexing for O(1) filtering and lookups';
         this.metadataIndex = null;
         this.flushTimer = null;
         this.config = {

package/dist/augmentations/intelligentVerbScoringAugmentation.d.ts

@@ -57,7 +57,8 @@ export declare class IntelligentVerbScoringAugmentation extends BaseAugmentation
     };
     operations: ("addVerb" | "relate")[];
     priority: number;
-    get enabled(): boolean;
+    readonly category: "core";
+    readonly description = "AI-powered intelligent scoring for relationship strength analysis";
     private config;
     private relationshipStats;
     private metrics;

package/dist/augmentations/intelligentVerbScoringAugmentation.js

@@ -12,10 +12,6 @@
  */
 import { BaseAugmentation } from './brainyAugmentation.js';
 export class IntelligentVerbScoringAugmentation extends BaseAugmentation {
-    // Add enabled property for backward compatibility
-    get enabled() {
-        return this.config.enabled;
-    }
     constructor(config = {}) {
         super();
         this.name = 'IntelligentVerbScoring';
@@ -26,6 +22,9 @@ export class IntelligentVerbScoringAugmentation extends BaseAugmentation {
         }; // Adds scoring metadata to verbs
         this.operations = ['addVerb', 'relate'];
         this.priority = 10; // Enhancement feature - runs after core operations
+        // Augmentation metadata
+        this.category = 'core';
+        this.description = 'AI-powered intelligent scoring for relationship strength analysis';
         this.relationshipStats = new Map();
         this.metrics = {
             relationshipsScored: 0,
@@ -59,6 +58,8 @@ export class IntelligentVerbScoringAugmentation extends BaseAugmentation {
             maxWeight: config.maxWeight ?? 1.0,
             baseWeight: config.baseWeight ?? 0.5
         };
+        // Set enabled property based on config
+        this.enabled = this.config.enabled;
     }
     async onInitialize() {
         if (this.config.enabled) {

package/dist/augmentations/universalDisplayAugmentation.d.ts

@@ -39,6 +39,8 @@ export declare class UniversalDisplayAugmentation extends BaseAugmentation {
     readonly priority = 50;
     readonly metadata: MetadataAccess;
     operations: any;
+    readonly category: "core";
+    readonly description = "AI-powered intelligent display fields for enhanced data visualization";
     computedFields: {
         display: {
             title: {

package/dist/augmentations/universalDisplayAugmentation.js

@@ -45,6 +45,9 @@ export class UniversalDisplayAugmentation extends BaseAugmentation {
             writes: ['_display'] // Cache computed fields in isolated namespace
         };
         this.operations = ['get', 'search', 'findSimilar', 'getVerb', 'addNoun', 'addVerb'];
+        // Augmentation metadata
+        this.category = 'core';
+        this.description = 'AI-powered intelligent display fields for enhanced data visualization';
         // Computed fields declaration for TypeScript support and discovery
         this.computedFields = {
             display: {

package/dist/augmentations/walAugmentation.d.ts

@@ -27,6 +27,8 @@ export declare class WALAugmentation extends BaseAugmentation {
     metadata: "readonly";
     operations: ("addNoun" | "addVerb" | "saveNoun" | "saveVerb" | "updateMetadata" | "delete" | "deleteVerb" | "clear")[];
     priority: number;
+    readonly category: "internal";
+    readonly description = "Write-ahead logging for durability and crash recovery";
     private config;
     private currentLogId;
     private operationCounter;

package/dist/augmentations/walAugmentation.js

@@ -20,6 +20,9 @@ export class WALAugmentation extends BaseAugmentation {
         this.metadata = 'readonly'; // Reads metadata for logging/recovery
         this.operations = ['addNoun', 'addVerb', 'saveNoun', 'saveVerb', 'updateMetadata', 'delete', 'deleteVerb', 'clear'];
         this.priority = 100; // Critical system operation - highest priority
+        // Augmentation metadata
+        this.category = 'internal';
+        this.description = 'Write-ahead logging for durability and crash recovery';
         this.operationCounter = 0;
         this.isRecovering = false;
         this.config = {

package/dist/brainyData.d.ts

@@ -332,7 +332,7 @@ export interface BrainyDataConfig {
     intelligentVerbScoring?: {
         /**
          * Whether to enable intelligent verb scoring
-         * Default: false (off by default)
+         * Default: true (enabled by default for better relationship quality)
          */
         enabled?: boolean;
         /**

package/dist/brainyData.js

@@ -296,11 +296,11 @@ export class BrainyData {
             ttl: 5000,
             maxSize: 1000
         }));
-        // Priority 10: Enhancement features  
-        const intelligentVerbAugmentation = new IntelligentVerbScoringAugmentation(this.config.intelligentVerbScoring || { enabled: false });
+        // Priority 10: Core relationship quality features  
+        const intelligentVerbAugmentation = new IntelligentVerbScoringAugmentation(this.config.intelligentVerbScoring || { enabled: true });
         this.augmentations.register(intelligentVerbAugmentation);
-        // Store reference if intelligent verb scoring is enabled
-        if (this.config.intelligentVerbScoring?.enabled) {
+        // Store reference if intelligent verb scoring is enabled (enabled by default)
+        if (this.config.intelligentVerbScoring?.enabled !== false) {
             this.intelligentVerbScoring = intelligentVerbAugmentation.getScoring();
         }
     }
@@ -6166,7 +6166,13 @@ export class BrainyData {
      * @returns Array of augmentations with name, type, and enabled status
      */
     listAugmentations() {
-        return augmentationPipeline.listAugmentationsWithStatus();
+        // Use the real augmentation registry instead of deprecated pipeline
+        return this.augmentations.getInfo().map(aug => ({
+            name: aug.name,
+            type: aug.category, // Map category to type for backward compatibility
+            enabled: aug.enabled,
+            description: aug.description
+        }));
     }
     /**
      * Enable all augmentations of a specific type

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. 31 nouns × 40 verbs for infinite expressiveness.",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -55,7 +55,7 @@
     }
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.0.0"
   },
   "scripts": {
     "build": "npm run build:patterns:if-needed && tsc",