Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'

vendor/ruvector/crates/ruvector-gnn-wasm/README.md

@@ -0,0 +1,190 @@
+# RuVector GNN WASM
+
+WebAssembly bindings for RuVector Graph Neural Network operations.
+
+## Features
+
+- **GNN Layer Operations**: Multi-head attention, GRU updates, layer normalization
+- **Tensor Compression**: Adaptive compression based on access frequency
+- **Differentiable Search**: Soft attention-based similarity search
+- **Hierarchical Forward**: Multi-layer GNN processing
+
+## Installation
+
+```bash
+npm install ruvector-gnn-wasm
+```
+
+## Usage
+
+### Initialize
+
+```typescript
+import init, {
+  JsRuvectorLayer,
+  JsTensorCompress,
+  differentiableSearch,
+  SearchConfig
+} from 'ruvector-gnn-wasm';
+
+await init();
+```
+
+### GNN Layer
+
+```typescript
+// Create a GNN layer
+const layer = new JsRuvectorLayer(
+  4,    // input dimension
+  8,    // hidden dimension
+  2,    // number of attention heads
+  0.1   // dropout rate
+);
+
+// Forward pass
+const nodeEmbedding = new Float32Array([1.0, 2.0, 3.0, 4.0]);
+const neighbors = [
+  new Float32Array([0.5, 1.0, 1.5, 2.0]),
+  new Float32Array([2.0, 3.0, 4.0, 5.0])
+];
+const edgeWeights = new Float32Array([0.3, 0.7]);
+
+const output = layer.forward(nodeEmbedding, neighbors, edgeWeights);
+console.log('Output dimension:', layer.outputDim);
+```
+
+### Tensor Compression
+
+```typescript
+const compressor = new JsTensorCompress();
+
+// Compress based on access frequency
+const embedding = new Float32Array(128).fill(0.5);
+const compressed = compressor.compress(embedding, 0.5); // 50% access frequency
+
+// Decompress
+const decompressed = compressor.decompress(compressed);
+
+// Or specify compression level explicitly
+const compressedPQ8 = compressor.compressWithLevel(embedding, "pq8");
+
+// Get compression ratio
+const ratio = compressor.getCompressionRatio(0.5); // Returns ~2.0 for half precision
+```
+
+### Compression Levels
+
+Access frequency determines compression:
+- `f > 0.8`: **Full precision** (no compression) - hot data
+- `f > 0.4`: **Half precision** (2x compression) - warm data
+- `f > 0.1`: **8-bit PQ** (4x compression) - cool data
+- `f > 0.01`: **4-bit PQ** (8x compression) - cold data
+- `f <= 0.01`: **Binary** (32x compression) - archive data
+
+### Differentiable Search
+
+```typescript
+const query = new Float32Array([1.0, 0.0, 0.0]);
+const candidates = [
+  new Float32Array([1.0, 0.0, 0.0]),  // Perfect match
+  new Float32Array([0.9, 0.1, 0.0]),  // Close match
+  new Float32Array([0.0, 1.0, 0.0])   // Orthogonal
+];
+
+const config = new SearchConfig(2, 1.0); // k=2, temperature=1.0
+const result = differentiableSearch(query, candidates, config);
+
+console.log('Top indices:', result.indices);
+console.log('Weights:', result.weights);
+```
+
+## API Reference
+
+### `JsRuvectorLayer`
+
+```typescript
+class JsRuvectorLayer {
+  constructor(
+    inputDim: number,
+    hiddenDim: number,
+    heads: number,
+    dropout: number
+  );
+
+  forward(
+    nodeEmbedding: Float32Array,
+    neighborEmbeddings: Float32Array[],
+    edgeWeights: Float32Array
+  ): Float32Array;
+
+  readonly outputDim: number;
+}
+```
+
+### `JsTensorCompress`
+
+```typescript
+class JsTensorCompress {
+  constructor();
+
+  compress(embedding: Float32Array, accessFreq: number): object;
+  compressWithLevel(embedding: Float32Array, level: string): object;
+  decompress(compressed: object): Float32Array;
+  getCompressionRatio(accessFreq: number): number;
+}
+```
+
+Compression levels: `"none"`, `"half"`, `"pq8"`, `"pq4"`, `"binary"`
+
+### `differentiableSearch`
+
+```typescript
+function differentiableSearch(
+  query: Float32Array,
+  candidateEmbeddings: Float32Array[],
+  config: SearchConfig
+): { indices: number[], weights: number[] };
+```
+
+### `SearchConfig`
+
+```typescript
+class SearchConfig {
+  constructor(k: number, temperature: number);
+  k: number;          // Number of results
+  temperature: number; // Softmax temperature (lower = sharper)
+}
+```
+
+### `cosineSimilarity`
+
+```typescript
+function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+```
+
+## Building from Source
+
+```bash
+# Install wasm-pack
+curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
+
+# Build for Node.js
+wasm-pack build --target nodejs
+
+# Build for browser
+wasm-pack build --target web
+
+# Build for bundler (webpack, etc.)
+wasm-pack build --target bundler
+```
+
+## Performance
+
+- GNN layers use efficient attention mechanisms
+- Compression reduces memory usage by 2-32x
+- All operations are optimized for WASM
+- No garbage collection during forward passes
+
+## License
+
+MIT