@backendkit-labs/auto-learning 0.1.4 → 0.2.0

package/dist/{index-CtdA-dkB.d.cts → index-CuVtbErY.d.cts}

@@ -57,20 +57,40 @@ type LearningCycleEvent = {
     durationMs: number;
 };
 
-type LearningErrorTag = 'STORAGE_ERROR' | 'INSUFFICIENT_DATA' | 'INVALID_CONFIG' | 'ANOMALY_DETECTION_FAILED' | 'FEEDBACK_LOOP_ALREADY_RUNNING' | 'FEEDBACK_LOOP_NOT_RUNNING';
-type LearningError = {
-    readonly tag: LearningErrorTag;
+type StorageError = {
+    readonly tag: 'STORAGE_ERROR';
     readonly message: string;
     readonly cause?: unknown;
-    readonly required?: number;
-    readonly actual?: number;
-    readonly key?: string;
-    readonly value?: unknown;
 };
+type InsufficientDataError = {
+    readonly tag: 'INSUFFICIENT_DATA';
+    readonly message: string;
+    readonly required: number;
+    readonly actual: number;
+};
+type InvalidConfigError = {
+    readonly tag: 'INVALID_CONFIG';
+    readonly message: string;
+    readonly key: string;
+    readonly value: unknown;
+};
+type AnomalyDetectionFailedError = {
+    readonly tag: 'ANOMALY_DETECTION_FAILED';
+    readonly message: string;
+};
+type FeedbackLoopAlreadyRunningError = {
+    readonly tag: 'FEEDBACK_LOOP_ALREADY_RUNNING';
+    readonly message: string;
+};
+type FeedbackLoopNotRunningError = {
+    readonly tag: 'FEEDBACK_LOOP_NOT_RUNNING';
+    readonly message: string;
+};
+type LearningError = StorageError | InsufficientDataError | InvalidConfigError | AnomalyDetectionFailedError | FeedbackLoopAlreadyRunningError | FeedbackLoopNotRunningError;
 
 interface IPatternRegistry {
     record(pattern: EndpointPattern): Result<void, LearningError>;
-    getAggregates(windowMinutes: number): Result<AggregatePattern[], LearningError>;
+    getAggregates(windowMinutes: number, windowEnd?: Date): Result<AggregatePattern[], LearningError>;
     getHistory(endpoint: string, method: string, limit: number): Result<EndpointPattern[], LearningError>;
     getStats(): Result<RegistryStats, LearningError>;
 }
@@ -84,7 +104,7 @@ type RegistryStats = {
 interface StorageAdapter {
     savePattern(pattern: EndpointPattern): Result<void, LearningError>;
     getPatterns(windowStart: Date, windowEnd: Date): Result<EndpointPattern[], LearningError>;
-    getAggregates(windowMinutes: number): Result<AggregatePattern[], LearningError>;
+    getAggregates(windowMinutes: number, windowEnd?: Date): Result<AggregatePattern[], LearningError>;
     saveAnomaly(report: AnomalyReport$1): Result<void, LearningError>;
     getRecentAnomalies(limit: number): Result<AnomalyReport$1[], LearningError>;
     saveConfig(config: TunableConfig): Result<void, LearningError>;
@@ -105,7 +125,7 @@ interface ObservabilityAdapter {
 }
 
 interface IAnomalyDetector {
-    analyze(current: EndpointPattern, baseline: AggregatePattern): Result<AnomalyReport | null, LearningError>;
+    analyze(current: EndpointPattern, baseline: AggregatePattern): Result<AnomalyReport[], LearningError>;
     batchAnalyze(windowPatterns: EndpointPattern[], baselines: AggregatePattern[]): Result<AnomalyReport[], LearningError>;
 }
 type AnomalyReport = {
@@ -131,13 +151,15 @@ interface IConfigTuner {
     getCurrentConfig(): TunableConfig;
     tune(aggregates: AggregatePattern[], anomalies: AnomalyReport$1[]): Result<TunableConfig, LearningError>;
     reset(): Result<TunableConfig, LearningError>;
-    onConfigChange(callback: (config: TunableConfig) => void): void;
+    onConfigChange(callback: (config: TunableConfig) => void): () => void;
 }
 type ConfigTunerConfig = {
     minTimeoutMs: number;
     maxTimeoutMs: number;
     smoothingFactor: number;
     adjustmentStepMs: number;
+    /** Minimum milliseconds between successive config applications. Default: 60_000 */
+    cooldownMs: number;
 };
 declare const DEFAULT_TUNER_CONFIG: ConfigTunerConfig;
 
@@ -146,13 +168,14 @@ interface IFeedbackLoop {
     stop(): void;
     isRunning(): boolean;
     runOnce(): Promise<Result<LearningCycleEvent, LearningError>>;
-    onCycle(callback: (event: LearningCycleEvent) => void): void;
+    onCycle(callback: (event: LearningCycleEvent) => void): () => void;
 }
 type FeedbackLoopConfig = {
     defaultIntervalMs: number;
     windowSizeMinutes: number;
     minSamplesBeforeTuning: number;
-    cooldownBetweenChangesMs: number;
+    /** Hours to retain patterns and anomalies. Records older than this are pruned after each cycle. Default: 24 */
+    pruneTtlHours: number;
 };
 declare const DEFAULT_LOOP_CONFIG: FeedbackLoopConfig;
 
@@ -178,14 +201,17 @@ declare class AutoLearningCore {
     stopFeedbackLoop(): void;
     isFeedbackLoopRunning(): boolean;
     runOnce(): Promise<Result<LearningCycleEvent, LearningError>>;
-    onConfigChange(callback: (config: TunableConfig) => void): void;
-    onCycle(callback: (event: LearningCycleEvent) => void): void;
+    onConfigChange(callback: (config: TunableConfig) => void): () => void;
+    onCycle(callback: (event: LearningCycleEvent) => void): () => void;
 }
 
 type AutoLearningModuleOptions = {
     intervalMs?: number;
-    storage?: 'memory' | 'redis' | 'sql';
-    redisUrl?: string;
+    /**
+     * Set to false to skip auto-starting the feedback loop on bootstrap.
+     * Call core.startFeedbackLoop() manually when ready. Default: true.
+     */
+    autoStart?: boolean;
     observability?: {
         logger?: LoggerService;
         metrics?: {
@@ -215,4 +241,4 @@ declare const AUTO_LEARNING_OPTIONS: unique symbol;
 declare const AUTO_LEARNING_INSTANCE: unique symbol;
 declare const AUTO_LEARN_METADATA = "auto_learn_metadata";
 
-export { type AggregatePattern as A, type ConfigTunerConfig as C, DEFAULT_ANOMALY_CONFIG as D, type EndpointPattern as E, type FeedbackLoopConfig as F, type IPatternRegistry as I, type LearningError as L, type ObservabilityAdapter as O, type RegistryStats as R, type StorageAdapter as S, type TunableConfig as T, type IAnomalyDetector as a, type AnomalyDetectorConfig as b, type AnomalyReport as c, type IConfigTuner as d, type AnomalyReport$1 as e, type IFeedbackLoop as f, type LearningCycleEvent as g, AUTO_LEARNING_INSTANCE as h, AUTO_LEARNING_OPTIONS as i, AUTO_LEARN_METADATA as j, type AnomalySeverity as k, AutoLearn as l, type AutoLearnOptions as m, AutoLearningCore as n, type AutoLearningCoreOptions as o, AutoLearningModule as p, type AutoLearningModuleOptions as q, DEFAULT_LOOP_CONFIG as r, DEFAULT_TUNER_CONFIG as s };
+export { type AggregatePattern as A, type ConfigTunerConfig as C, DEFAULT_ANOMALY_CONFIG as D, type EndpointPattern as E, type FeedbackLoopConfig as F, type IPatternRegistry as I, type LearningError as L, type ObservabilityAdapter as O, type RegistryStats as R, type StorageAdapter as S, type TunableConfig as T, type IAnomalyDetector as a, type AnomalyDetectorConfig as b, type AnomalyReport as c, type IConfigTuner as d, type AnomalyReport$1 as e, type IFeedbackLoop as f, type LearningCycleEvent as g, AUTO_LEARNING_INSTANCE as h, AUTO_LEARNING_OPTIONS as i, AUTO_LEARN_METADATA as j, type AnomalyDetectionFailedError as k, type AnomalySeverity as l, AutoLearn as m, type AutoLearnOptions as n, AutoLearningCore as o, type AutoLearningCoreOptions as p, AutoLearningModule as q, type AutoLearningModuleOptions as r, DEFAULT_LOOP_CONFIG as s, DEFAULT_TUNER_CONFIG as t, type FeedbackLoopAlreadyRunningError as u, type FeedbackLoopNotRunningError as v, type InsufficientDataError as w, type InvalidConfigError as x, type StorageError as y };

package/dist/{index-CtdA-dkB.d.ts → index-CuVtbErY.d.ts}

@@ -57,20 +57,40 @@ type LearningCycleEvent = {
     durationMs: number;
 };
 
-type LearningErrorTag = 'STORAGE_ERROR' | 'INSUFFICIENT_DATA' | 'INVALID_CONFIG' | 'ANOMALY_DETECTION_FAILED' | 'FEEDBACK_LOOP_ALREADY_RUNNING' | 'FEEDBACK_LOOP_NOT_RUNNING';
-type LearningError = {
-    readonly tag: LearningErrorTag;
+type StorageError = {
+    readonly tag: 'STORAGE_ERROR';
     readonly message: string;
     readonly cause?: unknown;
-    readonly required?: number;
-    readonly actual?: number;
-    readonly key?: string;
-    readonly value?: unknown;
 };
+type InsufficientDataError = {
+    readonly tag: 'INSUFFICIENT_DATA';
+    readonly message: string;
+    readonly required: number;
+    readonly actual: number;
+};
+type InvalidConfigError = {
+    readonly tag: 'INVALID_CONFIG';
+    readonly message: string;
+    readonly key: string;
+    readonly value: unknown;
+};
+type AnomalyDetectionFailedError = {
+    readonly tag: 'ANOMALY_DETECTION_FAILED';
+    readonly message: string;
+};
+type FeedbackLoopAlreadyRunningError = {
+    readonly tag: 'FEEDBACK_LOOP_ALREADY_RUNNING';
+    readonly message: string;
+};
+type FeedbackLoopNotRunningError = {
+    readonly tag: 'FEEDBACK_LOOP_NOT_RUNNING';
+    readonly message: string;
+};
+type LearningError = StorageError | InsufficientDataError | InvalidConfigError | AnomalyDetectionFailedError | FeedbackLoopAlreadyRunningError | FeedbackLoopNotRunningError;
 
 interface IPatternRegistry {
     record(pattern: EndpointPattern): Result<void, LearningError>;
-    getAggregates(windowMinutes: number): Result<AggregatePattern[], LearningError>;
+    getAggregates(windowMinutes: number, windowEnd?: Date): Result<AggregatePattern[], LearningError>;
     getHistory(endpoint: string, method: string, limit: number): Result<EndpointPattern[], LearningError>;
     getStats(): Result<RegistryStats, LearningError>;
 }
@@ -84,7 +104,7 @@ type RegistryStats = {
 interface StorageAdapter {
     savePattern(pattern: EndpointPattern): Result<void, LearningError>;
     getPatterns(windowStart: Date, windowEnd: Date): Result<EndpointPattern[], LearningError>;
-    getAggregates(windowMinutes: number): Result<AggregatePattern[], LearningError>;
+    getAggregates(windowMinutes: number, windowEnd?: Date): Result<AggregatePattern[], LearningError>;
     saveAnomaly(report: AnomalyReport$1): Result<void, LearningError>;
     getRecentAnomalies(limit: number): Result<AnomalyReport$1[], LearningError>;
     saveConfig(config: TunableConfig): Result<void, LearningError>;
@@ -105,7 +125,7 @@ interface ObservabilityAdapter {
 }
 
 interface IAnomalyDetector {
-    analyze(current: EndpointPattern, baseline: AggregatePattern): Result<AnomalyReport | null, LearningError>;
+    analyze(current: EndpointPattern, baseline: AggregatePattern): Result<AnomalyReport[], LearningError>;
     batchAnalyze(windowPatterns: EndpointPattern[], baselines: AggregatePattern[]): Result<AnomalyReport[], LearningError>;
 }
 type AnomalyReport = {
@@ -131,13 +151,15 @@ interface IConfigTuner {
     getCurrentConfig(): TunableConfig;
     tune(aggregates: AggregatePattern[], anomalies: AnomalyReport$1[]): Result<TunableConfig, LearningError>;
     reset(): Result<TunableConfig, LearningError>;
-    onConfigChange(callback: (config: TunableConfig) => void): void;
+    onConfigChange(callback: (config: TunableConfig) => void): () => void;
 }
 type ConfigTunerConfig = {
     minTimeoutMs: number;
     maxTimeoutMs: number;
     smoothingFactor: number;
     adjustmentStepMs: number;
+    /** Minimum milliseconds between successive config applications. Default: 60_000 */
+    cooldownMs: number;
 };
 declare const DEFAULT_TUNER_CONFIG: ConfigTunerConfig;
 
@@ -146,13 +168,14 @@ interface IFeedbackLoop {
     stop(): void;
     isRunning(): boolean;
     runOnce(): Promise<Result<LearningCycleEvent, LearningError>>;
-    onCycle(callback: (event: LearningCycleEvent) => void): void;
+    onCycle(callback: (event: LearningCycleEvent) => void): () => void;
 }
 type FeedbackLoopConfig = {
     defaultIntervalMs: number;
     windowSizeMinutes: number;
     minSamplesBeforeTuning: number;
-    cooldownBetweenChangesMs: number;
+    /** Hours to retain patterns and anomalies. Records older than this are pruned after each cycle. Default: 24 */
+    pruneTtlHours: number;
 };
 declare const DEFAULT_LOOP_CONFIG: FeedbackLoopConfig;
 
@@ -178,14 +201,17 @@ declare class AutoLearningCore {
     stopFeedbackLoop(): void;
     isFeedbackLoopRunning(): boolean;
     runOnce(): Promise<Result<LearningCycleEvent, LearningError>>;
-    onConfigChange(callback: (config: TunableConfig) => void): void;
-    onCycle(callback: (event: LearningCycleEvent) => void): void;
+    onConfigChange(callback: (config: TunableConfig) => void): () => void;
+    onCycle(callback: (event: LearningCycleEvent) => void): () => void;
 }
 
 type AutoLearningModuleOptions = {
     intervalMs?: number;
-    storage?: 'memory' | 'redis' | 'sql';
-    redisUrl?: string;
+    /**
+     * Set to false to skip auto-starting the feedback loop on bootstrap.
+     * Call core.startFeedbackLoop() manually when ready. Default: true.
+     */
+    autoStart?: boolean;
     observability?: {
         logger?: LoggerService;
         metrics?: {
@@ -215,4 +241,4 @@ declare const AUTO_LEARNING_OPTIONS: unique symbol;
 declare const AUTO_LEARNING_INSTANCE: unique symbol;
 declare const AUTO_LEARN_METADATA = "auto_learn_metadata";
 
-export { type AggregatePattern as A, type ConfigTunerConfig as C, DEFAULT_ANOMALY_CONFIG as D, type EndpointPattern as E, type FeedbackLoopConfig as F, type IPatternRegistry as I, type LearningError as L, type ObservabilityAdapter as O, type RegistryStats as R, type StorageAdapter as S, type TunableConfig as T, type IAnomalyDetector as a, type AnomalyDetectorConfig as b, type AnomalyReport as c, type IConfigTuner as d, type AnomalyReport$1 as e, type IFeedbackLoop as f, type LearningCycleEvent as g, AUTO_LEARNING_INSTANCE as h, AUTO_LEARNING_OPTIONS as i, AUTO_LEARN_METADATA as j, type AnomalySeverity as k, AutoLearn as l, type AutoLearnOptions as m, AutoLearningCore as n, type AutoLearningCoreOptions as o, AutoLearningModule as p, type AutoLearningModuleOptions as q, DEFAULT_LOOP_CONFIG as r, DEFAULT_TUNER_CONFIG as s };
+export { type AggregatePattern as A, type ConfigTunerConfig as C, DEFAULT_ANOMALY_CONFIG as D, type EndpointPattern as E, type FeedbackLoopConfig as F, type IPatternRegistry as I, type LearningError as L, type ObservabilityAdapter as O, type RegistryStats as R, type StorageAdapter as S, type TunableConfig as T, type IAnomalyDetector as a, type AnomalyDetectorConfig as b, type AnomalyReport as c, type IConfigTuner as d, type AnomalyReport$1 as e, type IFeedbackLoop as f, type LearningCycleEvent as g, AUTO_LEARNING_INSTANCE as h, AUTO_LEARNING_OPTIONS as i, AUTO_LEARN_METADATA as j, type AnomalyDetectionFailedError as k, type AnomalySeverity as l, AutoLearn as m, type AutoLearnOptions as n, AutoLearningCore as o, type AutoLearningCoreOptions as p, AutoLearningModule as q, type AutoLearningModuleOptions as r, DEFAULT_LOOP_CONFIG as s, DEFAULT_TUNER_CONFIG as t, type FeedbackLoopAlreadyRunningError as u, type FeedbackLoopNotRunningError as v, type InsufficientDataError as w, type InvalidConfigError as x, type StorageError as y };