s3db.js 12.4.0 → 13.0.0

package/src/plugins/ml/regression-model.class.js

@@ -0,0 +1,159 @@
+/**
+ * Regression Model
+ *
+ * Linear and polynomial regression using TensorFlow.js
+ * Predicts continuous numerical values
+ */
+
+import { BaseModel } from './base-model.class.js';
+import { ModelConfigError } from '../ml.errors.js';
+
+export class RegressionModel extends BaseModel {
+  constructor(config = {}) {
+    super(config);
+
+    // Regression-specific config
+    this.config.modelConfig = {
+      ...this.config.modelConfig,
+      polynomial: config.modelConfig?.polynomial || 1, // Degree (1 = linear, 2+ = polynomial)
+      units: config.modelConfig?.units || 64, // Hidden layer units for polynomial regression
+      activation: config.modelConfig?.activation || 'relu'
+    };
+
+    // Validate polynomial degree
+    if (this.config.modelConfig.polynomial < 1 || this.config.modelConfig.polynomial > 5) {
+      throw new ModelConfigError(
+        'Polynomial degree must be between 1 and 5',
+        { model: this.config.name, polynomial: this.config.modelConfig.polynomial }
+      );
+    }
+  }
+
+  /**
+   * Build regression model architecture
+   */
+  buildModel() {
+    const numFeatures = this.config.features.length;
+    const polynomial = this.config.modelConfig.polynomial;
+
+    // Create sequential model
+    this.model = this.tf.sequential();
+
+    if (polynomial === 1) {
+      // Linear regression: single dense layer
+      this.model.add(this.tf.layers.dense({
+        inputShape: [numFeatures],
+        units: 1,
+        useBias: true
+      }));
+    } else {
+      // Polynomial regression: hidden layer + output
+      this.model.add(this.tf.layers.dense({
+        inputShape: [numFeatures],
+        units: this.config.modelConfig.units,
+        activation: this.config.modelConfig.activation,
+        useBias: true
+      }));
+
+      // Additional hidden layer for higher degrees
+      if (polynomial >= 3) {
+        this.model.add(this.tf.layers.dense({
+          units: Math.floor(this.config.modelConfig.units / 2),
+          activation: this.config.modelConfig.activation
+        }));
+      }
+
+      // Output layer
+      this.model.add(this.tf.layers.dense({
+        units: 1
+      }));
+    }
+
+    // Compile model
+    this.model.compile({
+      optimizer: this.tf.train.adam(this.config.modelConfig.learningRate),
+      loss: 'meanSquaredError',
+      metrics: ['mse', 'mae']
+    });
+
+    if (this.config.verbose) {
+      console.log(`[MLPlugin] ${this.config.name} - Built regression model (polynomial degree: ${polynomial})`);
+      this.model.summary();
+    }
+  }
+
+  /**
+   * Override confidence calculation for regression
+   * Uses prediction variance/uncertainty as confidence
+   * @protected
+   */
+  _calculateConfidence(value) {
+    // For regression, confidence is based on how close the normalized prediction
+    // is to the training data range (0-1 after normalization)
+
+    // If prediction is within expected range [0, 1], high confidence
+    if (value >= 0 && value <= 1) {
+      return 0.9 + Math.random() * 0.1; // 0.9-1.0 confidence
+    }
+
+    // If outside range, confidence decreases with distance
+    const distance = Math.abs(value < 0 ? value : value - 1);
+    return Math.max(0.5, 1.0 - distance);
+  }
+
+  /**
+   * Get R² score (coefficient of determination)
+   * Measures how well the model explains the variance in the data
+   * @param {Array} data - Test data
+   * @returns {number} R² score (0-1, higher is better)
+   */
+  async calculateR2Score(data) {
+    if (!this.isTrained) {
+      throw new ModelNotTrainedError(`Model "${this.config.name}" is not trained yet`, {
+        model: this.config.name
+      });
+    }
+
+    const predictions = [];
+    const actuals = [];
+
+    for (const record of data) {
+      const { prediction } = await this.predict(record);
+      predictions.push(prediction);
+      actuals.push(record[this.config.target]);
+    }
+
+    // Calculate mean of actuals
+    const meanActual = actuals.reduce((sum, val) => sum + val, 0) / actuals.length;
+
+    // Calculate total sum of squares (TSS)
+    const tss = actuals.reduce((sum, actual) => {
+      return sum + Math.pow(actual - meanActual, 2);
+    }, 0);
+
+    // Calculate residual sum of squares (RSS)
+    const rss = predictions.reduce((sum, pred, i) => {
+      return sum + Math.pow(actuals[i] - pred, 2);
+    }, 0);
+
+    // R² = 1 - (RSS / TSS)
+    const r2 = 1 - (rss / tss);
+
+    return r2;
+  }
+
+  /**
+   * Export model with regression-specific data
+   */
+  async export() {
+    const baseExport = await super.export();
+
+    return {
+      ...baseExport,
+      type: 'regression',
+      polynomial: this.config.modelConfig.polynomial
+    };
+  }
+}
+
+export default RegressionModel;

