@backtest-kit/signals 0.0.1 → 0.0.3

package/build/index.cjs

@@ -5,31 +5,97 @@ var backtestKit = require('backtest-kit');
 var diKit = require('di-kit');
 var functoolsKit = require('functools-kit');
 
+/**
+ * Dependency injection container for signals library.
+ *
+ * Creates an isolated DI container using di-kit for managing service instances.
+ * Provides methods for dependency registration, injection, and initialization.
+ *
+ * @module lib/core/di
+ */
+/**
+ * DI container exports for signals library.
+ *
+ * - provide: Register service factory in DI container
+ * - inject: Retrieve service instance from container
+ * - init: Initialize all registered services
+ * - override: Replace existing service registration
+ */
 const { provide, inject, init, override } = diKit.createActivator("signal");
 
+/**
+ * Dependency injection type symbols for signals library.
+ *
+ * Defines unique symbols for service registration and retrieval in the DI container.
+ * Organized by service category: common, math, and history services.
+ *
+ * @module lib/core/types
+ */
+/**
+ * Common service symbols.
+ */
 const commonServices$1 = {
+    /** Logger service for diagnostic output */
     loggerService: Symbol("loggerService"),
 };
+/**
+ * Technical analysis service symbols.
+ */
 const mathServices$1 = {
+    /** 1-hour (LongTerm) technical analysis service */
     longTermMathService: Symbol('longTermMathService'),
+    /** 30-minute (SwingTerm) technical analysis service */
     swingTermMathService: Symbol('swingTermMathService'),
+    /** 15-minute (ShortTerm) technical analysis service */
     shortTermMathService: Symbol('shortTermMathService'),
+    /** 1-minute (MicroTerm) technical analysis service */
     microTermMathService: Symbol('microTermMathService'),
+    /** Order book analysis service */
     bookDataMathService: Symbol('bookDataMathService'),
 };
+/**
+ * Candle history service symbols.
+ */
 const historyServices$1 = {
+    /** 15-minute candle history service */
     fifteenMinuteCandleHistoryService: Symbol('fifteenMinuteCandleHistoryService'),
+    /** 1-hour candle history service */
     hourCandleHistoryService: Symbol('hourCandleHistoryService'),
+    /** 1-minute candle history service */
     oneMinuteCandleHistoryService: Symbol('oneMinuteCandleHistoryService'),
+    /** 30-minute candle history service */
     thirtyMinuteCandleHistoryService: Symbol('thirtyMinuteCandleHistoryService'),
 };
+/**
+ * All service type symbols combined.
+ */
 const TYPES = {
     ...commonServices$1,
     ...mathServices$1,
     ...historyServices$1,
 };
 
+/**
+ * LongTerm (1-hour) technical analysis service for trend trading.
+ *
+ * Generates 30+ indicators on 1-hour candles with 48-candle lookback (48 hours).
+ * Optimized for multi-day trend trading and position management.
+ *
+ * Indicators: RSI(14), StochRSI(14), MACD(12,26,9), Bollinger(20,2), Stochastic(14,3,3),
+ * ADX(14), ATR(14,20), CCI(20), Momentum(10), SMA(50), EMA(20,34), DEMA(21), WMA(20),
+ * Support/Resistance, Fibonacci levels, Volume trends.
+ *
+ * Used by commitLongTermMath().
+ */
+/**
+ * Maximum number of historical rows to return in analysis results.
+ * Limits memory usage and table size for markdown reports.
+ */
 const TABLE_ROWS_LIMIT$3 = 48;
+/**
+ * Minimum number of candles required before generating analysis rows.
+ * Ensures all technical indicators (especially SMA(50)) have sufficient data.
+ */
 const WARMUP_PERIOD$3 = 50;
 const columns$3 = [
     {
@@ -214,6 +280,23 @@ const columns$3 = [
         format: (v) => new Date(v).toISOString(),
     },
 ];
+/**
+ * Validates whether a numeric value is safe for calculations.
+ *
+ * Checks if value is a valid finite number. Returns true if value is null,
+ * NaN, Infinity, or not a number type.
+ *
+ * @param value - Value to validate
+ * @returns True if value is unsafe (null/NaN/Infinity), false if valid number
+ *
+ * @example
+ * ```typescript
+ * isUnsafe(42) // false - valid number
+ * isUnsafe(null) // true - null value
+ * isUnsafe(NaN) // true - not a number
+ * isUnsafe(Infinity) // true - infinite value
+ * ```
+ */
 function isUnsafe$4(value) {
     if (typeof value !== "number") {
         return true;
@@ -226,6 +309,25 @@ function isUnsafe$4(value) {
     }
     return false;
 }
+/**
+ * Calculates Fibonacci retracement levels and finds nearest level to current price.
+ *
+ * Computes standard Fibonacci levels (0%, 23.6%, 38.2%, 50%, 61.8%, 78.6%, 100%)
+ * plus extension levels (127.2%, 161.8%) based on high-low range over lookback period.
+ * Returns the level closest to current price with distance in USD.
+ *
+ * @param candles - Array of candle data
+ * @param endIndex - Index of current candle in array
+ * @returns Object with nearest level name, price, and distance in USD
+ *
+ * @example
+ * ```typescript
+ * const candles = await getCandles('BTCUSDT', '1h', 100);
+ * const fib = calculateFibonacciLevels(candles, 99);
+ * console.log(fib);
+ * // { level: "61.8%", price: 42500.50, distance: 125.30 }
+ * ```
+ */
 function calculateFibonacciLevels$2(candles, endIndex) {
     const lookbackPeriod = Math.min(24, endIndex + 1);
     const startIndex = endIndex + 1 - lookbackPeriod;
@@ -258,6 +360,31 @@ function calculateFibonacciLevels$2(candles, endIndex) {
     });
     return nearestLevel;
 }
+/**
+ * Generates comprehensive technical analysis for 1-hour candles (long-term trading).
+ *
+ * Calculates 30+ technical indicators per candle including:
+ * - Momentum: RSI(14), Stochastic RSI(14), MACD(12,26,9), Momentum(10)
+ * - Trend: SMA(50), EMA(20,34), DEMA(21), WMA(20), ADX(14), +DI/-DI
+ * - Volatility: ATR(14,20), Bollinger Bands(20,2.0), CCI(20)
+ * - Volume: Volume trend analysis
+ * - Support/Resistance: Pivot points, Fibonacci levels
+ *
+ * Skips first WARMUP_PERIOD (50) candles to ensure indicator stability.
+ * Returns last TABLE_ROWS_LIMIT (48) rows for memory efficiency.
+ *
+ * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+ * @param candles - Array of 1-hour candle data
+ * @returns Array of technical analysis rows with all indicators
+ *
+ * @example
+ * ```typescript
+ * const candles = await getCandles('BTCUSDT', '1h', 100);
+ * const analysis = generateAnalysis('BTCUSDT', candles);
+ * console.log(analysis[0].rsi14); // 52.45
+ * console.log(analysis[0].support); // 42000.50
+ * ```
+ */
 function generateAnalysis$3(symbol, candles) {
     const closes = candles.map((candle) => Number(candle.close));
     const highs = candles.map((candle) => Number(candle.high));
@@ -439,6 +566,32 @@ function generateAnalysis$3(symbol, candles) {
     });
     return results;
 }
