@openfluke/welvet 0.2.0 → 0.74.0

package/dist/src/loader.browser.d.ts

@@ -0,0 +1,5 @@
+/**
+ * welvet WASM Browser Loader
+ * Loads the Go runtime and WASM module in a browser environment.
+ */
+export declare function loadLoomWASMBrowser(wasmUrl?: string): Promise<void>;

package/dist/src/loader.browser.js

@@ -0,0 +1,24 @@
+/**
+ * welvet WASM Browser Loader
+ * Loads the Go runtime and WASM module in a browser environment.
+ */
+export async function loadLoomWASMBrowser(wasmUrl) {
+    // Inject wasm_exec.js if the Go runtime is not yet available
+    if (typeof globalThis["Go"] === "undefined") {
+        const script = document.createElement("script");
+        script.src = "/dist/wasm_exec.js";
+        await new Promise((resolve, reject) => {
+            script.onload = () => resolve();
+            script.onerror = () => reject(new Error("Failed to load wasm_exec.js"));
+            document.head.appendChild(script);
+        });
+    }
+    const response = await fetch(wasmUrl ?? "/dist/main.wasm");
+    const wasmBuffer = await response.arrayBuffer();
+    // @ts-ignore — Go is injected by wasm_exec.js
+    const go = new Go();
+    const { instance } = await WebAssembly.instantiate(wasmBuffer, go.importObject);
+    go.run(instance);
+    // Allow Go goroutines to settle
+    await new Promise((resolve) => setTimeout(resolve, 100));
+}

package/dist/src/loader.d.ts

@@ -0,0 +1,5 @@
+/**
+ * welvet WASM Loader — Node.js
+ * Loads and initializes the welvet WebAssembly module.
+ */
+export declare function loadLoomWASM(): Promise<void>;

package/dist/src/loader.js

@@ -0,0 +1,26 @@
+/**
+ * welvet WASM Loader — Node.js
+ * Loads and initializes the welvet WebAssembly module.
+ */
+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);
+    // Resolve root: dist/ in production, or one level up from src/
+    const root = __dirname.endsWith("dist")
+        ? __dirname
+        : path.join(__dirname, "..", "dist");
+    // Bootstrap Go runtime
+    const wasmExecCode = fs.readFileSync(path.join(root, "wasm_exec.js"), "utf-8");
+    eval(wasmExecCode);
+    // Load and instantiate the WASM module
+    const wasmBuffer = fs.readFileSync(path.join(root, "main.wasm"));
+    // @ts-ignore — Go is injected by wasm_exec.js
+    const go = new Go();
+    const { instance } = await WebAssembly.instantiate(wasmBuffer, go.importObject);
+    go.run(instance);
+    // Allow Go goroutines to settle
+    await new Promise((resolve) => setTimeout(resolve, 100));
+}

package/dist/src/types.d.ts

