tradelab 1.2.0 → 1.3.0

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/monteCarlo.js

@@ -35,6 +35,10 @@ export function monteCarlo({
   if (!Array.isArray(tradePnls) || tradePnls.length === 0) {
     throw new Error("monteCarlo() requires a non-empty tradePnls array");
   }
+  const runCount = Math.floor(Number(iterations));
+  if (!Number.isFinite(runCount) || runCount < 1) {
+    throw new Error("monteCarlo() requires positive iterations");
+  }
   const rng = makeRng(seed);
   const n = tradePnls.length;
   const block = Math.max(1, Math.floor(blockSize));
@@ -43,7 +47,7 @@ export function monteCarlo({
   const drawdowns = [];
   const pathSamples = Array.from({ length: n + 1 }, () => []);
 
-  for (let it = 0; it < iterations; it += 1) {
+  for (let it = 0; it < runCount; it += 1) {
     const path = [equityStart];
     let equity = equityStart;
     let filled = 0;
@@ -78,7 +82,7 @@ export function monteCarlo({
   });
 
   return {
-    iterations,
+    iterations: runCount,
     blockSize: block,
     finalEquity: bands(sortedFinals),
     maxDrawdown: bands(sortedDd),

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[];

package/types/live.d.ts

@@ -341,7 +341,8 @@ export interface DashboardServer {
 export function createDashboardServer(options: {
   source: {
     eventBus: EventBus;
-    getStatus?: () => Record<string, unknown>;
+    getStatus?: () => unknown;
+    refresh?: () => Promise<unknown>;
   };
   port?: number;
   maxBuffer?: number;
@@ -414,6 +415,7 @@ export interface TradingSessionOptions {
   minQty?: number;
   maxLeverage?: number;
   eventBus?: EventBus;
+  confirmLive?: boolean;
 }
 
 export interface SessionPlaceOrderOptions {