cognitive-core 0.2.4 → 0.3.1

package/src/learning/healing-orchestrator.ts

@@ -1,383 +0,0 @@
-/**
- * HealingOrchestrator — Plug-in anomaly detection and repair pattern.
- *
- * Inspired by ruvector's HealingOrchestrator (ruvector-dag/healing/orchestrator.rs).
- * Runs registered anomaly detectors and repair strategies in each maintenance
- * cycle. Detectors and strategies are push-registered via add methods.
- *
- * The orchestrator itself has no internal timer — `runCycle()` is called
- * explicitly by the MaintenanceScheduler or manually by the caller.
- */
-
-/**
- * Health context provided to detectors and repair strategies.
- */
-export interface HealthContext {
-  /** Total trajectories processed since last cycle */
-  trajectoriesProcessed: number;
-  /** Current experience count */
-  experienceCount: number;
-  /** Current playbook count */
-  playbookCount: number;
-  /** Recent success rate (0.0–1.0) */
-  recentSuccessRate: number;
-  /** Batches since last maintenance */
-  batchesSinceLastMaintenance: number;
-  /** Custom metrics from subsystems */
-  metrics: Record<string, number>;
-}
-
-/**
- * An anomaly detected by a detector.
- */
-export interface Anomaly {
-  /** Unique type identifier (e.g., 'playbook-drift', 'memory-bloat') */
-  type: string;
-  /** Severity: higher = more urgent */
-  severity: 'low' | 'medium' | 'high';
-  /** Human-readable description */
-  description: string;
-  /** Detector that found this anomaly */
-  detectorName: string;
-  /** Arbitrary data for repair strategies to use */
-  data?: Record<string, unknown>;
-}
-
-/**
- * Result of a repair attempt.
- */
-export interface RepairResult {
-  /** Whether the repair was successful */
-  success: boolean;
-  /** What the repair strategy did */
-  action: string;
-  /** Repair strategy name */
-  strategyName: string;
-  /** Duration in ms */
-  durationMs: number;
-}
-
-/**
- * Result of a full healing cycle.
- */
-export interface HealingCycleResult {
-  /** Anomalies detected in this cycle */
-  anomaliesDetected: Anomaly[];
-  /** Repair attempts and their results */
-  repairs: RepairResult[];
-  /** Total duration of the cycle in ms */
-  durationMs: number;
-  /** Timestamp */
-  timestamp: Date;
-}
-
-/**
- * Interface for anomaly detectors.
- * Implement this to create custom health checks.
- */
-export interface AnomalyDetector {
-  /** Unique name for this detector */
-  readonly name: string;
-  /** Run detection and return any anomalies found */
-  detect(context: HealthContext): Promise<Anomaly[]>;
-}
-
-/**
- * Interface for repair strategies.
- * Implement this to create custom repair actions.
- */
-export interface RepairStrategy {
-  /** Unique name for this strategy */
-  readonly name: string;
-  /** Check if this strategy can handle a given anomaly type */
-  canRepair(anomaly: Anomaly): boolean;
-  /** Attempt to repair the anomaly */
-  repair(anomaly: Anomaly, context: HealthContext): Promise<RepairResult>;
-}
-
-/**
- * HealingOrchestrator — coordinates anomaly detection and repair.
- */
-export class HealingOrchestrator {
-  private detectors: AnomalyDetector[] = [];
-  private strategies: RepairStrategy[] = [];
-  private cycleHistory: HealingCycleResult[] = [];
-  private maxHistorySize: number;
-
-  constructor(options?: { maxHistorySize?: number }) {
-    this.maxHistorySize = options?.maxHistorySize ?? 20;
-  }
-
-  /**
-   * Register an anomaly detector.
-   */
-  addDetector(detector: AnomalyDetector): void {
-    // Replace existing detector with same name
-    this.detectors = this.detectors.filter(d => d.name !== detector.name);
-    this.detectors.push(detector);
-  }
-
-  /**
-   * Unregister an anomaly detector by name.
-   */
-  removeDetector(name: string): void {
-    this.detectors = this.detectors.filter(d => d.name !== name);
-  }
-
-  /**
-   * Register a repair strategy.
-   */
-  addRepairStrategy(strategy: RepairStrategy): void {
-    this.strategies = this.strategies.filter(s => s.name !== strategy.name);
-    this.strategies.push(strategy);
-  }
-
-  /**
-   * Unregister a repair strategy by name.
-   */
-  removeRepairStrategy(name: string): void {
-    this.strategies = this.strategies.filter(s => s.name !== name);
-  }
-
-  /**
-   * Run a healing cycle.
-   *
-   * 1. Runs all registered detectors to find anomalies
-   * 2. For each anomaly, finds the first matching repair strategy
-   * 3. Executes the repair
-   */
-  async runCycle(context: HealthContext): Promise<HealingCycleResult> {
-    const start = Date.now();
-    const anomalies: Anomaly[] = [];
-    const repairs: RepairResult[] = [];
-
-    // Phase 1: Detection
-    for (const detector of this.detectors) {
-      try {
-        const detected = await detector.detect(context);
-        anomalies.push(...detected);
-      } catch (error) {
-        // Non-critical — log but continue
-        anomalies.push({
-          type: 'detector-error',
-          severity: 'low',
-          description: `Detector '${detector.name}' failed: ${error instanceof Error ? error.message : String(error)}`,
-          detectorName: detector.name,
-        });
-      }
-    }
-
-    // Sort by severity (high first)
-    const severityOrder: Record<string, number> = { high: 0, medium: 1, low: 2 };
-    anomalies.sort(
-      (a, b) => (severityOrder[a.severity] ?? 3) - (severityOrder[b.severity] ?? 3),
-    );
-
-    // Phase 2: Repair
-    for (const anomaly of anomalies) {
-      // Skip detector errors (not repairable)
-      if (anomaly.type === 'detector-error') continue;
-
-      for (const strategy of this.strategies) {
-        if (!strategy.canRepair(anomaly)) continue;
-
-        const repairStart = Date.now();
-        try {
-          const result = await strategy.repair(anomaly, context);
-          repairs.push(result);
-        } catch (error) {
-          repairs.push({
-            success: false,
-            action: `Failed: ${error instanceof Error ? error.message : String(error)}`,
-            strategyName: strategy.name,
-            durationMs: Date.now() - repairStart,
-          });
-        }
-
-        // Only apply first matching strategy per anomaly
-        break;
-      }
-    }
-
-    const result: HealingCycleResult = {
-      anomaliesDetected: anomalies,
-      repairs,
-      durationMs: Date.now() - start,
-      timestamp: new Date(),
-    };
-
-    this.cycleHistory.push(result);
-    if (this.cycleHistory.length > this.maxHistorySize) {
-      this.cycleHistory.shift();
-    }
-
-    return result;
-  }
-
-  /**
-   * Get cycle history for diagnostics.
-   */
-  getCycleHistory(): readonly HealingCycleResult[] {
-    return this.cycleHistory;
-  }
-
-  /**
-   * Get registered detectors.
-   */
-  getDetectors(): readonly AnomalyDetector[] {
-    return this.detectors;
-  }
-
-  /**
-   * Get registered repair strategies.
-   */
-  getRepairStrategies(): readonly RepairStrategy[] {
-    return this.strategies;
-  }
-}
-
-/**
- * Create a HealingOrchestrator.
- */
-export function createHealingOrchestrator(
-  options?: { maxHistorySize?: number },
-): HealingOrchestrator {
-  return new HealingOrchestrator(options);
-}
-
-// =========================================================================
-// Built-in Detectors
-// =========================================================================
-
-/**
- * Detects when playbook success rates are consistently low,
- * suggesting playbook drift.
- */
-export class PlaybookDriftDetector implements AnomalyDetector {
-  readonly name = 'playbook-drift';
-  private threshold: number;
-
-  constructor(threshold = 0.3) {
-    this.threshold = threshold;
-  }
-
-  async detect(context: HealthContext): Promise<Anomaly[]> {
-    const anomalies: Anomaly[] = [];
-
-    if (
-      context.recentSuccessRate < this.threshold &&
-      context.playbookCount > 0 &&
-      context.trajectoriesProcessed >= 5
-    ) {
-      anomalies.push({
-        type: 'playbook-drift',
-        severity: 'medium',
-        description: `Recent success rate (${(context.recentSuccessRate * 100).toFixed(0)}%) is below threshold (${(this.threshold * 100).toFixed(0)}%) with ${context.playbookCount} playbooks available`,
-        detectorName: this.name,
-        data: {
-          successRate: context.recentSuccessRate,
-          playbookCount: context.playbookCount,
-        },
-      });
-    }
-
-    return anomalies;
-  }
-}
-
-/**
- * Detects when the experience store is growing beyond capacity,
- * suggesting aggressive pruning is needed.
- */
-export class MemoryBloatDetector implements AnomalyDetector {
-  readonly name = 'memory-bloat';
-  private maxExperiences: number;
-  private warningRatio: number;
-
-  constructor(maxExperiences = 1000, warningRatio = 0.9) {
-    this.maxExperiences = maxExperiences;
-    this.warningRatio = warningRatio;
-  }
-
-  async detect(context: HealthContext): Promise<Anomaly[]> {
-    const anomalies: Anomaly[] = [];
-
-    if (
-      this.maxExperiences > 0 &&
-      context.experienceCount >= this.maxExperiences * this.warningRatio
-    ) {
-      const severity =
-        context.experienceCount >= this.maxExperiences ? 'high' : 'medium';
-
-      anomalies.push({
-        type: 'memory-bloat',
-        severity,
-        description: `Experience count (${context.experienceCount}) is ${severity === 'high' ? 'at' : 'approaching'} capacity (${this.maxExperiences})`,
-        detectorName: this.name,
-        data: {
-          experienceCount: context.experienceCount,
-          maxExperiences: this.maxExperiences,
-        },
-      });
-    }
-
-    return anomalies;
-  }
-}
-
-/**
- * Detects when a custom metric exceeds a Z-score threshold,
- * inspired by ruvector's Z-score-based outlier detection.
- */
-export class MetricDriftDetector implements AnomalyDetector {
-  readonly name: string;
-  private metricKey: string;
-  private history: number[] = [];
-  private windowSize: number;
-  private zThreshold: number;
-
-  constructor(
-    metricKey: string,
-    options?: { windowSize?: number; zThreshold?: number },
-  ) {
-    this.name = `metric-drift:${metricKey}`;
-    this.metricKey = metricKey;
-    this.windowSize = options?.windowSize ?? 20;
-    this.zThreshold = options?.zThreshold ?? 2.0;
-  }
-
-  async detect(context: HealthContext): Promise<Anomaly[]> {
-    const value = context.metrics[this.metricKey];
-    if (value === undefined) return [];
-
-    this.history.push(value);
-    if (this.history.length > this.windowSize) {
-      this.history.shift();
-    }
-
-    if (this.history.length < 3) return [];
-
-    const mean = this.history.reduce((s, v) => s + v, 0) / this.history.length;
-    const variance =
-      this.history.reduce((s, v) => s + (v - mean) ** 2, 0) / this.history.length;
-    const std = Math.sqrt(variance);
-
-    if (std === 0) return [];
-
-    const zScore = Math.abs(value - mean) / std;
-
-    if (zScore >= this.zThreshold) {
-      return [
-        {
-          type: 'metric-drift',
-          severity: zScore >= this.zThreshold * 1.5 ? 'high' : 'medium',
-          description: `Metric '${this.metricKey}' value ${value.toFixed(2)} has z-score ${zScore.toFixed(2)} (threshold: ${this.zThreshold})`,
-          detectorName: this.name,
-          data: { metricKey: this.metricKey, value, zScore, mean, std },
-        },
-      ];
-    }
-
-    return [];
-  }
-}

