@backtest-kit/cli 5.10.2 → 5.11.1

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) |

package/template/project/docs/backtest_risk_async.md

@@ -0,0 +1,153 @@
+# Async Risk Validation with resolve()
+
+## Overview
+
+Risk validators can be async and call `resolve()` on any graph node. This lets you reuse the same source nodes (garch, trend, fear & greed) in both signal generation and risk filtering — without duplicate fetches.
+
+---
+
+## Sync vs async validation
+
+`backtest_strategy_structure.md` shows the basic sync pattern:
+
+```ts
+// Sync — receives pre-computed payload fields
+validations: [
+  {
+    validate: ({ currentSignal, currentPrice }) => {
+      if (currentSignal.position === "short" && currentPrice > 50000) {
+        throw new Error("Price too high for short");
+      }
+    },
+  },
+],
+```
+
+Async pattern — resolve a graph node:
+
+```ts
+// Async — fetch fresh data at validation time
+validations: [
+  async () => {
+    const garch = await resolve(garchSource);
+    if (!garch.reliable || garch.movePercent < 1.0) {
+      throw new Error(`GARCH volatility too low: ${garch.movePercent.toFixed(2)}%`);
+    }
+  },
+],
+```
+
+Both forms can coexist in the same `validations` array.
+
+---
+
+## GARCH volatility gate
+
+The canonical use case: block signals when predicted volatility is too low to cover transaction costs and generate profit.
+
+```ts
+import { predict } from "garch";
+import { sourceNode, resolve } from "@backtest-kit/graph";
+import { Cache, getCandles, addRiskSchema } from "backtest-kit";
+
+const CANDLES_FOR_GARCH = 1_000;
+const GARCH_CONFIDENCE  = 0.95;
+const MIN_MOVE_PERCENT  = 1.0;
+
+const garchSource = sourceNode(
+  Cache.fn(
+    async (symbol: string) => {
+      const candles = await getCandles(symbol, "8h", CANDLES_FOR_GARCH);
+      return predict(candles, "8h", null, GARCH_CONFIDENCE);
+    },
+    { interval: "8h", key: ([symbol]: [string]) => symbol },
+  ),
+);
+
+addRiskSchema({
+  riskName: "garch_volatility_risk",
+  validations: [
+    async () => {
+      const garch = await resolve(garchSource);
+      if (!garch.reliable || garch.movePercent < MIN_MOVE_PERCENT) {
+        throw new Error(
+          `GARCH volatility too low: ${garch.movePercent.toFixed(2)}% (need ≥${MIN_MOVE_PERCENT}%, confidence=${GARCH_CONFIDENCE})`,
+        );
+      }
+    },
+  ],
+});
+```
+
+**`garch.reliable`** — false when the model didn't converge or has insufficient data. Always check this before using `movePercent`.
+
+**`garch.movePercent`** — predicted price move as percentage of current price over one candle (one 8h bar here). At confidence=0.95 (±1.96σ), a value of 1.0 means the model predicts ≥1% move with 95% probability.
+
+---
+
+## Fear & Greed gate (directional)
+
+From `feb_2024.strategy.ts` — block longs in fear and shorts in greed:
+
+```ts
+addRiskSchema({
+  riskName: "fear_greed_directional",
+  validations: [
+    async ({ currentSignal }) => {
+      const fearGreed = await resolve(fearGreedSource);
+      if (currentSignal.position === "short" && fearGreed > 50) {
+        throw new Error(`Still greed (${fearGreed}): short not allowed`);
+      }
+    },
+    async ({ currentSignal }) => {
+      const fearGreed = await resolve(fearGreedSource);
+      if (currentSignal.position === "long" && fearGreed < 50) {
+        throw new Error(`Still fear (${fearGreed}): long not allowed`);
+      }
+    },
+  ],
+});
+```
+
+`fearGreedSource` uses `Cache.file` with `interval: "8h"` — fetched once per 8h from `api.alternative.me`.
+
+---
+
+## Node deduplication in risk
+
+When `garchSource` is a dependency of both `enterSignal` (output node) and the risk validator, the graph deduplicates resolution within the same tick. If `getSignal()` already resolved `garchSource`, the risk validator gets the cached result — no second fetch.
+
+This only holds if the validator uses `resolve(garchSource)` with the **same node reference**. Do not create a new `sourceNode` inside the validator — that would be a different node with its own cache.
+
+---
+
+## `validate` vs bare async function
+
+Both forms are accepted in `validations`:
+
+```ts
+// Object form — supports `note` field
+validations: [
+  {
+    note: "GARCH volatility must be at least 1%",
+    validate: async () => {
+      const garch = await resolve(garchSource);
+      if (!garch.reliable || garch.movePercent < 1.0) {
+        throw new Error("...");
+      }
+    },
+  },
+]
+
+// Bare async function — more concise
+validations: [
+  async () => {
+    const garch = await resolve(garchSource);
+    if (!garch.reliable || garch.movePercent < 1.0) {
+      throw new Error("...");
+    }
+  },
+]
+```
+
+Throw `Error` to reject the signal. Return normally (or return `void`) to allow it.