@omnid/tinyemo 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,45 @@
-# Temporary Holding Version
+# `@omnid/tinyemo`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Zero-dependency, pure **WebGPU** TypeScript inference SDK for the **TinyEmo** English emoji suggestion model (`812` emoji classes).
+
+- **Pure WebGPU compute pipeline**: Custom WGSL compute kernels for hashed n-gram embeddings, LayerNorm, token embeddings, multi-head self-attention, GELU FFN, attention pooling, and classification head.
+- **Self-contained compressed weights**: Packs `model.safetensors` and `tiny_tokenizer.bin` compressed via Web `CompressionStream("gzip")` and decodes them at runtime via `DecompressionStream("gzip")`. Also supports loading raw or compressed `safetensors` and `onnx` (`model.onnx`) weight buffers.
+- **0 shipped dependencies**: Uses only standard Web APIs (`navigator.gpu`, `CompressionStream`, `DecompressionStream`, `TypedArray`, `TextEncoder`/`TextDecoder`).
+
+## Usage
+
+```ts
+import { TinyEmo } from "@omnid/tinyemo";
+
+const model = await TinyEmo.create();
+
+// Suggest top-3 emojis (returns EmojiSuggestion[], supporting both object and tuple access)
+const suggestions = await model.suggest("walk the dog", 3);
+for (const { emoji, probability } of suggestions) {
+  console.log(emoji, probability);
+}
+// Output:
+// 🐕 0.771414
+// 🚶 0.121709
+// 🌳 0.041397
+
+// Tuple destructuring also works directly:
+const [[topEmoji, topScore]] = await model.suggest("happy birthday!!", 1);
+
+// Batch inference on WebGPU:
+const batch = await model.suggestBatch(["walk the dog", "broken heart crying"], 3);
+
+// Raw float32 logits (Float32Array of length 812):
+const logits = await model.logits("walk the dog");
+
+// Clean up GPU buffers when done:
+model.destroy();
+```
+
+## Scripts
+
+```bash
+npm run pack-assets   # Compress ../tinyemo/model.safetensors & tiny_tokenizer.bin via CompressionStream
+npm run build         # Pack assets and compile TypeScript to ./dist
+npm test              # Run unit + WebGPU (Dawn & Headless Chrome Metal) test suite
+```

package/dist/compression.d.ts

@@ -0,0 +1,31 @@
+import type { StreamCompressionFormat } from "./types.js";
+/**
+ * Convert a base64 string into a Uint8Array without any external dependencies.
+ * Works in browsers, Node.js, Deno, Bun, and Cloudflare Workers.
+ */
+export declare function base64ToBytes(base64: string): Uint8Array;
+/**
+ * Convert a Uint8Array into a base64 string without any external dependencies.
+ */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+/**
+ * Compress a Uint8Array using the standard Web `CompressionStream` API.
+ */
+export declare function compressStream(data: Uint8Array | ArrayBuffer, format?: StreamCompressionFormat): Promise<Uint8Array>;
+/**
+ * Decompress a Uint8Array using the standard Web `DecompressionStream` API.
+ */
+export declare function decompressStream(data: Uint8Array | ArrayBuffer, format?: StreamCompressionFormat): Promise<Uint8Array>;
+/**
+ * Compress binary data with `CompressionStream` and encode as base64 for SDK packing.
+ */
+export declare function encodePackedAsset(data: Uint8Array | ArrayBuffer, format?: StreamCompressionFormat): Promise<string>;
+/**
+ * Decode a base64 packed asset and decompress it with `DecompressionStream`.
+ */
+export declare function decodePackedAsset(base64: string, format?: StreamCompressionFormat): Promise<Uint8Array>;
+/**
+ * Check if a buffer starts with the gzip magic bytes (0x1f, 0x8b) and decompress if so.
+ */
+export declare function maybeDecompress(data: Uint8Array | ArrayBuffer): Promise<Uint8Array>;
+//# sourceMappingURL=compression.d.ts.map

package/dist/compression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compression.d.ts","sourceRoot":"","sources":["../src/compression.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1D;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAQxD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAQvD;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,UAAU,GAAG,WAAW,EAC9B,MAAM,GAAE,uBAAgC,GACvC,OAAO,CAAC,UAAU,CAAC,CAUrB;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,UAAU,GAAG,WAAW,EAC9B,MAAM,GAAE,uBAAgC,GACvC,OAAO,CAAC,UAAU,CAAC,CAUrB;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,UAAU,GAAG,WAAW,EAC9B,MAAM,GAAE,uBAAgC,GACvC,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,uBAAgC,GACvC,OAAO,CAAC,UAAU,CAAC,CAGrB;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAMzF"}

