tradelab 0.4.0 → 1.0.0

package/docs/README.md

@@ -4,32 +4,37 @@
 
 - [Backtest engine](backtest-engine.md)
 - [Data, reporting, and CLI](data-reporting-cli.md)
+- [Live trading](live-trading.md)
+- [Strategy examples](examples.md)
 - [API reference](api-reference.md)
 
 ## Choose a path
 
-| Goal | Start here |
-| --- | --- |
-| Run one strategy on one dataset | [Backtest engine](backtest-engine.md) |
-| Load Yahoo or CSV data | [Data, reporting, and CLI](data-reporting-cli.md) |
+| Goal                                       | Start here                                        |
+| ------------------------------------------ | ------------------------------------------------- |
+| Run one strategy on one dataset            | [Backtest engine](backtest-engine.md)             |
+| Load Yahoo or CSV data                     | [Data, reporting, and CLI](data-reporting-cli.md) |
 | Export reports or machine-readable results | [Data, reporting, and CLI](data-reporting-cli.md) |
-| Run multiple symbols together | [Backtest engine](backtest-engine.md) |
-| Run walk-forward validation | [Backtest engine](backtest-engine.md) |
-| Check the exact public exports | [API reference](api-reference.md) |
+| Run multiple symbols together              | [Backtest engine](backtest-engine.md)             |
+| Run walk-forward validation                | [Backtest engine](backtest-engine.md)             |
+| Run one strategy live or in paper mode     | [Live trading](live-trading.md)                   |
+| Run multiple live systems together         | [Live trading](live-trading.md)                   |
+| See complete strategy patterns             | [Strategy examples](examples.md)                  |
+| Check the exact public exports             | [API reference](api-reference.md)                 |
 
 ## Package scope
 
 tradelab is built for:
 
 - candle-based strategy research
+- optional tick or quote replay with event-driven fills
 - historical backtests with configurable fills and costs
+- live and paper execution using broker adapters
 - CSV and Yahoo-based data workflows
 - exportable outputs for review or automation
 
 tradelab is not built for:
 
-- live broker execution
-- tick-level simulation
 - exchange microstructure modeling
 
 ## Common workflows
@@ -54,8 +59,20 @@ tradelab is not built for:
 3. Run `walkForwardOptimize()`
 4. Review per-window winners before trusting the aggregate result
 
+### Live execution workflow
+
+1. Build a `signal()` used in backtest first
+2. Wire it into `LiveEngine` with a broker or `PaperEngine`
+3. Persist state with `JsonFileStorage`
+4. Start with `tradelab paper` or `tradelab live --paper`
+5. Inspect persisted state with `tradelab status`
+
 ## Documentation map
 
 - [Backtest engine](backtest-engine.md): strategy inputs, engine options, result shape, portfolio mode, walk-forward mode
 - [Data, reporting, and CLI](data-reporting-cli.md): data loading, cache behavior, exports, terminal usage
+- [Live trading](live-trading.md): live engine, broker adapters, paper mode, orchestration, lifecycle, and state
+- [Strategy examples](examples.md): mean reversion, breakout, sentiment, LLM, and portfolio research patterns
 - [API reference](api-reference.md): compact export index
+
+<small>[Back to README.md](../README.md)</small>

package/docs/api-reference.md

@@ -1,44 +1,102 @@
 # API reference
 
+<small>[Back to main page](README.md)</small>
+
 This page is the compact index of public exports.
 
 If you are learning the package, start with [backtest-engine.md](backtest-engine.md) or [data-reporting-cli.md](data-reporting-cli.md). This page is for quick lookup.
 
 ## Backtesting
 
-| Export | Summary |
-| --- | --- |
-| `backtest(options)` | Run one strategy on one candle series |
-| `backtestPortfolio(options)` | Run multiple systems and merge the result |
-| `walkForwardOptimize(options)` | Run rolling train/test validation |
-| `buildMetrics(input)` | Compute metrics from realized trades and equity data |
+| Export                         | Summary                                                        |
+| ------------------------------ | -------------------------------------------------------------- |
+| `backtest(options)`            | Run one strategy on one candle series                          |
+| `backtestTicks(options)`       | Run one strategy on tick or quote data                         |
+| `backtestPortfolio(options)`   | Run multiple systems through a shared-capital portfolio engine |
+| `walkForwardOptimize(options)` | Run rolling or anchored train/test validation                  |
+| `buildMetrics(input)`          | Compute metrics from realized trades and equity data           |
 
 ## Data
 
