tradelab 1.2.1 → 1.3.1

package/src/mcp/tools.js

@@ -5,6 +5,10 @@ import { getStrategy, listStrategies } from "../strategies/index.js";
 import { grid } from "../engine/grid.js";
 import { monteCarlo, deflatedSharpe } from "../research/index.js";
 import { liveTools } from "./liveTools.js";
+import { researchTools as researchSessionTools } from "./researchSession.js";
+import { createResearchStore } from "../research/store.js";
+
+const researchStore = createResearchStore();
 
 function summarizeMetrics(metrics) {
   const {
@@ -93,10 +97,31 @@ export const researchTools = {
         collectReplay: false,
         ...(args.backtestOptions || {}),
       });
+      const metrics = summarizeMetrics(result.metrics);
+      if (args.researchId) {
+        let verdict = null;
+        try {
+          const psr = deflatedSharpe({
+            sharpe: result.metrics.sharpe,
+            sampleSize: result.metrics.trades,
+            numTrials: args.numTrials ?? 1,
+          });
+          verdict = {
+            deflatedSharpe: psr,
+            overfit: Number.isFinite(psr) ? psr < 0.9 : false,
+            note: Number.isFinite(psr) ? `PSR ${(psr * 100).toFixed(1)}%` : "insufficient data",
+          };
+        } catch {
+          verdict = { deflatedSharpe: null, overfit: false, note: "verdict unavailable" };
+        }
+        await researchStore.log(args.researchId, {
+          hypothesis: args.strategy, params: args.params || {}, metrics, verdict,
+        }).catch(() => {});
+      }
       return {
         symbol: result.symbol,
         interval: result.interval,
-        metrics: summarizeMetrics(result.metrics),
+        metrics,
         tradesPreview: result.positions.slice(0, 10).map((p) => ({
           side: p.side,
           entry: p.entryFill ?? p.entry,
@@ -168,7 +193,7 @@ export const researchPlusTools = {
           metrics,
           monteCarlo: null,
           deflatedSharpe: null,
-          note: `Only ${tradePnls.length} trade(s) — need at least 2 for statistical analysis.`,
+          note: `Only ${tradePnls.length} trade(s), need at least 2 for statistical analysis.`,
         };
       }
       const mc = monteCarlo({
@@ -262,4 +287,4 @@ export const researchPlusTools = {
   },
 };
 
-export const mcpTools = { ...researchTools, ...researchPlusTools, ...liveTools };
+export const mcpTools = { ...researchTools, ...researchPlusTools, ...liveTools, ...researchSessionTools() };

package/src/reporting/summarize.js

@@ -0,0 +1,43 @@
+// src/reporting/summarize.js
+
+function pct(value, digits = 1) {
+  return Number.isFinite(value) ? `${value.toFixed(digits)}%` : "n/a";
+}
+
+/**
+ * Render a metrics object into one plain-English paragraph. Optionally append an
+ * overfitting caveat from a research verdict. No em-dashes (house style).
+ *
+ * @param {object} metrics - Fields: trades, winRate, maxDrawdownPct, totalReturnPct, sharpe.
+ * @param {{ verdict?: { overfit?: boolean, note?: string } }} [options]
+ * @returns {string}
+ */
+export function summarize(metrics = {}, { verdict } = {}) {
+  const trades = Number.isFinite(metrics.trades) ? metrics.trades : 0;
+  const win = Number.isFinite(metrics.winRate) ? Math.round(metrics.winRate * 100) : null;
+  const dd = Number.isFinite(metrics.maxDrawdownPct)
+    ? metrics.maxDrawdownPct
+    : Number.isFinite(metrics.maxDrawdown)
+      ? metrics.maxDrawdown * 100
+      : null;
+  const ret = Number.isFinite(metrics.totalReturnPct) ? metrics.totalReturnPct : null;
+  const sharpe = Number.isFinite(metrics.sharpe) ? metrics.sharpe : null;
+
+  if (trades === 0) return "Ran with 0 trades, so there is nothing to evaluate yet.";
+
+  const parts = [`Made ${trades} trades`];
+  if (win !== null) parts.push(`won ${win}% of them`);
+  if (ret !== null) parts.push(`for a ${pct(ret)} total return`);
+  if (dd !== null) parts.push(`with a worst drawdown of ${pct(dd)}`);
+
+  let text = parts.join(", ");
+  if (sharpe !== null) {
+    text += ` (Sharpe ${sharpe.toFixed(2)})`;
+  }
+  text += ".";
+
+  if (verdict && verdict.overfit) {
+    text += ` Caution: robustness checks flag this result as likely overfit${verdict.note ? ` (${verdict.note})` : ""}.`;
+  }
+  return text;
+}

package/src/research/store.js

@@ -0,0 +1,67 @@
+// src/research/store.js
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const DEFAULT_DIR = ".tradelab/research";
+
+function fileFor(dir, id) {
+  if (!/^[\w.-]+$/.test(String(id))) throw new Error(`invalid research id: ${id}`);
+  return join(dir, `${id}.json`);
+}
+
+async function load(dir, id) {
+  try {
+    const raw = await readFile(fileFor(dir, id), "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+async function save(dir, record) {
+  await mkdir(dir, { recursive: true });
+  await writeFile(fileFor(dir, record.id), JSON.stringify(record, null, 2));
+  return record;
+}
+
+function bestSharpe(entries) {
+  let best = null;
+  for (const e of entries) {
+    const s = e.metrics?.sharpe;
+    if (Number.isFinite(s) && (best === null || s > best.sharpe)) best = { sharpe: s, params: e.params };
+  }
+  return best;
+}
+
+export function createResearchStore({ dir = DEFAULT_DIR } = {}) {
+  return {
+    async open(id, goal = "") {
+      const existing = await load(dir, id);
+      if (existing) return existing;
+      const record = { id, goal, createdAt: new Date().toISOString(), closedAt: null, entries: [] };
+      return save(dir, record);
+    },
+    async log(id, { hypothesis = "", params = {}, metrics = {}, verdict = null } = {}) {
+      const record = (await load(dir, id)) || { id, goal: "", createdAt: new Date().toISOString(), closedAt: null, entries: [] };
+      const entry = { at: new Date().toISOString(), hypothesis, params, metrics, verdict };
+      record.entries.push(entry);
+      await save(dir, record);
+      return entry;
+    },
+    async recall(id, limit = 10) {
+      const record = (await load(dir, id)) || { goal: "", entries: [] };
+      const entries = record.entries.slice(-limit);
+      const best = bestSharpe(record.entries);
+      const flagged = record.entries.filter((e) => e.verdict?.overfit).length;
+      const summary = record.entries.length
+        ? `Best Sharpe so far: ${best ? best.sharpe.toFixed(2) : "n/a"}${best ? ` via ${JSON.stringify(best.params)}` : ""}. ${flagged} of ${record.entries.length} flagged overfit.`
+        : "No entries logged yet.";
+      return { goal: record.goal, entries, summary };
+    },
+    async close(id) {
+      const record = (await load(dir, id)) || { id, goal: "", createdAt: new Date().toISOString(), entries: [] };
+      record.closedAt = new Date().toISOString();
+      return save(dir, record);
+    },
+  };
+}

package/types/index.d.ts

@@ -724,6 +724,36 @@ export function registerStrategy(name: string, def: StrategyDefinition): void;
 export function listStrategies(): StrategySummary[];
 export function getStrategy(name: string): StrategyDefinition["factory"];
 
+export interface ResearchEntry {
+  at: string;
+  hypothesis?: string;
+  params?: Record<string, unknown>;
+  metrics?: Record<string, unknown>;
+  verdict?: Record<string, unknown> | null;
+}
+
+export interface ResearchRecord {
+  id: string;
+  goal: string;
+  createdAt: string;
+  closedAt: string | null;
+  entries: ResearchEntry[];
+}
+
+export interface ResearchStore {
+  open(id: string, goal?: string): Promise<ResearchRecord>;
+  log(id: string, options?: {
+    hypothesis?: string;
+    params?: Record<string, unknown>;
+    metrics?: Record<string, unknown>;
+    verdict?: Record<string, unknown> | null;
+  }): Promise<ResearchEntry>;
+  recall(id: string, limit?: number): Promise<{ goal: string; entries: ResearchEntry[]; summary: string }>;
+  close(id: string): Promise<ResearchRecord>;
+}
+
+export function createResearchStore(options?: { dir?: string }): ResearchStore;
+
 export namespace research {
   function monteCarlo(options: {
     tradePnls: number[];