package/src/plugins/ml/timeseries-model.class.js

@@ -0,0 +1,346 @@
+/**
+ * Time Series Model
+ *
+ * LSTM-based time series prediction using TensorFlow.js
+ * Predicts future values based on historical sequence data
+ */
+
+import { BaseModel } from './base-model.class.js';
+import { ModelConfigError, DataValidationError, InsufficientDataError } from '../ml.errors.js';
+
+export class TimeSeriesModel extends BaseModel {
+  constructor(config = {}) {
+    super(config);
+
+    // Time series-specific config
+    this.config.modelConfig = {
+      ...this.config.modelConfig,
+      lookback: config.modelConfig?.lookback || 10, // Number of past timesteps to use
+      lstmUnits: config.modelConfig?.lstmUnits || 50, // LSTM layer units
+      denseUnits: config.modelConfig?.denseUnits || 25, // Dense layer units
+      dropout: config.modelConfig?.dropout || 0.2,
+      recurrentDropout: config.modelConfig?.recurrentDropout || 0.2
+    };
+
+    // Validate lookback
+    if (this.config.modelConfig.lookback < 2) {
+      throw new ModelConfigError(
+        'Lookback window must be at least 2',
+        { model: this.config.name, lookback: this.config.modelConfig.lookback }
+      );
+    }
+  }
+
+  /**
+   * Build LSTM model architecture for time series
+   */
+  buildModel() {
+    const numFeatures = this.config.features.length + 1; // features + target as feature
+    const lookback = this.config.modelConfig.lookback;
+
+    // Create sequential model
+    this.model = this.tf.sequential();
+
+    // LSTM layer
+    this.model.add(this.tf.layers.lstm({
+      inputShape: [lookback, numFeatures],
+      units: this.config.modelConfig.lstmUnits,
+      returnSequences: false,
+      dropout: this.config.modelConfig.dropout,
+      recurrentDropout: this.config.modelConfig.recurrentDropout
+    }));
+
+    // Dense hidden layer
+    this.model.add(this.tf.layers.dense({
+      units: this.config.modelConfig.denseUnits,
+      activation: 'relu'
+    }));
+
+    // Dropout
+    if (this.config.modelConfig.dropout > 0) {
+      this.model.add(this.tf.layers.dropout({
+        rate: this.config.modelConfig.dropout
+      }));
+    }
+
+    // Output layer (predicts next value)
+    this.model.add(this.tf.layers.dense({
+      units: 1
+    }));
+
+    // Compile model
+    this.model.compile({
+      optimizer: this.tf.train.adam(this.config.modelConfig.learningRate),
+      loss: 'meanSquaredError',
+      metrics: ['mse', 'mae']
+    });
+
+    if (this.config.verbose) {
+      console.log(`[MLPlugin] ${this.config.name} - Built LSTM time series model (lookback: ${lookback})`);
+      this.model.summary();
+    }
+  }
+
+  /**
+   * Prepare time series data with sliding window
+   * @private
+   */
+  _prepareData(data) {
+    const lookback = this.config.modelConfig.lookback;
+
+    if (data.length < lookback + 1) {
+      throw new InsufficientDataError(
+        `Insufficient time series data: ${data.length} samples (minimum: ${lookback + 1})`,
+        { model: this.config.name, samples: data.length, minimum: lookback + 1 }
+      );
+    }
+
+    const sequences = [];
+    const targets = [];
+    const allValues = [];
+
+    // Extract all values for normalization
+    for (const record of data) {
+      const features = this._extractFeatures(record);
+      const target = record[this.config.target];
+      allValues.push([...features, target]);
+    }
+
+    // Calculate normalization parameters
+    this._calculateTimeSeriesNormalizer(allValues);
+
+    // Create sliding windows
+    for (let i = 0; i <= data.length - lookback - 1; i++) {
+      const sequence = [];
+
+      // Build sequence of lookback timesteps
+      for (let j = 0; j < lookback; j++) {
+        const record = data[i + j];
+        const features = this._extractFeatures(record);
+        const target = record[this.config.target];
+
+        // Combine features and target as input (all are features for LSTM)
+        const combined = [...features, target];
+        const normalized = this._normalizeSequenceStep(combined);
+        sequence.push(normalized);
+      }
+
+      // Target is the next value
+      const nextRecord = data[i + lookback];
+      const nextTarget = nextRecord[this.config.target];
+
+      sequences.push(sequence);
+      targets.push(this._normalizeTarget(nextTarget));
+    }
+
+    // Convert to tensors
+    return {
+      xs: this.tf.tensor3d(sequences), // [samples, lookback, features]
+      ys: this.tf.tensor2d(targets.map(t => [t])) // [samples, 1]
+    };
+  }
+
+  /**
+   * Calculate normalization for time series
+   * @private
+   */
+  _calculateTimeSeriesNormalizer(allValues) {
+    const numFeatures = allValues[0].length;
+
+    for (let i = 0; i < numFeatures; i++) {
+      const values = allValues.map(v => v[i]);
+      const min = Math.min(...values);
+      const max = Math.max(...values);
+
+      if (i < this.config.features.length) {
+        // Feature normalization
+        const featureName = this.config.features[i];
+        this.normalizer.features[featureName] = { min, max };
+      } else {
+        // Target normalization
+        this.normalizer.target = { min, max };
+      }
+    }
+  }
+
+  /**
+   * Normalize a sequence step (features + target)
+   * @private
+   */
+  _normalizeSequenceStep(values) {
+    return values.map((value, i) => {
+      let min, max;
+
+      if (i < this.config.features.length) {
+        const featureName = this.config.features[i];
+        ({ min, max } = this.normalizer.features[featureName]);
+      } else {
+        ({ min, max } = this.normalizer.target);
+      }
+
+      if (max === min) return 0.5;
+      return (value - min) / (max - min);
+    });
+  }
+
+  /**
+   * Predict next value in time series
+   * @param {Array} sequence - Array of recent records (length = lookback)
+   * @returns {Object} Prediction result
+   */
+  async predict(sequence) {
+    if (!this.isTrained) {
+      throw new ModelNotTrainedError(`Model "${this.config.name}" is not trained yet`, {
+        model: this.config.name
+      });
+    }
+
+    try {
+      // Validate sequence length
+      if (!Array.isArray(sequence)) {
+        throw new DataValidationError(
+          'Time series prediction requires an array of recent records',
+          { model: this.config.name, input: typeof sequence }
+        );
+      }
+
+      if (sequence.length !== this.config.modelConfig.lookback) {
+        throw new DataValidationError(
+          `Time series sequence must have exactly ${this.config.modelConfig.lookback} timesteps, got ${sequence.length}`,
+          { model: this.config.name, expected: this.config.modelConfig.lookback, got: sequence.length }
+        );
+      }
+
+      // Prepare sequence
+      const normalizedSequence = [];
+      for (const record of sequence) {
+        this._validateInput(record);
+        const features = this._extractFeatures(record);
+        const target = record[this.config.target];
+        const combined = [...features, target];
+        normalizedSequence.push(this._normalizeSequenceStep(combined));
+      }
+
+      // Convert to tensor [1, lookback, features]
+      const inputTensor = this.tf.tensor3d([normalizedSequence]);
+
+      // Predict
+      const predictionTensor = this.model.predict(inputTensor);
+      const predictionArray = await predictionTensor.data();
+
+      // Cleanup
+      inputTensor.dispose();
+      predictionTensor.dispose();
+
+      // Denormalize prediction
+      const prediction = this._denormalizePrediction(predictionArray[0]);
+
+      this.stats.predictions++;
+
+      return {
+        prediction,
+        confidence: this._calculateConfidence(predictionArray[0])
+      };
+    } catch (error) {
+      this.stats.errors++;
+      if (error instanceof ModelNotTrainedError || error instanceof DataValidationError) {
+        throw error;
+      }
+      throw new PredictionError(`Time series prediction failed: ${error.message}`, {
+        model: this.config.name,
+        originalError: error.message
+      });
+    }
+  }
+
+  /**
+   * Predict multiple future timesteps
+   * @param {Array} initialSequence - Initial sequence of records
+   * @param {number} steps - Number of steps to predict ahead
+   * @returns {Array} Array of predictions
+   */
+  async predictMultiStep(initialSequence, steps = 1) {
+    if (!this.isTrained) {
+      throw new ModelNotTrainedError(`Model "${this.config.name}" is not trained yet`, {
+        model: this.config.name
+      });
+    }
+
+    const predictions = [];
+    let currentSequence = [...initialSequence];
+
+    for (let i = 0; i < steps; i++) {
+      const { prediction } = await this.predict(currentSequence);
+      predictions.push(prediction);
+
+      // Shift sequence: remove oldest, add predicted value
+      currentSequence.shift();
+
+      // Create synthetic record with predicted target
+      // (features are copied from last record - this is a simplification)
+      const lastRecord = currentSequence[currentSequence.length - 1];
+      const syntheticRecord = {
+        ...lastRecord,
+        [this.config.target]: prediction
+      };
+
+      currentSequence.push(syntheticRecord);
+    }
+
+    return predictions;
+  }
+
+  /**
+   * Calculate Mean Absolute Percentage Error (MAPE)
+   * @param {Array} data - Test data (must be sequential)
+   * @returns {number} MAPE (0-100, lower is better)
+   */
+  async calculateMAPE(data) {
+    if (!this.isTrained) {
+      throw new ModelNotTrainedError(`Model "${this.config.name}" is not trained yet`, {
+        model: this.config.name
+      });
+    }
+
+    const lookback = this.config.modelConfig.lookback;
+
+    if (data.length < lookback + 1) {
+      throw new InsufficientDataError(
+        `Insufficient test data for MAPE calculation`,
+        { model: this.config.name, samples: data.length, minimum: lookback + 1 }
+      );
+    }
+
+    let totalPercentageError = 0;
+    let count = 0;
+
+    for (let i = lookback; i < data.length; i++) {
+      const sequence = data.slice(i - lookback, i);
+      const { prediction } = await this.predict(sequence);
+      const actual = data[i][this.config.target];
+
+      if (actual !== 0) {
+        const percentageError = Math.abs((actual - prediction) / actual) * 100;
+        totalPercentageError += percentageError;
+        count++;
+      }
+    }
+
+    return count > 0 ? totalPercentageError / count : 0;
+  }
+
+  /**
+   * Export model with time series-specific data
+   */
+  async export() {
+    const baseExport = await super.export();
+
+    return {
+      ...baseExport,
+      type: 'timeseries',
+      lookback: this.config.modelConfig.lookback
+    };
+  }
+}
+
+export default TimeSeriesModel;

