@sparkleideas/neural 3.5.2-patch.1

package/examples/sona-usage.ts

@@ -0,0 +1,318 @@
+/**
+ * Example: Using SONA Integration with V3 Neural Module
+ *
+ * Demonstrates:
+ * - Creating a SONA learning engine
+ * - Learning from trajectories
+ * - Adapting behavior based on context
+ * - Performance monitoring (<0.05ms learning target)
+ */
+
+import {
+  createSONALearningEngine,
+  type Context,
+  type Trajectory,
+  type TrajectoryStep,
+} from '../src/index.js';
+import { getModeConfig } from '../src/sona-manager.js';
+
+// =============================================================================
+// Example 1: Basic SONA Learning
+// =============================================================================
+
+async function basicLearningExample() {
+  console.log('\n=== Example 1: Basic SONA Learning ===\n');
+
+  // Create SONA engine with balanced mode
+  const modeConfig = getModeConfig('balanced');
+  const sona = createSONALearningEngine('balanced', modeConfig);
+
+  console.log(`Created SONA engine (balanced mode)`);
+  console.log(`- LoRA Rank: ${modeConfig.loraRank}`);
+  console.log(`- Learning Rate: ${modeConfig.learningRate}`);
+  console.log(`- Quality Threshold: ${modeConfig.qualityThreshold}`);
+
+  // Create a sample trajectory
+  const trajectory: Trajectory = {
+    trajectoryId: 'traj-001',
+    context: 'Implement authentication middleware',
+    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,
+      },
+      {
+        stepId: 'step-2',
+        timestamp: Date.now() + 1000,
+        action: 'implement JWT validation',
+        stateBefore: new Float32Array(768).fill(0.2),
+        stateAfter: new Float32Array(768).fill(0.3),
+        reward: 0.9,
+      },
+      {
+        stepId: 'step-3',
+        timestamp: Date.now() + 2000,
+        action: 'write tests',
+        stateBefore: new Float32Array(768).fill(0.3),
+        stateAfter: new Float32Array(768).fill(0.4),
+        reward: 0.95,
+      },
+    ],
+    qualityScore: 0.88,
+    isComplete: true,
+    startTime: Date.now(),
+    endTime: Date.now() + 3000,
+  };
+
+  // Learn from trajectory
+  await sona.learn(trajectory);
+
+  console.log(`\nLearned from trajectory:`);
+  console.log(`- Steps: ${trajectory.steps.length}`);
+  console.log(`- Quality: ${trajectory.qualityScore}`);
+  console.log(`- Learning time: ${sona.getLearningTime().toFixed(4)}ms`);
+  console.log(`- Target: <0.05ms ✓`);
+
+  // Get statistics
+  const stats = sona.getStats();
+  console.log(`\nEngine statistics:`);
+  console.log(`- Total trajectories: ${stats.totalTrajectories}`);
+  console.log(`- Patterns learned: ${stats.patternsLearned}`);
+  console.log(`- Avg quality: ${stats.avgQuality.toFixed(3)}`);
+  console.log(`- Enabled: ${stats.enabled}`);
+}
+
+// =============================================================================
+// Example 2: Context Adaptation
+// =============================================================================
+
+async function adaptationExample() {
+  console.log('\n=== Example 2: Context Adaptation ===\n');
+
+  // Create SONA engine with real-time mode (fastest)
+  const modeConfig = getModeConfig('real-time');
+  const sona = createSONALearningEngine('real-time', modeConfig);
+
+  console.log(`Created SONA engine (real-time mode)`);
+  console.log(`- Max Latency: ${modeConfig.maxLatencyMs}ms`);
+
+  // First, learn from some trajectories to build patterns
+  const trajectories: Trajectory[] = [
+    {
+      trajectoryId: 'traj-auth-1',
+      context: 'Implement JWT authentication',
+      domain: 'code',
+      steps: createMockSteps(3, 0.9),
+      qualityScore: 0.9,
+      isComplete: true,
+      startTime: Date.now(),
+    },
+    {
+      trajectoryId: 'traj-auth-2',
+      context: 'Add OAuth2 flow',
+      domain: 'code',
+      steps: createMockSteps(4, 0.85),
+      qualityScore: 0.85,
+      isComplete: true,
+      startTime: Date.now(),
+    },
+    {
+      trajectoryId: 'traj-api-1',
+      context: 'Build REST API endpoint',
+      domain: 'code',
+      steps: createMockSteps(5, 0.8),
+      qualityScore: 0.8,
+      isComplete: true,
+      startTime: Date.now(),
+    },
+  ];
+
+  // Learn from all trajectories
+  for (const traj of trajectories) {
+    await sona.learn(traj);
+  }
+
+  console.log(`\nLearned from ${trajectories.length} trajectories`);
+
+  // Now adapt to a new context
+  const context: Context = {
+    domain: 'code',
+    queryEmbedding: new Float32Array(768).fill(0.15),
+    metadata: {
+      task: 'Implement user session management',
+    },
+  };
+
+  const adapted = await sona.adapt(context);
+
+  console.log(`\nAdapted behavior:`);
+  console.log(`- Transformation applied: micro-LoRA`);
+  console.log(`- Similar patterns found: ${adapted.patterns.length}`);
+  console.log(`- Suggested route: ${adapted.suggestedRoute}`);
+  console.log(`- Confidence: ${adapted.confidence.toFixed(3)}`);
+  console.log(`- Adaptation time: ${sona.getAdaptationTime().toFixed(4)}ms`);
+
+  if (adapted.patterns.length > 0) {
+    console.log(`\nTop pattern:`);
+    console.log(`- Type: ${adapted.patterns[0].patternType}`);
+    console.log(`- Quality: ${adapted.patterns[0].avgQuality.toFixed(3)}`);
+    console.log(`- Cluster size: ${adapted.patterns[0].clusterSize}`);
+  }
+}
+
+// =============================================================================
+// Example 3: Pattern Discovery
+// =============================================================================
+
+async function patternDiscoveryExample() {
+  console.log('\n=== Example 3: Pattern Discovery ===\n');
+
+  const modeConfig = getModeConfig('research');
+  const sona = createSONALearningEngine('research', modeConfig);
+
+  console.log(`Created SONA engine (research mode)`);
+  console.log(`- Pattern Clusters: ${modeConfig.patternClusters}`);
+
+  // Learn from multiple high-quality trajectories
+  const domains: Array<'code' | 'math' | 'reasoning'> = ['code', 'math', 'reasoning'];
+
+  for (let i = 0; i < 10; i++) {
+    const domain = domains[i % domains.length];
+    const trajectory: Trajectory = {
+      trajectoryId: `traj-${domain}-${i}`,
+      context: `${domain} task ${i}`,
+      domain,
+      steps: createMockSteps(3 + (i % 3), 0.7 + Math.random() * 0.3),
+      qualityScore: 0.7 + Math.random() * 0.3,
+      isComplete: true,
+      startTime: Date.now(),
+    };
+
+    await sona.learn(trajectory);
+  }
+
+  console.log(`\nLearned from 10 trajectories across ${domains.length} domains`);
+
+  // Force a learning cycle to cluster patterns
+  const learnStatus = sona.forceLearning();
+  console.log(`\nForced learning cycle: ${learnStatus}`);
+
+  // Find patterns for each domain
+  for (const domain of domains) {
+    const queryEmbedding = new Float32Array(768).fill(0.1 + Math.random() * 0.1);
+    const patterns = sona.findPatterns(queryEmbedding, 3);
+
+    console.log(`\n${domain.toUpperCase()} patterns:`);
+    patterns.forEach((pattern, idx) => {
+      console.log(`  ${idx + 1}. Quality: ${pattern.avgQuality.toFixed(3)}, Cluster: ${pattern.clusterSize} trajectories`);
+    });
+  }
+
+  const stats = sona.getStats();
+  console.log(`\nFinal statistics:`);
+  console.log(`- Total trajectories: ${stats.totalTrajectories}`);
+  console.log(`- Patterns learned: ${stats.patternsLearned}`);
+  console.log(`- Avg quality: ${stats.avgQuality.toFixed(3)}`);
+}
+
+// =============================================================================
+// Example 4: Performance Monitoring
+// =============================================================================
+
+async function performanceMonitoringExample() {
+  console.log('\n=== Example 4: Performance Monitoring ===\n');
+
+  const modes: Array<'real-time' | 'balanced' | 'edge'> = ['real-time', 'balanced', 'edge'];
+
+  for (const mode of modes) {
+    const modeConfig = getModeConfig(mode);
+    const sona = createSONALearningEngine(mode, modeConfig);
+
+    // Benchmark learning
+    const trajectory: Trajectory = {
+      trajectoryId: `perf-${mode}`,
+      context: 'Performance test',
+      domain: 'general',
+      steps: createMockSteps(5, 0.8),
+      qualityScore: 0.8,
+      isComplete: true,
+      startTime: Date.now(),
+    };
+
+    const iterations = 100;
+    const times: number[] = [];
+
+    for (let i = 0; i < iterations; i++) {
+      await sona.learn(trajectory);
+      times.push(sona.getLearningTime());
+    }
+
+    const avgTime = times.reduce((sum, t) => sum + t, 0) / times.length;
+    const minTime = Math.min(...times);
+    const maxTime = Math.max(...times);
+    const meetsTarget = avgTime < 0.05;
+
+    console.log(`\n${mode.toUpperCase()} mode (${iterations} iterations):`);
+    console.log(`- Avg learning time: ${avgTime.toFixed(4)}ms ${meetsTarget ? '✓' : '✗'}`);
+    console.log(`- Min time: ${minTime.toFixed(4)}ms`);
+    console.log(`- Max time: ${maxTime.toFixed(4)}ms`);
+    console.log(`- Target: <0.05ms`);
+  }
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+function createMockSteps(count: number, avgReward: number): TrajectoryStep[] {
+  const steps: TrajectoryStep[] = [];
+  const baseTime = Date.now();
+
+  for (let i = 0; i < count; i++) {
+    steps.push({
+      stepId: `step-${i}`,
+      timestamp: baseTime + i * 1000,
+      action: `action-${i}`,
+      stateBefore: new Float32Array(768).fill(0.1 + i * 0.05),
+      stateAfter: new Float32Array(768).fill(0.15 + i * 0.05),
+      reward: avgReward + (Math.random() - 0.5) * 0.1,
+    });
+  }
+
+  return steps;
+}
+
+// =============================================================================
+// Run All Examples
+// =============================================================================
+
+async function main() {
+  console.log('\n╔═══════════════════════════════════════════════════════════╗');
+  console.log('║   SONA Integration Examples - V3 Neural Module           ║');
+  console.log('║   @ruvector/sona v0.1.5                                   ║');
+  console.log('╚═══════════════════════════════════════════════════════════╝');
+
+  try {
+    await basicLearningExample();
+    await adaptationExample();
+    await patternDiscoveryExample();
+    await performanceMonitoringExample();
+
+    console.log('\n✓ All examples completed successfully!\n');
+  } catch (error) {
+    console.error('\n✗ Error running examples:', error);
+    process.exit(1);
+  }
+}
+
+// Run if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}
+
+export { main };

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@sparkleideas/neural",
+  "version": "3.5.2-patch.1",
+  "type": "module",
+  "description": "Neural module - SONA learning integration, neural modes",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@ruvector/sona": "latest",
+    "@sparkleideas/memory": "^3.0.0-alpha.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "v3alpha"
+  }
+}

