@openfluke/welvet 0.2.0 → 0.74.0

package/dist/types.d.ts

@@ -1,200 +1,299 @@
 /**
- * Type definitions for LOOM WASM API
+ * 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 interface LayerConfig {
-    type: string;
-    input_size?: number;
-    output_size?: number;
-    hidden_size?: number;
-    activation?: string;
-    combine_mode?: string;
-    grid_output_rows?: number;
-    grid_output_cols?: number;
-    grid_output_layers?: number;
-    grid_positions?: GridPosition[];
+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;
-    output_height?: number;
     input_width?: number;
+    input_depth?: number;
+    output_height?: number;
+    output_width?: number;
+    output_depth?: number;
     input_channels?: number;
-    output_channels?: number;
+    filters?: number;
     kernel_size?: number;
     stride?: number;
     padding?: number;
-    filters?: number;
-    d_model?: number;
     num_heads?: number;
+    num_kv_heads?: number;
+    d_model?: number;
     seq_length?: number;
-    norm_size?: number;
     vocab_size?: number;
     embedding_dim?: number;
-    epsilon?: number;
-    softmax_variant?: string;
-    temperature?: number;
-    residual?: boolean;
-    filter_gate?: LayerConfig;
-    filter_temperature?: number;
-    branches?: LayerConfig[];
+    z?: number;
+    y?: number;
+    x?: number;
+    l?: number;
+    tile_size?: number;
 }
 export interface NetworkConfig {
-    batch_size: number;
-    grid_rows?: number;
-    grid_cols?: number;
+    /** 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;
-    layers: LayerConfig[];
-}
-export interface GridPosition {
-    branch_index: number;
-    target_row: number;
-    target_col: number;
-    target_layer: number;
+    /** Layer definitions (flat list, laid out z→y→x→l) */
+    layers: LayerSpec[];
 }
 export interface TrainingBatch {
-    Input: number[];
-    Target: number[];
-}
-export interface TrainingConfig {
-    Epochs: number;
-    LearningRate: number;
-    LossType?: string;
-    Verbose?: boolean;
-    UseGPU?: boolean;
-    PrintEveryBatch?: number;
-    GradientClip?: number;
+    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[];
 }
-/**
- * Network interface with all available methods
- * All methods take a JSON string of parameters (JSON array)
- * and return a JSON string of results (JSON array)
- */
-export interface Network {
-    ForwardCPU(inputsJSON: string): string;
-    ForwardGPU(inputsJSON: string): string;
-    BackwardCPU(gradientsJSON: string): string;
-    BackwardGPU(gradientsJSON: string): string;
-    UpdateWeights(paramsJSON: string): string;
-    Train(paramsJSON: string): string;
-    ZeroGradients(paramsJSON: string): string;
-    ResetGradients(paramsJSON: string): string;
-    SaveModelToString(paramsJSON: string): string;
-    SerializeModel(paramsJSON: string): string;
-    GetWeights(paramsJSON: string): string;
-    SetWeights(paramsJSON: string): string;
-    GetBiases(paramsJSON: string): string;
-    SetBiases(paramsJSON: string): string;
-    GetLayer(paramsJSON: string): string;
-    SetLayer(paramsJSON: string): string;
-    GetActivation(paramsJSON: string): string;
-    SetActivation(paramsJSON: string): string;
-    GetLayerType(paramsJSON: string): string;
-    GetLayerSizes(paramsJSON: string): string;
-    GetBatchSize(paramsJSON: string): string;
-    SetBatchSize(paramsJSON: string): string;
-    GetGridDimensions(paramsJSON: string): string;
-    GetLayersPerCell(paramsJSON: string): string;
-    TotalLayers(paramsJSON: string): string;
-    GetNetworkInfo(paramsJSON: string): string;
-    GetTotalParameters(paramsJSON: string): string;
-    GetMemoryUsage(paramsJSON: string): string;
-    ValidateArchitecture(paramsJSON: string): string;
-    GetLastOutput(paramsJSON: string): string;
-    GetLastGradients(paramsJSON: string): string;
-    Activations(paramsJSON: string): string;
-    KernelGradients(paramsJSON: string): string;
-    BiasGradients(paramsJSON: string): string;
-    Clone(paramsJSON: string): string;
-    InitializeWeights(paramsJSON: string): string;
-    InitGPU(paramsJSON: string): string;
-    ReleaseGPU(paramsJSON: string): string;
-    GetMethods(paramsJSON: string): string;
-    GetMethodsJSON(paramsJSON: string): string;
-    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 {
+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;
-    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
- * Only createLoomNetwork is exposed - use network.SaveModelToString() for saving
- */
-declare global {
-    function createLoomNetwork(jsonConfig: string): Network;
-    function createAdaptationTracker(windowMs: number, totalMs: number): AdaptationTracker;
-    function createNetworkForGraft(jsonConfig: string): number;
-    function graftNetworks(idsJSON: string, combineMode: string): string;
-    function kmeansCluster(dataJSON: string, k: number, iter: number): string;
-    function computeCorrelation(matrixAJSON: string, matrixBJSON: string): string;
-    function findComplementaryMatches(modelsJSON: string, minCoverage: number): string;
+    /**
+     * 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 EnsembleMatch {
-    ModelA: string;
-    ModelB: string;
-    Coverage: number;
-    Overlap: number;
-    WeightedAcc?: number;
+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 GraftResult {
-    success: boolean;
-    type: string;
-    num_branches: number;
-    combine_mode: string;
-    error?: string;
+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 KMeansResult {
-    centroids: number[][];
-    assignment: number[];
-    silhouette_score: number;
+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 CorrelationResult {
-    pearson: number[][];
-    spearman: number[][];
+export interface DNACompareResult {
+    similarity: number;
+    layer_count_match: boolean;
+    depth_match: boolean;
+    architecture_match: boolean;
+    [key: string]: unknown;
 }
-/**
- * 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;
+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/types.js

@@ -1,4 +1,65 @@
 /**
- * Type definitions for LOOM WASM API
+ * 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 {};
+// ──────────────────────────────────────────────────────────────────────────────
+// 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,
+};