@openfinclaw/fin-strategy-engine 0.0.1

package/src/builtin-strategies/regime-adaptive.test.ts

@@ -0,0 +1,210 @@
+import { describe, expect, it } from "vitest";
+import type { OHLCV } from "../../../fin-shared-types/src/types.js";
+import { BacktestEngine } from "../backtest-engine.js";
+import type { BacktestConfig } from "../types.js";
+import { createRegimeAdaptive } from "./regime-adaptive.js";
+
+function makeBar(index: number, close: number, overrides?: Partial<OHLCV>): OHLCV {
+  return {
+    timestamp: 1000000 + index * 86400000,
+    open: close,
+    high: close * 1.01,
+    low: close * 0.99,
+    close,
+    volume: 1000,
+    ...overrides,
+  };
+}
+
+const config: BacktestConfig = {
+  capital: 10000,
+  commissionRate: 0,
+  slippageBps: 0,
+  market: "crypto",
+};
+
+describe("Regime Adaptive strategy", () => {
+  it("creates strategy with default parameters", () => {
+    const strategy = createRegimeAdaptive();
+    expect(strategy.id).toBe("regime-adaptive");
+    expect(strategy.name).toBe("Regime Adaptive");
+    expect(strategy.parameters.bbPeriod).toBe(20);
+    expect(strategy.parameters.fastEma).toBe(12);
+    expect(strategy.parameters.slowEma).toBe(26);
+    expect(strategy.parameters.rsiPeriod).toBe(14);
+    expect(strategy.parameters.macdFast).toBe(12);
+    expect(strategy.parameters.macdSlow).toBe(26);
+    expect(strategy.parameters.macdSignal).toBe(9);
+    expect(strategy.parameters.atrPeriod).toBe(14);
+    expect(strategy.parameters.bandWidthThreshold).toBe(0.04);
+    expect(strategy.parameters.emaSepThreshold).toBe(0.02);
+    expect(strategy.parameters.rsiOversoldMR).toBe(30);
+    expect(strategy.parameters.rsiOverboughtMR).toBe(70);
+    expect(strategy.parameters.rsiTrendMinimum).toBe(45);
+    expect(strategy.parameters.atrStopMultiplier).toBe(2.0);
+    expect(strategy.parameters.maxSizePct).toBe(70);
+  });
+
+  it("creates strategy with custom parameters", () => {
+    const strategy = createRegimeAdaptive({
+      bbPeriod: 15,
+      fastEma: 8,
+      slowEma: 21,
+      rsiPeriod: 10,
+      macdFast: 8,
+      macdSlow: 21,
+      macdSignal: 5,
+      atrPeriod: 10,
+      bandWidthThreshold: 0.05,
+      emaSepThreshold: 0.03,
+      rsiOversoldMR: 25,
+      rsiOverboughtMR: 75,
+      rsiTrendMinimum: 50,
+      atrStopMultiplier: 2.5,
+      maxSizePct: 60,
+      symbol: "ETH/USDT",
+    });
+    expect(strategy.parameters.bbPeriod).toBe(15);
+    expect(strategy.parameters.fastEma).toBe(8);
+    expect(strategy.parameters.slowEma).toBe(21);
+    expect(strategy.parameters.macdFast).toBe(8);
+    expect(strategy.parameters.maxSizePct).toBe(60);
+    expect(strategy.symbols).toEqual(["ETH/USDT"]);
+  });
+
+  it("returns null during warm-up", async () => {
+    // Only 10 bars — not enough for any indicator to produce valid values
+    const data: OHLCV[] = [];
+    for (let i = 0; i < 10; i++) {
+      data.push(makeBar(i, 100 + i));
+    }
+
+    const strategy = createRegimeAdaptive();
+    const engine = new BacktestEngine();
+    const result = await engine.run(strategy, data, config);
+
+    expect(result.totalTrades).toBe(0);
+  });
+
+  it("trades in trend mode when BB expands", async () => {
+    // Use small indicator periods so regime detection kicks in quickly
+    const strategy = createRegimeAdaptive({
+      bbPeriod: 5,
+      fastEma: 3,
+      slowEma: 5,
+      macdFast: 3,
+      macdSlow: 5,
+      macdSignal: 2,
+      rsiPeriod: 3,
+      atrPeriod: 3,
+      bandWidthThreshold: 0.03,
+      emaSepThreshold: 0.01,
+    });
+
+    const prices: number[] = [];
+    // Phase 1: 15 bars flat at 100 (warm-up, tight bands → mean-reversion)
+    for (let i = 0; i < 15; i++) prices.push(100);
+    // Phase 2: 15 bars sharp rise to ~140 (expanding BB + EMA separation → trend)
+    for (let i = 1; i <= 15; i++) {
+      // Accelerating rise for wider bands and stronger EMA separation
+      prices.push(100 + i * i * 0.18);
+    }
+
+    const data = prices.map((p, i) => makeBar(i, p));
+    const engine = new BacktestEngine();
+    const result = await engine.run(strategy, data, config);
+
+    // With expanding bands and rising EMAs, strategy should detect trend and trade
+    expect(result.totalTrades).toBeGreaterThanOrEqual(1);
+  });
+
+  it("trades in mean-reversion mode in tight range", async () => {
+    const strategy = createRegimeAdaptive({
+      bbPeriod: 5,
+      fastEma: 3,
+      slowEma: 5,
+      macdFast: 3,
+      macdSlow: 5,
+      macdSignal: 2,
+      rsiPeriod: 3,
+      atrPeriod: 3,
+      bandWidthThreshold: 0.03,
+      emaSepThreshold: 0.01,
+      rsiOversoldMR: 40,
+      rsiOverboughtMR: 65,
+    });
+
+    const prices: number[] = [];
+    // Phase 1: 10 bars at 100 (warm-up)
+    for (let i = 0; i < 10; i++) prices.push(100);
+    // Phase 2: establish some volatility so BB bands widen slightly
+    prices.push(101, 99, 101, 99, 100);
+    // Phase 3: sharp dip below BB lower to push RSI low
+    prices.push(97, 94, 91);
+    // Phase 4: slight uptick — RSI turns up while still below lower band
+    prices.push(92);
+    // Phase 5: recovery back to the middle for MR sell
+    prices.push(95, 98, 100, 102, 100);
+
+    const data = prices.map((p, i) => makeBar(i, p));
+    const engine = new BacktestEngine();
+    const result = await engine.run(strategy, data, config);
+
+    // Mean-reversion should detect the dip below BB lower and trade
+    expect(result.totalTrades).toBeGreaterThanOrEqual(1);
+  });
+
+  it("forces exit on regime switch after 5 bars", async () => {
+    const strategy = createRegimeAdaptive({
+      bbPeriod: 5,
+      fastEma: 3,
+      slowEma: 5,
+      macdFast: 3,
+      macdSlow: 5,
+      macdSignal: 2,
+      rsiPeriod: 3,
+      atrPeriod: 3,
+      bandWidthThreshold: 0.03,
+      emaSepThreshold: 0.01,
+      rsiOversoldMR: 40,
+      rsiOverboughtMR: 75,
+    });
+
+    const prices: number[] = [];
+    // Phase 1: 10 bars stable (warm-up, MR mode)
+    for (let i = 0; i < 10; i++) prices.push(100);
+    // Phase 2: sharp dip to trigger MR buy (3 bars down)
+    prices.push(96, 93, 91);
+    // Phase 3: slight uptick (RSI turns up while still below BB lower)
+    prices.push(92);
+    // Phase 4: strong trend emerges — 10 bars of accelerating rise
+    // This switches detected mode to "trend" and if the MR position is still open,
+    // after 5 bars in the new regime the forced exit triggers
+    for (let i = 1; i <= 10; i++) {
+      prices.push(92 + i * i * 0.3);
+    }
+    // Phase 5: continue trend (in case more bars needed for confirmation + 5 switch bars)
+    for (let i = 0; i < 8; i++) {
+      prices.push(prices[prices.length - 1]! + 3);
+    }
+
+    const data = prices.map((p, i) => makeBar(i, p));
+    const engine = new BacktestEngine();
+    const result = await engine.run(strategy, data, config);
+
+    // Should have at least one trade — either from MR entry + regime forced exit,
+    // or MR entry + MR sell on middle reversion, or a combination
+    expect(result.totalTrades).toBeGreaterThanOrEqual(1);
+
+    // Check if any trade has "regime switch forced exit" as the exit reason
+    const forcedExits = result.trades.filter((t) => t.exitReason === "regime switch forced exit");
+    // The forced exit may or may not trigger depending on whether the MR sell
+    // fires first (price reverts to BB middle). Either path is valid behavior.
+    // We verify the strategy completed without errors and produced trades.
+    expect(result.trades.length).toBeGreaterThanOrEqual(1);
+    // If there was a forced exit, confirm it has the expected reason
+    for (const t of forcedExits) {
+      expect(t.exitReason).toBe("regime switch forced exit");
+    }
+  });
+});

