canli-backtest-mcp 0.5.0 → 0.6.0

package/README.md

@@ -7,6 +7,8 @@ ledger**, so the best of a search is judged against the whole search instead of
 
 Local stdio only: your prices, signals and ledgers never leave your machine.
 
+**[canli-backtest-mcp on canlicapital.com](https://canlicapital.com/mcp-servers/backtest)** · [All Canli Capital MCP servers](https://canlicapital.com/mcp-servers). Free, MIT-licensed. For every server behind one install, use [canli-mcp](https://www.npmjs.com/package/canli-mcp).
+
 ## Why
 
 Three mistakes make most agent-run backtests look better than they are:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canli-backtest-mcp",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "MCP server for backtests that refuse lookahead: point-in-time factors from SEC filings, cross-sectional backtests of any signal on your own prices, costs on actual trades, and every variant counted in a trial ledger.",
   "private": false,
   "type": "module",
@@ -35,7 +35,7 @@
     "url": "git+https://github.com/arhancanli/canlicapital.git",
     "directory": "mcp-backtest"
   },
-  "homepage": "https://canlicapital.com/mcp-servers",
+  "homepage": "https://canlicapital.com/mcp-servers/backtest",
   "bugs": {
     "url": "https://github.com/arhancanli/canlicapital/issues"
   },
@@ -52,8 +52,13 @@
     "deflated-sharpe",
     "overfitting",
     "factor-investing",
-    "ai-agents"
-  ],
+    "ai-agents",
+    "backtest",
+    "algorithmic-trading",
+    "sec-filings",
+    "mcp-server",
+    "claude",
+    "cursor"],
   "overrides": {
     "zod": "4.6.7"
   }

package/src/diversifiers.mjs

@@ -7,8 +7,8 @@ import { z } from "zod";
 import { readPanel } from "./panel-io.mjs";
 
 export const diversifiersInput = z.object({
-  book_file: z.string().min(1).max(1000).describe("A CSV of the book's daily returns: date, then one column per strategy or one for the whole book."),
-  candidates_file: z.string().min(1).max(1000).describe("A CSV of candidates' daily returns: date, then one column each."),
+  book_file: z.string().min(1).max(1000).regex(/^[^\0]+$/, "a file path").describe("A CSV of the book's daily returns: date, then one column per strategy or one for the whole book."),
+  candidates_file: z.string().min(1).max(1000).regex(/^[^\0]+$/, "a file path").describe("A CSV of candidates' daily returns: date, then one column each."),
   limit: z.number().int().min(1).max(100).optional().describe("How many to return; default 10."),
   min_days: z.number().int().min(60).max(100000).optional().describe("Days a candidate must share with the book; default 252."),
 }).strict();

package/src/exchange.mjs

@@ -19,7 +19,7 @@ export const EXCHANGE_LIMITS_TEXT = Object.freeze([
   "Personas are simple scripts with parameters someone chose. Different parameters give different cascades, so a result here is a question to ask of a real system, not an answer about it.",
 ]);
 
-const file = z.string().min(1).max(1000);
+const file = z.string().min(1).max(1000).regex(/^[^\0]+$/, "a file path");
 const agentId = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_-]{1,39}$/).refine((n) => !(n in {}), "that name is reserved");
 const assetId = z.string().regex(/^ART[0-9]{1,2}$/, "an exchange asset, such as ART1");
 const PERSONAS = ["market_maker", "value", "momentum", "noise", "deleverager", "stop_loss", "levered_long"];

package/src/panel-io.mjs

@@ -60,6 +60,12 @@ export function readPanel(path, name) {
   return parsePanel(bytes.toString("utf8"), name ?? path);
 }
 
