@openfluke/welvet 0.1.1 → 0.1.3

package/README.md

@@ -9,8 +9,10 @@
 
 ## ✨ Features
 
-- 🚀 **5.4MB WASM Binary** - Complete neural network framework compiled to WebAssembly
-- 🧠 **All 5 Layer Types** - Dense, Conv2D, Multi-Head Attention, RNN, LSTM fully supported
+- 🤖 **Transformer Inference (NEW!)** - Run LLMs like SmolLM2-135M with streaming generation
+- 🚀 **6.0MB WASM Binary** - Complete neural network framework + transformer inference
+- 🧠 **7 Layer Types (All CPU)** - Dense, Conv2D, Multi-Head Attention, LayerNorm, RNN, LSTM, Softmax (10 variants)
+- ✅ **Full CPU Implementation** - Every layer works with complete forward/backward passes
 - 🎯 **Registry-based Initialization** - Dynamic layer creation via `CallLayerInit()` with zero manual exports
 - 🔍 **Runtime Introspection** - Discover methods, signatures, and parameters dynamically
 - 💾 **Model Serialization** - Save/load models as JSON (no filesystem required)
@@ -42,6 +44,76 @@ bun add @openfluke/welvet
 
 ## 🚀 Quick Start
 
+### 🤖 Transformer Inference (NEW!)
+
+Run Large Language Models with streaming generation:
+
+```typescript
+import { initLoom, createTransformerAPI } from "@openfluke/welvet";
+
+// Initialize WASM
+await initLoom();
+
+// Create transformer API
+const transformer = await createTransformerAPI();
+
+// Load tokenizer
+const tokenizerData = await fetch("models/SmolLM2-135M-Instruct/tokenizer.json")
+  .then((r) => r.arrayBuffer())
+  .then((buf) => new Uint8Array(buf));
+await transformer.loadTokenizer(tokenizerData);
+
+// Load model
+const configData = await fetch("models/SmolLM2-135M-Instruct/config.json")
+  .then((r) => r.arrayBuffer())
+  .then((buf) => new Uint8Array(buf));
+const weightsData = await fetch(
+  "models/SmolLM2-135M-Instruct/model.safetensors"
+)
+  .then((r) => r.arrayBuffer())
+  .then((buf) => new Uint8Array(buf));
+await transformer.loadModel(configData, weightsData);
+
+// Stream generation token-by-token
+for await (const token of transformer.generateStream(
+  "The capital of France is",
+  50,
+  0.7
+)) {
+  process.stdout.write(token); // Paris...
+}
+```
+
+**Live Demo:** See `wasm/inference.html` for a beautiful web UI with real-time token streaming!
+
+### The Easy Way: Load Complete Models
+
+Instead of manually configuring layers, **load a complete model with ONE line**:
+
+```typescript
+import { initLoom } from "@openfluke/welvet";
+
+const loom = await initLoom();
+
+// Load model from JSON (architecture + weights all at once!)
+const modelJSON = await fetch("test.json").then((r) => r.json());
+const network = loom.LoadModelFromString(
+  JSON.stringify(modelJSON),
+  "all_layers_test"
+);
+
+// That's it! All 16 layers, weights, biases loaded automatically
+const input = new Array(10).fill(0).map(() => Math.random());
+const [output, duration] = JSON.parse(
+  network.ForwardCPU(JSON.stringify([input]))
+);
+console.log("Output:", output);
+```
+
+**Live Demo:** See `wasm/all_layers_test.html` for a complete working example that loads a 26.4KB model with 16 layers (Dense, Conv2D, Attention, RNN, LSTM) and runs inference in the browser!
+
+### Manual Configuration (for building models from scratch)
+
 ```typescript
 import { initLoom, ActivationType } from "@openfluke/welvet";
 
@@ -254,6 +326,28 @@ network.UpdateWeights(JSON.stringify([learningRate]));
 
 ### Model Persistence
 
+#### Load Model (The Easy Way - ONE LINE!)
+
+```typescript
+// Fetch model from server
+const savedModel = await fetch("model.json").then((r) => r.json());
+
+// Load complete network with ONE function call!
+const network = loom.LoadModelFromString(
+  JSON.stringify(savedModel),
+  "model_name"
+);
+
+// Or from localStorage
+const savedModel = JSON.parse(localStorage.getItem("my_model")!);
+const network = loom.LoadModelFromString(
+  JSON.stringify(savedModel),
+  "model_name"
+);
+```
+
+**That's it!** All layers, weights, biases, and configurations are automatically restored. No manual layer setup needed!
+
 #### Save Model
 
 ```typescript
