@masteryhub-its/speakout-local-client-model

Production-ready text moderation library using BERT model with ONNX Runtime. This package provides efficient client-side text moderation capabilities for browser environments using WebAssembly.

Features

• 🚀 Fast Inference: Powered by ONNX Runtime Web with optimized INT8 quantized model
• 🌐 Browser-Ready: Designed for browser environments using WebAssembly
• 📦 Zero Config: Works out of the box with embedded model files - no manual setup required
• 🔒 Type Safe: Full TypeScript support with type definitions included
• ⚡ Efficient: Minimal dependencies and optimized WASM performance
• 🔧 Fully Typed: Written entirely in TypeScript for better developer experience

Installation

npm install @masteryhub-its/speakout-local-client-model

Quick Start

Browser (Vite/React)

import { ClientContentModeration } from '@masteryhub-its/speakout-local-client-model';

const moderation = new ClientContentModeration();

await moderation.initialize();

const result = await moderation.moderate("User input text");

if (result.approved) {
  // Content is safe
} else {
  // Content should be rejected
}

Vite Configuration

For Vite projects, you need to configure WASM asset support. The model files are embedded in the package, so no manual copying is required:

Create or update vite.config.ts:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  assetsInclude: ['**/*.onnx', '**/*.wasm'],
  optimizeDeps: {
    exclude: ['onnxruntime-web'],
  },
  server: {
    fs: {
      // Allow serving files from node_modules (for embedded models)
      allow: ['..'],
    },
  },
});

Initialize with default paths (models are automatically resolved from the package):

import { ClientContentModeration } from '@masteryhub-its/speakout-local-client-model';

const moderation = new ClientContentModeration();

// Uses default paths: /models/bert-mini-moderation-output/model.int8.onnx
await moderation.initialize();

// Or specify custom URLs:
await moderation.initialize(
  '/models/bert-mini-moderation-output/model.int8.onnx',
  '/models/bert-mini-moderation-output/tokenizer.json'
);

Note: Model files are embedded in the package and will be automatically resolved. The package uses import.meta.url to locate models relative to the package location, so they work seamlessly in both development and production builds.

API

ClientContentModeration

Main class for text moderation.

Constructor

new ClientContentModeration(options?: ModerationOptions)

Options:

• modelFilePath?: string - Custom URL to ONNX model file (e.g., "/models/model.onnx")
• tokenizerFilePath?: string - Custom URL to tokenizer file (e.g., "/models/tokenizer.json")
• maxLength?: number - Maximum sequence length (default: 128)
• threshold?: number - Confidence threshold (default: 0.5)

Methods

initialize(modelFilePath?, tokenizerFilePath?): Promise<void>

Initialize the model and tokenizer. This is called automatically on first use, but you can call it explicitly for better error handling.

Parameters:

• modelFilePath?: string - URL to the ONNX model file (default: /models/bert-mini-moderation-output/model.int8.onnx)
• tokenizerFilePath?: string - URL to the tokenizer JSON file (default: /models/bert-mini-moderation-output/tokenizer.json)

moderate(text: string, threshold?: number): Promise<ModerationResult>

Moderate a single text string.

Returns:

{
  approved: boolean;        // Whether content should be approved
  confidence: number;       // Confidence score (0-1)
  probabilities: {
    reject: number;         // Probability of rejection (0-1)
    approve: number;       // Probability of approval (0-1)
  }
}

moderateBatch(texts: string[], threshold?: number): Promise<ModerationResult[]>

Moderate multiple texts in parallel.

dispose(): void

Clean up resources and dispose of the model session.

Examples

Basic Usage

import { ClientContentModeration } from '@masteryhub-its/speakout-local-client-model';

const moderation = new ClientContentModeration();
await moderation.initialize();

const result = await moderation.moderate("This is a test message");
console.log(`Approved: ${result.approved}, Confidence: ${result.confidence}`);

Custom Threshold

const result = await moderation.moderate("User content", 0.7); // 70% threshold

Batch Processing

const texts = [
  "Hello world",
  "This is safe content",
  "Another message"
];

const results = await moderation.moderateBatch(texts);
results.forEach((result, index) => {
  console.log(`Text ${index}: ${result.approved ? 'Approved' : 'Rejected'}`);
});

Custom Model FilePaths

const moderation = new ClientContentModeration({
  modelFilePath: '/FilePath/to/model.onnx',
  tokenizerFilePath: '/FilePath/to/tokenizer.json',
  maxLength: 256,
  threshold: 0.6
});

Development

Building from Source

# Clone the repository
git clone <repository-url>
cd speakout-platform-local-model

# Install dependencies
npm install

# Build the project
npm run build

# Verify package structure
npm run verify

Project Structure

├── src/              # TypeScript source files
│   ├── index.ts      # Main entry point
│   ├── model.ts      # ONNX model wrapper
│   ├── tokenizer.ts  # Text tokenization
│   ├── types.ts      # TypeScript type definitions
│   └── utils/        # Utility functions and constants
├── lib/              # Compiled JavaScript (generated)
├── models/           # Model files (ONNX model and tokenizer)
├── build.ts          # Build verification script
└── example.ts        # Example usage file

Requirements

• Node.js >= 18.0.0
• For browser usage: Modern browser with WebAssembly support
• TypeScript >= 5.3.3 (for development)

Dependencies

Runtime Dependencies

• onnxruntime-web - ONNX Runtime for model inference (browser/WASM)
• tokenizers - Fast tokenization library

Development Dependencies

• typescript - TypeScript compiler
• ts-node - TypeScript execution for Node.js
• @types/node - Node.js type definitions

TypeScript Support

This package is written entirely in TypeScript and includes full type definitions. All types are exported and available for use:

import type { 
  ModerationResult, 
  ModerationOptions, 
  TokenizerEncoding 
} from '@masteryhub-its/speakout-local-client-model';

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues, questions, or contributions, please open an issue on the repository.