+// A panel's dates alone (its first column, as readPanel would read them), without parsing every price.
+export function readPanelDates(path) {
+  const lines = readFileSync(path, "utf8").replace(/^\uFEFF/, "").split(/\r?\n/).filter((l) => l.trim() !== "");
+  return lines.slice(1).map((l) => { const c = l.indexOf(","); return (c < 0 ? l : l.slice(0, c)).trim().replace(/^"(.*)"$/, "$1"); });
+}
+
 export function writePanel(path, { dates, tickers, values }) {
   const rows = [["date", ...tickers].join(",")];
   dates.forEach((d, i) => rows.push([d, ...tickers.map((t) => (values[t][i] === null || values[t][i] === undefined ? "" : String(values[t][i])))].join(",")));

package/src/sweep-worker.mjs

@@ -1,5 +1,6 @@
 // One worker of breadth_sweep: reads the panel once, runs its share of the settings, posts each
-// result back. Runs in a worker thread; nothing here writes files.
+// result back with the book's daily returns (a flat day as 0), moved rather than copied. Runs in a
+// worker thread; nothing here writes files.
 import { parentPort, workerData } from "node:worker_threads";
 
 import { runBreadth } from "./breadth.mjs";
@@ -11,7 +12,8 @@ for (const c of combos) {
   try {
     const r = runBreadth({ ...base, signals: c.signals ?? null, minNames: c.min_names ?? 10, smoothing: c.smoothing ?? null, costBps: c.cost_bps ?? 10, targetVol: c.target_vol ?? 0.1, splitDate });
     const book = r.book ?? {};
-    parentPort.postMessage({ k: c.k, ok: true, sleeves: r.sleeves ?? 0, bets: r.effective_bets?.effective_bets ?? null, all: book.netted ?? null, search: book.search?.netted ?? null, test: book.test?.netted ?? null });
+    const daily = Float64Array.from(r.series?.book ?? [], (v) => (Number.isNaN(v) ? 0 : v));
+    parentPort.postMessage({ k: c.k, ok: true, sleeves: r.sleeves ?? 0, bets: r.effective_bets?.effective_bets ?? null, all: book.netted ?? null, search: book.search?.netted ?? null, test: book.test?.netted ?? null, daily }, [daily.buffer]);
   } catch (err) {
     parentPort.postMessage({ k: c.k, ok: false, error: String(err?.message ?? err).slice(0, 200) });
   }

package/src/sweep.mjs

@@ -5,14 +5,16 @@
 // Sharpe the best of that many trials would reach by luck alone (the expected maximum of N draws,
 // Bailey and Lopez de Prado), and, with split_date, the in-sample winner's Sharpe after the split is
 // reported beside it, the honest check. A shard carries the hash of the inputs and of the grid, so a
-// merge refuses shards run on other data or settings, and refuses gaps and duplicates.
+// merge refuses shards run on other data or settings, and refuses gaps and duplicates. Each variant's
+// daily book returns go back beside the answer, under a symbol key that JSON leaves out, for a server
+// that runs this package in its own process (canli-mcp) to measure overfitting across a session.
 import { createHash } from "node:crypto";
 import { readFileSync, writeFileSync } from "node:fs";
 import { availableParallelism } from "node:os";
 import { Worker } from "node:worker_threads";
 import { z } from "zod";
 
-import { readPanel } from "./panel-io.mjs";
+import { readPanel, readPanelDates } from "./panel-io.mjs";
 
 const filePath = z.string().min(1).max(1000);
 export const sweepInput = z.object({
@@ -97,19 +99,36 @@ function runParallel(files, combos, splitDate, workers) {
 }
 
 const r3 = (x) => (Number.isFinite(x) ? Math.round(x * 1000) / 1000 : null);
+const DAY_YEAR = 252; // breadth books are daily (breadth.mjs)
 
-// The summary over a complete set of results.
+// Each variant's daily book returns over every date of the prices file (a flat day as 0, so variants with longer
+// warm-ups line up), in every_trial's order. The key is canli-quant-mcp's: JSON leaves it out, so the answer, a shard
+// file and out_file never carry them. With split_date too, since the table shows every variant after the split.
+export const TRIAL_RETURNS = Symbol.for("canli.trial_returns");
+// And the date of each of those days, the prices file's first column, under canli-mcp's key, so a server can set the
+// returns against other strategies over the same months.
+export const TRIAL_DATES = Symbol.for("canli.trial_dates");
+const handOver = (daily, every, dates) => ({ [TRIAL_RETURNS]: every.k.map((k) => daily.get(k)), ...(dates ? { [TRIAL_DATES]: dates } : {}) });
+
+// The summary over a complete set of results. Every variant's Sharpe, best first, goes back with its combination k and
+// the days it was measured on (every_trial: one number when all variants share them, else one per variant), so a
+// server that counts the strategies tried in a session counts each one and not only the best, as with
+// canli-quant-mcp's strategy_sweep, and knows a variant again by its sweep_id and k. With split_date that is the
+// Sharpe the settings were chosen on, before the split.
 export function summarize(results, combos, splitDate) {
   const byK = new Map(results.map((r) => [r.k, r]));
-  const rows = combos.map((c) => { const r = byK.get(c.k) ?? {}; const pick = splitDate ? r.search : r.all; return [c.k, c.signals ? c.signals.join("+") : "all", c.smoothing ?? null, c.target_vol ?? null, c.cost_bps ?? null, c.min_names ?? null, r.sleeves ?? null, r.bets ?? null, pick?.sharpe ?? null, splitDate ? r.test?.sharpe ?? null : null, r.ok === false ? r.error : null]; });
+  const pickOf = (k) => { const r = byK.get(k) ?? {}; return splitDate ? r.search : r.all; };
+  const rows = combos.map((c) => { const r = byK.get(c.k) ?? {}; return [c.k, c.signals ? c.signals.join("+") : "all", c.smoothing ?? null, c.target_vol ?? null, c.cost_bps ?? null, c.min_names ?? null, r.sleeves ?? null, r.bets ?? null, pickOf(c.k)?.sharpe ?? null, splitDate ? r.test?.sharpe ?? null : null, r.ok === false ? r.error : null]; });
   const ranked = [...rows].sort((x, y) => (y[8] ?? -99) - (x[8] ?? -99));
   const best = ranked[0], luck = expectedMaxSharpe(rows.map((r) => r[8]));
-  const trials = rows.filter((r) => Number.isFinite(r[8])).length;
+  const tried = ranked.filter((r) => Number.isFinite(r[8])), days = tried.map((r) => pickOf(r[0])?.days ?? null);
+  const trials = tried.length;
   return {
     trials, columns: ["k", "signals", "smoothing", "target_vol", "cost_bps", "min_names", "sleeves", "effective_bets", splitDate ? "sharpe_search" : "sharpe", "sharpe_after_split", "error"],
     rows: ranked,
     best: best ? { k: best[0], settings: combos[best[0]], sharpe: best[8], ...(splitDate ? { sharpe_after_split: best[9] } : {}) } : null,
     luck: { expected_best_sharpe_by_luck: r3(luck), best_minus_luck: best && luck != null && Number.isFinite(best[8]) ? r3(best[8] - luck) : null, note: `The best of ${trials} trials would reach about ${r3(luck)} by luck alone, from the spread of their Sharpes; only the excess above it is evidence. Correlated trials (they share data) make this benchmark conservative.` },
+    every_trial: { periods: trials && days.every((d) => d === days[0]) ? days[0] : days, periods_per_year: DAY_YEAR, k: tried.map((r) => r[0]), sharpes: tried.map((r) => r[8]) },
   };
 }
 
@@ -139,12 +158,19 @@ export async function breadthSweep(session, args) {
   const t0 = Date.now();
   const results = await runParallel(files, mine, a.split_date ?? null, workers);
   const seconds = Math.round((Date.now() - t0) / 100) / 10;
+  // The returns leave the results, which a shard file and a shard's answer carry; a merge has none to hand over.
+  const daily = new Map();
+  for (const r of results) if (r.daily) { daily.set(r.k, r.daily); delete r.daily; }
+  const dates = daily.size ? readPanelDates(files.prices_file) : null;
   if (a.shard) {
     const shard = { schema: "canli.breadth-sweep-shard.v1", sweep_id: sweepId, shard: a.shard, inputs, split_date: a.split_date ?? null, combos, results };
     if (a.out_file) writeFileSync(a.out_file, JSON.stringify(shard));
-    return { sweep_id: sweepId, shard: a.shard, ran: mine.length, of: combos.length, seconds, workers, ...(a.out_file ? { shard_file: a.out_file } : { results }), next: "Run the other shards (same files, grid and split_date) on any machine, then breadth_sweep with merge_files." };
+    // The shard's own variants, as the whole sweep lists them, so a server that counts tries counts them as they run
+    // and not first at the merge, which then adds only the variants that server has not seen.
+    const { every_trial } = summarize(results, mine, a.split_date ?? null);
+    return { sweep_id: sweepId, shard: a.shard, ran: mine.length, of: combos.length, seconds, workers, ...(a.out_file ? { shard_file: a.out_file } : { results }), every_trial, next: "Run the other shards (same files, grid and split_date) on any machine, then breadth_sweep with merge_files.", ...handOver(daily, every_trial, dates) };
   }
   const out = { sweep_id: sweepId, inputs, workers, seconds, ...summarize(results, combos, a.split_date ?? null) };
   if (a.out_file) writeFileSync(a.out_file, JSON.stringify(out));
-  return { ...out, limits: ["Trials share the same data, so they are correlated: counting each as an independent trial makes the luck benchmark conservative (it overstates luck).", "Judge the chosen settings on sharpe_after_split only if nothing was chosen on those dates.", "Not investment advice."] };
+  return { ...out, limits: ["Trials share the same data, so they are correlated: counting each as an independent trial makes the luck benchmark conservative (it overstates luck).", "Judge the chosen settings on sharpe_after_split only if nothing was chosen on those dates.", "Not investment advice."], ...handOver(daily, out.every_trial, dates) };
 }