feat: pure-JS LSTM/GRU + walk-forward + HMM regime [3.8.0]

Author: MeridianAlgo-Developer

CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.8.0] - 2026-05-03
+
+### Added
+- **Pure-JS RNN cells** (`src/ml/lstm.ts`, `src/ml/gru.ts`):
+  - `LSTMCell` with `[i, f, g, o]` gate ordering, weights `Wi[4H×N]`, `Wh[4H×H]`, `b[4H]`.
+  - `GRUCell` with `[r, z, n]` gate ordering, weights `Wi`, `Wh`, `bi`, `bh`.
+  - Forward pass only — load pre-trained weights from Python/JAX for inference.
+- **Walk-forward validation** (`src/ml/walk-forward.ts`):
+  - `walkForward(X, y, cfg)` with `expanding` and `rolling` modes.
+  - Per-fold MSE/MAE/R² plus combined out-of-sample predictions.
+- **Feature engineering** (`src/ml/feature-engineer.ts`):
+  - `lagFeatures`, `rollingMean`, `rollingStd`, `logReturns`, `simpleReturns`, `zScore`, `minMaxScale`, `diff`.
+- **HMM regime detection** (`src/ml/hmm-regime.ts`):
+  - `trainHMM` — Gaussian-emission Baum-Welch with scaled forward-backward.
+  - `viterbi` — log-domain decoding.
+- Docs: `docs/ML.md`.
+- Tests: `tests/ml.test.ts` (10 tests, including 2-state regime decode >70% accuracy).
+
 ## [3.7.0] - 2026-05-03
 
 ### Added

docs/ML.md

@@ -0,0 +1,118 @@
+# Machine Learning (Pure-JS)
+
+Zero-dependency ML primitives for time-series forecasting and regime detection.
+No native bindings, no tfjs — runs in Node, Deno, Bun, browsers.
+
+## Modules
+
+| Module | Purpose |
+|--------|---------|
+| `LSTMCell` / `GRUCell` | Forward-pass RNN cells |
+| `walkForward` | Time-series cross-validation |
+| Feature engineering | Lags, rolling stats, returns, scaling |
+| `trainHMM` / `viterbi` | Gaussian HMM regime detection |
+
+## LSTM / GRU Forward Pass
+
+Pre-trained weights only (no backprop). Useful for deploying models trained
+elsewhere (Python, JAX) into pure-JS runtimes.
+
+```typescript
+import { LSTMCell, randomLSTMWeights } from 'meridianalgo';
+
+const inputSize = 5;
+const hiddenSize = 16;
+const cell = new LSTMCell(randomLSTMWeights(inputSize, hiddenSize));
+
+const sequence = [/* ... [number[]] ... */];
+const { h, c } = cell.forward(sequence);
+// h: final hidden state (length hiddenSize)
+```
+
+GRU API mirrors LSTM, returns only `h`.
+
+Gate ordering:
+- LSTM: `[i, f, g, o]` (input, forget, candidate, output)
+- GRU: `[r, z, n]` (reset, update, candidate)
+
+Weight shapes:
+- LSTM: `Wi[4H × N]`, `Wh[4H × H]`, `b[4H]`
+- GRU: `Wi[3H × N]`, `Wh[3H × H]`, `bi[3H]`, `bh[3H]`
+
+## Walk-Forward Validation
+
+Time-series CV that respects causality. Two modes:
+
+```typescript
+import { walkForward } from 'meridianalgo';
+
+const result = walkForward(X, y, {
+  mode: 'expanding',  // or 'rolling'
+  initialTrainSize: 100,
+  testSize: 20,
+  step: 20,
+  fit: (Xtrain, ytrain) => trainModel(Xtrain, ytrain),
+  predict: (model, Xtest) => model.predict(Xtest),
+});
+
+result.folds;              // per-fold {predictions, actual, mse, mae, rSquared}
+result.combinedPredictions; // concatenated out-of-sample predictions
+result.meanMse;
+result.meanMae;
+```
+
+- **Expanding**: train window grows each fold (`[0, end)`).
+- **Rolling**: train window slides at fixed size.
+
+## Feature Engineering
+
+```typescript
+import {
+  lagFeatures, rollingMean, rollingStd,
+  logReturns, simpleReturns,
+  zScore, minMaxScale, diff,
+} from 'meridianalgo';
+
+const lags = lagFeatures(prices, [1, 5, 10]);   // matrix [n × 3]
+const ma = rollingMean(prices, 20);
+const sd = rollingStd(prices, 20);
+const r = logReturns(prices);
+const z = zScore(values);                        // (x - μ)/σ
+const scaled = minMaxScale(values);              // [0, 1]
+```
+
+NaN-padded arrays preserve index alignment with original series.
+
+## HMM Regime Detection
+
+Gaussian-emission HMM with Baum-Welch training (forward-backward + scaling)
+and Viterbi decoding in log-domain.
+
+```typescript
+import { trainHMM, viterbi } from 'meridianalgo';
+
+const observations = returns;  // 1-D series
+const k = 2;                   // num regimes (e.g. bull/bear)
+
+const { params, logLik, iterations } = trainHMM(observations, k, {
+  maxIter: 100,
+  tol: 1e-4,
+});
+
+const states = viterbi(observations, params);
+// states[t] ∈ {0, 1, ..., k-1}
+```
+
+`HMMParams`:
+- `pi[k]` — initial state distribution
+- `A[k][k]` — transition matrix
+- `mu[k]`, `sigma[k]` — emission Gaussian params
+
+## Limitations
+
+- No autograd / training for RNN cells (forward-only).
+- HMM Gaussian emissions are univariate scalar.
+- For heavy training workloads use Python — load weights here for inference.
+
+See also: `INDICATORS-PATTERNS.md` for streaming indicators that pair well
+with online ML inference.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "meridianalgo",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "description": "Professional-grade quantitative finance framework for JavaScript/TypeScript - algorithmic trading, backtesting, risk management, and portfolio optimization",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

