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

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,257 @@
+# @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
+
+```bash
+npm install @masteryhub-its/speakout-local-client-model
+```
+
+## Quick Start
+
+### Browser (Vite/React)
+
+```typescript
+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`:**
+
+```typescript
+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):**
+
+```typescript
+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
+
+```typescript
+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:**
+```typescript
+{
+  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
+
+```typescript
+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
+
+```typescript
+const result = await moderation.moderate("User content", 0.7); // 70% threshold
+```
+
+### Batch Processing
+
+```typescript
+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
+
+```typescript
+const moderation = new ClientContentModeration({
+  modelFilePath: '/FilePath/to/model.onnx',
+  tokenizerFilePath: '/FilePath/to/tokenizer.json',
+  maxLength: 256,
+  threshold: 0.6
+});
+```
+
+## Development
+
+### Building from Source
+
+```bash
+# 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:
+
+```typescript
+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.

package/index.js

@@ -0,0 +1 @@
+export { default as ClientContentModeration } from './lib/index.js';

package/lib/index.d.ts

@@ -0,0 +1,22 @@
+import { ModerationResult, ModerationOptions } from "./types.js";
+export declare class ClientContentModeration {
+    private model;
+    private tokenizer;
+    private initialized;
+    constructor(options?: ModerationOptions);
+    initialize(): Promise<void>;
+    moderate(text: string, threshold?: number): Promise<ModerationResult>;
+    moderateBatch(texts: string[], threshold?: number): Promise<ModerationResult[]>;
+    /**
+     * Compute softmax probabilities from logits
+     * @param logits - Array of logit values
+     * @returns Array of probabilities (sums to 1)
+     */
+    private softmax;
+    /**
+     * Dispose resources and clean up
+     */
+    dispose(): void;
+}
+export type { ModerationResult, ModerationOptions };
+export default ClientContentModeration;

package/lib/index.js

@@ -0,0 +1,89 @@
+import { ModerationModel } from "./model.js";
+import { Tokenizer } from "./tokenizer.js";
+import { DEFAULTS } from "./utils/constants.js";
+export class ClientContentModeration {
+    model;
+    tokenizer;
+    initialized = false;
+    constructor(options) {
+        this.model = new ModerationModel();
+        this.tokenizer = new Tokenizer();
+    }
+    async initialize() {
+        if (this.initialized)
+            return;
+        await Promise.all([
+            this.model.initialize(),
+            this.tokenizer.initialize(),
+        ]);
+        this.initialized = true;
+    }
+    async moderate(text, threshold = DEFAULTS.THRESHOLD) {
+        if (!this.initialized)
+            await this.initialize();
+        const encodings = await this.tokenizer.encodeChunks(text);
+        const chunkResults = await Promise.all(encodings.map(e => this.model.predict(e.inputIds, e.attentionMask)));
+        const validChunks = chunkResults.filter(c => (Array.isArray(c) || c instanceof Float32Array) && c.length > 0);
+        if (!validChunks.length) {
+            return {
+                approved: true,
+                confidence: 0.5,
+                probabilities: { reject: 0.5, approve: 0.5 }
+            };
+        }
+        const aggregatedLogits = validChunks[0].map((_, i) => validChunks.reduce((sum, logits) => sum + logits[i], 0) / validChunks.length);
+        const probabilities = this.softmax(aggregatedLogits);
+        const shouldApprove = probabilities[1] >= threshold;
+        return {
+            approved: shouldApprove,
+            confidence: Math.max(...probabilities),
+            probabilities: {
+                reject: probabilities[0],
+                approve: probabilities[1]
+            }
+        };
+    }
+    async moderateBatch(texts, threshold = DEFAULTS.THRESHOLD) {
+        if (!this.initialized)
+            await this.initialize();
+        return Promise.all(texts.map(t => this.moderate(t, threshold)));
+    }
+    /**
+     * Compute softmax probabilities from logits
+     * @param logits - Array of logit values
+     * @returns Array of probabilities (sums to 1)
+     */
+    softmax(logits) {
+        const output = [];
+        let max = -Infinity;
+        // Find max (numerical stability)
+        for (const v of logits) {
+            if (v > max)
+                max = v;
+        }
+        // Exponentiate and sum
+        let sum = 0;
+        for (const v of logits) {
+            const e = Math.exp(v - max);
+            output.push(e);
+            sum += e;
+        }
+        // Normalize (guard against edge cases)
+        if (sum === 0 || !Number.isFinite(sum)) {
+            const uniform = 1 / output.length;
+            return output.map(() => uniform);
+        }
+        for (let i = 0; i < output.length; i++) {
+            output[i] /= sum;
+        }
+        return output;
+    }
+    /**
+     * Dispose resources and clean up
+     */
+    dispose() {
+        this.model.dispose();
+        this.initialized = false;
+    }
+}
+export default ClientContentModeration;

package/lib/model.d.ts

@@ -0,0 +1,11 @@
+export declare class ModerationModel {
+    private session;
+    private initialized;
+    private static runtime;
+    private modelFileUrl;
+    private static getOnnxRuntime;
+    constructor(file?: string);
+    initialize(): Promise<void>;
+    predict(inputIds: number[], attentionMask: number[]): Promise<Float32Array>;
+    dispose(): void;
+}

package/lib/model.js

@@ -0,0 +1,72 @@
+import * as ort from 'onnxruntime-web';
+import { ERROR_MESSAGES, ONNX_CONFIG, MODEL_PATH } from './utils/constants.js';
+export class ModerationModel {
+    session = null;
+    initialized = false;
+    static runtime = null;
+    modelFileUrl;
+    static getOnnxRuntime() {
+        if (ModerationModel.runtime)
+            return ModerationModel.runtime;
+        if (!ort?.InferenceSession)
+            throw new Error(ERROR_MESSAGES.ONNX_RUNTIME_NOT_AVAILABLE);
+        ModerationModel.runtime = ort;
+        return ModerationModel.runtime;
+    }
+    constructor(file) {
+        this.modelFileUrl = file ?? MODEL_PATH;
+    }
+    async initialize() {
+        if (this.initialized && this.session)
+            return;
+        const runtime = ModerationModel.getOnnxRuntime();
+        if (runtime.env?.wasm) {
+            runtime.env.wasm.numThreads = ONNX_CONFIG.WASM_NUM_THREADS;
+            runtime.env.wasm.simd = true;
+        }
+        const sessionOptions = {
+            graphOptimizationLevel: ONNX_CONFIG.GRAPH_OPTIMIZATION_LEVEL,
+            executionProviders: [ONNX_CONFIG.EXECUTION_PROVIDER_WASM],
+        };
+        try {
+            this.session = await runtime.InferenceSession.create(this.modelFileUrl, sessionOptions);
+            this.initialized = true;
+        }
+        catch (error) {
+            // If model loading fails, verify the URL is correct
+            const verifyResponse = await fetch(this.modelFileUrl);
+            const contentType = verifyResponse.headers.get('content-type') || '';
+            if (contentType.includes('text/html')) {
+                const text = await verifyResponse.text();
+                throw new Error(`Failed to load ONNX model: The URL ${this.modelFileUrl} returned HTML instead of a model file. This usually means the model file path is incorrect. Response preview: ${text.substring(0, 200)}`);
+            }
+            throw error;
+        }
+    }
+    async predict(inputIds, attentionMask) {
+        if (!this.session)
+            await this.initialize();
+        if (!this.session)
+            throw new Error(ERROR_MESSAGES.SESSION_NOT_INITIALIZED);
+        const runtime = ModerationModel.getOnnxRuntime();
+        const tokenTypeIds = new Array(inputIds.length).fill(0);
+        const feeds = {
+            input_ids: new runtime.Tensor(ONNX_CONFIG.TENSOR_TYPE_INT64, inputIds, [1, inputIds.length]),
+            attention_mask: new runtime.Tensor(ONNX_CONFIG.TENSOR_TYPE_INT64, attentionMask, [1, attentionMask.length]),
+            token_type_ids: new runtime.Tensor(ONNX_CONFIG.TENSOR_TYPE_INT64, tokenTypeIds, [1, tokenTypeIds.length]),
+        };
+        const output = await this.session.run(feeds);
+        const logits = (output.logits ||
+            output[Object.keys(output)[0]]);
+        if (!logits || !("data" in logits)) {
+            throw new Error("Model output does not contain logits");
+        }
+        return logits.data instanceof Float32Array
+            ? logits.data
+            : new Float32Array(logits.data);
+    }
+    dispose() {
+        this.session = null;
+        this.initialized = false;
+    }
+}

package/lib/tokenizer.d.ts

@@ -0,0 +1,15 @@
+import type { TokenizerEncoding } from './types.js';
+export declare class Tokenizer {
+    private tokenizer;
+    private readonly maxLength;
+    private readonly reservedTokens;
+    constructor(maxLength?: number);
+    initialize(path?: string): Promise<void>;
+    private tokenizeText;
+    private findSubwordTokens;
+    private padTokens;
+    private rawTokenize;
+    encodeChunks(text: string): Promise<TokenizerEncoding[]>;
+    private createEmptyChunk;
+    encode(text: string): Promise<TokenizerEncoding>;
+}

package/lib/tokenizer.js

@@ -0,0 +1,111 @@
+import { ERROR_MESSAGES, SPECIAL_TOKENS, DEFAULT_TOKEN_IDS, DEFAULTS, TOKENIZER_PATH } from './utils/constants.js';
+export class Tokenizer {
+    tokenizer = null;
+    maxLength;
+    reservedTokens = 2;
+    constructor(maxLength) {
+        this.maxLength = maxLength ?? DEFAULTS.MAX_LENGTH;
+    }
+    async initialize(path) {
+        if (this.tokenizer)
+            return;
+        const url = path ?? TOKENIZER_PATH;
+        try {
+            const res = await fetch(url);
+            if (!res.ok) {
+                throw new Error(`Failed to load tokenizer: HTTP ${res.status} at ${url}`);
+            }
+            const contentType = res.headers.get('content-type') || '';
+            if (contentType.includes('text/html')) {
+                const text = await res.text();
+                throw new Error(`Failed to load tokenizer: The URL ${url} returned HTML instead of JSON. This usually means the path is incorrect. Response preview: ${text.substring(0, 200)}`);
+            }
+            const json = await res.json();
+            this.tokenizer = { vocab: json.model?.vocab ?? {} };
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes('HTML')) {
+                throw error;
+            }
+            throw new Error(`Failed to initialize tokenizer at ${url}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    tokenizeText(text, vocab, unkId) {
+        const words = text.toLowerCase().match(/\S+/g) ?? [];
+        const tokens = [];
+        for (const word of words) {
+            if (vocab[word])
+                tokens.push(vocab[word]);
+            else
+                tokens.push(...this.findSubwordTokens(word, vocab, unkId));
+            if (tokens.length >= this.maxLength - this.reservedTokens)
+                break;
+        }
+        return tokens.slice(0, this.maxLength - this.reservedTokens);
+    }
+    findSubwordTokens(word, vocab, unkId) {
+        const lengths = Array.from({ length: word.length }, (_, k) => word.length - k);
+        for (const i of lengths) {
+            const subword = word.substring(0, i);
+            if (vocab[subword]) {
+                const tokens = [vocab[subword]];
+                const remaining = word.substring(i);
+                if (remaining) {
+                    const subwordToken = `${SPECIAL_TOKENS.SUBWORD_PREFIX}${remaining}`;
+                    tokens.push(vocab[subwordToken] ?? unkId);
+                }
+                return tokens;
+            }
+        }
+        return [unkId];
+    }
+    padTokens(tokens, padId) {
+        const inputIds = tokens.slice(0, this.maxLength);
+        const attentionMask = inputIds.map(() => 1);
+        while (inputIds.length < this.maxLength) {
+            inputIds.push(padId);
+            attentionMask.push(0);
+        }
+        return { inputIds, attentionMask };
+    }
+    async rawTokenize(text) {
+        if (!this.tokenizer)
+            await this.initialize();
+        if (!this.tokenizer)
+            throw new Error(ERROR_MESSAGES.TOKENIZER_NOT_INITIALIZED);
+        const vocab = this.tokenizer.vocab ?? {};
+        const unkId = vocab[SPECIAL_TOKENS.UNK] ?? DEFAULT_TOKEN_IDS.UNK;
+        return this.tokenizeText(text, vocab, unkId);
+    }
+    async encodeChunks(text) {
+        if (!this.tokenizer)
+            await this.initialize();
+        if (!this.tokenizer)
+            throw new Error(ERROR_MESSAGES.TOKENIZER_NOT_INITIALIZED);
+        const raw = await this.rawTokenize(text);
+        const vocab = this.tokenizer.vocab ?? {};
+        const padId = vocab[SPECIAL_TOKENS.PAD] ?? DEFAULT_TOKEN_IDS.PAD;
+        const clsId = vocab[SPECIAL_TOKENS.CLS] ?? DEFAULT_TOKEN_IDS.CLS;
+        const sepId = vocab[SPECIAL_TOKENS.SEP] ?? DEFAULT_TOKEN_IDS.SEP;
+        if (raw.length === 0)
+            return [this.createEmptyChunk(clsId, sepId, padId)];
+        const chunks = [];
+        const chunkSize = this.maxLength - this.reservedTokens;
+        const numChunks = Math.max(1, Math.ceil(raw.length / chunkSize));
+        const starts = Array.from({ length: numChunks }, (_, k) => k * chunkSize);
+        for (const start of starts) {
+            const slice = raw.slice(start, start + chunkSize);
+            chunks.push(this.padTokens([clsId, ...slice, sepId], padId));
+        }
+        return chunks;
+    }
+    createEmptyChunk(clsId, sepId, padId) {
+        const inputIds = [clsId, sepId, ...Array(this.maxLength - this.reservedTokens).fill(padId)];
+        const attentionMask = inputIds.map((id) => (id === padId ? 0 : 1));
+        return { inputIds: inputIds.slice(0, this.maxLength), attentionMask };
+    }
+    async encode(text) {
+        const [first] = await this.encodeChunks(text);
+        return first;
+    }
+}

package/lib/types.d.ts

@@ -0,0 +1,56 @@
+export interface ModerationResult {
+    approved: boolean;
+    confidence: number;
+    probabilities: {
+        reject: number;
+        approve: number;
+    };
+}
+export interface ModerationOptions {
+    modelFilePath?: string;
+    tokenizerFilePath?: string;
+    maxLength?: number;
+    threshold?: number;
+}
+export interface TokenizerEncoding {
+    inputIds: number[];
+    attentionMask: number[];
+}
+export interface OnnxRuntime {
+    InferenceSession: {
+        create: (modelFilePath: string, options?: SessionOptions) => Promise<InferenceSession>;
+    };
+    Tensor: new (type: string, data: number[] | Float32Array, dims: number[]) => OnnxTensor;
+    env?: {
+        wasm?: {
+            numThreads?: number;
+            simd?: boolean;
+        };
+    };
+}
+export interface InferenceSession {
+    run: (feeds: Record<string, OnnxTensor>) => Promise<InferenceOutput>;
+}
+export interface OnnxTensor {
+    data: Float32Array | number[];
+    dims: number[];
+    type?: string;
+    [key: string]: unknown;
+}
+export interface InferenceOutput {
+    logits?: OnnxTensor;
+    [key: string]: OnnxTensor | unknown;
+}
+export interface SessionOptions {
+    graphOptimizationLevel?: string;
+    executionProviders?: string[];
+    [key: string]: unknown;
+}
+export interface TokenizerVocab {
+    [token: string]: number;
+}
+export interface TokenizerData {
+    model?: {
+        vocab?: TokenizerVocab;
+    };
+}

package/lib/types.js

@@ -0,0 +1 @@
+export {};