package/src/learning/index.ts

@@ -1,150 +0,0 @@
-export {
-  TrajectoryAnalyzer,
-  createAnalyzer,
-  simpleCreditAssignment,
-  outcomeCreditAssignment,
-  getCreditAssignmentFn,
-  type AnalysisResult,
-  type ErrorPattern,
-  type TrainingExample,
-  type CreditAssignmentFn,
-  type AnalyzerConfig,
-} from './analyzer.js';
-
-// Playbook-based learning
-export {
-  PlaybookExtractor,
-  createPlaybookExtractor,
-  type ExtractedPlaybooks,
-  type PlaybookUpdate,
-  type PlaybookExtractorConfig,
-} from './playbook-extractor.js';
-
-export {
-  MetaLearner,
-  createMetaLearner,
-  type MetaLearnerConfig,
-} from './meta-learner.js';
-
-export {
-  PlaybookUsageInference,
-  createUsageInference,
-  type PlaybookUsageResult,
-  type UsageInferenceConfig,
-} from './usage-inference.js';
-
-// Team-aware learning
-export {
-  TeamTrajectoryIngester,
-  createTeamTrajectoryIngester,
-  type CompressionConfig,
-  type CriticalStep,
-  type CriticalInteraction,
-  type StructuralMetrics,
-  type IngestionResult,
-} from './team-ingester.js';
-
-export {
-  TeamLearningPipeline,
-  createTeamLearningPipeline,
-  type TeamProcessResult as TeamLearningProcessResult,
-  type TeamBatchResult,
-} from './team-pipeline.js';
-
-export {
-  TeamMetaLearner,
-  createTeamMetaLearner,
-  type TeamMetaLearnerConfig,
-} from './team-meta-learner.js';
-
-// Knowledge extraction
-export {
-  KnowledgeExtractor,
-  createKnowledgeExtractor,
-  type KnowledgeExtractorConfig,
-  type ExtractionContext,
-} from './knowledge-extractor.js';
-
-// Trajectory sources
-export {
-  InMemoryTrajectorySource,
-  FileTrajectorySource,
-  PipelineTrajectorySource,
-  SessionTrajectorySource,
-  type SessionSynthesisOptions,
-  DataclawTrajectorySource,
-  type DataclawSourceOptions,
-} from './trajectory-sources/index.js';
-
-// Instant (hot-path) learning
-export {
-  InstantLoop,
-  createInstantLoop,
-  type InstantLoopResult,
-  type InstantLoopConfig,
-} from './instant-loop.js';
-
-// Reflexion generation
-export {
-  ReflexionGenerator,
-  createReflexionGenerator,
-  type ReflexionGeneratorConfig,
-} from './reflexion-generator.js';
-
-// Effectiveness tracking
-export {
-  LearningEffectivenessTracker,
-  createEffectivenessTracker,
-  type TaskAnnotation,
-  type EffectivenessMetrics,
-  type PlaybookEffectivenessEntry,
-} from './effectiveness.js';
-
-// Unified learning pipeline (three-speed: immediate + batch + maintenance)
-export {
-  UnifiedLearningPipeline,
-  createUnifiedPipeline,
-  type UnifiedPipelineConfig,
-  type UnifiedPipelineFeatures,
-  type EfficacyMaintenanceConfig,
-  type ImmediateResult,
-  type UnifiedBatchResult,
-  type UnifiedPipelineStats,
-  type EnergyEvaluation,
-  type EnergySignal,
-  type EscalationReason,
-  type MaintenanceCycleResult,
-  type MaintenanceTask,
-  type HealingCycleResult,
-  type HealthContext,
-  type AnomalyDetector,
-  type RepairStrategy,
-} from './unified-pipeline.js';
-
-// Energy evaluator (ruvector-inspired batch trigger)
-export {
-  EnergyEvaluator,
-  createEnergyEvaluator,
-  type EnergyEvaluatorConfig,
-  type LaneTransition,
-} from './energy-evaluator.js';
-
-// Maintenance scheduler (circadian-style duty-gated)
-export {
-  MaintenanceScheduler,
-  createMaintenanceScheduler,
-  type MaintenanceSchedulerConfig,
-  type MaintenanceMode,
-  type MaintenanceTaskResult,
-} from './maintenance-scheduler.js';
-
-// Healing orchestrator (plug-in detector/repair)
-export {
-  HealingOrchestrator,
-  createHealingOrchestrator,
-  PlaybookDriftDetector,
-  MemoryBloatDetector,
-  MetricDriftDetector,
-  type Anomaly,
-  type RepairResult,
-} from './healing-orchestrator.js';