backtest-kit 1.4.11 → 1.4.12

package/build/index.cjs

@@ -7,6 +7,7 @@ var fs = require('fs/promises');
 var path = require('path');
 var crypto = require('crypto');
 var os = require('os');
+var fs$1 = require('fs');
 
 const GLOBAL_CONFIG = {
     /**
@@ -162,6 +163,7 @@ const markdownServices$1 = {
     walkerMarkdownService: Symbol('walkerMarkdownService'),
     heatMarkdownService: Symbol('heatMarkdownService'),
     partialMarkdownService: Symbol('partialMarkdownService'),
+    outlineMarkdownService: Symbol('outlineMarkdownService'),
 };
 const validationServices$1 = {
     exchangeValidationService: Symbol('exchangeValidationService'),
@@ -10906,6 +10908,145 @@ class PartialGlobalService {
     }
 }
 
+/**
+ * Warning threshold for message size in kilobytes.
+ * Messages exceeding this size trigger console warnings.
+ */
+const WARN_KB = 100;
+/**
+ * Internal function for dumping signal data to markdown files.
+ * Creates a directory structure with system prompts, user messages, and LLM output.
+ *
+ * @param signalId - Unique identifier for the result
+ * @param history - Array of message models from LLM conversation
+ * @param signal - Signal DTO with trade parameters
+ * @param outputDir - Output directory path (default: "./dump/strategy")
+ * @returns Promise that resolves when all files are written
+ */
+const DUMP_SIGNAL_FN = async (signalId, history, signal, outputDir = "./dump/strategy") => {
+    // 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(signalId));
+    try {
+        await fs$1.promises.access(subfolderPath);
+        return;
+    }
+    catch {
+        await fs$1.promises.mkdir(subfolderPath, { recursive: true });
+    }
+    {
+        let summary = "# Outline Result Summary\n";
+        {
+            summary += "\n";
+            summary += `**ResultId**: ${String(signalId)}\n`;
+            summary += "\n";
+        }
+        if (signal) {
+            summary += "## Output Data\n\n";
+            summary += "```json\n";
+            summary += JSON.stringify(signal, 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$1.promises.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`);
+                }
+            }
+            let content = `# User Input ${idx + 1}\n\n`;
+            content += `**ResultId**: ${String(signalId)}\n\n`;
+            content += message.content;
+            content += "\n";
+            await fs$1.promises.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**: ${String(signalId)}\n\n`;
+        if (signal) {
+            content += "## Output Data\n\n";
+            content += "```json\n";
+            content += JSON.stringify(signal, null, 2);
+            content += "\n```\n";
+        }
+        await fs$1.promises.writeFile(contentFilePath, content, "utf8");
+    }
+};
+/**
+ * Service for generating markdown documentation from LLM outline results.
+ * Used by AI Strategy Optimizer to save debug logs and conversation history.
+ *
+ * Creates directory structure:
+ * - ./dump/strategy/{signalId}/00_system_prompt.md - System messages and output data
+ * - ./dump/strategy/{signalId}/01_user_message.md - First user input
+ * - ./dump/strategy/{signalId}/02_user_message.md - Second user input
+ * - ./dump/strategy/{signalId}/XX_llm_output.md - Final LLM output
+ */
+class OutlineMarkdownService {
+    constructor() {
+        /** Logger service injected via DI */
+        this.loggerService = inject(TYPES.loggerService);
+        /**
+         * Dumps signal data and conversation history to markdown files.
+         * Skips if directory already exists to avoid overwriting previous results.
+         *
+         * Generated files:
+         * - 00_system_prompt.md - System messages and output summary
+         * - XX_user_message.md - Each user message in separate file (numbered)
+         * - XX_llm_output.md - Final LLM output with signal data
+         *
+         * @param signalId - Unique identifier for the result (used as directory name)
+         * @param history - Array of message models from LLM conversation
+         * @param signal - Signal DTO with trade parameters (priceOpen, TP, SL, etc.)
+         * @param outputDir - Output directory path (default: "./dump/strategy")
+         * @returns Promise that resolves when all files are written
+         *
+         * @example
+         * ```typescript
+         * await outlineService.dumpSignal(
+         *   "strategy-1",
+         *   conversationHistory,
+         *   { position: "long", priceTakeProfit: 51000, priceStopLoss: 49000, minuteEstimatedTime: 60 }
+         * );
+         * // Creates: ./dump/strategy/strategy-1/00_system_prompt.md
+         * //          ./dump/strategy/strategy-1/01_user_message.md
+         * //          ./dump/strategy/strategy-1/02_llm_output.md
+         * ```
+         */
+        this.dumpSignal = async (signalId, history, signal, outputDir = "./dump/strategy") => {
+            this.loggerService.log("outlineMarkdownService dumpSignal", {
+                signalId,
+                history,
+                signal,
+                outputDir,
+            });
+            return await DUMP_SIGNAL_FN(signalId, history, signal, outputDir);
+        };
+    }
+}
+
 {
     provide(TYPES.loggerService, () => new LoggerService());
 }
@@ -10963,6 +11104,7 @@ class PartialGlobalService {
     provide(TYPES.walkerMarkdownService, () => new WalkerMarkdownService());
     provide(TYPES.heatMarkdownService, () => new HeatMarkdownService());
     provide(TYPES.partialMarkdownService, () => new PartialMarkdownService());
+    provide(TYPES.outlineMarkdownService, () => new OutlineMarkdownService());
 }
 {
     provide(TYPES.exchangeValidationService, () => new ExchangeValidationService());
@@ -11034,6 +11176,7 @@ const markdownServices = {
     walkerMarkdownService: inject(TYPES.walkerMarkdownService),
     heatMarkdownService: inject(TYPES.heatMarkdownService),
     partialMarkdownService: inject(TYPES.partialMarkdownService),
+    outlineMarkdownService: inject(TYPES.outlineMarkdownService),
 };
 const validationServices = {
     exchangeValidationService: inject(TYPES.exchangeValidationService),
@@ -12700,6 +12843,83 @@ async function getMode() {
     return bt ? "backtest" : "live";
 }
 
+const DUMP_SIGNAL_METHOD_NAME = "dump.dumpSignal";
+/**
+ * Dumps signal data and LLM conversation history to markdown files.
+ * Used by AI-powered strategies to save debug logs for analysis.
+ *
+ * Creates a directory structure with:
+ * - 00_system_prompt.md - System messages and output summary
+ * - XX_user_message.md - Each user message in separate file (numbered)
+ * - XX_llm_output.md - Final LLM output with signal data
+ *
+ * Skips if directory already exists to avoid overwriting previous results.
+ *
+ * @param signalId - Unique identifier for the result (used as directory name, e.g., UUID)
+ * @param history - Array of message models from LLM conversation
+ * @param signal - Signal DTO returned by LLM (position, priceOpen, TP, SL, etc.)
+ * @param outputDir - Output directory path (default: "./dump/strategy")
+ * @returns Promise that resolves when all files are written
+ *
+ * @example
+ * ```typescript
+ * import { dumpSignal, getCandles } from "backtest-kit";
+ * import { v4 as uuid } from "uuid";
+ *
+ * addStrategy({
+ *   strategyName: "llm-strategy",
+ *   interval: "5m",
+ *   getSignal: async (symbol) => {
+ *     const messages = [];
+ *
+ *     // Build multi-timeframe analysis conversation
+ *     const candles1h = await getCandles(symbol, "1h", 24);
+ *     messages.push(
+ *       { role: "user", content: `Analyze 1h trend:\n${formatCandles(candles1h)}` },
+ *       { role: "assistant", content: "Trend analyzed" }
+ *     );
+ *
+ *     const candles5m = await getCandles(symbol, "5m", 24);
+ *     messages.push(
+ *       { role: "user", content: `Analyze 5m structure:\n${formatCandles(candles5m)}` },
+ *       { role: "assistant", content: "Structure analyzed" }
+ *     );
+ *
+ *     // Request signal
+ *     messages.push({
+ *       role: "user",
+ *       content: "Generate trading signal. Use position: 'wait' if uncertain."
+ *     });
+ *
+ *     const resultId = uuid();
+ *     const signal = await llmRequest(messages);
+ *
+ *     // Save conversation and result for debugging
+ *     await dumpSignal(resultId, messages, signal);
+ *
+ *     return signal;
+ *   }
+ * });
+ *
+ * // Creates: ./dump/strategy/{uuid}/00_system_prompt.md
+ * //          ./dump/strategy/{uuid}/01_user_message.md (1h analysis)
+ * //          ./dump/strategy/{uuid}/02_assistant_message.md
+ * //          ./dump/strategy/{uuid}/03_user_message.md (5m analysis)
+ * //          ./dump/strategy/{uuid}/04_assistant_message.md
+ * //          ./dump/strategy/{uuid}/05_user_message.md (signal request)
+ * //          ./dump/strategy/{uuid}/06_llm_output.md (final signal)
+ * ```
+ */
+async function dumpSignal(signalId, history, signal, outputDir = "./dump/strategy") {
+    backtest$1.loggerService.info(DUMP_SIGNAL_METHOD_NAME, {
+        signalId,
+        history,
+        signal,
+        outputDir,
+    });
+    return await backtest$1.outlineMarkdownService.dumpSignal(signalId, history, signal, outputDir);
+}
+
 const BACKTEST_METHOD_NAME_RUN = "BacktestUtils.run";
 const BACKTEST_METHOD_NAME_BACKGROUND = "BacktestUtils.background";
 const BACKTEST_METHOD_NAME_GET_REPORT = "BacktestUtils.getReport";
@@ -14168,6 +14388,7 @@ exports.addRisk = addRisk;
 exports.addSizing = addSizing;
 exports.addStrategy = addStrategy;
 exports.addWalker = addWalker;
+exports.dumpSignal = dumpSignal;
 exports.emitters = emitters;
 exports.formatPrice = formatPrice;
 exports.formatQuantity = formatQuantity;

package/build/index.mjs

@@ -5,6 +5,7 @@ import fs, { mkdir, writeFile } from 'fs/promises';
 import path, { join } from 'path';
 import crypto from 'crypto';
 import os from 'os';
+import { promises } from 'fs';
 
 const GLOBAL_CONFIG = {
     /**
@@ -160,6 +161,7 @@ const markdownServices$1 = {
     walkerMarkdownService: Symbol('walkerMarkdownService'),
     heatMarkdownService: Symbol('heatMarkdownService'),
     partialMarkdownService: Symbol('partialMarkdownService'),
+    outlineMarkdownService: Symbol('outlineMarkdownService'),
 };
 const validationServices$1 = {
     exchangeValidationService: Symbol('exchangeValidationService'),
@@ -10904,6 +10906,145 @@ class PartialGlobalService {
     }
 }
 
+/**
+ * Warning threshold for message size in kilobytes.
+ * Messages exceeding this size trigger console warnings.
+ */
+const WARN_KB = 100;
+/**
+ * Internal function for dumping signal data to markdown files.
+ * Creates a directory structure with system prompts, user messages, and LLM output.
+ *
+ * @param signalId - Unique identifier for the result
+ * @param history - Array of message models from LLM conversation
+ * @param signal - Signal DTO with trade parameters
+ * @param outputDir - Output directory path (default: "./dump/strategy")
+ * @returns Promise that resolves when all files are written
+ */
+const DUMP_SIGNAL_FN = async (signalId, history, signal, outputDir = "./dump/strategy") => {
+    // 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(signalId));
+    try {
+        await promises.access(subfolderPath);
+        return;
+    }
+    catch {
+        await promises.mkdir(subfolderPath, { recursive: true });
+    }
+    {
+        let summary = "# Outline Result Summary\n";
+        {
+            summary += "\n";
+            summary += `**ResultId**: ${String(signalId)}\n`;
+            summary += "\n";
+        }
+        if (signal) {
+            summary += "## Output Data\n\n";
+            summary += "```json\n";
+            summary += JSON.stringify(signal, 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 promises.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`);
+                }
+            }
+            let content = `# User Input ${idx + 1}\n\n`;
+            content += `**ResultId**: ${String(signalId)}\n\n`;
+            content += message.content;
+            content += "\n";
+            await promises.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**: ${String(signalId)}\n\n`;
+        if (signal) {
+            content += "## Output Data\n\n";
+            content += "```json\n";
+            content += JSON.stringify(signal, null, 2);
+            content += "\n```\n";
+        }
+        await promises.writeFile(contentFilePath, content, "utf8");
+    }
+};
+/**
+ * Service for generating markdown documentation from LLM outline results.
+ * Used by AI Strategy Optimizer to save debug logs and conversation history.
+ *
+ * Creates directory structure:
+ * - ./dump/strategy/{signalId}/00_system_prompt.md - System messages and output data
+ * - ./dump/strategy/{signalId}/01_user_message.md - First user input
+ * - ./dump/strategy/{signalId}/02_user_message.md - Second user input
+ * - ./dump/strategy/{signalId}/XX_llm_output.md - Final LLM output
+ */
+class OutlineMarkdownService {
+    constructor() {
+        /** Logger service injected via DI */
+        this.loggerService = inject(TYPES.loggerService);
+        /**
+         * Dumps signal data and conversation history to markdown files.
+         * Skips if directory already exists to avoid overwriting previous results.
+         *
+         * Generated files:
+         * - 00_system_prompt.md - System messages and output summary
+         * - XX_user_message.md - Each user message in separate file (numbered)
+         * - XX_llm_output.md - Final LLM output with signal data
+         *
+         * @param signalId - Unique identifier for the result (used as directory name)
+         * @param history - Array of message models from LLM conversation
+         * @param signal - Signal DTO with trade parameters (priceOpen, TP, SL, etc.)
+         * @param outputDir - Output directory path (default: "./dump/strategy")
+         * @returns Promise that resolves when all files are written
+         *
+         * @example
+         * ```typescript
+         * await outlineService.dumpSignal(
+         *   "strategy-1",
+         *   conversationHistory,
+         *   { position: "long", priceTakeProfit: 51000, priceStopLoss: 49000, minuteEstimatedTime: 60 }
+         * );
+         * // Creates: ./dump/strategy/strategy-1/00_system_prompt.md
+         * //          ./dump/strategy/strategy-1/01_user_message.md
+         * //          ./dump/strategy/strategy-1/02_llm_output.md
+         * ```
+         */
+        this.dumpSignal = async (signalId, history, signal, outputDir = "./dump/strategy") => {
+            this.loggerService.log("outlineMarkdownService dumpSignal", {
+                signalId,
+                history,
+                signal,
+                outputDir,
+            });
+            return await DUMP_SIGNAL_FN(signalId, history, signal, outputDir);
+        };
+    }
+}
+
 {
     provide(TYPES.loggerService, () => new LoggerService());
 }
@@ -10961,6 +11102,7 @@ class PartialGlobalService {
     provide(TYPES.walkerMarkdownService, () => new WalkerMarkdownService());
     provide(TYPES.heatMarkdownService, () => new HeatMarkdownService());
     provide(TYPES.partialMarkdownService, () => new PartialMarkdownService());
+    provide(TYPES.outlineMarkdownService, () => new OutlineMarkdownService());
 }
 {
     provide(TYPES.exchangeValidationService, () => new ExchangeValidationService());
@@ -11032,6 +11174,7 @@ const markdownServices = {
     walkerMarkdownService: inject(TYPES.walkerMarkdownService),
     heatMarkdownService: inject(TYPES.heatMarkdownService),
     partialMarkdownService: inject(TYPES.partialMarkdownService),
+    outlineMarkdownService: inject(TYPES.outlineMarkdownService),
 };
 const validationServices = {
     exchangeValidationService: inject(TYPES.exchangeValidationService),
@@ -12698,6 +12841,83 @@ async function getMode() {
     return bt ? "backtest" : "live";
 }
 
+const DUMP_SIGNAL_METHOD_NAME = "dump.dumpSignal";
+/**
+ * Dumps signal data and LLM conversation history to markdown files.
+ * Used by AI-powered strategies to save debug logs for analysis.
+ *
+ * Creates a directory structure with:
+ * - 00_system_prompt.md - System messages and output summary
+ * - XX_user_message.md - Each user message in separate file (numbered)
+ * - XX_llm_output.md - Final LLM output with signal data
+ *
+ * Skips if directory already exists to avoid overwriting previous results.
+ *
+ * @param signalId - Unique identifier for the result (used as directory name, e.g., UUID)
+ * @param history - Array of message models from LLM conversation
+ * @param signal - Signal DTO returned by LLM (position, priceOpen, TP, SL, etc.)
+ * @param outputDir - Output directory path (default: "./dump/strategy")
+ * @returns Promise that resolves when all files are written
+ *
+ * @example
+ * ```typescript
+ * import { dumpSignal, getCandles } from "backtest-kit";
+ * import { v4 as uuid } from "uuid";
+ *
+ * addStrategy({
+ *   strategyName: "llm-strategy",
+ *   interval: "5m",
+ *   getSignal: async (symbol) => {
+ *     const messages = [];
+ *
+ *     // Build multi-timeframe analysis conversation
+ *     const candles1h = await getCandles(symbol, "1h", 24);
+ *     messages.push(
+ *       { role: "user", content: `Analyze 1h trend:\n${formatCandles(candles1h)}` },
+ *       { role: "assistant", content: "Trend analyzed" }
+ *     );
+ *
+ *     const candles5m = await getCandles(symbol, "5m", 24);
+ *     messages.push(
+ *       { role: "user", content: `Analyze 5m structure:\n${formatCandles(candles5m)}` },
+ *       { role: "assistant", content: "Structure analyzed" }
+ *     );
+ *
+ *     // Request signal
+ *     messages.push({
+ *       role: "user",
+ *       content: "Generate trading signal. Use position: 'wait' if uncertain."
+ *     });
+ *
+ *     const resultId = uuid();
+ *     const signal = await llmRequest(messages);
+ *
+ *     // Save conversation and result for debugging
+ *     await dumpSignal(resultId, messages, signal);
+ *
+ *     return signal;
+ *   }
+ * });
+ *
+ * // Creates: ./dump/strategy/{uuid}/00_system_prompt.md
+ * //          ./dump/strategy/{uuid}/01_user_message.md (1h analysis)
+ * //          ./dump/strategy/{uuid}/02_assistant_message.md
+ * //          ./dump/strategy/{uuid}/03_user_message.md (5m analysis)
+ * //          ./dump/strategy/{uuid}/04_assistant_message.md
+ * //          ./dump/strategy/{uuid}/05_user_message.md (signal request)
+ * //          ./dump/strategy/{uuid}/06_llm_output.md (final signal)
+ * ```
+ */
+async function dumpSignal(signalId, history, signal, outputDir = "./dump/strategy") {
+    backtest$1.loggerService.info(DUMP_SIGNAL_METHOD_NAME, {
+        signalId,
+        history,
+        signal,
+        outputDir,
+    });
+    return await backtest$1.outlineMarkdownService.dumpSignal(signalId, history, signal, outputDir);
+}
+
 const BACKTEST_METHOD_NAME_RUN = "BacktestUtils.run";
 const BACKTEST_METHOD_NAME_BACKGROUND = "BacktestUtils.background";
 const BACKTEST_METHOD_NAME_GET_REPORT = "BacktestUtils.getReport";
@@ -14142,4 +14362,4 @@ class ConstantUtils {
  */
 const Constant = new ConstantUtils();
 
-export { Backtest, Constant, ExecutionContextService, Heat, Live, MethodContextService, Optimizer, Partial, Performance, PersistBase, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PositionSize, Schedule, Walker, addExchange, addFrame, addOptimizer, addRisk, addSizing, addStrategy, addWalker, emitters, formatPrice, formatQuantity, getAveragePrice, getCandles, getDate, getMode, backtest as lib, listExchanges, listFrames, listOptimizers, listRisks, listSizings, listStrategies, listWalkers, listenBacktestProgress, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenOptimizerProgress, listenPartialLoss, listenPartialLossOnce, listenPartialProfit, listenPartialProfitOnce, listenPerformance, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, setConfig, setLogger };
+export { Backtest, Constant, ExecutionContextService, Heat, Live, MethodContextService, Optimizer, Partial, Performance, PersistBase, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PositionSize, Schedule, Walker, addExchange, addFrame, addOptimizer, addRisk, addSizing, addStrategy, addWalker, dumpSignal, emitters, formatPrice, formatQuantity, getAveragePrice, getCandles, getDate, getMode, backtest as lib, listExchanges, listFrames, listOptimizers, listRisks, listSizings, listStrategies, listWalkers, listenBacktestProgress, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenOptimizerProgress, listenPartialLoss, listenPartialLossOnce, listenPartialProfit, listenPartialProfitOnce, listenPerformance, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, setConfig, setLogger };

package/package.json

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

package/types.d.ts

@@ -3616,6 +3616,74 @@ declare function getDate(): Promise<Date>;
  */
 declare function getMode(): Promise<"backtest" | "live">;
 
+/**
+ * Dumps signal data and LLM conversation history to markdown files.
+ * Used by AI-powered strategies to save debug logs for analysis.
+ *
+ * Creates a directory structure with:
+ * - 00_system_prompt.md - System messages and output summary
+ * - XX_user_message.md - Each user message in separate file (numbered)
+ * - XX_llm_output.md - Final LLM output with signal data
+ *
+ * Skips if directory already exists to avoid overwriting previous results.
+ *
+ * @param signalId - Unique identifier for the result (used as directory name, e.g., UUID)
+ * @param history - Array of message models from LLM conversation
+ * @param signal - Signal DTO returned by LLM (position, priceOpen, TP, SL, etc.)
+ * @param outputDir - Output directory path (default: "./dump/strategy")
+ * @returns Promise that resolves when all files are written
+ *
+ * @example
+ * ```typescript
+ * import { dumpSignal, getCandles } from "backtest-kit";
+ * import { v4 as uuid } from "uuid";
+ *
+ * addStrategy({
+ *   strategyName: "llm-strategy",
+ *   interval: "5m",
+ *   getSignal: async (symbol) => {
+ *     const messages = [];
+ *
+ *     // Build multi-timeframe analysis conversation
+ *     const candles1h = await getCandles(symbol, "1h", 24);
+ *     messages.push(
+ *       { role: "user", content: `Analyze 1h trend:\n${formatCandles(candles1h)}` },
+ *       { role: "assistant", content: "Trend analyzed" }
+ *     );
+ *
+ *     const candles5m = await getCandles(symbol, "5m", 24);
+ *     messages.push(
+ *       { role: "user", content: `Analyze 5m structure:\n${formatCandles(candles5m)}` },
+ *       { role: "assistant", content: "Structure analyzed" }
+ *     );
+ *
+ *     // Request signal
+ *     messages.push({
+ *       role: "user",
+ *       content: "Generate trading signal. Use position: 'wait' if uncertain."
+ *     });
+ *
+ *     const resultId = uuid();
+ *     const signal = await llmRequest(messages);
+ *
+ *     // Save conversation and result for debugging
+ *     await dumpSignal(resultId, messages, signal);
+ *
+ *     return signal;
+ *   }
+ * });
+ *
+ * // Creates: ./dump/strategy/{uuid}/00_system_prompt.md
+ * //          ./dump/strategy/{uuid}/01_user_message.md (1h analysis)
+ * //          ./dump/strategy/{uuid}/02_assistant_message.md
+ * //          ./dump/strategy/{uuid}/03_user_message.md (5m analysis)
+ * //          ./dump/strategy/{uuid}/04_assistant_message.md
+ * //          ./dump/strategy/{uuid}/05_user_message.md (signal request)
+ * //          ./dump/strategy/{uuid}/06_llm_output.md (final signal)
+ * ```
+ */
+declare function dumpSignal(signalId: string | number, history: MessageModel[], signal: ISignalDto, outputDir?: string): Promise<void>;
+
 /**
  * Portfolio heatmap statistics for a single symbol.
  * Aggregated metrics across all strategies for one trading pair.
@@ -8661,6 +8729,54 @@ declare class PartialGlobalService {
     clear: (symbol: string, data: ISignalRow, priceClose: number) => Promise<void>;
 }
 
+/**
+ * Unique identifier for outline result.
+ * Can be string or number for flexible ID formats.
+ */
+type ResultId = string | number;
+/**
+ * Service for generating markdown documentation from LLM outline results.
+ * Used by AI Strategy Optimizer to save debug logs and conversation history.
+ *
+ * Creates directory structure:
+ * - ./dump/strategy/{signalId}/00_system_prompt.md - System messages and output data
+ * - ./dump/strategy/{signalId}/01_user_message.md - First user input
+ * - ./dump/strategy/{signalId}/02_user_message.md - Second user input
+ * - ./dump/strategy/{signalId}/XX_llm_output.md - Final LLM output
+ */
+declare class OutlineMarkdownService {
+    /** Logger service injected via DI */
+    private readonly loggerService;
+    /**
+     * Dumps signal data and conversation history to markdown files.
+     * Skips if directory already exists to avoid overwriting previous results.
+     *
+     * Generated files:
+     * - 00_system_prompt.md - System messages and output summary
+     * - XX_user_message.md - Each user message in separate file (numbered)
+     * - XX_llm_output.md - Final LLM output with signal data
+     *
+     * @param signalId - Unique identifier for the result (used as directory name)
+     * @param history - Array of message models from LLM conversation
+     * @param signal - Signal DTO with trade parameters (priceOpen, TP, SL, etc.)
+     * @param outputDir - Output directory path (default: "./dump/strategy")
+     * @returns Promise that resolves when all files are written
+     *
+     * @example
+     * ```typescript
+     * await outlineService.dumpSignal(
+     *   "strategy-1",
+     *   conversationHistory,
+     *   { position: "long", priceTakeProfit: 51000, priceStopLoss: 49000, minuteEstimatedTime: 60 }
+     * );
+     * // Creates: ./dump/strategy/strategy-1/00_system_prompt.md
+     * //          ./dump/strategy/strategy-1/01_user_message.md
+     * //          ./dump/strategy/strategy-1/02_llm_output.md
+     * ```
+     */
+    dumpSignal: (signalId: ResultId, history: MessageModel[], signal: ISignalDto, outputDir?: string) => Promise<void>;
+}
+
 declare const backtest: {
     optimizerTemplateService: OptimizerTemplateService;
     exchangeValidationService: ExchangeValidationService;
@@ -8677,6 +8793,7 @@ declare const backtest: {
     walkerMarkdownService: WalkerMarkdownService;
     heatMarkdownService: HeatMarkdownService;
     partialMarkdownService: PartialMarkdownService;
+    outlineMarkdownService: OutlineMarkdownService;
     backtestLogicPublicService: BacktestLogicPublicService;
     liveLogicPublicService: LiveLogicPublicService;
     walkerLogicPublicService: WalkerLogicPublicService;
@@ -8716,4 +8833,4 @@ declare const backtest: {
     loggerService: LoggerService;
 };
 
-export { Backtest, type BacktestStatistics, type CandleInterval, Constant, type DoneContract, type EntityId, ExecutionContextService, type FrameInterval, type GlobalConfig, Heat, type ICandleData, type IExchangeSchema, type IFrameSchema, type IHeatmapRow, type IHeatmapStatistics, type IOptimizerCallbacks, type IOptimizerData, type IOptimizerFetchArgs, type IOptimizerFilterArgs, type IOptimizerRange, type IOptimizerSchema, type IOptimizerSource, type IOptimizerStrategy, type IOptimizerTemplate, type IPersistBase, type IPositionSizeATRParams, type IPositionSizeFixedPercentageParams, type IPositionSizeKellyParams, type IRiskActivePosition, type IRiskCheckArgs, type IRiskSchema, type IRiskValidation, type IRiskValidationFn, type IRiskValidationPayload, type IScheduledSignalRow, type ISignalDto, type ISignalRow, type ISizingCalculateParams, type ISizingCalculateParamsATR, type ISizingCalculateParamsFixedPercentage, type ISizingCalculateParamsKelly, type ISizingSchema, type ISizingSchemaATR, type ISizingSchemaFixedPercentage, type ISizingSchemaKelly, type IStrategyPnL, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultCancelled, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, type IStrategyTickResultScheduled, type IWalkerResults, type IWalkerSchema, type IWalkerStrategyResult, Live, type LiveStatistics, type MessageModel, type MessageRole, MethodContextService, Optimizer, Partial$1 as Partial, type PartialData, type PartialLossContract, type PartialProfitContract, type PartialStatistics, Performance, type PerformanceContract, type PerformanceMetricType, type PerformanceStatistics, PersistBase, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PositionSize, type ProgressBacktestContract, type ProgressOptimizerContract, type ProgressWalkerContract, type RiskData, Schedule, type ScheduleData, type ScheduleStatistics, type SignalData, type SignalInterval, type TPersistBase, type TPersistBaseCtor, Walker, type WalkerContract, type WalkerMetric, type WalkerStatistics, addExchange, addFrame, addOptimizer, addRisk, addSizing, addStrategy, addWalker, emitters, formatPrice, formatQuantity, getAveragePrice, getCandles, getDate, getMode, backtest as lib, listExchanges, listFrames, listOptimizers, listRisks, listSizings, listStrategies, listWalkers, listenBacktestProgress, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenOptimizerProgress, listenPartialLoss, listenPartialLossOnce, listenPartialProfit, listenPartialProfitOnce, listenPerformance, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, setConfig, setLogger };
+export { Backtest, type BacktestStatistics, type CandleInterval, Constant, type DoneContract, type EntityId, ExecutionContextService, type FrameInterval, type GlobalConfig, Heat, type ICandleData, type IExchangeSchema, type IFrameSchema, type IHeatmapRow, type IHeatmapStatistics, type IOptimizerCallbacks, type IOptimizerData, type IOptimizerFetchArgs, type IOptimizerFilterArgs, type IOptimizerRange, type IOptimizerSchema, type IOptimizerSource, type IOptimizerStrategy, type IOptimizerTemplate, type IPersistBase, type IPositionSizeATRParams, type IPositionSizeFixedPercentageParams, type IPositionSizeKellyParams, type IRiskActivePosition, type IRiskCheckArgs, type IRiskSchema, type IRiskValidation, type IRiskValidationFn, type IRiskValidationPayload, type IScheduledSignalRow, type ISignalDto, type ISignalRow, type ISizingCalculateParams, type ISizingCalculateParamsATR, type ISizingCalculateParamsFixedPercentage, type ISizingCalculateParamsKelly, type ISizingSchema, type ISizingSchemaATR, type ISizingSchemaFixedPercentage, type ISizingSchemaKelly, type IStrategyPnL, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultCancelled, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, type IStrategyTickResultScheduled, type IWalkerResults, type IWalkerSchema, type IWalkerStrategyResult, Live, type LiveStatistics, type MessageModel, type MessageRole, MethodContextService, Optimizer, Partial$1 as Partial, type PartialData, type PartialLossContract, type PartialProfitContract, type PartialStatistics, Performance, type PerformanceContract, type PerformanceMetricType, type PerformanceStatistics, PersistBase, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PositionSize, type ProgressBacktestContract, type ProgressOptimizerContract, type ProgressWalkerContract, type RiskData, Schedule, type ScheduleData, type ScheduleStatistics, type SignalData, type SignalInterval, type TPersistBase, type TPersistBaseCtor, Walker, type WalkerContract, type WalkerMetric, type WalkerStatistics, addExchange, addFrame, addOptimizer, addRisk, addSizing, addStrategy, addWalker, dumpSignal, emitters, formatPrice, formatQuantity, getAveragePrice, getCandles, getDate, getMode, backtest as lib, listExchanges, listFrames, listOptimizers, listRisks, listSizings, listStrategies, listWalkers, listenBacktestProgress, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenOptimizerProgress, listenPartialLoss, listenPartialLossOnce, listenPartialProfit, listenPartialProfitOnce, listenPerformance, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, setConfig, setLogger };