tradelab 1.0.1 → 1.1.0

package/src/engine/optimize.js

@@ -0,0 +1,86 @@
+import { Worker } from "node:worker_threads";
+import os from "node:os";
+
+function defaultConcurrency() {
+  return Math.max(1, (os.cpus()?.length ?? 2) - 1);
+}
+
+function scoreValue(metrics, scoreBy) {
+  const v = metrics?.[scoreBy];
+  return Number.isFinite(v) ? v : -Infinity;
+}
+
+export function optimize({
+  candles,
+  signalModulePath,
+  parameterSets,
+  interval,
+  backtestOptions = {},
+  concurrency,
+  scoreBy = "profitFactor",
+}) {
+  if (!Array.isArray(parameterSets) || parameterSets.length === 0) {
+    return Promise.resolve({ results: [], leaderboard: [], best: null });
+  }
+
+  return new Promise((resolve, reject) => {
+    const poolSize = Math.min(concurrency || defaultConcurrency(), parameterSets.length);
+    const results = new Array(parameterSets.length);
+    const workers = [];
+    let nextIndex = 0;
+    let completed = 0;
+    let settled = false;
+
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      for (const w of workers) w.terminate();
+      const ranked = results
+        .filter((r) => r && r.metrics)
+        .sort((a, b) => scoreValue(b.metrics, scoreBy) - scoreValue(a.metrics, scoreBy));
+      resolve({ results, leaderboard: ranked, best: ranked[0] ?? null });
+    };
+
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      for (const w of workers) w.terminate();
+      reject(error);
+    };
+
+    const dispatch = (worker) => {
+      if (nextIndex >= parameterSets.length) {
+        worker.postMessage({ type: "stop" });
+        return;
+      }
+      const index = nextIndex;
+      nextIndex += 1;
+      worker.postMessage({ type: "run", index, params: parameterSets[index] });
+    };
+
+    for (let i = 0; i < poolSize; i += 1) {
+      const worker = new Worker(new URL("./optimizeWorker.js", import.meta.url), {
+        workerData: { candles, signalModulePath, interval, backtestOptions },
+      });
+      workers.push(worker);
+
+      worker.on("message", (msg) => {
+        if (msg.type === "ready") {
+          dispatch(worker);
+          return;
+        }
+        if (msg.type === "result" || msg.type === "error") {
+          results[msg.index] =
+            msg.type === "result"
+              ? { params: msg.params, metrics: msg.metrics }
+              : { params: msg.params, error: msg.error };
+          completed += 1;
+          if (completed === parameterSets.length) finish();
+          else dispatch(worker);
+        }
+      });
+
+      worker.on("error", fail);
+    }
+  });
+}

package/src/engine/optimizeWorker.js

