@backendkit-labs/auto-learning 0.1.3 → 0.2.0

package/README.md

@@ -10,6 +10,8 @@
 
 Static resilience configuration is a guess. `@backendkit-labs/auto-learning` observes your actual traffic, detects anomalies, and adjusts thresholds continuously — so your circuit breaker opens at the right rate, your bulkhead concurrency matches real load, and your HTTP timeouts reflect actual p95 latency rather than a number someone typed four years ago.
 
+> **Not machine learning.** This library uses descriptive statistics (averages, percentiles, standard deviation) and deterministic rules with exponential smoothing. There are no models, no training data, and no weights. The name reflects the *behavior* — the system learns what "normal" looks like for your traffic — not the technique.
+
 Optional NestJS integration included — global interceptor that records patterns automatically, and adapters that push config changes directly to `CircuitBreakerRegistry` and `BulkheadRegistry`.
 
 ---
@@ -176,6 +178,21 @@ That's it. Every request to `GET /orders` is recorded automatically. The feedbac
 
 ## Core Concepts
 
+### How it actually works (no ML)
+
+Despite the name, this library does not use machine learning. The techniques are deliberate:
+
+| Technique | Where it's used |
+|-----------|----------------|
+| Descriptive statistics (avg, p50/p95/p99, error rate) | Aggregating patterns per endpoint |
+| Threshold comparison against a rolling baseline | Anomaly detection |
+| Exponential smoothing: `current + (target − current) × factor` | Gradual timeout adjustment |
+| Deterministic step rules (+1/−1, ±10×n) | Retry and circuit breaker tuning |
+
+**Why not ML?** Statistical rules are transparent, deterministic, and need no training data. You can read the tuning logic, predict its output, and reason about its behavior in production. A neural network that adjusts your circuit breaker threshold is a black box with no explanation for why it opened your circuit at 3 AM.
+
+The trade-off is that the rules are hand-crafted and may not fit every traffic pattern perfectly. The configuration knobs (`smoothingFactor`, `errorRateThreshold`, `latencyStdDevThreshold`) let you adapt the behavior to your system without touching the code.
+
 ### Pattern Recording
 
 A **pattern** is a single observation of one HTTP request: method, path, status code, duration, and timestamp. Patterns are the raw data from which everything else is derived.

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 };