@ruvector/cnn 0.1.0

package/index.js

@@ -0,0 +1,266 @@
+/**
+ * @ruvector/cnn - CNN feature extraction for image embeddings
+ *
+ * SIMD-optimized image embedding extraction using contrastive learning.
+ *
+ * @example
+ * ```javascript
+ * const { CnnEmbedder, InfoNCELoss, SimdOps } = require('@ruvector/cnn');
+ *
+ * // Create embedder
+ * const embedder = new CnnEmbedder({ embeddingDim: 512, normalize: true });
+ *
+ * // Extract embedding from image data
+ * const imageData = new Uint8Array(224 * 224 * 3); // RGB image
+ * const embedding = embedder.extract(imageData, 224, 224);
+ *
+ * // Compute similarity
+ * const sim = embedder.cosineSimilarity(embedding1, embedding2);
+ * ```
+ */
+
+'use strict';
+
+let wasm = null;
+let initialized = false;
+
+/**
+ * Initialize the WASM module
+ * @returns {Promise<void>}
+ */
+async function init() {
+  if (initialized) return;
+
+  if (typeof window !== 'undefined') {
+    // Browser environment
+    const wasmModule = await import('./ruvector_cnn_wasm.js');
+    await wasmModule.default();
+    wasm = wasmModule;
+  } else {
+    // Node.js environment
+    const fs = require('fs');
+    const path = require('path');
+    const wasmPath = path.join(__dirname, 'ruvector_cnn_wasm_bg.wasm');
+
+    if (fs.existsSync(wasmPath)) {
+      const wasmModule = require('./ruvector_cnn_wasm.js');
+      const wasmBuffer = fs.readFileSync(wasmPath);
+      await wasmModule.default(wasmBuffer);
+      wasm = wasmModule;
+    } else {
+      throw new Error('WASM file not found. Run `npm run build` first.');
+    }
+  }
+
+  initialized = true;
+}
+
+/**
+ * CNN Embedder for extracting image features
+ */
+class CnnEmbedder {
+  /**
+   * Create a new CNN embedder
+   * @param {Object} [config] - Configuration options
+   * @param {number} [config.inputSize=224] - Input image size (square)
+   * @param {number} [config.embeddingDim=512] - Output embedding dimension
+   * @param {boolean} [config.normalize=true] - L2 normalize embeddings
+   */
+  constructor(config = {}) {
+    if (!initialized) {
+      throw new Error('Module not initialized. Call init() first.');
+    }
+
+    const wasmConfig = new wasm.EmbedderConfig();
+    wasmConfig.input_size = config.inputSize || 224;
+    wasmConfig.embedding_dim = config.embeddingDim || 512;
+    wasmConfig.normalize = config.normalize !== false;
+
+    this._inner = new wasm.WasmCnnEmbedder(wasmConfig);
+    this._embeddingDim = wasmConfig.embedding_dim;
+  }
+
+  /**
+   * Extract embedding from image data
+   * @param {Uint8Array} imageData - RGB image data (row-major, no alpha)
+   * @param {number} width - Image width
+   * @param {number} height - Image height
+   * @returns {Float32Array} - Embedding vector
+   */
+  extract(imageData, width, height) {
+    const result = this._inner.extract(imageData, width, height);
+    return new Float32Array(result);
+  }
+
+  /**
+   * Compute cosine similarity between two embeddings
+   * @param {Float32Array} a - First embedding
+   * @param {Float32Array} b - Second embedding
+   * @returns {number} - Similarity in [-1, 1]
+   */
+  cosineSimilarity(a, b) {
+    return this._inner.cosine_similarity(a, b);
+  }
+
+  /**
+   * Get the embedding dimension
+   * @returns {number}
+   */
+  get embeddingDim() {
+    return this._embeddingDim;
+  }
+}
+
+/**
+ * InfoNCE loss for contrastive learning (SimCLR style)
+ */
+class InfoNCELoss {
+  /**
+   * Create InfoNCE loss
+   * @param {number} [temperature=0.1] - Temperature parameter
+   */
+  constructor(temperature = 0.1) {
+    if (!initialized) {
+      throw new Error('Module not initialized. Call init() first.');
+    }
+    this._inner = new wasm.WasmInfoNCELoss(temperature);
+  }
+
+  /**
+   * Compute loss for embedding pairs
+   * @param {Float32Array} embeddings - Flattened [2N, D] array
+   * @param {number} batchSize - N (number of pairs)
+   * @param {number} dim - D (embedding dimension)
+   * @returns {number} - Loss value
+   */
+  forward(embeddings, batchSize, dim) {
+    return this._inner.forward(embeddings, batchSize, dim);
+  }
+
+  /**
+   * Get temperature parameter
+   * @returns {number}
+   */
+  get temperature() {
+    return this._inner.temperature;
+  }
+}
+
+/**
+ * Triplet loss for metric learning
+ */
+class TripletLoss {
+  /**
+   * Create triplet loss
+   * @param {number} [margin=1.0] - Margin parameter
+   */
+  constructor(margin = 1.0) {
+    if (!initialized) {
+      throw new Error('Module not initialized. Call init() first.');
+    }
+    this._inner = new wasm.WasmTripletLoss(margin);
+  }
+
+  /**
+   * Compute triplet loss
+   * @param {Float32Array} anchors - Anchor embeddings [N, D]
+   * @param {Float32Array} positives - Positive embeddings [N, D]
+   * @param {Float32Array} negatives - Negative embeddings [N, D]
+   * @param {number} dim - Embedding dimension D
+   * @returns {number} - Loss value
+   */
+  forward(anchors, positives, negatives, dim) {
+    return this._inner.forward(anchors, positives, negatives, dim);
+  }
+
+  /**
+   * Get margin parameter
+   * @returns {number}
+   */
+  get margin() {
+    return this._inner.margin;
+  }
+}
+
+/**
+ * SIMD-optimized operations
+ */
+const SimdOps = {
+  /**
+   * Compute dot product of two vectors
+   * @param {Float32Array} a
+   * @param {Float32Array} b
+   * @returns {number}
+   */
+  dotProduct(a, b) {
+    if (!initialized) throw new Error('Module not initialized');
+    return wasm.SimdOps.dot_product(a, b);
+  },
+
+  /**
+   * Apply ReLU activation in-place
+   * @param {Float32Array} data
+   */
+  relu(data) {
+    if (!initialized) throw new Error('Module not initialized');
+    wasm.SimdOps.relu(data);
+  },
+
+  /**
+   * Apply ReLU6 activation in-place
+   * @param {Float32Array} data
+   */
+  relu6(data) {
+    if (!initialized) throw new Error('Module not initialized');
+    wasm.SimdOps.relu6(data);
+  },
+
+  /**
+   * L2 normalize a vector in-place
+   * @param {Float32Array} data
+   */
+  l2Normalize(data) {
+    if (!initialized) throw new Error('Module not initialized');
+    wasm.SimdOps.l2_normalize(data);
+  }
+};
+
+/**
+ * Layer operations for building custom networks
+ */
+const LayerOps = {
+  /**
+   * Apply batch normalization
+   * @param {Float32Array} input - Input data (modified in-place)
+   * @param {Float32Array} gamma - Scale parameter
+   * @param {Float32Array} beta - Shift parameter
+   * @param {Float32Array} mean - Running mean
+   * @param {Float32Array} variance - Running variance
+   * @param {number} [epsilon=1e-5] - Numerical stability
+   */
+  batchNorm(input, gamma, beta, mean, variance, epsilon = 1e-5) {
+    if (!initialized) throw new Error('Module not initialized');
+    wasm.LayerOps.batch_norm(input, gamma, beta, mean, variance, epsilon);
+  },
+
+  /**
+   * Apply global average pooling
+   * @param {Float32Array} input - Input tensor [C, H, W]
+   * @param {number} channels - Number of channels
+   * @param {number} spatialSize - H * W
+   * @returns {Float32Array} - Output [C]
+   */
+  globalAvgPool(input, channels, spatialSize) {
+    if (!initialized) throw new Error('Module not initialized');
+    return new Float32Array(wasm.LayerOps.global_avg_pool(input, channels, spatialSize));
+  }
+};
+
+module.exports = {
+  init,
+  CnnEmbedder,
+  InfoNCELoss,
+  TripletLoss,
+  SimdOps,
+  LayerOps
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@ruvector/cnn",
+  "version": "0.1.0",
+  "description": "CNN feature extraction for image embeddings - SIMD-optimized, pure Rust/WASM",
+  "main": "index.js",
+  "module": "index.mjs",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "ruvector_cnn_wasm_bg.wasm",
+    "ruvector_cnn_wasm.js",
+    "ruvector_cnn_wasm.d.ts",
+    "ruvector_cnn_wasm_bg.wasm.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "wasm-pack build ../../crates/ruvector-cnn-wasm --target web --out-dir ../../npm/packages/ruvector-cnn/pkg",
+    "postbuild": "cp pkg/* . && rm -rf pkg",
+    "test": "node test.js"
+  },
+  "keywords": [
+    "cnn",
+    "embeddings",
+    "image",
+    "wasm",
+    "simd",
+    "machine-learning",
+    "contrastive-learning",
+    "mobilenet",
+    "ruvector"
+  ],
+  "author": "ruvnet",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ruvnet/ruvector.git",
+    "directory": "npm/packages/ruvector-cnn"
+  },
+  "bugs": {
+    "url": "https://github.com/ruvnet/ruvector/issues"
+  },
+  "homepage": "https://github.com/ruvnet/ruvector#readme",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/ruvector_cnn_wasm.d.ts