-| Export | Summary |
-| --- | --- |
-| `getHistoricalCandles(options)` | Load candles from Yahoo or CSV |
-| `backtestHistorical({ data, backtestOptions })` | Load candles and immediately run `backtest()` |
-| `fetchHistorical(symbol, interval, period, options)` | Call the Yahoo layer directly |
-| `fetchLatestCandle(symbol, interval, options)` | Fetch the latest Yahoo candle |
-| `loadCandlesFromCSV(filePath, options)` | Parse and normalize a CSV file |
-| `normalizeCandles(candles)` | Normalize candle field names and sort/dedupe |
-| `mergeCandles(...arrays)` | Merge multiple candle arrays |
-| `candleStats(candles)` | Return summary stats for a candle array |
-| `saveCandlesToCache(candles, meta)` | Write normalized candles to the local cache |
-| `loadCandlesFromCache(symbol, interval, period, outDir)` | Read normalized candles from the local cache |
-| `cachedCandlesPath(symbol, interval, period, outDir)` | Return the expected cache path |
+| Export                                                   | Summary                                       |
+| -------------------------------------------------------- | --------------------------------------------- |
+| `getHistoricalCandles(options)`                          | Load candles from Yahoo or CSV                |
+| `backtestHistorical({ data, backtestOptions })`          | Load candles and immediately run `backtest()` |
+| `fetchHistorical(symbol, interval, period, options)`     | Call the Yahoo layer directly                 |
+| `fetchLatestCandle(symbol, interval, options)`           | Fetch the latest Yahoo candle                 |
+| `loadCandlesFromCSV(filePath, options)`                  | Parse and normalize a CSV file                |
+| `normalizeCandles(candles)`                              | Normalize candle field names and sort/dedupe  |
+| `mergeCandles(...arrays)`                                | Merge multiple candle arrays                  |
+| `candleStats(candles)`                                   | Return summary stats for a candle array       |
+| `saveCandlesToCache(candles, meta)`                      | Write normalized candles to the local cache   |
+| `loadCandlesFromCache(symbol, interval, period, outDir)` | Read normalized candles from the local cache  |
+| `cachedCandlesPath(symbol, interval, period, outDir)`    | Return the expected cache path                |
 
 ## Reporting
 
-| Export | Summary |
-| --- | --- |
-| `renderHtmlReport(options)` | Return the HTML report as a string |
-| `exportHtmlReport(options)` | Write the HTML report to disk |
-| `exportTradesCsv(trades, options)` | Write a CSV ledger of trades or positions |
-| `exportMetricsJSON(options)` | Write machine-readable metrics JSON |
+| Export                             | Summary                                    |
+| ---------------------------------- | ------------------------------------------ |
+| `renderHtmlReport(options)`        | Return the HTML report as a string         |
+| `exportHtmlReport(options)`        | Write the HTML report to disk              |
+| `exportTradesCsv(trades, options)` | Write a CSV ledger of trades or positions  |
+| `exportMetricsJSON(options)`       | Write machine-readable metrics JSON        |
 | `exportBacktestArtifacts(options)` | Write HTML, CSV, and metrics JSON together |
 
