@livefolio/sdk 0.3.6 → 0.3.7

package/dist/index.d.ts

@@ -372,6 +372,85 @@ declare class PortfolioHandle {
     trades(target: AllocationHandle, prices: [TickerHandle, number][], date: string): Trade[];
 }
 
+interface MetricsOptions {
+    riskFreeRate?: number;
+    topDrawdowns?: number;
+    varConfidence?: number;
+}
+interface DrawdownEntry {
+    peakDate: string;
+    troughDate: string;
+    recoveryDate: string | null;
+    depth: number;
+    durationDays: number;
+    underwaterDays: number;
+}
+interface MonthlyReturnsTable {
+    rows: Array<{
+        year: number;
+        months: (number | null)[];
+        ytd: number | null;
+    }>;
+}
+interface MetricsResult {
+    range: {
+        from: string;
+        to: string;
+        years: number;
+    };
+    returns: {
+        totalReturn: number;
+        cagr: number;
+        bestYear: {
+            year: number;
+            return: number;
+        } | null;
+        worstYear: {
+            year: number;
+            return: number;
+        } | null;
+        bestMonth: {
+            date: string;
+            return: number;
+        } | null;
+        worstMonth: {
+            date: string;
+            return: number;
+        } | null;
+        pctPositiveMonths: number;
+    };
+    risk: {
+        volatility: number;
+        downsideDeviation: number;
+        maxDrawdown: DrawdownEntry;
+        currentDrawdown: number;
+        ulcerIndex: number;
+        skew: number;
+        kurtosis: number;
+        var95: number;
+        cvar95: number;
+    };
+    riskAdjusted: {
+        sharpe: number;
+        sortino: number;
+        calmar: number;
+    };
+    activity: {
+        rebalances: number;
+        trades: number;
+        turnover: number;
+        winRate: number;
+    };
+    tables: {
+        drawdowns: DrawdownEntry[];
+        monthly: MonthlyReturnsTable;
+        yearly: Array<{
+            year: number;
+            return: number;
+        }>;
+    };
+}
+
 interface SimulateOptions {
     from: string;
     to: string;
@@ -466,6 +545,7 @@ declare class SimulationHandle {
      *   the current UTC ISO date; callers with non-UTC semantics or after-hours
      *   rollover should supply their own.
      */
+    metrics(options?: MetricsOptions): MetricsResult;
     pushAndPreview(quotes: Record<string, number>, options?: {
         date?: string;
     }): Promise<LivePreviewState>;
@@ -628,4 +708,25 @@ declare function allocationsEqual(a: AllocationHandle | null, b: AllocationHandl
 
 declare function computeRebalanceDates(tradingDays: string[], freq: TradingFreq, offset: number): Set<string>;
 
-export { AllocationHandle, type Comparison, type DailyBar, type DateRange, IndicatorHandle, type IndicatorIdentity, type IndicatorType, type LiveEvaluator, type LivePreviewState, type LiveRuleState, type LiveSignalState, type LivefolioClient, type LivefolioClientOptions, type MarketProvider, PortfolioHandle, type PortfolioSnapshot, type PriceStream, SignalHandle, type SignalIdentity, type SimulateOptions, SimulationHandle, type StorageProvider, type StrategyBar, type StrategyDefinition, StrategyHandle, type StrategyLiveState, type StrategyOptions, type StrategyReferenceData, type StrategyRule, type StrategyRuleDefinition, type StrategySeriesEntry, type StreamStatus, TickerHandle, type Trade, type TradingFreq, type Unit, allocationsEqual, computeRebalanceDates, createClient };
+declare function computeMetrics(series: DailyBar[], trades: Trade[], options?: MetricsOptions): MetricsResult;
+
+declare function sharpe(returns: number[], rfAnnual: number): number;
+declare function sortino(returns: number[], rfAnnual: number): number;
+
+declare function computeDrawdownTable(series: DailyBar[], topN: number): DrawdownEntry[];
+
+interface MonthlyReturn {
+    year: number;
+    month: number;
+    return: number;
+    partial: boolean;
+}
+interface YearlyReturn {
+    year: number;
+    return: number;
+    partial: boolean;
+}
+declare function monthlyReturns(series: DailyBar[]): MonthlyReturn[];
+declare function yearlyReturns(series: DailyBar[]): YearlyReturn[];
+
+export { AllocationHandle, type Comparison, type DailyBar, type DateRange, type DrawdownEntry, IndicatorHandle, type IndicatorIdentity, type IndicatorType, type LiveEvaluator, type LivePreviewState, type LiveRuleState, type LiveSignalState, type LivefolioClient, type LivefolioClientOptions, type MarketProvider, type MetricsOptions, type MetricsResult, type MonthlyReturn, type MonthlyReturnsTable, PortfolioHandle, type PortfolioSnapshot, type PriceStream, SignalHandle, type SignalIdentity, type SimulateOptions, SimulationHandle, type StorageProvider, type StrategyBar, type StrategyDefinition, StrategyHandle, type StrategyLiveState, type StrategyOptions, type StrategyReferenceData, type StrategyRule, type StrategyRuleDefinition, type StrategySeriesEntry, type StreamStatus, TickerHandle, type Trade, type TradingFreq, type Unit, type YearlyReturn, allocationsEqual, computeDrawdownTable, computeMetrics, monthlyReturns as computeMonthlyReturns, computeRebalanceDates, sharpe as computeSharpe, sortino as computeSortino, yearlyReturns as computeYearlyReturns, createClient };

package/dist/index.js

@@ -222,20 +222,20 @@ function returnNext(prev, newRaw, lookback, mode = "pct") {
 // src/computations/volatility.ts
 function computeVolatility(bars, lookback) {
   if (bars.length < lookback + 1) return [];
-  const dailyReturns = [];
+  const dailyReturns2 = [];
   for (let i = 1; i < bars.length; i++) {
-    dailyReturns.push({
+    dailyReturns2.push({
       date: bars[i].date,
       value: bars[i].value / bars[i - 1].value - 1
     });
   }
-  if (dailyReturns.length < lookback) return [];
+  if (dailyReturns2.length < lookback) return [];
   const result = [];
-  for (let i = lookback - 1; i < dailyReturns.length; i++) {
-    const window = dailyReturns.slice(i - lookback + 1, i + 1);
-    const mean = window.reduce((s, r) => s + r.value, 0) / lookback;
-    const variance = window.reduce((s, r) => s + (r.value - mean) ** 2, 0) / lookback;
-    result.push({ date: dailyReturns[i].date, value: Math.sqrt(variance) });
+  for (let i = lookback - 1; i < dailyReturns2.length; i++) {
+    const window = dailyReturns2.slice(i - lookback + 1, i + 1);
+    const mean2 = window.reduce((s, r) => s + r.value, 0) / lookback;
+    const variance = window.reduce((s, r) => s + (r.value - mean2) ** 2, 0) / lookback;
+    result.push({ date: dailyReturns2[i].date, value: Math.sqrt(variance) });
   }
   return result;
 }
@@ -247,8 +247,8 @@ function volatilityNext(prev, newRaw, lookback) {
   const tail = [...prev.tail.slice(1), newRaw];
   const returns = [];
   for (let i = 1; i < tail.length; i++) returns.push(tail[i] / tail[i - 1] - 1);
-  const mean = returns.reduce((s, r) => s + r, 0) / lookback;
-  const variance = returns.reduce((s, r) => s + (r - mean) ** 2, 0) / lookback;
+  const mean2 = returns.reduce((s, r) => s + r, 0) / lookback;
+  const variance = returns.reduce((s, r) => s + (r - mean2) ** 2, 0) / lookback;
   return { value: Math.sqrt(variance), state: { tail } };
 }
 
@@ -1527,6 +1527,506 @@ function runSimulation(bars, prices, rebalanceDates, portfolio) {
   return { series, trades, finalPortfolio };
 }
 
+// src/metrics/returns.ts
+function dailyReturns(series) {
+  const out = [];
+  for (let i = 1; i < series.length; i++) {
+    const prev = series[i - 1].value;
+    const curr = series[i].value;
+    out.push(curr / prev - 1);
+  }
+  return out;
+}
+function ymd(date) {
+  return {
+    y: Number(date.slice(0, 4)),
+    m: Number(date.slice(5, 7)) - 1,
+    d: Number(date.slice(8, 10))
+  };
+}
+function lastDayOfMonth(year, month) {
+  return new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
+}
+function monthlyReturns(series) {
+  if (series.length < 2) return [];
+  const buckets = [];
+  for (const bar of series) {
+    const { y, m } = ymd(bar.date);
+    const last = buckets[buckets.length - 1];
+    if (!last || last.year !== y || last.month !== m) {
+      buckets.push({
+        year: y,
+        month: m,
+        firstDate: bar.date,
+        firstValue: bar.value,
+        lastDate: bar.date,
+        lastValue: bar.value
+      });
+    } else {
+      last.lastDate = bar.date;
+      last.lastValue = bar.value;
+    }
+  }
+  const out = [];
+  for (let i = 0; i < buckets.length; i++) {
+    const b = buckets[i];
+    const prevLast = i === 0 ? b.firstValue : buckets[i - 1].lastValue;
+    const ret = b.lastValue / prevLast - 1;
+    const startsAtMonthStart = ymd(b.firstDate).d === 1;
+    const endsAtMonthEnd = ymd(b.lastDate).d === lastDayOfMonth(b.year, b.month);
+    const isFirst = i === 0;
+    const isLast = i === buckets.length - 1;
+    const partial = isFirst && !startsAtMonthStart || isLast && !endsAtMonthEnd;
+    out.push({ year: b.year, month: b.month, return: ret, partial });
+  }
+  return out;
+}
+function yearlyReturns(series) {
+  if (series.length < 2) return [];
+  const buckets = [];
+  for (const bar of series) {
+    const { y } = ymd(bar.date);
+    const last = buckets[buckets.length - 1];
+    if (!last || last.year !== y) {
+      buckets.push({
+        year: y,
+        firstDate: bar.date,
+        firstValue: bar.value,
+        lastDate: bar.date,
+        lastValue: bar.value
+      });
+    } else {
+      last.lastDate = bar.date;
+      last.lastValue = bar.value;
+    }
+  }
+  const out = [];
+  for (let i = 0; i < buckets.length; i++) {
+    const b = buckets[i];
+    const prevLast = i === 0 ? b.firstValue : buckets[i - 1].lastValue;
+    const ret = b.lastValue / prevLast - 1;
+    const isFirst = i === 0;
+    const isLast = i === buckets.length - 1;
+    const startsAtYearStart = b.firstDate.endsWith("-01-01");
+    const endsAtYearEnd = b.lastDate.endsWith("-12-31");
+    const partial = isFirst && !startsAtYearStart || isLast && !endsAtYearEnd;
+    out.push({ year: b.year, return: ret, partial });
+  }
+  return out;
+}
+
+// src/metrics/summary.ts
+var DAY_MS = 24 * 60 * 60 * 1e3;
+function dateUTC(iso) {
+  return Date.UTC(Number(iso.slice(0, 4)), Number(iso.slice(5, 7)) - 1, Number(iso.slice(8, 10)));
+}
+function totalReturn(series) {
+  return series[series.length - 1].value / series[0].value - 1;
+}
+function years(series) {
+  const first = dateUTC(series[0].date);
+  const last = dateUTC(series[series.length - 1].date);
+  return (last - first) / DAY_MS / 365.25;
+}
+function cagr(series) {
+  const y = years(series);
+  if (y <= 0) return 0;
+  const ratio = series[series.length - 1].value / series[0].value;
+  return Math.pow(ratio, 1 / y) - 1;
+}
+function bestYear(yr) {
+  let best = null;
+  for (const y of yr) {
+    if (y.partial) continue;
+    if (!best || y.return > best.return) best = y;
+  }
+  return best ? { year: best.year, return: best.return } : null;
+}
+function worstYear(yr) {
+  let worst = null;
+  for (const y of yr) {
+    if (y.partial) continue;
+    if (!worst || y.return < worst.return) worst = y;
+  }
+  return worst ? { year: worst.year, return: worst.return } : null;
+}
+function monthKey(m) {
+  return `${m.year}-${String(m.month + 1).padStart(2, "0")}`;
+}
+function bestMonth(mr) {
+  let best = null;
+  for (const m of mr) {
+    if (m.partial) continue;
+    if (!best || m.return > best.return) best = m;
+  }
+  return best ? { date: monthKey(best), return: best.return } : null;
+}
+function worstMonth(mr) {
+  let worst = null;
+  for (const m of mr) {
+    if (m.partial) continue;
+    if (!worst || m.return < worst.return) worst = m;
+  }
+  return worst ? { date: monthKey(worst), return: worst.return } : null;
+}
+function pctPositiveMonths(mr) {
+  let total = 0;
+  let pos = 0;
+  for (const m of mr) {
+    if (m.partial) continue;
+    total++;
+    if (m.return > 0) pos++;
+  }
+  return total === 0 ? 0 : pos / total;
+}
+
+// src/metrics/risk.ts
+var TRADING_DAYS = 252;
+function mean(xs) {
+  if (xs.length === 0) return 0;
+  let s = 0;
+  for (const x of xs) s += x;
+  return s / xs.length;
+}
+function stdev(xs) {
+  if (xs.length < 2) return 0;
+  const m = mean(xs);
+  let s = 0;
+  for (const x of xs) {
+    const d = x - m;
+    s += d * d;
+  }
+  return Math.sqrt(s / (xs.length - 1));
+}
+function volatility(returns) {
+  return stdev(returns) * Math.sqrt(TRADING_DAYS);
+}
+function downsideDeviation(returns, marDaily) {
+  if (returns.length === 0) return 0;
+  let s = 0;
+  for (const r of returns) {
+    const d = Math.min(0, r - marDaily);
+    s += d * d;
+  }
+  return Math.sqrt(s / returns.length) * Math.sqrt(TRADING_DAYS);
+}
+function skewness(xs) {
+  const n = xs.length;
+  if (n < 3) return 0;
+  const m = mean(xs);
+  const s = stdev(xs);
+  if (s === 0) return 0;
+  let sum = 0;
+  for (const x of xs) {
+    const z = (x - m) / s;
+    sum += z * z * z;
+  }
+  return n / ((n - 1) * (n - 2)) * sum;
+}
+function excessKurtosis(xs) {
+  const n = xs.length;
+  if (n < 4) return 0;
+  const m = mean(xs);
+  const s = stdev(xs);
+  if (s === 0) return 0;
+  let sum = 0;
+  for (const x of xs) {
+    const z = (x - m) / s;
+    sum += z * z * z * z;
+  }
+  const term1 = n * (n + 1) / ((n - 1) * (n - 2) * (n - 3));
+  const term2 = 3 * (n - 1) * (n - 1) / ((n - 2) * (n - 3));
+  return term1 * sum - term2;
+}
+function quantile(sortedAsc, p) {
+  if (sortedAsc.length === 0) return NaN;
+  if (sortedAsc.length === 1) return sortedAsc[0];
+  const idx = p * (sortedAsc.length - 1);
+  const lo = Math.floor(idx);
+  const hi = Math.ceil(idx);
+  if (lo === hi) return sortedAsc[lo];
+  const frac = idx - lo;
+  return sortedAsc[lo] * (1 - frac) + sortedAsc[hi] * frac;
+}
+function historicalVar(returns, confidence) {
+  if (returns.length === 0) return 0;
+  const sorted = [...returns].sort((a, b) => a - b);
+  const q = quantile(sorted, 1 - confidence);
+  return Math.max(0, -q);
+}
+function historicalCvar(returns, confidence) {
+  if (returns.length === 0) return 0;
+  const sorted = [...returns].sort((a, b) => a - b);
+  const q = quantile(sorted, 1 - confidence);
+  const tail = sorted.filter((r) => r <= q);
+  if (tail.length === 0) return 0;
+  return Math.max(0, -mean(tail));
+}
+function ulcerIndex(series) {
+  if (series.length === 0) return 0;
+  let runningMax = -Infinity;
+  let sumSq = 0;
+  for (const bar of series) {
+    if (bar.value > runningMax) runningMax = bar.value;
+    const ddPct = (bar.value - runningMax) / runningMax * 100;
+    sumSq += ddPct * ddPct;
+  }
+  return Math.sqrt(sumSq / series.length);
+}
+
+// src/metrics/drawdown.ts
+var DAY_MS2 = 24 * 60 * 60 * 1e3;
+var NOISE = 1e-4;
+function dateUTC2(iso) {
+  return Date.UTC(Number(iso.slice(0, 4)), Number(iso.slice(5, 7)) - 1, Number(iso.slice(8, 10)));
+}
+function daysBetween2(a, b) {
+  return Math.round((dateUTC2(b) - dateUTC2(a)) / DAY_MS2);
+}
+function computeDrawdownTable(series, topN) {
+  if (series.length === 0) return [];
+  const segments = [];
+  let peakDate = series[0].date;
+  let peakValue = series[0].value;
+  let open = null;
+  for (let i = 0; i < series.length; i++) {
+    const bar = series[i];
+    if (bar.value >= peakValue) {
+      if (open) {
+        const recoveryDate = bar.date;
+        const depth = open.troughValue / open.peakValue - 1;
+        if (Math.abs(depth) >= NOISE) {
+          segments.push({
+            peakDate: open.peakDate,
+            troughDate: open.troughDate,
+            recoveryDate,
+            depth,
+            durationDays: daysBetween2(open.peakDate, recoveryDate),
+            underwaterDays: daysBetween2(open.peakDate, open.troughDate)
+          });
+        }
+        open = null;
+      }
+      peakDate = bar.date;
+      peakValue = bar.value;
+    } else {
+      if (!open) {
+        open = { peakDate, peakValue, troughDate: bar.date, troughValue: bar.value };
+      } else if (bar.value < open.troughValue) {
+        open.troughDate = bar.date;
+        open.troughValue = bar.value;
+      }
+    }
+  }
+  if (open) {
+    const lastDate = series[series.length - 1].date;
+    const depth = open.troughValue / open.peakValue - 1;
+    if (Math.abs(depth) >= NOISE) {
+      segments.push({
+        peakDate: open.peakDate,
+        troughDate: open.troughDate,
+        recoveryDate: null,
+        depth,
+        durationDays: daysBetween2(open.peakDate, lastDate),
+        underwaterDays: daysBetween2(open.peakDate, open.troughDate)
+      });
+    }
+  }
+  segments.sort((a, b) => Math.abs(b.depth) - Math.abs(a.depth));
+  return segments.slice(0, topN);
+}
+function currentDrawdown(series) {
+  if (series.length === 0) return 0;
+  let runningMax = -Infinity;
+  for (const bar of series) {
+    if (bar.value > runningMax) runningMax = bar.value;
+  }
+  const last = series[series.length - 1].value;
+  return last / runningMax - 1;
+}
+
+// src/metrics/riskAdjusted.ts
+var TRADING_DAYS2 = 252;
+function dailyRiskFree(annual) {
+  return Math.pow(1 + annual, 1 / TRADING_DAYS2) - 1;
+}
+function sharpe(returns, rfAnnual) {
+  const rfDaily = dailyRiskFree(rfAnnual);
+  const s = stdev(returns);
+  if (s === 0) return NaN;
+  return (mean(returns) - rfDaily) / s * Math.sqrt(TRADING_DAYS2);
+}
+function sortino(returns, rfAnnual) {
+  const rfDaily = dailyRiskFree(rfAnnual);
+  const dd = downsideDeviation(returns, rfDaily);
+  if (dd === 0) return NaN;
+  return (mean(returns) - rfDaily) * TRADING_DAYS2 / dd;
+}
+function calmar(cagrValue, maxDdDepth) {
+  if (maxDdDepth === 0) return Infinity;
+  return cagrValue / Math.abs(maxDdDepth);
+}
+
+// src/metrics/activity.ts
+function rebalanceCount(trades) {
+  const dates = /* @__PURE__ */ new Set();
+  for (const t of trades) dates.add(t.date);
+  return dates.size;
+}
+function tradeCount(trades) {
+  return trades.length;
+}
+function turnover(trades, series, years2) {
+  if (years2 <= 0 || series.length === 0) return 0;
+  let gross = 0;
+  for (const t of trades) {
+    if (t.symbol === "CASHX") continue;
+    gross += Math.abs(t.quantity * t.price);
+  }
+  let navSum = 0;
+  for (const bar of series) navSum += bar.value;
+  const avgNav = navSum / series.length;
+  if (avgNav === 0) return 0;
+  return gross / avgNav / years2;
+}
+function navAtOrBefore(series, date) {
+  let result = null;
+  for (const bar of series) {
+    if (bar.date <= date) result = bar.value;
+    else break;
+  }
+  return result;
+}
+function winRatePerRebalance(series, trades) {
+  if (series.length < 2) return 0;
+  const firstDate = series[0].date;
+  const lastDate = series[series.length - 1].date;
+  const distinctTradeDates = Array.from(new Set(trades.map((t) => t.date))).sort();
+  const inRange = distinctTradeDates.filter((d) => d > firstDate && d < lastDate);
+  if (inRange.length === 0) {
+    const total2 = series[series.length - 1].value / series[0].value - 1;
+    return total2 > 0 ? 1 : 0;
+  }
+  const boundaries = [firstDate, ...inRange, lastDate];
+  let wins = 0;
+  let total = 0;
+  for (let i = 0; i < boundaries.length - 1; i++) {
+    const a = navAtOrBefore(series, boundaries[i]);
+    const b = navAtOrBefore(series, boundaries[i + 1]);
+    if (a == null || b == null || a === 0) continue;
+    total++;
+    if (b / a - 1 > 0) wins++;
+  }
+  return total === 0 ? 0 : wins / total;
+}
+
+// src/metrics/tables.ts
+function buildMonthlyTable(monthly) {
+  if (monthly.length === 0) return { rows: [] };
+  const byYear = /* @__PURE__ */ new Map();
+  for (const m of monthly) {
+    let row = byYear.get(m.year);
+    if (!row) {
+      row = new Array(12).fill(null);
+      byYear.set(m.year, row);
+    }
+    row[m.month] = m.return;
+  }
+  const years2 = Array.from(byYear.keys()).sort((a, b) => a - b);
+  const rows = years2.map((year) => {
+    const months = byYear.get(year);
+    let ytd = null;
+    for (const v of months) {
+      if (v == null) continue;
+      ytd = (ytd == null ? 1 : 1 + ytd) * (1 + v) - 1;
+    }
+    return { year, months, ytd };
+  });
+  return { rows };
+}
+function buildYearlyList(monthly) {
+  const byYear = /* @__PURE__ */ new Map();
+  for (const m of monthly) {
+    if (m.partial) continue;
+    let arr = byYear.get(m.year);
+    if (!arr) {
+      arr = [];
+      byYear.set(m.year, arr);
+    }
+    arr.push(m.return);
+  }
+  const years2 = Array.from(byYear.keys()).sort((a, b) => a - b);
+  return years2.map((year) => {
+    const months = byYear.get(year);
+    let compounded = 1;
+    for (const v of months) compounded *= 1 + v;
+    return { year, return: compounded - 1 };
+  });
+}
+
+// src/metrics/compute.ts
+function computeMetrics(series, trades, options = {}) {
+  if (series.length < 2) {
+    throw new Error("metrics requires at least 2 daily bars");
+  }
+  const rfAnnual = options.riskFreeRate ?? 0;
+  const topN = options.topDrawdowns ?? 5;
+  const conf = options.varConfidence ?? 0.95;
+  const ret = dailyReturns(series);
+  const monthly = monthlyReturns(series);
+  const yearly = yearlyReturns(series);
+  const yrs = years(series);
+  const dds = computeDrawdownTable(series, Math.max(topN, 1));
+  const maxDd = dds[0] ?? {
+    peakDate: series[0].date,
+    troughDate: series[0].date,
+    recoveryDate: series[series.length - 1].date,
+    depth: 0,
+    durationDays: 0,
+    underwaterDays: 0
+  };
+  const cagrVal = cagr(series);
+  return {
+    range: { from: series[0].date, to: series[series.length - 1].date, years: yrs },
+    returns: {
+      totalReturn: totalReturn(series),
+      cagr: cagrVal,
+      bestYear: bestYear(yearly),
+      worstYear: worstYear(yearly),
+      bestMonth: bestMonth(monthly),
+      worstMonth: worstMonth(monthly),
+      pctPositiveMonths: pctPositiveMonths(monthly)
+    },
+    risk: {
+      volatility: volatility(ret),
+      downsideDeviation: downsideDeviation(ret, dailyRiskFree(rfAnnual)),
+      maxDrawdown: maxDd,
+      currentDrawdown: currentDrawdown(series),
+      ulcerIndex: ulcerIndex(series),
+      skew: skewness(ret),
+      kurtosis: excessKurtosis(ret),
+      var95: historicalVar(ret, conf),
+      cvar95: historicalCvar(ret, conf)
+    },
+    riskAdjusted: {
+      sharpe: sharpe(ret, rfAnnual),
+      sortino: sortino(ret, rfAnnual),
+      calmar: calmar(cagrVal, maxDd.depth)
+    },
+    activity: {
+      rebalances: rebalanceCount(trades),
+      trades: tradeCount(trades),
+      turnover: turnover(trades, series, yrs),
+      winRate: winRatePerRebalance(series, trades)
+    },
+    tables: {
+      drawdowns: dds.slice(0, topN),
+      monthly: buildMonthlyTable(monthly),
+      yearly: buildYearlyList(monthly)
+    }
+  };
+}
+
 // src/backtest/types.ts
 var SimulationHandle = class {
   series;
@@ -1612,6 +2112,9 @@ var SimulationHandle = class {
    *   the current UTC ISO date; callers with non-UTC semantics or after-hours
    *   rollover should supply their own.
    */
+  metrics(options = {}) {
+    return computeMetrics(this.series, this.trades, options);
+  }
   async pushAndPreview(quotes, options = {}) {
     const priceArgs = [];
     if (this._portfolio) {
@@ -2309,7 +2812,13 @@ export {
   StrategyHandle,
   TickerHandle,
   allocationsEqual,
+  computeDrawdownTable,
+  computeMetrics,
+  monthlyReturns as computeMonthlyReturns,
   computeRebalanceDates,
+  sharpe as computeSharpe,
+  sortino as computeSortino,
+  yearlyReturns as computeYearlyReturns,
   createClient
 };
 //# sourceMappingURL=index.js.map