tradelab 0.5.0 → 1.0.0

package/docs/README.md

@@ -4,20 +4,23 @@
 
 - [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) |
-| See complete strategy patterns | [Strategy examples](examples.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
 
@@ -26,12 +29,12 @@ 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
 - exchange microstructure modeling
 
 ## Common workflows
@@ -56,10 +59,19 @@ 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
 

package/docs/api-reference.md

@@ -1,5 +1,5 @@
-
 # API reference
+
 <small>[Back to main page](README.md)</small>
 
 This page is the compact index of public exports.
@@ -8,40 +8,95 @@ If you are learning the package, start with [backtest-engine.md](backtest-engine
 
 ## Backtesting
 
-| 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 |
+| 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
@@ -70,6 +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:
 
-<small>[Back to main page](README.md)</small>
+- [../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

@@ -2,7 +2,6 @@
 
 <small>[Back to main page](README.md)</small>
 
-
 This page covers the simulation layer:
 
 - `backtest(options)`
@@ -15,15 +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()` |
-| One strategy on tick or quote data | `backtestTicks()` |
-| Multiple symbols with one combined result | `backtestPortfolio()` |
+| 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()` |
+| Recompute metrics from realized trades    | `buildMetrics()`        |
 
 ## Candle input
 
@@ -76,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:
 
@@ -97,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`.
@@ -207,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`
@@ -267,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.
@@ -390,4 +374,4 @@ Most users do not need this directly. Use it when:
 - 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>
+<small>[Back to main page](README.md)</small>

package/docs/data-reporting-cli.md

@@ -1,4 +1,5 @@
 # Data, reporting, and CLI
+
 <small>[Back to main page](README.md)</small>
 
 This page covers the parts of the package around the core engine:
@@ -6,7 +7,7 @@ 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
 
@@ -14,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
 
@@ -50,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.
 
@@ -149,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.
@@ -184,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 |
+| 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 prefetch` | Download and cache Yahoo data |
-| `tradelab import-csv` | Normalize and cache a CSV file |
+| `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
 
@@ -238,6 +239,31 @@ tradelab walk-forward \
 
 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
 
 ```bash
@@ -247,12 +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>
+<small>[Back to main page](README.md)</small>

package/docs/examples.md

@@ -1,4 +1,5 @@
 # Strategy examples
+
 <small>[Back to main page](README.md)</small>
 
 These are research templates. They show how to wire different kinds of data and execution assumptions into the engine without changing the output pipeline.
@@ -117,14 +118,13 @@ const candles = await getHistoricalCandles({
 
 const sentimentByDay = new Map([
   ["2025-01-02", 0.75],
-  ["2025-01-03", -0.10],
+  ["2025-01-03", -0.1],
   // ...
 ]);
 
 const enriched = candles.map((bar) => ({
   ...bar,
-  sentiment:
-    sentimentByDay.get(new Date(bar.time).toISOString().slice(0, 10)) ?? 0,
+  sentiment: sentimentByDay.get(new Date(bar.time).toISOString().slice(0, 10)) ?? 0,
 }));
 
 const result = backtest({
@@ -137,11 +137,7 @@ const result = backtest({
     const slow = ema(closes, 30);
     const last = closes.length - 1;
 
-    if (
-      fast[last - 1] <= slow[last - 1] &&
-      fast[last] > slow[last] &&
-      bar.sentiment > 0.5
-    ) {
+    if (fast[last - 1] <= slow[last - 1] && fast[last] > slow[last] && bar.sentiment > 0.5) {
       return {
         side: "long",
         entry: bar.close,
@@ -180,9 +176,7 @@ const labeled = await Promise.all(
     regime:
       index < 20
         ? "neutral"
-        : await classifyRegime(
-            candles.slice(index - 20, index).map((c) => c.close)
-          ),
+        : await classifyRegime(candles.slice(index - 20, index).map((c) => c.close)),
   }))
 );
 
@@ -278,4 +272,4 @@ const result = backtestPortfolio({
 
 `result.eqSeries` includes `lockedCapital` and `availableCapital` at each realized equity point. Use those to see how often the portfolio was fully deployed versus sitting partially idle.
 
-<small>[Back to main page](README.md)</small>
+<small>[Back to main page](README.md)</small>