package/src/builtin-strategies/regime-adaptive.ts

@@ -0,0 +1,285 @@
+import type { OHLCV } from "../../../fin-shared-types/src/types.js";
+import type { Signal, StrategyContext, StrategyDefinition } from "../types.js";
+
+/**
+ * Regime Adaptive composite strategy.
+ *
+ * Detects the local market regime (trend vs mean-reversion) using
+ * Bollinger Band width and EMA separation, then applies the appropriate
+ * sub-strategy logic. A 3-bar confirmation filter prevents whipsaw on
+ * regime transitions, and a forced-exit mechanism closes stale positions
+ * that were entered under a different regime.
+ */
+export function createRegimeAdaptive(params?: {
+  bbPeriod?: number;
+  fastEma?: number;
+  slowEma?: number;
+  rsiPeriod?: number;
+  macdFast?: number;
+  macdSlow?: number;
+  macdSignal?: number;
+  atrPeriod?: number;
+  bandWidthThreshold?: number;
+  emaSepThreshold?: number;
+  rsiOversoldMR?: number;
+  rsiOverboughtMR?: number;
+  rsiTrendMinimum?: number;
+  atrStopMultiplier?: number;
+  maxSizePct?: number;
+  symbol?: string;
+}): StrategyDefinition {
+  const bbPeriod = params?.bbPeriod ?? 20;
+  const fastEma = params?.fastEma ?? 12;
+  const slowEma = params?.slowEma ?? 26;
+  const rsiPeriod = params?.rsiPeriod ?? 14;
+  const macdFast = params?.macdFast ?? 12;
+  const macdSlow = params?.macdSlow ?? 26;
+  const macdSignal = params?.macdSignal ?? 9;
+  const atrPeriod = params?.atrPeriod ?? 14;
+  const bandWidthThreshold = params?.bandWidthThreshold ?? 0.04;
+  const emaSepThreshold = params?.emaSepThreshold ?? 0.02;
+  const rsiOversoldMR = params?.rsiOversoldMR ?? 30;
+  const rsiOverboughtMR = params?.rsiOverboughtMR ?? 70;
+  const rsiTrendMinimum = params?.rsiTrendMinimum ?? 45;
+  const atrStopMultiplier = params?.atrStopMultiplier ?? 2.0;
+  const maxSizePct = params?.maxSizePct ?? 70;
+  const symbol = params?.symbol ?? "BTC/USDT";
+
+  return {
+    id: "regime-adaptive",
+    name: "Regime Adaptive",
+    version: "1.0.0",
+    markets: ["crypto", "equity"],
+    symbols: [symbol],
+    timeframes: ["1d"],
+    parameters: {
+      bbPeriod,
+      fastEma,
+      slowEma,
+      rsiPeriod,
+      macdFast,
+      macdSlow,
+      macdSignal,
+      atrPeriod,
+      bandWidthThreshold,
+      emaSepThreshold,
+      rsiOversoldMR,
+      rsiOverboughtMR,
+      rsiTrendMinimum,
+      atrStopMultiplier,
+      maxSizePct,
+    },
+    parameterRanges: {
+      bbPeriod: { min: 10, max: 40, step: 5 },
+      fastEma: { min: 5, max: 20, step: 1 },
+      slowEma: { min: 15, max: 50, step: 1 },
+      rsiPeriod: { min: 7, max: 28, step: 7 },
+      macdFast: { min: 8, max: 20, step: 2 },
+      macdSlow: { min: 20, max: 40, step: 2 },
+      macdSignal: { min: 5, max: 15, step: 2 },
+      atrPeriod: { min: 7, max: 28, step: 7 },
+      bandWidthThreshold: { min: 0.02, max: 0.08, step: 0.01 },
+      emaSepThreshold: { min: 0.01, max: 0.05, step: 0.005 },
+      rsiOversoldMR: { min: 20, max: 40, step: 5 },
+      rsiOverboughtMR: { min: 60, max: 80, step: 5 },
+      rsiTrendMinimum: { min: 35, max: 55, step: 5 },
+      atrStopMultiplier: { min: 1, max: 4, step: 0.5 },
+      maxSizePct: { min: 30, max: 100, step: 10 },
+    },
+
+    async onBar(bar: OHLCV, ctx: StrategyContext): Promise<Signal | null> {
+      // --- 1. Compute all indicators ---
+      const bands = ctx.indicators.bollingerBands(bbPeriod, 2);
+      const fastEmaArr = ctx.indicators.ema(fastEma);
+      const slowEmaArr = ctx.indicators.ema(slowEma);
+      const rsiArr = ctx.indicators.rsi(rsiPeriod);
+      const macdResult = ctx.indicators.macd(macdFast, macdSlow, macdSignal);
+      const atrArr = ctx.indicators.atr(atrPeriod);
+
+      const len = bands.upper.length;
+      if (len < 2) return null;
+
+      // --- 2. NaN guard on all current values ---
+      const currUpper = bands.upper[len - 1]!;
+      const currLower = bands.lower[len - 1]!;
+      const currMiddle = bands.middle[len - 1]!;
+      const currFastEma = fastEmaArr[fastEmaArr.length - 1]!;
+      const currSlowEma = slowEmaArr[slowEmaArr.length - 1]!;
+      const currRsi = rsiArr[rsiArr.length - 1]!;
+      const prevRsi = rsiArr.length >= 2 ? rsiArr[rsiArr.length - 2]! : Number.NaN;
+      const currHist = macdResult.histogram[macdResult.histogram.length - 1]!;
+      const prevHist =
+        macdResult.histogram.length >= 2
+          ? macdResult.histogram[macdResult.histogram.length - 2]!
+          : Number.NaN;
+      const currAtr = atrArr[atrArr.length - 1]!;
+
+      if (
+        Number.isNaN(currUpper) ||
+        Number.isNaN(currLower) ||
+        Number.isNaN(currMiddle) ||
+        Number.isNaN(currFastEma) ||
+        Number.isNaN(currSlowEma) ||
+        Number.isNaN(currRsi) ||
+        Number.isNaN(prevRsi) ||
+        Number.isNaN(currHist) ||
+        Number.isNaN(prevHist) ||
+        Number.isNaN(currAtr)
+      ) {
+        return null;
+      }
+
+      // --- 3. Regime filter: crisis → sit out ---
+      if (ctx.regime === "crisis") return null;
+
+      // --- 4. Local regime detection ---
+      const bandWidth = (currUpper - currLower) / currMiddle;
+      const emaSep = Math.abs(currFastEma - currSlowEma) / bar.close;
+      const detectedMode: "trend" | "mean-reversion" =
+        bandWidth > bandWidthThreshold && emaSep > emaSepThreshold ? "trend" : "mean-reversion";
+
+      // --- 5. 3-bar confirmation to prevent whipsaw ---
+      let activeMode =
+        (ctx.memory.get("activeMode") as "trend" | "mean-reversion" | undefined) ??
+        "mean-reversion";
+      let modeBarCount = (ctx.memory.get("modeBarCount") as number | undefined) ?? 0;
+
+      if (detectedMode !== activeMode) {
+        modeBarCount++;
+        if (modeBarCount >= 3) {
+          activeMode = detectedMode;
+          modeBarCount = 0;
+        }
+      } else {
+        modeBarCount = 0;
+      }
+
+      ctx.memory.set("activeMode", activeMode);
+      ctx.memory.set("modeBarCount", modeBarCount);
+
+      // --- 6. Position check ---
+      const hasLong = ctx.portfolio.positions.some((p) => p.side === "long");
+
+      // --- 9. Regime-switch forced exit (checked before entry logic) ---
+      if (hasLong) {
+        const entryMode = ctx.memory.get("entryMode") as "trend" | "mean-reversion" | undefined;
+        if (entryMode !== undefined && entryMode !== activeMode) {
+          let switchBars = (ctx.memory.get("switchBars") as number | undefined) ?? 0;
+          switchBars++;
+          ctx.memory.set("switchBars", switchBars);
+          if (switchBars >= 5) {
+            ctx.memory.delete("entryMode");
+            ctx.memory.delete("switchBars");
+            return {
+              action: "sell",
+              symbol,
+              sizePct: 100,
+              orderType: "market",
+              reason: "regime switch forced exit",
+              confidence: 0.5,
+            };
+          }
+        } else if (entryMode === activeMode) {
+          ctx.memory.set("switchBars", 0);
+        }
+      }
+
+      // --- 7. Trend mode logic ---
+      if (activeMode === "trend") {
+        // BUY: bullish EMA crossover + rising MACD histogram + RSI above minimum
+        if (
+          !hasLong &&
+          currFastEma > currSlowEma &&
+          currHist > prevHist &&
+          currRsi > rsiTrendMinimum
+        ) {
+          // Confidence: 0.5 base + alignment bonuses
+          const emaSepStrength = Math.min(emaSep / (emaSepThreshold * 3), 0.15);
+          const macdStrength = Math.min(Math.abs(currHist - prevHist) / (bar.close * 0.005), 0.15);
+          const rsiBonus = Math.min((currRsi - rsiTrendMinimum) / 100, 0.15);
+          const confidence = Math.min(
+            0.95,
+            Math.max(0.3, 0.5 + emaSepStrength + macdStrength + rsiBonus),
+          );
+          const sizePctCalc = Math.min(maxSizePct, Math.max(20, confidence * 90));
+
+          ctx.memory.set("entryMode", activeMode);
+
+          return {
+            action: "buy",
+            symbol,
+            sizePct: sizePctCalc,
+            orderType: "market",
+            stopLoss: bar.close - atrStopMultiplier * currAtr,
+            takeProfit: bar.close + 3 * currAtr,
+            reason: `trend buy: fastEMA>${slowEma} EMA, MACD rising, RSI=${currRsi.toFixed(1)}`,
+            confidence,
+          };
+        }
+
+        // SELL: death cross OR MACD negative
+        if (hasLong && (currFastEma < currSlowEma || currHist < 0)) {
+          ctx.memory.delete("entryMode");
+          ctx.memory.delete("switchBars");
+          const reason =
+            currFastEma < currSlowEma
+              ? `trend sell: EMA death cross (fast=${currFastEma.toFixed(2)} < slow=${currSlowEma.toFixed(2)})`
+              : `trend sell: MACD histogram negative (${currHist.toFixed(4)})`;
+          return {
+            action: "sell",
+            symbol,
+            sizePct: 100,
+            orderType: "market",
+            reason,
+            confidence: 0.6,
+          };
+        }
+      }
+
+      // --- 8. Mean-reversion mode logic ---
+      if (activeMode === "mean-reversion") {
+        // BUY: below lower BB + RSI oversold + RSI turning up
+        if (!hasLong && bar.close < currLower && currRsi < rsiOversoldMR && currRsi > prevRsi) {
+          // Confidence: 0.4 base + oversold depth + RSI reversal strength
+          const oversoldDepth = Math.min((rsiOversoldMR - currRsi) / rsiOversoldMR, 0.25);
+          const rsiReversal = Math.min((currRsi - prevRsi) / 10, 0.25);
+          const confidence = Math.min(0.95, Math.max(0.3, 0.4 + oversoldDepth + rsiReversal));
+          const sizePctCalc = Math.min(maxSizePct, Math.max(20, confidence * 90));
+
+          ctx.memory.set("entryMode", activeMode);
+
+          return {
+            action: "buy",
+            symbol,
+            sizePct: sizePctCalc,
+            orderType: "market",
+            stopLoss: bar.close - 1.5 * currAtr,
+            takeProfit: currMiddle,
+            reason: `MR buy: close=${bar.close.toFixed(2)} < BB lower=${currLower.toFixed(2)}, RSI=${currRsi.toFixed(1)} turning up`,
+            confidence,
+          };
+        }
+
+        // SELL: price reverts to BB middle OR RSI overbought
+        if (hasLong && (bar.close >= currMiddle || currRsi > rsiOverboughtMR)) {
+          ctx.memory.delete("entryMode");
+          ctx.memory.delete("switchBars");
+          const reason =
+            bar.close >= currMiddle
+              ? `MR sell: price=${bar.close.toFixed(2)} reverted to BB middle=${currMiddle.toFixed(2)}`
+              : `MR sell: RSI overbought=${currRsi.toFixed(1)} > ${rsiOverboughtMR}`;
+          return {
+            action: "sell",
+            symbol,
+            sizePct: 100,
+            orderType: "market",
+            reason,
+            confidence: 0.55,
+          };
+        }
+      }
+
+      return null;
+    },
+  };
+}