package/dist/compression.js

@@ -0,0 +1,78 @@
+/**
+ * Convert a base64 string into a Uint8Array without any external dependencies.
+ * Works in browsers, Node.js, Deno, Bun, and Cloudflare Workers.
+ */
+export function base64ToBytes(base64) {
+    const binString = atob(base64);
+    const len = binString.length;
+    const bytes = new Uint8Array(len);
+    for (let i = 0; i < len; i++) {
+        bytes[i] = binString.charCodeAt(i);
+    }
+    return bytes;
+}
+/**
+ * Convert a Uint8Array into a base64 string without any external dependencies.
+ */
+export function bytesToBase64(bytes) {
+    let binString = "";
+    const chunkSize = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunkSize) {
+        const chunk = bytes.subarray(i, i + chunkSize);
+        binString += String.fromCharCode(...chunk);
+    }
+    return btoa(binString);
+}
+/**
+ * Compress a Uint8Array using the standard Web `CompressionStream` API.
+ */
+export async function compressStream(data, format = "gzip") {
+    if (typeof CompressionStream === "undefined") {
+        throw new Error("Web CompressionStream API is not available in this runtime.");
+    }
+    const input = data instanceof Uint8Array ? data : new Uint8Array(data);
+    const stream = new Blob([input])
+        .stream()
+        .pipeThrough(new CompressionStream(format));
+    const ab = await new Response(stream).arrayBuffer();
+    return new Uint8Array(ab);
+}
+/**
+ * Decompress a Uint8Array using the standard Web `DecompressionStream` API.
+ */
+export async function decompressStream(data, format = "gzip") {
+    if (typeof DecompressionStream === "undefined") {
+        throw new Error("Web DecompressionStream API is not available in this runtime.");
+    }
+    const input = data instanceof Uint8Array ? data : new Uint8Array(data);
+    const stream = new Blob([input])
+        .stream()
+        .pipeThrough(new DecompressionStream(format));
+    const ab = await new Response(stream).arrayBuffer();
+    return new Uint8Array(ab);
+}
+/**
+ * Compress binary data with `CompressionStream` and encode as base64 for SDK packing.
+ */
+export async function encodePackedAsset(data, format = "gzip") {
+    const compressed = await compressStream(data, format);
+    return bytesToBase64(compressed);
+}
+/**
+ * Decode a base64 packed asset and decompress it with `DecompressionStream`.
+ */
+export async function decodePackedAsset(base64, format = "gzip") {
+    const compressed = base64ToBytes(base64);
+    return decompressStream(compressed, format);
+}
+/**
+ * Check if a buffer starts with the gzip magic bytes (0x1f, 0x8b) and decompress if so.
+ */
+export async function maybeDecompress(data) {
+    const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+    if (bytes.byteLength >= 2 && bytes[0] === 0x1f && bytes[1] === 0x8b) {
+        return decompressStream(bytes, "gzip");
+    }
+    return bytes;
+}
+//# sourceMappingURL=compression.js.map

package/dist/compression.js.map

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

package/dist/engine.d.ts

