@openfluke/welvet 0.3.0 → 0.75.0

package/dist/index.js

@@ -1,110 +1,220 @@
 /**
- * @openfluke/welvet - Isomorphic WASM Wrapper
+ * @openfluke/welvet — M-POLY-VTD AI Engine
  *
- * Direct wrapper around Loom WASM that mirrors main.go exports exactly.
- * Provides the same API in both Node.js and browser environments.
+ * Isomorphic TypeScript wrapper for the Loom v0.75.0 WASM module.
+ * Supports Node.js and browser environments.
+ *
+ * @example
+ * ```ts
+ * import { init, createNetwork, DType } from "@openfluke/welvet";
+ *
+ * await init();
+ *
+ * const net = createNetwork({
+ *   layers: [
+ *     { type: "dense", input_height: 4, output_height: 8 },
+ *     { type: "dense", input_height: 8, output_height: 2 },
+ *   ]
+ * });
+ *
+ * const output = net.sequentialForward(new Float32Array([1, 0, 0, 1]));
+ * console.log(output); // Float32Array [...]
+ * ```
  */
+import { DType, LayerType, Activation } from "./types.js";
 import { loadLoomWASMBrowser } from "./loader.browser.js";
+// Re-export all types and constants
 export * from "./types.js";
 export { loadLoomWASMBrowser };
-export async function loadLoomWASM() {
-    const mod = await import("./loader.js");
-    await mod.loadLoomWASM();
-}
+// ──────────────────────────────────────────────────────────────────────────────
+// Initialization
+// ──────────────────────────────────────────────────────────────────────────────
 /**
- * Initialize WASM
- * Auto-detects environment (Browser vs Node.js)
+ * Initialize the welvet WASM module.
+ * Auto-detects Node.js vs browser environment.
+ *
+ * @param wasmUrl Optional custom URL for browser WASM loading (default: /dist/main.wasm)
  */
 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 loadLoomWASMBrowser(wasmUrl);
     }
-    return loadLoomWASM();
+    const mod = await import("./loader.js");
+    return mod.loadLoomWASM();
 }
 /**
- * Initialize WASM for Browser environment
+ * Initialize explicitly for browser environments.
+ * @param wasmUrl Optional custom URL for WASM binary
  */
 export async function initBrowser(wasmUrl) {
-    await loadLoomWASMBrowser(wasmUrl);
+    return loadLoomWASMBrowser(wasmUrl);
 }
+// ──────────────────────────────────────────────────────────────────────────────
+// Network Lifecycle
+// ──────────────────────────────────────────────────────────────────────────────
 /**
- * Create a network from JSON config
- * Wrapper around the global createLoomNetwork function exposed by WASM
+ * Build a VolumetricNetwork from a JSON configuration object or string.
+ *
+ * @example
+ * ```ts
+ * const net = createNetwork({
+ *   layers: [
+ *     { type: "dense", input_height: 784, output_height: 256 },
+ *     { type: "dense", input_height: 256, output_height: 10, activation: "silu" },
+ *   ]
+ * });
+ * ```
  */
 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);
 }
 /**
- * Load a network from JSON string and ID
+ * Build a network from a JSON string.
  */