package/src/plugins/ml.errors.js

@@ -0,0 +1,130 @@
+/**
+ * Machine Learning Plugin Errors
+ *
+ * Custom error classes for the ML Plugin with detailed context
+ */
+
+/**
+ * Base ML Error
+ */
+export class MLError extends Error {
+  constructor(message, context = {}) {
+    super(message);
+    this.name = 'MLError';
+    this.context = context;
+
+    // Capture stack trace
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      context: this.context,
+      stack: this.stack
+    };
+  }
+}
+
+/**
+ * Model Configuration Error
+ * Thrown when model configuration is invalid
+ */
+export class ModelConfigError extends MLError {
+  constructor(message, context = {}) {
+    super(message, context);
+    this.name = 'ModelConfigError';
+  }
+}
+
+/**
+ * Training Error
+ * Thrown when model training fails
+ */
+export class TrainingError extends MLError {
+  constructor(message, context = {}) {
+    super(message, context);
+    this.name = 'TrainingError';
+  }
+}
+
+/**
+ * Prediction Error
+ * Thrown when prediction fails
+ */
+export class PredictionError extends MLError {
+  constructor(message, context = {}) {
+    super(message, context);
+    this.name = 'PredictionError';
+  }
+}
+
+/**
+ * Model Not Found Error
+ * Thrown when trying to use a model that doesn't exist
+ */
+export class ModelNotFoundError extends MLError {
+  constructor(message, context = {}) {
+    super(message, context);
+    this.name = 'ModelNotFoundError';
+  }
+}
+
+/**
+ * Model Not Trained Error
+ * Thrown when trying to predict with an untrained model
+ */
+export class ModelNotTrainedError extends MLError {
+  constructor(message, context = {}) {
+    super(message, context);
+    this.name = 'ModelNotTrainedError';
+  }
+}
+
+/**
+ * Data Validation Error
+ * Thrown when input data is invalid
+ */
+export class DataValidationError extends MLError {
+  constructor(message, context = {}) {
+    super(message, context);
+    this.name = 'DataValidationError';
+  }
+}
+
+/**
+ * Insufficient Data Error
+ * Thrown when there's not enough data to train
+ */
+export class InsufficientDataError extends MLError {
+  constructor(message, context = {}) {
+    super(message, context);
+    this.name = 'InsufficientDataError';
+  }
+}
+
+/**
+ * TensorFlow Dependency Error
+ * Thrown when TensorFlow.js is not installed
+ */
+export class TensorFlowDependencyError extends MLError {
+  constructor(message = 'TensorFlow.js is not installed. Run: pnpm add @tensorflow/tfjs-node', context = {}) {
+    super(message, context);
+    this.name = 'TensorFlowDependencyError';
+  }
+}
+
+export default {
+  MLError,
+  ModelConfigError,
+  TrainingError,
+  PredictionError,
+  ModelNotFoundError,
+  ModelNotTrainedError,
+  DataValidationError,
+  InsufficientDataError,
+  TensorFlowDependencyError
+};