webml-kit 0.1.0

package/dist/device.js

@@ -0,0 +1,195 @@
+/**
+ * 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.
+ */
+// ─── VRAM thresholds for dtype recommendation ───
+const VRAM_THRESHOLDS = [
+    { min: 8 * 1024 ** 3, dtype: 'fp16' }, // 8 GB+  → fp16
+    { min: 4 * 1024 ** 3, dtype: 'q8' }, // 4 GB+  → q8
+    { min: 2 * 1024 ** 3, dtype: 'q4' }, // 2 GB+  → q4
+    { min: 0, dtype: 'q4' }, // < 2 GB → q4 (safest)
+];
+/**
+ * Check if WebGPU is available and request an adapter.
+ * Returns `null` if WebGPU is not supported.
+ */
+export async function getGPUAdapter() {
+    if (typeof navigator === 'undefined')
+        return null;
+    if (!('gpu' in navigator))
+        return null;
+    try {
+        const adapter = await navigator.gpu.requestAdapter({
+            powerPreference: 'high-performance',
+        });
+        return adapter;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Extract GPU info from an adapter.
+ */
+export async function getGPUInfo(adapter) {
+    // adapterInfo is available synchronously on modern browsers
+    const info = adapter.info ?? adapter.requestAdapterInfo?.();
+    const resolved = info instanceof Promise ? await info : info;
+    // maxBufferSize gives a rough VRAM lower-bound
+    const vram = Number(adapter.limits?.maxBufferSize ?? 0);
+    return {
+        vendor: resolved?.vendor ?? 'unknown',
+        architecture: resolved?.architecture ?? 'unknown',
+        description: resolved?.description ?? 'unknown',
+        vram,
+        vramFormatted: formatSize(vram),
+    };
+}
+/**
+ * Recommend a quantization dtype based on available VRAM.
+ */
+export function recommendDtype(vram) {
+    for (const { min, dtype } of VRAM_THRESHOLDS) {
+        if (vram >= min)
+            return dtype;
+    }
+    return 'q4';
+}
+/**
+ * Check if WebGPU is available.
+ */
+export async function checkWebGPU() {
+    const adapter = await getGPUAdapter();
+    return adapter !== null;
+}
+/**
+ * Check if WebAssembly is available.
+ */
+export function checkWASM() {
+    return typeof WebAssembly !== 'undefined';
+}
+/**
+ * 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 async function detectDevice() {
+    // Try WebGPU first
+    const adapter = await getGPUAdapter();
+    if (adapter) {
+        const gpu = await getGPUInfo(adapter);
+        return {
+            backend: 'webgpu',
+            gpu,
+            recommendedDtype: recommendDtype(gpu.vram),
+        };
+    }
+    // Fall back to WASM
+    if (checkWASM()) {
+        return {
+            backend: 'wasm',
+            gpu: null,
+            recommendedDtype: 'q4',
+        };
+    }
+    // CPU-only (rare)
+    return {
+        backend: 'cpu',
+        gpu: null,
+        recommendedDtype: 'q4',
+    };
+}
+// ─── Size parsing / formatting ───
+const SIZE_UNITS = {
+    b: 1,
+    kb: 1024,
+    mb: 1024 ** 2,
+    gb: 1024 ** 3,
+    tb: 1024 ** 4,
+};
+/**
+ * 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 function parseSize(input) {
+    if (typeof input === 'number')
+        return input;
+    const match = input.trim().match(/^([\d.]+)\s*(b|kb|mb|gb|tb)$/i);
+    if (!match) {
+        throw new Error(`Invalid size format: "${input}". Use something like "4GB", "512MB", or a number in bytes.`);
+    }
+    const value = parseFloat(match[1]);
+    const unit = match[2].toLowerCase();
+    return Math.round(value * SIZE_UNITS[unit]);
+}
+/**
+ * Format bytes into a human-readable string.
+ *
+ * ```ts
+ * formatSize(4294967296)  // '4 GB'
+ * formatSize(536870912)   // '512 MB'
+ * formatSize(1536)        // '1.5 KB'
+ * ```
+ */
+export function formatSize(bytes) {
+    if (bytes >= 1024 ** 4)
+        return `${(bytes / 1024 ** 4).toFixed(1)} TB`;
+    if (bytes >= 1024 ** 3)
+        return `${(bytes / 1024 ** 3).toFixed(1)} GB`;
+    if (bytes >= 1024 ** 2)
+        return `${(bytes / 1024 ** 2).toFixed(1)} MB`;
+    if (bytes >= 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${bytes} B`;
+}
+// ─── canRun ───
+/**
+ * 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 async function canRun(estimatedSize) {
+    const bytes = parseSize(estimatedSize);
+    const device = await detectDevice();
+    if (device.backend === 'webgpu' && device.gpu) {
+        // Leave ~500MB headroom for browser internals
+        const available = device.gpu.vram - 512 * 1024 ** 2;
+        if (bytes > available) {
+            return {
+                ok: false,
+                backend: device.backend,
+                reason: `Model (~${formatSize(bytes)}) exceeds available VRAM (~${formatSize(available)})`,
+            };
+        }
+    }
+    return { ok: true, backend: device.backend };
+}
+//# sourceMappingURL=device.js.map

package/dist/device.js.map

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

package/dist/gpu-recovery.d.ts

@@ -0,0 +1,61 @@
+/**
+ * GPU device-lost recovery handler.
+ *
+ * WebGPU devices can be lost due to TDR resets, VRAM exhaustion, driver
+ * updates, or mobile browsers reclaiming resources. This module provides
+ * automatic recovery with exponential backoff.
+ */
+export type RecoveryState = 'idle' | 'lost' | 'recovering' | 'recovered' | 'failed';
+export interface GPURecoveryEvents {
+    'state-change': RecoveryState;
+    'lost': {
+        reason: string;
+    };
+    'recovered': {
+        adapter: GPUAdapter;
+    };
+    'failed': {
+        attempts: number;
+        lastError: string;
+    };
+}
+export type GPURecoveryListener<K extends keyof GPURecoveryEvents> = (data: GPURecoveryEvents[K]) => void;
+/**
+ * Monitors a GPU device for loss and attempts automatic recovery.
+ *
+ * ```ts
+ * const recovery = new GPURecovery();
+ * recovery.on('lost', ({ reason }) => showBanner('GPU lost: ' + reason));
+ * recovery.on('recovered', ({ adapter }) => reinitPipeline(adapter));
+ * recovery.on('failed', () => showFallbackUI());
+ *
+ * const device = await recovery.watchDevice(existingDevice);
+ * ```
+ */
+export declare class GPURecovery {
+    private state;
+    private listeners;
+    private maxRetries;
+    private baseDelay;
+    constructor(options?: {
+        maxRetries?: number;
+        baseDelayMs?: number;
+    });
+    /** Current recovery state. */
+    getState(): RecoveryState;
+    /** Register a listener for recovery events. */
+    on<K extends keyof GPURecoveryEvents>(event: K, listener: GPURecoveryListener<K>): void;
+    /** Remove a listener. */
+    off<K extends keyof GPURecoveryEvents>(event: K, listener: GPURecoveryListener<K>): void;
+    private emit;
+    private setState;
+    /**
+     * Watch a GPU device for loss. When the device is lost, automatically
+     * attempt to re-acquire an adapter.
+     *
+     * @returns The same device (for chaining)
+     */
+    watchDevice(device: GPUDevice): GPUDevice;
+    private attemptRecovery;
+}
+//# sourceMappingURL=gpu-recovery.d.ts.map

package/dist/gpu-recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu-recovery.d.ts","sourceRoot":"","sources":["../src/gpu-recovery.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,YAAY,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEpF,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,aAAa,CAAC;IAC9B,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3B,WAAW,EAAE;QAAE,OAAO,EAAE,UAAU,CAAA;KAAE,CAAC;IACrC,QAAQ,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CACnD;AAED,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,MAAM,iBAAiB,IAC/D,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;AAEvC;;;;;;;;;;;GAWG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAyB;IACtC,OAAO,CAAC,SAAS,CAAoC;IACrD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,SAAS,CAAS;gBAEd,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE;IAKnE,8BAA8B;IAC9B,QAAQ,IAAI,aAAa;IAIzB,+CAA+C;IAC/C,EAAE,CAAC,CAAC,SAAS,MAAM,iBAAiB,EAClC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC/B,IAAI;IAOP,yBAAyB;IACzB,GAAG,CAAC,CAAC,SAAS,MAAM,iBAAiB,EACnC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC/B,IAAI;IAIP,OAAO,CAAC,IAAI;IAOZ,OAAO,CAAC,QAAQ;IAKhB;;;;;OAKG;IACH,WAAW,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS;YAmB3B,eAAe;CAqC9B"}

package/dist/gpu-recovery.js

@@ -0,0 +1,105 @@
+/**
+ * GPU device-lost recovery handler.
+ *
+ * WebGPU devices can be lost due to TDR resets, VRAM exhaustion, driver
+ * updates, or mobile browsers reclaiming resources. This module provides
+ * automatic recovery with exponential backoff.
+ */
+/**
+ * Monitors a GPU device for loss and attempts automatic recovery.
+ *
+ * ```ts
+ * const recovery = new GPURecovery();
+ * recovery.on('lost', ({ reason }) => showBanner('GPU lost: ' + reason));
+ * recovery.on('recovered', ({ adapter }) => reinitPipeline(adapter));
+ * recovery.on('failed', () => showFallbackUI());
+ *
+ * const device = await recovery.watchDevice(existingDevice);
+ * ```
+ */
+export class GPURecovery {
+    state = 'idle';
+    listeners = new Map();
+    maxRetries;
+    baseDelay;
+    constructor(options) {
+        this.maxRetries = options?.maxRetries ?? 3;
+        this.baseDelay = options?.baseDelayMs ?? 1000;
+    }
+    /** Current recovery state. */
+    getState() {
+        return this.state;
+    }
+    /** Register a listener for recovery events. */
+    on(event, listener) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event).add(listener);
+    }
+    /** Remove a listener. */
+    off(event, listener) {
+        this.listeners.get(event)?.delete(listener);
+    }
+    emit(event, data) {
+        this.listeners.get(event)?.forEach(fn => fn(data));
+    }
+    setState(state) {
+        this.state = state;
+        this.emit('state-change', state);
+    }
+    /**
+     * Watch a GPU device for loss. When the device is lost, automatically
+     * attempt to re-acquire an adapter.
+     *
+     * @returns The same device (for chaining)
+     */
+    watchDevice(device) {
+        device.lost.then((info) => {
+            const reason = info.message || 'unknown';
+            // If the device was intentionally destroyed, don't recover
+            if (info.reason === 'destroyed') {
+                this.setState('idle');
+                return;
+            }
+            this.setState('lost');
+            this.emit('lost', { reason });
+            this.attemptRecovery(0);
+        });
+        this.setState('idle');
+        return device;
+    }
+    async attemptRecovery(attempt) {
+        if (attempt >= this.maxRetries) {
+            this.setState('failed');
+            this.emit('failed', {
+                attempts: attempt,
+                lastError: 'Max retries exceeded',
+            });
+            return;
+        }
+        this.setState('recovering');
+        // Exponential backoff: 1s, 2s, 4s
+        const delay = this.baseDelay * 2 ** attempt;
+        await new Promise(r => setTimeout(r, delay));
+        try {
+            if (typeof navigator === 'undefined' || !('gpu' in navigator)) {
+                throw new Error('WebGPU not available');
+            }
+            const adapter = await navigator.gpu.requestAdapter({
+                powerPreference: 'high-performance',
+            });
+            if (!adapter) {
+                throw new Error('No GPU adapter available');
+            }
+            this.setState('recovered');
+            this.emit('recovered', { adapter });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            // Retry
+            this.attemptRecovery(attempt + 1);
+        }
+    }
+}
+//# sourceMappingURL=gpu-recovery.js.map

package/dist/gpu-recovery.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * webml-kit — Browser ML Made Easy
+ *
+ * Framework-agnostic utilities for loading and running ML models
+ * in the browser via WebGPU/WASM, powered by @huggingface/transformers.
+ *
+ * @example
+ * ```ts
+ * import { ModelClient, detectDevice, isCached } from 'webml-kit';
+ *
+ * // Check device
+ * const device = await detectDevice();
+ * console.log(device.backend); // 'webgpu'
+ *
+ * // Check cache
+ * if (await isCached('onnx-community/Bonsai-1.7B-ONNX')) {
+ *   console.log('Model already downloaded!');
+ * }
+ *
+ * // Create client
+ * const client = new ModelClient(
+ *   new URL('./model-worker.js', import.meta.url)
+ * );
+ *
+ * // Load model
+ * await client.load({
+ *   task: 'text-generation',
+ *   modelId: 'onnx-community/Bonsai-1.7B-ONNX',
+ *   dtype: 'q4',
+ *   onProgress: ({ percent }) => console.log(`${percent}%`),
+ * });
+ *
+ * // Stream tokens
+ * for await (const { token, tps } of client.stream('Hello!')) {
+ *   process.stdout.write(token);
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { ModelClient } from './model-client.js';
+export type { LoadOptions, ClientEventType } from './model-client.js';
+export { detectDevice, checkWebGPU, checkWASM, getGPUAdapter, getGPUInfo, recommendDtype, canRun, parseSize, formatSize, } from './device.js';
+export { getCacheBackend, isCached, getCacheSize, listCachedModels, clearCache, } from './cache.js';
+export { TokenStream, collectStream } from './streaming.js';
+export { GPURecovery } from './gpu-recovery.js';
+export type { RecoveryState, GPURecoveryEvents } from './gpu-recovery.js';
+export { PIPELINE_REGISTRY, getPipelineDefaults, supportsStreaming, } from './pipelines/index.js';
+export type { PipelineDefaults } from './pipelines/index.js';
+export type { DeviceBackend, DeviceInfo, GPUInfo, QuantizationType, PipelineTask, ModelConfig, ProgressEvent, ProgressCallback, TokenEvent, ChatMessage, TextGenerationOptions, TextGenerationResult, ClassificationResult, DetectionResult, TranscriptionResult, EmbeddingResult, CaptionResult, TextResult, CacheBackend, CachedModel, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGtE,OAAO,EACL,YAAY,EACZ,WAAW,EACX,SAAS,EACT,aAAa,EACb,UAAU,EACV,cAAc,EACd,MAAM,EACN,SAAS,EACT,UAAU,GACX,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,eAAe,EACf,QAAQ,EACR,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAG5D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAG1E,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAG7D,YAAY,EACV,aAAa,EACb,UAAU,EACV,OAAO,EACP,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,eAAe,EACf,mBAAmB,EACnB,eAAe,EACf,aAAa,EACb,UAAU,EACV,YAAY,EACZ,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,53 @@
+/**
+ * webml-kit — Browser ML Made Easy
+ *
+ * Framework-agnostic utilities for loading and running ML models
+ * in the browser via WebGPU/WASM, powered by @huggingface/transformers.
+ *
+ * @example
+ * ```ts
+ * import { ModelClient, detectDevice, isCached } from 'webml-kit';
+ *
+ * // Check device
+ * const device = await detectDevice();
+ * console.log(device.backend); // 'webgpu'
+ *
+ * // Check cache
+ * if (await isCached('onnx-community/Bonsai-1.7B-ONNX')) {
+ *   console.log('Model already downloaded!');
+ * }
+ *
+ * // Create client
+ * const client = new ModelClient(
+ *   new URL('./model-worker.js', import.meta.url)
+ * );
+ *
+ * // Load model
+ * await client.load({
+ *   task: 'text-generation',
+ *   modelId: 'onnx-community/Bonsai-1.7B-ONNX',
+ *   dtype: 'q4',
+ *   onProgress: ({ percent }) => console.log(`${percent}%`),
+ * });
+ *
+ * // Stream tokens
+ * for await (const { token, tps } of client.stream('Hello!')) {
+ *   process.stdout.write(token);
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+// ─── Core ───
+export { ModelClient } from './model-client.js';
+// ─── Device Detection ───
+export { detectDevice, checkWebGPU, checkWASM, getGPUAdapter, getGPUInfo, recommendDtype, canRun, parseSize, formatSize, } from './device.js';
+// ─── Cache ───
+export { getCacheBackend, isCached, getCacheSize, listCachedModels, clearCache, } from './cache.js';
+// ─── Streaming ───
+export { TokenStream, collectStream } from './streaming.js';
+// ─── GPU Recovery ───
+export { GPURecovery } from './gpu-recovery.js';
+// ─── Pipelines ───
+export { PIPELINE_REGISTRY, getPipelineDefaults, supportsStreaming, } from './pipelines/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,eAAe;AACf,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,2BAA2B;AAC3B,OAAO,EACL,YAAY,EACZ,WAAW,EACX,SAAS,EACT,aAAa,EACb,UAAU,EACV,cAAc,EACd,MAAM,EACN,SAAS,EACT,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,gBAAgB;AAChB,OAAO,EACL,eAAe,EACf,QAAQ,EACR,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB,oBAAoB;AACpB,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE5D,uBAAuB;AACvB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,oBAAoB;AACpB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC"}

package/dist/model-client.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Main-thread client for communicating with the ML worker.
+ *
+ * Wraps the Web Worker's postMessage protocol with a promise-based API,
+ * AsyncIterable token streaming, and typed events.
+ *
+ * ```ts
+ * import { ModelClient } from 'webml-kit';
+ *
+ * const client = new ModelClient();
+ *
+ * // Check device capabilities
+ * const device = await client.detect();
+ * console.log(device.backend); // 'webgpu'
+ *
+ * // Load a model
+ * await client.load({
+ *   task: 'text-generation',
+ *   modelId: 'onnx-community/Bonsai-1.7B-ONNX',
+ *   dtype: 'q4',
+ *   onProgress: ({ percent }) => console.log(`${percent}%`),
+ * });
+ *
+ * // Stream text generation
+ * for await (const { token, tps } of client.stream('Hello!')) {
+ *   process.stdout.write(token);
+ * }
+ *
+ * // One-shot inference
+ * const labels = await client.run('image-classification', imageBlob);
+ * ```
+ */
+import type { DeviceInfo, ModelConfig, PipelineTask, ProgressCallback, TextGenerationOptions, TextGenerationResult, ChatMessage } from './types.js';
+import { TokenStream } from './streaming.js';
+export interface LoadOptions extends ModelConfig {
+    onProgress?: ProgressCallback;
+}
+export type ClientEventType = 'progress' | 'ready' | 'error' | 'device-lost' | 'device-recovered';
+type Listener = (data: unknown) => void;
+export declare class ModelClient {
+    private worker;
+    private workerUrl;
+    private listeners;
+    private pendingRequests;
+    private requestCounter;
+    private deviceInfo;
+    private loadedModels;
+    private progressCallback;
+    private gpuRecovery;
+    /**
+     * Create a new ModelClient.
+     *
+     * @param workerUrl - URL to the model-worker.js file. If omitted,
+     *   creates a Blob URL from the bundled worker (requires bundler support).
+     */
+    constructor(workerUrl?: string | URL);
+    private getWorker;
+    private send;
+    private nextId;
+    private handleMessage;
+    /** Register an event listener. */
+    on(event: ClientEventType, listener: Listener): this;
+    /** Remove an event listener. */
+    off(event: ClientEventType, listener: Listener): this;
+    private emit;
+    /**
+     * Detect the best available compute backend.
+     *
+     * ```ts
+     * const info = await client.detect();
+     * console.log(info.backend);         // 'webgpu'
+     * console.log(info.gpu?.vendor);      // 'apple'
+     * console.log(info.recommendedDtype); // 'q4'
+     * ```
+     */
+    detect(): Promise<DeviceInfo>;
+    /**
+     * Load a model pipeline.
+     *
+     * ```ts
+     * await client.load({
+     *   task: 'text-generation',
+     *   modelId: 'onnx-community/Bonsai-1.7B-ONNX',
+     *   dtype: 'q4',
+     *   onProgress: ({ percent }) => updateUI(percent),
+     * });
+     * ```
+     */
+    load(options: LoadOptions): Promise<void>;
+    /**
+     * Run one-shot inference for any pipeline task.
+     *
+     * ```ts
+     * // Image classification
+     * const labels = await client.run('image-classification', imageUrl);
+     *
+     * // Speech recognition
+     * const { text } = await client.run('automatic-speech-recognition', audioBlob);
+     *
+     * // Embeddings
+     * const vectors = await client.run('feature-extraction', 'Hello world');
+     * ```
+     */
+    run<T = unknown>(task: PipelineTask, input: unknown, options?: Record<string, unknown>): Promise<T>;
+    /**
+     * Generate text with streaming tokens.
+     *
+     * Returns an `AsyncIterable<TokenEvent>` that yields tokens as they're generated.
+     *
+     * ```ts
+     * for await (const { token, tps } of client.stream('Tell me a joke')) {
+     *   process.stdout.write(token);
+     * }
+     * ```
+     */
+    stream(input: string | ChatMessage[], options?: TextGenerationOptions): TokenStream;
+    /**
+     * Generate text and wait for the complete result.
+     *
+     * ```ts
+     * const { text, tps, numTokens } = await client.generate('Hello!');
+     * ```
+     */
+    generate(input: string | ChatMessage[], options?: TextGenerationOptions): Promise<TextGenerationResult>;
+    /**
+     * Interrupt an ongoing text generation.
+     */
+    interrupt(): void;
+    /**
+     * Reset the KV cache (start a new conversation).
+     */
+    reset(): void;
+    /**
+     * Dispose a loaded model and free memory.
+     *
+     * @param modelKey - Specific model key (task::modelId), or omit to dispose all.
+     */
+    dispose(modelKey?: string): void;
+    /**
+     * Check if a model is currently loaded.
+     */
+    isLoaded(task: PipelineTask, modelId: string): boolean;
+    /**
+     * Terminate the worker completely.
+     */
+    terminate(): void;
+}
+export {};
+//# sourceMappingURL=model-client.d.ts.map

package/dist/model-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-client.d.ts","sourceRoot":"","sources":["../src/model-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EAIpB,WAAW,EACZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,WAAW,EAAiB,MAAM,gBAAgB,CAAC;AAK5D,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC9C,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B;AAED,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,OAAO,GACP,OAAO,GACP,aAAa,GACb,kBAAkB,CAAC;AAEvB,KAAK,QAAQ,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;AAIxC,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,SAAS,CAA6C;IAC9D,OAAO,CAAC,eAAe,CAOnB;IACJ,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,gBAAgB,CAAiC;IACzD,OAAO,CAAC,WAAW,CAAc;IAEjC;;;;;OAKG;gBACS,SAAS,CAAC,EAAE,MAAM,GAAG,GAAG;IAcpC,OAAO,CAAC,SAAS;IAsBjB,OAAO,CAAC,IAAI;IAIZ,OAAO,CAAC,MAAM;IAMd,OAAO,CAAC,aAAa;IA8ErB,kCAAkC;IAClC,EAAE,CAAC,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAQpD,gCAAgC;IAChC,GAAG,CAAC,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAKrD,OAAO,CAAC,IAAI;IAMZ;;;;;;;;;OASG;IACG,MAAM,IAAI,OAAO,CAAC,UAAU,CAAC;IASnC;;;;;;;;;;;OAWG;IACG,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB/C;;;;;;;;;;;;;OAaG;IACG,GAAG,CAAC,CAAC,GAAG,OAAO,EACnB,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,CAAC,CAAC;IASb;;;;;;;;;;OAUG;IACH,MAAM,CACJ,KAAK,EAAE,MAAM,GAAG,WAAW,EAAE,EAC7B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,WAAW;IAqBd;;;;;;OAMG;IACG,QAAQ,CACZ,KAAK,EAAE,MAAM,GAAG,WAAW,EAAE,EAC7B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,oBAAoB,CAAC;IAShC;;OAEG;IACH,SAAS,IAAI,IAAI;IAIjB;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;IAShC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IAItD;;OAEG;IACH,SAAS,IAAI,IAAI;CAOlB"}