tradelab 1.0.0 → 1.1.0

package/examples/llmSignal.js

@@ -0,0 +1,33 @@
+// Run: node examples/llmSignal.js
+import { backtestAsync, LlmSignal, getHistoricalCandles } from "../src/index.js";
+
+const candles = await getHistoricalCandles({
+  source: "yahoo",
+  symbol: "SPY",
+  interval: "1d",
+  period: "1y",
+  cache: true,
+});
+
+// Stand-in for a real model call. Replace `resolve` with an LLM/agent request.
+const llm = new LlmSignal({
+  budgetMs: 2000,
+  onError: "skip",
+  async resolve({ candles: history, bar }) {
+    const closes = history.map((c) => c.close);
+    const recent = closes.slice(-5);
+    const rising = recent.every((c, i) => i === 0 || c >= recent[i - 1]);
+    return rising ? { side: "long", stop: bar.close * 0.98, rr: 2 } : null;
+  },
+});
+
+const result = await backtestAsync({
+  candles,
+  symbol: "SPY",
+  interval: "1d",
+  signal: llm.signal,
+  signalBudgetMs: 3000,
+});
+
+console.log("trades:", result.metrics.trades, "PnL:", result.metrics.totalPnL.toFixed(2));
+console.log("decisions logged:", llm.log.length);

package/examples/optimize.js

@@ -0,0 +1,25 @@
+// Run: node examples/optimize.js
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { optimize, grid, getHistoricalCandles } from "../src/index.js";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+const candles = await getHistoricalCandles({
+  source: "yahoo",
+  symbol: "SPY",
+  interval: "1d",
+  period: "2y",
+  cache: true,
+});
+
+const { leaderboard, best } = await optimize({
+  candles,
+  interval: "1d",
+  signalModulePath: path.join(here, "..", "test", "fixtures", "emaSignal.js"),
+  parameterSets: grid({ fast: [5, 8, 10, 12], slow: [20, 30, 50] }),
+  scoreBy: "sharpeAnnualized",
+});
+
+console.log("best params:", best?.params, "sharpe:", best?.metrics.sharpeAnnualized);
+console.table(leaderboard.slice(0, 5).map((r) => ({ ...r.params, ...r.metrics })));

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "tradelab",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Backtesting toolkit for Node.js with strategy simulation, historical data loading, and report generation",
   "type": "module",
   "main": "./dist/cjs/index.cjs",
   "module": "./src/index.js",
   "types": "./types/index.d.ts",
   "bin": {
-    "tradelab": "./bin/tradelab.js"
+    "tradelab": "bin/tradelab.js",
+    "tradelab-mcp": "bin/tradelab-mcp.js"
   },
   "license": "MIT",
   "repository": {
@@ -38,6 +39,14 @@
       "import": "./src/live/index.js",
       "require": "./dist/cjs/live.cjs"
     },
+    "./ta": {
+      "types": "./types/ta.d.ts",
+      "import": "./src/ta/index.js",
+      "require": "./dist/cjs/ta.cjs"
+    },
+    "./mcp": {
+      "import": "./src/mcp/server.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -49,6 +58,7 @@
     "templates",
     "examples/*.js",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
@@ -83,5 +93,9 @@
     "globals": "^15.15.0",
     "prettier": "^3.5.3",
     "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
   }
 }

package/src/engine/asyncSignal.js

@@ -0,0 +1,28 @@
+export class BudgetExceededError extends Error {
+  constructor(ms) {
+    super(`signal() exceeded its ${ms}ms per-bar budget`);
+    this.name = "BudgetExceededError";
+    this.budgetMs = ms;
+  }
+}
+
+/**
+ * Race a promise against a per-bar time budget. `budgetMs` of 0/undefined
+ * disables the timeout. Rejects with BudgetExceededError on overrun.
+ */
+export function withBudget(promise, budgetMs) {
+  if (!budgetMs || budgetMs <= 0) return Promise.resolve(promise);
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new BudgetExceededError(budgetMs)), budgetMs);
+    Promise.resolve(promise).then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err);
+      }
+    );
+  });
+}

package/src/engine/backtest.js