package/src/algorithms/a2c.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Advantage Actor-Critic (A2C)
+ *
+ * Implements synchronous A2C algorithm with:
+ * - Shared actor-critic network
+ * - N-step returns
+ * - Entropy regularization
+ * - Advantage normalization
+ *
+ * Performance Target: <10ms per update step
+ */
+import type { RLConfig, Trajectory } from '../types.js';
+/**
+ * A2C configuration
+ */
+export interface A2CConfig extends RLConfig {
+    algorithm: 'a2c';
+    nSteps: number;
+    useGAE: boolean;
+    gaeLambda: number;
+}
+/**
+ * Default A2C configuration
+ */
+export declare const DEFAULT_A2C_CONFIG: A2CConfig;
+/**
+ * A2C Algorithm Implementation
+ */
+export declare class A2CAlgorithm {
+    private config;
+    private sharedWeights;
+    private policyHead;
+    private valueHead;
+    private sharedMomentum;
+    private policyMomentum;
+    private valueMomentum;
+    private buffer;
+    private inputDim;
+    private hiddenDim;
+    private numActions;
+    private updateCount;
+    private avgPolicyLoss;
+    private avgValueLoss;
+    private avgEntropy;
+    constructor(config?: Partial<A2CConfig>);
+    /**
+     * Add experience from trajectory
+     */
+    addExperience(trajectory: Trajectory): void;
+    /**
+     * Perform A2C update
+     * Target: <10ms
+     */
+    update(): {
+        policyLoss: number;
+        valueLoss: number;
+        entropy: number;
+    };
+    /**
+     * Get action from policy
+     */
+    getAction(state: Float32Array): {
+        action: number;
+        value: number;
+    };
+    /**
+     * Get statistics
+     */
+    getStats(): Record<string, number>;
+    private evaluate;
+    private forward;
+    private forwardWithHidden;
+    private computeReturns;
+    private computeAdvantages;
+    private computeGAE;
+    private accumulateGradients;
+    private applyGradients;
+    private softmax;
+    private sampleAction;
+    private hashAction;
+}
+/**
+ * Factory function
+ */
+export declare function createA2C(config?: Partial<A2CConfig>): A2CAlgorithm;
+//# sourceMappingURL=a2c.d.ts.map