@@ -0,0 +1,204 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Configuration for CNN embedder
+ */
+export class EmbedderConfig {
+    free(): void;
+    [Symbol.dispose](): void;
+    constructor();
+    /**
+     * Output embedding dimension
+     */
+    embedding_dim: number;
+    /**
+     * Input image size (square)
+     */
+    input_size: number;
+    /**
+     * Whether to L2 normalize embeddings
+     */
+    normalize: boolean;
+}
+
+/**
+ * Layer operations for building custom networks
+ */
+export class LayerOps {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Apply batch normalization (returns new array)
+     */
+    static batch_norm(input: Float32Array, gamma: Float32Array, beta: Float32Array, mean: Float32Array, _var: Float32Array, epsilon: number): Float32Array;
+    /**
+     * Apply global average pooling
+     * Returns one value per channel
+     */
+    static global_avg_pool(input: Float32Array, height: number, width: number, channels: number): Float32Array;
+}
+
+/**
+ * SIMD-optimized operations
+ */
+export class SimdOps {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Dot product of two vectors
+     */
+    static dot_product(a: Float32Array, b: Float32Array): number;
+    /**
+     * L2 normalize a vector (returns new array)
+     */
+    static l2_normalize(data: Float32Array): Float32Array;
+    /**
+     * ReLU activation (returns new array)
+     */
+    static relu(data: Float32Array): Float32Array;
+    /**
+     * ReLU6 activation (returns new array)
+     */
+    static relu6(data: Float32Array): Float32Array;
+}
+
+/**
+ * WASM CNN Embedder for image feature extraction
+ */
+export class WasmCnnEmbedder {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Compute cosine similarity between two embeddings
+     */
+    cosine_similarity(a: Float32Array, b: Float32Array): number;
+    /**
+     * Extract embedding from image data (RGB format, row-major)
+     */
+    extract(image_data: Uint8Array, width: number, height: number): Float32Array;
+    /**
+     * Create a new CNN embedder
+     */
+    constructor(config?: EmbedderConfig | null);
+    /**
+     * Get the embedding dimension
+     */
+    readonly embedding_dim: number;
+}
+
+/**
+ * InfoNCE loss for contrastive learning (SimCLR style)
+ */
+export class WasmInfoNCELoss {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Compute loss for a batch of embedding pairs
+     * embeddings: [2N, D] flattened where (i, i+N) are positive pairs
+     */
+    forward(embeddings: Float32Array, batch_size: number, dim: number): number;
+    /**
+     * Create new InfoNCE loss with temperature parameter
+     */
+    constructor(temperature: number);
+    /**
+     * Get the temperature parameter
+     */
+    readonly temperature: number;
+}
+
+/**
+ * Triplet loss for metric learning
+ */
+export class WasmTripletLoss {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Compute loss for a batch of triplets
+     */
+    forward(anchors: Float32Array, positives: Float32Array, negatives: Float32Array, dim: number): number;
+    /**
+     * Compute loss for a single triplet
+     */
+    forward_single(anchor: Float32Array, positive: Float32Array, negative: Float32Array): number;
+    /**
+     * Create new triplet loss with margin
+     */
+    constructor(margin: number);
+    /**
+     * Get the margin parameter
+     */
+    readonly margin: number;
+}
+
+/**
+ * Initialize panic hook for better error messages
+ */
+export function init(): void;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_embedderconfig_free: (a: number, b: number) => void;
+    readonly __wbg_get_embedderconfig_embedding_dim: (a: number) => number;
+    readonly __wbg_get_embedderconfig_input_size: (a: number) => number;
+    readonly __wbg_get_embedderconfig_normalize: (a: number) => number;
+    readonly __wbg_layerops_free: (a: number, b: number) => void;
+    readonly __wbg_set_embedderconfig_embedding_dim: (a: number, b: number) => void;
+    readonly __wbg_set_embedderconfig_input_size: (a: number, b: number) => void;
+    readonly __wbg_set_embedderconfig_normalize: (a: number, b: number) => void;
+    readonly __wbg_wasmcnnembedder_free: (a: number, b: number) => void;
+    readonly __wbg_wasminfonceloss_free: (a: number, b: number) => void;
+    readonly __wbg_wasmtripletloss_free: (a: number, b: number) => void;
+    readonly embedderconfig_new: () => number;
+    readonly layerops_batch_norm: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number) => void;
+    readonly layerops_global_avg_pool: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly simdops_dot_product: (a: number, b: number, c: number, d: number) => number;
+    readonly simdops_l2_normalize: (a: number, b: number, c: number) => void;
+    readonly simdops_relu: (a: number, b: number, c: number) => void;
+    readonly simdops_relu6: (a: number, b: number, c: number) => void;
+    readonly wasmcnnembedder_cosine_similarity: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly wasmcnnembedder_embedding_dim: (a: number) => number;
+    readonly wasmcnnembedder_extract: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly wasmcnnembedder_new: (a: number, b: number) => void;
+    readonly wasminfonceloss_forward: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly wasminfonceloss_new: (a: number) => number;
+    readonly wasminfonceloss_temperature: (a: number) => number;
+    readonly wasmtripletloss_forward: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
+    readonly wasmtripletloss_forward_single: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
+    readonly wasmtripletloss_margin: (a: number) => number;
+    readonly wasmtripletloss_new: (a: number) => number;
+    readonly init: () => void;
+    readonly __wbg_simdops_free: (a: number, b: number) => void;
+    readonly __wbindgen_export: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_export2: (a: number, b: number) => number;
+    readonly __wbindgen_export3: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;