@@ -12,6 +12,7 @@ import {
   estimateBarMs,
   dayKeyUTC,
   dayKeyET,
+  financingCost,
 } from "./execution.js";
 
 function asNumber(value) {
@@ -154,6 +155,7 @@ function mergeOptions(options) {
     maxSlipROnFill: options.maxSlipROnFill ?? 0.4,
     collectEqSeries: options.collectEqSeries ?? true,
     collectReplay: options.collectReplay ?? true,
+    benchmarkReturns: Array.isArray(options.benchmarkReturns) ? options.benchmarkReturns : null,
     strict: options.strict ?? false,
   };
 }
@@ -305,7 +307,14 @@ export function backtest(rawOptions) {
     const entryFill = openPos.entryFill;
     const grossPnl = (exitPx - entryFill) * direction * qty;
     const entryFeePortion = (openPos.entryFeeTotal || 0) * (qty / openPos.initSize);
-    const pnl = grossPnl - entryFeePortion - exitFeeTotal;
+    const financing = financingCost({
+      side: openPos.side,
+      notional: entryFill * qty,
+      fromMs: openPos.openTime,
+      toMs: time,
+      costs,
+    });
+    const pnl = grossPnl - entryFeePortion - exitFeeTotal - financing;
 
     currentEquity += pnl;
     dayPnl += pnl;
@@ -349,6 +358,7 @@ export function backtest(rawOptions) {
         time,
         reason,
         pnl,
+        financing,
         exitATR: openPos._lastATR ?? undefined,
       },
       mfeR: openPos._mfeR ?? 0,
@@ -872,6 +882,8 @@ export function backtest(rawOptions) {
     candles,
     estBarMs: estimatedBarMs,
     eqSeries,
+    interval: options.interval,
+    benchmarkReturns: options.benchmarkReturns,
   });
   const positions = closed.filter((trade) => trade.exit.reason !== "SCALE");
   const lastPrice = asNumber(candles[candles.length - 1]?.close);

package/src/engine/backtestAsync.js

@@ -0,0 +1,27 @@
+import { BarSystemRunner } from "./barSystemRunner.js";
+import { withBudget } from "./asyncSignal.js";
+
+/**
+ * Async sibling of backtest(). Identical result shape, but `signal()` may return
+ * a Promise. Each bar's signal is raced against `signalBudgetMs` (0 disables).
+ *
+ * Built on BarSystemRunner so position/pending/exit logic is shared with the
+ * sync engine and portfolio mode.
+ */
+export async function backtestAsync(rawOptions = {}) {
+  const budgetMs = rawOptions.signalBudgetMs ?? 0;
+  const userSignal = rawOptions.signal;
+  const budgetedSignal = (context) =>
+    withBudget(
+      Promise.resolve().then(() => userSignal(context)),
+      budgetMs
+    );
+
+  const runner = new BarSystemRunner({ ...rawOptions, signal: budgetedSignal });
+
+  while (runner.hasNext()) {
+    await runner.stepAsync({ signalEquity: runner.getMarkedEquity() });
+  }
+
+  return runner.buildResult();
+}

package/src/engine/backtestTicks.js

@@ -1,6 +1,6 @@
 import { buildMetrics } from "../metrics/buildMetrics.js";
 import { calculatePositionSize } from "../utils/positionSizing.js";