@@ -0,0 +1,95 @@
+import { TinyTokenizer } from "./tokenizer.js";
+import type { EmojiSuggestion, EncodedBatch, EncodedInput, TinyEmoModelConfig, TinyEmoOptions } from "./types.js";
+export declare const MAX_OUTPUT = 3;
+/**
+ * Numerically stable softmax over a Float32Array.
+ */
+export declare function softmax(logits: Float32Array): Float32Array;
+/**
+ * Create an EmojiSuggestion object supporting both `{ emoji, probability }` and `[emoji, probability]`.
+ */
+export declare function createSuggestion(emoji: string, probability: number, index: number): EmojiSuggestion;
+/**
+ * Request a WebGPU `GPUDevice` from the global `navigator.gpu`.
+ */
+export declare function requestWebGpuDevice(adapterOptions?: GPURequestAdapterOptions): Promise<GPUDevice>;
+/**
+ * Pure WebGPU inference engine for the TinyEmo emoji suggestion model.
+ */
+export declare class TinyEmo {
+    readonly device: GPUDevice;
+    readonly config: TinyEmoModelConfig;
+    readonly labels: readonly string[];
+    readonly tokenizer: TinyTokenizer;
+    private readonly packedWeights;
+    private readonly weightsBuffer;
+    private readonly bindGroupLayout;
+    private readonly pipelines;
+    private readonly layerParamsBuffers;
+    private allocatedBatchCap;
+    private inputsIntBuffer;
+    private inputsFloatBuffer;
+    private workspaceBuffer;
+    private logitsBuffer;
+    private readbackBuffer;
+    private layerBindGroups;
+    private destroyed;
+    private queueLock;
+    private constructor();
+    /**
+     * Create and initialize a new TinyEmo WebGPU inference instance.
+     * Decompresses the packed safetensors weights and tokenizer using Web `DecompressionStream`
+     * unless custom weights/tokenizer buffers are provided.
+     */
+    static create(options?: TinyEmoOptions): Promise<TinyEmo>;
+    private ensureBatchBuffers;
+    /**
+     * Normalize input phrase using TinyEmo's normalization rules.
+     */
+    normalize(text: string, maxWords?: number): string;
+    /**
+     * Encode a single text phrase into token IDs, attention mask, and hashed n-gram features.
+     */
+    encode(text: string): EncodedInput;
+    /**
+     * Encode a batch of text phrases into contiguous typed arrays for WebGPU execution.
+     */
+    encodeBatch(texts: readonly string[]): EncodedBatch;
+    /**
+     * Execute the WebGPU forward pass on an encoded batch, returning a flattened
+     * `Float32Array` of shape `[batchSize * n_labels]`.
+     */
+    forward(batch: EncodedBatch): Promise<Float32Array>;
+    /**
+     * Compute raw logits (`Float32Array` of length 812) for a single text phrase on WebGPU.
+     */
+    logits(text: string): Promise<Float32Array>;
+    /**
+     * Compute raw logits for a batch of text phrases on WebGPU.
+     */
+    logitsBatch(texts: readonly string[], batchSize?: number): Promise<Float32Array[]>;
+    /**
+     * Compute softmax probability distribution (`Float32Array` of length 812) for a text phrase.
+     */
+    probabilities(text: string): Promise<Float32Array>;
+    /**
+     * Suggest up to `limit` emojis (clamped to 1..3, default 1) for an input phrase.
+     * Returns `[]` if the phrase normalizes to empty string, matching `TinyEmoRuntime.suggest`.
+     */
+    suggest(text: string, limit?: number): Promise<EmojiSuggestion[]>;
+    /**
+     * Suggest up to `limit` emojis (clamped to 1..3, default 1) for a batch of phrases
+     * in a single WebGPU dispatch.
+     */
+    suggestBatch(texts: readonly string[], limit?: number): Promise<EmojiSuggestion[][]>;
+    private topKSuggestionsFromProbs;
+    /**
+     * Release all GPU buffers allocated by this TinyEmo instance.
+     */
+    destroy(): void;
+}
+/**
+ * Convenience factory function to create a TinyEmo WebGPU inference instance.
+ */
+export declare function createTinyEmo(options?: TinyEmoOptions): Promise<TinyEmo>;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACf,MAAM,YAAY,CAAC;AASpB,eAAO,MAAM,UAAU,IAAI,CAAC;AA2B5B;;GAEG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAsB1D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,GACZ,eAAe,CAcjB;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,cAAc,CAAC,EAAE,wBAAwB,GACxC,OAAO,CAAC,SAAS,CAAC,CAepB;AAED;;GAEG;AACH,qBAAa,OAAO;IAClB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAElC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmB;IACjD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAY;IAC1C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAUxB;IAEF,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAmB;IACtD,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,eAAe,CAA0B;IACjD,OAAO,CAAC,iBAAiB,CAA0B;IACnD,OAAO,CAAC,eAAe,CAA0B;IACjD,OAAO,CAAC,YAAY,CAA0B;IAC9C,OAAO,CAAC,cAAc,CAA0B;IAChD,OAAO,CAAC,eAAe,CAAsB;IAC7C,OAAO,CAAC,SAAS,CAAS;IAG1B,OAAO,CAAC,SAAS,CAAuC;IAExD,OAAO;IA4GP;;;;OAIG;WACU,MAAM,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IAkBnE,OAAO,CAAC,kBAAkB;IAwD1B;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM;IAIlD;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY;IA+BlC;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,YAAY;IAiCnD;;;OAGG;IACG,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAuIzD;;OAEG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAKjD;;OAEG;IACG,WAAW,CACf,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,SAAS,SAAM,GACd,OAAO,CAAC,YAAY,EAAE,CAAC;IAgB1B;;OAEG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAKxD;;;OAGG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IASlE;;;OAGG;IACG,YAAY,CAChB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,KAAK,SAAI,GACR,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC;IAe/B,OAAO,CAAC,wBAAwB;IAYhC;;OAEG;IACH,OAAO,IAAI,IAAI;CAahB;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAE9E"}