@openfluke/welvet 0.1.5 → 0.1.7

package/README.md

@@ -151,53 +151,106 @@ const [output2] = loadedNetwork.ForwardCPU(
 - ✅ Same behavior as Python, C#, C, and WASM
 
 See `example/grid-scatter.ts` for a complete working example.
-{
-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",
-},
-],
-});
-
-// Train multi-agent network
-const batches: TrainingBatch[] = [
-{ 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 config: TrainingConfig = {
-Epochs: 800,
-LearningRate: 0.15,
-LossType: "mse",
-Verbose: false,
-};
+### ⚡ Stepping API - Fine-Grained Execution Control
 
-const result = agentNetwork.Train(JSON.stringify([batches, config]));
+**NEW:** 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);
+
+// 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();
+  
+  // Calculate gradients
+  const gradients = new Float32Array(output.length);
+  for (let i = 0; i < output.length; i++)
+    gradients[i] = output[i] - target[i];
+  
+  // Backward pass
+  state.stepBackward(gradients);
+  
+  // Update weights immediately
+  network.ApplyGradients(JSON.stringify([learningRate]));
+}
+```
+
+**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:
+
+```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 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);
+}
+```
+
+**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
+
+**NEW:** Run the full Test 18 Multi-Architecture Adaptation Benchmark:
+
+```bash
+cd example
+bun run test18_adaptation.ts
+```
+
+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).
+
+See `example/test18_adaptation.ts` for the full implementation.
+
+```
 
 ## API Reference
 
@@ -323,9 +376,9 @@ interface TrainingConfig {
 }
 ```
 
-## Example
+## Examples
 
-See `example/grid-scatter.ts` for a complete multi-agent training demo:
+### Grid Scatter Multi-Agent
 
 ```bash
 cd example
@@ -333,20 +386,20 @@ bun install
 bun run grid-scatter.ts
 ```
 
-Expected output:
+### Stepping Training (LSTM)
 
+```bash
+bun run step_train_v3.ts
 ```
-🤖 Running Grid Scatter Multi-Agent Training...
-✅ Agent network created!
-Training for 800 epochs with learning rate 0.150
-✅ Training complete!
-Training time: 0.47 seconds
-Initial Loss: 0.252249
-Final Loss: 0.001374
-Improvement: 99.46%
-Total Epochs: 800
+
+### Adaptation Benchmark (75 tests)
+
+```bash
+bun run test18_adaptation.ts
 ```
 
+> **Note:** Full benchmark takes ~12.5 minutes (10 seconds per test)
+
 ## Layer Types
 
 - `dense` - Fully connected layer
@@ -366,7 +419,7 @@ Total Epochs: 800
 
 ## License
 
-MIT
+APACHE2
 
 ## Links
 

package/dist/index.browser.js

@@ -24,7 +24,9 @@ export async function init() {
  * Wrapper around the global createLoomNetwork function exposed by WASM
  */
 export function createNetwork(config) {
-    const jsonConfig = typeof config === 'string' ? config : JSON.stringify(config);
+    const jsonConfig = typeof config === "string"
+        ? config
+        : JSON.stringify(config);
     return createLoomNetwork(jsonConfig);
 }
 /**

package/dist/index.js

@@ -25,7 +25,9 @@ export async function initBrowser() {
  * Wrapper around the global createLoomNetwork function exposed by WASM
  */
 export function createNetwork(config) {
-    const jsonConfig = typeof config === 'string' ? config : JSON.stringify(config);
+    const jsonConfig = typeof config === "string"
+        ? config
+        : JSON.stringify(config);
     return createLoomNetwork(jsonConfig);
 }
 /**

package/dist/loader.js

@@ -8,19 +8,31 @@ import { dirname, join } from "path";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 export async function loadLoomWASM() {
+    // __dirname points to:
+    // - dist/   → in production
+    // - src/    → when running via Bun, ts-node, or example files
+    let root;
+    if (__dirname.endsWith("dist")) {
+        // Normal production layout
+        root = __dirname;
+    }
+    else {
+        // Running from src/ or example/
+        // Point to project’s dist/ directory
+        root = join(__dirname, "..", "dist");
+    }
     // Load wasm_exec.js
-    const wasmExecPath = join(__dirname, "../assets/wasm_exec.js");
+    const wasmExecPath = join(root, "wasm_exec.js");
     const wasmExecCode = readFileSync(wasmExecPath, "utf-8");
     // Execute wasm_exec.js to get the Go runtime
     eval(wasmExecCode);
     // Load main.wasm
-    const wasmPath = join(__dirname, "../assets/main.wasm");
+    const wasmPath = join(root, "main.wasm");
     const wasmBuffer = readFileSync(wasmPath);
-    // @ts-ignore - Go is defined by wasm_exec.js
+    // @ts-ignore - Go runtime from wasm_exec.js
     const go = new Go();
     const { instance } = await WebAssembly.instantiate(wasmBuffer, go.importObject);
-    // Run the Go WASM module
     go.run(instance);
-    // Wait a bit for initialization
+    // Wait for WASM runtime to finish bootstrapping
     await new Promise((resolve) => setTimeout(resolve, 100));
 }

package/dist/types.d.ts

@@ -95,6 +95,41 @@ export interface Network {
     ListMethods(paramsJSON: string): string;
     HasMethod(paramsJSON: string): string;
     GetMethodSignature(paramsJSON: string): string;
+    ApplyGradients(paramsJSON: string): string;
+    ApplyGradientsAdamW(paramsJSON: string): string;
+    ApplyGradientsRMSprop(paramsJSON: string): string;
+    ApplyGradientsSGDMomentum(paramsJSON: string): string;
+    createStepState(inputSize: number): StepState;
+    createTweenState(useChainRule?: boolean): TweenState;
+}
+/**
+ * StepState interface for stepping execution
+ */
+export interface StepState {
+    setInput(data: Float32Array | number[]): void;
+    stepForward(): number;
+    getOutput(): Float32Array;
+    stepBackward(gradients: Float32Array | number[]): Float32Array;
+}
+/**
+ * TweenState interface for neural tweening execution
+ */
+export interface TweenState {
+    /**
+     * Perform a tween training step
+     * @param input - Input data
+     * @param targetClass - Target class index
+     * @param outputSize - Size of output layer
+     * @param learningRate - Learning rate for this step
+     * @returns Loss value
+     */
+    TweenStep(input: Float32Array | number[], targetClass: number, outputSize: number, learningRate: number): number;
+    /** Enable/disable chain rule mode */
+    setChainRule(enabled: boolean): void;
+    /** Get current chain rule setting */
+    getChainRule(): boolean;
+    /** Get number of tween steps performed */
+    getTweenSteps(): number;
 }
 /**
  * Global WASM functions exposed by main.go
@@ -102,4 +137,16 @@ export interface Network {
  */
 declare global {
     function createLoomNetwork(jsonConfig: string): Network;
+    function createAdaptationTracker(windowMs: number, totalMs: number): AdaptationTracker;
+}
+/**
+ * AdaptationTracker interface for tracking accuracy during task changes
+ */
+export interface AdaptationTracker {
+    setModelInfo(modelName: string, modeName: string): void;
+    scheduleTaskChange(atOffsetMs: number, taskID: number, taskName: string): void;
+    start(initialTask: string, initialTaskID: number): void;
+    recordOutput(isCorrect: boolean): void;
+    getCurrentTask(): number;
+    finalize(): string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfluke/welvet",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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",
@@ -58,4 +58,4 @@
     "@types/node": "^22.7.5",
     "typescript": "^5.6.3"
   }
-}
+}