David Snelling 885a8b403a **feat(docs): add compatibility and testing guides; enforce Universal Sentence Encoder usage**

- Added new documentation files:
  - `COMPATIBILITY.md` detailing environment-specific compatibility and behavior (Node.js, Browser, Worker).
  - `TESTING.md` providing instructions for verifying cache detection across environments.
  - Created browser (`test-browser-cache-detection.html`) and worker (`test-worker-cache-detection.html`) test scripts to validate cache mechanisms.

- Removed fallback mechanisms for embedding:
  - Updated `embedding.ts` to enforce strict usage of Universal Sentence Encoder (USE).
  - Fallback methods (`generateFallbackVector`) and related logic have been removed.
  - Errors are thrown when USE initialization or embedding fails, ensuring stricter reliability.

- Improved error handling:
  - Standardized error throwing for all USE-related failures across single and batch embeddings.
  - Logging updated to reflect critical embedding issues without allowing degraded operations.

**Purpose**: Improve documentation for environment compatibility and testing while enforcing consistent use of Universal Sentence Encoder for deterministic embeddings, removing unreliable fallback mechanisms.

2025-08-01 11:02:01 -07:00

2.5 KiB

Raw Blame History

Testing Brainy Across Different Environments

This document provides instructions for testing Brainy's cache detection functionality across different environments.

Testing in Node.js Environment

To test Brainy in a Node.js environment:

Build the project:
```
npm run build
```
Run the Node.js test script:
```
node test-cache-detection.js
```

Expected output:

Brainy: Successfully patched TensorFlow.js PlatformNode at module load time
Applied TensorFlow.js patch via ES modules in setup.ts
Brainy running in Node.js environment
Creating BrainyData instance...
BrainyData instance created successfully!
Test completed successfully!

Testing in Browser Environment

To test Brainy in a browser environment:

Build the project:
```
npm run build
```
Start a local web server:
```
npx http-server -p 8080
```

Open the browser test page:

http://localhost:8080/test-browser-cache-detection.html

Click the "Run Test" button on the page.
Expected results:
- The page should display success messages
- No errors should appear in the browser console
- You should see "BrainyData instance created successfully!" and "Test completed successfully!"

Testing in Web Worker Environment

To test Brainy in a Web Worker environment:

Build the project:
```
npm run build
```
Start a local web server:
```
npx http-server -p 8080
```

Open the worker test page:

http://localhost:8080/test-worker-cache-detection.html

Click the "Run Test" button on the page.
Expected results:
- The page should display success messages from the worker
- No errors should appear in the browser console
- You should see "BrainyData instance created successfully!" and "Test completed successfully!"

Compatibility Notes

Brainy's cache detection has been designed to work across all environments:

Node.js Environment:
- Uses fixed default memory values (8GB total, 4GB free) for cache size calculation
- This approach ensures compatibility with ES modules
Browser Environment:
- Uses navigator.deviceMemory API when available
- Falls back to conservative defaults when the API is not available
Worker Environment:
- Uses a more conservative approach to cache sizing
- Automatically detects the worker environment and adjusts accordingly

The cache manager automatically detects the environment and adjusts its behavior to ensure optimal performance in each context.