@soulcraft/brainy 0.9.22 → 0.9.25

package/README.md

@@ -3,10 +3,10 @@
 <br/><br/>
 
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D24.0.0-brightgreen.svg)](https://nodejs.org/)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D23.0.0-brightgreen.svg)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.1.6-blue.svg)](https://www.typescriptlang.org/)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
-[![npm](https://img.shields.io/badge/npm-v0.9.22-blue.svg)](https://www.npmjs.com/package/@soulcraft/brainy)
+[![npm](https://img.shields.io/badge/npm-v0.9.25-blue.svg)](https://www.npmjs.com/package/@soulcraft/brainy)
 
 [//]: # ([![Cartographer]&#40;https://img.shields.io/badge/Cartographer-Official%20Standard-brightgreen&#41;]&#40;https://github.com/sodal-project/cartographer&#41;)
 
@@ -280,43 +280,6 @@ Brainy's pipeline is designed to handle streaming data efficiently:
     - Automatic thread management based on environment capabilities
     - Example: `executeTypedPipeline(augmentations, method, args, { mode: ExecutionMode.THREADED })`
 
-### Build System
-
-Brainy uses a modern build system that optimizes for both Node.js and browser environments:
-
-1. **ES Modules**
-    - Built as ES modules for maximum compatibility
-    - Works in modern browsers and Node.js environments
-    - Separate optimized builds for browser and Node.js
-
-2. **Environment-Specific Builds**
-    - **Node.js Build**: Optimized for server environments with full functionality
-    - **Browser Build**: Optimized for browser environments with reduced bundle size
-    - **CLI Build**: Separate build for command-line interface functionality
-    - Conditional exports in package.json for automatic environment detection
-
-3. **Modular Architecture**
-    - Core functionality and CLI are built separately
-    - CLI (4MB) is only included when explicitly imported or used from command line
-    - Reduced bundle size for browser and Node.js applications
-
-4. **Environment Detection**
-    - Automatically detects whether it's running in a browser or Node.js
-    - Loads appropriate dependencies and functionality based on the environment
-    - Provides consistent API across all environments
-
-5. **TypeScript**
-    - Written in TypeScript for type safety and better developer experience
-    - Generates type definitions for TypeScript users
-    - Compiled to ES2020 for modern JavaScript environments
-
-6. **Build Scripts**
-    - `npm run build`: Builds the core library without CLI
-    - `npm run build:browser`: Builds the browser-optimized version
-    - `npm run build:cli`: Builds the CLI version (only needed for CLI usage)
-    - `npm run prepare:cli`: Builds the CLI for command-line usage
-    - `npm run demo`: Builds both core library and browser versions and starts a demo server
-    - GitHub Actions workflow: Automatically deploys the demo directory to GitHub Pages when pushing to the main branch
 
 ### Running the Pipeline
 
@@ -453,10 +416,6 @@ brainy visualize
 brainy visualize --root <id> --depth 3
 ```
 
-### Publishing the CLI Package
-
-If you need to publish the CLI package to npm, please refer to the [CLI Publishing Guide](docs/publishing-cli.md) for
-detailed instructions.
 
 ### Using the CLI in Your Code
 
@@ -473,15 +432,6 @@ import '@soulcraft/brainy/cli'
 This will only build and load the CLI when you explicitly import it, keeping your bundle size small when you don't need
 the CLI.
 
-### Development Usage
-
-```bash
-# Run the CLI directly from the source
-npm run cli help
-
-# Generate a random graph for testing
-npm run cli generate-random-graph --noun-count 20 --verb-count 40
-```
 
 ### Available Commands
 
@@ -1303,74 +1253,14 @@ comprehensive [Scaling Strategy](scalingStrategy.md) document.
 
 - Node.js >= 24.0.0
 
-### Node.js 24 Optimizations
-
-Brainy takes advantage of several optimizations available in Node.js 24:
-
-1. **Improved Worker Threads Performance**: The multithreading system has been completely rewritten to leverage Node.js
-   24's enhanced Worker Threads API, resulting in better performance for compute-intensive operations like embedding
-   generation and vector similarity calculations.
-
-2. **Worker Pool Management**: A sophisticated worker pool system reuses worker threads to minimize the overhead of
-   creating and destroying threads, leading to more efficient resource utilization.
-
-3. **Dynamic Module Imports**: Uses the new `node:` protocol prefix for importing core modules, which provides better
-   performance and more reliable module resolution.
-
-4. **ES Modules Optimizations**: Takes advantage of Node.js 24's improved ESM implementation for faster module loading
-   and execution.
-
-5. **Enhanced Error Handling**: Implements more robust error handling patterns available in Node.js 24 for better
-   stability and debugging.
-
-These optimizations are particularly beneficial for:
-
-- Large-scale vector operations
-- Batch processing of embeddings
-- Real-time data processing pipelines
-- High-throughput search operations
 
 ## Contributing
 
 For detailed contribution guidelines, please see [CONTRIBUTING.md](CONTRIBUTING.md).
 
-We have a [Code of Conduct](CODE_OF_CONDUCT.md) that all contributors are expected to follow.
-
-### Reporting Issues
-
-We use GitHub issues to track bugs and feature requests. Please use the provided issue templates when creating a new
-issue:
-
-- [Bug Report Template](.github/ISSUE_TEMPLATE/bug_report.md)
-- [Feature Request Template](.github/ISSUE_TEMPLATE/feature_request.md)
-
-### Code Style Guidelines
+For developer documentation, including building, testing, and publishing instructions, please see [DEVELOPERS.md](DEVELOPERS.md).
 
-Brainy follows a specific code style to maintain consistency throughout the codebase:
-
-1. **No Semicolons**: All code in the project should avoid using semicolons wherever possible
-2. **Formatting**: The project uses Prettier for code formatting
-3. **Linting**: ESLint is configured with specific rules for the project
-4. **TypeScript Configuration**: Strict type checking enabled with ES2020 target
-5. **Commit Messages**: Use the imperative mood and keep the first line concise
-
-### Development Workflow
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Submit a pull request
-
-### Badge Maintenance
-
-The README badges are automatically updated during the build process:
-
-1. **npm Version Badge**: The npm version badge is automatically updated to match the version in package.json when:
-    - Running `npm run build` (via the prebuild script)
-    - Running `npm version` commands (patch, minor, major)
-    - Manually running `node scripts/generate-version.js`
-
-This ensures that the badge always reflects the current version in package.json, even before publishing to npm.
+We have a [Code of Conduct](CODE_OF_CONDUCT.md) that all contributors are expected to follow.
 
 ## License
 

package/dist/brainy.js

@@ -2900,6 +2900,19 @@ let UniversalSentenceEncoder$1 = class UniversalSentenceEncoder {
         this.use = null;
         this.backend = 'cpu'; // Default to CPU
     }
+    /**
+     * Add polyfills and patches for TensorFlow.js compatibility
+     * This addresses issues with TensorFlow.js in Node.js environments
+     */
+    addNodeCompatibilityPolyfills() {
+        // Only apply in Node.js environment
+        if (typeof process === 'undefined' ||
+            !process.versions ||
+            !process.versions.node) {
+            return;
+        }
+        // No compatibility patches needed - TensorFlow.js now works correctly with Node.js 24+
+    }
     /**
      * Initialize the embedding model
      */
@@ -2916,6 +2929,8 @@ let UniversalSentenceEncoder$1 = class UniversalSentenceEncoder {
                 }
                 originalWarn(message, ...optionalParams);
             };
+            // Add polyfills for TensorFlow.js compatibility
+            this.addNodeCompatibilityPolyfills();
             // TensorFlow.js will use its default EPSILON value
             // Dynamically import TensorFlow.js core module and backends
             // Use type assertions to tell TypeScript these modules exist
@@ -9312,9 +9327,42 @@ class BrainyData {
     }
 }
 
-// We'll dynamically import Node.js built-in modules
+// Import Node.js built-in modules
+// Using require for compatibility with Node.js
 let fs;
 let path;
+// Initialize these modules immediately if in Node.js environment
+if (typeof process !== 'undefined' &&
+    process.versions &&
+    process.versions.node) {
+    try {
+        // Use require for Node.js built-in modules
+        fs = require('fs');
+        path = require('path');
+        // Verify that path has the required methods
+        if (!path || typeof path.resolve !== 'function') {
+            throw new Error('path module is missing required methods');
+        }
+    }
+    catch (e) {
+        console.warn('Failed to load Node.js modules with require:', e);
+        // Try using dynamic import as a fallback
+        try {
+            // Use a synchronous approach to ensure modules are loaded before continuing
+            const pathModule = require('node:path');
+            const fsModule = require('node:fs');
+            path = pathModule;
+            fs = fsModule;
+            // Verify that path has the required methods
+            if (!path || typeof path.resolve !== 'function') {
+                throw new Error('path module from node:path is missing required methods');
+            }
+        }
+        catch (nodeImportError) {
+            console.warn('Failed to load Node.js modules with node: prefix:', nodeImportError);
+        }
+    }
+}
 // Constants for directory and file names
 const ROOT_DIR = 'brainy-data';
 const NOUNS_DIR = 'nouns';
@@ -9355,32 +9403,91 @@ class FileSystemStorage {
             return;
         }
         try {
-            // Dynamically import Node.js built-in modules
-            try {
-                // Import the modules
-                const fsModule = await Promise.resolve().then(function () { return _fsShim$1; });
-                const pathModule = await Promise.resolve().then(function () { return _pathShim$1; });
-                // Assign to our module-level variables
-                fs = fsModule.default || fsModule;
-                path = pathModule.default || pathModule;
-                // Now set up the directory paths
-                const rootDir = this.rootDir || process.cwd();
-                this.rootDir = path.resolve(rootDir, ROOT_DIR);
-                this.nounsDir = path.join(this.rootDir, NOUNS_DIR);
-                this.verbsDir = path.join(this.rootDir, VERBS_DIR);
-                this.metadataDir = path.join(this.rootDir, METADATA_DIR);
-                // Set up noun type directory paths
-                this.personDir = path.join(this.nounsDir, PERSON_DIR);
-                this.placeDir = path.join(this.nounsDir, PLACE_DIR);
-                this.thingDir = path.join(this.nounsDir, THING_DIR);
-                this.eventDir = path.join(this.nounsDir, EVENT_DIR);
-                this.conceptDir = path.join(this.nounsDir, CONCEPT_DIR);
-                this.contentDir = path.join(this.nounsDir, CONTENT_DIR);
-                this.defaultDir = path.join(this.nounsDir, DEFAULT_DIR);
-            }
-            catch (importError) {
-                throw new Error(`Failed to import Node.js modules: ${importError}. This adapter requires a Node.js environment.`);
+            // Check if fs and path modules are available and have required methods
+            if (!fs || !path || typeof path.resolve !== 'function') {
+                console.log('Node.js modules not properly loaded, attempting to load them now');
+                // Try multiple approaches to load the modules
+                const loadAttempts = [
+                    // Attempt 1: Use require
+                    async () => {
+                        console.log('Attempting to load Node.js modules with require()');
+                        const fsModule = require('fs');
+                        const pathModule = require('path');
+                        if (!pathModule || typeof pathModule.resolve !== 'function') {
+                            throw new Error('path.resolve is not a function after require()');
+                        }
+                        return { fs: fsModule, path: pathModule };
+                    },
+                    // Attempt 2: Use require with node: prefix
+                    async () => {
+                        console.log('Attempting to load Node.js modules with require("node:...")');
+                        const fsModule = require('node:fs');
+                        const pathModule = require('node:path');
+                        if (!pathModule || typeof pathModule.resolve !== 'function') {
+                            throw new Error('path.resolve is not a function after require("node:path")');
+                        }
+                        return { fs: fsModule, path: pathModule };
+                    },
+                    // Attempt 3: Use dynamic import
+                    async () => {
+                        console.log('Attempting to load Node.js modules with dynamic import');
+                        const fsModule = await Promise.resolve().then(function () { return _fsShim$1; });
+                        const pathModule = await Promise.resolve().then(function () { return _pathShim$1; });
+                        const fsResolved = fsModule.default || fsModule;
+                        const pathResolved = pathModule.default || pathModule;
+                        if (!pathResolved || typeof pathResolved.resolve !== 'function') {
+                            throw new Error('path.resolve is not a function after dynamic import');
+                        }
+                        return { fs: fsResolved, path: pathResolved };
+                    },
+                    // Attempt 4: Use dynamic import with node: prefix
+                    async () => {
+                        console.log('Attempting to load Node.js modules with dynamic import("node:...")');
+                        const fsModule = await import('node:fs');
+                        const pathModule = await import('node:path');
+                        const fsResolved = fsModule.default || fsModule;
+                        const pathResolved = pathModule.default || pathModule;
+                        if (!pathResolved || typeof pathResolved.resolve !== 'function') {
+                            throw new Error('path.resolve is not a function after dynamic import("node:path")');
+                        }
+                        return { fs: fsResolved, path: pathResolved };
+                    }
+                ];
+                // Try each loading method until one succeeds
+                let lastError = null;
+                for (const loadAttempt of loadAttempts) {
+                    try {
+                        const modules = await loadAttempt();
+                        fs = modules.fs;
+                        path = modules.path;
+                        console.log('Successfully loaded Node.js modules');
+                        break;
+                    }
+                    catch (error) {
+                        lastError = error;
+                        console.warn(`Module loading attempt failed:`, error);
+                        // Continue to the next attempt
+                    }
+                }
+                // If all attempts failed, throw an error
+                if (!fs || !path || typeof path.resolve !== 'function') {
+                    throw new Error(`Failed to import Node.js modules after multiple attempts: ${lastError}. This adapter requires a Node.js environment.`);
+                }
             }
+            // Now set up the directory paths
+            const rootDir = this.rootDir || process.cwd();
+            this.rootDir = path.resolve(rootDir, ROOT_DIR);
+            this.nounsDir = path.join(this.rootDir, NOUNS_DIR);
+            this.verbsDir = path.join(this.rootDir, VERBS_DIR);
+            this.metadataDir = path.join(this.rootDir, METADATA_DIR);
+            // Set up noun type directory paths
+            this.personDir = path.join(this.nounsDir, PERSON_DIR);
+            this.placeDir = path.join(this.nounsDir, PLACE_DIR);
+            this.thingDir = path.join(this.nounsDir, THING_DIR);
+            this.eventDir = path.join(this.nounsDir, EVENT_DIR);
+            this.conceptDir = path.join(this.nounsDir, CONCEPT_DIR);
+            this.contentDir = path.join(this.nounsDir, CONTENT_DIR);
+            this.defaultDir = path.join(this.nounsDir, DEFAULT_DIR);
             // Create directories if they don't exist
             await this.ensureDirectoryExists(this.rootDir);
             await this.ensureDirectoryExists(this.nounsDir);