12 KiB
12 KiB
@ruvector/wasm-unified
Unified TypeScript API surface for RuVector WASM - exposing attention, learning, economy, and exotic computation features through a clean, type-safe interface.
Features
- 14+ Attention Mechanisms: Neural (scaled-dot, multi-head, hyperbolic, linear, flash, local-global, MoE, Mamba) and DAG (topological, mincut-gated, hierarchical, spectral, flow, causal, sparse)
- Adaptive Learning: Micro-LoRA adaptation, SONA pre-query, BTSP one-shot learning, RL algorithms, meta-learning
- Nervous System Simulation: Spiking neural networks, synaptic plasticity, multiple neuron models
- Compute Credit Economy: Balance management, staking, rewards, contribution multipliers
- Exotic Computation: Quantum-inspired, hyperbolic geometry, topological data analysis, fractal operations
Installation
npm install @ruvector/wasm-unified
# or
pnpm add @ruvector/wasm-unified
# or
yarn add @ruvector/wasm-unified
Quick Start
import { createUnifiedEngine } from '@ruvector/wasm-unified';
// Create and initialize the unified engine
const engine = await createUnifiedEngine();
await engine.init();
// Use attention mechanisms
const Q = new Float32Array([1, 2, 3, 4]);
const K = new Float32Array([1, 2, 3, 4]);
const V = new Float32Array([1, 2, 3, 4]);
const output = engine.attention.scaledDot(Q, K, V);
// Use learning capabilities
engine.learning.btspOneShotLearn(pattern, 1.0);
// Simulate nervous system
const neuronId = engine.nervous.createNeuron({ neuronType: 'excitatory' });
engine.nervous.step();
// Manage economy
const balance = engine.economy.creditBalance();
engine.economy.stakeDeposit(100);
// Exotic computations
const qstate = engine.exotic.quantumInit(4);
const measured = engine.exotic.quantumMeasure(qstate);
// Cleanup when done
engine.dispose();
Module Usage
Attention Engine
import { createAttentionEngine, listAttentionMechanisms } from '@ruvector/wasm-unified';
const attention = createAttentionEngine();
// List available mechanisms
console.log(listAttentionMechanisms());
// ['scaled-dot', 'multi-head', 'hyperbolic', 'linear', 'flash', ...]
// Scaled dot-product attention
const output = attention.scaledDot(Q, K, V);
// Multi-head attention
const multiHeadOutput = attention.multiHead(query, keys, values, {
numHeads: 8,
headDim: 64,
dropout: 0.1,
});
// Hyperbolic attention (for hierarchical data)
const hyperbolicOutput = attention.hyperbolic(query, keys, values, -1.0);
// Flash attention (memory-efficient)
const flashOutput = attention.flash(query, keys, values, 256);
// Mixture of Experts attention
const moeResult = attention.moe(query, keys, values, 8, 2);
console.log(moeResult.loadBalanceLoss);
// Mamba (state-space model)
const mambaResult = attention.mamba(input, state);
console.log(mambaResult.newState);
// DAG-based attention
const dag = {
nodes: [
{ id: 'n1', embedding: new Float32Array([1, 2]), nodeType: 'query' },
{ id: 'n2', embedding: new Float32Array([3, 4]), nodeType: 'key' },
],
edges: [{ source: 'n1', target: 'n2', weight: 1.0, edgeType: 'attention' }],
rootIds: ['n1'],
leafIds: ['n2'],
};
const dagScores = attention.dagTopological(dag);
const gatedScores = attention.dagMincutGated(dag, {
gateValues: new Float32Array([0.5, 0.8]),
threshold: 0.3,
mode: 'soft',
});
Learning Engine
import {
createLearningEngine,
createMicroLoraConfig,
createBtspConfig,
cosineAnnealingLr,
} from '@ruvector/wasm-unified';
const learning = createLearningEngine({
defaultLearningRate: 0.001,
batchSize: 32,
});
// Micro-LoRA adaptation
const loraConfig = createMicroLoraConfig(8, 16, ['attention', 'ffn']);
const adapted = learning.microLoraAdapt(embedding, 'attention', loraConfig);
// SONA pre-query enhancement
const enhanced = learning.sonaPreQuery(dag, 128);
console.log(enhanced.confidence);
// BTSP one-shot learning
const btspConfig = createBtspConfig(0.1, 0.95, 100);
learning.btspOneShotLearn(pattern, rewardSignal, btspConfig);
// Reinforcement learning
const trajectory = {
states: [state1, state2, state3],
actions: [0, 1, 0],
rewards: [0.1, 0.5, 1.0],
dones: [false, false, true],
};
const policyUpdate = learning.updateFromTrajectory(trajectory, 'ppo');
console.log(policyUpdate.loss, policyUpdate.entropy);
// Compute advantages with GAE
const advantages = learning.computeAdvantages(rewards, values, 0.99, 0.95);
// Experience replay
const batch = learning.experienceReplay(10000, 32);
// Meta-learning with MAML
const adaptedParams = learning.mamlInnerLoop(supportSet, 5, 0.01);
// Learning rate scheduling
const lr = cosineAnnealingLr(step, totalSteps, 0.001, 0.00001);
// Get statistics
const stats = learning.getStats();
console.log(stats.patternsLearned, stats.totalSteps);
Nervous System Engine
import {
createNervousEngine,
createStdpConfig,
izhikevichParams,
} from '@ruvector/wasm-unified';
const nervous = createNervousEngine({
maxNeurons: 10000,
simulationDt: 0.1,
enablePlasticity: true,
});
// Create neurons
const excitatory = nervous.createNeuron({
neuronType: 'excitatory',
model: 'izhikevich',
threshold: -55,
});
const inhibitory = nervous.createNeuron({
neuronType: 'inhibitory',
model: 'lif',
});
// Create synapses
nervous.createSynapse(excitatory, inhibitory, {
weight: 0.5,
delay: 1.0,
plasticity: { type: 'stdp', params: {} },
});
// Create network topologies
nervous.createReservoir(500, 0.9, 10); // Echo State Network
nervous.createSmallWorld(100, 4, 0.1); // Small-world network
nervous.createFeedforward([10, 50, 20, 5], 0.8); // Feedforward
// Simulate
nervous.injectCurrent(new Map([[excitatory, 10.0]]));
const result = nervous.step(0.1);
console.log('Spikes:', result.spikes);
// Apply plasticity
const stdpConfig = createStdpConfig();
nervous.applyStdp(stdpConfig);
nervous.applyHomeostasis(10); // Target 10 Hz firing rate
// Record activity
nervous.startRecording([excitatory, inhibitory]);
for (let i = 0; i < 1000; i++) {
nervous.step();
}
const recording = nervous.stopRecording();
const raster = nervous.getSpikeRaster(0, 100);
// Get topology statistics
const topoStats = nervous.getTopologyStats();
console.log('Neurons:', topoStats.neuronCount);
console.log('Clustering:', topoStats.clusteringCoefficient);
Economy Engine
import {
createEconomyEngine,
calculateStakingApy,
formatCredits,
} from '@ruvector/wasm-unified';
const economy = createEconomyEngine({
initialBalance: 1000,
stakingEnabled: true,
rewardRate: 0.05,
});
// Check balance
console.log('Balance:', formatCredits(economy.creditBalance()));
console.log('Multiplier:', economy.contributionMultiplier());
// Staking
if (economy.canAfford(500)) {
const position = economy.stakeDeposit(500, 86400 * 30); // 30-day lock
console.log('Expected reward:', position.expectedReward);
}
// Calculate APY
const apy = calculateStakingApy(0.05, 365);
console.log('APY:', (apy * 100).toFixed(2) + '%');
// Transactions
economy.deposit(100, 'external-source');
const withdrawTx = economy.withdraw(50, 'external-dest');
console.log('Transaction ID:', withdrawTx.id);
// Record contributions
economy.recordContribution('compute', 1000);
economy.recordContribution('validation', 500);
// Claim rewards
const pending = economy.getPendingRewards();
const claimed = economy.claimRewards();
console.log('Claimed:', formatCredits(claimed));
// Operation pricing
const cost = economy.getCost('attention_flash');
console.log('Flash attention cost:', cost);
// Analytics
const analytics = economy.getAnalytics('week');
console.log('Net flow:', formatCredits(analytics.netFlow));
Exotic Engine
import {
createExoticEngine,
createCircuitBuilder,
projectToPoincare,
poincareToLorentz,
} from '@ruvector/wasm-unified';
const exotic = createExoticEngine({
quantumSimulationDepth: 10,
hyperbolicPrecision: 1e-10,
topologicalMaxDimension: 3,
});
// Quantum-inspired computation
const qstate = exotic.quantumInit(4);
let state = exotic.quantumHadamard(qstate, 0); // Superposition
state = exotic.quantumCnot(state, 0, 1); // Entanglement
state = exotic.quantumPhase(state, 1, Math.PI / 4);
const measurement = exotic.quantumMeasure(state);
console.log('Measured:', measurement.bitstring);
// Build quantum circuits
const circuit = createCircuitBuilder(3);
circuit.h(0);
circuit.cnot(0, 1);
circuit.ry(2, Math.PI / 3);
const qc = circuit.build();
// VQE for ground state
const vqeResult = exotic.quantumVqe(hamiltonian, qc, 'cobyla');
console.log('Ground state energy:', vqeResult.energy);
// Hyperbolic geometry
const p1 = exotic.hyperbolicPoint(new Float32Array([0.1, 0.2]), 'poincare', -1);
const p2 = exotic.hyperbolicPoint(new Float32Array([0.3, 0.1]), 'poincare', -1);
const distance = exotic.hyperbolicDistance(p1, p2);
console.log('Hyperbolic distance:', distance);
// Mobius operations
const sum = exotic.mobiusAdd(p1, p2);
const centroid = exotic.hyperbolicCentroid([p1, p2]);
// Convert between models
const euclidean = new Float32Array([0.5, 0.3]);
const poincare = projectToPoincare(euclidean);
const lorentz = poincareToLorentz(poincare);
// Topological data analysis
const pointCloud = [
new Float32Array([0, 0]),
new Float32Array([1, 0]),
new Float32Array([0.5, 0.866]),
];
const features = exotic.persistentHomology(pointCloud, 2);
const betti = exotic.bettiNumbers(features, 0.1);
console.log('Betti numbers:', betti);
// Persistence diagram
const diagram = exotic.persistenceDiagram(features);
const bottleneck = exotic.bottleneckDistance(diagram1, diagram2);
// Mapper algorithm
const graph = exotic.mapper(data, undefined, 10, 0.5);
console.log('Mapper nodes:', graph.nodes.length);
// Fractal analysis
const fractalDim = exotic.fractalDimension(data);
const lyapunov = exotic.lyapunovExponents(timeSeries, 3, 1);
// Non-Euclidean neural layers
const hyperbolicOutput = exotic.hyperbolicLayer(inputs, weights, bias);
const sphericalOutput = exotic.sphericalLayer(inputs, weights);
Type Safety
All APIs are fully typed with TypeScript:
import type {
AttentionEngine,
LearningEngine,
NervousEngine,
EconomyEngine,
ExoticEngine,
MultiHeadConfig,
MoEResult,
QueryDag,
EnhancedEmbedding,
Neuron,
Synapse,
Transaction,
QuantumState,
HyperbolicPoint,
TopologicalFeature,
} from '@ruvector/wasm-unified';
Benchmarking
import { benchmarkAttention, listAttentionMechanisms } from '@ruvector/wasm-unified';
// Benchmark specific mechanism
const results = await benchmarkAttention('flash', 1024, 100);
console.log(`Flash attention: ${results.avgTimeMs}ms avg, ${results.throughputOpsPerSec} ops/sec`);
// Benchmark all mechanisms
for (const mechanism of listAttentionMechanisms()) {
const result = await benchmarkAttention(mechanism, 512, 50);
console.log(`${mechanism}: ${result.avgTimeMs.toFixed(3)}ms`);
}
Configuration
import { createUnifiedEngine } from '@ruvector/wasm-unified';
const engine = await createUnifiedEngine({
// Global settings
wasmPath: '/wasm/ruvector.wasm',
enableSimd: true,
enableThreads: true,
memoryLimit: 1024 * 1024 * 512, // 512MB
logLevel: 'info',
// Module-specific settings
attention: {
defaultMechanism: 'flash',
cacheSize: 1024,
precisionMode: 'mixed',
},
learning: {
defaultLearningRate: 0.001,
batchSize: 64,
enableGradientCheckpointing: true,
},
nervous: {
maxNeurons: 100000,
simulationDt: 0.05,
enablePlasticity: true,
},
economy: {
initialBalance: 10000,
stakingEnabled: true,
rewardRate: 0.08,
},
exotic: {
quantumSimulationDepth: 20,
hyperbolicPrecision: 1e-12,
topologicalMaxDimension: 4,
},
});
Statistics and Monitoring
const engine = await createUnifiedEngine();
await engine.init();
// ... perform operations ...
// Get comprehensive statistics
const stats = engine.getStats();
console.log('Attention ops:', stats.attention.operationCount);
console.log('Learning steps:', stats.learning.stepsCompleted);
console.log('Neurons:', stats.nervous.neuronCount);
console.log('Balance:', stats.economy.balance);
console.log('Quantum ops:', stats.exotic.quantumOps);
console.log('Uptime:', stats.system.uptime, 'ms');
API Reference
See the TypeScript definitions for complete API documentation.
License
MIT