@@ -0,0 +1,299 @@
+/**
+ * welvet — Type Definitions for the M-POLY-VTD AI Engine
+ *
+ * Wraps the Loom v0.73.0 WASM module which supports 21 numerical types,
+ * systolic grid propagation, target propagation, and WebGPU acceleration.
+ */
+export declare const DType: {
+    readonly FLOAT64: 0;
+    readonly FLOAT32: 1;
+    readonly FLOAT16: 2;
+    readonly BFLOAT16: 3;
+    readonly FP8_E4M3: 4;
+    readonly FP8_E5M2: 5;
+    readonly INT64: 6;
+    readonly INT32: 7;
+    readonly INT16: 8;
+    readonly INT8: 9;
+    readonly UINT64: 10;
+    readonly UINT32: 11;
+    readonly UINT16: 12;
+    readonly UINT8: 13;
+    readonly INT4: 14;
+    readonly UINT4: 15;
+    readonly FP4: 16;
+    readonly INT2: 17;
+    readonly UINT2: 18;
+    readonly TERNARY: 19;
+    readonly BINARY: 20;
+};
+export type DTypeValue = typeof DType[keyof typeof DType];
+export declare const LayerType: {
+    readonly DENSE: 0;
+    readonly RMS_NORM: 1;
+    readonly LAYER_NORM: 2;
+    readonly MHA: 3;
+    readonly SOFTMAX: 4;
+    readonly SWIGLU: 5;
+    readonly EMBEDDING: 6;
+    readonly RESIDUAL: 7;
+    readonly KMEANS: 8;
+    readonly RNN: 9;
+    readonly LSTM: 10;
+    readonly CNN1: 11;
+    readonly CNN2: 12;
+    readonly CNN3: 13;
+    readonly CONV_TRANSPOSED_1D: 14;
+    readonly CONV_TRANSPOSED_2D: 15;
+    readonly CONV_TRANSPOSED_3D: 16;
+};
+export type LayerTypeValue = typeof LayerType[keyof typeof LayerType];
+export declare const Activation: {
+    readonly RELU: 0;
+    readonly SILU: 1;
+    readonly GELU: 2;
+    readonly TANH: 3;
+    readonly SIGMOID: 4;
+    readonly LINEAR: 5;
+};
+export type ActivationValue = typeof Activation[keyof typeof Activation];
+export interface LayerSpec {
+    /** Layer type (use LayerType constants) */
+    type: string | number;
+    /** Numerical precision (use DType constants, default: FLOAT32) */
+    dtype?: number;
+    /** Activation function (use Activation constants) */
+    activation?: string | number;
+    input_height?: number;
+    input_width?: number;
+    input_depth?: number;
+    output_height?: number;
+    output_width?: number;
+    output_depth?: number;
+    input_channels?: number;
+    filters?: number;
+    kernel_size?: number;
+    stride?: number;
+    padding?: number;
+    num_heads?: number;
+    num_kv_heads?: number;
+    d_model?: number;
+    seq_length?: number;
+    vocab_size?: number;
+    embedding_dim?: number;
+    z?: number;
+    y?: number;
+    x?: number;
+    l?: number;
+    tile_size?: number;
+}
+export interface NetworkConfig {
+    /** Grid depth (number of z-planes). Default: 1 */
+    depth?: number;
+    /** Grid rows (y-dimension). Default: 1 */
+    rows?: number;
+    /** Grid columns (x-dimension). Default: 1 */
+    cols?: number;
+    /** Layers per cell. Default: number of layers */
+    layers_per_cell?: number;
+    /** Layer definitions (flat list, laid out z→y→x→l) */
+    layers: LayerSpec[];
+}
+export interface TrainingBatch {
+    input: number[] | Float32Array;
+    target: number[] | Float32Array;
+    /** Optional batch shape for input, e.g. [batchSize, features]. Defaults to [1, length]. */
+    inputShape?: number[];
+    /** Optional batch shape for target, e.g. [batchSize, outputs]. Defaults to [1, length]. */
+    targetShape?: number[];
+}
+export interface TrainingResult {
+    final_loss: number;
+    duration_ms: number;
+    epochs_completed: number;
+    loss_history?: number[];
+}
+export interface SystolicState {
+    /**
+     * Inject input into the first layer of the grid.
+     * @param data Float32Array or number[] of input values
+     */
+    setInput(data: Float32Array | number[]): void;
+    /**
+     * Advance the systolic grid by one clock cycle.
+     * @param captureHistory Whether to store history for backpropagation
+     * @returns Duration of the step in milliseconds
+     */
+    step(captureHistory?: boolean): number;
+    /**
+     * Read the output of a layer (default: last active layer).
+     * @param layerIdx Optional layer index (0-based)
+     */
+    getOutput(layerIdx?: number): Float32Array;
+    /**
+     * Backpropagate gradients through the stored history.
+     * @param gradients Output gradient (Float32Array or number[])
+     * @returns Input gradient as Float32Array
+     */
+    backward(gradients: Float32Array | number[]): Float32Array;
+    /**
+     * Apply target propagation (gradient-free alternative to backward).
+     * @param target Global target tensor
+     * @param lr Learning rate
+     */
+    applyTargetProp(target: Float32Array | number[], lr: number): void;
+    /** Total number of systolic steps executed. */
+    stepCount(): number;
+    /** Release resources (no-op in WASM, included for API parity). */
+    free(): void;
+}
+export interface TargetPropState {
+    /**
+     * Forward pass through all layers, storing local targets.
+     * @param input Input data
+     * @returns Output as Float32Array
+     */
+    forward(input: Float32Array | number[]): Float32Array;
+    /**
+     * Backward pass using target propagation (gap-based, no chain rule).
+     * @param target Desired output
+     */
+    backward(target: Float32Array | number[]): void;
+    /**
+     * Backward pass using the chain rule (standard backprop via TP state).
+     * @param target Desired output
+     */
+    backwardChainRule(target: Float32Array | number[]): void;
+    /**
+     * Apply accumulated gap gradients to all layer weights.
+     * @param lr Learning rate
+     */
+    applyGaps(lr?: number): void;
+    /** Release resources (no-op in WASM). */
+    free(): void;
+}
+export interface NEATPopulation {
+    /** Internal handle ID. */
+    _id: number;
+    /** Number of networks in the population. */
+    size: number;
+    /** Get a network wrapper by index. */
+    getNetwork(index: number): Network;
+    /** Run one generation given pre-computed fitnesses (length must equal size). */
+    evolveWithFitnesses(fitnesses: number[]): void;
+    /** Return the best-performing network wrapper. */
+    best(): Network;
+    /** Return the best fitness score. */
+    bestFitness(): number;
+    /** Human-readable generation summary. */
+    summary(generation: number): string;
+    /** Release resources. */
+    free(): void;
+}
+export interface Network {
+    /**
+     * Full sequential forward pass through the network.
+     * @param input Float32Array or number[] of inputs
+     * @returns Output as Float32Array
+     */
+    sequentialForward(input: Float32Array | number[]): Float32Array;
+    /**
+     * Returns a JSON string with network shape info.
+     * {depth, rows, cols, layers_per_cell, total_layers, use_gpu, default_dtype}
+     */
+    getInfo(): string;
+    /**
+     * Extract the network's DNA fingerprint as a JSON string.
+     * Use compareLoomDNA() to compare two fingerprints.
+     */
+    extractDNA(): string;
+    /**
+     * Extract the network's full blueprint as a JSON string.
+     * @param modelID Optional model identifier
+     */
+    extractBlueprint(modelID?: string): string;
+    /** Total number of layers in the network. */
+    getLayerCount(): number;
+    /**
+     * Get the specification of a single layer.
+     * @param layerIdx 0-based layer index
+     * @returns JSON string with layer spec
+     */
+    getLayerSpec(layerIdx: number): string;
+    /**
+     * Switch a layer's numerical type at runtime (zero-cost when cached).
+     * @param layerIdx 0-based layer index
+     * @param dtype DType constant
+     * @returns JSON status/error
+     */
+    morphLayer(layerIdx: number, dtype: DTypeValue): string;
+    /**
+     * Initialize WebGPU for this network.
+     * @returns Promise that resolves with status JSON
+     */
+    initGPU(): Promise<string>;
+    /**
+     * Upload all layer weights to GPU buffers.
+     * @returns Promise that resolves with status JSON
+     */
+    syncToGPU(): Promise<string>;
+    /** Download weights back to CPU and disable GPU mode. */
+    syncToCPU(): void;
+    /**
+     * High-level supervised training loop.
+     * @param batchesJSON JSON string of TrainingBatch[]
+     * @param epochs Number of epochs
+     * @param lr Learning rate
+     * @returns JSON string with TrainingResult
+     */
+    train(batchesJSON: string, epochs: number, lr: number): string;
+    /**
+     * Create a SystolicState for the stepping API.
+     */
+    createSystolicState(): SystolicState;
+    /**
+     * Create a TargetPropState for gradient-free learning.
+     * @param useChainRule If true, uses chain-rule backprop instead of gap-based TP
+     */
+    createTargetPropState(useChainRule?: boolean): TargetPropState;
+    /**
+     * Genetic crossover with another network.
+     * @param otherID The `_id` of the other parent network
+     * @param cfgJSON JSON string from defaultSpliceConfig()
+     */
+    spliceDNA(otherID: number, cfgJSON: string): Network;
+    /**
+     * NEAT-style structural mutation.
+     * @param cfgJSON JSON string from defaultNEATConfig()
+     */
+    neatMutate(cfgJSON: string): Network;
+    /** Internal handle ID — required for spliceDNA and population operations. */
+    _id: number;
+    /** Release resources (no-op in WASM, included for API parity). */
+    free(): void;
+}
+export interface DNACompareResult {
+    similarity: number;
+    layer_count_match: boolean;
+    depth_match: boolean;
+    architecture_match: boolean;
+    [key: string]: unknown;
+}
+declare global {
+    /** Build a VolumetricNetwork from a JSON config string. */
+    function createLoomNetwork(jsonConfig: string): Network;
+    /** Load a network from a SafeTensors file path. */
+    function loadLoomNetwork(path: string): Network;
+    /** Initialize WebGPU (returns a Promise). */
+    function setupWebGPU(): Promise<string>;
+    /** Compare two DNA JSON strings for architectural similarity. */
+    function compareLoomDNA(dnaA: string, dnaB: string): string;
+    /** Get the default TargetPropConfig. */
+    function getDefaultTargetPropConfig(): string;
+    /** Get the default SpliceConfig JSON string. */
+    function defaultSpliceConfig(): string;
+    /** Get the default NEATConfig JSON string for a given model dimension. */
+    function defaultNEATConfig(dModel: number): string;
+    /** Create a NEAT population from a seed network. */
+    function createLoomNEATPopulation(seedID: number, size: number, cfgJSON: string): NEATPopulation;
+}

