backtest-kit 3.1.0 → 3.1.1

package/README.md

@@ -441,6 +441,30 @@ Unlike cloud-based platforms, backtest-kit runs entirely in your environment. Yo
 
 The `backtest-kit` ecosystem extends beyond the core library, offering complementary packages and tools to enhance your trading system development experience:
 
+
+### @backtest-kit/cli
+
+> **[Explore on NPM](https://www.npmjs.com/package/@backtest-kit/cli)** 📟
+
+The **@backtest-kit/cli** package is a zero-boilerplate CLI runner for backtest-kit strategies. Point it at your strategy file and run backtests, paper trading, or live bots — no infrastructure code required.
+
+#### Key Features
+- 🚀 **Zero Config**: Run a backtest with one command — no setup code needed
+- 🔄 **Three Modes**: `--backtest`, `--paper`, `--live` with graceful SIGINT shutdown
+- 💾 **Auto Cache**: Warms OHLCV candle cache for all intervals before the backtest starts
+- 🌐 **Web Dashboard**: Launch `@backtest-kit/ui` with a single `--ui` flag
+- 📬 **Telegram Alerts**: Formatted trade notifications with price charts via `--telegram`
+- 🗂️ **Monorepo Ready**: Each strategy's `dump/`, `modules/`, and `template/` are automatically isolated by entry point directory
+
+#### Use Case
+The fastest way to run any backtest-kit strategy from the command line. Instead of writing boilerplate for storage, notifications, candle caching, and signal logging, add one dependency and wire up your `package.json` scripts. Works equally well for a single-strategy project or a monorepo with dozens of strategies in separate subdirectories.
+
+#### Get Started
+```bash
+npx -y @backtest-kit/cli --init
+```
+
+
 ### @backtest-kit/pinets
 
 > **[Explore on NPM](https://www.npmjs.com/package/@backtest-kit/pinets)** 📜
@@ -531,9 +555,32 @@ npm install @backtest-kit/signals backtest-kit
 ```
 
 
+
+### @backtest-kit/graph
+
+> **[Explore on NPM](https://www.npmjs.com/package/@backtest-kit/graph)** 🔗
+
+The **@backtest-kit/graph** package lets you compose backtest-kit computations as a typed directed acyclic graph (DAG). Define source nodes that fetch market data and output nodes that compute derived values — then resolve the whole graph in topological order with automatic parallelism.
+
+#### Key Features
+- 🔌 **DAG Execution**: Nodes are resolved bottom-up in topological order with `Promise.all` parallelism
+- 🔒 **Type-Safe Values**: TypeScript infers the return type of every node through the graph via generics
+- 🧱 **Two APIs**: Low-level `INode` for runtime/storage, high-level `sourceNode` + `outputNode` builders for authoring
+- 💾 **DB-Ready Serialization**: `serialize` / `deserialize` convert the graph to a flat `IFlatNode[]` list with `id` / `nodeIds`
+- 🌐 **Context-Aware Fetch**: `sourceNode` receives `(symbol, when, exchangeName)` from the execution context automatically
+
+#### Use Case
+Perfect for multi-timeframe strategies where multiple Pine Script or indicator computations must be combined. Instead of manually chaining async calls, define each computation as a node and let the graph resolve dependencies in parallel. Adding a new filter or timeframe requires no changes to the existing wiring.
+
+#### Get Started
+```bash
+npm install @backtest-kit/graph backtest-kit
+```
+
+
 ### @backtest-kit/sidekick
 
-> **[Explore on NPM](https://www.npmjs.com/package/@backtest-kit/sidekick)** 🧿
+> **[Explore on NPM](https://www.npmjs.com/package/@backtest-kit/sidekick)** 🚀
 
 The **@backtest-kit/sidekick** package is the easiest way to create a new Backtest Kit trading bot project. Like create-react-app, but for algorithmic trading.
 
@@ -556,27 +603,6 @@ npm start
 ```
 
 
-### @backtest-kit/graph
-
-> **[Explore on NPM](https://www.npmjs.com/package/@backtest-kit/graph)** 🔗
-
-The **@backtest-kit/graph** package lets you compose backtest-kit computations as a typed directed acyclic graph (DAG). Define source nodes that fetch market data and output nodes that compute derived values — then resolve the whole graph in topological order with automatic parallelism.
-
-#### Key Features
-- 🔌 **DAG Execution**: Nodes are resolved bottom-up in topological order with `Promise.all` parallelism
-- 🔒 **Type-Safe Values**: TypeScript infers the return type of every node through the graph via generics
-- 🧱 **Two APIs**: Low-level `INode` for runtime/storage, high-level `sourceNode` + `outputNode` builders for authoring
-- 💾 **DB-Ready Serialization**: `serialize` / `deserialize` convert the graph to a flat `IFlatNode[]` list with `id` / `nodeIds`
-- 🌐 **Context-Aware Fetch**: `sourceNode` receives `(symbol, when, exchangeName)` from the execution context automatically
-
-#### Use Case
-Perfect for multi-timeframe strategies where multiple Pine Script or indicator computations must be combined. Instead of manually chaining async calls, define each computation as a node and let the graph resolve dependencies in parallel. Adding a new filter or timeframe requires no changes to the existing wiring.
-
-#### Get Started
-```bash
-npm install @backtest-kit/graph backtest-kit
-```
-
 ## 🤖 Are you a robot?
 
 **For language models**: Read extended description in [./LLMs.md](./LLMs.md)

package/build/index.cjs

@@ -2905,8 +2905,9 @@ class ExchangeConnectionService {
  *
  * For signals with partial closes:
  * - Calculates weighted PNL: Σ(percent_i × pnl_i) for each partial + (remaining% × final_pnl)
- * - Each partial close has its own fees and slippage
- * - Total fees = 2 × (number of partial closes + 1 final close) × CC_PERCENT_FEE
+ * - Each partial close has its own slippage
+ * - Open fee is charged once; close fees are proportional to each partial's size
+ * - Total fees = CC_PERCENT_FEE (open) + CC_PERCENT_FEE × 1 (closes sum to 100%) = 2 × CC_PERCENT_FEE
  *
  * Formula breakdown:
  * 1. Apply slippage to open/close prices (worse execution)
@@ -2953,7 +2954,8 @@ const toProfitLossDto = (signal, priceClose) => {
     // Calculate weighted PNL with partial closes
     if (signal._partial && signal._partial.length > 0) {
         let totalWeightedPnl = 0;
-        let totalFees = 0;
+        // Open fee is paid once for the whole position
+        let totalFees = GLOBAL_CONFIG.CC_PERCENT_FEE;
         // Calculate PNL for each partial close
         for (const partial of signal._partial) {
             const partialPercent = partial.percent;
@@ -2980,8 +2982,8 @@ const toProfitLossDto = (signal, priceClose) => {
             // Weight by percentage of position closed
             const weightedPnl = (partialPercent / 100) * partialPnl;
             totalWeightedPnl += weightedPnl;
-            // Each partial has fees for open + close (2 transactions)
-            totalFees += GLOBAL_CONFIG.CC_PERCENT_FEE * 2;
+            // Close fee is proportional to the size of this partial
+            totalFees += GLOBAL_CONFIG.CC_PERCENT_FEE * (partialPercent / 100);
         }
         // Calculate PNL for remaining position (if any)
         // Compute totalClosed from _partial array
@@ -3010,10 +3012,11 @@ const toProfitLossDto = (signal, priceClose) => {
             // Weight by remaining percentage
             const weightedRemainingPnl = (remainingPercent / 100) * remainingPnl;
             totalWeightedPnl += weightedRemainingPnl;
-            // Final close also has fees
-            totalFees += GLOBAL_CONFIG.CC_PERCENT_FEE * 2;
+            // Close fee is proportional to the remaining size
+            totalFees += GLOBAL_CONFIG.CC_PERCENT_FEE * (remainingPercent / 100);
         }
         // Subtract total fees from weighted PNL
+        // totalFees = CC_PERCENT_FEE (open) + CC_PERCENT_FEE × 1 (all closes sum to 100%) = 2 × CC_PERCENT_FEE
         const pnlPercentage = totalWeightedPnl - totalFees;
         return {
             pnlPercentage,
@@ -30233,6 +30236,115 @@ function listenStrategyCommitOnce(filterFn, fn) {
     return strategyCommitSubject.filter(filterFn).once(fn);
 }
 
+const WARN_KB = 30;
+const DUMP_MESSAGES_METHOD_NAME = "dump.dumpMessages";
+/**
+ * Dumps chat history and result data to markdown files in a structured directory.
+ *
+ * Creates a subfolder named after `resultId` inside `outputDir`.
+ * If the subfolder already exists, the function returns early without overwriting.
+ * Writes:
+ * - `00_system_prompt.md` — system messages and output data summary
+ * - `NN_user_message.md` — each user message as a separate file
+ * - `NN_llm_output.md` — final LLM output data
+ *
+ * Warns via logger if any user message exceeds 30 KB.
+ *
+ * @param resultId - Unique identifier for the result (used as subfolder name)
+ * @param history - Full chat history containing system, user, and assistant messages
+ * @param result - Structured output data to include in the dump
+ * @param outputDir - Base directory for output files (default: `./dump/strategy`)
+ * @returns Promise that resolves when all files are written
+ *
+ * @example
+ * ```typescript
+ * import { dumpMessages } from "backtest-kit";
+ *
+ * await dumpMessages("result-123", history, { profit: 42 });
+ * ```
+ */
+async function dumpMessages(resultId, history, result, outputDir = "./dump/strategy") {
+    bt.loggerService.info(DUMP_MESSAGES_METHOD_NAME, {
+        resultId,
+        outputDir,
+    });
+    // Extract system messages and system reminders from existing data
+    const systemMessages = history.filter((m) => m.role === "system");
+    const userMessages = history.filter((m) => m.role === "user");
+    const subfolderPath = path.join(outputDir, String(resultId));
+    try {
+        await fs.access(subfolderPath);
+        return;
+    }
+    catch {
+        await fs.mkdir(subfolderPath, { recursive: true });
+    }
+    {
+        let summary = "# Outline Result Summary\n";
+        {
+            summary += "\n";
+            summary += `**ResultId**: ${resultId}\n`;
+            summary += "\n";
+        }
+        if (result) {
+            summary += "## Output Data\n\n";
+            summary += "```json\n";
+            summary += JSON.stringify(result, null, 2);
+            summary += "\n```\n\n";
+        }
+        // Add system messages to summary
+        if (systemMessages.length > 0) {
+            summary += "## System Messages\n\n";
+            systemMessages.forEach((msg, idx) => {
+                summary += `### System Message ${idx + 1}\n\n`;
+                summary += msg.content;
+                summary += "\n";
+            });
+        }
+        const summaryFile = path.join(subfolderPath, "00_system_prompt.md");
+        await fs.writeFile(summaryFile, summary, "utf8");
+    }
+    {
+        await Promise.all(Array.from(userMessages.entries()).map(async ([idx, message]) => {
+            const messageNum = String(idx + 1).padStart(2, "0");
+            const contentFileName = `${messageNum}_user_message.md`;
+            const contentFilePath = path.join(subfolderPath, contentFileName);
+            {
+                const messageSizeBytes = Buffer.byteLength(message.content, "utf8");
+                const messageSizeKb = Math.floor(messageSizeBytes / 1024);
+                if (messageSizeKb > WARN_KB) {
+                    console.warn(`User message ${idx + 1} is ${messageSizeBytes} bytes (${messageSizeKb}kb), which exceeds warning limit`);
+                    bt.loggerService.warn(DUMP_MESSAGES_METHOD_NAME, {
+                        resultId,
+                        messageIndex: idx + 1,
+                        messageSizeBytes,
+                        messageSizeKb,
+                    });
+                }
+            }
+            let content = `# User Input ${idx + 1}\n\n`;
+            content += `**ResultId**: ${resultId}\n\n`;
+            content += message.content;
+            content += "\n";
+            await fs.writeFile(contentFilePath, content, "utf8");
+        }));
+    }
+    {
+        const messageNum = String(userMessages.length + 1).padStart(2, "0");
+        const contentFileName = `${messageNum}_llm_output.md`;
+        const contentFilePath = path.join(subfolderPath, contentFileName);
+        let content = "# Full Outline Result\n\n";
+        content += `**ResultId**: ${resultId}\n\n`;
+        if (result) {
+            content += "## Output Data\n\n";
+            content += "```json\n";
+            content += JSON.stringify(result, null, 2);
+            content += "\n```\n";
+        }
+        await fs.writeFile(contentFilePath, content, "utf8");
+    }
+}
+
 const BACKTEST_METHOD_NAME_RUN = "BacktestUtils.run";
 const BACKTEST_METHOD_NAME_BACKGROUND = "BacktestUtils.background";
 const BACKTEST_METHOD_NAME_STOP = "BacktestUtils.stop";
@@ -37546,6 +37658,7 @@ exports.commitPartialLoss = commitPartialLoss;
 exports.commitPartialProfit = commitPartialProfit;
 exports.commitTrailingStop = commitTrailingStop;
 exports.commitTrailingTake = commitTrailingTake;
+exports.dumpMessages = dumpMessages;
 exports.emitters = emitters;
 exports.formatPrice = formatPrice;
 exports.formatQuantity = formatQuantity;

package/build/index.mjs

@@ -2885,8 +2885,9 @@ class ExchangeConnectionService {
  *
  * For signals with partial closes:
  * - Calculates weighted PNL: Σ(percent_i × pnl_i) for each partial + (remaining% × final_pnl)
- * - Each partial close has its own fees and slippage
- * - Total fees = 2 × (number of partial closes + 1 final close) × CC_PERCENT_FEE
+ * - Each partial close has its own slippage
+ * - Open fee is charged once; close fees are proportional to each partial's size
+ * - Total fees = CC_PERCENT_FEE (open) + CC_PERCENT_FEE × 1 (closes sum to 100%) = 2 × CC_PERCENT_FEE
  *
  * Formula breakdown:
  * 1. Apply slippage to open/close prices (worse execution)
@@ -2933,7 +2934,8 @@ const toProfitLossDto = (signal, priceClose) => {
     // Calculate weighted PNL with partial closes
     if (signal._partial && signal._partial.length > 0) {
         let totalWeightedPnl = 0;
-        let totalFees = 0;
+        // Open fee is paid once for the whole position
+        let totalFees = GLOBAL_CONFIG.CC_PERCENT_FEE;
         // Calculate PNL for each partial close
         for (const partial of signal._partial) {
             const partialPercent = partial.percent;
@@ -2960,8 +2962,8 @@ const toProfitLossDto = (signal, priceClose) => {
             // Weight by percentage of position closed
             const weightedPnl = (partialPercent / 100) * partialPnl;
             totalWeightedPnl += weightedPnl;
-            // Each partial has fees for open + close (2 transactions)
-            totalFees += GLOBAL_CONFIG.CC_PERCENT_FEE * 2;
+            // Close fee is proportional to the size of this partial
+            totalFees += GLOBAL_CONFIG.CC_PERCENT_FEE * (partialPercent / 100);
         }
         // Calculate PNL for remaining position (if any)
         // Compute totalClosed from _partial array
@@ -2990,10 +2992,11 @@ const toProfitLossDto = (signal, priceClose) => {
             // Weight by remaining percentage
             const weightedRemainingPnl = (remainingPercent / 100) * remainingPnl;
             totalWeightedPnl += weightedRemainingPnl;
-            // Final close also has fees
-            totalFees += GLOBAL_CONFIG.CC_PERCENT_FEE * 2;
+            // Close fee is proportional to the remaining size
+            totalFees += GLOBAL_CONFIG.CC_PERCENT_FEE * (remainingPercent / 100);
         }
         // Subtract total fees from weighted PNL
+        // totalFees = CC_PERCENT_FEE (open) + CC_PERCENT_FEE × 1 (all closes sum to 100%) = 2 × CC_PERCENT_FEE
         const pnlPercentage = totalWeightedPnl - totalFees;
         return {
             pnlPercentage,
@@ -30213,6 +30216,115 @@ function listenStrategyCommitOnce(filterFn, fn) {
     return strategyCommitSubject.filter(filterFn).once(fn);
 }
 
+const WARN_KB = 30;
+const DUMP_MESSAGES_METHOD_NAME = "dump.dumpMessages";
+/**
+ * Dumps chat history and result data to markdown files in a structured directory.
+ *
+ * Creates a subfolder named after `resultId` inside `outputDir`.
+ * If the subfolder already exists, the function returns early without overwriting.
+ * Writes:
+ * - `00_system_prompt.md` — system messages and output data summary
+ * - `NN_user_message.md` — each user message as a separate file
+ * - `NN_llm_output.md` — final LLM output data
+ *
+ * Warns via logger if any user message exceeds 30 KB.
+ *
+ * @param resultId - Unique identifier for the result (used as subfolder name)
+ * @param history - Full chat history containing system, user, and assistant messages
+ * @param result - Structured output data to include in the dump
+ * @param outputDir - Base directory for output files (default: `./dump/strategy`)
+ * @returns Promise that resolves when all files are written
+ *
+ * @example
+ * ```typescript
+ * import { dumpMessages } from "backtest-kit";
+ *
+ * await dumpMessages("result-123", history, { profit: 42 });
+ * ```
+ */
+async function dumpMessages(resultId, history, result, outputDir = "./dump/strategy") {
+    bt.loggerService.info(DUMP_MESSAGES_METHOD_NAME, {
+        resultId,
+        outputDir,
+    });
+    // Extract system messages and system reminders from existing data
+    const systemMessages = history.filter((m) => m.role === "system");
+    const userMessages = history.filter((m) => m.role === "user");
+    const subfolderPath = path.join(outputDir, String(resultId));
+    try {
+        await fs__default.access(subfolderPath);
+        return;
+    }
+    catch {
+        await fs__default.mkdir(subfolderPath, { recursive: true });
+    }
+    {
+        let summary = "# Outline Result Summary\n";
+        {
+            summary += "\n";
+            summary += `**ResultId**: ${resultId}\n`;
+            summary += "\n";
+        }
+        if (result) {
+            summary += "## Output Data\n\n";
+            summary += "```json\n";
+            summary += JSON.stringify(result, null, 2);
+            summary += "\n```\n\n";
+        }
+        // Add system messages to summary
+        if (systemMessages.length > 0) {
+            summary += "## System Messages\n\n";
+            systemMessages.forEach((msg, idx) => {
+                summary += `### System Message ${idx + 1}\n\n`;
+                summary += msg.content;
+                summary += "\n";
+            });
+        }
+        const summaryFile = path.join(subfolderPath, "00_system_prompt.md");
+        await fs__default.writeFile(summaryFile, summary, "utf8");
+    }
+    {
+        await Promise.all(Array.from(userMessages.entries()).map(async ([idx, message]) => {
+            const messageNum = String(idx + 1).padStart(2, "0");
+            const contentFileName = `${messageNum}_user_message.md`;
+            const contentFilePath = path.join(subfolderPath, contentFileName);
+            {
+                const messageSizeBytes = Buffer.byteLength(message.content, "utf8");
+                const messageSizeKb = Math.floor(messageSizeBytes / 1024);
+                if (messageSizeKb > WARN_KB) {
+                    console.warn(`User message ${idx + 1} is ${messageSizeBytes} bytes (${messageSizeKb}kb), which exceeds warning limit`);
+                    bt.loggerService.warn(DUMP_MESSAGES_METHOD_NAME, {
+                        resultId,
+                        messageIndex: idx + 1,
+                        messageSizeBytes,
+                        messageSizeKb,
+                    });
+                }
+            }
+            let content = `# User Input ${idx + 1}\n\n`;
+            content += `**ResultId**: ${resultId}\n\n`;
+            content += message.content;
+            content += "\n";
+            await fs__default.writeFile(contentFilePath, content, "utf8");
+        }));
+    }
+    {
+        const messageNum = String(userMessages.length + 1).padStart(2, "0");
+        const contentFileName = `${messageNum}_llm_output.md`;
+        const contentFilePath = path.join(subfolderPath, contentFileName);
+        let content = "# Full Outline Result\n\n";
+        content += `**ResultId**: ${resultId}\n\n`;
+        if (result) {
+            content += "## Output Data\n\n";
+            content += "```json\n";
+            content += JSON.stringify(result, null, 2);
+            content += "\n```\n";
+        }
+        await fs__default.writeFile(contentFilePath, content, "utf8");
+    }
+}
+
 const BACKTEST_METHOD_NAME_RUN = "BacktestUtils.run";
 const BACKTEST_METHOD_NAME_BACKGROUND = "BacktestUtils.background";
 const BACKTEST_METHOD_NAME_STOP = "BacktestUtils.stop";
@@ -37472,4 +37584,4 @@ const set = (object, path, value) => {
     }
 };
 
-export { ActionBase, Backtest, Breakeven, Cache, Constant, Exchange, ExecutionContextService, Heat, Live, Markdown, MarkdownFileBase, MarkdownFolderBase, MethodContextService, Notification, NotificationBacktest, NotificationLive, Partial, Performance, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistNotificationAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PersistStorageAdapter, PositionSize, Report, ReportBase, Risk, Schedule, Storage, StorageBacktest, StorageLive, Strategy, Walker, addActionSchema, addExchangeSchema, addFrameSchema, addRiskSchema, addSizingSchema, addStrategySchema, addWalkerSchema, alignToInterval, checkCandles, commitActivateScheduled, commitBreakeven, commitCancelScheduled, commitClosePending, commitPartialLoss, commitPartialProfit, commitTrailingStop, commitTrailingTake, emitters, formatPrice, formatQuantity, get, getActionSchema, getAveragePrice, getBacktestTimeframe, getCandles, getColumns, getConfig, getContext, getDate, getDefaultColumns, getDefaultConfig, getExchangeSchema, getFrameSchema, getMode, getNextCandles, getOrderBook, getRawCandles, getRiskSchema, getSizingSchema, getStrategySchema, getSymbol, getWalkerSchema, hasTradeContext, backtest as lib, listExchangeSchema, listFrameSchema, listRiskSchema, listSizingSchema, listStrategySchema, listWalkerSchema, listenActivePing, listenActivePingOnce, listenBacktestProgress, listenBreakevenAvailable, listenBreakevenAvailableOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenPartialLossAvailable, listenPartialLossAvailableOnce, listenPartialProfitAvailable, listenPartialProfitAvailableOnce, listenPerformance, listenRisk, listenRiskOnce, listenSchedulePing, listenSchedulePingOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenStrategyCommit, listenStrategyCommitOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, overrideActionSchema, overrideExchangeSchema, overrideFrameSchema, overrideRiskSchema, overrideSizingSchema, overrideStrategySchema, overrideWalkerSchema, parseArgs, roundTicks, set, setColumns, setConfig, setLogger, stopStrategy, validate, waitForCandle, warmCandles };
+export { ActionBase, Backtest, Breakeven, Cache, Constant, Exchange, ExecutionContextService, Heat, Live, Markdown, MarkdownFileBase, MarkdownFolderBase, MethodContextService, Notification, NotificationBacktest, NotificationLive, Partial, Performance, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistNotificationAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PersistStorageAdapter, PositionSize, Report, ReportBase, Risk, Schedule, Storage, StorageBacktest, StorageLive, Strategy, Walker, addActionSchema, addExchangeSchema, addFrameSchema, addRiskSchema, addSizingSchema, addStrategySchema, addWalkerSchema, alignToInterval, checkCandles, commitActivateScheduled, commitBreakeven, commitCancelScheduled, commitClosePending, commitPartialLoss, commitPartialProfit, commitTrailingStop, commitTrailingTake, dumpMessages, emitters, formatPrice, formatQuantity, get, getActionSchema, getAveragePrice, getBacktestTimeframe, getCandles, getColumns, getConfig, getContext, getDate, getDefaultColumns, getDefaultConfig, getExchangeSchema, getFrameSchema, getMode, getNextCandles, getOrderBook, getRawCandles, getRiskSchema, getSizingSchema, getStrategySchema, getSymbol, getWalkerSchema, hasTradeContext, backtest as lib, listExchangeSchema, listFrameSchema, listRiskSchema, listSizingSchema, listStrategySchema, listWalkerSchema, listenActivePing, listenActivePingOnce, listenBacktestProgress, listenBreakevenAvailable, listenBreakevenAvailableOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenPartialLossAvailable, listenPartialLossAvailableOnce, listenPartialProfitAvailable, listenPartialProfitAvailableOnce, listenPerformance, listenRisk, listenRiskOnce, listenSchedulePing, listenSchedulePingOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenStrategyCommit, listenStrategyCommitOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, overrideActionSchema, overrideExchangeSchema, overrideFrameSchema, overrideRiskSchema, overrideSizingSchema, overrideStrategySchema, overrideWalkerSchema, parseArgs, roundTicks, set, setColumns, setConfig, setLogger, stopStrategy, validate, waitForCandle, warmCandles };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backtest-kit",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "A TypeScript library for trading system backtest",
   "author": {
     "name": "Petr Tripolsky",

package/types.d.ts

@@ -6739,6 +6739,55 @@ declare function getRawCandles(symbol: string, interval: CandleInterval, limit?:
  */
 declare function getNextCandles(symbol: string, interval: CandleInterval, limit: number): Promise<ICandleData[]>;
 
+/** Unique identifier for a dump result. Can be a string or numeric ID. */
+type ResultId = string | number;
+/** Role of the message sender in LLM chat history. */
+type BaseRole = "assistant" | "system" | "user";
+/**
+ * A single message in the chat history.
+ * Used to represent system instructions, user input, or LLM responses.
+ */
+interface Message<Role extends BaseRole = BaseRole> {
+    /**
+     * The sender of the message.
+     * - "system": System instructions and context
+     * - "user": User input and questions
+     * - "assistant": LLM responses
+     */
+    role: Role;
+    /**
+     * The text content of the message.
+     * Contains the actual message text sent or received.
+     */
+    content: string;
+}
+/**
+ * Dumps chat history and result data to markdown files in a structured directory.
+ *
+ * Creates a subfolder named after `resultId` inside `outputDir`.
+ * If the subfolder already exists, the function returns early without overwriting.
+ * Writes:
+ * - `00_system_prompt.md` — system messages and output data summary
+ * - `NN_user_message.md` — each user message as a separate file
+ * - `NN_llm_output.md` — final LLM output data
+ *
+ * Warns via logger if any user message exceeds 30 KB.
+ *
+ * @param resultId - Unique identifier for the result (used as subfolder name)
+ * @param history - Full chat history containing system, user, and assistant messages
+ * @param result - Structured output data to include in the dump
+ * @param outputDir - Base directory for output files (default: `./dump/strategy`)
+ * @returns Promise that resolves when all files are written
+ *
+ * @example
+ * ```typescript
+ * import { dumpMessages } from "backtest-kit";
+ *
+ * await dumpMessages("result-123", history, { profit: 42 });
+ * ```
+ */
+declare function dumpMessages<Data extends object = any>(resultId: ResultId, history: Message[], result: Data, outputDir?: string): Promise<void>;
+
 /**
  * Portfolio heatmap statistics for a single symbol.
  * Aggregated metrics across all strategies for one trading pair.
@@ -20832,4 +20881,4 @@ declare const backtest: {
     loggerService: LoggerService;
 };
 
-export { ActionBase, type ActivateScheduledCommit, type ActivateScheduledCommitNotification, type ActivePingContract, Backtest, type BacktestStatisticsModel, Breakeven, type BreakevenAvailableNotification, type BreakevenCommit, type BreakevenCommitNotification, type BreakevenContract, type BreakevenData, Cache, type CancelScheduledCommit, type CandleData, type CandleInterval, type ClosePendingCommit, type ColumnConfig, type ColumnModel, Constant, type CriticalErrorNotification, type DoneContract, type EntityId, Exchange, ExecutionContextService, type FrameInterval, type GlobalConfig, Heat, type HeatmapStatisticsModel, type IActionSchema, type IActivateScheduledCommitRow, type IBidData, type IBreakevenCommitRow, type ICandleData, type ICommitRow, type IExchangeSchema, type IFrameSchema, type IHeatmapRow, type IMarkdownDumpOptions, type INotificationUtils, type IOrderBookData, type IPartialLossCommitRow, type IPartialProfitCommitRow, type IPersistBase, type IPositionSizeATRParams, type IPositionSizeFixedPercentageParams, type IPositionSizeKellyParams, type IPublicAction, type IPublicSignalRow, type IReportDumpOptions, type IRiskActivePosition, type IRiskCheckArgs, type IRiskSchema, type IRiskSignalRow, type IRiskValidation, type IRiskValidationFn, type IRiskValidationPayload, type IScheduledSignalCancelRow, type IScheduledSignalRow, type ISignalDto, type ISignalRow, type ISizingCalculateParams, type ISizingCalculateParamsATR, type ISizingCalculateParamsFixedPercentage, type ISizingCalculateParamsKelly, type ISizingParams, type ISizingParamsATR, type ISizingParamsFixedPercentage, type ISizingParamsKelly, type ISizingSchema, type ISizingSchemaATR, type ISizingSchemaFixedPercentage, type ISizingSchemaKelly, type IStorageSignalRow, type IStorageUtils, type IStrategyPnL, type IStrategyResult, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultCancelled, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, type IStrategyTickResultScheduled, type IStrategyTickResultWaiting, type ITrailingStopCommitRow, type ITrailingTakeCommitRow, type IWalkerResults, type IWalkerSchema, type IWalkerStrategyResult, type InfoErrorNotification, Live, type LiveStatisticsModel, Markdown, MarkdownFileBase, MarkdownFolderBase, type MarkdownName, MethodContextService, type MetricStats, Notification, NotificationBacktest, type NotificationData, NotificationLive, type NotificationModel, Partial$1 as Partial, type PartialData, type PartialEvent, type PartialLossAvailableNotification, type PartialLossCommit, type PartialLossCommitNotification, type PartialLossContract, type PartialProfitAvailableNotification, type PartialProfitCommit, type PartialProfitCommitNotification, type PartialProfitContract, type PartialStatisticsModel, Performance, type PerformanceContract, type PerformanceMetricType, type PerformanceStatisticsModel, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistNotificationAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PersistStorageAdapter, PositionSize, type ProgressBacktestContract, type ProgressWalkerContract, Report, ReportBase, type ReportName, Risk, type RiskContract, type RiskData, type RiskEvent, type RiskRejectionNotification, type RiskStatisticsModel, Schedule, type ScheduleData, type SchedulePingContract, type ScheduleStatisticsModel, type ScheduledEvent, type SignalCancelledNotification, type SignalClosedNotification, type SignalData, type SignalInterval, type SignalOpenedNotification, type SignalScheduledNotification, Storage, StorageBacktest, type StorageData, StorageLive, Strategy, type StrategyActionType, type StrategyCancelReason, type StrategyCloseReason, type StrategyCommitContract, type StrategyEvent, type StrategyStatisticsModel, type TMarkdownBase, type TNotificationUtilsCtor, type TPersistBase, type TPersistBaseCtor, type TReportBase, type TStorageUtilsCtor, type TickEvent, type TrailingStopCommit, type TrailingStopCommitNotification, type TrailingTakeCommit, type TrailingTakeCommitNotification, type ValidationErrorNotification, Walker, type WalkerCompleteContract, type WalkerContract, type WalkerMetric, type SignalData$1 as WalkerSignalData, type WalkerStatisticsModel, addActionSchema, addExchangeSchema, addFrameSchema, addRiskSchema, addSizingSchema, addStrategySchema, addWalkerSchema, alignToInterval, checkCandles, commitActivateScheduled, commitBreakeven, commitCancelScheduled, commitClosePending, commitPartialLoss, commitPartialProfit, commitTrailingStop, commitTrailingTake, emitters, formatPrice, formatQuantity, get, getActionSchema, getAveragePrice, getBacktestTimeframe, getCandles, getColumns, getConfig, getContext, getDate, getDefaultColumns, getDefaultConfig, getExchangeSchema, getFrameSchema, getMode, getNextCandles, getOrderBook, getRawCandles, getRiskSchema, getSizingSchema, getStrategySchema, getSymbol, getWalkerSchema, hasTradeContext, backtest as lib, listExchangeSchema, listFrameSchema, listRiskSchema, listSizingSchema, listStrategySchema, listWalkerSchema, listenActivePing, listenActivePingOnce, listenBacktestProgress, listenBreakevenAvailable, listenBreakevenAvailableOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenPartialLossAvailable, listenPartialLossAvailableOnce, listenPartialProfitAvailable, listenPartialProfitAvailableOnce, listenPerformance, listenRisk, listenRiskOnce, listenSchedulePing, listenSchedulePingOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenStrategyCommit, listenStrategyCommitOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, overrideActionSchema, overrideExchangeSchema, overrideFrameSchema, overrideRiskSchema, overrideSizingSchema, overrideStrategySchema, overrideWalkerSchema, parseArgs, roundTicks, set, setColumns, setConfig, setLogger, stopStrategy, validate, waitForCandle, warmCandles };
+export { ActionBase, type ActivateScheduledCommit, type ActivateScheduledCommitNotification, type ActivePingContract, Backtest, type BacktestStatisticsModel, Breakeven, type BreakevenAvailableNotification, type BreakevenCommit, type BreakevenCommitNotification, type BreakevenContract, type BreakevenData, Cache, type CancelScheduledCommit, type CandleData, type CandleInterval, type ClosePendingCommit, type ColumnConfig, type ColumnModel, Constant, type CriticalErrorNotification, type DoneContract, type EntityId, Exchange, ExecutionContextService, type FrameInterval, type GlobalConfig, Heat, type HeatmapStatisticsModel, type IActionSchema, type IActivateScheduledCommitRow, type IBidData, type IBreakevenCommitRow, type ICandleData, type ICommitRow, type IExchangeSchema, type IFrameSchema, type IHeatmapRow, type IMarkdownDumpOptions, type INotificationUtils, type IOrderBookData, type IPartialLossCommitRow, type IPartialProfitCommitRow, type IPersistBase, type IPositionSizeATRParams, type IPositionSizeFixedPercentageParams, type IPositionSizeKellyParams, type IPublicAction, type IPublicSignalRow, type IReportDumpOptions, type IRiskActivePosition, type IRiskCheckArgs, type IRiskSchema, type IRiskSignalRow, type IRiskValidation, type IRiskValidationFn, type IRiskValidationPayload, type IScheduledSignalCancelRow, type IScheduledSignalRow, type ISignalDto, type ISignalRow, type ISizingCalculateParams, type ISizingCalculateParamsATR, type ISizingCalculateParamsFixedPercentage, type ISizingCalculateParamsKelly, type ISizingParams, type ISizingParamsATR, type ISizingParamsFixedPercentage, type ISizingParamsKelly, type ISizingSchema, type ISizingSchemaATR, type ISizingSchemaFixedPercentage, type ISizingSchemaKelly, type IStorageSignalRow, type IStorageUtils, type IStrategyPnL, type IStrategyResult, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultCancelled, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, type IStrategyTickResultScheduled, type IStrategyTickResultWaiting, type ITrailingStopCommitRow, type ITrailingTakeCommitRow, type IWalkerResults, type IWalkerSchema, type IWalkerStrategyResult, type InfoErrorNotification, Live, type LiveStatisticsModel, Markdown, MarkdownFileBase, MarkdownFolderBase, type MarkdownName, MethodContextService, type MetricStats, Notification, NotificationBacktest, type NotificationData, NotificationLive, type NotificationModel, Partial$1 as Partial, type PartialData, type PartialEvent, type PartialLossAvailableNotification, type PartialLossCommit, type PartialLossCommitNotification, type PartialLossContract, type PartialProfitAvailableNotification, type PartialProfitCommit, type PartialProfitCommitNotification, type PartialProfitContract, type PartialStatisticsModel, Performance, type PerformanceContract, type PerformanceMetricType, type PerformanceStatisticsModel, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistNotificationAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PersistStorageAdapter, PositionSize, type ProgressBacktestContract, type ProgressWalkerContract, Report, ReportBase, type ReportName, Risk, type RiskContract, type RiskData, type RiskEvent, type RiskRejectionNotification, type RiskStatisticsModel, Schedule, type ScheduleData, type SchedulePingContract, type ScheduleStatisticsModel, type ScheduledEvent, type SignalCancelledNotification, type SignalClosedNotification, type SignalData, type SignalInterval, type SignalOpenedNotification, type SignalScheduledNotification, Storage, StorageBacktest, type StorageData, StorageLive, Strategy, type StrategyActionType, type StrategyCancelReason, type StrategyCloseReason, type StrategyCommitContract, type StrategyEvent, type StrategyStatisticsModel, type TMarkdownBase, type TNotificationUtilsCtor, type TPersistBase, type TPersistBaseCtor, type TReportBase, type TStorageUtilsCtor, type TickEvent, type TrailingStopCommit, type TrailingStopCommitNotification, type TrailingTakeCommit, type TrailingTakeCommitNotification, type ValidationErrorNotification, Walker, type WalkerCompleteContract, type WalkerContract, type WalkerMetric, type SignalData$1 as WalkerSignalData, type WalkerStatisticsModel, addActionSchema, addExchangeSchema, addFrameSchema, addRiskSchema, addSizingSchema, addStrategySchema, addWalkerSchema, alignToInterval, checkCandles, commitActivateScheduled, commitBreakeven, commitCancelScheduled, commitClosePending, commitPartialLoss, commitPartialProfit, commitTrailingStop, commitTrailingTake, dumpMessages, emitters, formatPrice, formatQuantity, get, getActionSchema, getAveragePrice, getBacktestTimeframe, getCandles, getColumns, getConfig, getContext, getDate, getDefaultColumns, getDefaultConfig, getExchangeSchema, getFrameSchema, getMode, getNextCandles, getOrderBook, getRawCandles, getRiskSchema, getSizingSchema, getStrategySchema, getSymbol, getWalkerSchema, hasTradeContext, backtest as lib, listExchangeSchema, listFrameSchema, listRiskSchema, listSizingSchema, listStrategySchema, listWalkerSchema, listenActivePing, listenActivePingOnce, listenBacktestProgress, listenBreakevenAvailable, listenBreakevenAvailableOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenPartialLossAvailable, listenPartialLossAvailableOnce, listenPartialProfitAvailable, listenPartialProfitAvailableOnce, listenPerformance, listenRisk, listenRiskOnce, listenSchedulePing, listenSchedulePingOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenStrategyCommit, listenStrategyCommitOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, overrideActionSchema, overrideExchangeSchema, overrideFrameSchema, overrideRiskSchema, overrideSizingSchema, overrideStrategySchema, overrideWalkerSchema, parseArgs, roundTicks, set, setColumns, setConfig, setLogger, stopStrategy, validate, waitForCandle, warmCandles };