-export function loadNetwork(jsonString, modelID) {
-    return loadLoomNetwork(jsonString, modelID);
+export function buildNetworkFromJSON(json) {
+    return globalThis["BuildNetworkFromJSON"](json);
 }
+/** Alias for buildNetworkFromJSON to match engine symbol */
+export const BuildNetworkFromJSON = buildNetworkFromJSON;
 /**
- * Create a network handle for grafting
+ * Load a pre-trained network from a SafeTensors file path.
  */
-export function createKHandle(config) {
-    const jsonConfig = typeof config === "string" ? config : JSON.stringify(config);
-    return createNetworkForGraft(jsonConfig);
+export function loadNetwork(path) {
+    return loadLoomNetwork(path);
+}
+// ──────────────────────────────────────────────────────────────────────────────
+// WebGPU
+// ──────────────────────────────────────────────────────────────────────────────
+/**
+ * Initialize WebGPU (browser only).
+ * Sets window.webgpuAdapter, window.webgpuDevice, window.webgpuQueue.
+ */
+export async function setupWebGPU() {
+    // @ts-ignore — setupWebGPU is injected by the WASM module
+    return setupWebGPU();
+}
+// ──────────────────────────────────────────────────────────────────────────────
+// DNA / Introspection
+// ──────────────────────────────────────────────────────────────────────────────
+/**
+ * Compare the architectural DNA of two networks.
+ *
+ * @param dnaA JSON string from network.extractDNA()
+ * @param dnaB JSON string from network.extractDNA()
+ * @returns DNACompareResult
+ */
+export function compareDNA(dnaA, dnaB) {
+    return JSON.parse(compareLoomDNA(dnaA, dnaB));
 }
 /**
- * Graft multiple networks together
+ * Get the default TargetPropConfig.
  */
-export function graft(ids, combineMode) {
-    const idsJSON = JSON.stringify(ids);
-    const resJSON = graftNetworks(idsJSON, combineMode);
-    return JSON.parse(resJSON);
+export function defaultTargetPropConfig() {
+    return JSON.parse(getDefaultTargetPropConfig());
 }
 /**
- * Perform K-Means Clustering
+ * Get the internal parity symbol list from Go.
+ * Used for audits and verification.
  */
-export function kmeans(data, k, iter) {
-    const resJSON = kmeansCluster(JSON.stringify(data), k, iter);
-    return JSON.parse(resJSON);
+export function getInternalParity() {
+    if (typeof getLoomInternalParity === "function") {
+        return getLoomInternalParity();
+    }
+    return [];
+}
+/** Global accessor for extractNetworkBlueprint (engine parity) */
+export function ExtractNetworkBlueprint(network, modelID) {
+    return network.extractNetworkBlueprint(modelID);
 }
+// ──────────────────────────────────────────────────────────────────────────────
+// Training Helpers
+// ──────────────────────────────────────────────────────────────────────────────
 /**
- * Compute Correlation Matrix
+ * Convenience wrapper for network.train() that handles JSON serialization.
+ *
+ * @param network The network to train
+ * @param batches Array of {input, target} training pairs
+ * @param epochs Number of training epochs
+ * @param lr Learning rate
  */
-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 || []
-    };
+export function trainNetwork(network, batches, epochs, lr) {
+    const serialized = batches.map((b) => {
+        const inp = b.input instanceof Float32Array ? b.input : new Float32Array(b.input);
+        const tgt = b.target instanceof Float32Array ? b.target : new Float32Array(b.target);
+        const inShape = b.inputShape ?? [1, inp.length];
+        const tgtShape = b.targetShape ?? [1, tgt.length];
+        return {
+            input: { shape: inShape, data: Array.from(inp) },
+            target: { shape: tgtShape, data: Array.from(tgt) },
+        };
+    });
+    return JSON.parse(network.train(JSON.stringify(serialized), epochs, lr));
+}
+// ──────────────────────────────────────────────────────────────────────────────
+// Evolution / DNA
+// ──────────────────────────────────────────────────────────────────────────────
+/** Get the default SpliceConfig as a plain object. */
+export function getSpliceConfig() {
+    return JSON.parse(globalThis["defaultSpliceConfig"]());
+}
+/** Get the default NEATConfig as a plain object. */
+export function getNEATConfig(dModel) {
+    return JSON.parse(globalThis["defaultNEATConfig"](dModel));
 }
 /**
- * Find Complementary Ensemble Matches
+ * Create a NEAT population from a seed network.
+ * @param network Seed network (its _id is used)
+ * @param size Population size
+ * @param cfg NEATConfig object or JSON string (defaults to getNEATConfig(64))
  */
-export function ensemble(models, minCoverage) {
-    const resJSON = findComplementaryMatches(JSON.stringify(models), minCoverage);
-    return JSON.parse(resJSON);
+export function createNEATPopulation(network, size, cfg) {
+    const cfgJSON = cfg
+        ? (typeof cfg === "string" ? cfg : JSON.stringify(cfg))
+        : globalThis["defaultNEATConfig"](64);
+    return globalThis["createLoomNEATPopulation"](network._id, size, cfgJSON);
 }
 /**
- * Create Adaptation Tracker
+ * Create a Transformer wrapper.
+ * @param network Network to use as the base
+ * @param embeddings Float32Array of embedding weights
+ * @param lmHead Float32Array of LM head weights
+ * @param finalNorm Float32Array of final norm weights
  */
-export function tracker(windowMs, totalMs) {
-    return createAdaptationTracker(windowMs, totalMs);
+export function createTransformer(network, embeddings, lmHead, finalNorm) {
+    return createLoomTransformer(network._id, embeddings, lmHead, finalNorm);
 }
 /**
- * Default export with all functions
+ * Save a network to a SafeTensors byte array.
  */
+export function saveNetwork(network) {
+    // @ts-ignore
+    return network.saveSafetensors();
+}
+// ──────────────────────────────────────────────────────────────────────────────
+// Default export
+// ──────────────────────────────────────────────────────────────────────────────
 export default {
     init,
     initBrowser,
     createNetwork,
+    buildNetworkFromJSON,
     loadNetwork,
-    createKHandle,
-    graft,
-    kmeans,
-    correlation,
-    ensemble,
-    tracker
+    saveNetwork,
+    setupWebGPU,
+    compareDNA,
+    defaultTargetPropConfig,
+    getInternalParity,
+    trainNetwork,
+    getSpliceConfig,
+    getNEATConfig,
+    createNEATPopulation,
+    createTransformer,
+    // Parity aliases
+    BuildNetworkFromJSON,
+    ExtractNetworkBlueprint,
+    // Re-export constants for convenience
+    DType,
+    LayerType,
+    Activation,
 };

package/dist/loader.browser.d.ts

@@ -1,5 +1,5 @@
 /**
- * LOOM WASM Browser Loader
- * Browser-only version without Node.js dependencies
+ * 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/loader.browser.js

@@ -1,11 +1,10 @@
 /**
- * LOOM WASM Browser Loader
- * Browser-only version without Node.js dependencies
+ * welvet WASM Browser Loader
+ * Loads the Go runtime and WASM module in a browser environment.
  */
 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/
+    // 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) => {
@@ -14,12 +13,12 @@ export async function loadLoomWASMBrowser(wasmUrl) {
             document.head.appendChild(script);
         });
     }
-    const response = await fetch(wasmUrl || "/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
+    // @ts-ignore — Go is injected by wasm_exec.js
     const go = new Go();
     const { instance } = await WebAssembly.instantiate(wasmBuffer, go.importObject);
     go.run(instance);
-    // Wait for initialization
+    // Allow Go goroutines to settle
     await new Promise((resolve) => setTimeout(resolve, 100));
 }

package/dist/loader.d.ts

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

package/dist/loader.js

@@ -1,39 +1,26 @@
 /**
- * LOOM WASM Loader
- * Loads and initializes the LOOM WebAssembly module (Node.js only)
+ * welvet WASM Loader — Node.js
+ * Loads and initializes the welvet WebAssembly module.
  */
-// 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
-    let root;
-    if (__dirname.endsWith("dist")) {
-        // Normal production layout
-        root = __dirname;
-    }
-    else {
-        // Running from src/ or example/
-        // Point to project’s dist/ directory
-        root = path.join(__dirname, "..", "dist");
-    }
-    // Load wasm_exec.js
-    const wasmExecPath = path.join(root, "wasm_exec.js");
-    const wasmExecCode = fs.readFileSync(wasmExecPath, "utf-8");
-    // Execute wasm_exec.js to get the Go runtime
+    // 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 main.wasm
-    const wasmPath = path.join(root, "main.wasm");
-    const wasmBuffer = fs.readFileSync(wasmPath);
-    // @ts-ignore - Go runtime from wasm_exec.js
+    // 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);
-    // Wait for WASM runtime to finish bootstrapping
+    // Allow Go goroutines to settle
     await new Promise((resolve) => setTimeout(resolve, 100));
 }

package/dist/src/index.d.ts

@@ -0,0 +1,182 @@
+/**
+ * @openfluke/welvet — M-POLY-VTD AI Engine
+ *
+ * Isomorphic TypeScript wrapper for the Loom v0.73.0 WASM module.
+ * Supports Node.js and browser environments.
+ *
+ * @example
+ * ```ts
+ * import { init, createNetwork, DType } from "@openfluke/welvet";
+ *
+ * await init();
+ *
+ * const net = createNetwork({
+ *   layers: [
+ *     { type: "dense", input_height: 4, output_height: 8 },
+ *     { type: "dense", input_height: 8, output_height: 2 },
+ *   ]
+ * });
+ *
+ * const output = net.sequentialForward(new Float32Array([1, 0, 0, 1]));
+ * console.log(output); // Float32Array [...]
+ * ```
+ */
+import type { Network, NEATPopulation, SystolicState, TargetPropState, TrainingBatch, TrainingResult, DNACompareResult, Transformer } from "./types.js";
+import { loadLoomWASMBrowser } from "./loader.browser.js";
+export * from "./types.js";
+export { loadLoomWASMBrowser };
+/**
+ * Initialize the welvet WASM module.
+ * Auto-detects Node.js vs browser environment.
+ *
+ * @param wasmUrl Optional custom URL for browser WASM loading (default: /dist/main.wasm)
+ */
+export declare function init(wasmUrl?: string): Promise<void>;
+/**
+ * Initialize explicitly for browser environments.
+ * @param wasmUrl Optional custom URL for WASM binary
+ */
+export declare function initBrowser(wasmUrl?: string): Promise<void>;
+/**
+ * Build a VolumetricNetwork from a JSON configuration object or string.
+ *
+ * @example
+ * ```ts
+ * const net = createNetwork({
+ *   layers: [
+ *     { type: "dense", input_height: 784, output_height: 256 },
+ *     { type: "dense", input_height: 256, output_height: 10, activation: "silu" },
+ *   ]
+ * });
+ * ```
+ */
+export declare function createNetwork(config: object | string): Network;
+/**
+ * Load a pre-trained network from a SafeTensors file path.
+ * (Node.js only — requires file system access)
+ *
+ * @param path Absolute or relative path to a .safetensors file
+ */
+export declare function loadNetwork(path: string): Network;
+/**
+ * Initialize WebGPU (browser only).
+ * Sets window.webgpuAdapter, window.webgpuDevice, window.webgpuQueue.
+ */
+export declare function setupWebGPU(): Promise<string>;
+/**
+ * Compare the architectural DNA of two networks.
+ *
+ * @param dnaA JSON string from network.extractDNA()
+ * @param dnaB JSON string from network.extractDNA()
+ * @returns DNACompareResult
+ */
+export declare function compareDNA(dnaA: string, dnaB: string): DNACompareResult;
+/**
+ * Get the default TargetPropConfig.
+ */
+export declare function defaultTargetPropConfig(): object;
+/**
+ * Get the internal parity symbol list from Go.
+ * Used for audits and verification.
+ */
+export declare function getInternalParity(): string[];
+/**
+ * Convenience wrapper for network.train() that handles JSON serialization.
+ *
+ * @param network The network to train
+ * @param batches Array of {input, target} training pairs
+ * @param epochs Number of training epochs
+ * @param lr Learning rate
+ */
+export declare function trainNetwork(network: Network, batches: TrainingBatch[], epochs: number, lr: number): TrainingResult;
+/** Get the default SpliceConfig as a plain object. */
+export declare function getSpliceConfig(): object;
+/** Get the default NEATConfig as a plain object. */
+export declare function getNEATConfig(dModel: number): object;
+/**
+ * Create a NEAT population from a seed network.
+ * @param network Seed network (its _id is used)
+ * @param size Population size
+ * @param cfg NEATConfig object or JSON string (defaults to getNEATConfig(64))
+ */
+export declare function createNEATPopulation(network: Network, size: number, cfg?: object | string): NEATPopulation;
+/**
+ * Create a Transformer wrapper.
+ * @param network Network to use as the base
+ * @param embeddings Float32Array of embedding weights
+ * @param lmHead Float32Array of LM head weights
+ * @param finalNorm Float32Array of final norm weights
+ */
+export declare function createTransformer(network: Network, embeddings: Float32Array | number[], lmHead: Float32Array | number[], finalNorm: Float32Array | number[]): Transformer;
+/**
+ * Save a network to a SafeTensors byte array.
+ */
+export declare function saveNetwork(network: Network): Uint8Array;
+declare const _default: {
+    init: typeof init;
+    initBrowser: typeof initBrowser;
+    createNetwork: typeof createNetwork;
+    loadNetwork: typeof loadNetwork;
+    saveNetwork: typeof saveNetwork;
+    setupWebGPU: typeof setupWebGPU;
+    compareDNA: typeof compareDNA;
+    defaultTargetPropConfig: typeof defaultTargetPropConfig;
+    getInternalParity: typeof getInternalParity;
+    trainNetwork: typeof trainNetwork;
+    getSpliceConfig: typeof getSpliceConfig;
+    getNEATConfig: typeof getNEATConfig;
+    createNEATPopulation: typeof createNEATPopulation;
+    createTransformer: typeof createTransformer;
+    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;
+    };
+    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;
+    };
+    Activation: {
+        readonly RELU: 0;
+        readonly SILU: 1;
+        readonly GELU: 2;
+        readonly TANH: 3;
+        readonly SIGMOID: 4;
+        readonly LINEAR: 5;
+    };
+};
+export default _default;
+export type { Network, NEATPopulation, SystolicState, TargetPropState, TrainingBatch, TrainingResult, DNACompareResult };