+/**
+ * Generates markdown table with long-term technical analysis history.
+ *
+ * Creates comprehensive markdown report with:
+ * - Formatted table of all technical indicators
+ * - Column headers with indicator names and parameters
+ * - Formatted values (prices in USD, percentages, decimals)
+ * - Data sources section explaining each indicator's calculation
+ * - Timeframe and lookback period documentation (1h candles, 48h lookback)
+ *
+ * Output is optimized for LLM consumption in long-term trading signal generation.
+ *
+ * @param indicators - Array of analysis rows from generateAnalysis()
+ * @param symbol - Trading pair symbol for price formatting
+ * @returns Markdown-formatted technical analysis report
+ *
+ * @example
+ * ```typescript
+ * const rows = await service.getData('BTCUSDT', candles);
+ * const markdown = await generateHistoryTable(rows, 'BTCUSDT');
+ * console.log(markdown);
+ * // # 1-Hour Candles Trading Analysis for BTCUSDT (Historical Data)
+ * // > Current time: 2025-01-14T10:30:00.000Z
+ * // | RSI(14) | MACD(12,26,9) | Support Level | ... |
+ * ```
+ */
 async function generateHistoryTable$3(indicators, symbol) {
     let markdown = "";
     const currentData = await backtestKit.getDate();
@@ -519,9 +672,61 @@ async function generateHistoryTable$3(indicators, symbol) {
         "- **Close Price**: close price at row timestamp (Min: 0 USD, Max: +∞ USD)\n";
     return markdown;
 }
+/**
+ * Service for long-term (1-hour) technical analysis and markdown report generation.
+ *
+ * Provides comprehensive technical analysis for 1-hour candles with 30+ indicators
+ * including momentum (RSI, MACD), trend (EMA, SMA), volatility (ATR, Bollinger Bands),
+ * support/resistance levels, and Fibonacci retracements.
+ *
+ * Key features:
+ * - 30+ technical indicators (RSI, MACD, Bollinger Bands, Stochastic, ADX, etc.)
+ * - Support/resistance level detection
+ * - Fibonacci retracement analysis
+ * - Volume trend analysis
+ * - Markdown table generation for LLM consumption
+ * - Intelligent indicator warmup (skips first 50 candles)
+ * - Memory-efficient output (last 48 rows only)
+ * - Dependency injection support
+ *
+ * @example
+ * ```typescript
+ * import { LongTermHistoryService } from '@backtest-kit/signals';
+ *
+ * const service = new LongTermHistoryService();
+ *
+ * // Get markdown report for symbol (fetches candles internally)
+ * const report = await service.getReport('BTCUSDT');
+ * console.log(report); // Markdown table with all indicators
+ *
+ * // Or analyze custom candles
+ * const candles = await getCandles('ETHUSDT', '1h', 100);
+ * const rows = await service.getData('ETHUSDT', candles);
+ * console.log(rows[0].rsi14); // 52.45
+ * ```
+ */
 class LongTermHistoryService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
+        /**
+         * Analyzes candle data and returns technical indicator rows.
+         *
+         * Calculates all technical indicators for provided candles, skips first WARMUP_PERIOD
+         * rows to ensure stability, and returns last TABLE_ROWS_LIMIT rows.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @param candles - Array of 1-hour candle data
+         * @returns Array of technical analysis rows with all indicators
+         *
+         * @example
+         * ```typescript
+         * const candles = await getCandles('BTCUSDT', '1h', 100);
+         * const rows = await service.getData('BTCUSDT', candles);
+         * console.log(rows.length); // Up to 48 rows
+         * console.log(rows[0].rsi14); // 52.45
+         * console.log(rows[0].support); // 42000.50
+         * ```
+         */
         this.getData = async (symbol, candles) => {
             this.loggerService.log("longTermHistoryService getData", {
                 symbol,
@@ -529,6 +734,26 @@ class LongTermHistoryService {
             });
             return generateAnalysis$3(symbol, candles);
         };
+        /**
+         * Generates complete markdown technical analysis report for a symbol.
+         *
+         * Fetches 100 1-hour candles (100 hours) from exchange, calculates all indicators,
+         * and formats last 48 rows as markdown table optimized for LLM consumption.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @returns Markdown-formatted technical analysis report with table and explanations
+         *
+         * @example
+         * ```typescript
+         * const report = await service.getReport('BTCUSDT');
+         * console.log(report);
+         * // # 1-Hour Candles Trading Analysis for BTCUSDT (Historical Data)
+         * // > Current time: 2025-01-14T10:30:00.000Z
+         * //
+         * // | RSI(14) | MACD(12,26,9) | Support Level | ...
+         * // | 52.45 | 0.0023 | 42000.50 USD | ...
+         * ```
+         */
         this.getReport = async (symbol) => {
             this.loggerService.log("longTermHistoryService getReport", { symbol });
             const fullCandles = await backtestKit.getCandles(symbol, "1h", 100);
@@ -537,6 +762,24 @@ class LongTermHistoryService {
             const rows = allRows.slice(-TABLE_ROWS_LIMIT$3);
             return generateHistoryTable$3(rows, symbol);
         };
+        /**
+         * Converts analysis rows into markdown table format.
+         *
+         * Takes pre-calculated indicator rows and formats them as markdown table
+         * with column headers, formatted values, and data source explanations.
+         *
+         * @param symbol - Trading pair symbol for price formatting
+         * @param rows - Array of technical analysis rows from getData()
+         * @returns Markdown-formatted table with all indicators
+         *
+         * @example
+         * ```typescript
+         * const candles = await getCandles('BTCUSDT', '1h', 100);
+         * const rows = await service.getData('BTCUSDT', candles);
+         * const markdown = await service.generateHistoryTable('BTCUSDT', rows);
+         * console.log(markdown); // Markdown table
+         * ```
+         */
         this.generateHistoryTable = async (symbol, rows) => {
             this.loggerService.log("longTermHistoryService generateHistoryTable", {
                 symbol,
@@ -547,7 +790,27 @@ class LongTermHistoryService {
     }
 }
 
+/**
+ * MicroTerm (1-minute) technical analysis service for scalping strategies.
+ *
+ * Generates 40+ indicators on 1-minute candles with 60-candle lookback.
+ * Optimized for high-frequency trading and sub-5 minute positions.
+ *
+ * Indicators: RSI(9,14), StochRSI(9,14), MACD(8,21,5), Bollinger(8,2), Stochastic(3,5),
+ * ADX(9), ATR(5,9), CCI(9), Momentum(5,10), ROC(1,3,5), EMA(3,8,13,21), SMA(8), DEMA(8),
+ * WMA(5), Support/Resistance, Volume analysis, Squeeze momentum.
+ *
+ * Used by commitMicroTermMath().
+ */
+/**
+ * Minimum number of candles required before generating analysis rows.
+ * Ensures all technical indicators (especially EMA(21)) have sufficient data.
+ */
 const WARMUP_PERIOD$2 = 21;
+/**
+ * Maximum number of historical rows to return in analysis results.
+ * Limits memory usage and table size for markdown reports.
+ */
 const TABLE_ROWS_LIMIT$2 = 40;
 const columns$2 = [
     {
@@ -825,6 +1088,23 @@ const columns$2 = [
         format: (v) => new Date(v).toISOString(),
     },
 ];
+/**
+ * Validates whether a numeric value is safe for calculations.
+ *
+ * Checks if value is a valid finite number. Returns true if value is null,
+ * NaN, Infinity, or not a number type.
+ *
+ * @param value - Value to validate
+ * @returns True if value is unsafe (null/NaN/Infinity), false if valid number
+ *
+ * @example
+ * ```typescript
+ * isUnsafe(42) // false - valid number
+ * isUnsafe(null) // true - null value
+ * isUnsafe(NaN) // true - not a number
+ * isUnsafe(Infinity) // true - infinite value
+ * ```
+ */
 function isUnsafe$3(value) {
     if (typeof value !== "number") {
         return true;
@@ -837,6 +1117,25 @@ function isUnsafe$3(value) {
     }
     return false;
 }
+/**
+ * Calculates volume metrics including SMA, ratio, and trend.
+ *
+ * Computes volume SMA(5), current volume to average ratio, and volume trend
+ * by comparing recent 3 candles to previous 3 candles. Returns "increasing"
+ * if recent average > 120% of previous, "decreasing" if < 80%, else "stable".
+ *
+ * @param candles - Array of candle data
+ * @param endIndex - Index of current candle in array
+ * @returns Object with volumeSma5, volumeRatio, and volumeTrend
+ *
+ * @example
+ * ```typescript
+ * const candles = await getCandles('BTCUSDT', '1m', 60);
+ * const metrics = calculateVolumeMetrics(candles, 59);
+ * console.log(metrics);
+ * // { volumeSma5: 1500000, volumeRatio: 1.25, volumeTrend: "increasing" }
+ * ```
+ */
 function calculateVolumeMetrics(candles, endIndex) {
     const volumes = candles.slice(0, endIndex + 1).map((c) => Number(c.volume));
     if (volumes.length < 5) {
@@ -863,6 +1162,24 @@ function calculateVolumeMetrics(candles, endIndex) {
     }
     return { volumeSma5: avgVolume, volumeRatio, volumeTrend };
 }
+/**
+ * Calculates price change percentages over 1, 3, and 5 minute periods.
+ *
+ * Computes percentage price changes from current price to prices at
+ * 1, 3, and 5 candles ago. Returns null for periods with insufficient data.
+ *
+ * @param candles - Array of candle data
+ * @param endIndex - Index of current candle in array
+ * @returns Object with priceChange1m, priceChange3m, and priceChange5m percentages
+ *
+ * @example
+ * ```typescript
+ * const candles = await getCandles('BTCUSDT', '1m', 60);
+ * const changes = calculatePriceChanges(candles, 59);
+ * console.log(changes);
+ * // { priceChange1m: 0.05, priceChange3m: 0.12, priceChange5m: -0.08 }
+ * ```
+ */
 function calculatePriceChanges(candles, endIndex) {
     const closes = candles.slice(0, endIndex + 1).map((c) => Number(c.close));
     if (closes.length < 2) {
@@ -883,6 +1200,26 @@ function calculatePriceChanges(candles, endIndex) {
         : null;
     return { priceChange1m, priceChange3m, priceChange5m };
 }
+/**
+ * Calculates support and resistance levels from recent high/low prices.
+ *
+ * Identifies support (minimum low) and resistance (maximum high) levels
+ * over last 30 candles. Uses minimum distance threshold (0.3% of current price)
+ * to filter significant levels. Falls back to current price if insufficient data.
+ *
+ * @param candles - Array of candle data
+ * @param endIndex - Index of current candle in array
+ * @param currentPrice - Current price for distance calculations
+ * @returns Object with support and resistance price levels
+ *
+ * @example
+ * ```typescript
+ * const candles = await getCandles('BTCUSDT', '1m', 60);
+ * const levels = calculateSupportResistance(candles, 59, 42500);
+ * console.log(levels);
+ * // { support: 42400.50, resistance: 42600.75 }
+ * ```
+ */
 function calculateSupportResistance$1(candles, endIndex, currentPrice) {
     const recentPeriod = Math.min(30, endIndex + 1);
     const startIdx = endIndex + 1 - recentPeriod;
@@ -913,6 +1250,32 @@ function calculateSupportResistance$1(candles, endIndex, currentPrice) {
             : currentPrice;
     return { support, resistance };
 }
+/**
+ * Generates comprehensive technical analysis for 1-minute candles (scalping).
+ *
+ * Calculates 40+ technical indicators per candle including:
+ * - Momentum: RSI(9,14), Stochastic RSI(9,14), MACD(8,21,5), Momentum(5,10), ROC(1,3,5)
+ * - Trend: EMA(3,8,13,21), SMA(8), DEMA(8), WMA(5), ADX(9), +DI/-DI
+ * - Volatility: ATR(5,9), Bollinger Bands(8,2.0), volatility(5), true range
+ * - Volume: Volume SMA(5), volume ratio, volume trend
+ * - Support/Resistance: Pivot points over 30 candles
+ * - Special: Squeeze momentum, pressure index, Bollinger position
+ *
+ * Skips first WARMUP_PERIOD (21) candles to ensure indicator stability.
+ * Returns last TABLE_ROWS_LIMIT (40) rows for memory efficiency.
+ *
+ * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+ * @param candles - Array of 1-minute candle data
+ * @returns Array of technical analysis rows with all indicators
+ *
+ * @example
+ * ```typescript
+ * const candles = await getCandles('BTCUSDT', '1m', 60);
+ * const analysis = generateAnalysis('BTCUSDT', candles);
+ * console.log(analysis[0].rsi9); // 45.23
+ * console.log(analysis[0].squeezeMomentum); // 1.25
+ * ```
+ */
 function generateAnalysis$2(symbol, candles) {
     const closes = candles.map((candle) => Number(candle.close));
     const highs = candles.map((candle) => Number(candle.high));
@@ -1157,6 +1520,32 @@ function generateAnalysis$2(symbol, candles) {
     // Return only the last TABLE_ROWS_LIMIT rows
     return results.slice(-TABLE_ROWS_LIMIT$2);
 }
+/**
+ * Generates markdown table with micro-term technical analysis history.
+ *
+ * Creates comprehensive markdown report with:
+ * - Formatted table of all 40+ technical indicators
+ * - Column headers with indicator names and parameters
+ * - Formatted values (prices in USD, percentages, decimals)
+ * - Data sources section explaining each indicator's calculation
+ * - Timeframe and lookback period documentation (1m candles, 60m lookback)
+ *
+ * Output is optimized for LLM consumption in scalping signal generation.
+ *
+ * @param indicators - Array of analysis rows from generateAnalysis()
+ * @param symbol - Trading pair symbol for price formatting
+ * @returns Markdown-formatted technical analysis report
+ *
+ * @example
+ * ```typescript
+ * const rows = await service.getData('BTCUSDT', candles);
+ * const markdown = await generateHistoryTable(rows, 'BTCUSDT');
+ * console.log(markdown);
+ * // # 1-Minute Candles Trading Analysis for BTCUSDT (Historical Data)
+ * // > Current time: 2025-01-14T10:30:00.000Z
+ * // | RSI(9) | MACD(8,21,5) | Squeeze Momentum | ... |
+ * ```
+ */
 async function generateHistoryTable$2(indicators, symbol) {
     let markdown = "";
     const currentData = await backtestKit.getDate();
@@ -1271,9 +1660,64 @@ async function generateHistoryTable$2(indicators, symbol) {
         "- **Close Price**: close price at row timestamp (Min: 0 USD, Max: +∞ USD)\n";
     return markdown;
 }
+/**
+ * Service for micro-term (1-minute) technical analysis and markdown report generation.
+ *
+ * Provides comprehensive technical analysis for 1-minute candles with 40+ indicators
+ * including momentum (RSI, MACD), trend (EMA, SMA), volatility (ATR, Bollinger Bands),
+ * support/resistance levels, volume analysis, and specialized scalping indicators.
+ *
+ * Key features:
+ * - 40+ technical indicators (RSI, MACD, Bollinger Bands, Stochastic, ADX, etc.)
+ * - Support/resistance level detection (30-candle lookback)
+ * - Volume analysis (SMA, ratio, trend)
+ * - Price change tracking (1m, 3m, 5m)
+ * - Specialized scalping indicators (squeeze momentum, pressure index, Bollinger position)
+ * - Volatility and true range calculations
+ * - Markdown table generation for LLM consumption
+ * - Intelligent indicator warmup (skips first 21 candles)
+ * - Memory-efficient output (last 40 rows only)
+ * - Dependency injection support
+ *
+ * @example
+ * ```typescript
+ * import { MicroTermHistoryService } from '@backtest-kit/signals';
+ *
+ * const service = new MicroTermHistoryService();
+ *
+ * // Get markdown report for symbol (fetches candles internally)
+ * const report = await service.getReport('BTCUSDT');
+ * console.log(report); // Markdown table with all indicators
+ *
+ * // Or analyze custom candles
+ * const candles = await getCandles('ETHUSDT', '1m', 60);
+ * const rows = await service.getData('ETHUSDT', candles);
+ * console.log(rows[0].rsi9); // 45.23
+ * console.log(rows[0].squeezeMomentum); // 1.25
+ * ```
+ */
 class MicroTermHistoryService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
+        /**
+         * Analyzes candle data and returns technical indicator rows.
+         *
+         * Calculates all technical indicators for provided candles, skips first WARMUP_PERIOD
+         * rows to ensure stability, and returns last TABLE_ROWS_LIMIT rows.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @param candles - Array of 1-minute candle data
+         * @returns Array of technical analysis rows with all indicators
+         *
+         * @example
+         * ```typescript
+         * const candles = await getCandles('BTCUSDT', '1m', 60);
+         * const rows = await service.getData('BTCUSDT', candles);
+         * console.log(rows.length); // Up to 40 rows
+         * console.log(rows[0].rsi9); // 45.23
+         * console.log(rows[0].volumeRatio); // 1.25
+         * ```
+         */
         this.getData = async (symbol, candles) => {
             this.loggerService.log("microTermHistoryService getData", {
                 symbol,
@@ -1281,12 +1725,50 @@ class MicroTermHistoryService {
             });
             return generateAnalysis$2(symbol, candles);
         };
+        /**
+         * Generates complete markdown technical analysis report for a symbol.
+         *
+         * Fetches 60 1-minute candles (60 minutes) from exchange, calculates all indicators,
+         * and formats results as markdown table optimized for LLM consumption.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @returns Markdown-formatted technical analysis report with table and explanations
+         *
+         * @example
+         * ```typescript
+         * const report = await service.getReport('BTCUSDT');
+         * console.log(report);
+         * // # 1-Minute Candles Trading Analysis for BTCUSDT (Historical Data)
+         * // > Current time: 2025-01-14T10:30:00.000Z
+         * //
+         * // | RSI(9) | MACD(8,21,5) | Squeeze Momentum | ...
+         * // | 45.23 | 0.0012 | 1.25 | ...
+         * ```
+         */
         this.getReport = async (symbol) => {
             this.loggerService.log("microTermHistoryService getReport", { symbol });
             const candles = await backtestKit.getCandles(symbol, "1m", 60);
             const rows = await this.getData(symbol, candles);
             return generateHistoryTable$2(rows, symbol);
         };
+        /**
+         * Converts analysis rows into markdown table format.
+         *
+         * Takes pre-calculated indicator rows and formats them as markdown table
+         * with column headers, formatted values, and data source explanations.
+         *
+         * @param symbol - Trading pair symbol for price formatting
+         * @param rows - Array of technical analysis rows from getData()
+         * @returns Markdown-formatted table with all indicators
+         *
+         * @example
+         * ```typescript
+         * const candles = await getCandles('BTCUSDT', '1m', 60);
+         * const rows = await service.getData('BTCUSDT', candles);
+         * const markdown = await service.generateHistoryTable('BTCUSDT', rows);
+         * console.log(markdown); // Markdown table
+         * ```
+         */
         this.generateHistoryTable = async (symbol, rows) => {
             this.loggerService.log("microTermHistoryService generateHistoryTable", {
                 symbol,
@@ -1297,7 +1779,15 @@ class MicroTermHistoryService {
     }
 }
 
+/**
+ * Maximum number of historical rows to return in analysis results.
+ * Limits memory usage and table size for markdown reports.
+ */
 const TABLE_ROWS_LIMIT$1 = 48;
+/**
+ * Minimum number of candles required before generating analysis rows.
+ * Ensures all technical indicators (especially SMA(50)) have sufficient data.
+ */
 const WARMUP_PERIOD$1 = 50;
 const columns$1 = [
     {
@@ -1485,6 +1975,23 @@ const columns$1 = [
         format: (v) => new Date(v).toISOString(),
     },
 ];
+/**
+ * Validates whether a numeric value is safe for calculations.
+ *
+ * Checks if value is a valid finite number. Returns true if value is null,
+ * NaN, Infinity, or not a number type.
+ *
+ * @param value - Value to validate
+ * @returns True if value is unsafe (null/NaN/Infinity), false if valid number
+ *
+ * @example
+ * ```typescript
+ * isUnsafe(42) // false - valid number
+ * isUnsafe(null) // true - null value
+ * isUnsafe(NaN) // true - not a number
+ * isUnsafe(Infinity) // true - infinite value
+ * ```
+ */
 function isUnsafe$2(value) {
     if (typeof value !== "number") {
         return true;
@@ -1497,6 +2004,25 @@ function isUnsafe$2(value) {
     }
     return false;
 }
+/**
+ * Calculates Fibonacci retracement levels and finds nearest level to current price.
+ *
+ * Computes standard Fibonacci levels (0%, 23.6%, 38.2%, 50%, 61.8%, 78.6%, 100%)
+ * plus extension levels (127.2%, 161.8%) based on high-low range over lookback period.
+ * Returns the level closest to current price with distance in USD.
+ *
+ * @param candles - Array of candle data
+ * @param endIndex - Index of current candle in array
+ * @returns Object with nearest level name, price, and distance in USD
+ *
+ * @example
+ * ```typescript
+ * const candles = await getCandles('BTCUSDT', '15m', 300);
+ * const fib = calculateFibonacciLevels(candles, 299);
+ * console.log(fib);
+ * // { level: "61.8%", price: 42500.50, distance: 125.30 }
+ * ```
+ */
 function calculateFibonacciLevels$1(candles, endIndex) {
     const lookbackPeriod = Math.min(288, endIndex + 1);
     const startIndex = endIndex + 1 - lookbackPeriod;
@@ -1529,6 +2055,24 @@ function calculateFibonacciLevels$1(candles, endIndex) {
     });
     return nearestLevel;
 }
+/**
+ * Analyzes volume trend by comparing recent vs older volume averages.
+ *
+ * Compares average volume of last 8 candles against previous 8 candles.
+ * Returns "increasing" if recent volume > 120% of older volume,
+ * "decreasing" if recent < 80% of older volume, otherwise "stable".
+ *
+ * @param candles - Array of candle data
+ * @param endIndex - Index of current candle in array
+ * @returns Volume trend: "increasing", "decreasing", or "stable"
+ *
+ * @example
+ * ```typescript
+ * const candles = await getCandles('ETHUSDT', '15m', 100);
+ * const trend = calculateVolumeTrend(candles, 99);
+ * console.log(trend); // "increasing" | "decreasing" | "stable"
+ * ```
+ */
 function calculateVolumeTrend(candles, endIndex) {
     const volumes = candles.slice(0, endIndex + 1).map((c) => Number(c.volume));
     if (volumes.length < 16)
@@ -1545,6 +2089,31 @@ function calculateVolumeTrend(candles, endIndex) {
         return "decreasing";
     return "stable";
 }
+/**
+ * Generates comprehensive technical analysis for 15-minute candles.
+ *
+ * Calculates 30+ technical indicators per candle including:
+ * - Momentum: RSI(9), Stochastic RSI(9), MACD(8,21,5), Momentum(8), ROC(5,10)
+ * - Trend: SMA(50), EMA(8,21), DEMA(21), WMA(20), ADX(14), +DI/-DI
+ * - Volatility: ATR(9), Bollinger Bands(10,2.0)
+ * - Volume: Volume trend analysis
+ * - Support/Resistance: Pivot points, Fibonacci levels
+ *
+ * Skips first WARMUP_PERIOD (50) candles to ensure indicator stability.
+ * Returns last TABLE_ROWS_LIMIT (48) rows for memory efficiency.
+ *
+ * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+ * @param candles - Array of 15-minute candle data
+ * @returns Array of technical analysis rows with all indicators
+ *
+ * @example
+ * ```typescript
+ * const candles = await getCandles('BTCUSDT', '15m', 144);
+ * const analysis = generateAnalysis('BTCUSDT', candles);
+ * console.log(analysis[0].rsi9); // 45.23
+ * console.log(analysis[0].support); // 42000.50
+ * ```
+ */
 function generateAnalysis$1(symbol, candles) {
     const closes = candles.map((candle) => Number(candle.close));
     const highs = candles.map((candle) => Number(candle.high));
@@ -1722,6 +2291,32 @@ function generateAnalysis$1(symbol, candles) {
     // Return only the last TABLE_ROWS_LIMIT rows
     return results.slice(-TABLE_ROWS_LIMIT$1);
 }
+/**
+ * Generates markdown table with technical analysis history.
+ *
+ * Creates comprehensive markdown report with:
+ * - Formatted table of all technical indicators
+ * - Column headers with indicator names and parameters
+ * - Formatted values (prices in USD, percentages, decimals)
+ * - Data sources section explaining each indicator's calculation
+ * - Timeframe and lookback period documentation
+ *
+ * Output is optimized for LLM consumption in trading signal generation.
+ *
+ * @param indicators - Array of analysis rows from generateAnalysis()
+ * @param symbol - Trading pair symbol for price formatting
+ * @returns Markdown-formatted technical analysis report
+ *
+ * @example
+ * ```typescript
+ * const rows = await service.getData('BTCUSDT', candles);
+ * const markdown = await generateHistoryTable(rows, 'BTCUSDT');
+ * console.log(markdown);
+ * // # 15-Minute Candles Trading Analysis for BTCUSDT (Historical Data)
+ * // > Current time: 2025-01-14T10:30:00.000Z
+ * // | RSI(9) | MACD(8,21,5) | ... |
+ * ```
+ */
 async function generateHistoryTable$1(indicators, symbol) {
     let markdown = "";
     const currentData = await backtestKit.getDate();
@@ -1804,9 +2399,61 @@ async function generateHistoryTable$1(indicators, symbol) {
         "- **Close Price**: close price at row timestamp (Min: 0 USD, Max: +∞ USD)\n";
     return markdown;
 }
+/**
+ * Service for short-term (15-minute) technical analysis and markdown report generation.
+ *
+ * Provides comprehensive technical analysis for 15-minute candles with 30+ indicators
+ * including momentum (RSI, MACD), trend (EMA, SMA), volatility (ATR, Bollinger Bands),
+ * support/resistance levels, and Fibonacci retracements.
+ *
+ * Key features:
+ * - 30+ technical indicators (RSI, MACD, Bollinger Bands, Stochastic, ADX, etc.)
+ * - Support/resistance level detection
+ * - Fibonacci retracement analysis
+ * - Volume trend analysis
+ * - Markdown table generation for LLM consumption
+ * - Intelligent indicator warmup (skips first 50 candles)
+ * - Memory-efficient output (last 48 rows only)
+ * - Dependency injection support
+ *
+ * @example
+ * ```typescript
+ * import { ShortTermHistoryService } from '@backtest-kit/signals';
+ *
+ * const service = new ShortTermHistoryService();
+ *
+ * // Get markdown report for symbol (fetches candles internally)
+ * const report = await service.getReport('BTCUSDT');
+ * console.log(report); // Markdown table with all indicators
+ *
+ * // Or analyze custom candles
+ * const candles = await getCandles('ETHUSDT', '15m', 144);
+ * const rows = await service.getData('ETHUSDT', candles);
+ * console.log(rows[0].rsi9); // 45.23
+ * ```
+ */
 class ShortTermHistoryService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
+        /**
+         * Analyzes candle data and returns technical indicator rows.
+         *
+         * Calculates all technical indicators for provided candles, skips first WARMUP_PERIOD
+         * rows to ensure stability, and returns last TABLE_ROWS_LIMIT rows.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @param candles - Array of 15-minute candle data
+         * @returns Array of technical analysis rows with all indicators
+         *
+         * @example
+         * ```typescript
+         * const candles = await getCandles('BTCUSDT', '15m', 144);
+         * const rows = await service.getData('BTCUSDT', candles);
+         * console.log(rows.length); // Up to 48 rows
+         * console.log(rows[0].rsi9); // 45.23
+         * console.log(rows[0].support); // 42000.50
+         * ```
+         */
         this.getData = async (symbol, candles) => {
             this.loggerService.log("shortTermHistoryService getData", {
                 symbol,
@@ -1814,12 +2461,50 @@ class ShortTermHistoryService {
             });
             return generateAnalysis$1(symbol, candles);
         };
+        /**
+         * Generates complete markdown technical analysis report for a symbol.
+         *
+         * Fetches 144 15-minute candles (36 hours) from exchange, calculates all indicators,
+         * and formats results as markdown table optimized for LLM consumption.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @returns Markdown-formatted technical analysis report with table and explanations
+         *
+         * @example
+         * ```typescript
+         * const report = await service.getReport('BTCUSDT');
+         * console.log(report);
+         * // # 15-Minute Candles Trading Analysis for BTCUSDT (Historical Data)
+         * // > Current time: 2025-01-14T10:30:00.000Z
+         * //
+         * // | RSI(9) | MACD(8,21,5) | Support Level | ...
+         * // | 45.23 | 0.0012 | 42000.50 USD | ...
+         * ```
+         */
         this.getReport = async (symbol) => {
             this.loggerService.log("shortTermHistoryService getReport", { symbol });
             const candles = await backtestKit.getCandles(symbol, "15m", 144);
             const rows = await this.getData(symbol, candles);
             return generateHistoryTable$1(rows, symbol);
         };
+        /**
+         * Converts analysis rows into markdown table format.
+         *
+         * Takes pre-calculated indicator rows and formats them as markdown table
+         * with column headers, formatted values, and data source explanations.
+         *
+         * @param symbol - Trading pair symbol for price formatting
+         * @param rows - Array of technical analysis rows from getData()
+         * @returns Markdown-formatted table with all indicators
+         *
+         * @example
+         * ```typescript
+         * const candles = await getCandles('BTCUSDT', '15m', 144);
+         * const rows = await service.getData('BTCUSDT', candles);
+         * const markdown = await service.generateHistoryTable('BTCUSDT', rows);
+         * console.log(markdown); // Markdown table
+         * ```
+         */
         this.generateHistoryTable = async (symbol, rows) => {
             this.loggerService.log("shortTermHistoryService generateHistoryTable", {
                 symbol,
@@ -1830,7 +2515,15 @@ class ShortTermHistoryService {
     }
 }
 
+/**
+ * Maximum number of historical rows to return in analysis results.
+ * Limits memory usage and table size for markdown reports.
+ */
 const TABLE_ROWS_LIMIT = 30;
+/**
+ * Minimum number of candles required before generating analysis rows.
+ * Ensures all technical indicators (especially EMA(34)) have sufficient data.
+ */
 const WARMUP_PERIOD = 34;
 const columns = [
     {
@@ -2029,6 +2722,23 @@ const columns = [
         format: (v) => new Date(v).toISOString(),
     },
 ];
+/**
+ * Validates whether a numeric value is safe for calculations.
+ *
+ * Checks if value is a valid finite number. Returns true if value is null,
+ * NaN, Infinity, or not a number type.
+ *
+ * @param value - Value to validate
+ * @returns True if value is unsafe (null/NaN/Infinity), false if valid number
+ *
+ * @example
+ * ```typescript
+ * isUnsafe(42) // false - valid number
+ * isUnsafe(null) // true - null value
+ * isUnsafe(NaN) // true - not a number
+ * isUnsafe(Infinity) // true - infinite value
+ * ```
+ */
 function isUnsafe$1(value) {
     if (typeof value !== "number") {
         return true;
@@ -2041,6 +2751,31 @@ function isUnsafe$1(value) {
     }
     return false;
 }
+/**
+ * Calculates Fibonacci levels and determines nearest support/resistance levels.
+ *
+ * Computes Fibonacci retracement levels (0%, 23.6%, 38.2%, 50%, 61.8%, 78.6%, 100%)
+ * and extension levels (127.2%, 161.8%, 261.8%) over specified lookback period.
+ * Identifies current price position relative to Fibonacci levels and finds
+ * nearest support/resistance levels.
+ *
+ * @param candles - Array of candle data
+ * @param endIndex - Index of current candle in array
+ * @param period - Lookback period in candles (default: 48)
+ * @returns Object with nearest support/resistance prices and current level description
+ *
+ * @example
+ * ```typescript
+ * const candles = await getCandles('BTCUSDT', '30m', 96);
+ * const fib = calculateFibonacciLevels(candles, 95, 48);
+ * console.log(fib);
+ * // {
+ * //   nearestSupport: 42000.50,
+ * //   nearestResistance: 43500.25,
+ * //   currentLevel: "50.0% Retracement"
+ * // }
+ * ```
+ */
 function calculateFibonacciLevels(candles, endIndex, period = 48) {
     if (endIndex + 1 < period) {
         return {
@@ -2127,6 +2862,25 @@ function calculateFibonacciLevels(candles, endIndex, period = 48) {
         currentLevel,
     };
 }
+/**
+ * Calculates support and resistance levels from recent high/low prices.
+ *
+ * Identifies support (minimum low) and resistance (maximum high) levels
+ * over specified window period. Falls back to current price if insufficient data.
+ *
+ * @param candles - Array of candle data
+ * @param endIndex - Index of current candle in array
+ * @param window - Lookback window in candles (default: 20)
+ * @returns Object with support and resistance price levels
+ *
+ * @example
+ * ```typescript
+ * const candles = await getCandles('ETHUSDT', '30m', 96);
+ * const levels = calculateSupportResistance(candles, 95, 20);
+ * console.log(levels);
+ * // { support: 2200.50, resistance: 2350.75 }
+ * ```
+ */
 function calculateSupportResistance(candles, endIndex, window = 20) {
     const startIdx = Math.max(0, endIndex + 1 - window);
     const recentHighs = candles
@@ -2142,6 +2896,31 @@ function calculateSupportResistance(candles, endIndex, window = 20) {
     const resistance = recentHighs.length > 0 ? Math.max(...recentHighs) : currentPrice;
     return { support, resistance };
 }
+/**
+ * Generates comprehensive technical analysis for 30-minute candles (swing trading).
+ *
+ * Calculates 25+ technical indicators per candle including:
+ * - Momentum: RSI(14), Stochastic RSI(14), MACD(12,26,9), Momentum(8), Price Momentum(6)
+ * - Trend: SMA(20), EMA(13,34), DEMA(21), WMA(20), ADX(14), +DI/-DI
+ * - Volatility: ATR(14), Bollinger Bands(20,2.0), calculated volatility
+ * - Support/Resistance: Pivot points, Fibonacci levels with nearest support/resistance
+ * - Volume analysis
+ *
+ * Skips first WARMUP_PERIOD (34) candles to ensure indicator stability.
+ * Returns last TABLE_ROWS_LIMIT (30) rows for memory efficiency.
+ *
+ * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+ * @param candles - Array of 30-minute candle data
+ * @returns Array of technical analysis rows with all indicators
+ *
+ * @example
+ * ```typescript
+ * const candles = await getCandles('BTCUSDT', '30m', 96);
+ * const analysis = generateAnalysis('BTCUSDT', candles);
+ * console.log(analysis[0].rsi14); // 52.45
+ * console.log(analysis[0].fibonacciCurrentLevel); // "50.0% Retracement"
+ * ```
+ */
 function generateAnalysis(symbol, candles) {
     const closes = candles.map((candle) => Number(candle.close));
     const highs = candles.map((candle) => Number(candle.high));
@@ -2318,6 +3097,32 @@ function generateAnalysis(symbol, candles) {
     // Return only the last TABLE_ROWS_LIMIT rows
     return results.slice(-TABLE_ROWS_LIMIT);
 }
+/**
+ * Generates markdown table with swing trading technical analysis history.
+ *
+ * Creates comprehensive markdown report with:
+ * - Formatted table of all technical indicators
+ * - Column headers with indicator names and parameters
+ * - Formatted values (prices in USD, percentages, decimals)
+ * - Data sources section explaining each indicator's calculation
+ * - Timeframe and lookback period documentation (30m candles, 48h lookback)
+ *
+ * Output is optimized for LLM consumption in swing trading signal generation.
+ *
+ * @param indicators - Array of analysis rows from generateAnalysis()
+ * @param symbol - Trading pair symbol for price formatting
+ * @returns Markdown-formatted technical analysis report
+ *
+ * @example
+ * ```typescript
+ * const rows = await service.getData('BTCUSDT', candles);
+ * const markdown = await generateHistoryTable(rows, 'BTCUSDT');
+ * console.log(markdown);
+ * // # 30-Min Candles Analysis for BTCUSDT (Historical Data)
+ * // > Current time: 2025-01-14T10:30:00.000Z
+ * // | RSI(14) | MACD(12,26,9) | Fibonacci Current Level | ... |
+ * ```
+ */
 async function generateHistoryTable(indicators, symbol) {
     let markdown = "";
     const currentData = await backtestKit.getDate();
@@ -2402,9 +3207,63 @@ async function generateHistoryTable(indicators, symbol) {
         "- **Volatility**: volatility percentage at row timestamp (Min: 0%, Max: +∞)\n";
     return markdown;
 }
+/**
+ * Service for swing-term (30-minute) technical analysis and markdown report generation.
+ *
+ * Provides comprehensive technical analysis for 30-minute candles with 25+ indicators
+ * including momentum (RSI, MACD), trend (EMA, SMA), volatility (ATR, Bollinger Bands),
+ * support/resistance levels, and Fibonacci analysis with nearest support/resistance.
+ *
+ * Key features:
+ * - 25+ technical indicators (RSI, MACD, Bollinger Bands, Stochastic, ADX, etc.)
+ * - Support/resistance level detection
+ * - Fibonacci retracement and extension analysis with nearest levels
+ * - Volume and volatility analysis
+ * - Price momentum tracking
+ * - Markdown table generation for LLM consumption
+ * - Intelligent indicator warmup (skips first 34 candles)
+ * - Memory-efficient output (last 30 rows only)
+ * - Dependency injection support
+ *
+ * @example
+ * ```typescript
+ * import { SwingTermHistoryService } from '@backtest-kit/signals';
+ *
+ * const service = new SwingTermHistoryService();
+ *
+ * // Get markdown report for symbol (fetches candles internally)
+ * const report = await service.getReport('BTCUSDT');
+ * console.log(report); // Markdown table with all indicators
+ *
+ * // Or analyze custom candles
+ * const candles = await getCandles('ETHUSDT', '30m', 96);
+ * const rows = await service.getData('ETHUSDT', candles);
+ * console.log(rows[0].rsi14); // 52.45
+ * console.log(rows[0].fibonacciCurrentLevel); // "50.0% Retracement"
+ * ```
+ */
 class SwingTermHistoryService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
+        /**
+         * Analyzes candle data and returns technical indicator rows.
+         *
+         * Calculates all technical indicators for provided candles, skips first WARMUP_PERIOD
+         * rows to ensure stability, and returns last TABLE_ROWS_LIMIT rows.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @param candles - Array of 30-minute candle data
+         * @returns Array of technical analysis rows with all indicators
+         *
+         * @example
+         * ```typescript
+         * const candles = await getCandles('BTCUSDT', '30m', 96);
+         * const rows = await service.getData('BTCUSDT', candles);
+         * console.log(rows.length); // Up to 30 rows
+         * console.log(rows[0].rsi14); // 52.45
+         * console.log(rows[0].fibonacciNearestSupport); // 42000.50
+         * ```
+         */
         this.getData = async (symbol, candles) => {
             this.loggerService.log("swingTermHistoryService getData", {
                 symbol,
@@ -2412,12 +3271,50 @@ class SwingTermHistoryService {
             });
             return generateAnalysis(symbol, candles);
         };
+        /**
+         * Generates complete markdown technical analysis report for a symbol.
+         *
+         * Fetches 96 30-minute candles (48 hours) from exchange, calculates all indicators,
+         * and formats results as markdown table optimized for LLM consumption.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @returns Markdown-formatted technical analysis report with table and explanations
+         *
+         * @example
+         * ```typescript
+         * const report = await service.getReport('BTCUSDT');
+         * console.log(report);
+         * // # 30-Min Candles Analysis for BTCUSDT (Historical Data)
+         * // > Current time: 2025-01-14T10:30:00.000Z
+         * //
+         * // | RSI(14) | MACD(12,26,9) | Fibonacci Current Level | ...
+         * // | 52.45 | 0.0023 | 50.0% Retracement | ...
+         * ```
+         */
         this.getReport = async (symbol) => {
             this.loggerService.log("swingTermHistoryService getReport", { symbol });
             const candles = await backtestKit.getCandles(symbol, "30m", 96);
             const rows = await this.getData(symbol, candles);
             return generateHistoryTable(rows, symbol);
         };
+        /**
+         * Converts analysis rows into markdown table format.
+         *
+         * Takes pre-calculated indicator rows and formats them as markdown table
+         * with column headers, formatted values, and data source explanations.
+         *
+         * @param symbol - Trading pair symbol for price formatting
+         * @param rows - Array of technical analysis rows from getData()
+         * @returns Markdown-formatted table with all indicators
+         *
+         * @example
+         * ```typescript
+         * const candles = await getCandles('BTCUSDT', '30m', 96);
+         * const rows = await service.getData('BTCUSDT', candles);
+         * const markdown = await service.generateHistoryTable('BTCUSDT', rows);
+         * console.log(markdown); // Markdown table
+         * ```
+         */
         this.generateHistoryTable = async (symbol, rows) => {
             this.loggerService.log("swingTermHistoryService generateHistoryTable", {
                 symbol,
@@ -2428,14 +3325,102 @@ class SwingTermHistoryService {
     }
 }
 
+/**
+ * Fifteen-minute candle history service for day trading analysis.
+ *
+ * Generates markdown reports of the last 8 fifteen-minute candles including:
+ * - OHLCV data with high-volatility detection
+ * - Candle type (Green/Red/Doji)
+ * - Volatility percentage (flagged if >1.5x average)
+ * - Body size percentage
+ * - Timestamp
+ *
+ * Used by commitFifteenMinuteHistory() for LLM context injection.
+ */
+/**
+ * Number of recent candles to include in history report.
+ * Provides 2-hour price action context for day trading decisions.
+ */
 const RECENT_CANDLES$3 = 8;
+/**
+ * Service for generating 15-minute candle history reports for day trading analysis.
+ *
+ * Provides detailed OHLCV analysis for the last 8 fifteen-minute candles with
+ * candle pattern identification, volatility metrics, high-volatility detection,
+ * and body size calculations.
+ *
+ * Key features:
+ * - Last 8 fifteen-minute candles (2 hours of price action)
+ * - OHLCV data with formatted prices and volumes
+ * - Candle type identification (Green/Red/Doji)
+ * - Volatility percentage calculations
+ * - High-volatility detection (>1.5x average volatility)
+ * - Body size percentage relative to candle range
+ * - ISO timestamp formatting
+ * - Dependency injection support
+ *
+ * @example
+ * ```typescript
+ * import { FifteenMinuteCandleHistoryService } from '@backtest-kit/signals';
+ *
+ * const service = new FifteenMinuteCandleHistoryService();
+ *
+ * // Get markdown report
+ * const report = await service.getReport('BTCUSDT');
+ * console.log(report);
+ * // ## 15-Minute Candles History (Last 8)
+ * // ### 15m Candle 1 (Green) HIGH-VOLATILITY
+ * // - **Open**: 42000.50 USD
+ * // - **15m Volatility**: 0.85%
+ *
+ * // Or get raw candle data
+ * const candles = await service.getData('ETHUSDT');
+ * console.log(candles.length); // 8
+ * ```
+ */
 class FifteenMinuteCandleHistoryService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
+        /**
+         * Fetches last 8 fifteen-minute candles for a symbol.
+         *
+         * Retrieves recent 15-minute candles from exchange for day trading analysis.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @returns Array of 8 fifteen-minute candles
+         *
+         * @example
+         * ```typescript
+         * const candles = await service.getData('BTCUSDT');
+         * console.log(candles.length); // 8
+         * console.log(candles[0].close); // Latest candle close price
+         * ```
+         */
         this.getData = async (symbol) => {
             this.loggerService.log("fifteenMinuteCandleHistoryService getData", { symbol });
             return backtestKit.getCandles(symbol, "15m", RECENT_CANDLES$3);
         };
+        /**
+         * Generates markdown report from candle data with volatility detection.
+         *
+         * Creates detailed markdown report with OHLCV data, candle patterns,
+         * volatility metrics, and HIGH-VOLATILITY flags for candles exceeding
+         * 1.5x the average volatility of all candles.
+         *
+         * @param symbol - Trading pair symbol for price formatting
+         * @param candles - Array of candle data to analyze
+         * @returns Markdown-formatted candle history report with volatility flags
+         *
+         * @example
+         * ```typescript
+         * const candles = await service.getData('BTCUSDT');
+         * const report = await service.generateReport('BTCUSDT', candles);
+         * console.log(report);
+         * // ## 15-Minute Candles History (Last 8)
+         * // ### 15m Candle 1 (Green) HIGH-VOLATILITY
+         * // - **Open**: 42000.50 USD
+         * ```
+         */
         this.generateReport = async (symbol, candles) => {
             this.loggerService.log("fifteenMinuteCandleHistoryService generateReport", { symbol });
             const averageVolatility = candles.reduce((sum, candle) => sum + ((candle.high - candle.low) / candle.close) * 100, 0) / candles.length;
@@ -2468,6 +3453,28 @@ class FifteenMinuteCandleHistoryService {
             }
             return report;
         };
+        /**
+         * Generates complete markdown candle history report for a symbol.
+         *
+         * Fetches last 8 fifteen-minute candles and formats them as markdown report
+         * with OHLCV data, patterns, volatility flags, and metrics.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @returns Markdown-formatted candle history report with high-volatility detection
+         *
+         * @example
+         * ```typescript
+         * const report = await service.getReport('BTCUSDT');
+         * console.log(report);
+         * // ## 15-Minute Candles History (Last 8)
+         * // > Current time: 2025-01-14T10:30:00.000Z
+         * //
+         * // ### 15m Candle 1 (Green) HIGH-VOLATILITY
+         * // - **Time**: 2025-01-14T10:15:00.000Z
+         * // - **Open**: 42000.50 USD
+         * // - **15m Volatility**: 0.85%
+         * ```
+         */
         this.getReport = async (symbol) => {
             this.loggerService.log("fifteenMinuteCandleHistoryService getReport", { symbol });
             const candles = await this.getData(symbol);
@@ -2476,14 +3483,99 @@ class FifteenMinuteCandleHistoryService {
     }
 }
 
+/**
+ * Hourly candle history service for trend analysis.
+ *
+ * Generates markdown reports of the last 6 hourly candles including:
+ * - OHLCV data
+ * - Candle type (Green/Red/Doji)
+ * - Volatility percentage
+ * - Body size percentage
+ * - Timestamp
+ *
+ * Used by commitHourHistory() for LLM context injection.
+ */
+/**
+ * Number of recent candles to include in history report.
+ * Provides 6-hour price action context for long-term trading decisions.
+ */
 const RECENT_CANDLES$2 = 6;
+/**
+ * Service for generating 1-hour candle history reports for trend analysis.
+ *
+ * Provides detailed OHLCV analysis for the last 6 hourly candles with
+ * candle pattern identification, volatility metrics, and body size calculations.
+ *
+ * Key features:
+ * - Last 6 hourly candles (6 hours of price action)
+ * - OHLCV data with formatted prices and volumes
+ * - Candle type identification (Green/Red/Doji)
+ * - Volatility percentage calculations
+ * - Body size percentage relative to candle range
+ * - ISO timestamp formatting
+ * - Dependency injection support
+ *
+ * @example
+ * ```typescript
+ * import { HourCandleHistoryService } from '@backtest-kit/signals';
+ *
+ * const service = new HourCandleHistoryService();
+ *
+ * // Get markdown report
+ * const report = await service.getReport('BTCUSDT');
+ * console.log(report);
+ * // ## Hourly Candles History (Last 6)
+ * // ### 1h Candle 1 (Green)
+ * // - **Open**: 42000.50 USD
+ * // - **1h Volatility**: 2.15%
+ *
+ * // Or get raw candle data
+ * const candles = await service.getData('ETHUSDT');
+ * console.log(candles.length); // 6
+ * ```
+ */
 class HourCandleHistoryService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
+        /**
+         * Fetches last 6 hourly candles for a symbol.
+         *
+         * Retrieves recent 1-hour candles from exchange for trend analysis.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @returns Array of 6 hourly candles
+         *
+         * @example
+         * ```typescript
+         * const candles = await service.getData('BTCUSDT');
+         * console.log(candles.length); // 6
+         * console.log(candles[0].close); // Latest candle close price
+         * ```
+         */
         this.getData = async (symbol) => {
             this.loggerService.log("hourCandleHistoryService getData", { symbol });
             return backtestKit.getCandles(symbol, "1h", RECENT_CANDLES$2);
         };
+        /**
+         * Generates markdown report from candle data.
+         *
+         * Creates detailed markdown report with OHLCV data, candle patterns,
+         * volatility metrics, and body size percentages for each candle.
+         *
+         * @param symbol - Trading pair symbol for price formatting
+         * @param candles - Array of candle data to analyze
+         * @returns Markdown-formatted candle history report
+         *
+         * @example
+         * ```typescript
+         * const candles = await service.getData('BTCUSDT');
+         * const report = await service.generateReport('BTCUSDT', candles);
+         * console.log(report);
+         * // ## Hourly Candles History (Last 6)
+         * // ### 1h Candle 1 (Green)
+         * // - **Open**: 42000.50 USD
+         * ```
+         */
         this.generateReport = async (symbol, candles) => {
             this.loggerService.log("hourCandleHistoryService generateReport", { symbol });
             let markdown = "";
@@ -2514,6 +3606,28 @@ class HourCandleHistoryService {
             }
             return markdown;
         };
+        /**
+         * Generates complete markdown candle history report for a symbol.
+         *
+         * Fetches last 6 hourly candles and formats them as markdown report
+         * with OHLCV data, patterns, and metrics.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @returns Markdown-formatted candle history report
+         *
+         * @example
+         * ```typescript
+         * const report = await service.getReport('BTCUSDT');
+         * console.log(report);
+         * // ## Hourly Candles History (Last 6)
+         * // > Current time: 2025-01-14T10:30:00.000Z
+         * //
+         * // ### 1h Candle 1 (Green)
+         * // - **Time**: 2025-01-14T10:00:00.000Z
+         * // - **Open**: 42000.50 USD
+         * // - **1h Volatility**: 2.15%
+         * ```
+         */
         this.getReport = async (symbol) => {
             this.loggerService.log("hourCandleHistoryService getReport", { symbol });
             const candles = await this.getData(symbol);
@@ -2522,14 +3636,99 @@ class HourCandleHistoryService {
     }
 }
 
+/**
+ * One-minute candle history service for ultra-short term analysis.
+ *
+ * Generates markdown reports of the last 15 one-minute candles including:
+ * - OHLCV data (Open, High, Low, Close, Volume)
+ * - Candle type (Green/Red/Doji)
+ * - Volatility percentage
+ * - Body size percentage
+ * - Timestamp
+ *
+ * Used by commitOneMinuteHistory() for LLM context injection.
+ */
+/**
+ * Number of recent candles to include in history report.
+ * Provides 15-minute price action context for scalping decisions.
+ */
 const RECENT_CANDLES$1 = 15;
+/**
+ * Service for generating 1-minute candle history reports for scalping analysis.
+ *
+ * Provides detailed OHLCV analysis for the last 15 one-minute candles with
+ * candle pattern identification, volatility metrics, and body size calculations.
+ *
+ * Key features:
+ * - Last 15 one-minute candles (15 minutes of price action)
+ * - OHLCV data with formatted prices and volumes
+ * - Candle type identification (Green/Red/Doji)
+ * - Volatility percentage calculations
+ * - Body size percentage relative to candle range
+ * - ISO timestamp formatting
+ * - Dependency injection support
+ *
+ * @example
+ * ```typescript
+ * import { OneMinuteCandleHistoryService } from '@backtest-kit/signals';
+ *
+ * const service = new OneMinuteCandleHistoryService();
+ *
+ * // Get markdown report
+ * const report = await service.getReport('BTCUSDT');
+ * console.log(report);
+ * // ## One-Minute Candles History (Last 15)
+ * // ### 1m Candle 1 (Green)
+ * // - **Open**: 42000.50 USD
+ * // - **1m Volatility**: 0.15%
+ *
+ * // Or get raw candle data
+ * const candles = await service.getData('ETHUSDT');
+ * console.log(candles.length); // 15
+ * ```
+ */
 class OneMinuteCandleHistoryService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
+        /**
+         * Fetches last 15 one-minute candles for a symbol.
+         *
+         * Retrieves recent 1-minute candles from exchange for scalping analysis.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @returns Array of 15 one-minute candles
+         *
+         * @example
+         * ```typescript
+         * const candles = await service.getData('BTCUSDT');
+         * console.log(candles.length); // 15
+         * console.log(candles[0].close); // Latest candle close price
+         * ```
+         */
         this.getData = async (symbol) => {
             this.loggerService.log("oneMinuteCandleHistoryService getData", { symbol });
             return backtestKit.getCandles(symbol, "1m", RECENT_CANDLES$1);
         };
+        /**
+         * Generates markdown report from candle data.
+         *
+         * Creates detailed markdown report with OHLCV data, candle patterns,
+         * volatility metrics, and body size percentages for each candle.
+         *
+         * @param symbol - Trading pair symbol for price formatting
+         * @param candles - Array of candle data to analyze
+         * @returns Markdown-formatted candle history report
+         *
+         * @example
+         * ```typescript
+         * const candles = await service.getData('BTCUSDT');
+         * const report = await service.generateReport('BTCUSDT', candles);
+         * console.log(report);
+         * // ## One-Minute Candles History (Last 15)
+         * // ### 1m Candle 1 (Green)
+         * // - **Open**: 42000.50 USD
+         * ```
+         */
         this.generateReport = async (symbol, candles) => {
             this.loggerService.log("oneMinuteCandleHistoryService generateReport", { symbol });
             let markdown = "";
@@ -2556,6 +3755,28 @@ class OneMinuteCandleHistoryService {
             }
             return markdown;
         };
+        /**
+         * Generates complete markdown candle history report for a symbol.
+         *
+         * Fetches last 15 one-minute candles and formats them as markdown report
+         * with OHLCV data, patterns, and metrics.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @returns Markdown-formatted candle history report
+         *
+         * @example
+         * ```typescript
+         * const report = await service.getReport('BTCUSDT');
+         * console.log(report);
+         * // ## One-Minute Candles History (Last 15)
+         * // > Current time: 2025-01-14T10:30:00.000Z
+         * //
+         * // ### 1m Candle 1 (Green)
+         * // - **Time**: 2025-01-14T10:29:00.000Z
+         * // - **Open**: 42000.50 USD
+         * // - **1m Volatility**: 0.15%
+         * ```
+         */
         this.getReport = async (symbol) => {
             this.loggerService.log("oneMinuteCandleHistoryService getReport", { symbol });
             const candles = await this.getData(symbol);
@@ -2564,14 +3785,99 @@ class OneMinuteCandleHistoryService {
     }
 }
 
+/**
+ * Thirty-minute candle history service for swing trading analysis.
+ *
+ * Generates markdown reports of the last 6 thirty-minute candles including:
+ * - OHLCV data
+ * - Candle type (Green/Red/Doji)
+ * - Volatility percentage
+ * - Body size percentage
+ * - Timestamp
+ *
+ * Used by commitThirtyMinuteHistory() for LLM context injection.
+ */
+/**
+ * Number of recent candles to include in history report.
+ * Provides 3-hour price action context for swing trading decisions.
+ */
 const RECENT_CANDLES = 6;
+/**
+ * Service for generating 30-minute candle history reports for swing trading analysis.
+ *
+ * Provides detailed OHLCV analysis for the last 6 thirty-minute candles with
+ * candle pattern identification, volatility metrics, and body size calculations.
+ *
+ * Key features:
+ * - Last 6 thirty-minute candles (3 hours of price action)
+ * - OHLCV data with formatted prices and volumes
+ * - Candle type identification (Green/Red/Doji)
+ * - Volatility percentage calculations
+ * - Body size percentage relative to candle range
+ * - ISO timestamp formatting
+ * - Dependency injection support
+ *
+ * @example
+ * ```typescript
+ * import { ThirtyMinuteCandleHistoryService } from '@backtest-kit/signals';
+ *
+ * const service = new ThirtyMinuteCandleHistoryService();
+ *
+ * // Get markdown report
+ * const report = await service.getReport('BTCUSDT');
+ * console.log(report);
+ * // ## 30-Min Candles History (Last 6)
+ * // ### 30m Candle 1 (Green)
+ * // - **Open**: 42000.50 USD
+ * // - **30m Volatility**: 1.25%
+ *
+ * // Or get raw candle data
+ * const candles = await service.getData('ETHUSDT');
+ * console.log(candles.length); // 6
+ * ```
+ */
 class ThirtyMinuteCandleHistoryService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
+        /**
+         * Fetches last 6 thirty-minute candles for a symbol.
+         *
+         * Retrieves recent 30-minute candles from exchange for analysis.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @returns Array of 6 thirty-minute candles
+         *
+         * @example
+         * ```typescript
+         * const candles = await service.getData('BTCUSDT');
+         * console.log(candles.length); // 6
+         * console.log(candles[0].close); // Latest candle close price
+         * ```
+         */
         this.getData = async (symbol) => {
             this.loggerService.log("thirtyMinuteCandleHistoryService getData", { symbol });
             return backtestKit.getCandles(symbol, "30m", RECENT_CANDLES);
         };
+        /**
+         * Generates markdown report from candle data.
+         *
+         * Creates detailed markdown report with OHLCV data, candle patterns,
+         * volatility metrics, and body size percentages for each candle.
+         *
+         * @param symbol - Trading pair symbol for price formatting
+         * @param candles - Array of candle data to analyze
+         * @returns Markdown-formatted candle history report
+         *
+         * @example
+         * ```typescript
+         * const candles = await service.getData('BTCUSDT');
+         * const report = await service.generateReport('BTCUSDT', candles);
+         * console.log(report);
+         * // ## 30-Min Candles History (Last 6)
+         * // ### 30m Candle 1 (Green)
+         * // - **Open**: 42000.50 USD
+         * ```
+         */
         this.generateReport = async (symbol, candles) => {
             this.loggerService.log("thirtyMinuteCandleHistoryService generateReport", { symbol });
             let report = "";
@@ -2602,6 +3908,28 @@ class ThirtyMinuteCandleHistoryService {
             }
             return report;
         };
+        /**
+         * Generates complete markdown candle history report for a symbol.
+         *
+         * Fetches last 6 thirty-minute candles and formats them as markdown report
+         * with OHLCV data, patterns, and metrics.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @returns Markdown-formatted candle history report
+         *
+         * @example
+         * ```typescript
+         * const report = await service.getReport('BTCUSDT');
+         * console.log(report);
+         * // ## 30-Min Candles History (Last 6)
+         * // > Current time: 2025-01-14T10:30:00.000Z
+         * //
+         * // ### 30m Candle 1 (Green)
+         * // - **Time**: 2025-01-14T10:00:00.000Z
+         * // - **Open**: 42000.50 USD
+         * // - **30m Volatility**: 1.25%
+         * ```
+         */
         this.getReport = async (symbol) => {
             this.loggerService.log("thirtyMinuteCandleHistoryService getReport", { symbol });
             const candles = await this.getData(symbol);
@@ -2610,6 +3938,46 @@ class ThirtyMinuteCandleHistoryService {
     }
 }
 
+/**
+ * Order book analysis service for real-time market depth and liquidity assessment.
+ *
+ * Generates comprehensive order book reports including:
+ * - Top 20 bid/ask levels sorted by volume percentage
+ * - Best bid/ask prices
+ * - Mid price and spread
+ * - Depth imbalance (buy vs sell pressure indicator)
+ *
+ * Depth Imbalance Formula:
+ * (Total Bid Volume - Total Ask Volume) / (Total Bid Volume + Total Ask Volume)
+ * - Positive: Buy pressure (more bids)
+ * - Negative: Sell pressure (more asks)
+ * - Zero: Balanced market
+ *
+ * Used by commitBookDataReport() for LLM context injection.
+ * Only available in live mode (skipped in backtest mode).
+ */
+/**
+ * Maximum order book depth levels to fetch for accurate metrics.
+ * Provides comprehensive liquidity view for depth imbalance calculation.
+ */
+const MAX_DEPTH_LEVELS = 1000;
+/**
+ * Validates whether a numeric value is safe for calculations.
+ *
+ * Checks if value is a valid finite number. Returns true if value is null,
+ * NaN, Infinity, or not a number type.
+ *
+ * @param value - Value to validate
+ * @returns True if value is unsafe (null/NaN/Infinity), false if valid number
+ *
+ * @example
+ * ```typescript
+ * isUnsafe(42) // false - valid number
+ * isUnsafe(null) // true - null value
+ * isUnsafe(NaN) // true - not a number
+ * isUnsafe(Infinity) // true - infinite value
+ * ```
+ */
 function isUnsafe(value) {
     if (typeof value !== "number") {
         return true;
@@ -2622,7 +3990,28 @@ function isUnsafe(value) {
     }
     return false;
 }
-const MAX_DEPTH_LEVELS = 1000; // Maximum depth for more accurate metrics
+/**
+ * Processes one side of order book (bids or asks) and calculates volume percentages.
+ *
+ * Converts raw bid/ask data to structured entries with volume percentage calculations.
+ * Each entry's percentage represents its share of total side volume.
+ *
+ * @param orders - Raw order book entries from exchange API
+ * @returns Processed entries with price, quantity, and volume percentage
+ *
+ * @example
+ * ```typescript
+ * const rawBids = [
+ *   { price: "42000", quantity: "1.5" },
+ *   { price: "41999", quantity: "0.5" }
+ * ];
+ * const processed = processOrderBookSide(rawBids);
+ * // [
+ * //   { price: 42000, quantity: 1.5, percentage: 75.0 },
+ * //   { price: 41999, quantity: 0.5, percentage: 25.0 }
+ * // ]
+ * ```
+ */
 function processOrderBookSide(orders) {
     const entries = orders.map((order) => ({
         price: parseFloat(order.price),
@@ -2637,7 +4026,34 @@ function processOrderBookSide(orders) {
     });
     return entries;
 }
-// Generate simple order book report
+/**
+ * Generates markdown-formatted order book report with depth analysis.
+ *
+ * Creates comprehensive markdown report including:
+ * - Order book summary (best bid/ask, mid price, spread, depth imbalance)
+ * - Top 20 bid levels sorted by volume percentage
+ * - Top 20 ask levels sorted by volume percentage
+ * - Formatted prices and quantities with proper USD notation
+ *
+ * Output is optimized for LLM consumption in trading signal generation.
+ *
+ * @param self - Service instance for logging context
+ * @param result - Order book analysis data with calculated metrics
+ * @returns Markdown-formatted order book report
+ *
+ * @example
+ * ```typescript
+ * const analysis = await service.getData('BTCUSDT');
+ * const report = await generateBookDataReport(service, analysis);
+ * console.log(report);
+ * // # Order Book Analysis for BTCUSDT
+ * // > Current time: 2025-01-14T10:30:00.000Z
+ * // ## Order Book Summary
+ * // - **Best Bid**: 42000.50 USD
+ * // - **Best Ask**: 42001.25 USD
+ * // - **Depth Imbalance**: 12.5%
+ * ```
+ */
 const generateBookDataReport = async (self, result) => {
     const currentData = await backtestKit.getDate();
     let markdown = `# Order Book Analysis for ${result.symbol}\n`;
@@ -2702,15 +4118,88 @@ const generateBookDataReport = async (self, result) => {
     markdown += `\n`;
     return markdown;
 };
+/**
+ * Service for order book analysis and markdown report generation.
+ *
+ * Provides real-time order book depth analysis with market liquidity metrics
+ * including bid/ask levels, depth imbalance, spread, and volume distribution.
+ *
+ * Key features:
+ * - Fetches up to 1000 order book depth levels
+ * - Calculates best bid/ask, mid price, and spread
+ * - Computes depth imbalance (buy vs sell pressure)
+ * - Analyzes volume distribution with percentage calculations
+ * - Generates markdown reports with top 20 levels
+ * - Only available in live mode (skipped in backtest)
+ * - Dependency injection support
+ *
+ * @example
+ * ```typescript
+ * import { BookDataMathService } from '@backtest-kit/signals';
+ *
+ * const service = new BookDataMathService();
+ *
+ * // Get markdown report (fetches order book internally)
+ * const report = await service.getReport('BTCUSDT');
+ * console.log(report); // Markdown with top 20 bid/ask levels
+ *
+ * // Or analyze custom order book data
+ * const analysis = await service.getData('ETHUSDT');
+ * console.log(analysis.depthImbalance); // 0.125 (12.5% buy pressure)
+ * console.log(analysis.bestBid); // 2300.50
+ * ```
+ */
 class BookDataMathService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
+        /**
+         * Converts order book analysis into markdown report format.
+         *
+         * Takes pre-calculated order book analysis and formats it as markdown
+         * with summary metrics and top 20 bid/ask levels sorted by volume.
+         *
+         * @param symbol - Trading pair symbol for header
+         * @param bookData - Order book analysis from getData()
+         * @returns Markdown-formatted order book report
+         *
+         * @example
+         * ```typescript
+         * const analysis = await service.getData('BTCUSDT');
+         * const report = await service.generateReport('BTCUSDT', analysis);
+         * console.log(report); // Markdown table with order book data
+         * ```
+         */
         this.generateReport = async (symbol, bookData) => {
             this.loggerService.log("bookDataMathService generateReport", {
                 symbol,
             });
             return await generateBookDataReport(this, bookData);
         };
+        /**
+         * Generates complete markdown order book report for a symbol.
+         *
+         * Fetches order book depth (up to 1000 levels) from exchange, calculates all metrics,
+         * and formats results as markdown report optimized for LLM consumption.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @returns Markdown-formatted order book report with depth analysis
+         *
+         * @example
+         * ```typescript
+         * const report = await service.getReport('BTCUSDT');
+         * console.log(report);
+         * // # Order Book Analysis for BTCUSDT
+         * // > Current time: 2025-01-14T10:30:00.000Z
+         * //
+         * // ## Order Book Summary
+         * // - **Best Bid**: 42000.50 USD
+         * // - **Depth Imbalance**: 12.5%
+         * //
+         * // ## Top 20 Order Book Levels
+         * // ### Bids (Buy Orders)
+         * // | Price | Quantity | % of Total |
+         * ```
+         */
         this.getReport = async (symbol) => {
             this.loggerService.log("bookDataMathService getReport", {
                 symbol,
@@ -2718,6 +4207,26 @@ class BookDataMathService {
             const bookData = await this.getData(symbol);
             return await this.generateReport(symbol, bookData);
         };
+        /**
+         * Fetches and analyzes order book data with depth metrics.
+         *
+         * Retrieves up to 1000 depth levels from exchange, processes bid/ask data,
+         * calculates volume percentages, and computes market depth metrics including
+         * best bid/ask, mid price, spread, and depth imbalance.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @returns Order book analysis with all calculated metrics
+         *
+         * @example
+         * ```typescript
+         * const analysis = await service.getData('BTCUSDT');
+         * console.log(analysis.bestBid); // 42000.50
+         * console.log(analysis.bestAsk); // 42001.25
+         * console.log(analysis.spread); // 0.75
+         * console.log(analysis.depthImbalance); // 0.125 (12.5% buy pressure)
+         * console.log(analysis.bids.length); // Up to 1000 levels
+         * ```
+         */
         this.getData = async (symbol) => {
             this.loggerService.log("bookDataMathService getBookDataAnalysis", {
                 symbol,
@@ -2751,6 +4260,28 @@ class BookDataMathService {
     }
 }
 
+/**
+ * Logger service for signals library diagnostic output.
+ *
+ * Provides logging capabilities with a no-op default implementation.
+ * Use setLogger() from the public API to enable actual logging output.
+ *
+ * @example
+ * ```typescript
+ * import { setLogger } from '@backtest-kit/signals';
+ *
+ * setLogger({
+ *   log: console.log,
+ *   debug: console.debug,
+ *   info: console.info,
+ *   warn: console.warn,
+ * });
+ * ```
+ */
+/**
+ * No-op logger implementation that discards all log calls.
+ * Used as default to avoid polluting console output.
+ */
 const NOOP_LOGGER = {
     log() {
     },
@@ -2761,30 +4292,133 @@ const NOOP_LOGGER = {
     warn() {
     },
 };
+/**
+ * Logger service implementation with configurable backend.
+ *
+ * Delegates all logging calls to the configured logger implementation.
+ * Defaults to NOOP_LOGGER which discards all output.
+ */
 class LoggerService {
     constructor() {
         this._commonLogger = NOOP_LOGGER;
+        /**
+         * Logs general messages with topic and optional arguments.
+         *
+         * Delegates to configured logger implementation. Uses no-op logger by default
+         * until setLogger() is called with custom implementation.
+         *
+         * @param topic - Log topic or category identifier
+         * @param args - Additional arguments to log
+         *
+         * @example
+         * ```typescript
+         * const logger = new LoggerService();
+         * await logger.log('user-action', { userId: '123', action: 'login' });
+         * // Output depends on configured logger implementation
+         * ```
+         */
         this.log = async (topic, ...args) => {
             await this._commonLogger.log(topic, ...args);
         };
+        /**
+         * Logs debug-level messages with topic and optional arguments.
+         *
+         * Typically used for detailed diagnostic information during development.
+         * Delegates to configured logger implementation.
+         *
+         * @param topic - Debug topic or category identifier
+         * @param args - Additional arguments to log
+         *
+         * @example
+         * ```typescript
+         * const logger = new LoggerService();
+         * await logger.debug('api-call', { endpoint: '/data', params: { limit: 10 } });
+         * ```
+         */
         this.debug = async (topic, ...args) => {
             await this._commonLogger.debug(topic, ...args);
         };
+        /**
+         * Logs informational messages with topic and optional arguments.
+         *
+         * Used for general informational messages about application state or progress.
+         * Delegates to configured logger implementation.
+         *
+         * @param topic - Info topic or category identifier
+         * @param args - Additional arguments to log
+         *
+         * @example
+         * ```typescript
+         * const logger = new LoggerService();
+         * await logger.info('server-start', { port: 3000, env: 'production' });
+         * ```
+         */
         this.info = async (topic, ...args) => {
             await this._commonLogger.info(topic, ...args);
         };
+        /**
+         * Logs warning messages with topic and optional arguments.
+         *
+         * Used for potentially harmful situations that don't prevent execution.
+         * Delegates to configured logger implementation.
+         *
+         * @param topic - Warning topic or category identifier
+         * @param args - Additional arguments to log
+         *
+         * @example
+         * ```typescript
+         * const logger = new LoggerService();
+         * await logger.warn('rate-limit', { limit: 100, current: 95 });
+         * ```
+         */
         this.warn = async (topic, ...args) => {
             await this._commonLogger.warn(topic, ...args);
         };
+        /**
+         * Sets custom logger implementation.
+         *
+         * Replaces the default no-op logger with a custom implementation that
+         * conforms to the ILogger interface. Call this during application initialization
+         * to enable actual logging output.
+         *
+         * @param logger - Custom logger conforming to ILogger interface
+         *
+         * @example
+         * ```typescript
+         * const logger = new LoggerService();
+         * logger.setLogger({
+         *   log: console.log,
+         *   debug: console.debug,
+         *   info: console.info,
+         *   warn: console.warn,
+         * });
+         * await logger.log('test', 'now logging to console');
+         * ```
+         */
         this.setLogger = (logger) => {
             this._commonLogger = logger;
         };
     }
 }
 
+/**
+ * Service registration for signals library DI container.
+ *
+ * Registers all service factories with the dependency injection container.
+ * Services are lazily instantiated on first injection.
+ *
+ * Service categories:
+ * - Common: Logger service
+ * - Math: Technical analysis services (MicroTerm, ShortTerm, SwingTerm, LongTerm, OrderBook)
+ * - History: Candle history services (1m, 15m, 30m, 1h)
+ *
+ * @module lib/core/provide
+ */
+// Register common services
 {
     provide(TYPES.loggerService, () => new LoggerService());
 }
+// Register technical analysis services
 {
     provide(TYPES.swingTermMathService, () => new SwingTermHistoryService());
     provide(TYPES.longTermMathService, () => new LongTermHistoryService());
@@ -2792,6 +4426,7 @@ class LoggerService {
     provide(TYPES.microTermMathService, () => new MicroTermHistoryService());
     provide(TYPES.bookDataMathService, () => new BookDataMathService());
 }
+// Register candle history services
 {
     provide(TYPES.fifteenMinuteCandleHistoryService, () => new FifteenMinuteCandleHistoryService());
     provide(TYPES.hourCandleHistoryService, () => new HourCandleHistoryService());
@@ -2799,9 +4434,30 @@ class LoggerService {
     provide(TYPES.thirtyMinuteCandleHistoryService, () => new ThirtyMinuteCandleHistoryService());
 }
 
+/**
+ * Service container initialization and export for signals library.
+ *
+ * Initializes the DI container, injects all registered services,
+ * and exports them as a unified 'signal' object for internal use.
+ *
+ * This module:
+ * 1. Imports service registrations from './core/provide'
+ * 2. Injects all services from DI container
+ * 3. Initializes DI container
+ * 4. Exports combined service object
+ * 5. Attaches to globalThis for debugging (non-production only)
+ *
+ * @module lib/index
+ */
+/**
+ * Common services.
+ */
 const commonServices = {
     loggerService: inject(TYPES.loggerService),
 };
+/**
+ * Technical analysis services.
+ */
 const mathServices = {
     swingTermMathService: inject(TYPES.swingTermMathService),
     longTermMathService: inject(TYPES.longTermMathService),
@@ -2809,32 +4465,97 @@ const mathServices = {
     microTermMathService: inject(TYPES.microTermMathService),
     bookDataMathService: inject(TYPES.bookDataMathService),
 };
+/**
+ * Candle history services.
+ */
 const historyServices = {
     fifteenMinuteCandleHistoryService: inject(TYPES.fifteenMinuteCandleHistoryService),
     hourCandleHistoryService: inject(TYPES.hourCandleHistoryService),
     oneMinuteCandleHistoryService: inject(TYPES.oneMinuteCandleHistoryService),
     thirtyMinuteCandleHistoryService: inject(TYPES.thirtyMinuteCandleHistoryService),
 };
+/**
+ * Combined service container for internal library use.
+ * Contains all registered services: common, math, and history.
+ */
 const signal = {
     ...commonServices,
     ...mathServices,
     ...historyServices,
 };
+// Initialize DI container
 init();
+// Attach to global for debugging (non-production)
 Object.assign(globalThis, { signal });
 
+/**
+ * Candle history report generation functions for multi-timeframe analysis.
+ *
+ * Provides cached functions to fetch and commit OHLCV candle history reports
+ * across 4 timeframes (1m, 15m, 30m, 1h) formatted as markdown for LLM consumption.
+ * Each function automatically handles caching, error recovery, and report formatting.
+ *
+ * Key features:
+ * - Intelligent caching with timeframe-specific TTL (1m: 1min, 15m: 5min, 30m: 15min, 1h: 30min)
+ * - Automatic cache clearing on errors for data freshness
+ * - Formatted markdown tables with candle details (OHLCV, volatility, body size, candle type)
+ * - User/assistant message pair format for LLM context
+ *
+ * @module function/history
+ */
+/**
+ * Cached function to fetch 1-hour candle history report.
+ * Cache TTL: 30 minutes
+ */
 const fetchHourHistory = backtestKit.Cache.fn(signal.hourCandleHistoryService.getReport, {
     interval: "30m",
 });
+/**
+ * Cached function to fetch 30-minute candle history report.
+ * Cache TTL: 15 minutes
+ */
 const fetchThirtyMinuteHistory = backtestKit.Cache.fn(signal.thirtyMinuteCandleHistoryService.getReport, {
     interval: "15m",
 });
+/**
+ * Cached function to fetch 15-minute candle history report.
+ * Cache TTL: 5 minutes
+ */
 const fetchFifteenMinuteHistory = backtestKit.Cache.fn(signal.fifteenMinuteCandleHistoryService.getReport, {
     interval: "5m",
 });
+/**
+ * Cached function to fetch 1-minute candle history report.
+ * Cache TTL: 1 minute
+ */
 const fetchOneMinuteHistory = backtestKit.Cache.fn(signal.oneMinuteCandleHistoryService.getReport, {
     interval: "1m",
 });
+/**
+ * Commits 1-hour candle history report to history container.
+ *
+ * Fetches and appends a markdown-formatted report of the last 6 hourly candles
+ * including OHLCV data, volatility, body size, and candle type (Green/Red/Doji).
+ * Automatically clears cache on errors to ensure data freshness.
+ *
+ * @param symbol - Trading pair symbol (e.g., 'BTCUSDT')
+ * @param history - History container to append report to
+ * @returns Promise that resolves when report is committed
+ *
+ * @example
+ * ```typescript
+ * import { commitHourHistory } from '@backtest-kit/signals';
+ *
+ * const messages = [];
+ * await commitHourHistory('BTCUSDT', messages);
+ *
+ * // messages now contains:
+ * // [
+ * //   { role: 'user', content: '=== HOURLY CANDLES HISTORY (LAST 6) ===\n\n...' },
+ * //   { role: 'assistant', content: 'Hourly candles history received.' }
+ * // ]
+ * ```
+ */
 const commitHourHistory = functoolsKit.trycatch(async (symbol, history) => {
     const hourHistory = await fetchHourHistory(symbol);
     await history.push({
@@ -2847,6 +4568,25 @@ const commitHourHistory = functoolsKit.trycatch(async (symbol, history) => {
 }, {
     fallback: () => backtestKit.Cache.clear(fetchHourHistory),
 });
+/**
+ * Commits 30-minute candle history report to history container.
+ *
+ * Fetches and appends a markdown-formatted report of the last 6 thirty-minute candles
+ * including OHLCV data, volatility, body size, and candle type (Green/Red/Doji).
+ * Automatically clears cache on errors to ensure data freshness.
+ *
+ * @param symbol - Trading pair symbol (e.g., 'BTCUSDT')
+ * @param history - History container to append report to
+ * @returns Promise that resolves when report is committed
+ *
+ * @example
+ * ```typescript
+ * import { commitThirtyMinuteHistory } from '@backtest-kit/signals';
+ *
+ * const messages = [];
+ * await commitThirtyMinuteHistory('ETHUSDT', messages);
+ * ```
+ */
 const commitThirtyMinuteHistory = functoolsKit.trycatch(async (symbol, history) => {
     const thirtyMinuteHistory = await fetchThirtyMinuteHistory(symbol);
     await history.push({
@@ -2859,6 +4599,25 @@ const commitThirtyMinuteHistory = functoolsKit.trycatch(async (symbol, history)
 }, {
     fallback: () => backtestKit.Cache.clear(fetchThirtyMinuteHistory),
 });
+/**
+ * Commits 15-minute candle history report to history container.
+ *
+ * Fetches and appends a markdown-formatted report of the last 8 fifteen-minute candles
+ * including OHLCV data, volatility, body size, and candle type (Green/Red/Doji).
+ * Automatically clears cache on errors to ensure data freshness.
+ *
+ * @param symbol - Trading pair symbol (e.g., 'BTCUSDT')
+ * @param history - History container to append report to
+ * @returns Promise that resolves when report is committed
+ *
+ * @example
+ * ```typescript
+ * import { commitFifteenMinuteHistory } from '@backtest-kit/signals';
+ *
+ * const messages = [];
+ * await commitFifteenMinuteHistory('BTCUSDT', messages);
+ * ```
+ */
 const commitFifteenMinuteHistory = functoolsKit.trycatch(async (symbol, history) => {
     const fifteenMinuteHistory = await fetchFifteenMinuteHistory(symbol);
     await history.push({
@@ -2871,6 +4630,25 @@ const commitFifteenMinuteHistory = functoolsKit.trycatch(async (symbol, history)
 }, {
     fallback: () => backtestKit.Cache.clear(fetchFifteenMinuteHistory),
 });
+/**
+ * Commits 1-minute candle history report to history container.
+ *
+ * Fetches and appends a markdown-formatted report of the last 15 one-minute candles
+ * including OHLCV data, volatility, body size, and candle type (Green/Red/Doji).
+ * Automatically clears cache on errors to ensure data freshness.
+ *
+ * @param symbol - Trading pair symbol (e.g., 'BTCUSDT')
+ * @param history - History container to append report to
+ * @returns Promise that resolves when report is committed
+ *
+ * @example
+ * ```typescript
+ * import { commitOneMinuteHistory } from '@backtest-kit/signals';
+ *
+ * const messages = [];
+ * await commitOneMinuteHistory('BTCUSDT', messages);
+ * ```
+ */
 const commitOneMinuteHistory = functoolsKit.trycatch(async (symbol, history) => {
     const oneMinuteHistory = await fetchOneMinuteHistory(symbol);
     await history.push({
@@ -2884,18 +4662,83 @@ const commitOneMinuteHistory = functoolsKit.trycatch(async (symbol, history) =>
     fallback: () => backtestKit.Cache.clear(fetchOneMinuteHistory),
 });
 
+/**
+ * Technical indicator report generation functions for multi-timeframe trading analysis.
+ *
+ * Provides cached functions to fetch and commit comprehensive technical indicator reports
+ * across 4 trading timeframes (MicroTerm: 1m, ShortTerm: 15m, SwingTerm: 30m, LongTerm: 1h).
+ * Each report includes 50+ indicators formatted as markdown tables for LLM consumption.
+ *
+ * Key features:
+ * - MicroTerm (1m): RSI(9,14), MACD(8,21,5), Stochastic, ADX(9), Bollinger(8,2), ATR, CCI, Volume analysis, Squeeze momentum
+ * - ShortTerm (15m): RSI(9), MACD(8,21,5), Stochastic(5,3,3), ADX(14), Bollinger(10,2), Fibonacci levels
+ * - SwingTerm (30m): RSI(14), MACD(12,26,9), Stochastic(14,3,3), Bollinger(20,2), Support/Resistance, Fibonacci
+ * - LongTerm (1h): RSI(14), MACD(12,26,9), ADX(14), Bollinger(20,2), SMA(50), DEMA, WMA, Volume trends
+ * - Intelligent caching with timeframe-specific TTL
+ * - Automatic cache clearing on errors
+ *
+ * @module function/math
+ */
+/**
+ * Cached function to fetch MicroTerm (1-minute) technical analysis report.
+ * Cache TTL: 1 minute
+ */
 const fetchMicroTermMath = backtestKit.Cache.fn(signal.microTermMathService.getReport, {
     interval: "1m",
 });
+/**
+ * Cached function to fetch ShortTerm (15-minute) technical analysis report.
+ * Cache TTL: 5 minutes
+ */
 const fetchShortTermMath = backtestKit.Cache.fn(signal.shortTermMathService.getReport, {
     interval: "5m",
 });
+/**
+ * Cached function to fetch SwingTerm (30-minute) technical analysis report.
+ * Cache TTL: 15 minutes
+ */
 const fetchSwingTermMath = backtestKit.Cache.fn(signal.swingTermMathService.getReport, {
     interval: "15m",
 });
+/**
+ * Cached function to fetch LongTerm (1-hour) technical analysis report.
+ * Cache TTL: 30 minutes
+ */
 const fetchLongTermMath = backtestKit.Cache.fn(signal.longTermMathService.getReport, {
     interval: "30m",
 });
+/**
+ * Commits MicroTerm (1-minute) technical analysis report to history container.
+ *
+ * Generates comprehensive technical analysis for scalping and ultra-short term trading.
+ * Includes 40+ indicators optimized for 1-minute timeframe with 60-candle lookback.
+ *
+ * Indicators included:
+ * - Momentum: RSI(9,14), Stochastic RSI(9,14), MACD(8,21,5), Momentum(5,10), ROC(1,3,5)
+ * - Trend: ADX(9), +DI/-DI(9), EMA(3,8,13,21), SMA(8), DEMA(8), WMA(5)
+ * - Volatility: ATR(5,9), Bollinger Bands(8,2) with width/position, Squeeze momentum
+ * - Volume: SMA(5), volume ratio, volume trend (increasing/decreasing/stable)
+ * - Support/Resistance: Dynamic levels from 30-candle window
+ * - Price Analysis: 1m/3m/5m price changes, volatility, true range, pressure index
+ *
+ * @param symbol - Trading pair symbol (e.g., 'BTCUSDT')
+ * @param history - History container to append report to
+ * @returns Promise that resolves when report is committed
+ *
+ * @example
+ * ```typescript
+ * import { commitMicroTermMath } from '@backtest-kit/signals';
+ *
+ * const messages = [];
+ * await commitMicroTermMath('BTCUSDT', messages);
+ *
+ * // Use in LLM strategy for scalping signals
+ * const signal = await llm([
+ *   { role: 'system', content: 'Analyze for scalping opportunities' },
+ *   ...messages
+ * ]);
+ * ```
+ */
 const commitMicroTermMath = functoolsKit.trycatch(async (symbol, history) => {
     const microTermMath = await fetchMicroTermMath(symbol);
     await history.push({
@@ -2908,6 +4751,32 @@ const commitMicroTermMath = functoolsKit.trycatch(async (symbol, history) => {
 }, {
     fallback: () => backtestKit.Cache.clear(fetchMicroTermMath),
 });
+/**
+ * Commits LongTerm (1-hour) technical analysis report to history container.
+ *
+ * Generates comprehensive technical analysis for trend identification and position management.
+ * Includes 30+ indicators optimized for 1-hour timeframe with 48-candle lookback (48 hours).
+ *
+ * Indicators included:
+ * - Momentum: RSI(14), Stochastic RSI(14), MACD(12,26,9), Stochastic(14,3,3), Momentum(10)
+ * - Trend: ADX(14), +DI/-DI(14), SMA(50), EMA(20,34), DEMA(21), WMA(20)
+ * - Volatility: ATR(14,20), Bollinger Bands(20,2), CCI(20)
+ * - Support/Resistance: 4-candle pivot detection
+ * - Fibonacci: Retracement levels (0%, 23.6%, 38.2%, 50%, 61.8%, 78.6%, 100%) with nearest level
+ * - Volume: Trend analysis (increasing/decreasing/stable)
+ *
+ * @param symbol - Trading pair symbol (e.g., 'BTCUSDT')
+ * @param history - History container to append report to
+ * @returns Promise that resolves when report is committed
+ *
+ * @example
+ * ```typescript
+ * import { commitLongTermMath } from '@backtest-kit/signals';
+ *
+ * const messages = [];
+ * await commitLongTermMath('ETHUSDT', messages);
+ * ```
+ */
 const commitLongTermMath = functoolsKit.trycatch(async (symbol, history) => {
     const longTermMath = await fetchLongTermMath(symbol);
     await history.push({
@@ -2920,6 +4789,32 @@ const commitLongTermMath = functoolsKit.trycatch(async (symbol, history) => {
 }, {
     fallback: () => backtestKit.Cache.clear(fetchLongTermMath),
 });
+/**
+ * Commits ShortTerm (15-minute) technical analysis report to history container.
+ *
+ * Generates comprehensive technical analysis for day trading strategies.
+ * Includes 30+ indicators optimized for 15-minute timeframe with 144-candle lookback (36 hours).
+ *
+ * Indicators included:
+ * - Momentum: RSI(9), Stochastic RSI(9), MACD(8,21,5), Stochastic(5,3,3), Momentum(8), ROC(5,10)
+ * - Trend: ADX(14), +DI/-DI(14), SMA(50), EMA(8,21), DEMA(21), WMA(20)
+ * - Volatility: ATR(9), Bollinger Bands(10,2) with width, CCI(14)
+ * - Support/Resistance: 48-candle window with 0.3% threshold
+ * - Fibonacci: Retracement levels over 288-candle lookback (72 hours)
+ * - Volume: Trend analysis over 16-candle window
+ *
+ * @param symbol - Trading pair symbol (e.g., 'BTCUSDT')
+ * @param history - History container to append report to
+ * @returns Promise that resolves when report is committed
+ *
+ * @example
+ * ```typescript
+ * import { commitShortTermMath } from '@backtest-kit/signals';
+ *
+ * const messages = [];
+ * await commitShortTermMath('BTCUSDT', messages);
+ * ```
+ */
 const commitShortTermMath = functoolsKit.trycatch(async (symbol, history) => {
     const shortTermMath = await fetchShortTermMath(symbol);
     await history.push({
@@ -2932,6 +4827,33 @@ const commitShortTermMath = functoolsKit.trycatch(async (symbol, history) => {
 }, {
     fallback: () => backtestKit.Cache.clear(fetchShortTermMath),
 });
+/**
+ * Commits SwingTerm (30-minute) technical analysis report to history container.
+ *
+ * Generates comprehensive technical analysis for swing trading strategies.
+ * Includes 30+ indicators optimized for 30-minute timeframe with 96-candle lookback (48 hours).
+ *
+ * Indicators included:
+ * - Momentum: RSI(14), Stochastic RSI(14), MACD(12,26,9), Stochastic(14,3,3), Momentum(8)
+ * - Trend: ADX(14), +DI/-DI(14), SMA(20), EMA(13,34), DEMA(21), WMA(20)
+ * - Volatility: ATR(14), Bollinger Bands(20,2) with width, CCI(20), Basic volatility
+ * - Support/Resistance: 20-candle window detection
+ * - Fibonacci: Support/resistance levels with current level identification
+ * - Volume: Trading volume analysis
+ * - Price Momentum: 6-period momentum indicator
+ *
+ * @param symbol - Trading pair symbol (e.g., 'BTCUSDT')
+ * @param history - History container to append report to
+ * @returns Promise that resolves when report is committed
+ *
+ * @example
+ * ```typescript
+ * import { commitSwingTermMath } from '@backtest-kit/signals';
+ *
+ * const messages = [];
+ * await commitSwingTermMath('BTCUSDT', messages);
+ * ```
+ */
 const commitSwingTermMath = functoolsKit.trycatch(async (symbol, history) => {
     const swingTermMath = await fetchSwingTermMath(symbol);
     await history.push({
@@ -2945,9 +4867,59 @@ const commitSwingTermMath = functoolsKit.trycatch(async (symbol, history) => {
     fallback: () => backtestKit.Cache.clear(fetchSwingTermMath),
 });
 
+/**
+ * Orchestrator functions for complete market analysis setup.
+ *
+ * Provides high-level functions that combine multiple analysis types
+ * (order book, candle history, technical indicators) into comprehensive
+ * market reports for LLM-based trading strategies.
+ *
+ * Key features:
+ * - commitBookDataReport: Order book analysis with top 20 levels by volume
+ * - commitHistorySetup: All-in-one setup with full multi-timeframe analysis
+ * - Automatic mode detection (skips order book in backtest mode)
+ * - System context injection (symbol, price, timestamp)
+ *
+ * @module function/other
+ */
+/**
+ * Cached function to fetch order book analysis report.
+ * Cache TTL: 5 minutes
+ */
 const fetchBookData = backtestKit.Cache.fn(signal.bookDataMathService.getReport, {
     interval: "5m",
 });
+/**
+ * Commits order book analysis report to history container.
+ *
+ * Fetches and appends real-time order book data including top 20 price levels
+ * by volume percentage, best bid/ask, mid price, spread, and depth imbalance.
+ * Automatically skipped in backtest mode (order book data unavailable).
+ *
+ * Order book metrics:
+ * - Best Bid/Ask: Top buy and sell prices
+ * - Mid Price: (Best Bid + Best Ask) / 2
+ * - Spread: Best Ask - Best Bid
+ * - Depth Imbalance: (Bid Volume - Ask Volume) / (Bid Volume + Ask Volume)
+ *   - Positive = buying pressure
+ *   - Negative = selling pressure
+ * - Top 20 Levels: Sorted by volume percentage on each side
+ *
+ * @param symbol - Trading pair symbol (e.g., 'BTCUSDT')
+ * @param history - History container to append report to
+ * @returns Promise that resolves when report is committed (or immediately in backtest mode)
+ *
+ * @example
+ * ```typescript
+ * import { commitBookDataReport } from '@backtest-kit/signals';
+ *
+ * const messages = [];
+ * await commitBookDataReport('BTCUSDT', messages);
+ *
+ * // In live mode: messages contains order book analysis
+ * // In backtest mode: messages unchanged (order book skipped)
+ * ```
+ */
 const commitBookDataReport = functoolsKit.trycatch(async (symbol, history) => {
     const mode = await backtestKit.getMode();
     if (mode === "backtest") {
@@ -2964,15 +4936,56 @@ const commitBookDataReport = functoolsKit.trycatch(async (symbol, history) => {
 }, {
     fallback: () => backtestKit.Cache.clear(fetchBookData),
 });
+/**
+ * Commits complete multi-timeframe market analysis setup to history container.
+ *
+ * All-in-one function that orchestrates the full technical analysis pipeline.
+ * Sequentially commits order book data, candle histories, technical indicators,
+ * and system context for comprehensive LLM-based trading analysis.
+ *
+ * Analysis pipeline:
+ * 1. Order Book: Top 20 levels, bid/ask depth, spread, imbalance (live mode only)
+ * 2. Candle Histories: 1m (15 candles), 15m (8 candles), 30m (6 candles), 1h (6 candles)
+ * 3. Technical Indicators:
+ *    - MicroTerm (1m): 40+ scalping indicators
+ *    - ShortTerm (15m): 30+ day trading indicators
+ *    - SwingTerm (30m): 30+ swing trading indicators
+ *    - LongTerm (1h): 30+ trend indicators
+ * 4. System Context: Symbol, current price (VWAP), timestamp
+ *
+ * Total output: 150+ indicators across 4 timeframes + order book + candle data
+ *
+ * @param symbol - Trading pair symbol (e.g., 'BTCUSDT')
+ * @param history - History container to append all reports to
+ * @returns Promise that resolves when all reports are committed
+ *
+ * @example
+ * ```typescript
+ * import { commitHistorySetup } from '@backtest-kit/signals';
+ * import { json } from './llm-wrapper';
+ *
+ * // Complete LLM strategy setup
+ * const messages = [
+ *   { role: 'system', content: 'You are a trading bot. Analyze and generate signals.' }
+ * ];
+ *
+ * // Inject all technical analysis
+ * await commitHistorySetup('BTCUSDT', messages);
+ *
+ * // Generate trading signal
+ * const signal = await json(messages);
+ * console.log(signal); // { position: 'long', priceTakeProfit: 50500, priceStopLoss: 49500 }
+ * ```
+ */
 const commitHistorySetup = async (symbol, history) => {
-    // Cтакан сделок
+    // Order book analysis
     await commitBookDataReport(symbol, history);
-    // Данные свечей отдельными блоками
+    // Candle histories across timeframes
     await commitOneMinuteHistory(symbol, history);
     await commitFifteenMinuteHistory(symbol, history);
     await commitThirtyMinuteHistory(symbol, history);
     await commitHourHistory(symbol, history);
-    // Данные индикаторов и осцилляторов
+    // Technical indicators across timeframes
     await commitMicroTermMath(symbol, history);
     await commitShortTermMath(symbol, history);
     await commitSwingTermMath(symbol, history);
@@ -2986,6 +4999,43 @@ const commitHistorySetup = async (symbol, history) => {
     });
 };
 
+/**
+ * Configuration utilities for signals library.
+ *
+ * Provides functions to customize library behavior, primarily logging configuration.
+ *
+ * @module tools/setup
+ */
+/**
+ * Sets custom logger implementation for signals library.
+ *
+ * By default, signals uses a no-op logger (no output).
+ * Use this function to enable logging for debugging and monitoring.
+ *
+ * @param logger - Custom logger implementation conforming to ILogger interface
+ *
+ * @example
+ * ```typescript
+ * import { setLogger } from '@backtest-kit/signals';
+ *
+ * // Enable console logging
+ * setLogger({
+ *   log: console.log,
+ *   debug: console.debug,
+ *   info: console.info,
+ *   warn: console.warn,
+ * });
+ *
+ * // Or use custom logger
+ * import winston from 'winston';
+ * setLogger({
+ *   log: (topic, ...args) => winston.log('info', topic, args),
+ *   debug: (topic, ...args) => winston.debug(topic, args),
+ *   info: (topic, ...args) => winston.info(topic, args),
+ *   warn: (topic, ...args) => winston.warn(topic, args),
+ * });
+ * ```
+ */
 const setLogger = (logger) => {
     signal.loggerService.setLogger(logger);
 };