@@ -0,0 +1,67 @@
+import { workerData, parentPort } from "node:worker_threads";
+import { pathToFileURL } from "node:url";
+import { backtest } from "./backtest.js";
+
+const { candles, signalModulePath, interval, backtestOptions } = workerData;
+
+const mod = await import(pathToFileURL(signalModulePath).href);
+const createSignal = mod.createSignal ?? mod.default;
+if (typeof createSignal !== "function") {
+  throw new Error(
+    `optimize: ${signalModulePath} must export createSignal(params) or a default factory`
+  );
+}
+
+function pickMetrics(metrics) {
+  const keep = [
+    "trades",
+    "winRate",
+    "profitFactor",
+    "expectancy",
+    "totalR",
+    "avgR",
+    "sharpe",
+    "sharpeAnnualized",
+    "maxDrawdown",
+    "calmar",
+    "returnPct",
+    "totalPnL",
+    "finalEquity",
+  ];
+  const out = {};
+  for (const k of keep) out[k] = metrics[k];
+  return out;
+}
+
+parentPort.on("message", (msg) => {
+  if (msg.type === "stop") {
+    process.exit(0);
+  }
+  if (msg.type === "run") {
+    try {
+      const result = backtest({
+        candles,
+        interval,
+        signal: createSignal(msg.params),
+        collectReplay: false,
+        collectEqSeries: false,
+        ...backtestOptions,
+      });
+      parentPort.postMessage({
+        type: "result",
+        index: msg.index,
+        params: msg.params,
+        metrics: pickMetrics(result.metrics),
+      });
+    } catch (error) {
+      parentPort.postMessage({
+        type: "error",
+        index: msg.index,
+        params: msg.params,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+});
+
+parentPort.postMessage({ type: "ready" });

package/src/engine/walkForward.js

@@ -225,6 +225,7 @@ export function walkForwardOptimize({
     candles,
     estBarMs: estimateBarMs(candles),
     eqSeries,
+    interval: backtestOptions.interval,
   });
   const bestParamsSummary = summarizeBestParams(windows);
 

package/src/index.js

@@ -1,9 +1,18 @@
 export { backtest } from "./engine/backtest.js";
+export { backtestAsync } from "./engine/backtestAsync.js";
 export { backtestTicks } from "./engine/backtestTicks.js";
 export { backtestPortfolio } from "./engine/portfolio.js";
+export { LlmSignal } from "./engine/llmSignal.js";
 export { walkForwardOptimize } from "./engine/walkForward.js";
+export { optimize } from "./engine/optimize.js";
+export { grid } from "./engine/grid.js";
+export { listStrategies, getStrategy, registerStrategy } from "./strategies/index.js";
+export * as research from "./research/index.js";
 
 export { buildMetrics } from "./metrics/buildMetrics.js";
+export { benchmarkStats } from "./metrics/benchmark.js";
+export { clampFinite, BIG_NUMBER } from "./metrics/finite.js";
+export { periodsPerYear } from "./metrics/annualize.js";
 export {
   backtestHistorical,
   cachedCandlesPath,

package/src/live/dashboard/server.js

@@ -0,0 +1,120 @@
+import http from "node:http";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const FALLBACK_HTML = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>tradelab live</title>
+  </head>
+  <body>
+    <h1>tradelab live</h1>
+    <pre id="state"></pre>
+    <script>
+      fetch("/state")
+        .then((res) => res.json())
+        .then((state) => {
+          document.getElementById("state").textContent = JSON.stringify(state, null, 2);
+        });
+    </script>
+  </body>
+</html>`;
+
+function readDashboardHtml() {
+  if (import.meta.url) {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const htmlPath = path.join(here, "..", "..", "..", "templates", "dashboard.html");
+    return readFileSync(htmlPath, "utf8");
+  }
+
+  try {
+    return readFileSync(path.join(process.cwd(), "templates", "dashboard.html"), "utf8");
+  } catch {
+    return FALLBACK_HTML;
+  }
+}
+
+/**
+ * Local realtime dashboard for a LiveEngine or LiveOrchestrator.
+ *
+ * @param {object} opts
+ * @param {{ eventBus: import("../events.js").EventBus, getStatus: Function }} opts.source
+ * @param {number} [opts.port=4317] 0 picks an ephemeral port for tests
+ * @param {number} [opts.maxBuffer=200] recent events replayed to new clients
+ * @returns {{ start: () => Promise<string>, close: () => Promise<void>, server: http.Server }}
+ */
+export function createDashboardServer({ source, port = 4317, maxBuffer = 200 }) {
+  if (!source?.eventBus || typeof source.eventBus.onAny !== "function") {
+    throw new Error("dashboard source must expose an eventBus with onAny()");
+  }
+
+  const recent = [];
+  const clients = new Set();
+
+  const unsubscribe = source.eventBus.onAny(({ event, payload }) => {
+    const msg = { event, payload, t: Date.now() };
+    recent.push(msg);
+    if (recent.length > maxBuffer) recent.shift();
+    const frame = `data: ${JSON.stringify(msg)}\n\n`;
+    for (const res of clients) res.write(frame);
+  });
+
+  const server = http.createServer((req, res) => {
+    const url = (req.url || "/").split("?")[0];
+
+    if (url === "/") {
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      res.end(readDashboardHtml());
+      return;
+    }
+
+    if (url === "/state") {
+      const status = typeof source.getStatus === "function" ? source.getStatus() : {};
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(status));
+      return;
+    }
+
+    if (url === "/events") {
+      res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive",
+      });
+      res.flushHeaders();
+      for (const msg of recent) res.write(`data: ${JSON.stringify(msg)}\n\n`);
+      clients.add(res);
+      req.on("close", () => clients.delete(res));
+      return;
+    }
+
+    res.writeHead(404, { "Content-Type": "text/plain" });
+    res.end("not found");
+  });
+
+  return {
+    start() {
+      return new Promise((resolve) => {
+        server.listen(port, () => {
+          const address = server.address();
+          const actualPort = typeof address === "object" && address ? address.port : port;
+          resolve(`http://localhost:${actualPort}`);
+        });
+      });
+    },
+    close() {
+      unsubscribe();
+      for (const res of clients) res.end();
+      clients.clear();
+      return new Promise((resolve, reject) => {
+        server.close((error) => {
+          if (error) reject(error);
+          else resolve();
+        });
+      });
+    },
+    server,
+  };
+}

