@soulcraft/brainy 0.33.0 → 0.35.0

package/dist/utils/embedding.d.ts

@@ -2,6 +2,7 @@
  * Embedding functions for converting data to vectors
  */
 import { EmbeddingFunction, EmbeddingModel, Vector } from '../coreTypes.js';
+import { ModelLoadOptions } from './robustModelLoader.js';
 /**
  * TensorFlow Universal Sentence Encoder embedding model
  * This model provides high-quality text embeddings using TensorFlow.js
@@ -10,6 +11,10 @@ import { EmbeddingFunction, EmbeddingModel, Vector } from '../coreTypes.js';
  * This implementation attempts to use GPU processing when available for better performance,
  * falling back to CPU processing for compatibility across all environments.
  */
+export interface UniversalSentenceEncoderOptions extends ModelLoadOptions {
+    /** Whether to enable verbose logging */
+    verbose?: boolean;
+}
 export declare class UniversalSentenceEncoder implements EmbeddingModel {
     private model;
     private initialized;
@@ -17,13 +22,12 @@ export declare class UniversalSentenceEncoder implements EmbeddingModel {
     private use;
     private backend;
     private verbose;
+    private robustLoader;
     /**
      * Create a new UniversalSentenceEncoder instance
-     * @param options Configuration options
+     * @param options Configuration options including reliability settings
      */
-    constructor(options?: {
-        verbose?: boolean;
-    });
+    constructor(options?: UniversalSentenceEncoderOptions);
     /**
      * Add polyfills and patches for TensorFlow.js compatibility
      * This addresses issues with TensorFlow.js across all server environments
@@ -44,13 +48,10 @@ export declare class UniversalSentenceEncoder implements EmbeddingModel {
      */
     private logger;
     /**
-     * Load the Universal Sentence Encoder model with retry logic
-     * This helps handle network failures and JSON parsing errors from TensorFlow Hub
-     * @param loadFunction The function to load the model
-     * @param maxRetries Maximum number of retry attempts
-     * @param baseDelay Base delay in milliseconds for exponential backoff
+     * Load the Universal Sentence Encoder model with robust retry and fallback mechanisms
+     * @param loadFunction The function to load the model from TensorFlow Hub
      */
-    private loadModelWithRetry;
+    private loadModelFromLocal;
     /**
      * Initialize the embedding model
      */
@@ -59,13 +60,6 @@ export declare class UniversalSentenceEncoder implements EmbeddingModel {
      * Embed text into a vector using Universal Sentence Encoder
      * @param data Text to embed
      */
-    /**
-     * Generate a deterministic vector from a string
-     * This is used as a fallback when the Universal Sentence Encoder is not available
-     * @param text Input text
-     * @returns A 512-dimensional vector derived from the text
-     */
-    private generateFallbackVector;
     embed(data: string | string[]): Promise<Vector>;
     /**
      * Embed multiple texts into vectors using Universal Sentence Encoder

package/dist/utils/embedding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"embedding.d.ts","sourceRoot":"","sources":["../../src/utils/embedding.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAI3E;;;;;;;GAOG;AACH,qBAAa,wBAAyB,YAAW,cAAc;IAC7D,OAAO,CAAC,KAAK,CAAY;IACzB,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,EAAE,CAAY;IACtB,OAAO,CAAC,GAAG,CAAY;IACvB,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,OAAO,CAAgB;IAE/B;;;OAGG;gBACS,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAO;IAI/C;;;;;;;;OAQG;IACH,OAAO,CAAC,+BAA+B;IA4CvC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAczB;;;OAGG;IACH,OAAO,CAAC,MAAM;IAWd;;;;;;OAMG;YACW,kBAAkB;IAkIhC;;OAEG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAgKlC;;;OAGG;IACH;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;IA0CjB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAyG5D;;;;;OAKG;IACU,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAoH/D;;OAEG;IACU,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAiBtC;AAsID;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,CAAC,EAAE,cAAc,GACrB,iBAAiB,CASnB;AAcD,wBAAgB,iCAAiC,CAAC,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,iBAAiB,CAiCxG;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,iBAAiB,CAElG;AAED;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBAAiD,CAAA;AAexF,wBAAgB,4BAA4B,CAAC,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,CACjF,SAAS,EAAE,MAAM,EAAE,KAChB,OAAO,CAAC,MAAM,EAAE,CAAC,CA2BrB;AAED;;;;;;;GAOG;AACH,wBAAgB,gCAAgC,CAAC,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,CACrF,SAAS,EAAE,MAAM,EAAE,KAChB,OAAO,CAAC,MAAM,EAAE,CAAC,CAErB;AAED;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,cAX7B,MAAM,EAAE,KAChB,OAAO,CAAC,MAAM,EAAE,CAU0D,CAAA;AAE/E;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,cAAc,GACpB,iBAAiB,CAUnB"}
+{"version":3,"file":"embedding.d.ts","sourceRoot":"","sources":["../../src/utils/embedding.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAG3E,OAAO,EAEL,gBAAgB,EAGjB,MAAM,wBAAwB,CAAA;AAE/B;;;;;;;GAOG;AACH,MAAM,WAAW,+BAAgC,SAAQ,gBAAgB;IACvE,wCAAwC;IACxC,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,qBAAa,wBAAyB,YAAW,cAAc;IAC7D,OAAO,CAAC,KAAK,CAAY;IACzB,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,EAAE,CAAY;IACtB,OAAO,CAAC,GAAG,CAAY;IACvB,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,YAAY,CAAmB;IAEvC;;;OAGG;gBACS,OAAO,GAAE,+BAAoC;IAiBzD;;;;;;;;OAQG;IACH,OAAO,CAAC,+BAA+B;IA4CvC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAczB;;;OAGG;IACH,OAAO,CAAC,MAAM;IAWd;;;OAGG;YACW,kBAAkB;IAmChC;;OAEG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA0LlC;;;OAGG;IACU,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAmF5D;;;;;OAKG;IACU,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAwF/D;;OAEG;IACU,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAiBtC;AAuID;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,CAAC,EAAE,cAAc,GACrB,iBAAiB,CASnB;AAcD,wBAAgB,iCAAiC,CAC/C,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAClC,iBAAiB,CAuCnB;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAClC,iBAAiB,CAEnB;AAED;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBACR,CAAA;AAe/B,wBAAgB,4BAA4B,CAC1C,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAClC,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAyC5C;AAED;;;;;;;GAOG;AACH,wBAAgB,gCAAgC,CAC9C,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAClC,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAE5C;AAED;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,cAV3B,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,EAAE,CAUmC,CAAA;AAE/E;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,cAAc,GACpB,iBAAiB,CAUnB"}

package/dist/utils/robustModelLoader.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Robust Model Loader - Enhanced model loading with retry mechanisms and fallbacks
+ *
+ * This module provides a more reliable way to load TensorFlow models with:
+ * - Exponential backoff retry mechanisms
+ * - Timeout handling
+ * - Multiple fallback strategies
+ * - Better error handling and logging
+ * - Optional local model bundling support
+ */
+import { EmbeddingModel } from '../coreTypes.js';
+export interface ModelLoadOptions {
+    /** Maximum number of retry attempts */
+    maxRetries?: number;
+    /** Initial retry delay in milliseconds */
+    initialRetryDelay?: number;
+    /** Maximum retry delay in milliseconds */
+    maxRetryDelay?: number;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Whether to use exponential backoff */
+    useExponentialBackoff?: boolean;
+    /** Fallback model URLs to try if primary fails */
+    fallbackUrls?: string[];
+    /** Whether to enable verbose logging */
+    verbose?: boolean;
+    /** Whether to prefer local bundled model if available */
+    preferLocalModel?: boolean;
+}
+export interface RetryConfig {
+    attempt: number;
+    maxRetries: number;
+    delay: number;
+    error: Error;
+}
+export declare class RobustModelLoader {
+    private options;
+    private loadAttempts;
+    constructor(options?: ModelLoadOptions);
+    /**
+     * Load a model with robust retry and fallback mechanisms
+     */
+    loadModel(primaryLoadFunction: () => Promise<EmbeddingModel>, modelIdentifier?: string): Promise<EmbeddingModel>;
+    /**
+     * Load a model with retry logic and exponential backoff
+     */
+    private loadWithRetries;
+    /**
+     * Try to load a locally bundled model
+     */
+    private tryLoadLocalBundledModel;
+    /**
+     * Load model from a specific URL
+     */
+    private loadFromUrl;
+    /**
+     * Create a model wrapper that matches the Universal Sentence Encoder interface
+     */
+    private createModelWrapper;
+    /**
+     * Apply timeout to a promise
+     */
+    private withTimeout;
+    /**
+     * Calculate retry delay with exponential backoff
+     */
+    private calculateRetryDelay;
+    /**
+     * Sleep for specified milliseconds
+     */
+    private sleep;
+    /**
+     * Log message if verbose mode is enabled
+     */
+    private log;
+    /**
+     * Get loading statistics
+     */
+    getLoadingStats(): {
+        [key: string]: number;
+    };
+    /**
+     * Reset loading statistics
+     */
+    resetStats(): void;
+}
+/**
+ * Create a robust model loader with sensible defaults
+ */
+export declare function createRobustModelLoader(options?: ModelLoadOptions): RobustModelLoader;
+/**
+ * Utility function to create fallback URLs for Universal Sentence Encoder
+ */
+export declare function getUniversalSentenceEncoderFallbacks(): string[];

package/dist/utils/robustModelLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"robustModelLoader.d.ts","sourceRoot":"","sources":["../../src/utils/robustModelLoader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAMhD,MAAM,WAAW,gBAAgB;IAC/B,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,0CAA0C;IAC1C,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,0CAA0C;IAC1C,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yCAAyC;IACzC,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB,wCAAwC;IACxC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,yDAAyD;IACzD,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,KAAK,CAAA;CACb;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,YAAY,CAAiC;gBAEzC,OAAO,GAAE,gBAAqB;IAa1C;;OAEG;IACG,SAAS,CACb,mBAAmB,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,EAClD,eAAe,GAAE,MAAkB,GAClC,OAAO,CAAC,cAAc,CAAC;IAqD1B;;OAEG;YACW,eAAe;IA2C7B;;OAEG;YACW,wBAAwB;IAwEtC;;OAEG;YACW,WAAW;IAMzB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAoB1B;;OAEG;YACW,WAAW;IAUzB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAiB3B;;OAEG;IACH,OAAO,CAAC,KAAK;IAIb;;OAEG;IACH,OAAO,CAAC,GAAG;IAMX;;OAEG;IACH,eAAe,IAAI;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE;IAQ5C;;OAEG;IACH,UAAU,IAAI,IAAI;CAGnB;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,iBAAiB,CAErF;AAED;;GAEG;AACH,wBAAgB,oCAAoC,IAAI,MAAM,EAAE,CAM/D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "description": "A vector graph database using HNSW indexing with Origin Private File System storage",
   "main": "dist/unified.js",
   "module": "dist/unified.js",
@@ -54,26 +54,7 @@
     "build:browser": "BUILD_TYPE=browser rollup -c rollup.config.js",
     "start": "node dist/unified.js",
     "demo": "npm run build && npm run build:browser && npx http-server -o /demo/index.html",
-    "release": "standard-version",
-    "release:patch": "standard-version --release-as patch",
-    "release:minor": "standard-version --release-as minor",
-    "release:major": "standard-version --release-as major",
-    "release:dry-run": "standard-version --dry-run",
-    "github-release": "node scripts/create-github-release.js",
-    "changelog:check": "echo 'Changelog is now automatically generated from commit messages'",
-    "lint": "eslint --ext .ts,.js src/",
-    "lint:fix": "eslint --ext .ts,.js src/ --fix",
-    "format": "prettier --write \"src/**/*.{ts,js}\"",
-    "check:format": "prettier --check \"src/**/*.{ts,js}\"",
-    "check:style": "node scripts/check-code-style.js",
     "prepare": "npm run build",
-    "deploy": "npm run build && npm publish",
-    "workflow": "node scripts/release-workflow.js",
-    "workflow:patch": "node scripts/release-workflow.js patch",
-    "workflow:minor": "node scripts/release-workflow.js minor",
-    "workflow:major": "node scripts/release-workflow.js major",
-    "workflow:dry-run": "npm run build && npm test && npm run release:dry-run",
-    "dry-run": "npm pack --dry-run",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:ui": "vitest --ui",
@@ -90,7 +71,27 @@
     "test:environments": "vitest run tests/multi-environment.test.ts",
     "test:specialized": "vitest run tests/specialized-scenarios.test.ts",
     "test:performance": "vitest run tests/performance.test.ts",
-    "test:comprehensive": "npm run test:error-handling && npm run test:edge-cases && npm run test:storage && npm run test:environments && npm run test:specialized"
+    "test:comprehensive": "npm run test:error-handling && npm run test:edge-cases && npm run test:storage && npm run test:environments && npm run test:specialized",
+    "_generate-pdf": "node dev/scripts/generate-architecture-pdf.js",
+    "_release": "standard-version",
+    "_release:patch": "standard-version --release-as patch",
+    "_release:minor": "standard-version --release-as minor",
+    "_release:major": "standard-version --release-as major",
+    "_release:dry-run": "standard-version --dry-run",
+    "_github-release": "node scripts/create-github-release.js",
+    "_changelog:check": "echo 'Changelog is now automatically generated from commit messages'",
+    "_lint": "eslint --ext .ts,.js src/",
+    "_lint:fix": "eslint --ext .ts,.js src/ --fix",
+    "_format": "prettier --write \"src/**/*.{ts,js}\"",
+    "_check:format": "prettier --check \"src/**/*.{ts,js}\"",
+    "_check:style": "node scripts/check-code-style.js",
+    "_deploy": "npm run build && npm publish",
+    "_workflow": "node scripts/release-workflow.js",
+    "_workflow:patch": "node scripts/release-workflow.js patch",
+    "_workflow:minor": "node scripts/release-workflow.js minor",
+    "_workflow:major": "node scripts/release-workflow.js major",
+    "_workflow:dry-run": "npm run build && npm test && npm run _release:dry-run",
+    "_dry-run": "npm pack --dry-run"
   },
   "keywords": [
     "vector-database",
@@ -151,7 +152,7 @@
     "happy-dom": "^18.0.1",
     "jsdom": "^26.1.0",
     "node-fetch": "^3.3.2",
-    "puppeteer": "^22.5.0",
+    "puppeteer": "^22.15.0",
     "rollup": "^4.13.0",
     "rollup-plugin-terser": "^7.0.2",
     "standard-version": "^9.5.0",