@ruvector/gnn - Graph Neural Network Node.js Bindings

High-performance Graph Neural Network (GNN) capabilities for Ruvector, powered by Rust and NAPI-RS.


Features

- GNN Layers: Multi-head attention, layer normalization, GRU cells
- Tensor Compression: Adaptive compression with 5 levels (None, Half, PQ8, PQ4, Binary)
- Differentiable Search: Soft attention-based search with temperature scaling
- Hierarchical Processing: Multi-layer GNN forward pass
- Zero-copy: Efficient data transfer between JavaScript and Rust
- TypeScript Support: Full type definitions included

Installation

``bash
npm install @ruvector/gnn
`

Quick Start

$3

`javascript
const { RuvectorLayer } = require('@ruvector/gnn');

// Create a GNN layer with:
// - Input dimension: 128
// - Hidden dimension: 256
// - Attention heads: 4
// - Dropout rate: 0.1
const layer = new RuvectorLayer(128, 256, 4, 0.1);

// Forward pass
const nodeEmbedding = new Array(128).fill(0).map(() => Math.random());
const neighborEmbeddings = [
new Array(128).fill(0).map(() => Math.random()),
new Array(128).fill(0).map(() => Math.random()),
];
const edgeWeights = [0.7, 0.3];

const output = layer.forward(nodeEmbedding, neighborEmbeddings, edgeWeights);
console.log('Output dimension:', output.length); // 256
`

$3

`javascript
const { TensorCompress, getCompressionLevel } = require('@ruvector/gnn');

const compressor = new TensorCompress();
const embedding = new Array(128).fill(0).map(() => Math.random());

// Adaptive compression based on access frequency
const accessFreq = 0.5; // 50% access rate
console.log('Selected level:', getCompressionLevel(accessFreq)); // "half"

const compressed = compressor.compress(embedding, accessFreq);
const decompressed = compressor.decompress(compressed);

console.log('Original size:', embedding.length);
console.log('Compression ratio:', compressed.length / JSON.stringify(embedding).length);

// Explicit compression level
const level = {
level_type: 'pq8',
subvectors: 8,
centroids: 16
};
const compressedPQ = compressor.compressWithLevel(embedding, level);
`

$3

`javascript
const { differentiableSearch } = require('@ruvector/gnn');

const query = [1.0, 0.0, 0.0];
const candidates = [
[1.0, 0.0, 0.0], // Perfect match
[0.9, 0.1, 0.0], // Close match
[0.0, 1.0, 0.0], // Orthogonal
];

const result = differentiableSearch(query, candidates, 2, 1.0);
console.log('Top-2 indices:', result.indices); // [0, 1]
console.log('Soft weights:', result.weights); // [0.x, 0.y]
`

$3

`javascript
const { hierarchicalForward, RuvectorLayer } = require('@ruvector/gnn');

const query = [1.0, 0.0];

// Layer embeddings (organized by HNSW layers)
const layerEmbeddings = [
[[1.0, 0.0], [0.0, 1.0]], // Layer 0 embeddings
];

// Create and serialize GNN layers
const layer1 = new RuvectorLayer(2, 2, 1, 0.0);
const layers = [layer1.toJson()];

// Hierarchical processing
const result = hierarchicalForward(query, layerEmbeddings, layers);
console.log('Final embedding:', result);
`

API Reference

$3

#### Constructor

`typescript
new RuvectorLayer(
inputDim: number,
hiddenDim: number,
heads: number,
dropout: number
): RuvectorLayer
`

#### Methods

- forward(nodeEmbedding: number[], neighborEmbeddings: number[][], edgeWeights: number[]): number[]
- toJson(): string - Serialize layer to JSON
- fromJson(json: string): RuvectorLayer - Deserialize layer from JSON

$3

#### Constructor

`typescript
new TensorCompress(): TensorCompress
`

#### Methods

- compress(embedding: number[], accessFreq: number): string - Adaptive compression
- compressWithLevel(embedding: number[], level: CompressionLevelConfig): string - Explicit level
- decompress(compressedJson: string): number[] - Decompress tensor

#### CompressionLevelConfig

`typescript
interface CompressionLevelConfig {
level_type: 'none' | 'half' | 'pq8' | 'pq4' | 'binary';
scale?: number; // For 'half'
subvectors?: number; // For 'pq8', 'pq4'
centroids?: number; // For 'pq8'
outlier_threshold?: number; // For 'pq4'
threshold?: number; // For 'binary'
}
`

$3

#### differentiableSearch

`typescript
function differentiableSearch(
query: number[],
candidateEmbeddings: number[][],
k: number,
temperature: number
): { indices: number[], weights: number[] }
`

#### hierarchicalForward

`typescript
function hierarchicalForward(
query: number[],
layerEmbeddings: number[][][],
gnnLayersJson: string[]
): number[]
`

$3

#### getCompressionLevel

`typescript
function getCompressionLevel(accessFreq: number): string
`

Returns the compression level that would be selected for the given access frequency:
- accessFreq > 0.8: "none" (hot data)
- accessFreq > 0.4: "half" (warm data)
- accessFreq > 0.1: "pq8" (cool data)
- accessFreq > 0.01: "pq4" (cold data)
- accessFreq <= 0.01: "binary" (archive)

Compression Levels

$3

Full precision, no compression. Best for frequently accessed data.

$3

~50% space savings with minimal quality loss. Good for warm data.

$3

~8x compression using 8-bit codes. Suitable for cool data.

$3

~16x compression with outlier handling. For cold data.

$3

~32x compression, values become +1/-1. For archival data.

Performance

- Zero-copy operations where possible
- SIMD optimizations for vector operations
- Parallel processing with Rayon
- Native performance with Rust backend

Building from Source

`bash


Install dependencies

npm install

Build debug

npm run build:debug

Build release

npm run build

Run tests

npm test
``

License

MIT - See LICENSE file for details

Contributing

Contributions are welcome! Please see the main Ruvector repository for guidelines.

Links

- GitHub Repository
- Documentation
- Issues