package/dist/src/types.js

@@ -0,0 +1,65 @@
+/**
+ * welvet — Type Definitions for the M-POLY-VTD AI Engine
+ *
+ * Wraps the Loom v0.73.0 WASM module which supports 21 numerical types,
+ * systolic grid propagation, target propagation, and WebGPU acceleration.
+ */
+// ──────────────────────────────────────────────────────────────────────────────
+// Numerical Type Constants (matches poly.DType)
+// ──────────────────────────────────────────────────────────────────────────────
+export const DType = {
+    FLOAT64: 0,
+    FLOAT32: 1,
+    FLOAT16: 2,
+    BFLOAT16: 3,
+    FP8_E4M3: 4,
+    FP8_E5M2: 5,
+    INT64: 6,
+    INT32: 7,
+    INT16: 8,
+    INT8: 9,
+    UINT64: 10,
+    UINT32: 11,
+    UINT16: 12,
+    UINT8: 13,
+    INT4: 14,
+    UINT4: 15,
+    FP4: 16,
+    INT2: 17,
+    UINT2: 18,
+    TERNARY: 19,
+    BINARY: 20,
+};
+// ──────────────────────────────────────────────────────────────────────────────
+// Layer Type Constants (matches poly.LayerType)
+// ──────────────────────────────────────────────────────────────────────────────
+export const LayerType = {
+    DENSE: 0,
+    RMS_NORM: 1,
+    LAYER_NORM: 2,
+    MHA: 3,
+    SOFTMAX: 4,
+    SWIGLU: 5,
+    EMBEDDING: 6,
+    RESIDUAL: 7,
+    KMEANS: 8,
+    RNN: 9,
+    LSTM: 10,
+    CNN1: 11,
+    CNN2: 12,
+    CNN3: 13,
+    CONV_TRANSPOSED_1D: 14,
+    CONV_TRANSPOSED_2D: 15,
+    CONV_TRANSPOSED_3D: 16,
+};
+// ──────────────────────────────────────────────────────────────────────────────
+// Activation Type Constants (matches poly.ActivationType)
+// ──────────────────────────────────────────────────────────────────────────────
+export const Activation = {
+    RELU: 0,
+    SILU: 1,
+    GELU: 2,
+    TANH: 3,
+    SIGMOID: 4,
+    LINEAR: 5,
+};

