📊 @backtest-kit/signals

import { v4 as uuid } from 'uuid';
import { addStrategy, dumpSignal } from 'backtest-kit';
import { commitHistorySetup } from '@backtest-kit/signals';
import { json } from './utils/json.mjs';   // your LLM wrapper

addStrategy({
  strategyName: 'llm-strategy', interval: '5m', riskName: 'demo',
  getSignal: async (symbol) => {
    const messages = [{ role: 'system', content: 'You are a trading bot. Analyze the indicators and generate a signal.' }];
    await commitHistorySetup(symbol, messages);
    messages.push({ role: 'user', content: [
      'Based on the technical analysis above, generate a trading signal.',
      'Use position: "wait" if signals are unclear or contradictory.',
      'Return JSON: { position: "long"|"short"|"wait", priceTakeProfit: number, priceStopLoss: number }',
    ].join('\n') });

    const resultId = uuid();
    const signal = await json(messages);
    await dumpSignal(resultId, messages, signal);   // archive for debugging
    return { ...signal, id: resultId };
  },
});
Copy

import {
  commitBookDataReport,                                 // order book: bids/asks, spread, imbalance
  commitOneMinuteHistory, commitFifteenMinuteHistory,   // candle histories (last 15 / 8 …)
  commitThirtyMinuteHistory, commitHourHistory,
  commitMicroTermMath, commitShortTermMath,             // indicator tables per timeframe
  commitSwingTermMath, commitLongTermMath,
} from '@backtest-kit/signals';

const messages = [];
await commitBookDataReport('BTCUSDT', messages);
await commitOneMinuteHistory('BTCUSDT', messages);
await commitMicroTermMath('BTCUSDT', messages);
// …add only the sections you want, then call your LLM
Copy

commitHistorySetup is simply the orchestrator that runs all of these in the right order.

Order book — symbol, best bid/ask, mid price, spread, depth imbalance ((bid_vol − ask_vol)/(bid_vol + ask_vol), + = buy pressure), and top-20 bid/ask levels with % of total.

Candle history — per-candle table: timestamp, OHLC, volume, volatility, body size.

Indicators — a wide per-bar table; e.g. MicroTerm columns: Price, RSI(9), RSI(14), MACD, Signal, Histogram, Stoch %K/%D, ADX, +DI, −DI, BB Upper/Middle/Lower, ATR(5/9), CCI(9), Volume, Vol Trend, Momentum, ROC, Support, Resistance, Squeeze, Pressure — followed by a Data Sources note listing every period used.

Cache TTL (cleared on error): 1m data → 1 min · 15m → 5 min · 30m → 15 min · 1h → 30 min · order book → 5 min.

• Support/Resistance — MicroTerm/SwingTerm look back N candles for significant highs/lows (±0.3% threshold); LongTerm uses a 4-candle pivot method.
• Fibonacci — levels 0 / 23.6 / 38.2 / 50 / 61.8 / 78.6 / 100 %, extensions 127.2 / 161.8 / 261.8 %; nearest level to price within 1.5% tolerance.
• Volume — MicroTerm: SMA(5) with increasing/decreasing/stable trend (±20%); LongTerm: 6-candle average (±10%).
• Order-book imbalance — (bid − ask)/(bid + ask), positive = buy pressure.

import { setLogger } from '@backtest-kit/signals';
setLogger({ log: console.log, debug: console.debug, info: console.info, warn: console.warn });
Copy

// ❌ Manual — 40+ indicators, formatting, caching, all by hand
const candles = await getCandles('BTCUSDT', '1m', 60);
const rsi  = calculateRSI(candles, 14);
const macd = calculateMACD(candles, 12, 26, 9);
const bb   = calculateBollingerBands(candles, 20, 2);
// …and the markdown formatting, and the cache
messages.push({ role: 'user', content: formatToMarkdown(rsi, macd, bb /* … */) });

// ✅ With signals
await commitHistorySetup('BTCUSDT', messages);
Copy

Pre-computed, cached, optimized · 50+ indicators × 4 timeframes · LLM-ready markdown · synchronized with the backtest timeline · validation & error handling built in.

• function/history.function.ts — the four commit*History functions. function/math.function.ts — the four commit*Math functions. function/other.function.ts — commitBookDataReport + commitHistorySetup.
• tools/setup.tool.ts — setLogger. contract/{History,ReportFn}.contract.ts — report-function contracts. interfaces/Logger.interface.ts.
• lib/ IoC: core/{di,provide,types}, services/common/LoggerService, services/history/{One,Fifteen,Thirty}MinuteCandleHistoryService + HourCandleHistoryService, services/math/{MicroTerm,ShortTerm,SwingTerm,LongTerm}MathService + BookDataMathService (the math services are the package's bulk — 32–45 KB each). Every export maps to one of these; nothing in src/ is undocumented.