-import { applyFill, dayKeyUTC, ocoExitCheck, roundStep } from "./execution.js";
+import { applyFill, dayKeyUTC, financingCost, ocoExitCheck, roundStep } from "./execution.js";
 
 function asNumber(value) {
   const numeric = Number(value);
@@ -163,6 +163,7 @@ export function backtestTicks({
   collectEqSeries = true,
   collectReplay = true,
   queueFillProbability = 1,
+  seed = "tradelab-ticks",
   oco = {},
 } = {}) {
   if (!Array.isArray(ticks) || ticks.length === 0) {
@@ -235,7 +236,14 @@ export function backtestTicks({
     });
     const direction = open.side === "long" ? 1 : -1;
     const grossPnl = (price - open.entryFill) * direction * open.size;
-    const pnl = grossPnl - (open.entryFeeTotal || 0) - feeTotal;
+    const financing = financingCost({
+      side: open.side,
+      notional: open.entryFill * open.size,
+      fromMs: open.openTime,
+      toMs: tick.time,
+      costs,
+    });
+    const pnl = grossPnl - (open.entryFeeTotal || 0) - feeTotal - financing;
     currentEquity += pnl;
     dayPnl += pnl;
     const trade = {
@@ -245,6 +253,7 @@ export function backtestTicks({
         time: tick.time,
         reason,
         pnl,
+        financing,
       },
     };
     trades.push(trade);
@@ -343,6 +352,7 @@ export function backtestTicks({
         if (
           touched &&
           deterministicFill(queueFillProbability, [
+            seed,
             symbol,
             tick.time,
             pending.entry,
@@ -462,6 +472,7 @@ export function backtestTicks({
         ? Math.max(1, normalizedTicks[1].time - normalizedTicks[0].time)
         : 1,
     eqSeries,
+    interval,
   });
 
   return {

package/src/engine/barSystemRunner.js

@@ -5,6 +5,7 @@ import { normalizeCandles } from "../data/csv.js";
 import {
   applyFill,
   clampStop,
+  financingCost,
   touchedLimit,
   ocoExitCheck,
   isEODBar,
@@ -63,6 +64,17 @@ export function callSignalWithContext({ signal, context, index, bar, symbol }) {
   }
 }
 
+export async function callSignalWithContextAsync({ signal, context, index, bar, symbol }) {
+  try {
+    return await signal(context);
+  } catch (error) {
+    const cause = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `signal() threw at index=${index}, time=${formatIsoTime(bar?.time)}, symbol=${symbol}: ${cause}`
+    );
+  }
+}
+
 export function snapshotOpenPosition(open, markPrice) {
   if (!open) return null;
   const entryPrice = open.entryFill ?? open.entry;
@@ -305,7 +317,14 @@ export class BarSystemRunner {
     const entryFill = openPos.entryFill;
     const grossPnl = (exitPx - entryFill) * direction * qty;
     const entryFeePortion = (openPos.entryFeeTotal || 0) * (qty / openPos.initSize);
-    const pnl = grossPnl - entryFeePortion - exitFeeTotal;
+    const financing = financingCost({
+      side: openPos.side,
+      notional: entryFill * qty,
+      fromMs: openPos.openTime,
+      toMs: time,
+      costs: this.options.costs,
+    });
+    const pnl = grossPnl - entryFeePortion - exitFeeTotal - financing;
 
     this.currentEquity += pnl;
     this.dayPnl += pnl;
@@ -350,6 +369,7 @@ export class BarSystemRunner {
         time,
         reason,
         pnl,
+        financing,
         exitATR: openPos._lastATR ?? undefined,
       },
       mfeR: openPos._mfeR ?? 0,
@@ -544,8 +564,8 @@ export class BarSystemRunner {
     };
   }
 
-  step({ signalEquity, canTrade = true, resolveEntrySize } = {}) {
-    if (!this.hasNext()) return null;
+  _preSignal({ signalEquity, canTrade = true, resolveEntrySize } = {}) {
+    if (!this.hasNext()) return { handled: true, bar: null };
 
     const bar = this.candles[this.index];
     this.history.push(bar);
@@ -929,52 +949,60 @@ export class BarSystemRunner {
       if (this.cooldown > 0) this.cooldown -= 1;
       this.recordFrame(bar);
       this.index += 1;
-      return bar;
+      return { handled: true, bar };
     }
 
     if (!canTrade || dailyLossHit || dailyTradeCapHit) {
       this.pending = null;
       this.recordFrame(bar);
       this.index += 1;
-      return bar;
+      return { handled: true, bar };
     }
 
-    if (!this.pending) {
-      const rawSignal = callSignalWithContext({
-        signal: this.options.signal,
-        context: this.buildSignalContext(this.index, bar, signalEquity),
-        index: this.index,
-        bar,
-        symbol: this.symbol,
-      });
-      const nextSignal = normalizeSignal(rawSignal, bar, this.options.finalTP_R);
-
-      if (nextSignal) {
-        const signalRiskFraction = Number.isFinite(nextSignal.riskFraction)
-          ? nextSignal.riskFraction
-          : Number.isFinite(nextSignal.riskPct)
-            ? nextSignal.riskPct / 100
-            : this.options.riskPct / 100;
-        const expiryBars = nextSignal._entryExpiryBars ?? 5;
-        this.pending = {
-          side: nextSignal.side,
-          entry: nextSignal.entry,
-          stop: nextSignal.stop,
-          tp: nextSignal.takeProfit,
-          riskFrac: signalRiskFraction,
-          fixedQty: nextSignal.qty,
-          expiresAt: this.index + Math.max(1, expiryBars),
-          startedAtIndex: this.index,
-          meta: nextSignal,
-          plannedRiskAbs: Math.abs(nextSignal._initRisk ?? nextSignal.entry - nextSignal.stop),
-        };
-
-        if (touchedLimit(this.pending.side, this.pending.entry, bar, trigger)) {
-          if (
-            !this.openFromPending(bar, signalEquity, this.pending.entry, "limit", resolveEntrySize)
-          ) {
-            this.pending = null;
-          }
+    if (this.pending) {
+      this.recordFrame(bar);
+      this.index += 1;
+      return { handled: true, bar };
+    }
+
+    return {
+      handled: false,
+      bar,
+      trigger,
+      signalEquity,
+      resolveEntrySize,
+    };
+  }
+
+  _applyRawSignal(rawSignal, pre) {
+    const { bar, trigger, signalEquity, resolveEntrySize } = pre;
+    const nextSignal = normalizeSignal(rawSignal, bar, this.options.finalTP_R);
+
+    if (nextSignal) {
+      const signalRiskFraction = Number.isFinite(nextSignal.riskFraction)
+        ? nextSignal.riskFraction
+        : Number.isFinite(nextSignal.riskPct)
+          ? nextSignal.riskPct / 100
+          : this.options.riskPct / 100;
+      const expiryBars = nextSignal._entryExpiryBars ?? 5;
+      this.pending = {
+        side: nextSignal.side,
+        entry: nextSignal.entry,
+        stop: nextSignal.stop,
+        tp: nextSignal.takeProfit,
+        riskFrac: signalRiskFraction,
+        fixedQty: nextSignal.qty,
+        expiresAt: this.index + Math.max(1, expiryBars),
+        startedAtIndex: this.index,
+        meta: nextSignal,
+        plannedRiskAbs: Math.abs(nextSignal._initRisk ?? nextSignal.entry - nextSignal.stop),
+      };
+
+      if (touchedLimit(this.pending.side, this.pending.entry, bar, trigger)) {
+        if (
+          !this.openFromPending(bar, signalEquity, this.pending.entry, "limit", resolveEntrySize)
+        ) {
+          this.pending = null;
         }
       }
     }
@@ -984,6 +1012,32 @@ export class BarSystemRunner {
     return bar;
   }
 
+  step(options = {}) {
+    const pre = this._preSignal(options);
+    if (pre.handled) return pre.bar;
+    const rawSignal = callSignalWithContext({
+      signal: this.options.signal,
+      context: this.buildSignalContext(this.index, pre.bar, pre.signalEquity),
+      index: this.index,
+      bar: pre.bar,
+      symbol: this.symbol,
+    });
+    return this._applyRawSignal(rawSignal, pre);
+  }
+
+  async stepAsync(options = {}) {
+    const pre = this._preSignal(options);
+    if (pre.handled) return pre.bar;
+    const rawSignal = await callSignalWithContextAsync({
+      signal: this.options.signal,
+      context: this.buildSignalContext(this.index, pre.bar, pre.signalEquity),
+      index: this.index,
+      bar: pre.bar,
+      symbol: this.symbol,
+    });
+    return this._applyRawSignal(rawSignal, pre);
+  }
+
   buildResult() {
     const metrics = buildMetrics({
       closed: this.closed,
@@ -992,6 +1046,7 @@ export class BarSystemRunner {
       candles: this.candles,
       estBarMs: this.estimatedBarMs,
       eqSeries: this.eqSeries,
+      interval: this.options.interval,
     });
     const positions = this.closed.filter((trade) => trade.exit.reason !== "SCALE");
     const lastPrice = asNumber(this.candles[this.candles.length - 1]?.close);

package/src/engine/execution.js

@@ -127,3 +127,42 @@ export function dayKeyET(timeMs) {
   const pseudoEtTime = anchor.getTime() + hoursET * 60 * 60 * 1000 + minutesETDay * 60 * 1000;
   return dayKeyUTC(pseudoEtTime);
 }
+
+const MS_PER_YEAR = 365 * 24 * 60 * 60 * 1000;
+
+/**
+ * Count funding boundaries in the half-open interval (fromMs, toMs], given a
+ * funding `intervalMs` cadence anchored at `anchorMs`.
+ */
+export function fundingEvents(fromMs, toMs, intervalMs, anchorMs = 0) {
+  if (!(intervalMs > 0) || toMs <= fromMs) return 0;
+  const firstK = Math.floor((fromMs - anchorMs) / intervalMs) + 1;
+  const lastK = Math.floor((toMs - anchorMs) / intervalMs);
+  return Math.max(0, lastK - firstK + 1);
+}
+
+/**
+ * Time-based financing cost for holding `notional` from `fromMs` to `toMs`.
+ * Positive return = cost to the position (subtract from PnL).
+ */
+export function financingCost({ side, notional, fromMs, toMs, costs }) {
+  const model = costs || {};
+  const absNotional = Math.abs(notional);
+  let cost = 0;
+
+  if (model.carry) {
+    const annualBps =
+      side === "long" ? (model.carry.longAnnualBps ?? 0) : (model.carry.shortAnnualBps ?? 0);
+    const years = Math.max(0, toMs - fromMs) / MS_PER_YEAR;
+    cost += absNotional * (annualBps / 10000) * years;
+  }
+
+  const funding = model.funding;
+  if (funding && funding.intervalMs > 0 && Number.isFinite(funding.rateBps)) {
+    const count = fundingEvents(fromMs, toMs, funding.intervalMs, funding.anchorMs ?? 0);
+    const perEvent = absNotional * (funding.rateBps / 10000);
+    cost += (side === "long" ? 1 : -1) * perEvent * count;
+  }
+
+  return cost;
+}

package/src/engine/grid.js

@@ -0,0 +1,15 @@
+/**
+ * Expand a parameter grid into an array of parameter-set objects.
+ * Array values are swept; scalar values are held fixed across all sets.
+ */
+export function grid(spec = {}) {
+  const keys = Object.keys(spec);
+  if (!keys.length) return [{}];
+  return keys.reduce(
+    (acc, key) => {
+      const values = Array.isArray(spec[key]) ? spec[key] : [spec[key]];
+      return acc.flatMap((base) => values.map((v) => ({ ...base, [key]: v })));
+    },
+    [{}]
+  );
+}

package/src/engine/llmSignal.js

@@ -0,0 +1,84 @@
+import { withBudget } from "./asyncSignal.js";
+
+function isArrayIndexKey(property) {
+  if (typeof property !== "string") return false;
+  const n = Number(property);
+  return Number.isInteger(n) && n >= 0;
+}
+
+function noLookaheadView(candles, index) {
+  return new Proxy(candles, {
+    get(target, property, receiver) {
+      if (isArrayIndexKey(property) && Number(property) > index) {
+        throw new Error(
+          `LlmSignal: lookahead access to candles[${String(property)}] (current index ${index})`
+        );
+      }
+      return Reflect.get(target, property, receiver);
+    },
+  });
+}
+
+/**
+ * Wraps an async model-backed decision function for use as a tradelab signal.
+ *
+ * - Caches by bar time: resolve() runs at most once per bar.
+ * - Enforces a per-bar `budgetMs` time budget.
+ * - Exposes a no-lookahead candle view to resolve().
+ * - Logs every decision (context summary, result or error) in `this.log`.
+ *
+ * `onError`: "skip" (return null, default) or "throw".
+ * Use the instance's `.signal` bound method as the engine's `signal` option.
+ */
+export class LlmSignal {
+  constructor({ resolve, budgetMs = 0, onError = "skip" } = {}) {
+    if (typeof resolve !== "function") {
+      throw new Error("LlmSignal requires a resolve(context) function");
+    }
+    this.resolve = resolve;
+    this.budgetMs = budgetMs;
+    this.onError = onError;
+    this.log = [];
+    this._cache = new Map();
+    this.signal = this.signal.bind(this);
+  }
+
+  async signal(context) {
+    const key = context.bar?.time ?? context.index;
+    if (this._cache.has(key)) return this._cache.get(key);
+
+    const safeContext = {
+      ...context,
+      candles: noLookaheadView(context.candles, context.index),
+    };
+
+    const startedAt = Date.now();
+    try {
+      const result = await withBudget(
+        Promise.resolve().then(() => this.resolve(safeContext)),
+        this.budgetMs
+      );
+      this._cache.set(key, result ?? null);
+      this.log.push({
+        index: context.index,
+        time: context.bar?.time,
+        close: context.bar?.close,
+        latencyMs: Date.now() - startedAt,
+        result: result ?? null,
+      });
+      return result ?? null;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.log.push({
+        index: context.index,
+        time: context.bar?.time,
+        close: context.bar?.close,
+        latencyMs: Date.now() - startedAt,
+        error: message,
+      });
+      this._cache.set(key, null);
+      if (this.onError === "throw") throw error;
+      return null;
+    }
+  }
+}