tradelab 1.0.1 → 1.2.0

package/types/index.d.ts

@@ -82,6 +82,7 @@ export interface TradeExit {
   time: number;
   reason: string;
   pnl: number;
+  financing?: number;
   exitATR?: number;
 }
 
@@ -131,6 +132,14 @@ export interface SideBreakdownEntry {
   avgR: number;
 }
 
+export interface BenchmarkStats {
+  alpha: number | null;
+  beta: number | null;
+  correlation: number | null;
+  informationRatio: number | null;
+  trackingError: number | null;
+}
+
 /** Aggregate performance metrics returned by `backtest()`. */
 export interface BacktestMetrics {
   /** Count of completed positions included in the aggregate metrics. */
@@ -145,6 +154,12 @@ export interface BacktestMetrics {
   avgR: number;
   /** Daily Sharpe ratio alias for quick access. */
   sharpe: number;
+  /** Annualized Sharpe ratio derived from the configured interval or bar spacing. */
+  sharpeAnnualized: number;
+  /** Annualized Sortino ratio derived from the configured interval or bar spacing. */
+  sortinoAnnualized: number;
+  /** Number of periods per year used for annualized metrics. */
+  annualizationPeriods: number;
   sharpePerTrade: number;
   sortinoPerTrade: number;
   /** Maximum drawdown percent alias. */
@@ -168,6 +183,7 @@ export interface BacktestMetrics {
   /** Daily Sharpe ratio computed from realized equity changes. */
   sharpeDaily: number;
   sortinoDaily: number;
+  benchmark: BenchmarkStats;
   /** Long/short breakdown grouped by completed position side. */
   sideBreakdown: {
     long: SideBreakdownEntry;
@@ -238,6 +254,9 @@ export interface SignalResult {
 }
 
 export type SignalFunction = (context: SignalContext) => SignalResult | null;
+export type AsyncSignalFunction = (
+  context: SignalContext
+) => SignalResult | null | Promise<SignalResult | null>;
 
 export interface PendingOrder {
   side: Side;
@@ -268,6 +287,15 @@ export interface ExecutionCostOptions {
   commissionPerUnit?: number;
   commissionPerOrder?: number;
   minCommission?: number;
+  carry?: {
+    longAnnualBps?: number;
+    shortAnnualBps?: number;
+  };
+  funding?: {
+    rateBps?: number;
+    intervalMs?: number;
+    anchorMs?: number;
+  };
 }
 
 export interface MfeTrailOptions {
@@ -337,6 +365,11 @@ export interface BacktestOptions {
   strict?: boolean;
 }
 
+export interface BacktestAsyncOptions extends Omit<BacktestOptions, "signal"> {
+  signal: AsyncSignalFunction;
+  signalBudgetMs?: number;
+}
+
 export interface BacktestTickOptions {
   ticks: Tick[];
   symbol?: string;
@@ -357,6 +390,7 @@ export interface BacktestTickOptions {
   collectEqSeries?: boolean;
   collectReplay?: boolean;
   queueFillProbability?: number;
+  seed?: string;
   oco?: OCOOptions;
 }
 
@@ -542,6 +576,81 @@ export interface ArtifactPaths {
   metrics: string | null;
 }
 
+export interface LlmSignalOptions {
+  resolve: AsyncSignalFunction;
+  budgetMs?: number;
+  onError?: "skip" | "throw";
+}
+
+export interface LlmDecisionLogEntry {
+  index: number;
+  time?: number;
+  close?: number;
+  latencyMs: number;
+  result?: SignalResult | null;
+  error?: string;
+}
+
+export interface StrategyParamSpec {
+  type: string;
+  default?: unknown;
+  description?: string;
+  [key: string]: unknown;
+}
+
+export interface StrategyDefinition {
+  description: string;
+  params: Record<string, StrategyParamSpec>;
+  factory: (params?: Record<string, unknown>) => SignalFunction;
+}
+
+export interface StrategySummary {
+  name: string;
+  description: string;
+  params: Record<string, StrategyParamSpec>;
+}
+
+export interface ResearchPercentileBands {
+  p5: number;
+  p25?: number;
+  p50: number;
+  p75?: number;
+  p95: number;
+}
+
+export interface MonteCarloResult {
+  iterations: number;
+  blockSize: number;
+  finalEquity: Required<ResearchPercentileBands>;
+  maxDrawdown: Required<ResearchPercentileBands>;
+  pathBands: Array<Pick<ResearchPercentileBands, "p5" | "p50" | "p95">>;
+  probProfit: number;
+}
+
+export interface PboResult {
+  pbo: number;
+  combos: number;
+  medianLogit: number;
+}
+
+export interface CpcvSplit {
+  train: number[];
+  test: number[];
+  testGroups: number[];
+}
+
+export interface OptimizeResultEntry {
+  params: Record<string, unknown>;
+  metrics?: Partial<BacktestMetrics>;
+  error?: string;
+}
+
+export interface OptimizeResult {
+  results: OptimizeResultEntry[];
+  leaderboard: OptimizeResultEntry[];
+  best: OptimizeResultEntry | null;
+}
+
 /**
  * Run a candle-based backtest.
  *
@@ -550,10 +659,22 @@ export interface ArtifactPaths {
  * chart-friendly replay frames/events in `replay`.
  */
 export function backtest(options: BacktestOptions): BacktestResult;
+export function backtestAsync(options: BacktestAsyncOptions): Promise<BacktestResult>;
 export function backtestTicks(options: BacktestTickOptions): BacktestResult;
+export function grid(spec?: Record<string, unknown | unknown[]>): Array<Record<string, unknown>>;
+export function optimize(options: {
+  candles: Candle[];
+  signalModulePath: string;
+  parameterSets: Array<Record<string, unknown>>;
+  interval?: string;
+  backtestOptions?: Partial<BacktestOptions>;
+  concurrency?: number;
+  scoreBy?: keyof BacktestMetrics | string;
+}): Promise<OptimizeResult>;
 export function backtestPortfolio(options: {
   systems: PortfolioSystem[];
   equity?: number;
+  interval?: string;
   allocation?: "equal" | "weight";
   collectEqSeries?: boolean;
   collectReplay?: boolean;
@@ -579,7 +700,65 @@ export function buildMetrics(input: {
   candles: Candle[];
   estBarMs: number;
   eqSeries?: EquityPoint[];
+  interval?: string;
+  benchmarkReturns?: number[];
 }): BacktestMetrics;
+export function benchmarkStats(
+  strategyReturns: number[],
+  benchmarkReturns: number[]
+): BenchmarkStats;
+export function clampFinite(value: unknown, fallback?: number): number;
+export const BIG_NUMBER: number;
+export function periodsPerYear(interval?: string, estBarMs?: number): number;
+
+export class LlmSignal {
+  constructor(options: LlmSignalOptions);
+  resolve: AsyncSignalFunction;
+  budgetMs: number;
+  onError: "skip" | "throw";
+  log: LlmDecisionLogEntry[];
+  signal(context: SignalContext): Promise<SignalResult | null>;
+}
+
+export function registerStrategy(name: string, def: StrategyDefinition): void;
+export function listStrategies(): StrategySummary[];
+export function getStrategy(name: string): StrategyDefinition["factory"];
+
+export namespace research {
+  function monteCarlo(options: {
+    tradePnls: number[];
+    equityStart?: number;
+    iterations?: number;
+    blockSize?: number;
+    seed?: string | number;
+  }): MonteCarloResult;
+  function deflatedSharpe(options: {
+    sharpe: number;
+    sampleSize: number;
+    numTrials?: number;
+    sharpeStd?: number;
+    skew?: number;
+    kurtosis?: number;
+  }): number;
+  function sweepHaircut(options: { numTrials: number; sharpeStd: number }): {
+    expectedMaxSharpe: number;
+    numTrials: number;
+  };
+  function probabilityOfBacktestOverfitting(
+    performanceMatrix: number[][],
+    options?: { groups?: number }
+  ): PboResult;
+  function combinatorialPurgedSplits(options: {
+    nObservations: number;
+    nGroups?: number;
+    nTestGroups?: number;
+    embargo?: number;
+  }): CpcvSplit[];
+  function combinations(n: number, k: number): number[][];
+  function normalCdf(x: number): number;
+  function normalPpf(p: number): number;
+  function moments(values: number[]): { mean: number; std: number; skew: number; kurtosis: number };
+}
 
 export function getHistoricalCandles(options?: HistoricalDataOptions): Promise<Candle[]>;
 export function backtestHistorical(options: BacktestHistoricalOptions): Promise<BacktestResult>;

package/types/live.d.ts

@@ -84,6 +84,8 @@ export interface StoredState {
   savedAt: number;
 }
 
+export const LIVE_EVENTS: string[];
+
 export class EventBus extends import("node:events").EventEmitter {
   emitEvent(event: string, payload?: Record<string, unknown>): true;
   onAny(handler: (input: { event: string; payload: Record<string, unknown> }) => void): () => void;
@@ -330,6 +332,21 @@ export class LiveOrchestrator {
   getStatus(): Record<string, unknown>;
 }
 
+export interface DashboardServer {
+  start(): Promise<string>;
+  close(): Promise<void>;
+  server: import("node:http").Server;
+}
+
+export function createDashboardServer(options: {
+  source: {
+    eventBus: EventBus;
+    getStatus?: () => Record<string, unknown>;
+  };
+  port?: number;
+  maxBuffer?: number;
+}): DashboardServer;
+
 export function createEventBus(): EventBus;
 export function createLogger(options?: {
   level?: "debug" | "info" | "warn" | "error" | "silent";
@@ -380,3 +397,100 @@ export function createLiveOrchestrator(options: {
 }): LiveOrchestrator;
 
 export type { SignalResult };
+
+// ── TradingSession / SessionManager ──────────────────────────────────────────
+
+export interface TradingSessionOptions {
+  id?: string;
+  symbol: string;
+  interval?: string;
+  broker: BrokerAdapter;
+  mode?: "paper" | "live";
+  equity?: number;
+  riskPct?: number;
+  maxDailyLossPct?: number;
+  maxPositionPct?: number;
+  qtyStep?: number;
+  minQty?: number;
+  maxLeverage?: number;
+  eventBus?: EventBus;
+}
+
+export interface SessionPlaceOrderOptions {
+  side: "long" | "short" | "buy" | "sell";
+  type?: "market" | "limit" | "stop" | "stop_limit";
+  qty?: number;
+  riskPct?: number;
+  stop?: number;
+  target?: number;
+  rr?: number;
+  limitPrice?: number;
+}
+
+export interface SessionStatus {
+  id: string;
+  symbol: string;
+  interval: string;
+  mode: "paper" | "live";
+  running: boolean;
+  equity: number;
+  dayPnl: number;
+  lastPrice: number | null;
+  positions: BrokerPosition[];
+  openOrders: OrderReceipt[];
+  risk: {
+    halted: boolean;
+    haltReason: string | null;
+    dayPnl: number;
+    dayTrades: number;
+    [key: string]: unknown;
+  };
+}
+
+export class TradingSession {
+  constructor(options: TradingSessionOptions);
+  readonly id: string;
+  readonly symbol: string;
+  readonly interval: string;
+  readonly mode: "paper" | "live";
+  readonly eventBus: EventBus;
+  equity: number;
+  lastPrice: number | null;
+  running: boolean;
+  candleBuffer: import("./index.d.ts").Candle[];
+  static liveAllowed(): boolean;
+  start(): Promise<void>;
+  stop(options?: { flatten?: boolean }): Promise<void>;
+  pushBar(bar: import("./index.d.ts").Candle): Promise<void>;
+  placeOrder(options: SessionPlaceOrderOptions): Promise<OrderReceipt>;
+  closePosition(symbol?: string): Promise<OrderReceipt | null>;
+  flatten(): Promise<void>;
+  cancelOrder(orderId: string): Promise<void>;
+  getAccount(): Promise<AccountInfo>;
+  getPositions(): Promise<BrokerPosition[]>;
+  recentEvents(limit?: number): Array<{ event: string; payload: unknown; t: number }>;
+  getStatus(): SessionStatus;
+  refresh(): Promise<SessionStatus>;
+}
+
+export interface SessionManagerOptions {
+  brokerFactory?: (options: Record<string, unknown>) => BrokerAdapter;
+}
+
+export interface CreateSessionOptions extends Partial<TradingSessionOptions> {
+  id: string;
+  symbol: string;
+  confirmLive?: boolean;
+  broker?: BrokerAdapter;
+}
+
+export class SessionManager {
+  constructor(options?: SessionManagerOptions);
+  create(options: CreateSessionOptions): Promise<TradingSession>;
+  get(id: string): TradingSession | null;
+  list(): TradingSession[];
+  remove(id: string, options?: { flatten?: boolean }): Promise<void>;
+  haltAll(): Promise<void>;
+}
+
+export function createSessionManager(options?: SessionManagerOptions): SessionManager;

package/types/mcp.d.ts

@@ -0,0 +1,17 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SessionManager } from "./live.d.ts";
+
+export function createServer(): McpServer;
+export function startStdioServer(): Promise<McpServer>;
+
+export interface McpToolHandler {
+  description: string;
+  handler(args: Record<string, unknown>): Promise<unknown>;
+}
+
+export const mcpTools: Record<string, McpToolHandler>;
+export const researchTools: Record<string, McpToolHandler>;
+export const liveTools: Record<string, McpToolHandler>;
+
+/** The shared SessionManager instance used by the MCP server process. */
+export const sessionManager: SessionManager;

package/types/ta.d.ts

@@ -0,0 +1,45 @@
+// types/ta.d.ts
+export type Candle = {
+  time: number;
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  volume?: number;
+};
+
+export function ema(values: number[], period?: number): number[];
+export function atr(bars: Candle[], period?: number): (number | undefined)[];
+export function rsi(closes: number[], period?: number): (number | undefined)[];
+export function macd(
+  closes: number[],
+  fast?: number,
+  slow?: number,
+  signalPeriod?: number
+): { macd: number[]; signal: number[]; histogram: number[] };
+export function stochastic(
+  bars: Candle[],
+  kPeriod?: number,
+  dPeriod?: number
+): { k: (number | undefined)[]; d: (number | undefined)[] };
+export function bollinger(
+  closes: number[],
+  period?: number,
+  mult?: number
+): { middle: (number | undefined)[]; upper: (number | undefined)[]; lower: (number | undefined)[] };
+export function donchian(
+  bars: Candle[],
+  period?: number
+): { upper: (number | undefined)[]; lower: (number | undefined)[]; middle: (number | undefined)[] };
+export function keltner(
+  bars: Candle[],
+  emaPeriod?: number,
+  atrPeriod?: number,
+  mult?: number
+): { upper: (number | undefined)[]; lower: (number | undefined)[]; middle: (number | undefined)[] };
+export function supertrend(
+  bars: Candle[],
+  period?: number,
+  mult?: number
+): { line: (number | undefined)[]; direction: (number | undefined)[] };
+export function vwap(bars: Candle[]): (number | undefined)[];