@openfluke/welvet 0.1.8 → 0.3.0

package/README.md

@@ -1,18 +1,57 @@
-# @openfluke/welvet
-
-Isomorphic TypeScript/JavaScript wrapper for the LOOM WebAssembly neural network framework.
-
-## Features
-
-- 🎉 **NEW: Simple API** - Streamlined functions with cross-platform consistency
-- 🚀 **Isomorphic WASM Wrapper** - Works in Node.js and browser with same API
-- 🔄 **Mirrors main.go** - Direct 1:1 mapping to WASM exports
-- 🎯 **Type-Safe** - Full TypeScript type definitions for all Network methods
-- 🤖 **Multi-Agent Networks** - Grid scatter architecture for heterogeneous agents
-- 📦 **JSON Configuration** - Build networks from simple JSON configs
-- ⚡ **Fast Training** - Optimized training with configurable parameters
-- 💾 **Model Persistence** - Save and load trained models as JSON
-- ✅ **Cross-Platform Consistency** - Same API as Python, C#, C, WASM
+# @openfluke/welvet - LOOM TypeScript/WASM Bindings
+ 
+ **Wrapper for Embedding Loom Via External (WASM) Toolchain**
+ 
+ High-performance neural network library with **full training in browser/Node.js** via WebAssembly. Zero external dependencies—just import and go.
+ 
+ > **v0.3.0 Update**: Now includes a **Universal Test Suite** (2298 tests) with 100% parity across Browser and Node.js environments.
+
+
+## Framework Comparison
+
+| Feature Category | Feature | **Loom/welvet** | **TensorFlow.js** | **Brain.js** | **ONNX.js** | **Candle (WASM)** |
+| :--- | :--- | :---: | :---: | :---: | :---: | :---: |
+| **Core** | **Runtime** | WASM (Pure Go) | JS + WebGL | Pure JS | WASM | WASM (Rust) |
+| | **Runtime Dependency** | **None** | Heavy | Light | Light | None |
+| **Loading** | **Safetensors** | ✅ **Native** | ❌ | ❌ | ❌ | ✅ |
+| | **Structure Inference** | ✅ **Auto-Detect** | ❌ | ❌ | ❌ | ❌ |
+| **Training** | **Browser Training** | ✅ **Full** | ✅ (Slow) | ✅ | ❌ | ✅ |
+| | **Neural Tweening** | ✅ **Hybrid Engine** | ❌ | ❌ | ❌ | ❌ |
+| | **LR Schedulers** | ✅ **7 Types** | ✅ | ⚠️ | ❌ | ✅ |
+| **Layer Support** | **Dense (MLP)** | ✅ | ✅ | ✅ | ✅ | ✅ |
+| | **Conv1D/2D** | ✅ **Native** | ✅ | ❌ | ✅ | ✅ |
+| | **RNN / LSTM** | ✅ **Full Gate** | ✅ | ✅ | ✅ | ✅ |
+| | **Transformer (MHA)** | ✅ (Explicit) | ✅ | ❌ | ✅ | ✅ |
+| | **Parallel / MoE** | ✅ **Structure** | ❌ (Manual) | ❌ | ❌ | ❌ |
+| | **Sequential Layers** | ✅ **Native** | ⚠️ | ⚠️ | ❌ | ⚠️ |
+| **Advanced** | **Step-Based Forward** | ✅ **Unique** | ❌ | ❌ | ❌ | ❌ |
+| | **Stitch Layers** | ✅ **Native** | ❌ | ❌ | ❌ | ❌ |
+| | **K-Means / Stats** | ✅ **Parallel** | ❌ | ❌ | ❌ | ❌ |
+| | **Cross-Lang ABI** | ✅ **Universal** | ❌ | ❌ | ❌ | ⚠️ |
+| **Streaming** | **LLM Streaming** | ✅ | ✅ | ❌ | ❌ | ✅ |
+| | **Pure Go Tokenizer** | ✅ | ❌ | ❌ | ❌ | ❌ |
+
+For detailed comparison, see [`docs/loom_assessment_comparison.md`](../docs/loom_assessment_comparison.md).
+
+## 🌍 Cross-Ecosystem Compatibility
+
+Models trained in TypeScript can be loaded instantly in Python, C#, Go, or other WASM environments. **Bit-for-bit identical results** across all platforms.
+
+| Platform | Package | Install |
+|:---------|:--------|:--------|
+| **TypeScript/Node** | [NPM](https://www.npmjs.com/package/@openfluke/welvet) | `npm install @openfluke/welvet` |
+| **Python** | [PyPI](https://pypi.org/project/welvet/) | `pip install welvet` |
+| **C#/.NET** | [NuGet](https://www.nuget.org/packages/Welvet) | `dotnet add package Welvet` |
+| **Go** | [GitHub](https://github.com/openfluke/loom) | `go get github.com/openfluke/loom` |
+
+### Key Strengths
+
+- **True Embeddability**: Single WASM binary. Works in Node.js and browsers with the same API.
+- **Hybrid Gradient/Geometric Engine**: "Neural Tweening" combines geometric gap-closing with backpropagation-guided momentum.
+- **Structural Parallelism**: Native support for Inception, ResNeXt, Siamese, and MoE architectures via `LayerParallel`.
+- **Native Mixed-Precision**: Generic tensor backend supports `int8`, `uint16`, and `float32`.
+- **Complete Evaluation Suite**: Deviation metrics, training milestones, and adaptation tracking.
+- **Network Telemetry**: Runtime introspection with `GetMethodsJSON()` and `ExtractNetworkBlueprint()`.
 
 ## Installation
 
@@ -20,18 +59,19 @@ Isomorphic TypeScript/JavaScript wrapper for the LOOM WebAssembly neural network
 npm install @openfluke/welvet
 ```
 
+**Using Bun:**
+```bash
+bun add @openfluke/welvet
+```
+
 ## Quick Start
 
-### 🎉 NEW: Simple API (Recommended)
+### 🎉 Simple API (Recommended)
 
-The simple API provides streamlined functions with consistent behavior across all platforms:
+The simple API provides streamlined functions with **cross-platform consistency**:
 
 ```typescript
-import {
-  init,
-  createNetworkFromJSON,
-  loadLoomNetwork,
-} from "@openfluke/welvet";
+import { init, createNetworkFromJSON, loadLoomNetwork } from "@openfluke/welvet";
 
 // Initialize LOOM WASM
 await init();
@@ -47,33 +87,17 @@ const config = {
     {
       type: "parallel",
       combine_mode: "grid_scatter",
-      grid_output_rows: 3,
-      grid_output_cols: 1,
-      grid_output_layers: 1,
+      grid_output_rows: 3, grid_output_cols: 1, grid_output_layers: 1,
       grid_positions: [
         { branch_index: 0, target_row: 0, target_col: 0, target_layer: 0 },
         { branch_index: 1, target_row: 1, target_col: 0, target_layer: 0 },
         { branch_index: 2, target_row: 2, target_col: 0, target_layer: 0 },
       ],
       branches: [
-        {
-          type: "parallel",
-          combine_mode: "add",
-          branches: [
-            {
-              type: "dense",
-              input_size: 16,
-              output_size: 8,
-              activation: "relu",
-            },
-            {
-              type: "dense",
-              input_size: 16,
-              output_size: 8,
-              activation: "gelu",
-            },
-          ],
-        },
+        { type: "parallel", combine_mode: "add", branches: [
+          { type: "dense", input_size: 16, output_size: 8, activation: "relu" },
+          { type: "dense", input_size: 16, output_size: 8, activation: "gelu" },
+        ]},
         { type: "lstm", input_size: 16, hidden_size: 8, seq_length: 1 },
         { type: "rnn", input_size: 16, hidden_size: 8, seq_length: 1 },
       ],
@@ -88,86 +112,55 @@ const network = createNetworkFromJSON(JSON.stringify(config));
 const batches = [
   { Input: [0.2, 0.2, 0.2, 0.2, 0.8, 0.8, 0.8, 0.8], Target: [1.0, 0.0] },
   { Input: [0.9, 0.9, 0.9, 0.9, 0.1, 0.1, 0.1, 0.1], Target: [0.0, 1.0] },
-  { Input: [0.7, 0.7, 0.7, 0.7, 0.3, 0.3, 0.3, 0.3], Target: [0.0, 1.0] },
-  { Input: [0.3, 0.3, 0.3, 0.3, 0.7, 0.7, 0.7, 0.7], Target: [1.0, 0.0] },
 ];
 
 const trainingConfig = {
   Epochs: 800,
   LearningRate: 0.15,
-  UseGPU: false,
-  PrintEveryBatch: 0,
-  GradientClip: 1.0,
   LossType: "mse",
-  Verbose: false,
+  GradientClip: 1.0,
 };
 
-const [result] = network.Train(JSON.stringify([batches, trainingConfig]));
-console.log("Training complete!");
+network.Train(JSON.stringify([batches, trainingConfig]));
 
 // Forward pass
-const [output] = network.ForwardCPU(
-  JSON.stringify([[0.2, 0.2, 0.2, 0.2, 0.8, 0.8, 0.8, 0.8]])
-);
-console.log("Output:", JSON.parse(output)); // [0.950, 0.050]
-
-// Evaluate network
-const inputs = batches.map((b) => b.Input);
-const expected = [0, 1, 1, 0];
-const [metrics] = network.EvaluateNetwork(JSON.stringify([inputs, expected]));
-const metricsData = JSON.parse(metrics);
-console.log(
-  `Quality: ${metricsData.score}/100, Deviation: ${metricsData.avg_deviation}%`
-);
+const [output] = network.ForwardCPU(JSON.stringify([[0.2, 0.2, 0.2, 0.2, 0.8, 0.8, 0.8, 0.8]]));
+console.log("Output:", JSON.parse(output)); // [0.95, 0.05]
 
 // Save/Load
 const [modelJSON] = network.SaveModelToString(JSON.stringify(["my_model"]));
-console.log(`Model saved (${modelJSON.length} bytes)`);
-
-// Load model
 const loadedNetwork = loadLoomNetwork(modelJSON, "my_model");
-const [output2] = loadedNetwork.ForwardCPU(
-  JSON.stringify([[0.2, 0.2, 0.2, 0.2, 0.8, 0.8, 0.8, 0.8]])
-);
-// output2 === output (bit-for-bit identical!)
 ```
 
 **Simple API Functions:**
 
-- `createNetworkFromJSON(jsonConfig)` - Create network from JSON
-- `loadLoomNetwork(jsonString, modelID)` - Load saved model
-- `network.ForwardCPU(inputJSON)` - Forward pass
-- `network.BackwardCPU(gradientsJSON)` - Backward pass
-- `network.Train(paramsJSON)` - Train network
-- `network.SaveModelToString(idJSON)` - Save to JSON string
-- `network.EvaluateNetwork(paramsJSON)` - Evaluate with metrics
-- `network.UpdateWeights(lrJSON)` - Update weights
-
-**Cross-Platform Results:**
-
-- ✅ Same training: 99.5% improvement, 100/100 quality score
-- ✅ Same save/load: 0.00 difference in predictions
-- ✅ Same evaluation: Identical deviation metrics
-- ✅ Same behavior as Python, C#, C, and WASM
-
-See `example/grid-scatter.ts` for a complete working example.
+| Function | Description |
+|:---------|:------------|
+| `createNetworkFromJSON(config)` | Create network from JSON |
+| `loadLoomNetwork(json, id)` | Load saved model |
+| `network.ForwardCPU(input)` | Forward pass |
+| `network.BackwardCPU(gradients)` | Backward pass |
+| `network.Train(params)` | Train network |
+| `network.SaveModelToString(id)` | Save to JSON string |
+| `network.EvaluateNetwork(params)` | Evaluate with metrics |
 
 ### ⚡ Stepping API - Fine-Grained Execution Control
 
-**NEW:** Execute networks one step at a time for online learning:
+Execute networks one step at a time for online learning:
 
 ```typescript
 import { init, createNetwork, StepState } from "@openfluke/welvet";
 
 await init();
 
-// Create network
-const config = { batch_size: 1, layers: [
-  { type: "dense", input_height: 4, output_height: 8, activation: "relu" },
-  { type: "lstm", input_size: 8, hidden_size: 12, seq_length: 1 },
-  { type: "dense", input_height: 12, output_height: 3, activation: "softmax" }
-]};
-const network = createNetwork(config);
+const network = createNetwork({
+  batch_size: 1,
+  layers: [
+    { type: "dense", input_height: 4, output_height: 8, activation: "relu" },
+    { type: "lstm", input_size: 8, hidden_size: 12, seq_length: 1 },
+    { type: "dense", input_height: 12, output_height: 3, activation: "softmax" }
+  ]
+});
 
 // Initialize stepping state
 const state: StepState = network.createStepState(4);
@@ -178,12 +171,8 @@ for (let step = 0; step < 100000; step++) {
   state.stepForward();
   const output = state.getOutput();
   
-  // Calculate gradients
-  const gradients = new Float32Array(output.length);
-  for (let i = 0; i < output.length; i++)
-    gradients[i] = output[i] - target[i];
-  
   // Backward pass
+  const gradients = output.map((o, i) => o - target[i]);
   state.stepBackward(gradients);
   
   // Update weights immediately
@@ -191,19 +180,9 @@ for (let step = 0; step < 100000; step++) {
 }
 ```
 
-**Stepping API:**
-- `network.createStepState(inputSize)` - Initialize stepping state
-- `state.setInput(data)` - Set input for current step
-- `state.stepForward()` - Execute forward pass
-- `state.getOutput()` - Get output from last layer
-- `state.stepBackward(gradients)` - Execute backward pass
-- `network.ApplyGradients(paramsJSON)` - Update network weights
-
-See `example/step_train_v3.ts` for a complete example achieving 100% accuracy.
-
 ### 🧠 Neural Tweening API - Gradient-Free Learning
 
-**NEW:** Direct weight adjustment without backpropagation:
+Direct weight adjustment without backpropagation:
 
 ```typescript
 import { init, createNetwork, TweenState } from "@openfluke/welvet";
@@ -217,212 +196,215 @@ const tweenState: TweenState = network.createTweenState(true); // useChainRule=t
 
 // Training loop - direct weight updates
 for (let step = 0; step < 10000; step++) {
-  const input = new Float32Array([0.1, 0.2, 0.3, 0.4]);
-  const targetClass = 1; // Target output class
-  
-  // Single-step tween learning
-  const loss = tweenState.TweenStep(input, targetClass, 4, 0.02);
+  const loss = tweenState.TweenStep(
+    new Float32Array([0.1, 0.2, 0.3, 0.4]),
+    1,     // targetClass
+    4,     // outputSize
+    0.02   // learningRate
+  );
 }
 ```
 
-**Tweening API:**
-- `network.createTweenState(useChainRule)` - Initialize tween state
-- `tweenState.TweenStep(input, targetClass, outputSize, lr)` - Train step
-- `tweenState.setChainRule(enabled)` - Toggle chain rule
-- `tweenState.getChainRule()` - Get chain rule status
-- `tweenState.getTweenSteps()` - Get total steps performed
-
-### 📊 Adaptation Benchmark - Multi-Architecture Testing
+### 📊 Adaptation Benchmark
 
-**NEW:** Run the full Test 18 Multi-Architecture Adaptation Benchmark:
+Run the full multi-architecture adaptation benchmark:
 
 ```bash
 cd example
 bun run test18_adaptation.ts
 ```
 
-Tests 5 architectures × 3 depths × 5 training modes (75 tests total):
+Tests **5 architectures × 3 depths × 5 training modes** (75 tests total):
 - **Architectures:** Dense, Conv2D, RNN, LSTM, Attention
 - **Depths:** 3, 5, 9 layers
 - **Modes:** NormalBP, StepBP, Tween, TweenChain, StepTweenChain
 
-Measures adaptation speed when tasks change mid-stream (chase→avoid→chase).
+## Complete Test Suite
+ 
+ The `universal_test.ts` example demonstrates all framework capabilities with **100% parity** to the Go/C core.
+ 
+ ### Running in Browser (v0.3.0+)
+ 
+ The universal test suite now runs directly in the browser with a full DOM report:
+ 
+ ```bash
+ cd typescript
+ python3 serve.py
+ # Open http://localhost:8081
+ ```
+ 
+ ### Running in Node/Bun
+ 
+ ```bash
+ cd example
+ bun run universal_test.ts
+ ```
+ 
+ **Test Coverage (2298 Tests):**
+ - ✅ **Serialization**: 12 Layer Types × 15 Data Types (2100 combinations)
+ - ✅ **In-Memory WASM**: SafeTensors without filesystem (144 tests)
+ - ✅ **Advanced Math**: K-Means, Correlation, Grafting, Ensembles
+ - ✅ **GPU Parity**: Determinism checks for forward/backward passes
+ - ✅ **Core**: Architecture generation, combinators, sequential layers
+ 
+ See [`example/universal_test.ts`](./example/universal_test.ts) for the complete test implementation.
 
-See `example/test18_adaptation.ts` for the full implementation.
-
-```
-
-## API Reference
-
-### Functions
-
-#### `async init(): Promise<void>`
-
-Initialize LOOM WASM module for Node.js environment.
+## Layer Types
 
-#### `async initBrowser(): Promise<void>`
+| Layer | Type String | Description |
+|:------|:------------|:------------|
+| Dense | `dense` | Fully connected layer |
+| LSTM | `lstm` | Long Short-Term Memory |
+| RNN | `rnn` | Recurrent Neural Network |
+| GRU | `gru` | Gated Recurrent Unit |
+| Conv2D | `conv2d` | 2D Convolution |
+| Conv1D | `conv1d` | 1D Convolution |
+| Multi-Head Attention | `multi_head_attention` | Transformer attention |
+| LayerNorm | `layer_norm` | Layer normalization |
+| RMSNorm | `rms_norm` | RMS normalization |
+| SwiGLU | `swiglu` | SwiGLU activation layer |
+| Softmax | `softmax` | Softmax classification |
+| Embedding | `embedding` | Token embedding |
+| Parallel | `parallel` | Branching with combine modes |
+| Sequential | `sequential` | Grouped sub-layers |
+
+**Parallel Combine Modes:** `add`, `concat`, `multiply`, `average`, `grid_scatter`, `filter`
 
-Initialize LOOM WASM module for browser environment.
+## Activation Functions
 
-#### `createNetwork(config: object | string): Network`
+`relu`, `sigmoid`, `tanh`, `softmax`, `gelu`, `swish`, `mish`, `leaky_relu`, `elu`, `selu`, `linear`
 
-Create a new neural network from JSON configuration object or string.
+## API Reference
 
-**Note:** This is the only global function exposed by the WASM (mirrors `createLoomNetwork` from main.go). To load a saved model, just pass the saved JSON string to `createNetwork()`.
+### Initialization
 
-### Network Interface
+```typescript
+import { init, initBrowser, createNetwork, createNetworkFromJSON } from "@openfluke/welvet";
 
-The `Network` object returned by `createNetwork()` has all methods from the Go `nn.Network` type automatically exposed via reflection.
+// Node.js
+await init();
 
-**Important:** All Network methods follow the WASM calling convention:
+// Browser
+await initBrowser();
+```
 
-- Take a single parameter: JSON string of an array of parameters
-- Return a JSON string of an array of results
+### Network Methods
 
-Example:
+All Network methods follow the WASM calling convention:
+- **Input:** JSON string of an array of parameters
+- **Return:** JSON string of an array of results
 
 ```typescript
 // Method with no parameters
 const info = network.GetNetworkInfo(JSON.stringify([]));
-const parsed = JSON.parse(info)[0];
 
 // Method with parameters
 const result = network.Train(JSON.stringify([batches, config]));
-const data = JSON.parse(result)[0];
 
-// Save model (requires modelID parameter)
+// Save model
 const saved = network.SaveModelToString(JSON.stringify(["my-model"]));
-const json = JSON.parse(saved)[0];
-````
-
-#### Available Network Methods
-
-- `ForwardCPU(paramsJSON)` - CPU forward pass: `[inputs]`
-- `ForwardGPU(paramsJSON)` - GPU forward pass: `[inputs]`
-- `BackwardCPU(paramsJSON)` - CPU backward pass: `[gradients]`
-- `BackwardGPU(paramsJSON)` - GPU backward pass: `[gradients]`
-- `UpdateWeights(paramsJSON)` - Update weights: `[learningRate]`
-- `Train(paramsJSON)` - Train network: `[batches, config]`
-- `SaveModelToString(paramsJSON)` - Save model: `["modelID"]`
-- `GetWeights(paramsJSON)` - Get layer weights: `[row, col, layer]`
-- `SetWeights(paramsJSON)` - Set layer weights: `[row, col, layer, weights]`
-- `GetBiases(paramsJSON)` - Get layer biases: `[row, col, layer]`
-- `SetBiases(paramsJSON)` - Set layer biases: `[row, col, layer, biases]`
-- `GetActivation(paramsJSON)` - Get activation: `[row, col, layer]`
-- `GetLayerType(paramsJSON)` - Get layer type: `[row, col, layer]`
-- `GetLayerSizes(paramsJSON)` - Get layer sizes: `[row, col, layer]`
-- `GetBatchSize(paramsJSON)` - Get batch size: `[]`
-- `GetGridDimensions(paramsJSON)` - Get grid dimensions: `[]`
-- `GetNetworkInfo(paramsJSON)` - Get network info: `[]`
-- `GetTotalParameters(paramsJSON)` - Get parameter count: `[]`
-- `InitializeWeights(paramsJSON)` - Initialize weights: `[]` or `[method]`
-- `Clone(paramsJSON)` - Clone network: `[]`
-- And 10+ more methods...
-- `GetLastOutput(): string` - Get last forward pass output
-
-### Types
-
-#### `NetworkConfig`
-
-```typescript
-interface NetworkConfig {
-  batch_size: number;
-  grid_rows?: number; // Required for grid networks (use 1 for sequential)
-  grid_cols?: number; // Required for grid networks (use 1 for sequential)
-  layers_per_cell?: number; // Required for grid networks
-  layers: LayerConfig[];
-}
 ```
 
-#### `LayerConfig`
+**Available Methods:**
+
+| Method | Parameters | Description |
+|:-------|:-----------|:------------|
+| `ForwardCPU` | `[inputs]` | CPU forward pass |
+| `ForwardGPU` | `[inputs]` | GPU forward pass |
+| `BackwardCPU` | `[gradients]` | CPU backward pass |
+| `Train` | `[batches, config]` | Train network |
+| `SaveModelToString` | `["modelID"]` | Save to JSON |
+| `GetWeights` | `[row, col, layer]` | Get layer weights |
+| `SetWeights` | `[row, col, layer, weights]` | Set layer weights |
+| `GetBiases` | `[row, col, layer]` | Get layer biases |
+| `SetBiases` | `[row, col, layer, biases]` | Set layer biases |
+| `GetNetworkInfo` | `[]` | Get network info |
+| `GetTotalParameters` | `[]` | Get parameter count |
+| `Clone` | `[]` | Clone network |
+| `TotalLayers` | `[]` | Get total layer count |
+
+### Statistical Tools
 
 ```typescript
-interface LayerConfig {
-  type: string;
-  input_size?: number;
-  output_size?: number;
-  hidden_size?: number;
-  seq_length?: number;
-  activation?: string;
-  combine_mode?: string;
-  grid_output_rows?: number;
-  grid_output_cols?: number;
-  grid_output_layers?: number;
-  grid_positions?: GridPosition[];
-  branches?: LayerConfig[];
-}
+import welvet from "@openfluke/welvet";
+
+// K-Means Clustering
+const data = [[1, 1], [1.1, 1.1], [5, 5], [5.1, 5.1]];
+const result = welvet.kmeans(data, 2, 100);
+console.log(`Centroids: ${result.centroids}`);
+console.log(`Silhouette Score: ${result.silhouette_score}`);
+
+// Correlation Matrix
+const matrix = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
+const corr = welvet.correlation(matrix);
+console.log(`Pearson: ${corr.pearson}`);
 ```
 
-#### `TrainingBatch`
-
-```typescript
-interface TrainingBatch {
-  Input: number[];
-  Target: number[];
-}
-```
+### Network Grafting
 
-#### `TrainingConfig`
+Combine multiple trained networks:
 
 ```typescript
-interface TrainingConfig {
-  Epochs: number;
-  LearningRate: number;
-  LossType?: string;
-  Verbose?: boolean;
-  UseGPU?: boolean;
-  PrintEveryBatch?: number;
-  GradientClip?: number;
-}
+const h1 = welvet.createKHandle(config);
+const h2 = welvet.createKHandle(config);
+
+const result = welvet.graft([h1, h2], "concat");
+console.log(`Grafted: ${result.num_branches} branches`);
 ```
 
 ## Examples
 
-### Grid Scatter Multi-Agent
-
 ```bash
 cd example
-bun install
-bun run grid-scatter.ts
-```
 
-### Stepping Training (LSTM)
+# Grid Scatter Multi-Agent
+bun run grid-scatter.ts
 
-```bash
+# Stepping Training (LSTM)
 bun run step_train_v3.ts
-```
-
-### Adaptation Benchmark (75 tests)
 
-```bash
+# Adaptation Benchmark (75 tests)
 bun run test18_adaptation.ts
-```
 
-> **Note:** Full benchmark takes ~12.5 minutes (10 seconds per test)
+# Full Test Suite (77 tests)
+bun run universal_test.ts
+```
 
-## Layer Types
+## TypeScript Types
 
-- `dense` - Fully connected layer
-- `lstm` - Long Short-Term Memory layer
-- `rnn` - Recurrent Neural Network layer
-- `gru` - Gated Recurrent Unit layer
-- `cnn` - Convolutional layer
-- `parallel` - Parallel branches with combine modes:
-  - `add` - Element-wise addition
-  - `concat` - Concatenation
-  - `multiply` - Element-wise multiplication
-  - `grid_scatter` - Multi-agent grid routing
+```typescript
+interface NetworkConfig {
+  batch_size: number;
+  grid_rows?: number;
+  grid_cols?: number;
+  layers_per_cell?: number;
+  layers: LayerConfig[];
+  dtype?: "float32" | "float64" | "int32" | "int16" | "int8" | "uint8";
+}
 
-## Activation Functions
+interface TrainingConfig {
+  Epochs: number;
+  LearningRate: number;
+  LossType?: string;
+  Verbose?: boolean;
+  UseGPU?: boolean;
+  GradientClip?: number;
+}
 
-`relu`, `sigmoid`, `tanh`, `softmax`, `gelu`, `swish`, `mish`, `leaky_relu`, `elu`, `selu`
+interface TrainingBatch {
+  Input: number[];
+  Target: number[];
+}
+```
 
 ## License
 
-APACHE2
+Apache-2.0
 
 ## Links
 
-- [GitHub](https://github.com/openfluke/loom)
-- [WASM Documentation](../wasm/README.md)
-- [Go Examples](../examples/)
+- **GitHub**: [github.com/openfluke/loom](https://github.com/openfluke/loom)
+- **NPM**: [@openfluke/welvet](https://www.npmjs.com/package/@openfluke/welvet)
+- **PyPI**: [welvet](https://pypi.org/project/welvet/)
+- **NuGet**: [Welvet](https://www.nuget.org/packages/Welvet)
+- **Documentation**: [`docs/loom_assessment_comparison.md`](../docs/loom_assessment_comparison.md)

package/dist/index.d.ts

@@ -4,24 +4,53 @@
  * Direct wrapper around Loom WASM that mirrors main.go exports exactly.
  * Provides the same API in both Node.js and browser environments.
  */
-import { Network } from "./types.js";
-import { loadLoomWASM } from "./loader.js";
+import { Network, GraftResult, KMeansResult, CorrelationResult, EnsembleMatch, AdaptationTracker } from "./types.js";
 import { loadLoomWASMBrowser } from "./loader.browser.js";
 export * from "./types.js";
-export { loadLoomWASM, loadLoomWASMBrowser };
+export { loadLoomWASMBrowser };
+export declare function loadLoomWASM(): Promise<void>;
 /**
- * Initialize WASM for Node.js environment
+ * Initialize WASM
+ * Auto-detects environment (Browser vs Node.js)
  */
-export declare function init(): Promise<void>;
+export declare function init(wasmUrl?: string): Promise<void>;
 /**
  * Initialize WASM for Browser environment
  */
-export declare function initBrowser(): Promise<void>;
+export declare function initBrowser(wasmUrl?: string): Promise<void>;
 /**
  * Create a network from JSON config
  * Wrapper around the global createLoomNetwork function exposed by WASM
  */
 export declare function createNetwork(config: object | string): Network;
+/**
+ * Load a network from JSON string and ID
+ */
+export declare function loadNetwork(jsonString: string, modelID: string): Network;
+/**
+ * Create a network handle for grafting
+ */
+export declare function createKHandle(config: object | string): number;
+/**
+ * Graft multiple networks together
+ */
+export declare function graft(ids: number[], combineMode: string): GraftResult;
+/**
+ * Perform K-Means Clustering
+ */
+export declare function kmeans(data: number[][], k: number, iter: number): KMeansResult;
+/**
+ * Compute Correlation Matrix
+ */
+export declare function correlation(matrixA: number[][], matrixB?: number[][]): CorrelationResult;
+/**
+ * Find Complementary Ensemble Matches
+ */
+export declare function ensemble(models: object[], minCoverage: number): EnsembleMatch[];
+/**
+ * Create Adaptation Tracker
+ */
+export declare function tracker(windowMs: number, totalMs: number): AdaptationTracker;
 /**
  * Default export with all functions
  */
@@ -29,5 +58,12 @@ declare const _default: {
     init: typeof init;
     initBrowser: typeof initBrowser;
     createNetwork: typeof createNetwork;
+    loadNetwork: typeof loadNetwork;
+    createKHandle: typeof createKHandle;
+    graft: typeof graft;
+    kmeans: typeof kmeans;
+    correlation: typeof correlation;
+    ensemble: typeof ensemble;
+    tracker: typeof tracker;
 };
 export default _default;

package/dist/index.js

@@ -4,21 +4,29 @@
  * Direct wrapper around Loom WASM that mirrors main.go exports exactly.
  * Provides the same API in both Node.js and browser environments.
  */
-import { loadLoomWASM } from "./loader.js";
 import { loadLoomWASMBrowser } from "./loader.browser.js";
 export * from "./types.js";
-export { loadLoomWASM, loadLoomWASMBrowser };
+export { loadLoomWASMBrowser };
+export async function loadLoomWASM() {
+    const mod = await import("./loader.js");
+    await mod.loadLoomWASM();
+}
 /**
- * Initialize WASM for Node.js environment
+ * Initialize WASM
+ * Auto-detects environment (Browser vs Node.js)
  */
-export async function init() {
-    await loadLoomWASM();
+export async function init(wasmUrl) {
+    // Check for browser environment (needs window and document for loader.browser.ts)
+    if (typeof window !== "undefined" && typeof document !== "undefined") {
+        return initBrowser(wasmUrl);
+    }
+    return loadLoomWASM();
 }
 /**
  * Initialize WASM for Browser environment
  */
-export async function initBrowser() {
-    await loadLoomWASMBrowser();
+export async function initBrowser(wasmUrl) {
+    await loadLoomWASMBrowser(wasmUrl);
 }
 /**
  * Create a network from JSON config
@@ -30,11 +38,73 @@ export function createNetwork(config) {
         : JSON.stringify(config);
     return createLoomNetwork(jsonConfig);
 }
+/**
+ * Load a network from JSON string and ID
+ */
+export function loadNetwork(jsonString, modelID) {
+    return loadLoomNetwork(jsonString, modelID);
+}
+/**
+ * Create a network handle for grafting
+ */
+export function createKHandle(config) {
+    const jsonConfig = typeof config === "string" ? config : JSON.stringify(config);
+    return createNetworkForGraft(jsonConfig);
+}
+/**
+ * Graft multiple networks together
+ */
+export function graft(ids, combineMode) {
+    const idsJSON = JSON.stringify(ids);
+    const resJSON = graftNetworks(idsJSON, combineMode);
+    return JSON.parse(resJSON);
+}
+/**
+ * Perform K-Means Clustering
+ */
+export function kmeans(data, k, iter) {
+    const resJSON = kmeansCluster(JSON.stringify(data), k, iter);
+    return JSON.parse(resJSON);
+}
+/**
+ * Compute Correlation Matrix
+ */
+export function correlation(matrixA, matrixB) {
+    const jsonA = JSON.stringify(matrixA);
+    const jsonB = matrixB ? JSON.stringify(matrixB) : "null"; // Use "null" string for nil
+    const resJSON = computeCorrelation(jsonA, jsonB);
+    const raw = JSON.parse(resJSON);
+    // Transform to match interface
+    return {
+        pearson: raw.correlation?.matrix || raw.Correlation?.Matrix || raw.matrix || [],
+        spearman: raw.spearman?.matrix || raw.Spearman?.Matrix || []
+    };
+}
+/**
+ * Find Complementary Ensemble Matches
+ */
+export function ensemble(models, minCoverage) {
+    const resJSON = findComplementaryMatches(JSON.stringify(models), minCoverage);
+    return JSON.parse(resJSON);
+}
+/**
+ * Create Adaptation Tracker
+ */
+export function tracker(windowMs, totalMs) {
+    return createAdaptationTracker(windowMs, totalMs);
+}
 /**
  * Default export with all functions
  */
 export default {
     init,
     initBrowser,
-    createNetwork
+    createNetwork,
+    loadNetwork,
+    createKHandle,
+    graft,
+    kmeans,
+    correlation,
+    ensemble,
+    tracker
 };

package/dist/loader.browser.d.ts

@@ -2,4 +2,4 @@
  * LOOM WASM Browser Loader
  * Browser-only version without Node.js dependencies
  */
-export declare function loadLoomWASMBrowser(): Promise<void>;
+export declare function loadLoomWASMBrowser(wasmUrl?: string): Promise<void>;

package/dist/loader.browser.js

@@ -2,7 +2,7 @@
  * LOOM WASM Browser Loader
  * Browser-only version without Node.js dependencies
  */
-export async function loadLoomWASMBrowser() {
+export async function loadLoomWASMBrowser(wasmUrl) {
     // For browser environments - load wasm_exec.js first if not already loaded
     if (typeof globalThis.Go === "undefined") {
         // Load wasm_exec.js dynamically from /dist/
@@ -14,7 +14,7 @@ export async function loadLoomWASMBrowser() {
             document.head.appendChild(script);
         });
     }
-    const response = await fetch("/dist/main.wasm");
+    const response = await fetch(wasmUrl || "/dist/main.wasm");
     const wasmBuffer = await response.arrayBuffer();
     // @ts-ignore - Go is defined by wasm_exec.js
     const go = new Go();

package/dist/loader.js

@@ -2,12 +2,13 @@
  * LOOM WASM Loader
  * Loads and initializes the LOOM WebAssembly module (Node.js only)
  */
-import { readFileSync } from "fs";
-import { fileURLToPath } from "url";
-import { dirname, join } from "path";
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+// Node.js only loader - using dynamic imports to allow bundling for browser (where this file is not used but might be analyzed)
 export async function loadLoomWASM() {
+    const fs = await import("fs");
+    const url = await import("url");
+    const path = await import("path");
+    const __filename = url.fileURLToPath(import.meta.url);
+    const __dirname = path.dirname(__filename);
     // __dirname points to:
     // - dist/   → in production
     // - src/    → when running via Bun, ts-node, or example files
@@ -19,16 +20,16 @@ export async function loadLoomWASM() {
     else {
         // Running from src/ or example/
         // Point to project’s dist/ directory
-        root = join(__dirname, "..", "dist");
+        root = path.join(__dirname, "..", "dist");
     }
     // Load wasm_exec.js
-    const wasmExecPath = join(root, "wasm_exec.js");
-    const wasmExecCode = readFileSync(wasmExecPath, "utf-8");
+    const wasmExecPath = path.join(root, "wasm_exec.js");
+    const wasmExecCode = fs.readFileSync(wasmExecPath, "utf-8");
     // Execute wasm_exec.js to get the Go runtime
     eval(wasmExecCode);
     // Load main.wasm
-    const wasmPath = join(root, "main.wasm");
-    const wasmBuffer = readFileSync(wasmPath);
+    const wasmPath = path.join(root, "main.wasm");
+    const wasmBuffer = fs.readFileSync(wasmPath);
     // @ts-ignore - Go runtime from wasm_exec.js
     const go = new Go();
     const { instance } = await WebAssembly.instantiate(wasmBuffer, go.importObject);

package/dist/types.d.ts

@@ -6,13 +6,33 @@ export interface LayerConfig {
     input_size?: number;
     output_size?: number;
     hidden_size?: number;
-    seq_length?: number;
     activation?: string;
     combine_mode?: string;
     grid_output_rows?: number;
     grid_output_cols?: number;
     grid_output_layers?: number;
     grid_positions?: GridPosition[];
+    input_height?: number;
+    output_height?: number;
+    input_width?: number;
+    input_channels?: number;
+    output_channels?: number;
+    kernel_size?: number;
+    stride?: number;
+    padding?: number;
+    filters?: number;
+    d_model?: number;
+    num_heads?: number;
+    seq_length?: number;
+    norm_size?: number;
+    vocab_size?: number;
+    embedding_dim?: number;
+    epsilon?: number;
+    softmax_variant?: string;
+    temperature?: number;
+    residual?: boolean;
+    filter_gate?: LayerConfig;
+    filter_temperature?: number;
     branches?: LayerConfig[];
 }
 export interface NetworkConfig {
@@ -137,7 +157,36 @@ export interface TweenState {
  */
 declare global {
     function createLoomNetwork(jsonConfig: string): Network;
+    function loadLoomNetwork(jsonString: string, modelID: string): Network;
     function createAdaptationTracker(windowMs: number, totalMs: number): AdaptationTracker;
+    function createNetworkForGraft(jsonConfig: string): number;
+    function graftNetworks(idsJSON: string, combineMode: string): string;
+    function kmeansCluster(dataJSON: string, k: number, iter: number): string;
+    function computeCorrelation(matrixAJSON: string, matrixBJSON: string): string;
+    function findComplementaryMatches(modelsJSON: string, minCoverage: number): string;
+}
+export interface EnsembleMatch {
+    ModelA: string;
+    ModelB: string;
+    Coverage: number;
+    Overlap: number;
+    WeightedAcc?: number;
+}
+export interface GraftResult {
+    success: boolean;
+    type: string;
+    num_branches: number;
+    combine_mode: string;
+    error?: string;
+}
+export interface KMeansResult {
+    centroids: number[][];
+    assignment: number[];
+    silhouette_score: number;
+}
+export interface CorrelationResult {
+    pearson: number[][];
+    spearman: number[][];
 }
 /**
  * AdaptationTracker interface for tracking accuracy during task changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfluke/welvet",
-  "version": "0.1.8",
+  "version": "0.3.0",
   "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",
@@ -22,13 +22,41 @@
     "gpu",
     "typescript",
     "javascript",
-    "go",
-    "golang",
     "ml",
     "ai",
     "training",
     "inference",
-    "browser"
+    "browser",
+    "nodejs",
+    "isomorphic",
+    "transformer",
+    "lstm",
+    "rnn",
+    "gru",
+    "attention",
+    "multi-head-attention",
+    "conv2d",
+    "conv1d",
+    "convolution",
+    "embedding",
+    "layer-norm",
+    "rms-norm",
+    "swiglu",
+    "moe",
+    "mixture-of-experts",
+    "tweening",
+    "gradient-free",
+    "safetensors",
+    "cross-platform",
+    "clustering",
+    "kmeans",
+    "k-means",
+    "correlation",
+    "statistics",
+    "streaming",
+    "llm",
+    "tokenizer",
+    "bpe"
   ],
   "license": "Apache-2.0",
   "repository": {