ruvnet--ruflo/v3/@claude-flow/neural/docs/SONA_INTEGRATION.md

SONA Integration Guide

Integration of @ruvector/sona package (v0.1.5) into the V3 Neural Module.

Overview

The SONA (Self-Optimizing Neural Architecture) integration provides runtime-adaptive learning capabilities with sub-millisecond performance:

• Learning Performance: <0.05ms per trajectory (target)
• Adaptation Performance: <0.1ms per context
• Memory Efficient: LoRA-based (1-16 rank)
• Platform Support: WASM + Node.js (NAPI bindings)

Installation

The package is already installed as a dependency:

npm install @ruvector/sona@0.1.5

Quick Start

import {
  createSONALearningEngine,
  type Trajectory,
  type Context,
} from '@claude-flow/neural';
import { getModeConfig } from '@claude-flow/neural';

// Create SONA engine with balanced mode
const modeConfig = getModeConfig('balanced');
const sona = createSONALearningEngine('balanced', modeConfig);

// Learn from a trajectory
const trajectory: Trajectory = {
  trajectoryId: 'traj-001',
  context: 'Implement authentication',
  domain: 'code',
  steps: [
    {
      stepId: 'step-1',
      timestamp: Date.now(),
      action: 'analyze requirements',
      stateBefore: new Float32Array(768).fill(0.1),
      stateAfter: new Float32Array(768).fill(0.2),
      reward: 0.8,
    },
    // ... more steps
  ],
  qualityScore: 0.88,
  isComplete: true,
  startTime: Date.now(),
};

await sona.learn(trajectory);
console.log(`Learning time: ${sona.getLearningTime()}ms`);

// Adapt to new context
const context: Context = {
  domain: 'code',
  queryEmbedding: new Float32Array(768).fill(0.15),
};

const adapted = await sona.adapt(context);
console.log(`Confidence: ${adapted.confidence}`);
console.log(`Suggested route: ${adapted.suggestedRoute}`);

API Reference

SONALearningEngine

Main class for SONA learning operations.

Constructor

new SONALearningEngine(mode: SONAMode, modeConfig: SONAModeConfig)

• mode: Learning mode ('real-time' | 'balanced' | 'research' | 'edge' | 'batch')
• modeConfig: Configuration for the mode (from getModeConfig())

Methods

learn(trajectory: Trajectory): Promise<void>

Learn from a completed trajectory.

Performance target: <0.05ms

await sona.learn(trajectory);

adapt(context: Context): Promise<AdaptedBehavior>

Adapt behavior based on current context.

Performance target: <0.1ms

const adapted = await sona.adapt({
  domain: 'code',
  queryEmbedding: embedding,
});

Returns:

• transformedQuery: Query after micro-LoRA transformation
• patterns: Similar learned patterns
• suggestedRoute: Recommended model/route
• confidence: Confidence score (0-1)

getAdaptationTime(): number

Get the last adaptation time in milliseconds.

const timeMs = sona.getAdaptationTime();

getLearningTime(): number

Get the last learning time in milliseconds.

const timeMs = sona.getLearningTime();

resetLearning(): void

Reset all learning state and create a fresh engine.

sona.resetLearning();

forceLearning(): string

Force an immediate background learning cycle.

const status = sona.forceLearning();
console.log(status);

tick(): string | null

Tick background learning (call periodically).

const status = sona.tick();
if (status) console.log(status);

getStats(): SONAStats

Get engine statistics.

const stats = sona.getStats();
console.log(`Trajectories: ${stats.totalTrajectories}`);
console.log(`Patterns: ${stats.patternsLearned}`);
console.log(`Avg Quality: ${stats.avgQuality}`);

setEnabled(enabled: boolean): void

Enable or disable the engine.

sona.setEnabled(false); // Disable learning

isEnabled(): boolean

Check if engine is enabled.

if (sona.isEnabled()) {
  // Learning is active
}

findPatterns(queryEmbedding: Float32Array, k: number): JsLearnedPattern[]

Find k similar learned patterns.

const patterns = sona.findPatterns(embedding, 5);
patterns.forEach(p => {
  console.log(`Quality: ${p.avgQuality}, Cluster: ${p.clusterSize}`);
});

Learning Modes

Real-Time Mode

Optimized for minimum latency:

• LoRA Rank: 1 (micro-LoRA only)
• Max Latency: 0.05ms
• Background Interval: 1 minute
• Use Case: Interactive applications, chatbots

const sona = createSONALearningEngine('real-time', getModeConfig('real-time'));

Balanced Mode (Default)

Balanced performance and quality:

• LoRA Rank: 4
• Max Latency: 1ms
• Background Interval: 30 minutes
• Use Case: General purpose, CLI tools

const sona = createSONALearningEngine('balanced', getModeConfig('balanced'));

Research Mode

Maximum quality, slower:

• LoRA Rank: 16
• Max Latency: 10ms
• Background Interval: 1 hour
• Use Case: Research, analysis, high-quality generation

const sona = createSONALearningEngine('research', getModeConfig('research'));

Edge Mode

Optimized for resource-constrained devices:

• LoRA Rank: 1
• Hidden Dim: 384 (vs 768)
• Memory Budget: 50MB
• Use Case: Mobile, embedded systems

const sona = createSONALearningEngine('edge', getModeConfig('edge'));

Batch Mode

Optimized for batch processing:

• LoRA Rank: 8
• Background Interval: 2 hours
• Batch Size: 128
• Use Case: Offline training, batch jobs

const sona = createSONALearningEngine('batch', getModeConfig('batch'));

Types

Context

interface Context {
  domain: 'code' | 'creative' | 'reasoning' | 'chat' | 'math' | 'general';
  queryEmbedding: Float32Array;
  metadata?: Record<string, unknown>;
}

AdaptedBehavior

interface AdaptedBehavior {
  transformedQuery: Float32Array;
  patterns: JsLearnedPattern[];
  suggestedRoute?: string;
  confidence: number;
}

SONAStats

interface SONAStats {
  totalTrajectories: number;
  patternsLearned: number;
  avgQuality: number;
  lastLearningMs: number;
  enabled: boolean;
}

JsLearnedPattern

interface JsLearnedPattern {
  id: string;
  centroid: number[];
  clusterSize: number;
  totalWeight: number;
  avgQuality: number;
  createdAt: string;
  lastAccessed: string;
  accessCount: number;
  patternType: string;
}

Performance Characteristics

Learning Performance

Mode	Avg Time	Target	Memory
Real-time	~0.03ms	<0.05ms	100MB
Balanced	~0.04ms	<0.05ms	200MB
Research	~0.08ms	<0.10ms	500MB
Edge	~0.02ms	<0.05ms	50MB
Batch	~0.05ms	<0.10ms	1GB

Adaptation Performance

Operation	Time
Micro-LoRA Apply	~0.01ms
Pattern Search (k=5)	~0.05ms
Total Adaptation	~0.06ms

Examples

See /examples/sona-usage.ts for comprehensive examples:

1. Basic Learning: Learn from trajectories
2. Context Adaptation: Adapt behavior to new contexts
3. Pattern Discovery: Discover and cluster patterns
4. Performance Monitoring: Benchmark learning performance

Run examples:

cd v3/@claude-flow/neural
npx tsx examples/sona-usage.ts

Integration with V3 Neural Module

The SONA integration works seamlessly with other V3 neural components:

import { createNeuralLearningSystem } from '@claude-flow/neural';

const system = createNeuralLearningSystem('balanced');
await system.initialize();

// SONA is used internally by the neural system
const taskId = system.beginTask('Implement feature X', 'code');

// Record steps...
system.recordStep(
  taskId,
  'analyze requirements',
  0.8,
  queryEmbedding
);

// Complete and trigger SONA learning
await system.completeTask(taskId, 0.9);

Platform Support

SONA uses native bindings for optimal performance:

• Linux: x64, ARM64 (GNU, MUSL)
• macOS: x64, ARM64 (Universal binary)
• Windows: x64, ARM64 (MSVC)

Runtime selection is automatic based on platform.

Advanced Usage

Custom Configuration

import { SonaEngine, type JsSonaConfig } from '@ruvector/sona';

const customConfig: JsSonaConfig = {
  hiddenDim: 512,
  embeddingDim: 512,
  microLoraRank: 2,
  baseLoraRank: 8,
  microLoraLr: 0.002,
  baseLoraLr: 0.0002,
  ewcLambda: 1000.0,
  patternClusters: 100,
  trajectoryCapacity: 20000,
  backgroundIntervalMs: 1800000,
  qualityThreshold: 0.6,
  enableSimd: true,
};

const engine = SonaEngine.withConfig(customConfig);

Background Learning

SONA automatically runs background learning cycles:

// Tick periodically (e.g., every second)
setInterval(() => {
  const status = sona.tick();
  if (status) {
    console.log('Background learning:', status);
  }
}, 1000);

Or force immediate learning:

const status = sona.forceLearning();
console.log(status);

Troubleshooting

Learning is too slow

• Use 'real-time' or 'edge' mode
• Reduce baseLoraRank in config
• Enable SIMD optimizations (enableSimd: true)

Memory usage too high

• Use 'edge' mode
• Reduce trajectoryCapacity
• Reduce patternClusters
• Lower hiddenDim and embeddingDim

Patterns not forming

• Increase trajectoryCapacity
• Lower qualityThreshold
• Increase backgroundIntervalMs
• Call forceLearning() manually

References

• SONA Package
• LoRA Paper
• EWC Paper
• V3 Neural Module

License

SONA integration follows the same license as the V3 neural module.