@backtest-kit/cli 5.11.0 → 6.0.0

package/template/project/docs/backtest_graph_pattern.md

@@ -0,0 +1,235 @@
+# Graph Pattern (sourceNode / outputNode / resolve)
+
+## Purpose
+
+`@backtest-kit/graph` provides a typed directed acyclic graph (DAG) for composing strategy logic. Instead of a single monolithic `getSignal` function, you define reusable **source nodes** (data fetchers) and **output nodes** (computations that combine them).
+
+Benefits:
+- Each node caches independently via `Cache.fn`
+- Type-safe: TypeScript infers value types through the graph
+- Parallel resolution: sibling nodes resolve concurrently
+
+---
+
+## Core API
+
+```ts
+import { sourceNode, outputNode, resolve } from "@backtest-kit/graph";
+import { Cache } from "backtest-kit";
+```
+
+### `sourceNode(fetch)`
+
+A leaf node with no dependencies. Fetches data from an external source.
+
+```ts
+const mySource = sourceNode(
+  Cache.fn(
+    async (symbol: string) => {
+      const candles = await getCandles(symbol, "15m", 500);
+      return garch.predictRange(candles, "15m", 32);
+    },
+    { interval: "15m", key: ([symbol]) => symbol },
+  ),
+);
+```
+
+- `fetch` signature: `(symbol: string, when: Date, exchangeName: string) => Promise<T>`
+- `Cache.fn` wraps the fetch function with interval-based caching (see [Cache section](#cachefn))
+- `T` can be any non-undefined value: `number`, `string`, `boolean`, `object`, `null`
+
+### `outputNode(compute, ...nodes)`
+
+A computation node that receives resolved values from its dependencies.
+
+```ts
+const strategySignal = outputNode(
+  async ([trend, volume, reversal]) => {
+    // trend, volume, reversal are the resolved values of the three source nodes
+    if (!volume.reliable) return null;
+    return { position: "long", priceTakeProfit: volume.upperPrice, ... };
+  },
+  masterTrendSource,  // dependency 1 → trend
+  rangeSource,        // dependency 2 → volume
+  reversalSource,     // dependency 3 → reversal
+);
+```
+
+- `compute` receives a tuple of resolved values **in the same order as the nodes**
+- Return type is inferred automatically
+- Can return `null` (no signal)
+- Can be nested: an output node can be a dependency of another output node
+
+### `resolve(node)`
+
+Executes the graph: resolves all dependencies recursively, then calls `compute`.
+
+```ts
+addStrategySchema({
+  strategyName: "my_strategy",
+  interval: "15m",
+  getSignal: () => resolve(strategySignal),
+});
+```
+
+- Dependencies are resolved **in parallel** (Promise.all internally)
+- The `symbol` and `when` context is injected automatically from the strategy runtime
+- Returns the output node's computed value
+
+---
+
+## Cache.fn
+
+Wraps any async function to cache results per candle interval and per cache key.
+
+```ts
+const cachedFn = Cache.fn(
+  async (symbol: string) => {
+    // expensive operation
+    return fetchSomething(symbol);
+  },
+  {
+    interval: "15m",                    // invalidate every 15m candle boundary
+    key: ([symbol]) => symbol,          // separate cache entry per symbol
+  },
+);
+```
+
+**How invalidation works:** The cache aligns to candle boundaries. At `interval="15m"`, the cache is valid within the same 15-minute bar and invalidated when a new bar opens. This means multiple calls within one bar return the same result without re-fetching.
+
+**Without `key`:** single cache entry — all calls share one result regardless of arguments.
+**With `key`:** separate cache entry per key — `"BTCUSDT"` and `"ETHUSDT"` computed independently.
+
+Cache.fn is designed to be passed directly as the `fetch` argument to `sourceNode`.
+
+---
+
+## Full Pattern Example
+
+```ts
+import { extract, run, File } from "@backtest-kit/pinets";
+import { getCandles, getAggregatedTrades, Cache } from "backtest-kit";
+import { sourceNode, outputNode, resolve } from "@backtest-kit/graph";
+import * as garch from "garch";
+import * as anomaly from "volume-anomaly";
+
+// === Source nodes ===
+
+const masterTrendSource = sourceNode(
+  Cache.fn(
+    async (symbol) => {
+      const plots = await run(
+        File.fromPath("master_trend_15m.pine", "../math"),
+        { symbol, timeframe: "15m", limit: 180 },
+      );
+      return extract(plots, {
+        position: "Position",
+        close:    "Close",
+      });
+    },
+    { interval: "15m", key: ([symbol]) => symbol },
+  ),
+);
+
+const rangeSource = sourceNode(
+  Cache.fn(
+    async (symbol) => {
+      const candles = await getCandles(symbol, "15m", 1_000);
+      return garch.predictRange(candles, "15m", 32);
+    },
+    { interval: "15m", key: ([symbol]) => symbol },
+  ),
+);
+
+const reversalSource = sourceNode(
+  Cache.fn(
+    async (symbol) => {
+      const all = await getAggregatedTrades(symbol, 1400);
+      return anomaly.predict(all.slice(0, 1200), all.slice(1200), 0.75);
+    },
+    { interval: "15m", key: ([symbol]) => symbol },
+  ),
+);
+
+// === Output node (signal logic) ===
+
+const strategySignal = outputNode(
+  async ([trend, volume, reversal]) => {
+    if (!volume.reliable || volume.movePercent < 0.7) return null;
+    if (trend.position === 0) return null;
+    if (!reversal.anomaly) return null;
+
+    let position: "long" | "short" | null = null;
+    if (trend.position === 1  && reversal.direction === "long")  position = "long";
+    if (trend.position === -1 && reversal.direction === "short") position = "short";
+    if (!position) return null;
+
+    return {
+      id: randomString(),
+      position,
+      priceTakeProfit:     position === "long" ? volume.upperPrice : volume.lowerPrice,
+      priceStopLoss:       position === "long" ? volume.lowerPrice : volume.upperPrice,
+      minuteEstimatedTime: 480,
+    } as const;
+  },
+  masterTrendSource,
+  rangeSource,
+  reversalSource,
+);
+
+// === Wire into strategy ===
+
+addStrategySchema({
+  strategyName: "bounce_strategy",
+  interval: "15m",
+  getSignal: () => resolve(strategySignal),
+});
+```
+
+---
+
+## Cache Interval Selection
+
+Choose `Cache.fn` interval to match the data's natural update frequency:
+
+| Data source | Recommended interval |
+|---|---|
+| Pine indicator (15m timeframe) | `"15m"` |
+| `garch.predictRange` on 15m candles | `"15m"` |
+| `garch.predict` on 5m candles | `"5m"` |
+| `anomaly.predict` (trade stream) | `"5m"` — refreshed every 5m bar |
+| Funding rate | `"1h"` |
+| Order book snapshot | `"1m"` |
+
+Setting interval too short wastes compute; too long means stale data spanning multiple bars. Match to the smallest timeframe of the data being fetched.
+
+---
+
+## Type Safety
+
+The graph is fully typed. TypeScript infers the compute callback parameter types from the node declarations:
+
+```ts
+// If rangeSource returns garch.PredictionResult:
+const rangeSource = sourceNode(
+  Cache.fn(async (symbol) => garch.predictRange(candles, "15m", 32), { interval: "15m", key: ([s]) => s }),
+);
+// TS knows rangeSource is SourceNode<PredictionResult>
+
+const out = outputNode(
+  async ([volume]) => {
+    volume.movePercent  // ✓ typed as number
+    volume.upperPrice   // ✓ typed as number
+    volume.nonExistent  // ✗ TS error
+  },
+  rangeSource,
+);
+```
+
+---
+
+## Notes
+
+- `resolve()` is called **inside** `getSignal`, not at module level. This ensures the graph runs per-tick with the correct symbol/when context.
+- Each source node in the graph is resolved **once per tick** even if referenced by multiple output nodes (deduplication by reference).
+- The graph does **not** support cycles.

package/template/project/docs/backtest_logging_jsonl.md

@@ -0,0 +1,246 @@
+# Logging & JSONL — Coefficient Tuning Guide
+
+## Purpose
+
+`Log` from `backtest-kit` writes structured entries to a `.jsonl` file during backtests. Each line is a JSON object. After running a backtest, you analyse the file to understand why signals fired or were blocked, then adjust thresholds.
+
+---
+
+## Setup
+
+Call `Log.useJsonl` **once at module level**, before any schema registrations:
+
+```ts
+import { Log } from "backtest-kit";
+
+Log.useJsonl("bounce_strategy", "./dump/log");
+// Writes to: ./dump/log/bounce_strategy.jsonl
+```
+
+Parameters:
+- First arg: base filename (without extension)
+- Second arg: directory path (created automatically if missing)
+
+Each `Log.log / Log.info / Log.debug / Log.warn` call appends one JSON line to the file.
+
+**Default mode is in-memory** — call `useJsonl` to activate file output. Other modes:
+- `Log.useMemory()` — default, no file I/O
+- `Log.useDummy()` — no-op, zero overhead
+- `Log.usePersist()` — persistent adapter (db-backed)
+
+---
+
+## Log Levels
+
+```ts
+Log.log(topic, ...args)    // general events — use for signal opens
+Log.debug(topic, ...args)  // diagnostic details — use for filter rejections
+Log.info(topic, ...args)   // informational — use for per-tick snapshots
+Log.warn(topic, ...args)   // warnings — unexpected but non-fatal conditions
+```
+
+`topic` is the first argument and becomes the log's searchable category. Always use a fixed string identifier. `args` are serialized as JSON in the `args` array of the log entry.
+
+---
+
+## ILogEntry Structure
+
+Every written line has this shape:
+
+```ts
+interface ILogEntry {
+  id:               string;   // unique entry id
+  type:             "log" | "debug" | "info" | "warn";
+  timestamp:        number;   // unix ms (wall clock)
+  createdAt:        string;   // ISO date from backtest context
+  topic:            string;   // first argument to Log.xxx()
+  args:             unknown[]; // remaining arguments
+  methodContext:    IMethodContext | null;
+  executionContext: IExecutionContext | null;
+}
+```
+
+`createdAt` reflects the **backtest simulation time** (the bar's timestamp), not the wall clock. This is what you use to correlate log entries with price history.
+
+---
+
+## Recommended Logging Pattern for Coefficient Tuning
+
+Three topic categories cover everything needed:
+
+### 1. `bar_snapshot` — every tick (Log.info)
+
+Log all indicator values on **every** `getSignal` call, regardless of whether a signal fires. This gives you the full distribution of each metric.
+
+```ts
+Log.info("bar_snapshot", {
+  // Pine extremes
+  totalHighs:  extreme.totalHighs,
+  totalLows:   extreme.totalLows,
+  balance:     extreme.balance,
+  trend:       extreme.trend,
+  // GARCH
+  movePercent: volume.movePercent,
+  sigma:       volume.sigma,
+  modelType:   volume.modelType,
+  reliable:    volume.reliable,
+  // Volume anomaly
+  anomaly:     reversal.anomaly,
+  confidence:  reversal.confidence,
+  direction:   reversal.direction,
+  imbalance:   reversal.imbalance,
+});
+```
+
+After backtest: load the JSONL and look at the **percentile distribution** of each field. Example: if `movePercent` is > 0.7% only 5% of the time, your filter is very restrictive — consider lowering the threshold or you'll have very few trades.
+
+### 2. `filter_rejected` — per failed filter (Log.debug)
+
+Log **which** filter blocked the signal and the exact value that failed:
+
+```ts
+// Filter 1: volatility
+if (!volume.reliable || volume.movePercent < MIN_MOVE_PERCENT) {
+  Log.debug("filter_rejected", {
+    reason:      "garch_low_vol",
+    movePercent: volume.movePercent,
+    threshold:   MIN_MOVE_PERCENT,
+    reliable:    volume.reliable,
+  });
+  return null;
+}
+
+// Filter 2: extreme touches
+if (extreme.totalHighs < MIN_TOTAL_TOUCHES && extreme.totalLows < MIN_TOTAL_TOUCHES) {
+  Log.debug("filter_rejected", {
+    reason:     "not_enough_touches",
+    totalHighs: extreme.totalHighs,
+    totalLows:  extreme.totalLows,
+    threshold:  MIN_TOTAL_TOUCHES,
+  });
+  return null;
+}
+
+// Filter 3: anomaly
+if (!reversal.anomaly) {
+  Log.debug("filter_rejected", {
+    reason:     "no_anomaly",
+    confidence: reversal.confidence,
+    threshold:  ANOMALY_CONFIDENCE,
+  });
+  return null;
+}
+
+// Filter 4: direction mismatch
+if (!position) {
+  Log.debug("filter_rejected", {
+    reason:     "direction_mismatch",
+    direction:  reversal.direction,
+    isHighTest, isLowTest,
+  });
+  return null;
+}
+```
+
+After backtest: count entries per `reason`. The most frequent rejection is your bottleneck. If `garch_low_vol` dominates — lower `MIN_MOVE_PERCENT`. If `no_anomaly` dominates — lower `ANOMALY_CONFIDENCE`.
+
+### 3. `signal_open` — when a signal fires (Log.log)
+
+Log the complete state at the moment a signal is created:
+
+```ts
+Log.log("signal_open", {
+  position,
+  tp,
+  sl,
+  totalHighs:  extreme.totalHighs,
+  totalLows:   extreme.totalLows,
+  balance:     extreme.balance,
+  confidence:  reversal.confidence,
+  direction:   reversal.direction,
+  imbalance:   reversal.imbalance,
+  movePercent: volume.movePercent,
+  sigma:       volume.sigma,
+  modelType:   volume.modelType,
+});
+```
+
+After backtest: cross-reference `signal_open` entries with trade PNL to find which combination of values (e.g. `totalHighs >= 5 AND confidence > 0.85`) correlates with profitable trades.
+
+---
+
+## Analysing the JSONL File
+
+The file at `./dump/log/bounce_strategy.jsonl` contains one JSON object per line.
+
+**Quick shell inspection:**
+
+```bash
+# Count entries per topic
+cat ./dump/log/bounce_strategy.jsonl | grep -o '"topic":"[^"]*"' | sort | uniq -c
+
+# Count filter rejection reasons
+cat ./dump/log/bounce_strategy.jsonl | python3 -c "
+import sys, json
+from collections import Counter
+reasons = []
+for line in sys.stdin:
+    e = json.loads(line)
+    if e['topic'] == 'filter_rejected' and e['args']:
+        reasons.append(e['args'][0].get('reason','?'))
+print(Counter(reasons))
+"
+
+# Extract all bar_snapshots as CSV for Excel
+cat ./dump/log/bounce_strategy.jsonl | python3 -c "
+import sys, json
+rows = []
+for line in sys.stdin:
+    e = json.loads(line)
+    if e['topic'] == 'bar_snapshot' and e['args']:
+        d = e['args'][0]
+        d['createdAt'] = e['createdAt']
+        rows.append(d)
+import csv
+if rows:
+    w = csv.DictWriter(sys.stdout, fieldnames=rows[0].keys())
+    w.writeheader()
+    w.writerows(rows)
+"
+```
+
+---
+
+## CONFIG Constants Pattern
+
+Keep all tunable thresholds as named constants at the top of the strategy file:
+
+```ts
+// === CONFIG (tune before each backtest run) ===
+const MIN_MOVE_PERCENT   = 0.7;   // garch filter: minimum 8h volatility
+const RANGE_STEPS        = 32;    // predictRange horizon: 32 × 15m = 8h
+const MIN_TOTAL_TOUCHES  = 3;     // extreme direction: min tests of high/low
+const ANOMALY_CONFIDENCE = 0.75;  // volume-anomaly composite threshold
+const PINE_LIMIT         = 300;   // Pine script warmup + output bars
+const CANDLES_FOR_GARCH  = 1_000; // GARCH history length
+const N_TRAIN            = 1200;  // volume-anomaly baseline window (trades)
+const N_DETECT           = 200;   // volume-anomaly detection window (trades)
+```
+
+**Tuning workflow:**
+1. Run backtest → check `filter_rejected` distribution in JSONL
+2. Identify the bottleneck (dominant rejection reason)
+3. Adjust the corresponding CONFIG constant
+4. Re-run backtest
+5. Repeat until signal frequency and PNL balance is acceptable
+
+---
+
+## Log File Location
+
+| `useJsonl(name, dir)` call | Output path |
+|---|---|
+| `Log.useJsonl("bounce_strategy", "./dump/log")` | `./dump/log/bounce_strategy.jsonl` |
+| `Log.useJsonl("debug", "./dump")` | `./dump/debug.jsonl` |
+
+The directory is relative to the working directory where the CLI is invoked (project root).

package/template/project/docs/backtest_pinets_usage.md

@@ -0,0 +1,190 @@
+# Pine Script Integration (@backtest-kit/pinets)
+
+## Overview
+
+`@backtest-kit/pinets` runs `.pine` files against exchange data and returns named plot series. In a strategy file you use two functions: `run()` to execute the script and `extract()` to read the last bar's values.
+
+---
+
+## Key Difference: Strategy vs Standalone Runner
+
+| Context | `exchangeName` | `when` |
+|---|---|---|
+| `content/*.strategy.ts` (backtest CLI) | **omit** — resolved from context | **omit** — uses current backtest tick |
+| `scripts/run_*.mjs` (standalone) | **required** | **required** |
+
+In strategy files, both arguments are injected automatically by the runtime. Do not pass them manually.
+
+---
+
+## `run(source, params)` — Execute Pine Script
+
+```ts
+import { run, File } from "@backtest-kit/pinets";
+
+const plots = await run(
+  File.fromPath("master_trend_15m.pine", "../math"),
+  {
+    symbol:    "BTCUSDT",   // injected from strategy context automatically
+    timeframe: "15m",       // Pine script timeframe
+    limit:     180,         // number of candles (warmup + output)
+  },
+  // exchangeName omitted — resolved from context in strategy files
+  // when omitted — uses current backtest tick time
+);
+```
+
+**`File.fromPath(filename, baseDir)`:**
+- `filename` — path relative to `baseDir`, not cwd
+- `baseDir` — optional, defaults to cwd
+- Example: `File.fromPath("master_trend_15m.pine", "../math")` → resolves to `../math/master_trend_15m.pine`
+
+**`params.limit`:**
+- Must cover warmup + desired output bars
+- See `pine_indicator_warmup.md` for how to calculate the correct limit
+
+**Returns:** `PlotModel` — a record of plot name → `{ data: Array<{ time: number, value: number }> }`
+
+---
+
+## `extract(plots, mapping)` — Read Last Bar Values
+
+`extract` reads the **last valid bar** from each named plot and returns a typed record.
+
+```ts
+import { extract } from "@backtest-kit/pinets";
+
+const result = await extract(plots, {
+  position: "Position",  // JS key → Pine plot name (case-sensitive)
+  close:    "Close",
+});
+
+// result.position → number (last bar value of "Position" plot)
+// result.close    → number
+```
+
+**The mapping object:**
+- Keys: JavaScript field names you want to use
+- Values: exact Pine plot names as written in the `plot(value, "Name", ...)` call
+- Plot names are **case-sensitive**
+
+**Advanced mapping — read N bars back:**
+
+```ts
+const result = await extract(plots, {
+  position:     "Position",
+  prevPosition: { plot: "Position", barsBack: 1 },   // previous bar value
+});
+// result.prevPosition → value from 1 bar before last
+```
+
+**With transform:**
+
+```ts
+const result = await extract(plots, {
+  isLong: { plot: "Position", transform: (v) => v === 1 },  // returns boolean
+});
+```
+
+---
+
+## Pine Plot Convention
+
+For `extract()` to work, the Pine script must expose plots with `display=display.data_window`:
+
+```pine
+// === OUTPUTS FOR BOT ===
+plot(close,    "Close",    display=display.data_window)
+plot(position, "Position", display=display.data_window)
+```
+
+Plots without `display=display.data_window` are not accessible via `extract()`.
+
+---
+
+## Using in a sourceNode
+
+The standard pattern in a strategy — wrap in `Cache.fn` inside `sourceNode`:
+
+```ts
+import { run, extract, File } from "@backtest-kit/pinets";
+import { Cache } from "backtest-kit";
+import { sourceNode } from "@backtest-kit/graph";
+
+const masterTrendSource = sourceNode(
+  Cache.fn(
+    async (symbol) => {
+      const plots = await run(
+        File.fromPath("master_trend_15m.pine", "../math"),
+        {
+          symbol,
+          timeframe: "15m",
+          limit: 180,           // warmup(30) + 150 output bars
+        },
+      );
+      return extract(plots, {
+        position: "Position",
+        close:    "Close",
+      });
+    },
+    { interval: "15m", key: ([symbol]) => symbol },
+  ),
+);
+```
+
+- Cache interval matches the Pine timeframe (`"15m"`)
+- `key` separates cache by symbol (important for multi-symbol backtests)
+- `limit` must be set high enough — see `pine_indicator_warmup.md`
+
+---
+
+## `getSignal()` — Pine-Driven Signal
+
+An alternative to manually computing signals in JS: let Pine compute the signal directly.
+
+Pine script must expose specific plot names:
+
+```pine
+plot(signal,         "Signal",        display=display.data_window)  // 1=long, -1=short, 0=none
+plot(close,          "Close",         display=display.data_window)  // entry price
+plot(sl_price,       "StopLoss",      display=display.data_window)
+plot(tp_price,       "TakeProfit",    display=display.data_window)
+plot(estimated_time, "EstimatedTime", display=display.data_window)  // optional, default 240
+```
+
+```ts
+import { getSignal, File } from "@backtest-kit/pinets";
+
+const signal = await getSignal(
+  File.fromPath("my_signal.pine", "../math"),
+  { symbol, timeframe: "15m", limit: 200 },
+);
+// Returns ISignalDto | null
+```
+
+Use `getSignal` when signal logic is simpler to express in Pine than in JS. Use `run` + `extract` when you need to combine Pine output with JS-side libraries (garch, volume-anomaly, etc.).
+
+---
+
+## Limit Calculation Quick Reference
+
+See `pine_indicator_warmup.md` for full details. Short version:
+
+```
+limit = max_lookback_period + desired_output_bars
+```
+
+For `master_trend_15m.pine` with default params (atrPeriod=15, confirmBars=15):
+- Warmup = atrPeriod + confirmBars = 15 + 15 = **30 bars**
+- For 150 output bars: `limit = 30 + 150 = 180`
+
+**Note:** Pine `input.int()` defaults are always used — the `inputs` parameter in `run()` is silently ignored. Change periods directly in the `.pine` file.
+
+---
+
+## Available Pine Outputs (master_trend_15m.pine)
+
+| Plot name | Type | Description |
+|---|---|---|
+| `"Close"` | number | Current close price |
+| `"Position"` | `-1 / 0 / 1` | Confirmed trend direction (0=pending confirmBars) |