src/index.ts

@@ -72,5 +72,8 @@ export * from './indicators/range-vol';
 // Microstructure (order book, spread estimators, market impact)
 export * from './microstructure';
 
+// Machine learning (LSTM/GRU forward pass, walk-forward, features, HMM regimes)
+export * from './ml';
+
 // CLI (not exported as class usually, but internal)
 // export * from './cli';

src/ml/feature-engineer.ts

@@ -0,0 +1,89 @@
+/**
+ * Feature engineering helpers — lag features, rolling statistics, returns,
+ * z-score normalization, and standard time-series transforms.
+ */
+
+/** Build lag features: [x_{t-1}, x_{t-2}, ..., x_{t-K}]. */
+export function lagFeatures(xs: readonly number[], lags: number): number[][] {
+  if (lags <= 0) throw new Error('lagFeatures: lags must be > 0');
+  const out: number[][] = [];
+  for (let i = lags; i < xs.length; i++) {
+    const row: number[] = [];
+    for (let k = 1; k <= lags; k++) row.push(xs[i - k]);
+    out.push(row);
+  }
+  return out;
+}
+
+/** Rolling mean. */
+export function rollingMean(xs: readonly number[], n: number): number[] {
+  const out: number[] = new Array(xs.length).fill(NaN);
+  let sum = 0;
+  for (let i = 0; i < xs.length; i++) {
+    sum += xs[i];
+    if (i >= n) sum -= xs[i - n];
+    if (i >= n - 1) out[i] = sum / n;
+  }
+  return out;
+}
+
+/** Rolling standard deviation. */
+export function rollingStd(xs: readonly number[], n: number): number[] {
+  const out: number[] = new Array(xs.length).fill(NaN);
+  for (let i = n - 1; i < xs.length; i++) {
+    let mean = 0;
+    for (let j = i - n + 1; j <= i; j++) mean += xs[j];
+    mean /= n;
+    let v = 0;
+    for (let j = i - n + 1; j <= i; j++) v += (xs[j] - mean) ** 2;
+    out[i] = Math.sqrt(v / (n - 1));
+  }
+  return out;
+}
+
+/** Log returns. */
+export function logReturns(prices: readonly number[]): number[] {
+  const out: number[] = new Array(prices.length).fill(NaN);
+  for (let i = 1; i < prices.length; i++) out[i] = Math.log(prices[i] / prices[i - 1]);
+  return out;
+}
+
+/** Simple returns. */
+export function simpleReturns(prices: readonly number[]): number[] {
+  const out: number[] = new Array(prices.length).fill(NaN);
+  for (let i = 1; i < prices.length; i++) out[i] = prices[i] / prices[i - 1] - 1;
+  return out;
+}
+
+/** Z-score normalization (population stats). */
+export function zScore(xs: readonly number[]): number[] {
+  const n = xs.length;
+  if (n === 0) return [];
+  const mean = xs.reduce((s, v) => s + v, 0) / n;
+  let v = 0;
+  for (const x of xs) v += (x - mean) ** 2;
+  const sd = Math.sqrt(v / n);
+  if (sd === 0) return new Array(n).fill(0);
+  return xs.map((x) => (x - mean) / sd);
+}
+
+/** Min-max normalization to [0, 1]. */
+export function minMaxScale(xs: readonly number[]): number[] {
+  if (xs.length === 0) return [];
+  let lo = Infinity;
+  let hi = -Infinity;
+  for (const x of xs) {
+    if (x < lo) lo = x;
+    if (x > hi) hi = x;
+  }
+  const r = hi - lo;
+  if (r === 0) return xs.map(() => 0);
+  return xs.map((x) => (x - lo) / r);
+}
+
+/** First difference (xs[i] - xs[i-1]). */
+export function diff(xs: readonly number[], lag = 1): number[] {
+  const out: number[] = new Array(xs.length).fill(NaN);
+  for (let i = lag; i < xs.length; i++) out[i] = xs[i] - xs[i - lag];
+  return out;
+}

