cognitive-core 0.1.2 → 0.2.1

package/dist/learning/unified-pipeline.d.ts

@@ -0,0 +1,311 @@
+/**
+ * UnifiedLearningPipeline — Three-speed learning orchestrator.
+ *
+ * Consolidates InstantLoop, LearningPipeline (batch), LoopCoordinator,
+ * MetaLearner, EffectivenessTracker, and KnowledgeExtractor into a single
+ * owner that manages the full learning lifecycle.
+ *
+ * Three processing speeds (inspired by ruvector SONA):
+ *
+ *   1. **Immediate** (InstantLoop, <200ms): Fires on every trajectory.
+ *      Stores experience, bumps playbooks, extracts lightweight knowledge,
+ *      causal edges, and reflexion episodes.
+ *
+ *   2. **Batch** (cold pipeline): Triggered by energy-threshold evaluation
+ *      (not just count). Runs full analysis, playbook extraction, temporal
+ *      compression, and experience clustering.
+ *
+ *   3. **Maintenance** (circadian-gated): Runs periodically or after N batches.
+ *      Knowledge defrag, healing orchestrator, meta-strategy generation,
+ *      effectiveness reporting.
+ *
+ * The pipeline owns all components and coordinates them. Atlas delegates
+ * learning to this pipeline rather than managing components directly.
+ */
+import type { Trajectory, LearningConfig } from '../types/index.js';
+import type { TrajectoryWithAnalysis } from '../types/trajectory-source.js';
+import type { MemorySystem } from '../memory/system.js';
+import type { SqlitePersistence } from '../persistence/index.js';
+import type { AgenticTaskRunner } from '../workspace/runner.js';
+import { type InstantLoopResult, type InstantLoopConfig } from './instant-loop.js';
+import { MetaLearner, type MetaLearnerConfig } from './meta-learner.js';
+import { LearningEffectivenessTracker } from './effectiveness.js';
+import { EnergyEvaluator, type EnergyEvaluatorConfig, type EnergyEvaluation, type EnergySignal, type EscalationReason } from './energy-evaluator.js';
+import { MaintenanceScheduler, type MaintenanceSchedulerConfig, type MaintenanceCycleResult, type MaintenanceTask } from './maintenance-scheduler.js';
+import { HealingOrchestrator, type HealthContext, type HealingCycleResult, type AnomalyDetector, type RepairStrategy } from './healing-orchestrator.js';
+export type { EnergyEvaluation, EnergySignal, EscalationReason, MaintenanceCycleResult, MaintenanceTask, HealingCycleResult, HealthContext, AnomalyDetector, RepairStrategy, };
+/**
+ * Feature flags for optional subsystems.
+ */
+export interface UnifiedPipelineFeatures {
+    /** Enable temporal compression in batch pipeline (default: true) */
+    temporalCompression?: boolean;
+    /** Enable experience clustering via ReasoningBank (default: true) */
+    reasoningBank?: boolean;
+    /** Enable reflexion episode generation (default: true) */
+    reflexion?: boolean;
+    /** Enable causal edge extraction (default: true) */
+    causalExtraction?: boolean;
+    /** Enable knowledge extraction in batch pipeline (default: true) */
+    knowledgeExtraction?: boolean;
+    /** Enable meta-learning (default: true) */
+    metaLearning?: boolean;
+    /** Enable effectiveness tracking (default: true) */
+    effectivenessTracking?: boolean;
+    /** Enable healing orchestrator with built-in detectors (default: true) */
+    healing?: boolean;
+    /** Enable efficacy maintenance tasks (decay detection, audit, lifecycle review) (default: true) */
+    efficacy?: boolean;
+}
+/**
+ * Full configuration for the UnifiedLearningPipeline.
+ */
+export interface UnifiedPipelineConfig {
+    /** Immediate-phase (InstantLoop) config */
+    instant: InstantLoopConfig;
+    /** Batch-phase config */
+    batch: {
+        learning: Partial<LearningConfig>;
+        energy: Partial<EnergyEvaluatorConfig>;
+    };
+    /** Maintenance-phase config */
+    maintenance: Partial<MaintenanceSchedulerConfig>;
+    /** Meta-learner config */
+    metaLearner: Partial<MetaLearnerConfig>;
+    /** Feature flags */
+    features: UnifiedPipelineFeatures;
+    /** Efficacy maintenance config */
+    efficacy: EfficacyMaintenanceConfig;
+    /** Max latency warning threshold for instant loop in ms (default: 200) */
+    maxInstantLatencyMs: number;
+}
+/**
+ * Configuration for efficacy maintenance tasks.
+ */
+export interface EfficacyMaintenanceConfig {
+    /** Run lifecycle review every Nth maintenance cycle (default: 3) */
+    lifecycleReviewFrequency: number;
+    /** Minimum playbooks required before running efficacy tasks (default: 1) */
+    minPlaybooks: number;
+    /** Minimum annotations required before running efficacy tasks (default: 3) */
+    minAnnotations: number;
+}
+/**
+ * Result of processing a single trajectory through the immediate phase.
+ */
+export interface ImmediateResult {
+    /** InstantLoop result */
+    instantLoop: InstantLoopResult;
+    /** Energy evaluation (did this trajectory push us toward batch?) */
+    energyEval: EnergyEvaluation;
+    /** Whether a batch was triggered by this trajectory */
+    batchTriggered: boolean;
+    /** Batch result if one was triggered */
+    batchResult?: UnifiedBatchResult;
+    /** Whether maintenance was triggered after batch */
+    maintenanceTriggered: boolean;
+    /** Maintenance result if triggered */
+    maintenanceResult?: MaintenanceCycleResult;
+}
+/**
+ * Result of a batch processing cycle.
+ */
+export interface UnifiedBatchResult {
+    /** Number of trajectories processed in this batch */
+    trajectoriesProcessed: number;
+    /** Playbooks extracted or updated */
+    playbooksExtracted: number;
+    /** Experiences pruned (including compression evictions) */
+    experiencesPruned: number;
+    /** Temporal compression details */
+    experiencesCompressed: {
+        promoted: number;
+        demoted: number;
+        evicted: number;
+    };
+    /** Experiences re-clustered */
+    experiencesClustered: number;
+    /** Knowledge notes extracted in batch (from KnowledgeExtractor) */
+    knowledgeExtracted: number;
+    /** Success rate of the batch */
+    successRate: number;
+    /** Escalation reasons that triggered this batch */
+    triggerReasons: EscalationReason[];
+}
+/**
+ * Pipeline statistics.
+ */
+export interface UnifiedPipelineStats {
+    /** Total trajectories processed (immediate) */
+    totalProcessed: number;
+    /** Total batch cycles run */
+    batchCyclesRun: number;
+    /** Total maintenance cycles run */
+    maintenanceCyclesRun: number;
+    /** Current pending count for batch */
+    pendingForBatch: number;
+    /** Batches since last maintenance */
+    batchesSinceLastMaintenance: number;
+    /** Registered maintenance tasks */
+    maintenanceTasks: string[];
+    /** Registered anomaly detectors */
+    anomalyDetectors: string[];
+    /** Registered repair strategies */
+    repairStrategies: string[];
+}
+/**
+ * UnifiedLearningPipeline — owns all learning components and orchestrates
+ * the three-speed processing loop.
+ */
+export declare class UnifiedLearningPipeline {
+    private config;
+    private learningConfig;
+    private instantLoop;
+    private analyzer;
+    private playbookExtractor;
+    private knowledgeExtractor;
+    private temporalCompressor;
+    private reasoningBank;
+    private metaLearner;
+    private effectivenessTracker;
+    private energyEvaluator;
+    private maintenanceScheduler;
+    private healingOrchestrator;
+    private memory;
+    private taskRunner;
+    private accumulated;
+    private accumulatedAnalyses;
+    private totalProcessed;
+    private batchCyclesRun;
+    private maintenanceCyclesRun;
+    private _onLatencyWarning;
+    private lastDecayResult;
+    constructor(memory: MemorySystem, config?: Partial<UnifiedPipelineConfig>, persistence?: SqlitePersistence);
+    /**
+     * Load persisted state for internal components.
+     * Call after persistence is initialized.
+     */
+    loadPersistedState(): void;
+    /**
+     * Initialize components that require async setup.
+     */
+    init(): Promise<void>;
+    /**
+     * Set the agentic task runner for workspace-based analysis.
+     */
+    setTaskRunner(runner: AgenticTaskRunner): void;
+    /**
+     * Process a single trajectory through the full pipeline.
+     *
+     * 1. Runs the instant loop (immediate phase)
+     * 2. Evaluates energy to decide on batch trigger
+     * 3. If batch triggered, runs batch + checks maintenance
+     *
+     * This is the primary entry point for trajectory processing.
+     */
+    processTrajectory(trajectory: Trajectory, signals?: Partial<EnergySignal>): Promise<ImmediateResult>;
+    /**
+     * Run batch learning on accumulated trajectories.
+     * Can be called manually or triggered by energy evaluation.
+     */
+    runBatch(triggerReasons?: EscalationReason[]): Promise<UnifiedBatchResult>;
+    /**
+     * Run a maintenance cycle.
+     * Executes registered maintenance tasks (defrag, healing, etc.).
+     * Can be called manually regardless of mode.
+     */
+    runMaintenance(options?: {
+        force?: boolean;
+    }): Promise<MaintenanceCycleResult>;
+    /**
+     * Register a custom maintenance task.
+     */
+    registerMaintenanceTask(task: MaintenanceTask): void;
+    /**
+     * Register a custom anomaly detector for the healing orchestrator.
+     */
+    addAnomalyDetector(detector: AnomalyDetector): void;
+    /**
+     * Register a custom repair strategy for the healing orchestrator.
+     */
+    addRepairStrategy(strategy: RepairStrategy): void;
+    /**
+     * Get the meta-learner instance.
+     */
+    getMetaLearner(): MetaLearner | null;
+    /**
+     * Get the effectiveness tracker.
+     */
+    getEffectivenessTracker(): LearningEffectivenessTracker | null;
+    /**
+     * Get the energy evaluator.
+     */
+    getEnergyEvaluator(): EnergyEvaluator;
+    /**
+     * Get the maintenance scheduler.
+     */
+    getMaintenanceScheduler(): MaintenanceScheduler;
+    /**
+     * Get the healing orchestrator.
+     */
+    getHealingOrchestrator(): HealingOrchestrator;
+    /**
+     * Get accumulated trajectory count.
+     */
+    getAccumulatedCount(): number;
+    /**
+     * Get accumulated trajectories with analyses (read-only).
+     */
+    getAccumulated(): TrajectoryWithAnalysis[];
+    /**
+     * Get pipeline statistics.
+     */
+    getStats(): UnifiedPipelineStats;
+    /**
+     * Register a callback for instant-loop latency warnings.
+     */
+    onLatencyWarning(callback: (durationMs: number) => void): void;
+    /**
+     * Update batch learning configuration.
+     */
+    updateConfig(config: Partial<LearningConfig>): void;
+    /**
+     * Register built-in maintenance tasks.
+     */
+    private registerBuiltInMaintenanceTasks;
+    /**
+     * Register efficacy maintenance tasks (decay detection, audit, lifecycle review).
+     * All tasks are log-only — results are returned in details but no automatic mutations.
+     */
+    private registerEfficacyMaintenanceTasks;
+    /**
+     * Fetch shared efficacy data used by all three efficacy maintenance tasks.
+     */
+    private getEfficacyData;
+    /**
+     * Build a trajectoryId→domain map from annotations.
+     * Uses accumulated trajectories when available, otherwise infers from task annotations.
+     */
+    private buildTrajectoryDomainMap;
+    /**
+     * Build health context for the healing orchestrator.
+     */
+    private buildHealthContext;
+    /**
+     * Analyze a trajectory via workspace template or heuristic fallback.
+     */
+    private analyzeWithTemplate;
+    /**
+     * Extract playbooks via workspace template or heuristic fallback.
+     */
+    private extractPlaybooks;
+    /**
+     * Empty batch result for when there's nothing to process.
+     */
+    private emptyBatchResult;
+}
+/**
+ * Create a UnifiedLearningPipeline.
+ */
+export declare function createUnifiedPipeline(memory: MemorySystem, config?: Partial<UnifiedPipelineConfig>, persistence?: SqlitePersistence): UnifiedLearningPipeline;
+//# sourceMappingURL=unified-pipeline.d.ts.map

package/dist/learning/unified-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unified-pipeline.d.ts","sourceRoot":"","sources":["../../src/learning/unified-pipeline.ts"],"names":[],"mappings":"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"}