package/src/live/engine/liveEngine.js

@@ -2,7 +2,7 @@ import { calculatePositionSize } from "../../utils/positionSizing.js";
 import { normalizeCandles } from "../../data/csv.js";
 import { isEODBar, ocoExitCheck } from "../../engine/execution.js";
 import {
-  callSignalWithContext,
+  callSignalWithContextAsync,
   normalizeSignal,
   snapshotOpenPosition,
 } from "../../engine/barSystemRunner.js";
@@ -513,7 +513,7 @@ export class LiveEngine {
 
     if (!this.openPosition && !this.pendingOrder) {
       const context = this._signalContext(bar);
-      const rawSignal = callSignalWithContext({
+      const rawSignal = await callSignalWithContextAsync({
         signal: this.options.signal,
         context,
         index: context.index,

package/src/live/index.js

@@ -25,3 +25,4 @@ export { PaperEngine, createPaperEngine } from "./engine/paperEngine.js";
 export { LiveEngine, createLiveEngine } from "./engine/liveEngine.js";
 
 export { LiveOrchestrator, createLiveOrchestrator } from "./orchestrator.js";
+export { createDashboardServer } from "./dashboard/server.js";

package/src/mcp/schemas.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+
+const candle = z.object({
+  time: z.number(),
+  open: z.number().optional(),
+  high: z.number(),
+  low: z.number(),
+  close: z.number(),
+  volume: z.number().optional(),
+});
+
+const dataSpec = z
+  .object({
+    source: z.enum(["yahoo", "csv", "auto"]).optional(),
+    symbol: z.string().optional(),
+    interval: z.string().optional(),
+    period: z.string().optional(),
+    csvPath: z.string().optional(),
+    cache: z.boolean().optional(),
+  })
+  .passthrough();
+
+export const schemas = {
+  list_strategies: {},
+  fetch_candles: dataSpec.shape,
+  run_backtest: {
+    candles: z.array(candle).optional(),
+    data: dataSpec.optional(),
+    symbol: z.string().optional(),
+    interval: z.string().optional(),
+    strategy: z.string(),
+    params: z.record(z.string(), z.any()).optional(),
+    backtestOptions: z.record(z.string(), z.any()).optional(),
+  },
+  walk_forward: {
+    candles: z.array(candle).optional(),
+    data: dataSpec.optional(),
+    interval: z.string().optional(),
+    strategy: z.string(),
+    trainBars: z.number(),
+    testBars: z.number(),
+    stepBars: z.number().optional(),
+    mode: z.enum(["rolling", "anchored"]).optional(),
+    scoreBy: z.string().optional(),
+    grid: z.record(z.string(), z.array(z.any())).optional(),
+    backtestOptions: z.record(z.string(), z.any()).optional(),
+  },
+};

package/src/mcp/server.js

@@ -0,0 +1,31 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { mcpTools } from "./tools.js";
+import { schemas } from "./schemas.js";
+
+/** Build (but do not start) an McpServer with all tradelab tools registered. */
+export function createServer() {
+  const server = new McpServer({ name: "tradelab", version: "1.1.0" });
+
+  for (const [name, def] of Object.entries(mcpTools)) {
+    server.tool(name, def.description, schemas[name] ?? {}, async (args) => {
+      try {
+        const result = await def.handler(args ?? {});
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { isError: true, content: [{ type: "text", text: `Error: ${message}` }] };
+      }
+    });
+  }
+
+  return server;
+}
+
+/** Start the server on stdio. Called by bin/tradelab-mcp.js. */
+export async function startStdioServer() {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  return server;
+}

package/src/mcp/tools.js

@@ -0,0 +1,142 @@
+import { backtest } from "../engine/backtest.js";
+import { walkForwardOptimize } from "../engine/walkForward.js";
+import { getHistoricalCandles } from "../data/index.js";
+import { getStrategy, listStrategies } from "../strategies/index.js";
+
+function summarizeMetrics(metrics) {
+  const {
+    trades,
+    winRate,
+    profitFactor,
+    expectancy,
+    totalR,
+    avgR,
+    sharpe,
+    sharpeAnnualized,
+    sortinoAnnualized,
+    maxDrawdown,
+    calmar,
+    returnPct,
+    totalPnL,
+    finalEquity,
+    exposurePct,
+    sideBreakdown,
+  } = metrics;
+  return {
+    trades,
+    winRate,
+    profitFactor,
+    expectancy,
+    totalR,
+    avgR,
+    sharpe,
+    sharpeAnnualized,
+    sortinoAnnualized,
+    maxDrawdown,
+    calmar,
+    returnPct,
+    totalPnL,
+    finalEquity,
+    exposurePct,
+    sideBreakdown,
+  };
+}
+
+async function resolveCandles(args) {
+  if (Array.isArray(args.candles) && args.candles.length) return args.candles;
+  if (args.data) return getHistoricalCandles(args.data);
+  throw new Error("Provide either `candles` (array) or `data` (getHistoricalCandles spec).");
+}
+
+function expandGrid(grid) {
+  const keys = Object.keys(grid || {});
+  if (!keys.length) return [{}];
+  return keys.reduce(
+    (acc, key) => acc.flatMap((base) => grid[key].map((v) => ({ ...base, [key]: v }))),
+    [{}]
+  );
+}
+
+export const mcpTools = {
+  list_strategies: {
+    description: "List built-in trading strategies with their tunable parameters.",
+    handler: async () => ({ strategies: listStrategies() }),
+  },
+
+  fetch_candles: {
+    description: "Download/caches OHLCV candles from Yahoo or CSV. Returns a compact summary.",
+    handler: async (args) => {
+      const candles = await getHistoricalCandles(args);
+      return {
+        count: candles.length,
+        first: candles[0] ?? null,
+        last: candles[candles.length - 1] ?? null,
+      };
+    },
+  },
+
+  run_backtest: {
+    description:
+      "Run a single backtest using a named strategy + params. Returns a metrics summary and a small trade preview (no replay).",
+    handler: async (args) => {
+      const candles = await resolveCandles(args);
+      const factory = getStrategy(args.strategy);
+      const signal = factory(args.params || {});
+      const result = backtest({
+        candles,
+        symbol: args.symbol ?? "UNKNOWN",
+        interval: args.interval,
+        signal,
+        collectReplay: false,
+        ...(args.backtestOptions || {}),
+      });
+      return {
+        symbol: result.symbol,
+        interval: result.interval,
+        metrics: summarizeMetrics(result.metrics),
+        tradesPreview: result.positions.slice(0, 10).map((p) => ({
+          side: p.side,
+          entry: p.entryFill ?? p.entry,
+          exit: p.exit.price,
+          pnl: p.exit.pnl,
+          reason: p.exit.reason,
+        })),
+      };
+    },
+  },
+
+  walk_forward: {
+    description:
+      "Walk-forward optimize a named strategy over a parameter grid. Returns out-of-sample metrics and winner stability.",
+    handler: async (args) => {
+      const candles = await resolveCandles(args);
+      const factory = getStrategy(args.strategy);
+      const wf = walkForwardOptimize({
+        candles,
+        mode: args.mode ?? "rolling",
+        trainBars: args.trainBars,
+        testBars: args.testBars,
+        stepBars: args.stepBars ?? args.testBars,
+        scoreBy: args.scoreBy ?? "profitFactor",
+        parameterSets: expandGrid(args.grid),
+        signalFactory: (params) => factory(params),
+        backtestOptions: {
+          interval: args.interval,
+          collectReplay: false,
+          ...(args.backtestOptions || {}),
+        },
+      });
+      return {
+        windows: wf.windows.length,
+        metrics: summarizeMetrics(wf.metrics),
+        stability: wf.bestParamsSummary,
+        windowSummaries: wf.windows.map((w) => ({
+          bestParams: w.bestParams,
+          oosTrades: w.oosTrades,
+          profitable: w.profitable,
+          stabilityScore: w.stabilityScore,
+        })),
+      };
+    },
+  },
+};

package/src/metrics/annualize.js

@@ -0,0 +1,32 @@
+// src/metrics/annualize.js
+
+const TRADING_DAYS = 252;
+const RTH_HOURS = 6.5; // US regular trading hours per day
+const MS_PER_YEAR = 365 * 24 * 60 * 60 * 1000;
+
+// Known intra/inter-day intervals => periods per trading year.
+const INTERVAL_PERIODS = {
+  "1m": TRADING_DAYS * RTH_HOURS * 60,
+  "2m": TRADING_DAYS * RTH_HOURS * 30,
+  "5m": TRADING_DAYS * RTH_HOURS * 12,
+  "15m": TRADING_DAYS * RTH_HOURS * 4,
+  "30m": TRADING_DAYS * RTH_HOURS * 2,
+  "1h": TRADING_DAYS * RTH_HOURS,
+  "60m": TRADING_DAYS * RTH_HOURS,
+  "1d": TRADING_DAYS,
+  "1wk": 52,
+  "1mo": 12,
+};
+
+/**
+ * Number of bars in one year for the given interval. Used to annualize
+ * per-bar Sharpe/Sortino. Falls back to estBarMs (assuming a 24/7 clock)
+ * when the interval string is unknown, then to 252.
+ */
+export function periodsPerYear(interval, estBarMs) {
+  if (interval && INTERVAL_PERIODS[interval]) return INTERVAL_PERIODS[interval];
+  if (Number.isFinite(estBarMs) && estBarMs > 0) {
+    return Math.round(MS_PER_YEAR / estBarMs);
+  }
+  return TRADING_DAYS;
+}

package/src/metrics/benchmark.js

@@ -0,0 +1,55 @@
+// src/metrics/benchmark.js
+
+function mean(xs) {
+  return xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0;
+}
+
+/**
+ * Ordinary least squares of strategy returns on benchmark returns.
+ * Returns { alpha, beta, correlation, informationRatio, trackingError }.
+ * `alpha` is per-period excess return (intercept). All null when inputs are
+ * empty or length-mismatched.
+ */
+export function benchmarkStats(strategyReturns, benchmarkReturns) {
+  const nullStats = {
+    alpha: null,
+    beta: null,
+    correlation: null,
+    informationRatio: null,
+    trackingError: null,
+  };
+  if (
+    !Array.isArray(strategyReturns) ||
+    !Array.isArray(benchmarkReturns) ||
+    strategyReturns.length === 0 ||
+    strategyReturns.length !== benchmarkReturns.length
+  ) {
+    return nullStats;
+  }
+
+  const meanStrat = mean(strategyReturns);
+  const meanBench = mean(benchmarkReturns);
+
+  let covar = 0;
+  let varBench = 0;
+  let varStrat = 0;
+  for (let i = 0; i < strategyReturns.length; i += 1) {
+    const ds = strategyReturns[i] - meanStrat;
+    const db = benchmarkReturns[i] - meanBench;
+    covar += ds * db;
+    varBench += db * db;
+    varStrat += ds * ds;
+  }
+
+  const beta = varBench === 0 ? 0 : covar / varBench;
+  const alpha = meanStrat - beta * meanBench;
+  const denom = Math.sqrt(varStrat * varBench);
+  const correlation = denom === 0 ? 0 : covar / denom;
+
+  const active = strategyReturns.map((r, i) => r - benchmarkReturns[i]);
+  const meanActive = mean(active);
+  const trackingError = Math.sqrt(mean(active.map((a) => (a - meanActive) ** 2)));
+  const informationRatio = trackingError === 0 ? 0 : meanActive / trackingError;
+
+  return { alpha, beta, correlation, informationRatio, trackingError };
+}