@@ -264,16 +358,155 @@ const model = JSON.parse(JSON.parse(modelJSON)[0]);
 localStorage.setItem("my_model", JSON.stringify(model));
 ```
 
-#### Load Model
+#### Save Model
 
 ```typescript
-const savedModel = JSON.parse(localStorage.getItem("my_model")!);
-const network = loom.LoadModelFromString(
-  JSON.stringify(savedModel),
-  "model_name"
+const modelJSON = network.SaveModelToString(JSON.stringify(["model_name"]));
+const model = JSON.parse(JSON.parse(modelJSON)[0]);
+
+// Store anywhere (localStorage, IndexedDB, backend API, etc.)
+localStorage.setItem("my_model", JSON.stringify(model));
+```
+
+#### Cross-Platform Model Loading
+
+The same JSON model file works across **all three platforms**:
+
+```typescript
+// JavaScript/WASM
+const network = loom.LoadModelFromString(modelJSON, "model_id");
+```
+
+```python
+# Python
+network = welvet.load_model_from_string(model_json, "model_id")
+```
+
+```go
+// Go
+network, _ := nn.LoadModelFromString(modelJSON, "model_id")
+```
+
+See `examples/all_layers_validation.go` for a complete demo that generates test.json (26.4KB with 16 layers) and verifies all three platforms load it identically!
+
+## 🤖 Transformer API
+
+### Loading Models
+
+```typescript
+import { initLoom, createTransformerAPI } from "@openfluke/welvet";
+
+// Initialize WASM
+await initLoom();
+
+// Create transformer API
+const transformer = await createTransformerAPI();
+
+// Load tokenizer from bytes
+const tokenizerData = await fetch("models/SmolLM2-135M/tokenizer.json")
+  .then((r) => r.arrayBuffer())
+  .then((buf) => new Uint8Array(buf));
+
+const tokResult = await transformer.loadTokenizer(tokenizerData);
+console.log(`Tokenizer loaded: ${tokResult.vocab_size} tokens`);
+
+// Load model from config and weights
+const configData = await fetch("models/SmolLM2-135M/config.json")
+  .then((r) => r.arrayBuffer())
+  .then((buf) => new Uint8Array(buf));
+
+const weightsData = await fetch("models/SmolLM2-135M/model.safetensors")
+  .then((r) => r.arrayBuffer())
+  .then((buf) => new Uint8Array(buf));
+
+const modelResult = await transformer.loadModel(configData, weightsData);
+console.log(
+  `Model loaded: ${modelResult.num_layers} layers, ${modelResult.hidden_size} hidden size`
 );
 ```
 
+### Text Encoding/Decoding
+
+```typescript
+// Encode text to token IDs
+const encodeResult = await transformer.encode("Hello world", true);
+console.log(encodeResult.ids); // [1, 9906, 2088]
+
+// Decode token IDs to text
+const decodeResult = await transformer.decode([1, 9906, 2088], true);
+console.log(decodeResult.text); // "Hello world"
+```
+
+### Text Generation
+
+#### Blocking Generation
+
+```typescript
+const result = await transformer.generate(
+  "The capital of France is",
+  50, // maxTokens
+  0.7 // temperature
+);
+console.log(result.generated_text);
+```
+
+#### Streaming Generation
+
+```typescript
+// Stream tokens one at a time
+process.stdout.write("Generated: ");
+for await (const token of transformer.generateStream(
+  "Once upon a time",
+  50, // maxTokens
+  0.7 // temperature
+)) {
+  process.stdout.write(token); // Print each token as it's generated
+}
+console.log();
+```
+
+### Transformer API Reference
+
+```typescript
+interface TransformerAPI {
+  // Load tokenizer from JSON bytes
+  loadTokenizer(tokenizerData: Uint8Array): Promise<TokenizerLoadResult>;
+
+  // Load model from config + weights bytes
+  loadModel(
+    configData: Uint8Array,
+    weightsData: Uint8Array
+  ): Promise<TransformerLoadResult>;
+
+  // Encode text to token IDs
+  encode(text: string, addSpecialTokens?: boolean): Promise<EncodeResult>;
+
+  // Decode token IDs to text
+  decode(
+    tokenIds: number[],
+    skipSpecialTokens?: boolean
+  ): Promise<DecodeResult>;
+
+  // Generate text (blocking)
+  generate(
+    prompt: string,
+    maxTokens?: number,
+    temperature?: number
+  ): Promise<GenerateResult>;
+
+  // Generate text (streaming)
+  generateStream(
+    prompt: string,
+    maxTokens?: number,
+    temperature?: number
+  ): AsyncGenerator<string, void, unknown>;
+}
+```
+
+#### Load Model (Legacy API)
+
+````
+
 ### Runtime Introspection
 
 #### Get All Methods
@@ -287,7 +520,7 @@ methods.forEach((method) => {
     `${method.method_name}(${method.parameters.map((p) => p.type).join(", ")})`
   );
 });
-```
+````
 
 #### Check Method Availability
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { InitOptions, LoomAPI } from "./types";
+import type { InitOptions, LoomAPI } from "./types.js";
 /**
  * Initialize the LOOM WASM module and return the API
  *
@@ -27,5 +27,7 @@ import type { InitOptions, LoomAPI } from "./types";
  * ```
  */
 export declare function initLoom(opts?: InitOptions): Promise<LoomAPI>;
-export type { LoomAPI, LoomNetwork, InitOptions } from "./types";
-export { ActivationType } from "./types";
+export type { LoomAPI, LoomNetwork, InitOptions, TransformerAPI, } from "./types.js";
+export { ActivationType } from "./types.js";
+export { createTransformerAPI } from "./transformer.js";
+export type { TokenizerLoadResult, TransformerLoadResult, EncodeResult, DecodeResult, GenerateResult, NextTokenResult, } from "./types.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-import { ensureGoRuntime, resolvePackagedWasmURL, instantiateGoWasm, } from "./loader";
+import { ensureGoRuntime, resolvePackagedWasmURL, instantiateGoWasm, } from "./loader.js";
 // tiny helper that waits until WASM has placed symbols on globalThis
 async function waitForExports(keys, timeoutMs = 5000) {
     const t0 = performance.now();
@@ -83,4 +83,5 @@ export async function initLoom(opts = {}) {
     }
     return api;
 }
-export { ActivationType } from "./types";
+export { ActivationType } from "./types.js";
+export { createTransformerAPI } from "./transformer.js";

package/dist/loader.js

@@ -1,4 +1,4 @@
-import { isBrowser } from "./env";
+import { isBrowser } from "./env.js";
 let goRuntimeInjected = false;
 let wasmExecTextBundled;
 let wasmUrlBundled;

package/dist/transformer.d.ts

@@ -0,0 +1,5 @@
+import type { TransformerAPI } from "./types.js";
+/**
+ * Create transformer API wrapper around WASM functions
+ */
+export declare function createTransformerAPI(): Promise<TransformerAPI>;

package/dist/transformer.js

@@ -0,0 +1,127 @@
+/**
+ * Helper to wait for a global function to be available
+ */
+async function waitForGlobal(name, timeoutMs = 5000) {
+    const t0 = performance.now();
+    for (;;) {
+        if (globalThis[name])
+            return;
+        if (performance.now() - t0 > timeoutMs) {
+            throw new Error(`Timeout waiting for ${name}`);
+        }
+        await new Promise((r) => setTimeout(r, 10));
+    }
+}
+/**
+ * Create transformer API wrapper around WASM functions
+ */
+export async function createTransformerAPI() {
+    // Wait for transformer functions to be available
+    await Promise.all([
+        waitForGlobal("LoadTokenizerFromBytes"),
+        waitForGlobal("LoadTransformerFromBytes"),
+        waitForGlobal("EncodeText"),
+        waitForGlobal("DecodeTokens"),
+        waitForGlobal("GenerateNextToken"),
+        waitForGlobal("GenerateText"),
+    ]);
+    const g = globalThis;
+    return {
+        async loadTokenizer(tokenizerData) {
+            return new Promise((resolve, reject) => {
+                try {
+                    const resultStr = g.LoadTokenizerFromBytes(tokenizerData);
+                    // If it's already an object, return it directly
+                    if (typeof resultStr === "object") {
+                        resolve(resultStr);
+                        return;
+                    }
+                    const result = JSON.parse(resultStr);
+                    resolve(result);
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+        },
+        async loadModel(configData, weightsData) {
+            return new Promise((resolve, reject) => {
+                try {
+                    const resultStr = g.LoadTransformerFromBytes(configData, weightsData);
+                    const result = JSON.parse(resultStr);
+                    resolve(result);
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+        },
+        async encode(text, addSpecialTokens = true) {
+            return new Promise((resolve, reject) => {
+                try {
+                    const resultStr = g.EncodeText(text, addSpecialTokens);
+                    const result = JSON.parse(resultStr);
+                    resolve(result);
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+        },
+        async decode(tokenIds, skipSpecialTokens = true) {
+            return new Promise((resolve, reject) => {
+                try {
+                    const resultStr = g.DecodeTokens(tokenIds, skipSpecialTokens);
+                    const result = JSON.parse(resultStr);
+                    resolve(result);
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+        },
+        async generate(prompt, maxTokens = 50, temperature = 0.7) {
+            return new Promise((resolve, reject) => {
+                try {
+                    const resultStr = g.GenerateText(prompt, maxTokens, temperature);
+                    const result = JSON.parse(resultStr);
+                    resolve(result);
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+        },
+        async *generateStream(prompt, maxTokens = 50, temperature = 0.7) {
+            // Encode the prompt
+            const encodeResultStr = g.EncodeText(prompt, true);
+            const encodeResult = JSON.parse(encodeResultStr);
+            if (!encodeResult.success || !encodeResult.ids) {
+                throw new Error(encodeResult.error || "Failed to encode prompt");
+            }
+            const tokens = [...encodeResult.ids];
+            // Generate tokens one at a time
+            for (let i = 0; i < maxTokens; i++) {
+                const resultStr = g.GenerateNextToken(tokens, temperature);
+                const result = JSON.parse(resultStr);
+                if (!result.success) {
+                    throw new Error(result.error || "Failed to generate token");
+                }
+                if (result.token === undefined) {
+                    break;
+                }
+                tokens.push(result.token);
+                // Decode just this token
+                const decodeResultStr = g.DecodeTokens([result.token], true);
+                const decodeResult = JSON.parse(decodeResultStr);
+                if (decodeResult.success && decodeResult.text) {
+                    yield decodeResult.text;
+                }
+                // Check for end of sequence
+                if (result.is_eos) {
+                    break;
+                }
+            }
+        },
+    };
+}

package/dist/types.d.ts

@@ -113,3 +113,99 @@ export declare enum ActivationType {
     LeakyReLU = 4,
     Linear = 5
 }
+/**
+ * Result from tokenizer loading
+ */
+export interface TokenizerLoadResult {
+    success: boolean;
+    vocab_size?: number;
+    message?: string;
+    error?: string;
+}
+/**
+ * Result from transformer model loading
+ */
+export interface TransformerLoadResult {
+    success: boolean;
+    num_layers?: number;
+    hidden_size?: number;
+    vocab_size?: number;
+    message?: string;
+    error?: string;
+}
+/**
+ * Result from text encoding
+ */
+export interface EncodeResult {
+    success: boolean;
+    ids?: number[];
+    error?: string;
+}
+/**
+ * Result from token decoding
+ */
+export interface DecodeResult {
+    success: boolean;
+    text?: string;
+    error?: string;
+}
+/**
+ * Result from text generation
+ */
+export interface GenerateResult {
+    success: boolean;
+    generated_text?: string;
+    error?: string;
+}
+/**
+ * Result from next token generation
+ */
+export interface NextTokenResult {
+    success: boolean;
+    token?: number;
+    is_eos?: boolean;
+    error?: string;
+}
+/**
+ * Transformer API for LLM inference
+ */
+export interface TransformerAPI {
+    /**
+     * Load tokenizer from JSON bytes
+     * @param tokenizerData - Uint8Array of tokenizer.json file
+     */
+    loadTokenizer(tokenizerData: Uint8Array): Promise<TokenizerLoadResult>;
+    /**
+     * Load transformer model from config and weights bytes
+     * @param configData - Uint8Array of config.json file
+     * @param weightsData - Uint8Array of model.safetensors file
+     */
+    loadModel(configData: Uint8Array, weightsData: Uint8Array): Promise<TransformerLoadResult>;
+    /**
+     * Encode text to token IDs
+     * @param text - Input text to encode
+     * @param addSpecialTokens - Whether to add special tokens (default: true)
+     */
+    encode(text: string, addSpecialTokens?: boolean): Promise<EncodeResult>;
+    /**
+     * Decode token IDs to text
+     * @param tokenIds - Array of token IDs
+     * @param skipSpecialTokens - Whether to skip special tokens (default: true)
+     */
+    decode(tokenIds: number[], skipSpecialTokens?: boolean): Promise<DecodeResult>;
+    /**
+     * Generate text from prompt (blocking, all tokens at once)
+     * @param prompt - Input prompt
+     * @param maxTokens - Maximum tokens to generate (default: 50)
+     * @param temperature - Sampling temperature (default: 0.7)
+     */
+    generate(prompt: string, maxTokens?: number, temperature?: number): Promise<GenerateResult>;
+    /**
+     * Generate text token-by-token (streaming)
+     * @param prompt - Input prompt
+     * @param maxTokens - Maximum tokens to generate (default: 50)
+     * @param temperature - Sampling temperature (default: 0.7)
+     * @yields Token text strings
+     */
+    generateStream(prompt: string, maxTokens?: number, temperature?: number): AsyncGenerator<string, void, unknown>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfluke/welvet",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "TypeScript/JavaScript bindings for LOOM neural network framework with WebAssembly support - GPU-accelerated machine learning in the browser",
   "type": "module",
   "main": "./dist/index.js",