/** * PredictiveAnalytics -- fitting, forecasting and scoring over numeric series * the caller supplies. * * WHAT WAS HERE: all eight published operations returned * `{ success: true, data: { result: " completed successfully" } }` * with a hard-coded `confidence: 0.85`, having read none of their input. * * WHAT A "MODEL" IS HERE, since the word invites the wrong expectation: an * ordinary-least-squares straight line, returned to the caller as its * coefficients plus the two quantities a prediction interval needs. There is * no training loop, no hidden store and no model file; `train-model` hands back * the fit, and `predict` takes that object straight from the caller. A tool * that kept a model somewhere the caller could not see, and reported * predictions from it, would be unfalsifiable -- which is what the thing this * file replaces was. * * EVERY INTERVAL IS A NORMAL APPROXIMATION and says so in the field name * (`interval: 'normal-95'`). None of them is an exact t interval, and none of * them is a probability that the caller's system will fail. * * An operation whose inputs are absent REFUSES, naming the missing key. */ import type { CacheEngine } from '../../core/cache-engine.js'; import type { TokenCounter } from '../../core/token-counter.js'; import type { MetricsCollector } from '../../core/metrics.js'; import { OutlierMethod } from './analytics-core.js'; import { EXPORT_FORMATS, type ExportFormat } from './render-core.js'; /** * The operations, in one place: the TS union and the published enum are both * derived from this array, so they cannot drift apart. */ export declare const PREDICTIVE_ANALYTICS_OPERATIONS: readonly ["predict", "train-model", "detect-anomalies", "forecast-capacity", "predict-failures", "analyze-trends", "evaluate", "export-model"]; export type PredictiveAnalyticsOperation = (typeof PREDICTIVE_ANALYTICS_OPERATIONS)[number]; /** The one model form this tool fits, named in the model it returns. */ export declare const MODEL_KIND = "ols-linear"; /** The interval every bound here is, named so none of them reads as exact. */ export declare const INTERVAL_KIND = "normal-95"; export { EXPORT_FORMATS, type ExportFormat }; /** * Defaults. Each is a presentation or convention choice, never a stand-in for * a missing input: 3 and 1.5 are the conventional z-score and IQR thresholds, * and 0.3 is a middling EWMA weight -- all three are the caller's to override, * which is why each is reported back in the result. */ export declare const PREDICTIVE_ANALYTICS_DEFAULTS: Readonly<{ zScoreThreshold: 3; iqrThreshold: 1.5; alpha: 0.3; horizon: 1; }>; /** * A fitted line, plus the two quantities needed to widen a prediction interval * for distance from the data: the mean of x, and the sum of squared deviations * about it. They are part of the model because without them `predict` could * only return a point, and a point with no interval reads as certainty. */ export interface PredictiveModel { kind: typeof MODEL_KIND; slope: number; intercept: number; r2: number; residualStdError: number | null; sampleSize: number; xMean: number; sxx: number; } /** One trial group `predict-failures` reads: how many of how many failed. */ export interface FailureRecord { label: string; failures: number; total: number; } export interface PredictiveAnalyticsOptions { operation: PredictiveAnalyticsOperation; /** train-model: paired observations. */ x?: number[]; y?: number[]; /** predict, export-model: the object train-model returned. */ model?: PredictiveModel; /** predict: the x positions to predict at. */ at?: number[]; /** detect-anomalies, forecast-capacity: one series in order. */ values?: number[]; method?: OutlierMethod; threshold?: number; /** forecast-capacity. */ horizon?: number; limit?: number; /** predict-failures. */ records?: FailureRecord[]; upcoming?: number; /** analyze-trends: named series, each in time order. */ series?: Record; alpha?: number; /** evaluate. */ actual?: number[]; predicted?: number[]; /** export-model. */ format?: ExportFormat; useCache?: boolean; } export interface PredictiveAnalyticsResult { success: boolean; operation: string; data: Record; metadata: { tokensUsed: number; tokensSaved: number; cacheHit: boolean; processingTime: number; }; } export declare class PredictiveAnalytics { private cache; private tokenCounter; private metricsCollector; constructor(cache: CacheEngine, tokenCounter: TokenCounter, metricsCollector: MetricsCollector); run(options: PredictiveAnalyticsOptions): Promise; /** * One branch per published operation, each naming the operation it performs. * No fall-through: a value added to the published enum without an * implementation here reaches the default and is refused. */ private compute; /** * Fit y = slope*x + intercept by ordinary least squares and hand the fit * back. The caller holds the model; nothing is stored here. */ private trainModel; /** * Point predictions with a 95% prediction interval, widened for distance * from the data the model was fitted on. The bounds are null when the fit * had too few points to estimate residual spread -- a null interval, not a * zero-width one, because zero width would read as certainty. */ private predict; private detectAnomalies; /** * Extrapolate a series and, when a limit is given, say which step first * crosses it -- at the point estimate and, separately, at the upper bound. * The two differ, and the earlier of them is the one capacity planning * cares about. */ private forecastCapacity; /** * Empirical failure rates with Wilson score intervals, worst first. * * Nothing here predicts an individual failure. It reports the rate each * group actually ran at, an interval that does not collapse to zero on a * clean run, and the expected count over `upcoming` trials, which is that * rate times a number the caller supplied. */ private predictFailures; /** * Per-series trend: the rank test for whether, the fit for how much, and the * last EWMA level for where the series currently sits. */ private analyzeTrends; /** * Score predictions the caller already made against what happened. Nothing * is fitted: both series come in, so these numbers measure the predictions * rather than describing a fit to them. */ private evaluate; private exportModel; } export declare const PREDICTIVEANALYTICSTOOL: { readonly name: "predictive-analytics"; readonly description: "Least-squares fitting, forecasting, anomaly detection and prediction scoring over numeric series you supply"; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly operation: { readonly type: "string"; readonly enum: readonly ["predict", "train-model", "detect-anomalies", "forecast-capacity", "predict-failures", "analyze-trends", "evaluate", "export-model"]; readonly description: "Operation to perform"; }; readonly x: { readonly type: "array"; readonly items: { readonly type: "number"; }; readonly minItems: 2; readonly description: "Independent observations, for train-model"; }; readonly y: { readonly type: "array"; readonly items: { readonly type: "number"; }; readonly minItems: 2; readonly description: "Dependent observations, same length as x"; }; readonly model: { readonly type: "object"; readonly properties: { readonly kind: { readonly const: "ols-linear"; }; readonly slope: { readonly type: "number"; }; readonly intercept: { readonly type: "number"; }; readonly r2: { readonly type: "number"; }; readonly residualStdError: { readonly type: "number"; }; readonly sampleSize: { readonly type: "integer"; readonly minimum: 2; }; readonly xMean: { readonly type: "number"; }; readonly sxx: { readonly type: "number"; readonly minimum: 0; }; }; readonly required: readonly ["kind", "slope", "intercept", "sampleSize", "xMean", "sxx"]; readonly description: "The model train-model returned, passed back unchanged"; }; readonly at: { readonly type: "array"; readonly items: { readonly type: "number"; }; readonly minItems: 1; readonly description: "x positions to predict at"; }; readonly values: { readonly type: "array"; readonly items: { readonly type: "number"; }; readonly minItems: 2; readonly description: "One series in order, for detect-anomalies and forecast-capacity"; }; readonly method: { readonly type: "string"; readonly enum: readonly ["z-score", "iqr"]; readonly default: "z-score"; readonly description: "Which rule flags an anomaly"; }; readonly threshold: { readonly type: "number"; readonly exclusiveMinimum: 0; readonly description: "Standard deviations, or interquartile ranges; defaults to 3 and 1.5 respectively"; }; readonly horizon: { readonly type: "integer"; readonly minimum: 1; readonly default: 1; readonly description: "How many steps forecast-capacity projects"; }; readonly limit: { readonly type: "number"; readonly description: "Capacity ceiling; the forecast reports when it is crossed"; }; readonly records: { readonly type: "array"; readonly items: { readonly type: "object"; readonly properties: { readonly label: { readonly type: "string"; readonly minLength: 1; }; readonly failures: { readonly type: "integer"; readonly minimum: 0; }; readonly total: { readonly type: "integer"; readonly minimum: 1; }; }; readonly required: readonly ["label", "failures", "total"]; readonly additionalProperties: false; }; readonly minItems: 1; readonly description: "Observed trial groups, for predict-failures"; }; readonly upcoming: { readonly type: "integer"; readonly minimum: 0; readonly description: "Trials ahead, for an expected failure count"; }; readonly series: { readonly type: "object"; readonly additionalProperties: { readonly type: "array"; readonly items: { readonly type: "number"; }; }; readonly description: "Named series in time order, for analyze-trends"; }; readonly alpha: { readonly type: "number"; readonly exclusiveMinimum: 0; readonly maximum: 1; readonly default: 0.3; readonly description: "EWMA weight on the newest observation"; }; readonly actual: { readonly type: "array"; readonly items: { readonly type: "number"; }; readonly minItems: 1; readonly description: "What happened, for evaluate"; }; readonly predicted: { readonly type: "array"; readonly items: { readonly type: "number"; }; readonly minItems: 1; readonly description: "What was predicted, same length as actual"; }; readonly format: { readonly type: "string"; readonly enum: readonly ["markdown", "json", "csv"]; readonly description: "Output format for export-model"; }; readonly useCache: { readonly type: "boolean"; readonly default: true; readonly description: "Enable caching"; }; }; readonly required: readonly ["operation"]; readonly anyOf: readonly [{ readonly properties: { readonly operation: { readonly const: "train-model"; }; }; readonly required: readonly ["operation", "x", "y"]; }, { readonly properties: { readonly operation: { readonly const: "predict"; }; }; readonly required: readonly ["operation", "model", "at"]; }, { readonly properties: { readonly operation: { readonly const: "detect-anomalies"; }; }; readonly required: readonly ["operation", "values"]; }, { readonly properties: { readonly operation: { readonly const: "forecast-capacity"; }; }; readonly required: readonly ["operation", "values"]; }, { readonly properties: { readonly operation: { readonly const: "predict-failures"; }; }; readonly required: readonly ["operation", "records"]; }, { readonly properties: { readonly operation: { readonly const: "analyze-trends"; }; }; readonly required: readonly ["operation", "series"]; }, { readonly properties: { readonly operation: { readonly const: "evaluate"; }; }; readonly required: readonly ["operation", "actual", "predicted"]; }, { readonly properties: { readonly operation: { readonly const: "export-model"; }; }; readonly required: readonly ["operation", "model", "format"]; }]; }; }; export declare function runPredictiveAnalytics(options: PredictiveAnalyticsOptions): Promise; //# sourceMappingURL=predictive-analytics.d.ts.map