@openfluke/welvet 0.3.0 → 0.75.0

package/README.md

@@ -1,410 +1,121 @@
-# @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()`.
+# @openfluke/welvet
+
+**M-POLY-VTD AI Engine (Loom v0.75.0)** — Isomorphic TypeScript/WASM library for building, training, and evolving neural networks with 21 numerical types, WebGPU acceleration, and DNA-based evolution.
+
+[![npm version](https://img.shields.io/npm/v/@openfluke/welvet.svg)](https://www.npmjs.com/package/@openfluke/welvet)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+## Features
+
+- **Isomorphic Architecture**: Runs seamlessly in Node.js, Bun, and the Browser (React/Frontend).
+- **Multi-Precision Support**: Native support for 21 numerical types (FP64, FP32, FP16, BF16, FP8, INT8... all the way down to Binary/Ternary).
+- **Hybrid Training**: standard Backprop, Target Propagation, and NEAT-style structural evolution in a single unified engine.
+- **Hardware Acceleration**: WebGPU support for high-performance inference and training in the browser.
+- **DNA Evolution**: Network "DNA" extraction and comparison for architectural analysis and genetic recombination.
 
 ## Installation
 
 ```bash
 npm install @openfluke/welvet
-```
-
-**Using Bun:**
-```bash
+# or
 bun add @openfluke/welvet
 ```
 
 ## Quick Start
 
-### 🎉 Simple API (Recommended)
+### 1. Initialization
 
-The simple API provides streamlined functions with **cross-platform consistency**:
+The engine initializes automatically after a single call to `init()`. It detects whether it's running in Node.js, Bun, or the Browser and loads the appropriate WASM environment.
 
 ```typescript
-import { init, createNetworkFromJSON, loadLoomNetwork } from "@openfluke/welvet";
-
-// Initialize LOOM WASM
-await init();
-
-// Create network from JSON config
-const config = {
-  batch_size: 1,
-  grid_rows: 1,
-  grid_cols: 3,
-  layers_per_cell: 1,
-  layers: [
-    { type: "dense", input_size: 8, output_size: 16, activation: "relu" },
-    {
-      type: "parallel",
-      combine_mode: "grid_scatter",
-      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: "lstm", input_size: 16, hidden_size: 8, seq_length: 1 },
-        { type: "rnn", input_size: 16, hidden_size: 8, seq_length: 1 },
-      ],
-    },
-    { type: "dense", input_size: 24, output_size: 2, activation: "sigmoid" },
-  ],
-};
-
-const network = createNetworkFromJSON(JSON.stringify(config));
-
-// Training
-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] },
-];
-
-const trainingConfig = {
-  Epochs: 800,
-  LearningRate: 0.15,
-  LossType: "mse",
-  GradientClip: 1.0,
-};
-
-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.95, 0.05]
+import welvet from "@openfluke/welvet";
 
-// Save/Load
-const [modelJSON] = network.SaveModelToString(JSON.stringify(["my_model"]));
-const loadedNetwork = loadLoomNetwork(modelJSON, "my_model");
+await welvet.init(); // Auto-detects Node.js/Browser and loads WASM
 ```
 
-**Simple API Functions:**
-
-| 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 |
+> [!TIP]
+> In browser environments, if your assets are served from a non-standard path, you can optionally pass a custom URL: `await init("/custom/path/to/main.wasm")`.
 
-### ⚡ Stepping API - Fine-Grained Execution Control
-
-Execute networks one step at a time for online learning:
+### 2. Create a Network
 
 ```typescript
-import { init, createNetwork, StepState } from "@openfluke/welvet";
-
-await init();
+import welvet from "@openfluke/welvet";
 
-const network = createNetwork({
-  batch_size: 1,
+// 1D sequential stack on the Volumetric Grid (cell 0,0,0)
+const net = welvet.createNetwork({
+  depth: 1, rows: 1, cols: 1, layers_per_cell: 2,
   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" }
+    { z: 0, y: 0, x: 0, l: 0, type: "Dense", input_height: 784, output_height: 256, activation: "ReLU" },
+    { z: 0, y: 0, x: 0, l: 1, type: "Dense", input_height: 256, output_height: 10, activation: "Linear" }
   ]
 });
 
-// Initialize stepping state
-const state: StepState = network.createStepState(4);
-
-// Training loop - update weights after EACH step
-for (let step = 0; step < 100000; step++) {
-  state.setInput(new Float32Array([0.1, 0.2, 0.1, 0.3]));
-  state.stepForward();
-  const output = state.getOutput();
-  
-  // Backward pass
-  const gradients = output.map((o, i) => o - target[i]);
-  state.stepBackward(gradients);
-  
-  // Update weights immediately
-  network.ApplyGradients(JSON.stringify([learningRate]));
-}
+const input = new Float32Array(784).fill(0.5);
+const output = net.sequentialForward(input);
+console.log("Prediction:", output[0]); // Returns Float32Array
 ```
 
-### 🧠 Neural Tweening API - Gradient-Free Learning
-
-Direct weight adjustment without backpropagation:
+### 3. Training
 
 ```typescript
-import { init, createNetwork, TweenState } from "@openfluke/welvet";
-
-await init();
-
-const network = createNetwork(config);
-
-// Create tween state (with optional chain rule)
-const tweenState: TweenState = network.createTweenState(true); // useChainRule=true
-
-// Training loop - direct weight updates
-for (let step = 0; step < 10000; step++) {
-  const loss = tweenState.TweenStep(
-    new Float32Array([0.1, 0.2, 0.3, 0.4]),
-    1,     // targetClass
-    4,     // outputSize
-    0.02   // learningRate
-  );
-}
-```
+import { trainNetwork } from "@openfluke/welvet";
 
-### 📊 Adaptation Benchmark
-
-Run the full multi-architecture adaptation benchmark:
+const batches = [
+  { input: [0.1, 0.2, ...], target: [1, 0, ...] },
+];
 
-```bash
-cd example
-bun run test18_adaptation.ts
+const result = trainNetwork(net, batches, 10, 0.001);
+console.log("Final Loss:", result.final_loss);
 ```
 
-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
-
-## 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.
-
-## Layer Types
-
-| 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`
-
-## Activation Functions
-
-`relu`, `sigmoid`, `tanh`, `softmax`, `gelu`, `swish`, `mish`, `leaky_relu`, `elu`, `selu`, `linear`
-
-## API Reference
-
-### Initialization
+### 4. Transformer (LLM Context)
 
 ```typescript
-import { init, initBrowser, createNetwork, createNetworkFromJSON } from "@openfluke/welvet";
-
-// Node.js
-await init();
+// Create an MHA layer (Multi-Head Attention)
+const tnet = welvet.createNetwork({
+  layers: [{ z: 0, y: 0, x: 0, l: 0, type: "MHA", d_model: 64, num_heads: 4 }]
+});
 
-// Browser
-await initBrowser();
+// Wrap in Transformer context with pre-loaded weights
+const model = welvet.createTransformer(tnet, embeds, lmHead, finalNorm);
+const logits = model.forwardFull([1, 2, 3, 4]); // Direct token prefill
 ```
 
-### Network Methods
-
-All Network methods follow the WASM calling convention:
-- **Input:** JSON string of an array of parameters
-- **Return:** JSON string of an array of results
+### 5. NEAT Evolution
 
 ```typescript
-// Method with no parameters
-const info = network.GetNetworkInfo(JSON.stringify([]));
+const population = welvet.createNEATPopulation(net, 100);
+const fitnesses = new Array(100).fill(1.0);
 
-// Method with parameters
-const result = network.Train(JSON.stringify([batches, config]));
-
-// Save model
-const saved = network.SaveModelToString(JSON.stringify(["my-model"]));
+population.evolveWithFitnesses(fitnesses);
+console.log("Top Fitness:", population.bestFitness());
 ```
 
-**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
-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}`);
+## Testing & Benchmarks
 
-// Correlation Matrix
-const matrix = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
-const corr = welvet.correlation(matrix);
-console.log(`Pearson: ${corr.pearson}`);
-```
+The package includes a built-in TypeScript testing suite suitable for both CI and environment verification.
 
-### Network Grafting
+### Run tests in Node.js:
 
-Combine multiple trained networks:
-
-```typescript
-const h1 = welvet.createKHandle(config);
-const h2 = welvet.createKHandle(config);
-
-const result = welvet.graft([h1, h2], "concat");
-console.log(`Grafted: ${result.num_branches} branches`);
+```bash
+npm test
 ```
 
-## Examples
-
+Or individual suites:
 ```bash
-cd example
-
-# Grid Scatter Multi-Agent
-bun run grid-scatter.ts
-
-# Stepping Training (LSTM)
-bun run step_train_v3.ts
-
-# Adaptation Benchmark (75 tests)
-bun run test18_adaptation.ts
-
-# Full Test Suite (77 tests)
-bun run universal_test.ts
+npm run test:cabi    # Check WASM exports and functional smoke tests
+npm run test:bench   # Run layer-by-layer performance benchmarks
 ```
 
-## TypeScript Types
+### Integrate tests into Frontend/React:
 
 ```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";
-}
-
-interface TrainingConfig {
-  Epochs: number;
-  LearningRate: number;
-  LossType?: string;
-  Verbose?: boolean;
-  UseGPU?: boolean;
-  GradientClip?: number;
-}
-
-interface TrainingBatch {
-  Input: number[];
-  Target: number[];
-}
+import { runVerify } from "@openfluke/welvet/tests/cabi_verify";
+
+// Run benchmarks or verification logic directly in your app's lifecycle
+await runVerify();
 ```
 
 ## License
 
 Apache-2.0
-
-## Links
-
-- **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)