horizon-code 0.5.1 → 0.6.1

package/src/strategy/ledger.ts

@@ -0,0 +1,185 @@
+// Performance ledger — persistent log of every backtest and run
+// Storage: ~/.horizon/ledger/<strategy-slug>.jsonl (append-only)
+
+import { homedir } from "os";
+import { resolve, join } from "path";
+import { existsSync, mkdirSync, appendFileSync, readFileSync } from "fs";
+import { createHash } from "crypto";
+
+const LEDGER_ROOT = resolve(homedir(), ".horizon", "ledger");
+
+export interface LedgerEntry {
+  strategy_name: string;
+  code_hash: string;
+  type: "backtest" | "run";
+  timestamp: string;
+  duration_secs: number;
+  params: Record<string, unknown>;
+  metrics: {
+    pnl: number;
+    rpnl: number;
+    upnl: number;
+    sharpe: number;
+    max_dd: number;
+    win_rate: number;
+    trades: number;
+    exposure: number;
+    [key: string]: unknown;
+  };
+  label?: string;
+}
+
+function ensureDir(): void {
+  if (!existsSync(LEDGER_ROOT)) mkdirSync(LEDGER_ROOT, { recursive: true });
+}
+
+function slugify(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_|_$/g, "");
+}
+
+export function codeHash(code: string): string {
+  return createHash("sha256").update(code).digest("hex").slice(0, 12);
+}
+
+/** Append a new entry to the ledger (append-only JSONL) */
+export function logEntry(entry: LedgerEntry): void {
+  ensureDir();
+  const slug = slugify(entry.strategy_name);
+  const path = join(LEDGER_ROOT, `${slug}.jsonl`);
+  appendFileSync(path, JSON.stringify(entry) + "\n");
+}
+
+/** Get all entries for a strategy, newest first */
+export function getHistory(name: string): LedgerEntry[] {
+  ensureDir();
+  const slug = slugify(name);
+  const path = join(LEDGER_ROOT, `${slug}.jsonl`);
+  if (!existsSync(path)) return [];
+
+  const lines = readFileSync(path, "utf-8").split("\n").filter(Boolean);
+  const entries: LedgerEntry[] = [];
+  for (const line of lines) {
+    try { entries.push(JSON.parse(line)); } catch {}
+  }
+  return entries.reverse();
+}
+
+/** Find the best run by a specific metric (e.g., "sharpe", "pnl", "win_rate") */
+export function getBestRun(name: string, metric: string = "sharpe"): LedgerEntry | null {
+  const history = getHistory(name);
+  if (history.length === 0) return null;
+
+  return history.reduce((best, entry) => {
+    const bestVal = (best.metrics as any)[metric] ?? -Infinity;
+    const entryVal = (entry.metrics as any)[metric] ?? -Infinity;
+    return entryVal > bestVal ? entry : best;
+  });
+}
+
+/** Generate a strategy performance report */
+export function generateReport(name: string): {
+  total_runs: number;
+  backtests: number;
+  live_runs: number;
+  best_sharpe: LedgerEntry | null;
+  best_pnl: LedgerEntry | null;
+  worst_dd: LedgerEntry | null;
+  avg_sharpe: number;
+  avg_win_rate: number;
+  avg_pnl: number;
+  trend: string;
+  versions_tested: number;
+  summary: string;
+} {
+  const history = getHistory(name);
+  if (history.length === 0) {
+    return {
+      total_runs: 0, backtests: 0, live_runs: 0,
+      best_sharpe: null, best_pnl: null, worst_dd: null,
+      avg_sharpe: 0, avg_win_rate: 0, avg_pnl: 0,
+      trend: "no data", versions_tested: 0,
+      summary: `No performance history for "${name}".`,
+    };
+  }
+
+  const backtests = history.filter(e => e.type === "backtest");
+  const runs = history.filter(e => e.type === "run");
+  const uniqueHashes = new Set(history.map(e => e.code_hash));
+
+  const sharpes = history.map(e => e.metrics.sharpe).filter(v => isFinite(v));
+  const winRates = history.map(e => e.metrics.win_rate).filter(v => isFinite(v));
+  const pnls = history.map(e => e.metrics.pnl).filter(v => isFinite(v));
+
+  const avg = (arr: number[]) => arr.length > 0 ? arr.reduce((a, b) => a + b, 0) / arr.length : 0;
+
+  // Trend: compare recent 3 vs older entries
+  let trend = "stable";
+  if (sharpes.length >= 6) {
+    const recent = avg(sharpes.slice(0, 3));
+    const older = avg(sharpes.slice(3, 6));
+    if (recent > older * 1.15) trend = "improving";
+    else if (recent < older * 0.85) trend = "degrading";
+  }
+
+  const bestSharpe = getBestRun(name, "sharpe");
+  const bestPnl = getBestRun(name, "pnl");
+  const worstDd = history.reduce((worst, e) => {
+    return (e.metrics.max_dd > (worst?.metrics.max_dd ?? 0)) ? e : worst;
+  }, history[0]!);
+
+  const summary = [
+    `${history.length} runs (${backtests.length} backtests, ${runs.length} live) across ${uniqueHashes.size} code versions.`,
+    `Avg Sharpe: ${avg(sharpes).toFixed(2)}, Avg Win Rate: ${(avg(winRates) * 100).toFixed(1)}%, Avg P&L: $${avg(pnls).toFixed(2)}.`,
+    bestSharpe ? `Best Sharpe: ${bestSharpe.metrics.sharpe.toFixed(2)} (${bestSharpe.code_hash}, ${new Date(bestSharpe.timestamp).toLocaleDateString()})` : "",
+    `Trend: ${trend}.`,
+  ].filter(Boolean).join(" ");
+
+  return {
+    total_runs: history.length,
+    backtests: backtests.length,
+    live_runs: runs.length,
+    best_sharpe: bestSharpe,
+    best_pnl: bestPnl,
+    worst_dd: worstDd ?? null,
+    avg_sharpe: avg(sharpes),
+    avg_win_rate: avg(winRates),
+    avg_pnl: avg(pnls),
+    trend,
+    versions_tested: uniqueHashes.size,
+    summary,
+  };
+}
+
+/** Get performance comparison between code versions */
+export function compareVersions(name: string): { hash: string; runs: number; avg_sharpe: number; avg_pnl: number; best_sharpe: number }[] {
+  const history = getHistory(name);
+  const byHash = new Map<string, LedgerEntry[]>();
+
+  for (const entry of history) {
+    const existing = byHash.get(entry.code_hash) ?? [];
+    existing.push(entry);
+    byHash.set(entry.code_hash, existing);
+  }
+
+  return [...byHash.entries()].map(([hash, entries]) => {
+    const sharpes = entries.map(e => e.metrics.sharpe).filter(v => isFinite(v));
+    const pnls = entries.map(e => e.metrics.pnl).filter(v => isFinite(v));
+    const avg = (arr: number[]) => arr.length > 0 ? arr.reduce((a, b) => a + b, 0) / arr.length : 0;
+    return {
+      hash,
+      runs: entries.length,
+      avg_sharpe: avg(sharpes),
+      avg_pnl: avg(pnls),
+      best_sharpe: sharpes.length > 0 ? Math.max(...sharpes) : 0,
+    };
+  }).sort((a, b) => b.avg_sharpe - a.avg_sharpe);
+}
+
+/** List all strategies with ledger entries */
+export function listLedgerStrategies(): string[] {
+  ensureDir();
+  const { readdirSync } = require("fs");
+  return readdirSync(LEDGER_ROOT)
+    .filter((f: string) => f.endsWith(".jsonl"))
+    .map((f: string) => f.replace(".jsonl", ""));
+}