webml-kit 0.2.1 → 0.4.0

package/README.md

@@ -6,6 +6,8 @@
 
 > Framework-agnostic utilities for loading and running ML models in the browser via WebGPU/WASM.
 
+**[Live Playground & Interactive Demos →](https://hemanth.github.io/webml-kit/)**
+
 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.
@@ -18,12 +20,39 @@ npm install webml-kit
 
 ## Quick start
 
+### Zero-ceremony functional API
+
+```ts
+import webml from 'webml-kit';
+
+// Speech recognition — auto-detects task, normalizes audio (Blob, File, URL, Float32Array)
+const asr = await webml('onnx-community/whisper-tiny.en');
+const { text } = await asr.transcribe(audioBlob);
+
+// Live microphone listening
+const mic = await asr.listen({
+  onTranscript: (text) => console.log(text),
+});
+
+// Text generation with streaming
+const llm = await webml('onnx-community/Llama-3.2-1B-Instruct-ONNX');
+for await (const { token } of llm.stream('Tell me a joke')) {
+  process.stdout.write(token);
+}
+
+// Image classification (callable object)
+const classifier = await webml('Xenova/vit-base-patch16-224');
+const labels = await classifier(imageFile);
+```
+
+### Low-level ModelClient
+
+For manual control over device detection, cache, and worker threads:
+
 ```ts
 import { ModelClient } from 'webml-kit';
 
 const client = new ModelClient();
-// or with an explicit worker path:
-// const client = new ModelClient(new URL('webml-kit/worker', import.meta.url));
 
 // What can this machine do?
 const device = await client.detect();
@@ -147,6 +176,53 @@ const objects = await client.run('object-detection', imageBlob);
 // classify text, extract entities, estimate depth, segment images
 ```
 
+### Standalone & Custom ONNX Models
+
+Not every model uses standard `@huggingface/transformers` pipelines. `webml-kit` automatically detects and supports standalone ONNX models, companion audio preprocessors, and custom CTC decoders (such as NeMo Conformer-CTC models, standalone vision backbones, or raw ONNX graphs), with automatic WebGPU-to-WASM fallback when operators require WASM SIMD:
+
+```ts
+// Load standalone ONNX models from HF Hub, local files, or URLs
+const asr = await webml('onnx-community/whisper-tiny.en'); // or any standalone ONNX model
+const { text } = await asr.transcribe(audioFloat32Array);
+```
+
+### Jev System One / OpenJev Decision Capabilities
+
+Fast, calibrated, programmable decisions without autoregressive token generation. Turn natural language and application state into typed choices, binary verdicts (`noul`), or continuous level scores (`score`) with direct logit readouts:
+
+```ts
+import webml, { createDecisionEngine, directChoice } from 'webml-kit';
+
+// One-shot direct choice
+const result = await directChoice({
+  state: 'Customer reports: "My subscription charged twice, please refund immediately."',
+  question: 'Which department should handle this request?',
+  options: ['billing', 'technical-support', 'sales'],
+});
+console.log(result.choice);        // 'billing'
+console.log(result.confidence);    // 0.88
+console.log(result.probabilities); // { billing: 0.88, 'technical-support': 0.08, sales: 0.04 }
+
+// Binary evaluation (Noul)
+const engine = webml.decision({ model: 'qwen3-0.6b' });
+const { noul, passed } = await engine.noul({
+  state: 'Production database cluster is reporting 500 errors',
+  statement: 'Is there an urgent incident?',
+});
+console.log(noul);   // 0.94
+console.log(passed); // true
+
+// Continuous scoring along ordered criteria levels
+const { score, confidence } = await engine.score({
+  state: 'There is a minor typo in the footer disclaimer.',
+  instructions: 'Rate issue severity',
+  criteria: ['P3', 'P2', 'P1', 'P0'],
+});
+console.log(score); // 0.15 (continuous score on 0-3 scale)
+```
+
+Supports OpenJev GGUF models (`minicpm5-2b`, `qwen3-0.6b`, `qwen3.5-4b`) via `@wllama/wllama` with WebGPU/WASM in browser and worker environments, with automatic, zero-dependency heuristic fallback for Node.js, offline, or test environments.
+
 ## API
 
 ### ModelClient

package/dist/cache.d.ts.map

@@ -1 +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"}
+{"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;AAU5D;;;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,CA0C/D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BhE"}

package/dist/cache.js

@@ -6,8 +6,11 @@
  * 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';
+/** Supported model cache name prefixes */
+const CACHE_PREFIXES = ['transformers-cache', 'webml-kit'];
+function isModelCache(name) {
+    return CACHE_PREFIXES.some(prefix => name.startsWith(prefix));
+}
 /**
  * Detect which cache backend is available.
  * Priority: Cache API → OPFS → IndexedDB
@@ -45,8 +48,8 @@ export async function isCached(modelId) {
         return false;
     try {
         const keys = await caches.keys();
-        const hfCaches = keys.filter(k => k.startsWith(HF_CACHE_PREFIX));
-        for (const cacheName of hfCaches) {
+        const matchedCaches = keys.filter(k => isModelCache(k));
+        for (const cacheName of matchedCaches) {
             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));
@@ -82,8 +85,8 @@ export async function listCachedModels() {
     const models = [];
     try {
         const keys = await caches.keys();
-        const hfCaches = keys.filter(k => k.startsWith(HF_CACHE_PREFIX));
-        for (const cacheName of hfCaches) {
+        const matchedCaches = keys.filter(k => isModelCache(k));
+        for (const cacheName of matchedCaches) {
             const cache = await caches.open(cacheName);
             const cacheKeys = await cache.keys();
             // Group by model ID (extract from URL pattern)
@@ -92,14 +95,12 @@ export async function listCachedModels() {
                 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);
-                }
+                const id = match ? match[1] : (url.split('/').filter(Boolean).slice(-2).join('/') || url);
+                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({
@@ -134,8 +135,8 @@ export async function clearCache(modelId) {
         return;
     try {
         const keys = await caches.keys();
-        const hfCaches = keys.filter(k => k.startsWith(HF_CACHE_PREFIX));
-        for (const cacheName of hfCaches) {
+        const matchedCaches = keys.filter(k => isModelCache(k));
+        for (const cacheName of matchedCaches) {
             if (!modelId) {
                 // Clear entire cache
                 await caches.delete(cacheName);

package/dist/cache.js.map

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

package/dist/decision.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Jev System One / OpenJev Decision Engine for webml-kit.
+ *
+ * Provides direct logit readout choice evaluation, direct binary evaluation (noul),
+ * and continuous scoring evaluation over structured application state.
+ *
+ * Supports OpenJev models (minicpm5-2b, qwen3-0.6b, qwen3.5-4b) using @wllama/wllama
+ * in browser/worker environments with WebGPU/WASM, and a high-performance,
+ * calibrated zero-dependency heuristic fallback for Node.js, test, or offline environments.
+ *
+ * @packageDocumentation
+ */
+export type OpenJevModelPreset = 'minicpm5-2b' | 'qwen3-0.6b' | 'qwen3.5-4b' | (string & {});
+export interface OpenJevModelInfo {
+    id: string;
+    name: string;
+    url: string;
+    family: 'minicpm' | 'qwen' | string;
+    sizeMB: number;
+}
+export declare const OPENJEV_MODELS: Record<string, OpenJevModelInfo>;
+export interface DecisionProgressEvent {
+    status: 'downloading' | 'loading' | 'compiling' | 'ready';
+    loaded: number;
+    total: number;
+    percent: number;
+    detail?: string;
+}
+export type DecisionProgressCallback = (event: DecisionProgressEvent) => void;
+export interface DecisionEngineOptions {
+    /** Model preset or custom model ID (default: 'qwen3-0.6b') */
+    model?: OpenJevModelPreset;
+    /** Custom direct URL to GGUF model file */
+    modelUrl?: string;
+    /** Execution mode: 'auto' (try wllama, fallback to heuristic), 'wllama', or 'heuristic' */
+    mode?: 'auto' | 'wllama' | 'heuristic';
+    /** Path config for @wllama/wllama assets */
+    wasmPaths?: {
+        default?: string;
+        'single-thread/wllama.wasm'?: string;
+        'multi-thread/wllama.wasm'?: string;
+    };
+    /** Callback for model download and initialization progress */
+    onProgress?: DecisionProgressCallback;
+    /** Default threshold for noul evaluation (default: 0.5) */
+    noulThreshold?: number;
+}
+export interface ChoiceInput {
+    /** Application state context (object, string, array, etc.) */
+    state: unknown;
+    /** Question or instruction to evaluate */
+    question?: string;
+    /** Alternative alias for question */
+    instructions?: string;
+    /** Options to evaluate: array of labels or key-description criteria object */
+    options: string[] | Record<string, string>;
+}
+export interface ChoiceResult {
+    /** Selected winning option */
+    choice: string;
+    /** Confidence score between 0.0 and 1.0 */
+    confidence: number;
+    /** Probability distribution across options (sums to ~1.0) */
+    probabilities: Record<string, number>;
+    /** Execution time in milliseconds */
+    latencyMs: number;
+}
+export interface NoulInput {
+    /** Application state context */
+    state: unknown;
+    /** Condition or statement to evaluate */
+    statement?: string;
+    /** Alternative alias for statement */
+    instructions?: string;
+    /** Pass threshold (default: 0.5) */
+    threshold?: number;
+}
+export interface NoulResult {
+    /** Probability (0.0 to 1.0) that the condition holds true */
+    noul: number;
+    /** Whether noul >= threshold */
+    passed: boolean;
+    /** Execution time in milliseconds */
+    latencyMs: number;
+}
+export interface ScoreInput {
+    /** Application state context */
+    state: unknown;
+    /** Evaluation instructions */
+    instructions?: string;
+    /** Alternative alias for instructions */
+    question?: string;
+    /** Ordered evaluation levels: array of level names or level map */
+    criteria: string[] | Record<string, string> | Record<number, string>;
+}
+export interface ScoreResult {
+    /** Probability-weighted continuous score along levels */
+    score: number;
+    /** Confidence score between 0.0 and 1.0 */
+    confidence: number;
+    /** Probability distribution across criteria levels */
+    probabilities: Record<string, number>;
+    /** Execution time in milliseconds */
+    latencyMs: number;
+}
+export interface DecisionEngine {
+    readonly model: string;
+    readonly isHeuristic: boolean;
+    readonly isLoaded: boolean;
+    init(): Promise<void>;
+    choice(input: ChoiceInput): Promise<ChoiceResult>;
+    directChoice(input: ChoiceInput): Promise<ChoiceResult>;
+    noul(input: NoulInput): Promise<NoulResult>;
+    score(input: ScoreInput): Promise<ScoreResult>;
+    dispose(): Promise<void> | void;
+}
+interface NormalizedOption {
+    key: string;
+    description: string;
+}
+export declare function normalizeOptions(rawOptions: string[] | Record<string, string>): NormalizedOption[];
+interface NormalizedLevel {
+    index: number;
+    key: string;
+    description: string;
+}
+export declare function normalizeCriteria(rawCriteria: string[] | Record<string, string> | Record<number, string>): NormalizedLevel[];
+export declare function validateModelOptions(options: DecisionEngineOptions): {
+    modelId: string;
+    modelUrl: string;
+    mode: 'auto' | 'wllama' | 'heuristic';
+};
+export declare class HeuristicDecisionEngine implements DecisionEngine {
+    readonly model: string;
+    readonly isHeuristic: boolean;
+    private _isLoaded;
+    private options;
+    constructor(options?: DecisionEngineOptions);
+    get isLoaded(): boolean;
+    init(): Promise<void>;
+    choice(input: ChoiceInput): Promise<ChoiceResult>;
+    directChoice(input: ChoiceInput): Promise<ChoiceResult>;
+    noul(input: NoulInput): Promise<NoulResult>;
+    score(input: ScoreInput): Promise<ScoreResult>;
+    dispose(): void;
+}
+export declare class OpenJevWllamaEngine implements DecisionEngine {
+    readonly model: string;
+    readonly isHeuristic: boolean;
+    private _isLoaded;
+    private options;
+    private modelUrl;
+    private wllamaInstance;
+    constructor(options?: DecisionEngineOptions);
+    get isLoaded(): boolean;
+    init(): Promise<void>;
+    choice(input: ChoiceInput): Promise<ChoiceResult>;
+    directChoice(input: ChoiceInput): Promise<ChoiceResult>;
+    noul(input: NoulInput): Promise<NoulResult>;
+    score(input: ScoreInput): Promise<ScoreResult>;
+    dispose(): Promise<void>;
+}
+/**
+ * Creates a DecisionEngine configured for OpenJev System One decision evaluations.
+ *
+ * Automatically selects OpenJev via Wllama in browser/worker environments with WebGPU/WASM,
+ * and falls back to a calibrated zero-dependency heuristic engine in Node.js or test environments.
+ *
+ * @param options - Configuration options (model preset, mode, wasm paths, onProgress)
+ * @returns Configured DecisionEngine instance
+ */
+export declare function createDecisionEngine(options?: DecisionEngineOptions): DecisionEngine;
+/**
+ * Executes a one-shot direct choice evaluation over application state with zero boilerplate.
+ *
+ * @param input - Evaluation state, question, and options (array or criteria record)
+ * @param options - Decision engine configuration options
+ * @returns ChoiceResult containing winning choice, confidence, and calibrated probabilities
+ */
+export declare function directChoice(input: ChoiceInput, options?: DecisionEngineOptions): Promise<ChoiceResult>;
+export {};
+//# sourceMappingURL=decision.d.ts.map

package/dist/decision.d.ts.map

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