+## Live module (`tradelab/live`)
+
+Live exports are under a separate entrypoint:
+
+```js
+import { LiveEngine, PaperEngine } from "tradelab/live";
+```
+
+### Engine and orchestration
+
+- `LiveEngine`
+- `LiveOrchestrator`
+- `PaperEngine`
+- `CandleAggregator`
+- `RiskManager`
+- `StateManager`
+
+### Broker and feed adapters
+
+- `BrokerAdapter`
+- `AlpacaBroker`
+- `BinanceBroker`
+- `CoinbaseBroker`
+- `InteractiveBrokersBroker`
+- `FeedProvider`
+- `BrokerFeed`
+- `PollingFeed`
+
+### Storage and runtime utilities
+
+- `StorageProvider`
+- `JsonFileStorage`
+- `EventBus`
+- `LiveLogger`
+- `BrokerClock`
+
+### Factories
+
+- `createLiveEngine(options)`
+- `createLiveOrchestrator(options)`
+- `createPaperEngine(options)`
+- `createAlpacaBroker(options)`
+- `createBinanceBroker(options)`
+- `createCoinbaseBroker(options)`
+- `createInteractiveBrokersBroker(options)`
+- `createBrokerFeed(options)`
+- `createPollingFeed(options)`
+- `createJsonFileStorage(options)`
+- `createCandleAggregator(options)`
+- `createRiskManager(options)`
+- `createStateManager(options)`
+- `createEventBus()`
+- `createLogger(options)`
+- `createClock(options)`
+
 ## Indicators and utilities
 
 ### Indicators
