ruv-neural-embed

Graph embedding generation for brain connectivity states using RuVector format.

Overview

ruv-neural-embed converts brain connectivity graphs into fixed-dimensional vector representations suitable for downstream classification, clustering, and temporal analysis. It provides multiple embedding methods and supports export to the RuVector .rvf binary format for interoperability with the broader RuVector ecosystem.

Features

Spectral embedding (spectral_embed): Laplacian eigenvector-based positional encoding from the graph's normalized Laplacian
Topology embedding (topology_embed): Hand-crafted topological feature vectors derived from graph-theoretic metrics
Node2Vec (node2vec): Random-walk co-occurrence embeddings using configurable walk length, return parameter (p), and in-out parameter (q)
Combined embedding (combined): Weighted concatenation of multiple embedding methods into a single vector
Temporal embedding (temporal): Sliding-window context-enriched embeddings that capture graph dynamics over time
Distance metrics (distance): Embedding distance and similarity computations
RVF export (rvf_export): Serialization of embeddings and trajectories to the RuVector .rvf binary format
Helper utilities: default_metadata for quick EmbeddingMetadata construction

Usage

rust

use ruv_neural_embed::{
    NeuralEmbedding, EmbeddingMetadata, EmbeddingTrajectory,
    default_metadata,
};
use ruv_neural_core::brain::Atlas;

// Create an embedding with metadata
let meta = default_metadata("spectral", Atlas::Schaefer100);
let emb = NeuralEmbedding::new(vec![0.1, 0.5, -0.3, 0.8], 1000.0, meta).unwrap();
assert_eq!(emb.dimension, 4);

// Compute similarity between embeddings
let other = NeuralEmbedding::new(
    vec![0.2, 0.4, -0.2, 0.9],
    1001.0,
    default_metadata("spectral", Atlas::Schaefer100),
).unwrap();
let similarity = emb.cosine_similarity(&other).unwrap();
let distance = emb.euclidean_distance(&other).unwrap();

// Build a trajectory from a sequence of embeddings
let trajectory = EmbeddingTrajectory {
    embeddings: vec![emb, other],
    timestamps: vec![1000.0, 1001.0],
};
assert_eq!(trajectory.len(), 2);

API Reference

Module	Key Types / Functions
`spectral_embed`	Spectral positional encoding from graph Laplacian
`topology_embed`	Topological feature vector extraction
`node2vec`	Random-walk based node embeddings
`combined`	Weighted multi-method embedding concatenation
`temporal`	Sliding-window temporal context embeddings
`distance`	Distance and similarity computations
`rvf_export`	RVF binary format serialization

Feature Flags

Feature	Default	Description
`std`	Yes	Standard library support
`wasm`	No	WASM-compatible implementations
`rvf`	No	RuVector RVF format export support

Integration

Depends on ruv-neural-core for NeuralEmbedding, BrainGraph, and EmbeddingGenerator trait. Receives graphs from ruv-neural-graph or ruv-neural-mincut. Produced embeddings are stored by ruv-neural-memory and classified by ruv-neural-decoder.

License

MIT OR Apache-2.0