@openfluke/welvet 0.3.0 → 0.74.0

package/dist/index.js

@@ -1,110 +1,181 @@
 /**
- * @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.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 { 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
+ * 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 function loadNetwork(jsonString, modelID) {
-    return loadLoomNetwork(jsonString, modelID);
+export function loadNetwork(path) {
+    return loadLoomNetwork(path);
 }
+// ──────────────────────────────────────────────────────────────────────────────
+// WebGPU
+// ──────────────────────────────────────────────────────────────────────────────
 /**
- * Create a network handle for grafting
+ * Initialize WebGPU (browser only).
+ * Sets window.webgpuAdapter, window.webgpuDevice, window.webgpuQueue.
  */
-export function createKHandle(config) {
-    const jsonConfig = typeof config === "string" ? config : JSON.stringify(config);
-    return createNetworkForGraft(jsonConfig);
+export async function setupWebGPU() {
+    // @ts-ignore — setupWebGPU is injected by the WASM module
+    return setupWebGPU();
 }
+// ──────────────────────────────────────────────────────────────────────────────
+// DNA / Introspection
+// ──────────────────────────────────────────────────────────────────────────────
 /**
- * Graft multiple networks together
+ * 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 graft(ids, combineMode) {
-    const idsJSON = JSON.stringify(ids);
-    const resJSON = graftNetworks(idsJSON, combineMode);
-    return JSON.parse(resJSON);
+export function compareDNA(dnaA, dnaB) {
+    return JSON.parse(compareLoomDNA(dnaA, dnaB));
 }
 /**
- * Perform K-Means Clustering
+ * Get the default TargetPropConfig.
  */
-export function kmeans(data, k, iter) {
-    const resJSON = kmeansCluster(JSON.stringify(data), k, iter);
-    return JSON.parse(resJSON);
+export function defaultTargetPropConfig() {
+    return JSON.parse(getDefaultTargetPropConfig());
 }
+// ──────────────────────────────────────────────────────────────────────────────
+// 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));
 }
-/**
- * Find Complementary Ensemble Matches
- */
-export function ensemble(models, minCoverage) {
-    const resJSON = findComplementaryMatches(JSON.stringify(models), minCoverage);
-    return JSON.parse(resJSON);
+// ──────────────────────────────────────────────────────────────────────────────
+// Evolution / DNA
+// ──────────────────────────────────────────────────────────────────────────────
+/** Get the default SpliceConfig as a plain object. */
+export function getSpliceConfig() {
+    return JSON.parse(globalThis["defaultSpliceConfig"]());
 }
-/**
- * Create Adaptation Tracker
- */
-export function tracker(windowMs, totalMs) {
-    return createAdaptationTracker(windowMs, totalMs);
+/** Get the default NEATConfig as a plain object. */
+export function getNEATConfig(dModel) {
+    return JSON.parse(globalThis["defaultNEATConfig"](dModel));
 }
 /**
- * Default export with all functions
+ * 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 createNEATPopulation(network, size, cfg) {
+    const cfgJSON = cfg
+        ? (typeof cfg === "string" ? cfg : JSON.stringify(cfg))
+        : globalThis["defaultNEATConfig"](64);
+    return globalThis["createLoomNEATPopulation"](network._id, size, cfgJSON);
+}
+// ──────────────────────────────────────────────────────────────────────────────
+// Default export
+// ──────────────────────────────────────────────────────────────────────────────
 export default {
     init,
     initBrowser,
     createNetwork,
     loadNetwork,
-    createKHandle,
-    graft,
-    kmeans,
-    correlation,
-    ensemble,
-    tracker
+    setupWebGPU,
+    compareDNA,
+    defaultTargetPropConfig,
+    trainNetwork,
+    getSpliceConfig,
+    getNEATConfig,
+    createNEATPopulation,
+    // Re-export constants for convenience
+    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,
+    },
 };

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,135 @@
+/**
+ * @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 } 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;
+/**
+ * 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;
+declare const _default: {
+    init: typeof init;
+    initBrowser: typeof initBrowser;
+    createNetwork: typeof createNetwork;
+    loadNetwork: typeof loadNetwork;
+    setupWebGPU: typeof setupWebGPU;
+    compareDNA: typeof compareDNA;
+    defaultTargetPropConfig: typeof defaultTargetPropConfig;
+    trainNetwork: typeof trainNetwork;
+    getSpliceConfig: typeof getSpliceConfig;
+    getNEATConfig: typeof getNEATConfig;
+    createNEATPopulation: typeof createNEATPopulation;
+    DType: {
+        FLOAT64: number;
+        FLOAT32: number;
+        FLOAT16: number;
+        BFLOAT16: number;
+        FP8_E4M3: number;
+        FP8_E5M2: number;
+        INT64: number;
+        INT32: number;
+        INT16: number;
+        INT8: number;
+        UINT64: number;
+        UINT32: number;
+        UINT16: number;
+        UINT8: number;
+        INT4: number;
+        UINT4: number;
+        FP4: number;
+        INT2: number;
+        UINT2: number;
+        TERNARY: number;
+        BINARY: number;
+    };
+};
+export default _default;
+export type { Network, NEATPopulation, SystolicState, TargetPropState, TrainingBatch, TrainingResult, DNACompareResult };