@sparkleideas/neural 3.5.2-patch.1

package/src/application/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Neural Application Layer - Public Exports
+ *
+ * @module v3/neural/application
+ */
+
+export {
+  NeuralApplicationService,
+  type TrainingSessionResult,
+  type NeuralMetrics,
+} from './services/neural-application-service.js';

package/src/application/services/neural-application-service.ts

@@ -0,0 +1,217 @@
+/**
+ * Neural Application Service - Application Layer
+ *
+ * Orchestrates neural learning operations.
+ *
+ * @module v3/neural/application/services
+ */
+
+import { Pattern, PatternType } from '../../domain/entities/pattern.js';
+import { LearningDomainService, Trajectory, LearningResult, RouteRecommendation } from '../../domain/services/learning-service.js';
+
+/**
+ * Training session result
+ */
+export interface TrainingSessionResult {
+  trajectoriesProcessed: number;
+  patternsExtracted: number;
+  patternsUpdated: number;
+  averageConfidenceChange: number;
+  duration: number;
+}
+
+/**
+ * Neural metrics
+ */
+export interface NeuralMetrics {
+  totalPatterns: number;
+  patternsByType: Record<PatternType, number>;
+  averageConfidence: number;
+  reliablePatterns: number;
+  totalSuccesses: number;
+  totalFailures: number;
+}
+
+/**
+ * Neural Application Service
+ */
+export class NeuralApplicationService {
+  private readonly learningService: LearningDomainService;
+
+  constructor() {
+    this.learningService = new LearningDomainService();
+  }
+
+  // ============================================================================
+  // Learning Operations
+  // ============================================================================
+
+  /**
+   * Learn from a single trajectory
+   */
+  learn(trajectory: Trajectory): LearningResult {
+    return this.learningService.updatePatterns(trajectory);
+  }
+
+  /**
+   * Train on batch of trajectories
+   */
+  train(trajectories: Trajectory[]): TrainingSessionResult {
+    const start = Date.now();
+    let totalPatternsExtracted = 0;
+    let totalPatternsUpdated = 0;
+    let totalConfidenceChange = 0;
+
+    for (const trajectory of trajectories) {
+      const result = this.learningService.updatePatterns(trajectory);
+      totalPatternsExtracted += result.patternsExtracted;
+      totalPatternsUpdated += result.patternsUpdated;
+      totalConfidenceChange += result.confidenceChange;
+    }
+
+    return {
+      trajectoriesProcessed: trajectories.length,
+      patternsExtracted: totalPatternsExtracted,
+      patternsUpdated: totalPatternsUpdated,
+      averageConfidenceChange: trajectories.length > 0 ? totalConfidenceChange / trajectories.length : 0,
+      duration: Date.now() - start,
+    };
+  }
+
+  // ============================================================================
+  // Routing
+  // ============================================================================
+
+  /**
+   * Get route recommendation for task
+   */
+  route(taskDescription: string): RouteRecommendation {
+    return this.learningService.getRouteRecommendation(taskDescription);
+  }
+
+  /**
+   * Explain routing decision
+   */
+  explain(taskDescription: string): {
+    recommendation: RouteRecommendation;
+    matchingPatterns: Pattern[];
+    reasoning: string[];
+  } {
+    const recommendation = this.route(taskDescription);
+    const matchingPatterns = this.learningService
+      .getPatternsByType('task-routing')
+      .filter((p) => p.matches(taskDescription));
+
+    const reasoning: string[] = [];
+    if (matchingPatterns.length > 0) {
+      reasoning.push(`Found ${matchingPatterns.length} matching patterns`);
+      for (const p of matchingPatterns.slice(0, 3)) {
+        reasoning.push(`- Pattern "${p.name}": ${p.successRate.toFixed(2)} success rate, ${p.confidence.toFixed(2)} confidence`);
+      }
+    } else {
+      reasoning.push('No matching patterns found, using keyword-based routing');
+    }
+    reasoning.push(`Recommended: ${recommendation.agentRole} (${(recommendation.confidence * 100).toFixed(0)}% confidence)`);
+
+    return {
+      recommendation,
+      matchingPatterns,
+      reasoning,
+    };
+  }
+
+  // ============================================================================
+  // Pattern Management
+  // ============================================================================
+
+  /**
+   * Get all patterns
+   */
+  getPatterns(): Pattern[] {
+    return this.learningService.getPatterns();
+  }
+
+  /**
+   * Get patterns by type
+   */
+  getPatternsByType(type: PatternType): Pattern[] {
+    return this.learningService.getPatternsByType(type);
+  }
+
+  /**
+   * Add custom pattern
+   */
+  addPattern(props: {
+    type: PatternType;
+    name: string;
+    description: string;
+    condition: string;
+    action: string;
+    confidence?: number;
+  }): Pattern {
+    const pattern = Pattern.create({
+      type: props.type,
+      name: props.name,
+      description: props.description,
+      condition: props.condition,
+      action: props.action,
+      confidence: props.confidence ?? 0.5,
+    });
+    this.learningService.addPattern(pattern);
+    return pattern;
+  }
+
+  /**
+   * Remove pattern
+   */
+  removePattern(id: string): boolean {
+    return this.learningService.removePattern(id);
+  }
+
+  /**
+   * Consolidate patterns
+   */
+  consolidate(minConfidence?: number): { merged: number; pruned: number } {
+    return this.learningService.consolidate(minConfidence);
+  }
+
+  // ============================================================================
+  // Metrics
+  // ============================================================================
+
+  /**
+   * Get neural metrics
+   */
+  getMetrics(): NeuralMetrics {
+    const patterns = this.learningService.getPatterns();
+
+    const patternsByType: Record<PatternType, number> = {
+      'task-routing': 0,
+      'error-recovery': 0,
+      optimization: 0,
+      learning: 0,
+    };
+
+    let totalConfidence = 0;
+    let reliablePatterns = 0;
+    let totalSuccesses = 0;
+    let totalFailures = 0;
+
+    for (const pattern of patterns) {
+      patternsByType[pattern.type]++;
+      totalConfidence += pattern.confidence;
+      if (pattern.isReliable()) reliablePatterns++;
+      totalSuccesses += pattern.successCount;
+      totalFailures += pattern.failureCount;
+    }
+
+    return {
+      totalPatterns: patterns.length,
+      patternsByType,
+      averageConfidence: patterns.length > 0 ? totalConfidence / patterns.length : 0,
+      reliablePatterns,
+      totalSuccesses,
+      totalFailures,
+    };
+  }
+}