package/src/algorithms/a2c.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2c.d.ts","sourceRoot":"","sources":["a2c.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,QAAQ,EACR,UAAU,EAEX,MAAM,aAAa,CAAC;AAErB;;GAEG;AACH,MAAM,WAAW,SAAU,SAAQ,QAAQ;IACzC,SAAS,EAAE,KAAK,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAYhC,CAAC;AAcF;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAY;IAG1B,OAAO,CAAC,aAAa,CAAe;IACpC,OAAO,CAAC,UAAU,CAAe;IACjC,OAAO,CAAC,SAAS,CAAe;IAGhC,OAAO,CAAC,cAAc,CAAe;IACrC,OAAO,CAAC,cAAc,CAAe;IACrC,OAAO,CAAC,aAAa,CAAe;IAGpC,OAAO,CAAC,MAAM,CAAuB;IAGrC,OAAO,CAAC,QAAQ,CAAO;IACvB,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,UAAU,CAAK;IAGvB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,UAAU,CAAK;gBAEX,MAAM,GAAE,OAAO,CAAC,SAAS,CAAM;IAyB3C;;OAEG;IACH,aAAa,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI;IAgB3C;;;OAGG;IACH,MAAM,IAAI;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAiFpE;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;IAMjE;;OAEG;IACH,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAclC,OAAO,CAAC,QAAQ;IAWhB,OAAO,CAAC,OAAO;IA+Bf,OAAO,CAAC,iBAAiB;IA4BzB,OAAO,CAAC,cAAc;IAiBtB,OAAO,CAAC,iBAAiB;IAoBzB,OAAO,CAAC,UAAU;IAsBlB,OAAO,CAAC,mBAAmB;IAkC3B,OAAO,CAAC,cAAc;IA+BtB,OAAO,CAAC,OAAO;IAiBf,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,UAAU;CAOnB;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,YAAY,CAEnE"}