webml-kit 0.1.0

package/README.md

@@ -0,0 +1,205 @@
+# webml-kit
+
+> Framework-agnostic utilities for loading and running ML models in the browser via WebGPU/WASM.
+
+If you've ever built a browser-ML demo, you know the drill: copy 150 lines of Web Worker boilerplate from the last project, wire up `postMessage`, add progress reporting, handle the GPU vanishing mid-inference, and pray the model is cached so your user doesn't wait 3 minutes. Every. Single. Time.
+
+This library does that part for you. It wraps [`@huggingface/transformers`](https://huggingface.co/docs/transformers.js) with a sane API and handles the ugly bits: device detection, model caching, token streaming, KV-cache management, and GPU recovery.
+
+## Install
+
+```bash
+npm install webml-kit @huggingface/transformers
+```
+
+## Quick start
+
+```ts
+import { ModelClient } from 'webml-kit';
+
+// Point to the worker file
+const client = new ModelClient(
+  new URL('webml-kit/worker', import.meta.url)
+);
+
+// What can this machine do?
+const device = await client.detect();
+console.log(device.backend);         // 'webgpu' or 'wasm' or 'cpu'
+console.log(device.gpu?.vendor);      // 'apple'
+console.log(device.recommendedDtype); // 'q4'
+
+// Load a model
+await client.load({
+  task: 'text-generation',
+  modelId: 'onnx-community/Bonsai-1.7B-ONNX',
+  dtype: 'q4',
+  onProgress: ({ percent }) => console.log(`Loading: ${percent}%`),
+});
+
+// Stream tokens as they're generated
+for await (const { token, tps } of client.stream('Tell me a joke')) {
+  process.stdout.write(token);
+}
+```
+
+## What's in here
+
+### Device detection
+
+Figures out what your user's machine can handle and picks a reasonable quantization level:
+
+```ts
+import { detectDevice, canRun } from 'webml-kit';
+
+const info = await detectDevice();
+// { backend: 'webgpu', gpu: { vendor: 'apple', vram: 8589934592, vramFormatted: '8.0 GB' }, recommendedDtype: 'fp16' }
+
+const { ok, reason } = await canRun('4GB');    // human-readable
+const same = await canRun(4_000_000_000);       // raw bytes — same result
+```
+
+### Cache visibility
+
+The worst UX in browser ML is showing "downloading 2GB..." to someone who already has the model. Now you can check:
+
+```ts
+import { isCached, listCachedModels, getCacheSize, clearCache } from 'webml-kit';
+
+if (await isCached('onnx-community/Bonsai-1.7B-ONNX')) {
+  // Skip the progress bar entirely
+}
+
+const models = await listCachedModels();
+// [{ modelId: 'onnx-community/Bonsai-1.7B-ONNX', size: '412.0 MB', sizeBytes: 432013312 }]
+
+await clearCache('onnx-community/Bonsai-1.7B-ONNX'); // Free storage on mobile
+```
+
+### Token streaming
+
+A proper `AsyncIterable` instead of raw `postMessage` callbacks. Tracks tokens-per-second and time-to-first-token:
+
+```ts
+for await (const event of client.stream('Hello!')) {
+  console.log(event);
+  // { token: 'World', tps: 38.5, numTokens: 12, timeToFirstToken: 145 }
+}
+
+// Or grab everything at once:
+const { text, tps, numTokens } = await client.generate('Hello!');
+```
+
+### GPU recovery
+
+GPUs disappear. It happens: TDR resets, VRAM pressure, mobile browsers reclaiming resources. Without handling this, the user has to reload the page. This recovers automatically with backoff:
+
+```ts
+import { GPURecovery } from 'webml-kit';
+
+const recovery = new GPURecovery({ maxRetries: 3, baseDelayMs: 1000 });
+recovery.on('lost', ({ reason }) => showBanner('GPU lost: ' + reason));
+recovery.on('recovered', ({ adapter }) => console.log('Back online'));
+recovery.on('failed', () => showFallbackMessage());
+```
+
+### All pipeline tasks
+
+Not just text generation. Every task `@huggingface/transformers` supports works through the same API:
+
+```ts
+// Classify an image
+const labels = await client.run('image-classification', imageUrl);
+// [{ label: 'tabby cat', score: 0.98 }]
+
+// Transcribe audio
+const { text } = await client.run('automatic-speech-recognition', audioBlob);
+
+// Get embeddings
+const vectors = await client.run('feature-extraction', 'Hello world');
+
+// Detect objects
+const objects = await client.run('object-detection', imageBlob);
+
+// Translate, summarize, caption images, answer questions,
+// classify text, extract entities, estimate depth, segment images
+```
+
+## API
+
+### ModelClient
+
+| Method | What it does |
+|---|---|
+| `detect()` | Returns device capabilities and recommended dtype |
+| `load(options)` | Downloads and initializes a model pipeline |
+| `stream(input, options?)` | Returns an async iterator of tokens |
+| `generate(input, options?)` | Generates text, waits for completion |
+| `run(task, input, options?)` | Runs any pipeline task |
+| `interrupt()` | Stops an in-progress generation |
+| `reset()` | Clears the KV cache (new conversation) |
+| `dispose(modelKey?)` | Frees model memory |
+| `isLoaded(task, modelId)` | Checks if a specific model is ready |
+| `terminate()` | Kills the worker entirely |
+| `on(event, listener)` | Listens for progress, ready, error, device-lost, device-recovered |
+
+### Standalone functions
+
+These work without a ModelClient — useful for pre-flight checks:
+
+| Function | What it does |
+|---|---|
+| `detectDevice()` | Backend detection + GPU info + dtype recommendation |
+| `checkWebGPU()` | Boolean: is WebGPU available? |
+| `canRun(bytes)` | Can a model of this size fit in VRAM? |
+| `isCached(modelId)` | Is this model already downloaded? |
+| `listCachedModels()` | What's in the cache? |
+| `clearCache(modelId?)` | Delete cached model files |
+| `getCacheSize()` | Total bytes used by cached models |
+| `parseSize(input)` | Convert '4GB' / '512MB' to bytes |
+| `formatSize(bytes)` | Convert bytes to '4.0 GB' / '512.0 MB' |
+
+## Supported tasks
+
+| Task | Streaming | Default model |
+|---|---|---|
+| `text-generation` | yes | `onnx-community/Llama-3.2-1B-Instruct-ONNX` |
+| `text-classification` | no | `Xenova/distilbert-base-uncased-finetuned-sst-2-english` |
+| `image-classification` | no | `Xenova/vit-base-patch16-224` |
+| `object-detection` | no | `Xenova/detr-resnet-50` |
+| `automatic-speech-recognition` | no | `onnx-community/whisper-tiny.en` |
+| `text-to-speech` | no | `Xenova/speecht5_tts` |
+| `translation` | no | `Xenova/nllb-200-distilled-600M` |
+| `summarization` | no | `Xenova/distilbart-cnn-6-6` |
+| `feature-extraction` | no | `Xenova/all-MiniLM-L6-v2` |
+| `image-to-text` | no | `Xenova/vit-gpt2-image-captioning` |
+| `zero-shot-classification` | no | `Xenova/mobilebert-uncased-mnli` |
+| `fill-mask` | no | `Xenova/bert-base-uncased` |
+| `question-answering` | no | `Xenova/distilbert-base-uncased-distilled-squad` |
+| `token-classification` | no | `Xenova/bert-base-NER` |
+| `depth-estimation` | no | `Xenova/depth-anything-small-hf` |
+| `image-segmentation` | no | `Xenova/detr-resnet-50-panoptic` |
+
+## How it works
+
+```
+Your App (main thread)          Web Worker
+--------------------------      ---------------------------
+ModelClient                     model-worker.ts
+  .load()    --- postMessage -->  pipeline() from @hf/transformers
+  .stream()  <-- tokens --------  TextStreamer + KV cache
+  .run()     <-- result --------  One-shot inference
+  .interrupt() -- signal ------>  InterruptableStoppingCriteria
+
+TokenStream (AsyncIterable)     Singleton pipeline cache
+GPURecovery (auto-reconnect)    WebGPU device management
+```
+
+## Requirements
+
+- Chrome 113+, Edge 113+, or Safari 18+ (falls back to WASM on older browsers)
+- Node.js 18+ (WASM only, no WebGPU)
+- `@huggingface/transformers` >= 4.0.0 as a peer dependency
+
+## License
+
+MIT — [Hemanth HM](https://h3manth.com)

package/dist/cache.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Model cache visibility utilities.
+ *
+ * Transformers.js uses the Cache API internally to persist downloaded model
+ * files. This module gives users visibility into what's cached, letting them
+ * skip "downloading…" UX for returning users or clear storage on mobile.
+ */
+import type { CachedModel, CacheBackend } from './types.js';
+/**
+ * Detect which cache backend is available.
+ * Priority: Cache API → OPFS → IndexedDB
+ */
+export declare function getCacheBackend(): Promise<CacheBackend>;
+/**
+ * Check if a specific model is already cached locally.
+ *
+ * ```ts
+ * if (await isCached('onnx-community/Bonsai-1.7B-ONNX')) {
+ *   // Skip "downloading..." UI
+ * }
+ * ```
+ */
+export declare function isCached(modelId: string): Promise<boolean>;
+/**
+ * Get total cache size in bytes used by downloaded models.
+ */
+export declare function getCacheSize(): Promise<number>;
+/**
+ * List all cached models with metadata.
+ */
+export declare function listCachedModels(): Promise<CachedModel[]>;
+/**
+ * Clear cached model files.
+ *
+ * @param modelId - Specific model to clear, or omit to clear all.
+ *
+ * ```ts
+ * // Clear a specific model
+ * await clearCache('onnx-community/Bonsai-1.7B-ONNX');
+ *
+ * // Clear all cached models
+ * await clearCache();
+ * ```
+ */
+export declare function clearCache(modelId?: string): Promise<void>;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAM5D;;;GAGG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,YAAY,CAAC,CAmB7D;AAED;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAoBhE;AAED;;GAEG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CASpD;AAED;;GAEG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CA4C/D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BhE"}

package/dist/cache.js

@@ -0,0 +1,160 @@
+/**
+ * Model cache visibility utilities.
+ *
+ * Transformers.js uses the Cache API internally to persist downloaded model
+ * files. This module gives users visibility into what's cached, letting them
+ * skip "downloading…" UX for returning users or clear storage on mobile.
+ */
+import { formatSize } from './device.js';
+/** HuggingFace Transformers.js cache name prefix */
+const HF_CACHE_PREFIX = 'transformers-cache';
+/**
+ * Detect which cache backend is available.
+ * Priority: Cache API → OPFS → IndexedDB
+ */
+export async function getCacheBackend() {
+    if (typeof caches !== 'undefined') {
+        return 'cache-api';
+    }
+    if (typeof navigator !== 'undefined' && 'storage' in navigator) {
+        try {
+            const root = await navigator.storage.getDirectory();
+            if (root)
+                return 'opfs';
+        }
+        catch {
+            // OPFS not available
+        }
+    }
+    if (typeof indexedDB !== 'undefined') {
+        return 'indexeddb';
+    }
+    return 'cache-api'; // fallback, will fail gracefully
+}
+/**
+ * Check if a specific model is already cached locally.
+ *
+ * ```ts
+ * if (await isCached('onnx-community/Bonsai-1.7B-ONNX')) {
+ *   // Skip "downloading..." UI
+ * }
+ * ```
+ */
+export async function isCached(modelId) {
+    if (typeof caches === 'undefined')
+        return false;
+    try {
+        const keys = await caches.keys();
+        const hfCaches = keys.filter(k => k.startsWith(HF_CACHE_PREFIX));
+        for (const cacheName of hfCaches) {
+            const cache = await caches.open(cacheName);
+            const cacheKeys = await cache.keys();
+            const hasModel = cacheKeys.some(req => req.url.includes(encodeURIComponent(modelId)) || req.url.includes(modelId));
+            if (hasModel)
+                return true;
+        }
+    }
+    catch {
+        // Cache API not available or permission denied
+    }
+    return false;
+}
+/**
+ * Get total cache size in bytes used by downloaded models.
+ */
+export async function getCacheSize() {
+    if (typeof navigator === 'undefined' || !('storage' in navigator))
+        return 0;
+    try {
+        const estimate = await navigator.storage.estimate();
+        return estimate.usage ?? 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * List all cached models with metadata.
+ */
+export async function listCachedModels() {
+    if (typeof caches === 'undefined')
+        return [];
+    const models = [];
+    try {
+        const keys = await caches.keys();
+        const hfCaches = keys.filter(k => k.startsWith(HF_CACHE_PREFIX));
+        for (const cacheName of hfCaches) {
+            const cache = await caches.open(cacheName);
+            const cacheKeys = await cache.keys();
+            // Group by model ID (extract from URL pattern)
+            const modelUrls = new Map();
+            for (const request of cacheKeys) {
+                const url = request.url;
+                // HF URLs: https://huggingface.co/{org}/{model}/resolve/{rev}/{file}
+                const match = url.match(/huggingface\.co\/([^/]+\/[^/]+)\//);
+                if (match) {
+                    const id = match[1];
+                    const response = await cache.match(request);
+                    const size = response
+                        ? Number(response.headers.get('content-length') ?? 0)
+                        : 0;
+                    modelUrls.set(id, (modelUrls.get(id) ?? 0) + size);
+                }
+            }
+            for (const [modelId, sizeBytes] of modelUrls) {
+                models.push({
+                    modelId,
+                    sizeBytes,
+                    size: formatSize(sizeBytes),
+                    lastAccessed: new Date(), // Cache API doesn't track this
+                });
+            }
+        }
+    }
+    catch {
+        // Cache API not available
+    }
+    return models;
+}
+/**
+ * Clear cached model files.
+ *
+ * @param modelId - Specific model to clear, or omit to clear all.
+ *
+ * ```ts
+ * // Clear a specific model
+ * await clearCache('onnx-community/Bonsai-1.7B-ONNX');
+ *
+ * // Clear all cached models
+ * await clearCache();
+ * ```
+ */
+export async function clearCache(modelId) {
+    if (typeof caches === 'undefined')
+        return;
+    try {
+        const keys = await caches.keys();
+        const hfCaches = keys.filter(k => k.startsWith(HF_CACHE_PREFIX));
+        for (const cacheName of hfCaches) {
+            if (!modelId) {
+                // Clear entire cache
+                await caches.delete(cacheName);
+            }
+            else {
+                // Clear specific model
+                const cache = await caches.open(cacheName);
+                const cacheKeys = await cache.keys();
+                for (const request of cacheKeys) {
+                    if (request.url.includes(encodeURIComponent(modelId)) ||
+                        request.url.includes(modelId)) {
+                        await cache.delete(request);
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        // Cache API not available
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"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"}

package/dist/device.d.ts

@@ -0,0 +1,86 @@
+/**
+ * WebGPU / WASM device detection and capability probing.
+ *
+ * Detects the best available backend, extracts GPU adapter info,
+ * and recommends a quantization level based on estimated VRAM.
+ */
+import type { DeviceBackend, DeviceInfo, GPUInfo, QuantizationType } from './types.js';
+/**
+ * Check if WebGPU is available and request an adapter.
+ * Returns `null` if WebGPU is not supported.
+ */
+export declare function getGPUAdapter(): Promise<GPUAdapter | null>;
+/**
+ * Extract GPU info from an adapter.
+ */
+export declare function getGPUInfo(adapter: GPUAdapter): Promise<GPUInfo>;
+/**
+ * Recommend a quantization dtype based on available VRAM.
+ */
+export declare function recommendDtype(vram: number): QuantizationType;
+/**
+ * Check if WebGPU is available.
+ */
+export declare function checkWebGPU(): Promise<boolean>;
+/**
+ * Check if WebAssembly is available.
+ */
+export declare function checkWASM(): boolean;
+/**
+ * Detect the best available compute backend and return device info.
+ *
+ * Priority: WebGPU → WASM → CPU
+ *
+ * ```ts
+ * const info = await detectDevice();
+ * console.log(info.backend);         // 'webgpu'
+ * console.log(info.recommendedDtype); // 'q4'
+ * console.log(info.gpu?.vendor);      // 'apple'
+ * ```
+ */
+export declare function detectDevice(): Promise<DeviceInfo>;
+/**
+ * Parse a human-readable size string into bytes.
+ *
+ * Accepts formats like '4GB', '512 MB', '1.5gb', '256mb'.
+ * Also accepts raw numbers (passed through as-is).
+ *
+ * ```ts
+ * parseSize('4GB')    // 4294967296
+ * parseSize('512MB')  // 536870912
+ * parseSize('1.5gb')  // 1610612736
+ * parseSize(1024)     // 1024
+ * ```
+ */
+export declare function parseSize(input: string | number): number;
+/**
+ * Format bytes into a human-readable string.
+ *
+ * ```ts
+ * formatSize(4294967296)  // '4 GB'
+ * formatSize(536870912)   // '512 MB'
+ * formatSize(1536)        // '1.5 KB'
+ * ```
+ */
+export declare function formatSize(bytes: number): string;
+/**
+ * Check whether a model of a given size can likely run
+ * on the current device without OOM.
+ *
+ * Accepts human-readable strings or raw byte counts:
+ *
+ * ```ts
+ * await canRun('4GB');
+ * await canRun('512MB');
+ * await canRun(4_000_000_000);
+ * ```
+ *
+ * This is a heuristic — real limits depend on browser, OS, and
+ * other tabs consuming VRAM.
+ */
+export declare function canRun(estimatedSize: string | number): Promise<{
+    ok: boolean;
+    backend: DeviceBackend;
+    reason?: string;
+}>;
+//# sourceMappingURL=device.d.ts.map

package/dist/device.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.d.ts","sourceRoot":"","sources":["../src/device.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAWvF;;;GAGG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAYhE;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAetE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAK7D;AAED;;GAEG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAGpD;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAEnC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,UAAU,CAAC,CA2BxD;AAYD;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAaxD;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMhD;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,MAAM,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACpE,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC,CAiBD"}