package/dist/tests/benchmark.d.ts

@@ -0,0 +1,5 @@
+/**
+ * benchmark.ts
+ * TypeScript port of benchmark_training.html
+ */
+export declare function runBenchmark(): Promise<void>;

package/dist/tests/benchmark.js

@@ -0,0 +1,139 @@
+/**
+ * benchmark.ts
+ * TypeScript port of benchmark_training.html
+ */
+const TRAINING_CASES = [
+    {
+        name: 'Dense (Linear)', iters: 5, inDim: 512, outDim: 512,
+        cfg: JSON.stringify({ depth: 1, rows: 1, cols: 1, layers_per_cell: 1, layers: [
+                { z: 0, y: 0, x: 0, l: 0, type: "Dense", input_height: 512, output_height: 512, activation: "Linear", dtype: "F32" }
+            ] })
+    },
+    {
+        name: 'RMSNorm', iters: 5, inDim: 512, outDim: 512,
+        cfg: JSON.stringify({ depth: 1, rows: 1, cols: 1, layers_per_cell: 1, layers: [
+                { z: 0, y: 0, x: 0, l: 0, type: "RMSNorm", input_height: 512, output_height: 512, dtype: "F32" }
+            ] })
+    },
+    {
+        name: 'SwiGLU (MLP)', iters: 5, inDim: 512, outDim: 1024,
+        cfg: JSON.stringify({ depth: 1, rows: 1, cols: 1, layers_per_cell: 1, layers: [
+                { z: 0, y: 0, x: 0, l: 0, type: "SwiGLU", input_height: 512, output_height: 1024, dtype: "F32" }
+            ] })
+    },
+    {
+        name: 'Embedding', iters: 5, inDim: 16, outDim: 2048, isEmbedding: true,
+        cfg: JSON.stringify({ depth: 1, rows: 1, cols: 1, layers_per_cell: 1, layers: [
+                { z: 0, y: 0, x: 0, l: 0, type: "Embedding", vocab_size: 1024, embedding_dim: 128, dtype: "F32" }
+            ] })
+    },
+    {
+        name: 'Residual Add', iters: 5, inDim: 512, outDim: 512,
+        cfg: JSON.stringify({ depth: 1, rows: 1, cols: 1, layers_per_cell: 1, layers: [
+                { z: 0, y: 0, x: 0, l: 0, type: "Residual", input_height: 512, output_height: 512, dtype: "F32" }
+            ] })
+    },
+    {
+        name: 'MHA (Fused)', iters: 5, inDim: 128, outDim: 128,
+        cfg: JSON.stringify({ depth: 1, rows: 1, cols: 1, layers_per_cell: 1, layers: [
+                { z: 0, y: 0, x: 0, l: 0, type: "MHA", input_height: 128, output_height: 128, num_heads: 4, d_model: 128, dtype: "F32" }
+            ] })
+    }
+];
+function makeTrainBatches(inDim, outDim, nBatches, batchSize, isEmbedding) {
+    const batches = [];
+    for (let b = 0; b < nBatches; b++) {
+        const inp = new Float32Array(batchSize * inDim);
+        const tgt = new Float32Array(batchSize * outDim);
+        if (isEmbedding) {
+            for (let i = 0; i < inp.length; i++)
+                inp[i] = i % 1024;
+        }
+        else {
+            for (let i = 0; i < inp.length; i++)
+                inp[i] = (Math.random() * 2 - 1) * 0.5;
+        }
+        for (let i = 0; i < tgt.length; i++)
+            tgt[i] = Math.random() * 0.1;
+        batches.push({
+            input: { shape: [batchSize, inDim], data: Array.from(inp) },
+            target: { shape: [batchSize, outDim], data: Array.from(tgt) }
+        });
+    }
+    return batches;
+}
+async function runCase(tc) {
+    // @ts-ignore
+    const net = globalThis.createLoomNetwork(tc.cfg);
+    const batchSize = 4;
+    const nBatches = 4;
+    const epochs = 3;
+    const batches = makeTrainBatches(tc.inDim, tc.outDim, nBatches, batchSize, tc.isEmbedding);
+    const batchesJSON = JSON.stringify(batches);
+    const input = new Float32Array(tc.inDim);
+    input.fill(0.5);
+    if (tc.isEmbedding)
+        for (let i = 0; i < input.length; i++)
+            input[i] = i % 1024;
+    // warm-up
+    net.sequentialForward(input);
+    const t0 = performance.now();
+    let lastOut;
+    for (let i = 0; i < tc.iters; i++) {
+        lastOut = net.sequentialForward(input);
+    }
+    const fwdMs = (performance.now() - t0) / tc.iters;
+    let trainMs = -1;
+    let initialLoss = null, finalLoss = null;
+    try {
+        const t1 = performance.now();
+        const trainResult = await net.train(batchesJSON, epochs, 0.001);
+        trainMs = performance.now() - t1;
+        if (typeof trainResult === 'string') {
+            try {
+                const r = JSON.parse(trainResult);
+                if (r.loss_history && r.loss_history.length > 0) {
+                    initialLoss = r.loss_history[0];
+                    finalLoss = r.loss_history[r.loss_history.length - 1];
+                }
+            }
+            catch (e) { }
+        }
+    }
+    catch (e) {
+        trainMs = -1;
+    }
+    const sample = lastOut ? [lastOut[0] || 0, lastOut[1] || 0, lastOut[2] || 0] : null;
+    const sanity = sample && sample.some((v) => Math.abs(v) > 1e-9);
+    net.free();
+    return { fwdMs, trainMs, sample, sanity, initialLoss, finalLoss };
+}
+export async function runBenchmark() {
+    console.log("=== M-POLY-VTD Training Showdown Benchmark ===");
+    // Decide which loader to use
+    if (typeof process !== "undefined" && process.versions && process.versions.node) {
+        const { loadLoomWASM } = await import("../src/loader.js");
+        await loadLoomWASM();
+    }
+    else {
+        // @ts-ignore
+        const { loadLoomWASMBrowser } = await import("../src/loader.browser.js");
+        await loadLoomWASMBrowser();
+    }
+    console.log("Layer".padEnd(15) + " | " + "Fwd ms/it".padEnd(11) + " | " + "Train ms".padEnd(10) +
+        " | " + "Init Loss".padEnd(11) + " | " + "Final Loss".padEnd(11) + " | Sanity");
+    console.log("-".repeat(85));
+    for (const tc of TRAINING_CASES) {
+        const res = await runCase(tc);
+        const fwdStr = res.fwdMs >= 0 ? res.fwdMs.toFixed(3).padEnd(10) : 'N/A'.padEnd(10);
+        const trainStr = res.trainMs >= 0 ? res.trainMs.toFixed(1).padEnd(9) : 'N/A'.padEnd(9);
+        const iLoss = res.initialLoss != null ? res.initialLoss.toFixed(4).padEnd(10) : 'N/A'.padEnd(10);
+        const fLoss = res.finalLoss != null ? res.finalLoss.toFixed(4).padEnd(10) : 'N/A'.padEnd(10);
+        const sanStr = res.sanity ? 'REAL' : 'ZERO';
+        console.log(`${tc.name.padEnd(15)} | ${fwdStr} | ${trainStr} | ${iLoss} | ${fLoss} | ${sanStr}`);
+    }
+}
+// Auto-run if executed directly via Node.js/tsx
+if (typeof process !== "undefined" && import.meta.url.includes(process.argv[1].replace(/\\/g, '/'))) {
+    runBenchmark();
+}