tradelab 0.4.0 → 1.0.0

package/README.md

@@ -3,19 +3,19 @@
 
   <p><strong>A Node.js backtesting toolkit for serious trading strategy research.</strong></p>
 
-  [![npm version](https://img.shields.io/npm/v/tradelab?color=0f172a&label=npm&logo=npm)](https://www.npmjs.com/package/tradelab)
-  [![GitHub](https://img.shields.io/badge/github-ishsharm0/tradelab-0f172a?logo=github)](https://github.com/ishsharm0/tradelab)
-  [![License: MIT](https://img.shields.io/badge/license-MIT-0f172a)](https://github.com/ishsharm0/tradelab/blob/main/LICENSE)
-  [![Node.js](https://img.shields.io/badge/node-%3E%3D18-0f172a?logo=node.js)](https://nodejs.org)
-  [![TypeScript](https://img.shields.io/badge/TypeScript-ready-0f172a?logo=typescript)](https://github.com/ishsharm0/tradelab/blob/main/types/index.d.ts)
+[![npm version](https://img.shields.io/npm/v/tradelab?color=0f172a&label=npm&logo=npm)](https://www.npmjs.com/package/tradelab)
+[![GitHub](https://img.shields.io/badge/github-ishsharm0/tradelab-0f172a?logo=github)](https://github.com/ishsharm0/tradelab)
+[![License: MIT](https://img.shields.io/badge/license-MIT-0f172a)](https://github.com/ishsharm0/tradelab/blob/main/LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-0f172a?logo=node.js)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ready-0f172a?logo=typescript)](https://github.com/ishsharm0/tradelab/blob/main/types/index.d.ts)
 
 </div>
 
 ---
 
-**tradelab** handles the simulation, sizing, exits, costs, and result exports — you bring the candles and signal logic.
+**tradelab** handles strategy research and execution workflows in one package.
 
-It works cleanly for a single-strategy backtest and scales up to portfolio runs, walk-forward testing, and detailed execution modeling. It is not a broker connector or a live trading tool.
+Use it for backtests, portfolio and walk-forward validation, and live or paper execution through broker adapters while keeping the same `signal()` contract.
 
 ```bash
 npm install tradelab
@@ -31,6 +31,8 @@ npm install tradelab
 - [Core concepts](#core-concepts)
 - [Portfolio mode](#portfolio-mode)
 - [Walk-forward optimization](#walk-forward-optimization)
+- [Tick backtests](#tick-backtests)
+- [Live trading](#live-trading)
 - [Execution and cost modeling](#execution-and-cost-modeling)
 - [Exports and reporting](#exports-and-reporting)
 - [CLI](#cli)
@@ -41,15 +43,16 @@ npm install tradelab
 
 ## What it includes
 
-| Area | What you get |
-|---|---|
-| **Engine** | Candle-based backtests with position sizing, exits, risk controls, replay capture |
-| **Portfolio** | Multi-symbol aggregation with weight-based capital allocation |
-| **Walk-forward** | Rolling train/test validation with parameter search |
-| **Data** | Yahoo Finance downloads, CSV import, and local cache helpers |
-| **Costs** | Slippage, spread, and commission modeling |
-| **Exports** | HTML reports, metrics JSON, and trade CSV |
-| **Dev experience** | TypeScript definitions, ESM/CJS support, CLI for quick runs |
+| Area               | What you get                                                                             |
+| ------------------ | ---------------------------------------------------------------------------------------- |
+| **Engine**         | Candle and tick backtests with position sizing, exits, replay capture, and cost models   |
+| **Portfolio**      | Multi-system shared-capital simulation with live capital locking and daily loss halts    |
+| **Walk-forward**   | Rolling and anchored train/test validation with parameter search and stability summaries |
+| **Live execution** | Live and paper engines with broker adapters, state persistence, and orchestration        |
+| **Data**           | Yahoo Finance downloads, CSV import, and local cache helpers                             |
+| **Costs**          | Slippage, spread, and commission modeling                                                |
+| **Exports**        | HTML reports, metrics JSON, and trade CSV                                                |
+| **Dev experience** | TypeScript definitions, ESM/CJS support, CLI for quick runs                              |
 
 ---
 
@@ -107,7 +110,7 @@ const candles = await getHistoricalCandles({
   symbol: "SPY",
   interval: "1d",
   period: "2y",
-  cache: true,       // reuses local copy on repeated runs
+  cache: true, // reuses local copy on repeated runs
 });
 
 const result = backtest({ candles, symbol: "SPY", interval: "1d", range: "2y", signal });
@@ -160,16 +163,16 @@ The minimum viable signal is just `side`, `stop`, and `rr`. Start there and add
 
 ### Key backtest options
 
-| Option | Purpose |
-|---|---|
-| `equity` | Starting equity (default `10000`) |
-| `riskPct` | Percent of equity risked per trade |
-| `warmupBars` | Bars skipped before signal evaluation starts |
-| `flattenAtClose` | Forces end-of-day exit when enabled |
-| `costs` | Slippage, spread, and commission model |
-| `strict` | Throws on lookahead access |
-| `collectEqSeries` | Enables equity curve output |
-| `collectReplay` | Enables visualization payload |
+| Option            | Purpose                                      |
+| ----------------- | -------------------------------------------- |
+| `equity`          | Starting equity (default `10000`)            |
+| `riskPct`         | Percent of equity risked per trade           |
+| `warmupBars`      | Bars skipped before signal evaluation starts |
+| `flattenAtClose`  | Forces end-of-day exit when enabled          |
+| `costs`           | Slippage, spread, and commission model       |
+| `strict`          | Throws on lookahead access                   |
+| `collectEqSeries` | Enables equity curve output                  |
+| `collectReplay`   | Enables visualization payload                |
 
 ### Result shape
 
@@ -177,19 +180,19 @@ The minimum viable signal is just `side`, `stop`, and `rr`. Start there and add
 {
   symbol, interval, range,
   trades,     // every realized leg, including partial exits
-  positions,  // completed positions — start here for analysis
+  positions,  // completed positions - start here for analysis
   metrics,    // winRate, profitFactor, maxDrawdown, sharpe, ...
-  eqSeries,   // [{ time, timestamp, equity }] — equity curve
+  eqSeries,   // [{ time, timestamp, equity }] - equity curve
   replay,     // visualization frames and events
 }
 ```
 
 **First checks after any run:**
 
-- `metrics.trades` — enough sample size to trust the numbers?
-- `metrics.profitFactor` — do winners beat losers gross of costs?
-- `metrics.maxDrawdown` — is the equity path survivable?
-- `metrics.sideBreakdown` — does one side carry the whole result?
+- `metrics.trades` - enough sample size to trust the numbers?
+- `metrics.profitFactor` - do winners beat losers gross of costs?
+- `metrics.maxDrawdown` - is the equity path survivable?
+- `metrics.sideBreakdown` - does one side carry the whole result?
 
 ---
 
@@ -209,25 +212,26 @@ const result = backtestPortfolio({
 });
 ```
 
-Capital is allocated up front by weight. Each system runs through the normal single-symbol engine, and the portfolio result merges trades, positions, replay events, and the equity series.
+Weights now act as default per-system allocation caps rather than pre-funded sleeves. Capital is locked only when a fill happens, `eqSeries` includes `lockedCapital` and `availableCapital`, later systems size against remaining live capital, and `maxDailyLossPct` on `backtestPortfolio()` can halt the whole book for the rest of the day.
 
 ---
 
 ## Walk-forward optimization
 
-Use `walkForwardOptimize()` when one in-sample backtest is not enough. It runs rolling train/test windows across the full candle history.
+Use `walkForwardOptimize()` when one in-sample backtest is not enough. It supports rolling and anchored train/test windows across the full candle history.
 
 ```js
 import { walkForwardOptimize } from "tradelab";
 
 const wf = walkForwardOptimize({
   candles,
+  mode: "anchored",
   trainBars: 180,
   testBars: 60,
   stepBars: 60,
   scoreBy: "profitFactor",
   parameterSets: [
-    { fast: 8,  slow: 21, rr: 2 },
+    { fast: 8, slow: 21, rr: 2 },
     { fast: 10, slow: 30, rr: 2 },
   ],
   signalFactory(params) {
@@ -236,7 +240,59 @@ const wf = walkForwardOptimize({
 });
 ```
 
-Each window picks the best parameter set in training, then runs it blind on the test slice. The `windows` array in the result shows per-window winners. If the winning parameters swing wildly from window to window, that is a real signal — not a formatting detail.
+Each window picks the best parameter set in training, then runs it blind on the test slice. The `windows` array now includes out-of-sample trade count, profitability, and a per-window stability score. `bestParamsSummary` reports how stable the winners were across the full run.
+
+---
+
+## Tick backtests
+
+Use `backtestTicks()` when you want event-driven fills on tick or quote data without changing the result shape used by metrics, exports, or replay.
+
+```js
+import { backtestTicks } from "tradelab";
+
+const result = backtestTicks({
+  ticks,
+  queueFillProbability: 0.35,
+  signal,
+});
+```
+
+Market entries fill on the next tick, limit orders can fill at the touch with configurable queue probability, and stop exits use the existing cost model with stop-specific slippage if you provide it in `costs.slippageByKind.stop`.
+
+---
+
+## Live trading
+
+`tradelab/live` provides the live stack:
+
+- `LiveEngine` for single-system live/paper execution
+- `LiveOrchestrator` for multi-system execution with shared broker state
+- `PaperEngine` implementing the broker interface for deterministic simulation
+- broker adapters for Alpaca, Binance, Coinbase, and Interactive Brokers
+- JSON state/trade/equity persistence via `JsonFileStorage`
+
+Use the same signal contract from backtesting in live mode:
+
+```js
+import { LiveEngine, PaperEngine, JsonFileStorage } from "tradelab/live";
+
+const engine = new LiveEngine({
+  id: "aapl-1m",
+  symbol: "AAPL",
+  interval: "1m",
+  broker: new PaperEngine({ equity: 25_000 }),
+  storage: new JsonFileStorage({ baseDir: "./output/live-state" }),
+  signal({ bar, openPosition }) {
+    if (openPosition) return null;
+    return { side: "long", stop: bar.close - 1, rr: 2 };
+  },
+});
+
+await engine.start();
+```
+
+See [docs/live-trading.md](docs/live-trading.md) for API and CLI workflows.
 
 ---
 
@@ -282,12 +338,12 @@ exportBacktestArtifacts({ result, outDir: "./output" });
 
 Or use the narrower helpers:
 
-| Helper | Output |
-|---|---|
-| `exportHtmlReport(options)` | Interactive HTML report written to disk |
-| `renderHtmlReport(options)` | HTML report returned as a string |
-| `exportTradesCsv(trades, options)` | Flat trade ledger for spreadsheets or pandas |
-| `exportMetricsJSON(options)` | Machine-readable metrics for dashboards or automation |
+| Helper                             | Output                                                |
+| ---------------------------------- | ----------------------------------------------------- |
+| `exportHtmlReport(options)`        | Interactive HTML report written to disk               |
+| `renderHtmlReport(options)`        | HTML report returned as a string                      |
+| `exportTradesCsv(trades, options)` | Flat trade ledger for spreadsheets or pandas          |
+| `exportMetricsJSON(options)`       | Machine-readable metrics for dashboards or automation |
 
 For programmatic pipelines, `exportMetricsJSON` is usually the most useful format to build on.
 
@@ -313,7 +369,16 @@ npx tradelab portfolio \
 # Walk-forward validation
 npx tradelab walk-forward \
   --source yahoo --symbol QQQ --interval 1d --period 2y \
-  --trainBars 180 --testBars 60
+  --trainBars 180 --testBars 60 --mode anchored
+
+# Live paper engine (single system)
+npx tradelab paper --symbol AAPL --interval 1m --mode polling --once true
+
+# Live orchestrator from config
+npx tradelab live --config ./live-portfolio.json --paper --mode polling --once true
+
+# Inspect persisted live state
+npx tradelab status --dir ./output/live-state
 
 # Prefetch and cache data
 npx tradelab prefetch --symbol SPY --interval 1d --period 1y
@@ -322,7 +387,7 @@ npx tradelab import-csv --csvPath ./data/spy.csv --symbol SPY --interval 1d
 
 **Built-in strategies:** `ema-cross` · `buy-hold`
 
-You can also point `--strategy` at a local module that exports `default(args)`, `createSignal(args)`, or `signal`.
+You can also point `--strategy` at a local module that exports `default(args)`, `createSignal(args)`, or `signal` for `backtest`, or `signalFactory(params, args)` plus `parameterSets`/`createParameterSets(args)` for `walk-forward`.
 
 ---
 
@@ -344,6 +409,7 @@ The examples are a good place to start if you want something runnable before wir
 ```js
 import { backtest, getHistoricalCandles, ema } from "tradelab";
 import { fetchHistorical } from "tradelab/data";
+import { LiveEngine, PaperEngine } from "tradelab/live";
 ```
 
 ### CommonJS
@@ -351,24 +417,27 @@ import { fetchHistorical } from "tradelab/data";
 ```js
 const { backtest, getHistoricalCandles, ema } = require("tradelab");
 const { fetchHistorical } = require("tradelab/data");
+const { LiveEngine, PaperEngine } = require("tradelab/live");
 ```
 
 ---
 
 ## Documentation
 
-| Guide | What it covers |
-|---|---|
-| [Backtest engine](docs/backtest-engine.md) | Signal contract, all options, result shape, portfolio mode, walk-forward |
-| [Data, reporting, and CLI](docs/data-reporting-cli.md) | Data loading, cache behavior, exports, CLI reference |
-| [API reference](docs/api-reference.md) | Compact index of every public export |
+| Guide                                                  | What it covers                                                                 |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| [Backtest engine](docs/backtest-engine.md)             | Signal contract, all options, result shape, portfolio mode, walk-forward       |
+| [Data, reporting, and CLI](docs/data-reporting-cli.md) | Data loading, cache behavior, exports, CLI reference                           |
+| [Live trading](docs/live-trading.md)                   | Live engine, broker adapters, paper mode, orchestration, and state persistence |
+| [Strategy examples](docs/examples.md)                  | Mean reversion, breakout, sentiment, LLM, and portfolio strategy patterns      |
+| [API reference](docs/api-reference.md)                 | Compact index of every public export                                           |
 
 ---
 
 ## Common mistakes
 
 - Using unsorted candles or mixed intervals in a single series
-- Reading `trades` as if they were always full positions — use `positions` for top-line analysis
+- Reading `trades` as if they were always full positions - use `positions` for top-line analysis
 - Leaving costs at zero and overestimating edge
 - Trusting one backtest without out-of-sample validation
 - Debugging a strategy with `strict: false` when lookahead is possible
@@ -380,4 +449,4 @@ const { fetchHistorical } = require("tradelab/data");
 - Node `18+` is required
 - Yahoo downloads are cached under `output/data` by default
 - CommonJS and ESM are both supported
-- The engine is built for historical research — not brokerage execution, tick-level simulation, or exchange microstructure modeling
+- Live adapters support broker execution workflows, but this is still not an exchange microstructure simulator