{"_id":"@aigentic/attention-unified-wasm","_rev":"2-b993a0d5c3830d19c01743b29075c482","name":"@aigentic/attention-unified-wasm","dist-tags":{"alpha":"0.1.29","latest":"0.1.29"},"versions":{"0.1.29":{"name":"@aigentic/attention-unified-wasm","version":"0.1.29","keywords":["attention","wasm","neural","dag","mamba","ruvector","webassembly","transformer","graph-attention","state-space-models"],"author":{"name":"RuVector Team","email":"ruvnet@users.noreply.github.com"},"license":"MIT OR Apache-2.0","_id":"@aigentic/attention-unified-wasm@0.1.29","maintainers":[{"name":"aigentic","email":"engineering@aigentic.net"}],"homepage":"https://ruv.io","bugs":{"url":"https://github.com/ruvnet/ruvector/issues"},"dist":{"shasum":"70af1fd3c3a1193f065324974178f278a06ebb60","tarball":"https://registry.npmjs.org/@aigentic/attention-unified-wasm/-/attention-unified-wasm-0.1.29.tgz","fileCount":6,"integrity":"sha512-l0NgP423J4LpEW4tzTvAlylXuk2JLUw/I2L50PLCCQh+9atiDwMYmSB68SBuNavseEADM0rA4wkRL5JF0qJQdg==","signatures":[{"sig":"MEUCIHYL3yQHTFPilnEV8b/MY69NQv1yPubVvY18vcJSYvwvAiEAs+L0/boxEmZMMYWlixQHstmPYErj9RYpfutmDPR3xxU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":488214},"main":"ruvector_attention_unified_wasm.js","type":"module","types":"ruvector_attention_unified_wasm.d.ts","gitHead":"e2cb6210ce8d478b39cad81872a4aef78a05ceb4","_npmUser":{"name":"aigentic","email":"engineering@aigentic.net"},"repository":{"url":"git+https://github.com/ruvnet/ruvector.git","type":"git"},"_npmVersion":"11.12.0","description":"Unified WebAssembly bindings for 18+ attention mechanisms: Neural, DAG, Graph, and Mamba SSM","directories":{},"sideEffects":["./snippets/*"],"_nodeVersion":"22.22.1","collaborators":["RuVector Team"],"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/attention-unified-wasm_0.1.29_1779324004793_0.5120322890858406","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-05-21T00:40:04.557Z","modified":"2026-09-13T15:30:25.105Z","0.1.29":"2026-05-21T00:40:05.007Z"},"bugs":{"url":"https://github.com/ruvnet/ruvector/issues"},"author":{"name":"RuVector Team","email":"ruvnet@users.noreply.github.com"},"license":"MIT OR Apache-2.0","homepage":"https://ruv.io","keywords":["attention","wasm","neural","dag","mamba","ruvector","webassembly","transformer","graph-attention","state-space-models"],"repository":{"url":"git+https://github.com/ruvnet/ruvector.git","type":"git"},"description":"Unified WebAssembly bindings for 18+ attention mechanisms: Neural, DAG, Graph, and Mamba SSM","maintainers":[{"email":"engineering@aigentic.net","name":"aiggy"}],"readme":"# @aigentic/attention-unified-wasm - 18+ Attention Mechanisms in WASM\n\n[![npm version](https://img.shields.io/npm/v/ruvector-attention-unified-wasm.svg)](https://www.npmjs.com/package/ruvector-attention-unified-wasm)\n[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](https://github.com/ruvnet/ruvector)\n[![Bundle Size](https://img.shields.io/badge/bundle%20size-331KB%20gzip-green.svg)](https://www.npmjs.com/package/ruvector-attention-unified-wasm)\n[![WebAssembly](https://img.shields.io/badge/WebAssembly-654FF0?logo=webassembly&logoColor=white)](https://webassembly.org/)\n\n**Unified WebAssembly library** with 18+ attention mechanisms spanning Neural, DAG, Graph, and State Space Model categories. Single import for all your attention needs in browser and edge environments.\n\n## Key Features\n\n- **7 Neural Attention**: Scaled dot-product, multi-head, hyperbolic, linear, flash, local-global, MoE\n- **7 DAG Attention**: Topological, causal cone, critical path, MinCut-gated, hierarchical Lorentz, parallel branch, temporal BTSP\n- **3 Graph Attention**: GAT, GCN, GraphSAGE\n- **1 State Space**: Mamba SSM with hybrid attention\n- **Unified API**: Single selector for all mechanisms\n- **WASM-Optimized**: Runs in browsers, Node.js, and edge runtimes\n\n## Installation\n\n```bash\nnpm install ruvector-attention-unified-wasm\n# or\nyarn add ruvector-attention-unified-wasm\n# or\npnpm add ruvector-attention-unified-wasm\n```\n\n## Quick Start\n\n```typescript\nimport init, {\n  UnifiedAttention,\n  availableMechanisms,\n  scaledDotAttention,\n  WasmMultiHeadAttention,\n  MambaSSMAttention,\n  MambaConfig\n} from 'ruvector-attention-unified-wasm';\n\nawait init();\n\n// List all available mechanisms\nconst mechanisms = availableMechanisms();\nconsole.log(mechanisms);\n// { neural: [...], dag: [...], graph: [...], ssm: [...] }\n\n// Use unified selector\nconst attention = new UnifiedAttention(\"multi_head\");\nconsole.log(`Category: ${attention.category}`);  // \"neural\"\nconsole.log(`Supports sequences: ${attention.supportsSequences()}`);\n\n// Direct attention computation\nconst query = new Float32Array([1.0, 0.5, 0.3, 0.1]);\nconst keys = [new Float32Array([0.9, 0.4, 0.2, 0.1])];\nconst values = [new Float32Array([1.0, 1.0, 1.0, 1.0])];\nconst output = scaledDotAttention(query, keys, values);\n```\n\n## Attention Categories\n\n### Neural Attention (7 mechanisms)\n\nStandard transformer-style attention mechanisms for sequence processing.\n\n```typescript\nimport {\n  scaledDotAttention,\n  WasmMultiHeadAttention,\n  WasmHyperbolicAttention,\n  WasmLinearAttention,\n  WasmFlashAttention,\n  WasmLocalGlobalAttention,\n  WasmMoEAttention\n} from 'ruvector-attention-unified-wasm';\n\n// Scaled Dot-Product Attention\nconst output = scaledDotAttention(query, keys, values, scale);\n\n// Multi-Head Attention\nconst mha = new WasmMultiHeadAttention(256, 8);  // 256 dim, 8 heads\nconst attended = mha.compute(query, keys, values);\nconsole.log(`Heads: ${mha.numHeads}, Head dim: ${mha.headDim}`);\n\n// Hyperbolic Attention (for hierarchical data)\nconst hyperbolic = new WasmHyperbolicAttention(64, -1.0);  // curvature = -1\nconst hypOut = hyperbolic.compute(query, keys, values);\n\n// Linear Attention (O(n) complexity)\nconst linear = new WasmLinearAttention(64, 32);  // 32 random features\nconst linOut = linear.compute(query, keys, values);\n\n// Flash Attention (memory-efficient)\nconst flash = new WasmFlashAttention(64, 32);  // block size 32\nconst flashOut = flash.compute(query, keys, values);\n\n// Local-Global Attention (sparse)\nconst localGlobal = new WasmLocalGlobalAttention(64, 128, 4);  // window=128, 4 global\nconst lgOut = localGlobal.compute(query, keys, values);\n\n// Mixture of Experts Attention\nconst moe = new WasmMoEAttention(64, 8, 2);  // 8 experts, top-2\nconst moeOut = moe.compute(query, keys, values);\n```\n\n### DAG Attention (7 mechanisms)\n\nSpecialized attention for Directed Acyclic Graphs, query plans, and workflow optimization.\n\n```typescript\nimport {\n  WasmQueryDag,\n  WasmTopologicalAttention,\n  WasmCausalConeAttention,\n  WasmCriticalPathAttention,\n  WasmMinCutGatedAttention,\n  WasmHierarchicalLorentzAttention,\n  WasmParallelBranchAttention,\n  WasmTemporalBTSPAttention\n} from 'ruvector-attention-unified-wasm';\n\n// Create a query DAG\nconst dag = new WasmQueryDag();\nconst scan = dag.addNode(\"scan\", 10.0);\nconst filter = dag.addNode(\"filter\", 5.0);\nconst join = dag.addNode(\"join\", 20.0);\nconst aggregate = dag.addNode(\"aggregate\", 15.0);\n\ndag.addEdge(scan, filter);\ndag.addEdge(filter, join);\ndag.addEdge(scan, join);\ndag.addEdge(join, aggregate);\n\n// Topological Attention (position-aware)\nconst topo = new WasmTopologicalAttention(0.9);  // decay factor\nconst topoScores = topo.forward(dag);\n\n// Causal Cone Attention (lightcone-based)\nconst causal = new WasmCausalConeAttention(0.8, 0.6);  // future discount, ancestor weight\nconst causalScores = causal.forward(dag);\n\n// Critical Path Attention\nconst critical = new WasmCriticalPathAttention(2.0, 0.5);  // path weight, branch penalty\nconst criticalScores = critical.forward(dag);\n\n// MinCut-Gated Attention (flow-based)\nconst mincut = new WasmMinCutGatedAttention(0.5);  // gate threshold\nconst mincutScores = mincut.forward(dag);\n\n// Hierarchical Lorentz Attention (hyperbolic DAG)\nconst lorentz = new WasmHierarchicalLorentzAttention(-1.0, 0.1);  // curvature, temperature\nconst lorentzScores = lorentz.forward(dag);\n\n// Parallel Branch Attention\nconst parallel = new WasmParallelBranchAttention(4, 0.2);  // max branches, sync penalty\nconst parallelScores = parallel.forward(dag);\n\n// Temporal BTSP Attention\nconst btsp = new WasmTemporalBTSPAttention(0.95, 0.1);  // decay, baseline\nconst btspScores = btsp.forward(dag);\n```\n\n### Graph Attention (3 mechanisms)\n\nAttention mechanisms for graph-structured data.\n\n```typescript\nimport {\n  WasmGNNLayer,\n  GraphAttentionFactory,\n  graphHierarchicalForward,\n  graphDifferentiableSearch,\n  WasmSearchConfig\n} from 'ruvector-attention-unified-wasm';\n\n// Create GNN layer with attention\nconst gnn = new WasmGNNLayer(\n  64,     // input dimension\n  128,    // hidden dimension\n  4,      // attention heads\n  0.1     // dropout\n);\n\n// Forward pass for a node\nconst nodeEmbed = new Float32Array(64);\nconst neighborEmbeds = [\n  new Float32Array(64),\n  new Float32Array(64)\n];\nconst edgeWeights = new Float32Array([0.8, 0.6]);\n\nconst updated = gnn.forward(nodeEmbed, neighborEmbeds, edgeWeights);\nconsole.log(`Output dim: ${gnn.outputDim}`);\n\n// Get available graph attention types\nconst types = GraphAttentionFactory.availableTypes();  // [\"GAT\", \"GCN\", \"GraphSAGE\"]\n\n// Differentiable search\nconst config = new WasmSearchConfig(5, 0.1);  // top-5, temperature\nconst candidates = [query, ...keys];\nconst searchResults = graphDifferentiableSearch(query, candidates, config);\n\n// Hierarchical forward through multiple layers\nconst layers = [gnn, gnn2, gnn3];\nconst final = graphHierarchicalForward(query, layerEmbeddings, layers);\n```\n\n### Mamba SSM (State Space Model)\n\nSelective State Space Model for efficient sequence processing with O(n) complexity.\n\n```typescript\nimport {\n  MambaConfig,\n  MambaSSMAttention,\n  HybridMambaAttention\n} from 'ruvector-attention-unified-wasm';\n\n// Configure Mamba\nconst config = new MambaConfig(256)  // d_model = 256\n  .withStateDim(16)           // state space dimension\n  .withExpandFactor(2)        // expansion factor\n  .withConvKernelSize(4);     // conv kernel\n\nconsole.log(`Dim: ${config.dim}, State: ${config.state_dim}`);\n\n// Create Mamba SSM Attention\nconst mamba = new MambaSSMAttention(config);\nconsole.log(`Inner dim: ${mamba.innerDim}`);\n\n// Or use defaults\nconst mambaDefault = MambaSSMAttention.withDefaults(128);\n\n// Forward pass (seq_len, dim) flattened to 1D\nconst seqLen = 32;\nconst input = new Float32Array(seqLen * 256);\nconst output = mamba.forward(input, seqLen);\n\n// Get pseudo-attention scores for visualization\nconst scores = mamba.getAttentionScores(input, seqLen);\n\n// Hybrid Mamba + Local Attention\nconst hybrid = new HybridMambaAttention(config, 64);  // local window = 64\nconst hybridOut = hybrid.forward(input, seqLen);\nconsole.log(`Local window: ${hybrid.localWindow}`);\n```\n\n## Unified Selector API\n\n```typescript\nimport { UnifiedAttention } from 'ruvector-attention-unified-wasm';\n\n// Create selector for any mechanism\nconst attention = new UnifiedAttention(\"mamba\");\n\n// Query capabilities\nconsole.log(`Mechanism: ${attention.mechanism}`);      // \"mamba\"\nconsole.log(`Category: ${attention.category}`);        // \"ssm\"\nconsole.log(`Supports sequences: ${attention.supportsSequences()}`);    // true\nconsole.log(`Supports graphs: ${attention.supportsGraphs()}`);          // false\nconsole.log(`Supports hyperbolic: ${attention.supportsHyperbolic()}`);  // false\n\n// Valid mechanisms:\n// Neural: scaled_dot_product, multi_head, hyperbolic, linear, flash, local_global, moe\n// DAG: topological, causal_cone, critical_path, mincut_gated, hierarchical_lorentz, parallel_branch, temporal_btsp\n// Graph: gat, gcn, graphsage\n// SSM: mamba\n```\n\n## Utility Functions\n\n```typescript\nimport { softmax, temperatureSoftmax, cosineSimilarity, getStats } from 'ruvector-attention-unified-wasm';\n\n// Softmax normalization\nconst logits = new Float32Array([1.0, 2.0, 3.0]);\nconst probs = softmax(logits);\n\n// Temperature-scaled softmax\nconst sharper = temperatureSoftmax(logits, 0.5);   // More peaked\nconst flatter = temperatureSoftmax(logits, 2.0);  // More uniform\n\n// Cosine similarity\nconst a = new Float32Array([1, 0, 0]);\nconst b = new Float32Array([0.7, 0.7, 0]);\nconst sim = cosineSimilarity(a, b);\n\n// Library statistics\nconst stats = getStats();\nconsole.log(`Total mechanisms: ${stats.total_mechanisms}`);  // 18\nconsole.log(`Neural: ${stats.neural_count}`);                // 7\nconsole.log(`DAG: ${stats.dag_count}`);                      // 7\nconsole.log(`Graph: ${stats.graph_count}`);                  // 3\nconsole.log(`SSM: ${stats.ssm_count}`);                      // 1\n```\n\n## Tensor Compression\n\n```typescript\nimport { WasmTensorCompress } from 'ruvector-attention-unified-wasm';\n\nconst compressor = new WasmTensorCompress();\nconst embedding = new Float32Array(256);\n\n// Compress based on access frequency\nconst compressed = compressor.compress(embedding, 0.5);  // 50% access frequency\nconst decompressed = compressor.decompress(compressed);\n\n// Or specify compression level directly\nconst pq8 = compressor.compressWithLevel(embedding, \"pq8\");  // 8-bit product quantization\n\n// Compression levels: \"none\", \"half\", \"pq8\", \"pq4\", \"binary\"\nconst ratio = compressor.getCompressionRatio(0.5);\n```\n\n## Performance Benchmarks\n\n| Mechanism | Complexity | Latency (256-dim) |\n|-----------|------------|-------------------|\n| Scaled Dot-Product | O(n^2) | ~50us |\n| Multi-Head (8 heads) | O(n^2) | ~200us |\n| Linear | O(n) | ~30us |\n| Flash | O(n^2) | ~100us (memory-efficient) |\n| Mamba SSM | O(n) | ~80us |\n| Topological DAG | O(V+E) | ~40us |\n| GAT | O(E*h) | ~150us |\n\n## API Reference Summary\n\n### Neural Attention\n\n| Class | Description |\n|-------|-------------|\n| `WasmMultiHeadAttention` | Parallel attention heads |\n| `WasmHyperbolicAttention` | Hyperbolic space attention |\n| `WasmLinearAttention` | O(n) performer-style |\n| `WasmFlashAttention` | Memory-efficient blocked |\n| `WasmLocalGlobalAttention` | Sparse with global tokens |\n| `WasmMoEAttention` | Mixture of experts |\n\n### DAG Attention\n\n| Class | Description |\n|-------|-------------|\n| `WasmTopologicalAttention` | Position in topological order |\n| `WasmCausalConeAttention` | Lightcone causality |\n| `WasmCriticalPathAttention` | Critical path weighting |\n| `WasmMinCutGatedAttention` | Flow-based gating |\n| `WasmHierarchicalLorentzAttention` | Multi-scale hyperbolic |\n| `WasmParallelBranchAttention` | Parallel DAG branches |\n| `WasmTemporalBTSPAttention` | Temporal eligibility traces |\n\n### Graph Attention\n\n| Class | Description |\n|-------|-------------|\n| `WasmGNNLayer` | Multi-head graph attention |\n| `GraphAttentionFactory` | Factory for graph attention types |\n\n### State Space\n\n| Class | Description |\n|-------|-------------|\n| `MambaSSMAttention` | Selective state space model |\n| `HybridMambaAttention` | Mamba + local attention |\n| `MambaConfig` | Mamba configuration |\n\n## Use Cases\n\n- **Transformers**: Standard and efficient attention variants\n- **Query Optimization**: DAG-aware attention for SQL planners\n- **Knowledge Graphs**: Graph attention for entity reasoning\n- **Long Sequences**: O(n) attention with Mamba SSM\n- **Hierarchical Data**: Hyperbolic attention for trees\n- **Sparse Attention**: Local-global for long documents\n\n## Bundle Size\n\n- **WASM binary**: ~331KB (uncompressed)\n- **Gzip compressed**: ~120KB\n- **JavaScript glue**: ~12KB\n\n## Related Packages\n\n- [ruvector-learning-wasm](https://www.npmjs.com/package/ruvector-learning-wasm) - MicroLoRA adaptation\n- [ruvector-nervous-system-wasm](https://www.npmjs.com/package/ruvector-nervous-system-wasm) - Bio-inspired neural\n- [ruvector-economy-wasm](https://www.npmjs.com/package/ruvector-economy-wasm) - CRDT credit economy\n\n## License\n\nMIT OR Apache-2.0\n\n## Links\n\n- [GitHub Repository](https://github.com/ruvnet/ruvector)\n- [Full Documentation](https://ruv.io)\n- [Bug Reports](https://github.com/ruvnet/ruvector/issues)\n\n---\n\n**Keywords**: attention mechanism, transformer, multi-head attention, DAG attention, graph neural network, GAT, GCN, GraphSAGE, Mamba, SSM, state space model, WebAssembly, WASM, hyperbolic attention, linear attention, flash attention, query optimization, neural network, deep learning, browser ML\n","readmeFilename":"README.md"}