package/src/domain/entities/pattern.ts

@@ -0,0 +1,169 @@
+/**
+ * Pattern Entity - Domain Layer
+ *
+ * Represents a learned pattern for intelligent routing and optimization.
+ *
+ * @module v3/neural/domain/entities
+ */
+
+import { randomUUID } from 'crypto';
+
+/**
+ * Pattern type
+ */
+export type PatternType = 'task-routing' | 'error-recovery' | 'optimization' | 'learning';
+
+/**
+ * Pattern properties
+ */
+export interface PatternProps {
+  id?: string;
+  type: PatternType;
+  name: string;
+  description: string;
+  condition: string;
+  action: string;
+  confidence: number;
+  successCount?: number;
+  failureCount?: number;
+  metadata?: Record<string, unknown>;
+  createdAt?: Date;
+  updatedAt?: Date;
+  lastMatchedAt?: Date;
+}
+
+/**
+ * Pattern Entity
+ */
+export class Pattern {
+  private _id: string;
+  private _type: PatternType;
+  private _name: string;
+  private _description: string;
+  private _condition: string;
+  private _action: string;
+  private _confidence: number;
+  private _successCount: number;
+  private _failureCount: number;
+  private _metadata: Record<string, unknown>;
+  private _createdAt: Date;
+  private _updatedAt: Date;
+  private _lastMatchedAt?: Date;
+
+  private constructor(props: PatternProps) {
+    const now = new Date();
+    this._id = props.id ?? randomUUID();
+    this._type = props.type;
+    this._name = props.name;
+    this._description = props.description;
+    this._condition = props.condition;
+    this._action = props.action;
+    this._confidence = props.confidence;
+    this._successCount = props.successCount ?? 0;
+    this._failureCount = props.failureCount ?? 0;
+    this._metadata = props.metadata ?? {};
+    this._createdAt = props.createdAt ?? now;
+    this._updatedAt = props.updatedAt ?? now;
+    this._lastMatchedAt = props.lastMatchedAt;
+  }
+
+  static create(props: PatternProps): Pattern {
+    return new Pattern(props);
+  }
+
+  static fromPersistence(props: PatternProps): Pattern {
+    return new Pattern(props);
+  }
+
+  get id(): string { return this._id; }
+  get type(): PatternType { return this._type; }
+  get name(): string { return this._name; }
+  get description(): string { return this._description; }
+  get condition(): string { return this._condition; }
+  get action(): string { return this._action; }
+  get confidence(): number { return this._confidence; }
+  get successCount(): number { return this._successCount; }
+  get failureCount(): number { return this._failureCount; }
+  get metadata(): Record<string, unknown> { return { ...this._metadata }; }
+  get createdAt(): Date { return new Date(this._createdAt); }
+  get updatedAt(): Date { return new Date(this._updatedAt); }
+  get lastMatchedAt(): Date | undefined { return this._lastMatchedAt ? new Date(this._lastMatchedAt) : undefined; }
+
+  /**
+   * Calculate success rate
+   */
+  get successRate(): number {
+    const total = this._successCount + this._failureCount;
+    return total > 0 ? this._successCount / total : 0;
+  }
+
+  /**
+   * Record successful match
+   */
+  recordSuccess(): void {
+    this._successCount++;
+    this._confidence = this.calculateConfidence();
+    this._lastMatchedAt = new Date();
+    this._updatedAt = new Date();
+  }
+
+  /**
+   * Record failed match
+   */
+  recordFailure(): void {
+    this._failureCount++;
+    this._confidence = this.calculateConfidence();
+    this._lastMatchedAt = new Date();
+    this._updatedAt = new Date();
+  }
+
+  /**
+   * Calculate confidence based on success rate
+   */
+  private calculateConfidence(): number {
+    const total = this._successCount + this._failureCount;
+    if (total < 5) return this._confidence; // Not enough data
+
+    const newConfidence = this.successRate;
+    // Weighted average with existing confidence
+    return this._confidence * 0.3 + newConfidence * 0.7;
+  }
+
+  /**
+   * Check if pattern matches input
+   */
+  matches(input: string): boolean {
+    try {
+      const regex = new RegExp(this._condition, 'i');
+      return regex.test(input);
+    } catch {
+      return input.toLowerCase().includes(this._condition.toLowerCase());
+    }
+  }
+
+  /**
+   * Check if pattern is reliable (high confidence, sufficient data)
+   */
+  isReliable(): boolean {
+    const total = this._successCount + this._failureCount;
+    return total >= 10 && this._confidence >= 0.7;
+  }
+
+  toPersistence(): Record<string, unknown> {
+    return {
+      id: this._id,
+      type: this._type,
+      name: this._name,
+      description: this._description,
+      condition: this._condition,
+      action: this._action,
+      confidence: this._confidence,
+      successCount: this._successCount,
+      failureCount: this._failureCount,
+      metadata: this._metadata,
+      createdAt: this._createdAt.toISOString(),
+      updatedAt: this._updatedAt.toISOString(),
+      lastMatchedAt: this._lastMatchedAt?.toISOString(),
+    };
+  }
+}