src/ml/gru.ts

@@ -0,0 +1,79 @@
+/**
+ * Pure-JS GRU cell — forward-pass inference only.
+ */
+
+export interface GRUWeights {
+  /** input-to-hidden: shape [3*hiddenSize, inputSize]. Order: [r, z, n]. */
+  Wi: number[][];
+  /** hidden-to-hidden: shape [3*hiddenSize, hiddenSize]. */
+  Wh: number[][];
+  /** input bias: shape [3*hiddenSize]. */
+  bi: number[];
+  /** hidden bias: shape [3*hiddenSize]. */
+  bh: number[];
+}
+
+const sigmoid = (x: number) => 1 / (1 + Math.exp(-x));
+const tanh = Math.tanh;
+
+function matVec(M: readonly (readonly number[])[], v: readonly number[]): number[] {
+  const out = new Array(M.length).fill(0);
+  for (let i = 0; i < M.length; i++) {
+    let s = 0;
+    const row = M[i];
+    for (let j = 0; j < v.length; j++) s += row[j] * v[j];
+    out[i] = s;
+  }
+  return out;
+}
+
+export class GRUCell {
+  readonly hiddenSize: number;
+  readonly inputSize: number;
+
+  constructor(public readonly weights: GRUWeights) {
+    const threeH = weights.bi.length;
+    if (threeH % 3 !== 0) throw new Error('GRUCell: bias length must be multiple of 3');
+    this.hiddenSize = threeH / 3;
+    this.inputSize = weights.Wi[0].length;
+  }
+
+  step(x: readonly number[], h: readonly number[]): number[] {
+    const H = this.hiddenSize;
+    const xi = matVec(this.weights.Wi, x);
+    const hi = matVec(this.weights.Wh, h);
+    const r: number[] = new Array(H);
+    const z: number[] = new Array(H);
+    const n: number[] = new Array(H);
+    for (let k = 0; k < H; k++) {
+      r[k] = sigmoid(xi[k] + this.weights.bi[k] + hi[k] + this.weights.bh[k]);
+      z[k] = sigmoid(xi[k + H] + this.weights.bi[k + H] + hi[k + H] + this.weights.bh[k + H]);
+      n[k] = tanh(xi[k + 2 * H] + this.weights.bi[k + 2 * H] + r[k] * (hi[k + 2 * H] + this.weights.bh[k + 2 * H]));
+    }
+    const out: number[] = new Array(H);
+    for (let k = 0; k < H; k++) out[k] = (1 - z[k]) * n[k] + z[k] * h[k];
+    return out;
+  }
+
+  forward(sequence: readonly (readonly number[])[]): number[] {
+    let h = new Array(this.hiddenSize).fill(0);
+    for (const x of sequence) h = this.step(x, h);
+    return h;
+  }
+}
+
+export function randomGRUWeights(inputSize: number, hiddenSize: number, scale = 0.1, seed = 1): GRUWeights {
+  let s = seed;
+  const rng = () => {
+    s = (s * 1664525 + 1013904223) | 0;
+    return ((s >>> 0) / 0x100000000 - 0.5) * 2;
+  };
+  const threeH = 3 * hiddenSize;
+  const Wi: number[][] = Array.from({ length: threeH }, () =>
+    Array.from({ length: inputSize }, () => rng() * scale),
+  );
+  const Wh: number[][] = Array.from({ length: threeH }, () =>
+    Array.from({ length: hiddenSize }, () => rng() * scale),
+  );
+  return { Wi, Wh, bi: new Array(threeH).fill(0), bh: new Array(threeH).fill(0) };
+}