brainy/brainy-models-package

@soulcraft/brainy-models

Pre-bundled TensorFlow models for maximum reliability with Brainy vector database.

Overview

This package provides offline access to the Universal Sentence Encoder model, eliminating network dependencies and ensuring consistent performance. It's designed as an optional companion to the main @soulcraft/brainy package for applications requiring maximum reliability.

Features

• 🔒 Maximum Reliability: Fully offline model loading with zero network dependencies
• 📦 Pre-bundled Models: Complete Universal Sentence Encoder model (~25MB) included
• 🗜️ Model Compression: Multiple optimized variants (float16, int8) for different use cases
• ⚡ Performance Optimized: Use case-specific optimizations for memory and speed
• 🛠️ Easy Integration: Drop-in replacement for online model loading
• 📊 Comprehensive Metrics: Detailed model information and performance statistics

Installation

npm install @soulcraft/brainy-models

Prerequisites

• Node.js >= 18.0.0
• @soulcraft/brainy >= 0.33.0

Quick Start

Basic Usage

import { BundledUniversalSentenceEncoder } from '@soulcraft/brainy-models'

// Create encoder instance
const encoder = new BundledUniversalSentenceEncoder({
  verbose: true,
  preferCompressed: false
})

// Load the bundled model
await encoder.load()

// Generate embeddings
const texts = ['Hello world', 'How are you?', 'Machine learning is amazing']
const embeddings = await encoder.embedToArrays(texts)

console.log(`Generated ${embeddings.length} embeddings of ${embeddings[0].length} dimensions`)

// Clean up
encoder.dispose()

Integration with Brainy

import Brainy from '@soulcraft/brainy'
import { BundledUniversalSentenceEncoder } from '@soulcraft/brainy-models'

// Create bundled encoder
const bundledEncoder = new BundledUniversalSentenceEncoder({ verbose: true })
await bundledEncoder.load()

// Use with Brainy (custom integration)
const brainy = new Brainy({
  // Configure Brainy to use the bundled encoder
  customEmbedding: async (texts) => {
    return await bundledEncoder.embedToArrays(texts)
  }
})

Using Compressed Models

import { BundledUniversalSentenceEncoder } from '@soulcraft/brainy-models'

// Use compressed model for memory-constrained environments
const encoder = new BundledUniversalSentenceEncoder({
  preferCompressed: true,
  verbose: true
})

await encoder.load()

// The encoder will automatically use the most appropriate compressed variant
const embeddings = await encoder.embedToArrays(['Sample text'])

API Reference

BundledUniversalSentenceEncoder

Main class for loading and using bundled models.

Constructor

new BundledUniversalSentenceEncoder(options)

Options:

• verbose?: boolean - Enable detailed logging (default: false)
• preferCompressed?: boolean - Prefer compressed model variants (default: false)

Methods

load(): Promise<void>

Load the bundled model from local files.

await encoder.load()

embed(texts: string[]): Promise<tf.Tensor2D>

Generate embeddings as TensorFlow tensors.

const embeddings = await encoder.embed(['Hello world'])
// Remember to dispose of tensors when done
embeddings.dispose()

embedToArrays(texts: string[]): Promise<number[][]>

Generate embeddings as JavaScript arrays (automatically disposes tensors).

const embeddings = await encoder.embedToArrays(['Hello world'])
console.log(embeddings[0].length) // 512

getMetadata(): ModelMetadata | null

Get model metadata information.

const metadata = encoder.getMetadata()
console.log(metadata?.dimensions) // 512

isLoaded(): boolean

Check if the model is loaded.

if (encoder.isLoaded()) {
  // Model is ready to use
}

getModelInfo(): { inputShape: number[], outputShape: number[] } | null

Get model input/output shape information.

const info = encoder.getModelInfo()
console.log(info?.outputShape) // [-1, 512]

dispose(): void

Clean up model resources.

encoder.dispose()

ModelCompressor

Utility class for model compression and optimization.

Static Methods

quantizeModel(modelPath: string, outputPath: string, options?): Promise<void>

Compress a model using quantization.

import { ModelCompressor } from '@soulcraft/brainy-models'

await ModelCompressor.quantizeModel(
  '/path/to/model.json',
  '/path/to/compressed/model.json',
  { dtype: 'int8' }
)

getModelSize(modelPath: string): Promise<ModelSizeInfo>

Get detailed model size information.

const sizeInfo = await ModelCompressor.getModelSize('/path/to/model.json')
console.log(`Total size: ${sizeInfo.totalSize} bytes`)

Utility Functions

utils.checkModelsAvailable(): boolean

Check if bundled models are available.

import { utils } from '@soulcraft/brainy-models'

if (utils.checkModelsAvailable()) {
  console.log('Models are ready to use')
}

utils.listAvailableModels(): string[]

List available bundled models.

const models = utils.listAvailableModels()
console.log('Available models:', models)

Model Variants

The package includes multiple model variants optimized for different use cases:

Original (Float32)

• Size: ~25MB
• Use case: Maximum accuracy
• Memory: High
• Speed: Fast

Float16 Compressed

• Size: ~12-15MB
• Use case: Balanced performance
• Memory: Medium
• Speed: Fast

Int8 Quantized

• Size: ~6-8MB
• Use case: Memory-constrained environments
• Memory: Low
• Speed: Medium

Scripts

The package includes several utility scripts:

Download Models

Download the complete Universal Sentence Encoder model:

npm run download-models

Compress Models

Create optimized model variants:

npm run compress-models

Test Models

Verify model functionality:

npm test

Development

Building the Package

npm run build

Running Tests

npm test

Creating a Release

npm run pack

Comparison with Online Loading

Feature	Online Loading	Bundled Models
Reliability	Network dependent	100% offline
First load time	30-60 seconds	< 1 second
Subsequent loads	Cached (~1 second)	< 1 second
Package size	~3KB	~25MB
Network required	Yes (first time)	No
Offline support	Limited	Complete

Use Cases

When to Use Bundled Models

• ✅ Production applications requiring maximum reliability
• ✅ Offline or air-gapped environments
• ✅ Applications with strict SLA requirements
• ✅ Edge computing and IoT devices
• ✅ Development environments with unreliable internet

When to Use Online Loading

• ✅ Development and prototyping
• ✅ Applications where package size matters
• ✅ Environments with reliable internet connectivity
• ✅ Applications that rarely use embeddings

Troubleshooting

Model Not Found Error

Error: Bundled model not found. Please run "npm run download-models"

Solution: Run the download script to fetch the model files:

cd node_modules/@soulcraft/brainy-models
npm run download-models

Memory Issues

If you encounter memory issues, try using compressed models:

const encoder = new BundledUniversalSentenceEncoder({
  preferCompressed: true
})

Performance Optimization

For optimal performance:

1. Memory-constrained: Use int8 quantized models
2. Speed-critical: Use original float32 models
3. Balanced: Use float16 compressed models

License

MIT

Contributing

Contributions are welcome! Please see the main Brainy repository for contribution guidelines.

Support

For issues and questions:

• GitHub Issues
• Documentation