package/src/domain/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Neural Domain Layer - Public Exports
+ *
+ * @module v3/neural/domain
+ */
+
+export {
+  Pattern,
+  type PatternType,
+  type PatternProps,
+} from './entities/pattern.js';
+
+export {
+  LearningDomainService,
+  type Trajectory,
+  type LearningResult,
+  type RouteRecommendation,
+} from './services/learning-service.js';

package/src/domain/services/learning-service.ts

@@ -0,0 +1,256 @@
+/**
+ * Learning Domain Service - Domain Layer
+ *
+ * Contains learning logic for pattern recognition and optimization.
+ *
+ * @module v3/neural/domain/services
+ */
+
+import { Pattern, PatternType } from '../entities/pattern.js';
+
+/**
+ * Learning trajectory
+ */
+export interface Trajectory {
+  id: string;
+  input: string;
+  actions: string[];
+  outcome: 'success' | 'failure' | 'partial';
+  reward: number;
+  metadata?: Record<string, unknown>;
+  timestamp: Date;
+}
+
+/**
+ * Learning result
+ */
+export interface LearningResult {
+  patternsExtracted: number;
+  patternsUpdated: number;
+  confidenceChange: number;
+}
+
+/**
+ * Route recommendation
+ */
+export interface RouteRecommendation {
+  agentRole: string;
+  confidence: number;
+  reasoning: string;
+  alternates: Array<{ role: string; confidence: number }>;
+}
+
+/**
+ * Learning Domain Service
+ */
+export class LearningDomainService {
+  private patterns: Map<string, Pattern> = new Map();
+
+  /**
+   * Extract patterns from trajectory
+   */
+  extractPatterns(trajectory: Trajectory): Pattern[] {
+    const extracted: Pattern[] = [];
+
+    // Extract task-routing pattern
+    if (trajectory.outcome === 'success') {
+      const taskPattern = Pattern.create({
+        type: 'task-routing',
+        name: `route_${trajectory.id}`,
+        description: `Learned from successful trajectory`,
+        condition: this.extractCondition(trajectory.input),
+        action: trajectory.actions[0] ?? 'default',
+        confidence: 0.6 + trajectory.reward * 0.2,
+        metadata: { source: trajectory.id },
+      });
+      extracted.push(taskPattern);
+    }
+
+    // Extract error recovery pattern if failure
+    if (trajectory.outcome === 'failure' && trajectory.actions.length > 1) {
+      const lastAction = trajectory.actions[trajectory.actions.length - 1];
+      const recoveryPattern = Pattern.create({
+        type: 'error-recovery',
+        name: `recovery_${trajectory.id}`,
+        description: `Recovery action from failure`,
+        condition: `error:${trajectory.actions[0]}`,
+        action: lastAction,
+        confidence: 0.5,
+        metadata: { source: trajectory.id },
+      });
+      extracted.push(recoveryPattern);
+    }
+
+    return extracted;
+  }
+
+  /**
+   * Update patterns based on trajectory outcome
+   */
+  updatePatterns(trajectory: Trajectory): LearningResult {
+    let patternsUpdated = 0;
+    let totalConfidenceChange = 0;
+
+    for (const pattern of this.patterns.values()) {
+      if (pattern.matches(trajectory.input)) {
+        const oldConfidence = pattern.confidence;
+
+        if (trajectory.outcome === 'success') {
+          pattern.recordSuccess();
+        } else {
+          pattern.recordFailure();
+        }
+
+        totalConfidenceChange += pattern.confidence - oldConfidence;
+        patternsUpdated++;
+      }
+    }
+
+    // Extract and add new patterns
+    const newPatterns = this.extractPatterns(trajectory);
+    for (const pattern of newPatterns) {
+      this.patterns.set(pattern.id, pattern);
+    }
+
+    return {
+      patternsExtracted: newPatterns.length,
+      patternsUpdated,
+      confidenceChange: totalConfidenceChange,
+    };
+  }
+
+  /**
+   * Get route recommendation for task
+   */
+  getRouteRecommendation(taskDescription: string): RouteRecommendation {
+    const matchingPatterns: Array<{ pattern: Pattern; score: number }> = [];
+
+    for (const pattern of this.patterns.values()) {
+      if (pattern.type !== 'task-routing') continue;
+
+      if (pattern.matches(taskDescription)) {
+        const score = pattern.confidence * (pattern.isReliable() ? 1.2 : 1.0);
+        matchingPatterns.push({ pattern, score });
+      }
+    }
+
+    // Sort by score
+    matchingPatterns.sort((a, b) => b.score - a.score);
+
+    if (matchingPatterns.length === 0) {
+      return this.getDefaultRecommendation(taskDescription);
+    }
+
+    const best = matchingPatterns[0];
+    const alternates = matchingPatterns.slice(1, 4).map((m) => ({
+      role: m.pattern.action,
+      confidence: m.score,
+    }));
+
+    return {
+      agentRole: best.pattern.action,
+      confidence: best.score,
+      reasoning: `Based on pattern "${best.pattern.name}" with ${best.pattern.successCount} successes`,
+      alternates,
+    };
+  }
+
+  /**
+   * Get default recommendation based on keywords
+   */
+  private getDefaultRecommendation(task: string): RouteRecommendation {
+    const taskLower = task.toLowerCase();
+    const keywordMap: Record<string, string> = {
+      code: 'coder',
+      implement: 'coder',
+      write: 'coder',
+      test: 'tester',
+      review: 'reviewer',
+      plan: 'planner',
+      research: 'researcher',
+      security: 'security-architect',
+      performance: 'performance-engineer',
+      memory: 'memory-specialist',
+    };
+
+    for (const [keyword, role] of Object.entries(keywordMap)) {
+      if (taskLower.includes(keyword)) {
+        return {
+          agentRole: role,
+          confidence: 0.5,
+          reasoning: `Keyword match: "${keyword}"`,
+          alternates: [],
+        };
+      }
+    }
+
+    return {
+      agentRole: 'coder',
+      confidence: 0.3,
+      reasoning: 'Default fallback',
+      alternates: [],
+    };
+  }
+
+  /**
+   * Extract condition from input
+   */
+  private extractCondition(input: string): string {
+    // Extract key terms from input
+    const words = input.toLowerCase().split(/\s+/);
+    const keyWords = words.filter((w) => w.length > 4).slice(0, 5);
+    return keyWords.join('|');
+  }
+
+  /**
+   * Consolidate patterns (merge duplicates, prune low-confidence)
+   */
+  consolidate(minConfidence: number = 0.3): { merged: number; pruned: number } {
+    let merged = 0;
+    let pruned = 0;
+
+    const toRemove: string[] = [];
+
+    for (const [id, pattern] of this.patterns) {
+      // Prune low confidence patterns with enough data
+      if (pattern.confidence < minConfidence && pattern.successCount + pattern.failureCount > 20) {
+        toRemove.push(id);
+        pruned++;
+      }
+    }
+
+    for (const id of toRemove) {
+      this.patterns.delete(id);
+    }
+
+    return { merged, pruned };
+  }
+
+  /**
+   * Get all patterns
+   */
+  getPatterns(): Pattern[] {
+    return Array.from(this.patterns.values());
+  }
+
+  /**
+   * Get patterns by type
+   */
+  getPatternsByType(type: PatternType): Pattern[] {
+    return Array.from(this.patterns.values()).filter((p) => p.type === type);
+  }
+
+  /**
+   * Add pattern
+   */
+  addPattern(pattern: Pattern): void {
+    this.patterns.set(pattern.id, pattern);
+  }
+
+  /**
+   * Remove pattern
+   */
+  removePattern(id: string): boolean {
+    return this.patterns.delete(id);
+  }
+}