{"_id":"@aigentic/sona","_rev":"3-b81afb25de90d007d3b1900aca371001","name":"@aigentic/sona","dist-tags":{"latest":"0.1.7"},"versions":{"0.1.6":{"name":"@aigentic/sona","version":"0.1.6","keywords":["sona","neural-network","adaptive-learning","lora","low-rank-adaptation","ewc","elastic-weight-consolidation","reasoningbank","llm","llm-router","machine-learning","ai","deep-learning","continual-learning","napi","rust","ruvector"],"author":{"name":"rUv Team","email":"team@ruv.io"},"license":"MIT OR Apache-2.0","_id":"@aigentic/sona@0.1.6","maintainers":[{"name":"aigentic","email":"engineering@aigentic.net"}],"homepage":"https://github.com/ruvnet/ruvector/tree/main/crates/sona","bugs":{"url":"https://github.com/ruvnet/ruvector/issues"},"dist":{"shasum":"34a67f656b8c39c2f62de8c2c03b9ad91ed0b05e","tarball":"https://registry.npmjs.org/@aigentic/sona/-/sona-0.1.6.tgz","fileCount":2,"integrity":"sha512-scaWpJxASMEqdIQ9PeDfKryzjWp0oIDkQ8iMCLbo5LDvnu9O5XdWnnXkAHa42VfwN04o2F5YzhBQ4nDHzWtW0Q==","signatures":[{"sig":"MEUCIQC+ceVeyYr+FPK1aUbTzvlS/DXO71i7Lvon/7fIsaMlAQIgNY+CinC7LPtfgQMof00e8Cto6vXFfWPQpGJq6fYISI4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":11944},"main":"index.js","napi":{"targets":["x86_64-unknown-linux-gnu","x86_64-unknown-linux-musl","aarch64-unknown-linux-gnu","x86_64-apple-darwin","aarch64-apple-darwin","x86_64-pc-windows-msvc","aarch64-pc-windows-msvc"],"binaryName":"sona"},"types":"index.d.ts","engines":{"node":">= 16"},"gitHead":"06426cbc6e70f09762e996a98517b0b1fd1c7c4e","scripts":{"test":"node --test","build":"napi build --platform --release -p ruvector-sona --manifest-path ../../../crates/sona/Cargo.toml -F napi","version":"napi version","artifacts":"napi artifacts","universal":"napi universal","build:debug":"napi build --platform -p ruvector-sona --manifest-path ../../../crates/sona/Cargo.toml -F napi"},"_npmUser":{"name":"aigentic","email":"engineering@aigentic.net"},"repository":{"url":"git+https://github.com/ruvnet/ruvector.git","type":"git","directory":"npm/packages/sona"},"_npmVersion":"11.12.0","description":"Self-Optimizing Neural Architecture (SONA) - Runtime-adaptive learning with LoRA, EWC++, and ReasoningBank for LLM routers and AI systems. Sub-millisecond learning overhead, WASM and Node.js support.","directories":{},"_nodeVersion":"22.22.1","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"@napi-rs/cli":"^2.18.0"},"optionalDependencies":{"@aigentic/sona-darwin-x64":"0.1.4","@aigentic/sona-darwin-arm64":"0.1.4","@aigentic/sona-linux-x64-gnu":"0.1.4","@aigentic/sona-linux-x64-musl":"0.1.4","@aigentic/sona-win32-x64-msvc":"0.1.4","@aigentic/sona-linux-arm64-gnu":"0.1.4","@aigentic/sona-win32-arm64-msvc":"0.1.4"},"_npmOperationalInternal":{"tmp":"tmp/sona_0.1.6_1779091192232_0.2940515966296564","host":"s3://npm-registry-packages-npm-production"}},"0.1.7":{"name":"@aigentic/sona","version":"0.1.7","keywords":["sona","neural-network","adaptive-learning","lora","low-rank-adaptation","ewc","elastic-weight-consolidation","reasoningbank","llm","llm-router","machine-learning","ai","deep-learning","continual-learning","napi","rust","ruvector"],"author":{"name":"rUv Team","email":"team@ruv.io"},"license":"MIT OR Apache-2.0","_id":"@aigentic/sona@0.1.7","maintainers":[{"name":"aigentic","email":"engineering@aigentic.net"}],"homepage":"https://github.com/ruvnet/ruvector/tree/main/crates/sona","bugs":{"url":"https://github.com/ruvnet/ruvector/issues"},"dist":{"shasum":"b0258d2caa9e146f02bf5df5cb7d76ae33e07c9f","tarball":"https://registry.npmjs.org/@aigentic/sona/-/sona-0.1.7.tgz","fileCount":2,"integrity":"sha512-sYAOvGMoJHpDjRuqi4hDE61gkJPGJGvTuRxXQE3eJZwnOgbWubcNLp81nsseuI86cjKl0hGctWsN+OdWm40E4Q==","signatures":[{"sig":"MEUCIBJDTz2aNvQz8VL/ZFiOyvACyUZa2U2kwUXWhC2Lx0dFAiEAoL38248qzRzbsYAwCECDNOhpyyL/Udrz0X4a1DQ2CvI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":11945},"main":"index.js","napi":{"targets":["x86_64-unknown-linux-gnu","x86_64-unknown-linux-musl","aarch64-unknown-linux-gnu","x86_64-apple-darwin","aarch64-apple-darwin","x86_64-pc-windows-msvc","aarch64-pc-windows-msvc"],"binaryName":"sona"},"types":"index.d.ts","engines":{"node":">= 16"},"gitHead":"06426cbc6e70f09762e996a98517b0b1fd1c7c4e","scripts":{"test":"node --test","build":"napi build --platform --release -p ruvector-sona --manifest-path ../../../crates/sona/Cargo.toml -F napi","version":"napi version","artifacts":"napi artifacts","universal":"napi universal","build:debug":"napi build --platform -p ruvector-sona --manifest-path ../../../crates/sona/Cargo.toml -F napi"},"_npmUser":{"name":"aigentic","email":"engineering@aigentic.net"},"repository":{"url":"git+https://github.com/ruvnet/ruvector.git","type":"git","directory":"npm/packages/sona"},"_npmVersion":"11.12.0","description":"Self-Optimizing Neural Architecture (SONA) - Runtime-adaptive learning with LoRA, EWC++, and ReasoningBank for LLM routers and AI systems. Sub-millisecond learning overhead, WASM and Node.js support.","directories":{},"_nodeVersion":"22.22.1","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"@napi-rs/cli":"^2.18.0"},"optionalDependencies":{"@aigentic/sona-darwin-x64":"0.1.4","@aigentic/sona-darwin-arm64":"0.1.4","@aigentic/sona-linux-x64-gnu":"0.1.4","@aigentic/sona-linux-x64-musl":"0.1.4","@aigentic/sona-win32-x64-msvc":"0.1.4","@aigentic/sona-linux-arm64-gnu":"0.1.4","@aigentic/sona-win32-arm64-msvc":"0.1.4"},"_npmOperationalInternal":{"tmp":"tmp/sona_0.1.7_1779093061552_0.347813327303373","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-05-18T07:59:52.144Z","modified":"2026-09-13T15:30:37.796Z","0.1.6":"2026-05-18T07:59:52.377Z","0.1.7":"2026-05-18T08:31:01.671Z"},"bugs":{"url":"https://github.com/ruvnet/ruvector/issues"},"author":{"name":"rUv Team","email":"team@ruv.io"},"license":"MIT OR Apache-2.0","homepage":"https://github.com/ruvnet/ruvector/tree/main/crates/sona","keywords":["sona","neural-network","adaptive-learning","lora","low-rank-adaptation","ewc","elastic-weight-consolidation","reasoningbank","llm","llm-router","machine-learning","ai","deep-learning","continual-learning","napi","rust","ruvector"],"repository":{"url":"git+https://github.com/ruvnet/ruvector.git","type":"git","directory":"npm/packages/sona"},"description":"Self-Optimizing Neural Architecture (SONA) - Runtime-adaptive learning with LoRA, EWC++, and ReasoningBank for LLM routers and AI systems. Sub-millisecond learning overhead, WASM and Node.js support.","maintainers":[{"email":"engineering@aigentic.net","name":"aiggy"}],"readme":"# @ruvector/sona\n\n**Self-Optimizing Neural Architecture (SONA)** - Node.js bindings for adaptive learning with ReasoningBank.\n\nSONA is a cutting-edge adaptive learning system that combines:\n- **Micro-LoRA** (rank 1-2): Ultra-fast inference-time adaptation\n- **Base LoRA** (rank 8+): Deeper background learning\n- **EWC++**: Catastrophic forgetting prevention\n- **ReasoningBank**: Pattern extraction and storage\n- **Dual Learning Loops**: Instant (<1ms) and background (periodic) learning\n\n## Features\n\n- 🚀 **Instant Adaptation**: Sub-millisecond learning updates during inference\n- 🧠 **Pattern Recognition**: Automatic extraction and clustering of learned patterns\n- 🔄 **Dual Learning Loops**: Balance speed and depth with instant and background learning\n- 💾 **Memory Preservation**: EWC++ prevents catastrophic forgetting\n- ⚡ **High Performance**: Native Rust implementation with SIMD optimizations\n- 🎯 **Production Ready**: Used in large-scale LLM deployments\n\n## Installation\n\n```bash\nnpm install @ruvector/sona\n```\n\n## Quick Start\n\n```typescript\nimport { SonaEngine } from '@ruvector/sona';\n\n// Create engine with hidden dimension\nconst engine = new SonaEngine(512);\n\n// Or with custom configuration\nconst engine = SonaEngine.withConfig({\n  hiddenDim: 512,\n  microLoraRank: 2,\n  baseLoraRank: 16,\n  microLoraLr: 0.002,\n  qualityThreshold: 0.7,\n});\n\n// Start a trajectory\nconst builder = engine.beginTrajectory(queryEmbedding);\n\n// Record inference steps\nbuilder.addStep(activations, attentionWeights, 0.8);\nbuilder.addStep(activations2, attentionWeights2, 0.9);\n\n// Complete trajectory\nengine.endTrajectory(builder, 0.85); // quality score\n\n// Apply learned transformations\nconst output = engine.applyMicroLora(input);\n\n// Force learning cycle\nconst result = engine.forceLearn();\nconsole.log(result);\n\n// Find similar patterns\nconst patterns = engine.findPatterns(queryEmbedding, 5);\npatterns.forEach(p => {\n  console.log(`Pattern ${p.id}: quality=${p.avgQuality}, size=${p.clusterSize}`);\n});\n```\n\n## API Reference\n\n### SonaEngine\n\nMain class for adaptive learning.\n\n#### Constructor\n\n```typescript\nnew SonaEngine(hiddenDim: number)\n```\n\nCreate a new SONA engine with default configuration.\n\n**Parameters:**\n- `hiddenDim`: Hidden dimension size (e.g., 256, 512, 1024)\n\n#### Static Methods\n\n##### `SonaEngine.withConfig(config: SonaConfig): SonaEngine`\n\nCreate engine with custom configuration.\n\n**Configuration Options:**\n```typescript\ninterface SonaConfig {\n  hiddenDim: number;              // Required: Hidden dimension\n  embeddingDim?: number;          // Default: hiddenDim\n  microLoraRank?: number;         // Default: 1 (range: 1-2)\n  baseLoraRank?: number;          // Default: 8\n  microLoraLr?: number;           // Default: 0.001\n  baseLoraLr?: number;            // Default: 0.0001\n  ewcLambda?: number;             // Default: 1000.0\n  patternClusters?: number;       // Default: 50\n  trajectoryCapacity?: number;    // Default: 10000\n  backgroundIntervalMs?: number;  // Default: 3600000 (1 hour)\n  qualityThreshold?: number;      // Default: 0.5\n  enableSimd?: boolean;           // Default: true\n}\n```\n\n#### Instance Methods\n\n##### `beginTrajectory(queryEmbedding: Float64Array | number[]): TrajectoryBuilder`\n\nStart recording a new inference trajectory.\n\n##### `endTrajectory(builder: TrajectoryBuilder, quality: number): void`\n\nComplete and submit trajectory for learning.\n\n**Parameters:**\n- `builder`: TrajectoryBuilder instance\n- `quality`: Final quality score [0.0, 1.0]\n\n##### `applyMicroLora(input: Float64Array | number[]): Float64Array`\n\nApply micro-LoRA transformation (instant learning).\n\n##### `applyBaseLora(layerIdx: number, input: Float64Array | number[]): Float64Array`\n\nApply base-LoRA transformation to specific layer.\n\n##### `tick(): string | null`\n\nRun background learning cycle if due. Returns status message if executed.\n\n##### `forceLearn(): string`\n\nForce immediate background learning cycle.\n\n##### `flush(): void`\n\nFlush instant loop updates.\n\n##### `findPatterns(queryEmbedding: Float64Array | number[], k: number): LearnedPattern[]`\n\nFind k most similar learned patterns.\n\n##### `getStats(): string`\n\nGet engine statistics as JSON string.\n\n##### `setEnabled(enabled: boolean): void`\n\nEnable or disable learning.\n\n##### `isEnabled(): boolean`\n\nCheck if engine is enabled.\n\n### TrajectoryBuilder\n\nBuilder for recording inference trajectories.\n\n#### Methods\n\n##### `addStep(activations: Float64Array | number[], attentionWeights: Float64Array | number[], reward: number): void`\n\nAdd a step to the trajectory.\n\n**Parameters:**\n- `activations`: Layer activations\n- `attentionWeights`: Attention weights\n- `reward`: Reward signal for this step\n\n##### `setRoute(route: string): void`\n\nSet model route identifier.\n\n##### `addContext(contextId: string): void`\n\nAdd context ID to trajectory.\n\n### LearnedPattern\n\nRepresents a learned pattern from trajectory clustering.\n\n```typescript\ninterface LearnedPattern {\n  id: string;\n  centroid: Float64Array;\n  clusterSize: number;\n  totalWeight: number;\n  avgQuality: number;\n  createdAt: string;\n  lastAccessed: string;\n  accessCount: number;\n  patternType: PatternType;\n}\n```\n\n### PatternType\n\nPattern classification enumeration.\n\n```typescript\nenum PatternType {\n  General = 'General',\n  Reasoning = 'Reasoning',\n  Factual = 'Factual',\n  Creative = 'Creative',\n  CodeGen = 'CodeGen',\n  Conversational = 'Conversational',\n}\n```\n\n## Advanced Usage\n\n### LLM Integration Example\n\n```typescript\nimport { SonaEngine } from '@ruvector/sona';\n\nclass AdaptiveLLM {\n  private sona: SonaEngine;\n\n  constructor() {\n    this.sona = SonaEngine.withConfig({\n      hiddenDim: 4096,\n      microLoraRank: 2,\n      baseLoraRank: 16,\n      microLoraLr: 0.002,\n      qualityThreshold: 0.7,\n      backgroundIntervalMs: 1800000, // 30 minutes\n    });\n  }\n\n  async generate(prompt: string): Promise<string> {\n    const embedding = await this.embed(prompt);\n    const builder = this.sona.beginTrajectory(embedding);\n\n    // Generate with SONA-enhanced layers\n    const output = await this.runInference(builder);\n\n    // Calculate quality score\n    const quality = this.assessQuality(output);\n\n    // Submit trajectory for learning\n    this.sona.endTrajectory(builder, quality);\n\n    // Periodic background learning\n    const status = this.sona.tick();\n    if (status) {\n      console.log('Background learning:', status);\n    }\n\n    return output;\n  }\n\n  private async runInference(builder: TrajectoryBuilder): Promise<string> {\n    let output = '';\n\n    for (const layer of this.layers) {\n      // Get layer activations\n      const activations = layer.forward(/* ... */);\n      const attention = layer.getAttention();\n\n      // Apply micro-LoRA enhancement\n      const enhanced = this.sona.applyMicroLora(activations);\n\n      // Record step\n      const reward = this.calculateReward(enhanced);\n      builder.addStep(activations, attention, reward);\n\n      // Continue generation with enhanced activations\n      output += this.decode(enhanced);\n    }\n\n    return output;\n  }\n}\n```\n\n### Pattern-Based Routing\n\n```typescript\n// Find similar patterns for routing decisions\nconst patterns = engine.findPatterns(queryEmbedding, 3);\n\nif (patterns.length > 0) {\n  const topPattern = patterns[0];\n\n  if (topPattern.patternType === 'CodeGen' && topPattern.avgQuality > 0.8) {\n    // Route to specialized code generation model\n    await routeToCodeModel(query);\n  } else if (topPattern.patternType === 'Reasoning') {\n    // Use chain-of-thought prompting\n    await useCoTPrompting(query);\n  }\n}\n```\n\n### Performance Monitoring\n\n```typescript\n// Get statistics\nconst stats = JSON.parse(engine.getStats());\nconsole.log(`\n  Trajectories buffered: ${stats.trajectories_buffered}\n  Patterns learned: ${stats.patterns_learned}\n  Micro-LoRA updates: ${stats.micro_updates}\n  Background cycles: ${stats.background_cycles}\n`);\n\n// Force learning when needed\nif (stats.trajectories_buffered > 100) {\n  const result = engine.forceLearn();\n  console.log('Forced learning:', result);\n}\n```\n\n## Performance Characteristics\n\n- **Micro-LoRA Application**: <1ms per forward pass\n- **Trajectory Recording**: ~10μs per step\n- **Background Learning**: Depends on buffer size (typically 100-500ms for 1000 trajectories)\n- **Pattern Search**: O(k * n) where k = number of results, n = total patterns\n- **Memory Usage**: ~50MB base + ~1KB per trajectory + ~10KB per pattern\n\n## Architecture\n\nSONA implements a dual-loop learning architecture:\n\n1. **Instant Loop** (<1ms):\n   - Accumulates micro-LoRA gradients during inference\n   - Updates on every trajectory\n   - Rank-1 or rank-2 LoRA for minimal overhead\n\n2. **Background Loop** (periodic):\n   - Extracts patterns via k-means clustering\n   - Updates base LoRA weights\n   - Applies EWC++ for stability\n   - Prunes low-quality patterns\n\n## Requirements\n\n- Node.js >= 16\n- Native bindings for your platform (automatically installed)\n\n## Supported Platforms\n\n- Linux (x64, ARM64, ARM)\n- macOS (x64, ARM64, Universal)\n- Windows (x64, ARM64)\n- FreeBSD (x64)\n\n## License\n\nMIT OR Apache-2.0\n\n## Links\n\n- [GitHub Repository](https://github.com/ruvnet/ruvector)\n- [Documentation](https://github.com/ruvnet/ruvector/tree/main/crates/sona)\n- [rUvector Project](https://github.com/ruvnet/ruvector)\n\n## Contributing\n\nContributions are welcome! Please see the main rUvector repository for contribution guidelines.\n\n## Acknowledgments\n\nSONA is part of the rUvector project, building on research in:\n- Low-Rank Adaptation (LoRA)\n- Elastic Weight Consolidation (EWC)\n- Continual Learning\n- Neural Architecture Search\n\n---\n\nBuilt with ❤️ by the rUv Team\n","readmeFilename":"README.md"}