@@ -67,4 +125,9 @@ If you are learning the package, start with [backtest-engine.md](backtest-engine
 
 ## Types
 
-The package ships declarations in [../types/index.d.ts](../types/index.d.ts). Use that file when you need the exact option and result contracts in TypeScript or editor IntelliSense.
+The package ships declarations in:
+
+- [../types/index.d.ts](../types/index.d.ts) for the main module
+- [../types/live.d.ts](../types/live.d.ts) for `tradelab/live`
+
+<small>[Back to main page](README.md)</small>

package/docs/backtest-engine.md

@@ -1,8 +1,11 @@
 # Backtest engine
 
+<small>[Back to main page](README.md)</small>
+
 This page covers the simulation layer:
 
 - `backtest(options)`
+- `backtestTicks(options)`
 - `backtestPortfolio(options)`
 - `walkForwardOptimize(options)`
 - `buildMetrics(input)`
@@ -11,14 +14,17 @@ This page covers the simulation layer:
 
 Use the engine layer when you already have candles and want to simulate strategy behavior, inspect the result, and export or post-process it.
 
+The same `signal()` contract is used by `LiveEngine` in `tradelab/live`, so strategy logic can move from research to execution without rewriting signal inputs.
+
 ## Choose the right function
 
-| Use case | Function |
-| --- | --- |
-| One strategy on one candle series | `backtest()` |
-| Multiple symbols with one combined result | `backtestPortfolio()` |
-| Rolling train/test validation | `walkForwardOptimize()` |
-| Recompute metrics from realized trades | `buildMetrics()` |
+| Use case                                  | Function                |
+| ----------------------------------------- | ----------------------- |
+| One strategy on one candle series         | `backtest()`            |
+| One strategy on tick or quote data        | `backtestTicks()`       |
+| Multiple symbols with one combined result | `backtestPortfolio()`   |
+| Rolling or anchored train/test validation | `walkForwardOptimize()` |
+| Recompute metrics from realized trades    | `buildMetrics()`        |
 
 ## Candle input
 
@@ -71,16 +77,16 @@ const result = backtest({
 
 ### Core options
 
-| Option | Purpose |
-| --- | --- |
-| `symbol`, `interval`, `range` | Labels carried into results and exports |
-| `equity` | Starting equity, default `10000` |
-| `riskPct` or `riskFraction` | Default risk per trade when `qty` is not provided |
-| `warmupBars` | Bars skipped before signal evaluation starts |
-| `flattenAtClose` | Forces end-of-day exit when enabled |
-| `collectEqSeries`, `collectReplay` | Builds extra output for charts and exports |
-| `strict` | Throws on direct lookahead access such as `candles[index + 1]` |
-| `costs` | Slippage, spread, and commission model |
+| Option                             | Purpose                                                        |
+| ---------------------------------- | -------------------------------------------------------------- |
+| `symbol`, `interval`, `range`      | Labels carried into results and exports                        |
+| `equity`                           | Starting equity, default `10000`                               |
+| `riskPct` or `riskFraction`        | Default risk per trade when `qty` is not provided              |
+| `warmupBars`                       | Bars skipped before signal evaluation starts                   |
+| `flattenAtClose`                   | Forces end-of-day exit when enabled                            |
+| `collectEqSeries`, `collectReplay` | Builds extra output for charts and exports                     |
+| `strict`                           | Throws on direct lookahead access such as `candles[index + 1]` |
+| `costs`                            | Slippage, spread, and commission model                         |
 
 If you are starting from scratch, the most useful options to set explicitly are:
 
@@ -92,38 +98,31 @@ If you are starting from scratch, the most useful options to set explicitly are:
 
 ### Signal contract
 
-The signal function receives:
+The signal function receives a context object with these fields:
 
+<!-- prettier-ignore -->
 ```js
-{
-  candles,
-  index,
-  bar,
-  equity,
-  openPosition,
-  pendingOrder
-}
+{ candles, index, bar, equity, openPosition, pendingOrder }
 ```
 
 Return `null` for no trade, or a signal object:
 
 ```js
-{
-  side: "long" | "short",
-  entry: 101.25,
-  stop: 99.75,
-  takeProfit: 104.25
-}
+// minimal
+{ side: "long", stop: 99.75, rr: 2 }
+
+// explicit targets
+{ side: "long", entry: 101.25, stop: 99.75, takeProfit: 104.25 }
 ```
 
 ### Signal conveniences
 
-| Field | Behavior |
-| --- | --- |
-| `side` | Accepts `long`, `short`, `buy`, or `sell` |
-| `entry` | Defaults to the current close if omitted |
-| `takeProfit` | Can be derived from `rr` or `_rr` |
-| `qty` or `size` | Overrides risk-based sizing |
+| Field                       | Behavior                                         |
+| --------------------------- | ------------------------------------------------ |
+| `side`                      | Accepts `long`, `short`, `buy`, or `sell`        |
+| `entry`                     | Defaults to the current close if omitted         |
+| `takeProfit`                | Can be derived from `rr` or `_rr`                |
+| `qty` or `size`             | Overrides risk-based sizing                      |
 | `riskPct` or `riskFraction` | Overrides the global risk setting for that trade |
 
 Practical rule: return the smallest signal object that expresses the trade clearly. In many strategies that is just `side`, `stop`, and `rr`.
@@ -202,19 +201,11 @@ Recommended order of adoption:
 
 ## Result shape
 
-`backtest()` returns:
+`backtest()` returns an object with these fields:
 
+<!-- prettier-ignore -->
 ```js
-{
-  symbol,
-  interval,
-  range,
-  trades,
-  positions,
-  metrics,
-  eqSeries,
-  replay
-}
+{ symbol, interval, range, trades, positions, openPositions, metrics, eqSeries, replay }
 ```
 
 ### `trades`
@@ -262,9 +253,7 @@ Useful first checks after any run:
 Realized equity points:
 
 ```js
-[
-  { time, timestamp, equity }
-]
+[{ time, timestamp, equity }];
 ```
 
 `time` and `timestamp` contain the same Unix-millisecond value.
@@ -298,25 +287,47 @@ const result = backtestPortfolio({
 
 ### How it works
 
-- capital is allocated up front by weight
-- each system runs through the normal single-symbol engine
-- the portfolio result merges trades, positions, replay events, and equity series
+- systems share one live capital pool
+- `weight` or `allocation: "equal" | "weight"` defines the default per-system cap, not a pre-funded sleeve
+- fills lock capital immediately, later fills size against remaining available capital
+- `eqSeries` points include `lockedCapital` and `availableCapital`
+- `maxDailyLossPct` can halt all systems for the rest of the day once breached
 
 ### What it is not
 
 - a cross-margin broker simulator
-- a portfolio-level fill arbiter
-- a shared capital-locking engine
+- a prime-broker margin model
+- a full portfolio optimizer
 
-If you need shared real-time portfolio constraints, this is not that tool yet.
+This mode now does enforce shared capital and cross-system sizing, but it still uses the library's research-oriented execution assumptions rather than full broker accounting.
+
+## `backtestTicks(options)`
+
+Use tick mode when you want event-driven fills while keeping the same result shape as `backtest()`.
+
+```js
+const result = backtestTicks({
+  ticks,
+  queueFillProbability: 0.5,
+  signal,
+});
+```
+
+### How it works
+
+- market entries fill on the next tick
+- limit orders can fill at the touch based on `queueFillProbability`
+- stop exits fill at the stop and use the normal stop slippage model from `costs.slippageByKind.stop`
+- results still come back as `trades`, `positions`, `metrics`, `eqSeries`, and `replay`
 
 ## `walkForwardOptimize(options)`
 
-Use walk-forward mode when one in-sample backtest is not enough and you want rolling train/test validation.
+Use walk-forward mode when one in-sample backtest is not enough and you want rolling or anchored train/test validation.
 
 ```js
 const wf = walkForwardOptimize({
   candles,
+  mode: "anchored",
   trainBars: 180,
   testBars: 60,
   stepBars: 60,
@@ -336,13 +347,14 @@ const wf = walkForwardOptimize({
 1. Evaluate every parameter set on the training slice
 2. Pick the best one by `scoreBy`
 3. Run that parameter set on the next test slice
-4. Repeat for each window
+4. Repeat for each window using either rolling or anchored training windows
 
 ### Return value
 
 - `windows`: per-window summaries and chosen parameters
 - `trades`, `positions`, `metrics`, `eqSeries`
-- `bestParams`: chosen parameters for each window
+- `bestParams`: chosen parameters for each window plus a stability summary
+- `bestParamsSummary`: adjacent repeat rate, dominant winner, and winner leaderboard
 
 In practice, the per-window output matters more than the aggregate headline. If the winning parameters swing wildly from one window to the next, treat that as a real signal.
 
@@ -361,3 +373,5 @@ Most users do not need this directly. Use it when:
 - 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
+
+<small>[Back to main page](README.md)</small>

package/docs/data-reporting-cli.md

@@ -1,11 +1,13 @@
 # Data, reporting, and CLI
 
+<small>[Back to main page](README.md)</small>
+
 This page covers the parts of the package around the core engine:
 
 - historical data loading
 - local cache helpers
 - export helpers
-- command-line usage
+- command-line usage for backtest and live workflows
 
 ## Overview
 
@@ -13,13 +15,13 @@ If you are not bringing your own candles yet, start here.
 
 ## Choose the right entry point
 
-| Use case | Function |
-| --- | --- |
+| Use case                                                  | Function                 |
+| --------------------------------------------------------- | ------------------------ |
 | Load data without caring about the source-specific helper | `getHistoricalCandles()` |
-| Fetch directly from Yahoo | `fetchHistorical()` |
-| Load a local CSV file | `loadCandlesFromCSV()` |
-| Reuse saved normalized data | `loadCandlesFromCache()` |
-| Try the package from a terminal first | `tradelab` CLI |
+| Fetch directly from Yahoo                                 | `fetchHistorical()`      |
+| Load a local CSV file                                     | `loadCandlesFromCSV()`   |
+| Reuse saved normalized data                               | `loadCandlesFromCache()` |
+| Try the package from a terminal first                     | `tradelab` CLI           |
 
 ## Historical data
 
@@ -49,15 +51,15 @@ If you are writing application code, prefer `getHistoricalCandles()` over callin
 
 ### Yahoo options
 
-| Option | Purpose |
-| --- | --- |
-| `symbol` | Ticker or Yahoo symbol |
-| `interval` | Candle interval such as `1d` or `5m` |
-| `period` | Lookback period such as `6mo` or `1y` |
+| Option           | Purpose                                               |
+| ---------------- | ----------------------------------------------------- |
+| `symbol`         | Ticker or Yahoo symbol                                |
+| `interval`       | Candle interval such as `1d` or `5m`                  |
+| `period`         | Lookback period such as `6mo` or `1y`                 |
 | `includePrePost` | Includes premarket and postmarket data when supported |
-| `cache` | Reuses saved normalized data |
-| `refresh` | Forces a fresh download even if cache exists |
-| `cacheDir` | Overrides the default cache directory |
+| `cache`          | Reuses saved normalized data                          |
+| `refresh`        | Forces a fresh download even if cache exists          |
+| `cacheDir`       | Overrides the default cache directory                 |
 
 The Yahoo layer retries transient failures with exponential backoff. If the endpoint still fails, the error message points users toward CSV or cached data.
 
@@ -148,12 +150,9 @@ The main bundle export. By default it writes:
 
 Return value:
 
+<!-- prettier-ignore -->
 ```js
-{
-  csv,
-  html,
-  metrics
-}
+{ csv, html, metrics }
 ```
 
 If you only need one output type, call the narrower helper directly.
@@ -183,13 +182,16 @@ The CLI is best for quick iteration, smoke tests, and trying the package before
 
 ## Commands
 
-| Command | Purpose |
-| --- | --- |
-| `tradelab backtest` | Run a single backtest from Yahoo or CSV |
-| `tradelab portfolio` | Run a simple multi-file portfolio backtest |
-| `tradelab walk-forward` | Run rolling validation with the built-in search |
-| `tradelab prefetch` | Download and cache Yahoo data |
-| `tradelab import-csv` | Normalize and cache a CSV file |
+| Command                 | Purpose                                                                   |
+| ----------------------- | ------------------------------------------------------------------------- |
+| `tradelab backtest`     | Run a single backtest from Yahoo or CSV                                   |
+| `tradelab portfolio`    | Run a simple multi-file portfolio backtest                                |
+| `tradelab walk-forward` | Run rolling or anchored validation with built-in or local strategy search |
+| `tradelab live`         | Run live engine or orchestrator mode                                      |
+| `tradelab paper`        | Run live engine in paper broker mode                                      |
+| `tradelab status`       | Inspect persisted live namespace state                                    |
+| `tradelab prefetch`     | Download and cache Yahoo data                                             |
+| `tradelab import-csv`   | Normalize and cache a CSV file                                            |
 
 ### Backtest
 
@@ -231,10 +233,36 @@ tradelab walk-forward \
   --interval 1d \
   --period 2y \
   --trainBars 180 \
-  --testBars 60
+  --testBars 60 \
+  --mode anchored
 ```
 
-The CLI walk-forward command currently uses the built-in `ema-cross` parameter search.
+The CLI walk-forward command defaults to the built-in `ema-cross` search, but `--strategy ./path/to/module.mjs` can now load a local module that exports `signalFactory(params, args)` and either `parameterSets` or `createParameterSets(args)`. Inline JSON grids are also accepted through `--parameterSets`.
+
+### Live and paper
+
+```bash
+tradelab paper --symbol AAPL --interval 1m --mode polling --once true
+
+tradelab live \
+  --strategy ./mySignal.js \
+  --symbol AAPL \
+  --interval 1m \
+  --broker alpaca \
+  --apiKey $APCA_KEY \
+  --apiSecret $APCA_SECRET
+
+tradelab live --config ./live-portfolio.json --paper --mode polling --once true
+```
+
+For full runtime details, see [live-trading.md](live-trading.md).
+
+### Status
+
+```bash
+tradelab status --dir ./output/live-state
+tradelab status --dir ./output/live-state --namespace my-system
+```
 
 ### Cache utilities
 
@@ -245,10 +273,12 @@ tradelab import-csv --csvPath ./data/spy.csv --symbol SPY --interval 1d
 
 ## Troubleshooting
 
-| Problem | Check first |
-| --- | --- |
-| Yahoo request errors | enable cache, retry later, or fall back to CSV |
-| Unexpected trade count | `warmupBars`, `flattenAtClose`, and signal frequency |
-| Empty result | candle order, signal logic, and stop/target validity |
-| Confusing CSV import | inspect normalized bars from `loadCandlesFromCSV()` before backtesting |
-| Export confusion | use metrics JSON first if you need programmatic output |
+| Problem                | Check first                                                            |
+| ---------------------- | ---------------------------------------------------------------------- |
+| Yahoo request errors   | enable cache, retry later, or fall back to CSV                         |
+| Unexpected trade count | `warmupBars`, `flattenAtClose`, and signal frequency                   |
+| Empty result           | candle order, signal logic, and stop/target validity                   |
+| Confusing CSV import   | inspect normalized bars from `loadCandlesFromCSV()` before backtesting |
+| Export confusion       | use metrics JSON first if you need programmatic output                 |
+
+<small>[Back to main page](README.md)</small>