@backtest-kit/signals 7.8.0 → 8.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +307 -307
  2. package/package.json +87 -87
package/README.md CHANGED
@@ -1,307 +1,307 @@
1
- <img src="https://github.com/tripolskypetr/backtest-kit/raw/refs/heads/master/assets/chronos.svg" height="45px" align="right">
2
-
3
- # 📊 @backtest-kit/signals
4
-
5
- > Technical analysis and trading signal generation library for AI-powered trading systems. Computes 50+ indicators across 4 timeframes and generates markdown reports for LLM consumption.
6
-
7
- ![screenshot](https://raw.githubusercontent.com/tripolskypetr/backtest-kit/HEAD/assets/screenshots/screenshot16.png)
8
-
9
- [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/tripolskypetr/backtest-kit)
10
- [![npm](https://img.shields.io/npm/v/@backtest-kit/signals.svg?style=flat-square)](https://npmjs.org/package/@backtest-kit/signals)
11
- [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)]()
12
-
13
- Transform raw market data into actionable trading insights with multi-timeframe technical analysis, order book depth, and AI-ready markdown reports.
14
-
15
- 📚 **[Backtest Kit Docs](https://backtest-kit.github.io/documents/article_07_ai_news_trading_signals.html)** | 🌟 **[GitHub](https://github.com/tripolskypetr/backtest-kit)**
16
-
17
- > **New to backtest-kit?** The fastest way to get a real, production-ready setup is to clone the [reference implementation](https://github.com/tripolskypetr/backtest-kit/tree/master/example) — a fully working news-sentiment AI trading system with LLM forecasting, multi-timeframe data, and a documented February 2026 backtest. Start there instead of from scratch.
18
-
19
- ## ✨ Features
20
-
21
- - 📈 **Multi-Timeframe Analysis**: 1m, 15m, 30m, 1h with synchronized indicator computation
22
- - 🎯 **50+ Technical Indicators**: RSI, MACD, Bollinger Bands, Stochastic, ADX, ATR, CCI, Fibonacci, Support/Resistance
23
- - 📊 **Order Book Analysis**: Bid/ask depth, spread, liquidity imbalance, top 20 levels
24
- - 🤖 **AI-Ready Output**: Markdown reports formatted for LLM context injection
25
- - ⚡ **Performance Optimized**: Intelligent caching with configurable TTL per timeframe
26
- - 🧮 **Custom Algorithms**: Fibonacci retracements, support/resistance detection, volume analysis
27
- - 📦 **Zero Config**: Works out-of-the-box with backtest-kit
28
-
29
- ## 📋 What It Does
30
-
31
- `@backtest-kit/signals` analyzes market data and generates comprehensive technical reports across multiple timeframes:
32
-
33
- | Timeframe | Candles | Indicators | Use Case |
34
- |-----------|---------|------------|----------|
35
- | **MicroTerm** (1m) | 60 | RSI(9,14), MACD(8,21,5), Stochastic, ADX(9), Bollinger(8,2), ATR, CCI, Volume, Squeeze | Scalping, ultra-short entries |
36
- | **ShortTerm** (15m) | 144 | RSI(9), MACD(8,21,5), Stochastic(5,3,3), ADX(14), Bollinger(10,2), Fibonacci | Day trading |
37
- | **SwingTerm** (30m) | 96 | RSI(14), MACD(12,26,9), Stochastic(14,3,3), Bollinger(20,2), Support/Resistance | Swing trading |
38
- | **LongTerm** (1h) | 100 | RSI(14), MACD(12,26,9), ADX(14), Bollinger(20,2), SMA(50), DEMA, WMA, Volume Trend | Trend analysis |
39
-
40
- **Plus:** Real-time order book analysis with bid/ask depth and imbalance metrics.
41
-
42
- ## 🚀 Installation
43
-
44
- ```bash
45
- npm install @backtest-kit/signals backtest-kit
46
- ```
47
-
48
- ## 📖 Usage
49
-
50
- ### Quick Start - All-in-One Report
51
-
52
- The easiest way to inject technical analysis into your LLM strategy:
53
-
54
- ```typescript
55
- import { commitHistorySetup } from '@backtest-kit/signals';
56
- import { getCandles } from 'backtest-kit';
57
-
58
- // In your strategy's getSignal function:
59
- const messages = [];
60
-
61
- // Add all technical analysis + order book + candle history
62
- await commitHistorySetup('BTCUSDT', messages);
63
-
64
- // Now messages contains:
65
- // - Order book analysis (bids/asks, spread, imbalance)
66
- // - Candle history (1m, 15m, 30m, 1h)
67
- // - Technical indicators for all 4 timeframes
68
- // - System info (symbol, price, timestamp)
69
-
70
- // Send to LLM
71
- const signal = await llm(messages);
72
- ```
73
-
74
- ### Granular Control - Individual Reports
75
-
76
- For fine-grained control over what data to include:
77
-
78
- ```typescript
79
- import {
80
- commitBookDataReport,
81
- commitOneMinuteHistory,
82
- commitFifteenMinuteHistory,
83
- commitThirtyMinuteHistory,
84
- commitHourHistory,
85
- commitMicroTermMath,
86
- commitShortTermMath,
87
- commitSwingTermMath,
88
- commitLongTermMath,
89
- } from '@backtest-kit/signals';
90
-
91
- const messages = [];
92
-
93
- // Order book analysis
94
- await commitBookDataReport('BTCUSDT', messages);
95
-
96
- // Candle histories
97
- await commitOneMinuteHistory('BTCUSDT', messages); // Last 15 candles
98
- await commitFifteenMinuteHistory('BTCUSDT', messages); // Last 8 candles
99
- await commitThirtyMinuteHistory('BTCUSDT', messages); // Last 6 candles
100
- await commitHourHistory('BTCUSDT', messages); // Last 6 candles
101
-
102
- // Technical indicators
103
- await commitMicroTermMath('BTCUSDT', messages); // 1m indicators
104
- await commitShortTermMath('BTCUSDT', messages); // 15m indicators
105
- await commitSwingTermMath('BTCUSDT', messages); // 30m indicators
106
- await commitLongTermMath('BTCUSDT', messages); // 1h indicators
107
-
108
- // Send to LLM
109
- const signal = await llm(messages);
110
- ```
111
-
112
- ### Complete LLM Strategy Example
113
-
114
- ```typescript
115
- import { v4 as uuid } from 'uuid';
116
- import { addStrategy, dumpSignal } from 'backtest-kit';
117
- import { commitHistorySetup } from '@backtest-kit/signals';
118
- import { json } from './utils/json.mjs'; // Your LLM wrapper
119
-
120
- addStrategy({
121
- strategyName: 'llm-strategy',
122
- interval: '5m',
123
- riskName: 'demo',
124
- getSignal: async (symbol) => {
125
- const messages = [
126
- {
127
- role: 'system',
128
- content: 'You are a trading bot. Analyze technical indicators and generate signals.'
129
- }
130
- ];
131
-
132
- // Inject all technical analysis
133
- await commitHistorySetup(symbol, messages);
134
-
135
- // Add trading instructions
136
- messages.push({
137
- role: 'user',
138
- content: [
139
- 'Based on the technical analysis above, generate a trading signal.',
140
- 'Use position: "wait" if signals are unclear or contradictory.',
141
- 'Return JSON: { position: "long"|"short"|"wait", priceTakeProfit: number, priceStopLoss: number }'
142
- ].join('\n')
143
- });
144
-
145
- // Generate signal via LLM
146
- const resultId = uuid();
147
- const signal = await json(messages);
148
-
149
- // Save conversation for debugging
150
- await dumpSignal(resultId, messages, signal);
151
-
152
- return { ...signal, id: resultId };
153
- }
154
- });
155
- ```
156
-
157
- ### Custom Logger
158
-
159
- By default, signals uses a no-op logger. To enable logging:
160
-
161
- ```typescript
162
- import { setLogger } from '@backtest-kit/signals';
163
-
164
- setLogger({
165
- log: console.log,
166
- debug: console.debug,
167
- info: console.info,
168
- warn: console.warn,
169
- });
170
- ```
171
-
172
- ## 📊 Generated Report Structure
173
-
174
- ### Order Book Report
175
-
176
- ```markdown
177
- ## Order Book Analysis
178
-
179
- **Symbol:** BTCUSDT
180
- **Best Bid:** 50000.00 | **Best Ask:** 50001.00
181
- **Mid Price:** 50000.50 | **Spread:** 1.00
182
- **Depth Imbalance:** +5.2% (buy pressure)
183
-
184
- ### Top 20 Levels (Bids)
185
- | Price | Volume | % Total |
186
- |-------|--------|---------|
187
- | 50000.00 | 1.234 | 15.5% |
188
- ...
189
-
190
- ### Top 20 Levels (Asks)
191
- | Price | Volume | % Total |
192
- |-------|--------|---------|
193
- | 50001.00 | 0.987 | 12.3% |
194
- ...
195
- ```
196
-
197
- ### Candle History Report
198
-
199
- ```markdown
200
- ## 1-Minute Candle History (Last 15)
201
-
202
- | Timestamp | Open | High | Low | Close | Volume | Volatility | Body Size |
203
- |-----------|------|------|-----|-------|--------|------------|-----------|
204
- | 2025-01-13 10:00 | 50000 | 50050 | 49990 | 50020 | 123.45 | 0.12% | 0.04% |
205
- ...
206
- ```
207
-
208
- ### Technical Indicators Report
209
-
210
- ```markdown
211
- ## MicroTerm Analysis (1-Minute Timeframe)
212
-
213
- | Time | Price | RSI(9) | RSI(14) | MACD | Signal | Histogram | Stoch %K | Stoch %D | ADX | +DI | -DI | BB Upper | BB Middle | BB Lower | ATR(5) | ATR(9) | CCI(9) | Volume | Vol Trend | Momentum | ROC | Support | Resistance | Squeeze | Pressure |
214
- |------|-------|--------|---------|------|--------|-----------|----------|----------|-----|-----|-----|----------|-----------|----------|--------|--------|--------|--------|-----------|----------|-----|---------|------------|---------|----------|
215
- | 10:00 | 50020 | 55.2 | 52.8 | 12.5 | 8.3 | 4.2 | 45.6 | 42.1 | 28.5 | 22.3 | 18.7 | 50100 | 50000 | 49900 | 15.2 | 18.9 | 45.7 | 123.45 | increasing | 0.8% | 1.2% | 49950 | 50100 | 0.85 | 15.2 |
216
- ...
217
-
218
- **Data Sources:**
219
- - RSI periods: 9, 14
220
- - MACD: Fast=8, Slow=21, Signal=5
221
- - Stochastic: K=3, D=3, Smooth=3 (primary), K=5, D=3, Smooth=3 (secondary)
222
- ...
223
- ```
224
-
225
- ## 🔄 Caching Strategy
226
-
227
- Reports are cached to avoid redundant calculations:
228
-
229
- | Timeframe | Cache Duration |
230
- |-----------|----------------|
231
- | 1-minute data | 1 minute |
232
- | 15-minute data | 5 minutes |
233
- | 30-minute data | 15 minutes |
234
- | 1-hour data | 30 minutes |
235
- | Order book | 5 minutes |
236
-
237
- Cache is automatically cleared on errors.
238
-
239
- ## 🧮 Key Algorithms
240
-
241
- ### Support/Resistance Detection
242
- - **MicroTerm/SwingTerm**: Looks back N candles for significant highs/lows (±0.3% threshold)
243
- - **LongTerm**: 4-candle pivot point method
244
-
245
- ### Fibonacci Retracement
246
- - Calculates levels: 0%, 23.6%, 38.2%, 50%, 61.8%, 78.6%, 100%
247
- - Extensions: 127.2%, 161.8%, 261.8%
248
- - Finds nearest level to current price (1.5% tolerance)
249
-
250
- ### Volume Analysis
251
- - **MicroTerm**: SMA(5) volume with increasing/decreasing/stable trend (±20% threshold)
252
- - **LongTerm**: 6-candle average comparison (±10% threshold)
253
-
254
- ### Order Book Imbalance
255
-
256
- Imbalance = (bid_volume - ask_volume) / (bid_volume + ask_volume)
257
-
258
- Positive = buy pressure, Negative = sell pressure
259
-
260
- ## 🎯 Use Cases
261
-
262
- ### 1. LLM-Powered Trading Strategies
263
- Inject technical analysis into your LLM's context for intelligent signal generation.
264
-
265
- ### 2. Multi-Timeframe Confirmation
266
- Combine indicators from different timeframes to filter false signals.
267
-
268
- ### 3. Market Context for AI Agents
269
- Provide comprehensive market state to AI agents making trading decisions.
270
-
271
- ### 4. Debugging & Analysis
272
- Save generated reports for post-analysis and strategy improvement.
273
-
274
- ## 💡 Why Use @backtest-kit/signals?
275
-
276
- Instead of manually calculating indicators and formatting data for your LLM:
277
-
278
- ```typescript
279
- // ❌ Without signals (manual work)
280
- const candles = await getCandles('BTCUSDT', '1m', 60);
281
- const rsi = calculateRSI(candles, 14);
282
- const macd = calculateMACD(candles, 12, 26, 9);
283
- const bb = calculateBollingerBands(candles, 20, 2);
284
- // ... 40+ more indicators
285
- const report = formatToMarkdown(rsi, macd, bb, ...);
286
- messages.push({ role: 'user', content: report });
287
- ```
288
-
289
- ```typescript
290
- // ✅ With signals (one line)
291
- await commitHistorySetup('BTCUSDT', messages);
292
- ```
293
-
294
- **Benefits:**
295
- - ⚡ Pre-computed, cached, optimized
296
- - 📊 50+ indicators across 4 timeframes
297
- - 🎨 Formatted markdown tables ready for LLM
298
- - 🔄 Synchronized with backtest timeline
299
- - 🛡️ Error handling and validation built-in
300
-
301
- ## 🤝 Contribute
302
-
303
- Fork/PR on [GitHub](https://github.com/tripolskypetr/backtest-kit).
304
-
305
- ## 📜 License
306
-
307
- MIT © [tripolskypetr](https://github.com/tripolskypetr)
1
+ <img src="https://github.com/tripolskypetr/backtest-kit/raw/refs/heads/master/assets/chronos.svg" height="45px" align="right">
2
+
3
+ # 📊 @backtest-kit/signals
4
+
5
+ > Technical analysis and trading signal generation library for AI-powered trading systems. Computes 50+ indicators across 4 timeframes and generates markdown reports for LLM consumption.
6
+
7
+ ![screenshot](https://raw.githubusercontent.com/tripolskypetr/backtest-kit/HEAD/assets/screenshots/screenshot16.png)
8
+
9
+ [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/tripolskypetr/backtest-kit)
10
+ [![npm](https://img.shields.io/npm/v/@backtest-kit/signals.svg?style=flat-square)](https://npmjs.org/package/@backtest-kit/signals)
11
+ [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)]()
12
+
13
+ Transform raw market data into actionable trading insights with multi-timeframe technical analysis, order book depth, and AI-ready markdown reports.
14
+
15
+ 📚 **[Backtest Kit Docs](https://backtest-kit.github.io/documents/article_07_ai_news_trading_signals.html)** | 🌟 **[GitHub](https://github.com/tripolskypetr/backtest-kit)**
16
+
17
+ > **New to backtest-kit?** The fastest way to get a real, production-ready setup is to clone the [reference implementation](https://github.com/tripolskypetr/backtest-kit/tree/master/example) — a fully working news-sentiment AI trading system with LLM forecasting, multi-timeframe data, and a documented February 2026 backtest. Start there instead of from scratch.
18
+
19
+ ## ✨ Features
20
+
21
+ - 📈 **Multi-Timeframe Analysis**: 1m, 15m, 30m, 1h with synchronized indicator computation
22
+ - 🎯 **50+ Technical Indicators**: RSI, MACD, Bollinger Bands, Stochastic, ADX, ATR, CCI, Fibonacci, Support/Resistance
23
+ - 📊 **Order Book Analysis**: Bid/ask depth, spread, liquidity imbalance, top 20 levels
24
+ - 🤖 **AI-Ready Output**: Markdown reports formatted for LLM context injection
25
+ - ⚡ **Performance Optimized**: Intelligent caching with configurable TTL per timeframe
26
+ - 🧮 **Custom Algorithms**: Fibonacci retracements, support/resistance detection, volume analysis
27
+ - 📦 **Zero Config**: Works out-of-the-box with backtest-kit
28
+
29
+ ## 📋 What It Does
30
+
31
+ `@backtest-kit/signals` analyzes market data and generates comprehensive technical reports across multiple timeframes:
32
+
33
+ | Timeframe | Candles | Indicators | Use Case |
34
+ |-----------|---------|------------|----------|
35
+ | **MicroTerm** (1m) | 60 | RSI(9,14), MACD(8,21,5), Stochastic, ADX(9), Bollinger(8,2), ATR, CCI, Volume, Squeeze | Scalping, ultra-short entries |
36
+ | **ShortTerm** (15m) | 144 | RSI(9), MACD(8,21,5), Stochastic(5,3,3), ADX(14), Bollinger(10,2), Fibonacci | Day trading |
37
+ | **SwingTerm** (30m) | 96 | RSI(14), MACD(12,26,9), Stochastic(14,3,3), Bollinger(20,2), Support/Resistance | Swing trading |
38
+ | **LongTerm** (1h) | 100 | RSI(14), MACD(12,26,9), ADX(14), Bollinger(20,2), SMA(50), DEMA, WMA, Volume Trend | Trend analysis |
39
+
40
+ **Plus:** Real-time order book analysis with bid/ask depth and imbalance metrics.
41
+
42
+ ## 🚀 Installation
43
+
44
+ ```bash
45
+ npm install @backtest-kit/signals backtest-kit
46
+ ```
47
+
48
+ ## 📖 Usage
49
+
50
+ ### Quick Start - All-in-One Report
51
+
52
+ The easiest way to inject technical analysis into your LLM strategy:
53
+
54
+ ```typescript
55
+ import { commitHistorySetup } from '@backtest-kit/signals';
56
+ import { getCandles } from 'backtest-kit';
57
+
58
+ // In your strategy's getSignal function:
59
+ const messages = [];
60
+
61
+ // Add all technical analysis + order book + candle history
62
+ await commitHistorySetup('BTCUSDT', messages);
63
+
64
+ // Now messages contains:
65
+ // - Order book analysis (bids/asks, spread, imbalance)
66
+ // - Candle history (1m, 15m, 30m, 1h)
67
+ // - Technical indicators for all 4 timeframes
68
+ // - System info (symbol, price, timestamp)
69
+
70
+ // Send to LLM
71
+ const signal = await llm(messages);
72
+ ```
73
+
74
+ ### Granular Control - Individual Reports
75
+
76
+ For fine-grained control over what data to include:
77
+
78
+ ```typescript
79
+ import {
80
+ commitBookDataReport,
81
+ commitOneMinuteHistory,
82
+ commitFifteenMinuteHistory,
83
+ commitThirtyMinuteHistory,
84
+ commitHourHistory,
85
+ commitMicroTermMath,
86
+ commitShortTermMath,
87
+ commitSwingTermMath,
88
+ commitLongTermMath,
89
+ } from '@backtest-kit/signals';
90
+
91
+ const messages = [];
92
+
93
+ // Order book analysis
94
+ await commitBookDataReport('BTCUSDT', messages);
95
+
96
+ // Candle histories
97
+ await commitOneMinuteHistory('BTCUSDT', messages); // Last 15 candles
98
+ await commitFifteenMinuteHistory('BTCUSDT', messages); // Last 8 candles
99
+ await commitThirtyMinuteHistory('BTCUSDT', messages); // Last 6 candles
100
+ await commitHourHistory('BTCUSDT', messages); // Last 6 candles
101
+
102
+ // Technical indicators
103
+ await commitMicroTermMath('BTCUSDT', messages); // 1m indicators
104
+ await commitShortTermMath('BTCUSDT', messages); // 15m indicators
105
+ await commitSwingTermMath('BTCUSDT', messages); // 30m indicators
106
+ await commitLongTermMath('BTCUSDT', messages); // 1h indicators
107
+
108
+ // Send to LLM
109
+ const signal = await llm(messages);
110
+ ```
111
+
112
+ ### Complete LLM Strategy Example
113
+
114
+ ```typescript
115
+ import { v4 as uuid } from 'uuid';
116
+ import { addStrategy, dumpSignal } from 'backtest-kit';
117
+ import { commitHistorySetup } from '@backtest-kit/signals';
118
+ import { json } from './utils/json.mjs'; // Your LLM wrapper
119
+
120
+ addStrategy({
121
+ strategyName: 'llm-strategy',
122
+ interval: '5m',
123
+ riskName: 'demo',
124
+ getSignal: async (symbol) => {
125
+ const messages = [
126
+ {
127
+ role: 'system',
128
+ content: 'You are a trading bot. Analyze technical indicators and generate signals.'
129
+ }
130
+ ];
131
+
132
+ // Inject all technical analysis
133
+ await commitHistorySetup(symbol, messages);
134
+
135
+ // Add trading instructions
136
+ messages.push({
137
+ role: 'user',
138
+ content: [
139
+ 'Based on the technical analysis above, generate a trading signal.',
140
+ 'Use position: "wait" if signals are unclear or contradictory.',
141
+ 'Return JSON: { position: "long"|"short"|"wait", priceTakeProfit: number, priceStopLoss: number }'
142
+ ].join('\n')
143
+ });
144
+
145
+ // Generate signal via LLM
146
+ const resultId = uuid();
147
+ const signal = await json(messages);
148
+
149
+ // Save conversation for debugging
150
+ await dumpSignal(resultId, messages, signal);
151
+
152
+ return { ...signal, id: resultId };
153
+ }
154
+ });
155
+ ```
156
+
157
+ ### Custom Logger
158
+
159
+ By default, signals uses a no-op logger. To enable logging:
160
+
161
+ ```typescript
162
+ import { setLogger } from '@backtest-kit/signals';
163
+
164
+ setLogger({
165
+ log: console.log,
166
+ debug: console.debug,
167
+ info: console.info,
168
+ warn: console.warn,
169
+ });
170
+ ```
171
+
172
+ ## 📊 Generated Report Structure
173
+
174
+ ### Order Book Report
175
+
176
+ ```markdown
177
+ ## Order Book Analysis
178
+
179
+ **Symbol:** BTCUSDT
180
+ **Best Bid:** 50000.00 | **Best Ask:** 50001.00
181
+ **Mid Price:** 50000.50 | **Spread:** 1.00
182
+ **Depth Imbalance:** +5.2% (buy pressure)
183
+
184
+ ### Top 20 Levels (Bids)
185
+ | Price | Volume | % Total |
186
+ |-------|--------|---------|
187
+ | 50000.00 | 1.234 | 15.5% |
188
+ ...
189
+
190
+ ### Top 20 Levels (Asks)
191
+ | Price | Volume | % Total |
192
+ |-------|--------|---------|
193
+ | 50001.00 | 0.987 | 12.3% |
194
+ ...
195
+ ```
196
+
197
+ ### Candle History Report
198
+
199
+ ```markdown
200
+ ## 1-Minute Candle History (Last 15)
201
+
202
+ | Timestamp | Open | High | Low | Close | Volume | Volatility | Body Size |
203
+ |-----------|------|------|-----|-------|--------|------------|-----------|
204
+ | 2025-01-13 10:00 | 50000 | 50050 | 49990 | 50020 | 123.45 | 0.12% | 0.04% |
205
+ ...
206
+ ```
207
+
208
+ ### Technical Indicators Report
209
+
210
+ ```markdown
211
+ ## MicroTerm Analysis (1-Minute Timeframe)
212
+
213
+ | Time | Price | RSI(9) | RSI(14) | MACD | Signal | Histogram | Stoch %K | Stoch %D | ADX | +DI | -DI | BB Upper | BB Middle | BB Lower | ATR(5) | ATR(9) | CCI(9) | Volume | Vol Trend | Momentum | ROC | Support | Resistance | Squeeze | Pressure |
214
+ |------|-------|--------|---------|------|--------|-----------|----------|----------|-----|-----|-----|----------|-----------|----------|--------|--------|--------|--------|-----------|----------|-----|---------|------------|---------|----------|
215
+ | 10:00 | 50020 | 55.2 | 52.8 | 12.5 | 8.3 | 4.2 | 45.6 | 42.1 | 28.5 | 22.3 | 18.7 | 50100 | 50000 | 49900 | 15.2 | 18.9 | 45.7 | 123.45 | increasing | 0.8% | 1.2% | 49950 | 50100 | 0.85 | 15.2 |
216
+ ...
217
+
218
+ **Data Sources:**
219
+ - RSI periods: 9, 14
220
+ - MACD: Fast=8, Slow=21, Signal=5
221
+ - Stochastic: K=3, D=3, Smooth=3 (primary), K=5, D=3, Smooth=3 (secondary)
222
+ ...
223
+ ```
224
+
225
+ ## 🔄 Caching Strategy
226
+
227
+ Reports are cached to avoid redundant calculations:
228
+
229
+ | Timeframe | Cache Duration |
230
+ |-----------|----------------|
231
+ | 1-minute data | 1 minute |
232
+ | 15-minute data | 5 minutes |
233
+ | 30-minute data | 15 minutes |
234
+ | 1-hour data | 30 minutes |
235
+ | Order book | 5 minutes |
236
+
237
+ Cache is automatically cleared on errors.
238
+
239
+ ## 🧮 Key Algorithms
240
+
241
+ ### Support/Resistance Detection
242
+ - **MicroTerm/SwingTerm**: Looks back N candles for significant highs/lows (±0.3% threshold)
243
+ - **LongTerm**: 4-candle pivot point method
244
+
245
+ ### Fibonacci Retracement
246
+ - Calculates levels: 0%, 23.6%, 38.2%, 50%, 61.8%, 78.6%, 100%
247
+ - Extensions: 127.2%, 161.8%, 261.8%
248
+ - Finds nearest level to current price (1.5% tolerance)
249
+
250
+ ### Volume Analysis
251
+ - **MicroTerm**: SMA(5) volume with increasing/decreasing/stable trend (±20% threshold)
252
+ - **LongTerm**: 6-candle average comparison (±10% threshold)
253
+
254
+ ### Order Book Imbalance
255
+
256
+ Imbalance = (bid_volume - ask_volume) / (bid_volume + ask_volume)
257
+
258
+ Positive = buy pressure, Negative = sell pressure
259
+
260
+ ## 🎯 Use Cases
261
+
262
+ ### 1. LLM-Powered Trading Strategies
263
+ Inject technical analysis into your LLM's context for intelligent signal generation.
264
+
265
+ ### 2. Multi-Timeframe Confirmation
266
+ Combine indicators from different timeframes to filter false signals.
267
+
268
+ ### 3. Market Context for AI Agents
269
+ Provide comprehensive market state to AI agents making trading decisions.
270
+
271
+ ### 4. Debugging & Analysis
272
+ Save generated reports for post-analysis and strategy improvement.
273
+
274
+ ## 💡 Why Use @backtest-kit/signals?
275
+
276
+ Instead of manually calculating indicators and formatting data for your LLM:
277
+
278
+ ```typescript
279
+ // ❌ Without signals (manual work)
280
+ const candles = await getCandles('BTCUSDT', '1m', 60);
281
+ const rsi = calculateRSI(candles, 14);
282
+ const macd = calculateMACD(candles, 12, 26, 9);
283
+ const bb = calculateBollingerBands(candles, 20, 2);
284
+ // ... 40+ more indicators
285
+ const report = formatToMarkdown(rsi, macd, bb, ...);
286
+ messages.push({ role: 'user', content: report });
287
+ ```
288
+
289
+ ```typescript
290
+ // ✅ With signals (one line)
291
+ await commitHistorySetup('BTCUSDT', messages);
292
+ ```
293
+
294
+ **Benefits:**
295
+ - ⚡ Pre-computed, cached, optimized
296
+ - 📊 50+ indicators across 4 timeframes
297
+ - 🎨 Formatted markdown tables ready for LLM
298
+ - 🔄 Synchronized with backtest timeline
299
+ - 🛡️ Error handling and validation built-in
300
+
301
+ ## 🤝 Contribute
302
+
303
+ Fork/PR on [GitHub](https://github.com/tripolskypetr/backtest-kit).
304
+
305
+ ## 📜 License
306
+
307
+ MIT © [tripolskypetr](https://github.com/tripolskypetr)
package/package.json CHANGED
@@ -1,87 +1,87 @@
1
- {
2
- "name": "@backtest-kit/signals",
3
- "version": "7.8.0",
4
- "description": "Technical analysis and trading signal generation library for AI-powered trading systems. Computes 50+ indicators across 4 timeframes and generates markdown reports for LLM consumption.",
5
- "author": {
6
- "name": "Petr Tripolsky",
7
- "email": "tripolskypetr@gmail.com",
8
- "url": "https://github.com/tripolskypetr"
9
- },
10
- "funding": {
11
- "type": "individual",
12
- "url": "http://paypal.me/tripolskypetr"
13
- },
14
- "license": "MIT",
15
- "homepage": "https://backtest-kit.github.io/documents/article_07_ai_news_trading_signals.html",
16
- "keywords": [
17
- "framework",
18
- "technical-analysis",
19
- "trading-bot",
20
- "algorithmic-trading",
21
- "quantitative-trading",
22
- "stock-market",
23
- "cryptocurrency",
24
- "forex",
25
- "strategy-testing",
26
- "portfolio-management",
27
- "market-data",
28
- "ohlcv",
29
- "candlestick",
30
- "time-series"
31
- ],
32
- "files": [
33
- "build",
34
- "types.d.ts",
35
- "README.md"
36
- ],
37
- "repository": {
38
- "type": "git",
39
- "url": "https://github.com/tripolskypetr/backtest-kit",
40
- "documentation": "https://github.com/tripolskypetr/backtest-kit/tree/master/docs"
41
- },
42
- "bugs": {
43
- "url": "https://github.com/tripolskypetr/backtest-kit/issues"
44
- },
45
- "scripts": {
46
- "build": "rollup -c"
47
- },
48
- "main": "build/index.cjs",
49
- "module": "build/index.mjs",
50
- "source": "src/index.ts",
51
- "types": "./types.d.ts",
52
- "exports": {
53
- "require": "./build/index.cjs",
54
- "types": "./types.d.ts",
55
- "import": "./build/index.mjs",
56
- "default": "./build/index.cjs"
57
- },
58
- "devDependencies": {
59
- "@rollup/plugin-typescript": "11.1.6",
60
- "@types/node": "22.9.0",
61
- "glob": "11.0.1",
62
- "rimraf": "6.0.1",
63
- "rollup": "3.29.5",
64
- "rollup-plugin-dts": "6.1.1",
65
- "rollup-plugin-peer-deps-external": "2.2.4",
66
- "ts-morph": "27.0.2",
67
- "tslib": "2.7.0",
68
- "typedoc": "0.27.9",
69
- "backtest-kit": "7.8.0",
70
- "worker-testbed": "2.0.0"
71
- },
72
- "peerDependencies": {
73
- "backtest-kit": "^7.8.0",
74
- "typescript": "^5.0.0"
75
- },
76
- "dependencies": {
77
- "di-kit": "^1.1.1",
78
- "di-scoped": "^1.0.21",
79
- "functools-kit": "^2.3.0",
80
- "trading-signals": "^6.9.1",
81
- "get-moment-stamp": "^1.1.2",
82
- "agent-swarm-kit": "^2.6.0"
83
- },
84
- "publishConfig": {
85
- "access": "public"
86
- }
87
- }
1
+ {
2
+ "name": "@backtest-kit/signals",
3
+ "version": "8.0.0",
4
+ "description": "Technical analysis and trading signal generation library for AI-powered trading systems. Computes 50+ indicators across 4 timeframes and generates markdown reports for LLM consumption.",
5
+ "author": {
6
+ "name": "Petr Tripolsky",
7
+ "email": "tripolskypetr@gmail.com",
8
+ "url": "https://github.com/tripolskypetr"
9
+ },
10
+ "funding": {
11
+ "type": "individual",
12
+ "url": "http://paypal.me/tripolskypetr"
13
+ },
14
+ "license": "MIT",
15
+ "homepage": "https://backtest-kit.github.io/documents/article_07_ai_news_trading_signals.html",
16
+ "keywords": [
17
+ "framework",
18
+ "technical-analysis",
19
+ "trading-bot",
20
+ "algorithmic-trading",
21
+ "quantitative-trading",
22
+ "stock-market",
23
+ "cryptocurrency",
24
+ "forex",
25
+ "strategy-testing",
26
+ "portfolio-management",
27
+ "market-data",
28
+ "ohlcv",
29
+ "candlestick",
30
+ "time-series"
31
+ ],
32
+ "files": [
33
+ "build",
34
+ "types.d.ts",
35
+ "README.md"
36
+ ],
37
+ "repository": {
38
+ "type": "git",
39
+ "url": "https://github.com/tripolskypetr/backtest-kit",
40
+ "documentation": "https://github.com/tripolskypetr/backtest-kit/tree/master/docs"
41
+ },
42
+ "bugs": {
43
+ "url": "https://github.com/tripolskypetr/backtest-kit/issues"
44
+ },
45
+ "scripts": {
46
+ "build": "rollup -c"
47
+ },
48
+ "main": "build/index.cjs",
49
+ "module": "build/index.mjs",
50
+ "source": "src/index.ts",
51
+ "types": "./types.d.ts",
52
+ "exports": {
53
+ "require": "./build/index.cjs",
54
+ "types": "./types.d.ts",
55
+ "import": "./build/index.mjs",
56
+ "default": "./build/index.cjs"
57
+ },
58
+ "devDependencies": {
59
+ "@rollup/plugin-typescript": "11.1.6",
60
+ "@types/node": "22.9.0",
61
+ "glob": "11.0.1",
62
+ "rimraf": "6.0.1",
63
+ "rollup": "3.29.5",
64
+ "rollup-plugin-dts": "6.1.1",
65
+ "rollup-plugin-peer-deps-external": "2.2.4",
66
+ "ts-morph": "27.0.2",
67
+ "tslib": "2.7.0",
68
+ "typedoc": "0.27.9",
69
+ "backtest-kit": "8.0.0",
70
+ "worker-testbed": "2.0.0"
71
+ },
72
+ "peerDependencies": {
73
+ "backtest-kit": "^8.0.0",
74
+ "typescript": "^5.0.0"
75
+ },
76
+ "dependencies": {
77
+ "di-kit": "^1.1.1",
78
+ "di-scoped": "^1.0.21",
79
+ "functools-kit": "^2.3.0",
80
+ "trading-signals": "^6.9.1",
81
+ "get-moment-stamp": "^1.1.2",
82
+ "agent-swarm-kit": "^2.6.0"
83
+ },
84
+ "publishConfig": {
85
+ "access": "public"
86
+ }
87
+ }