npm package: @reham_h/speakout-local-client-model
Description: Local text moderation library using an Arabic MiniBERT model with ONNX Runtime (Web/Browser)
Author: MasteryHub ITS
Latest version: 0.5.8

# @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.