@backtest-kit/sidekick 13.6.0 โ†’ 14.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 (3) hide show
  1. package/README.md +98 -91
  2. package/package.json +1 -1
  3. package/template/package.mustache +6 -6
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # ๐Ÿงฟ @backtest-kit/sidekick
2
2
 
3
- > The easiest way to create a new Backtest Kit trading bot project. Scaffolds a multi-timeframe crypto trading strategy with Pine Script indicators via [PineTS](https://github.com/QuantForgeOrg/PineTS) runtime, 4H trend filter + 15m signal generator, partial profit taking, breakeven trailing stops, and risk validation.
3
+ > The fastest way to start a [backtest-kit](https://www.npmjs.com/package/backtest-kit) trading bot โ€” but the *full-control* one. Scaffolds a complete multi-timeframe crypto strategy where every wire (exchange, frames, risk, actions, runner) is editable source in **your** project: a 4H trend filter + 15m signal generator in Pine Script, partial profit taking, breakeven trailing stops, and risk validation.
4
4
 
5
5
  ![screenshot](https://raw.githubusercontent.com/tripolskypetr/backtest-kit/HEAD/assets/screenshots/screenshot16.png)
6
6
 
@@ -8,41 +8,89 @@
8
8
  [![npm](https://img.shields.io/npm/v/@backtest-kit/sidekick.svg?style=flat-square)](https://npmjs.org/package/@backtest-kit/sidekick)
9
9
  [![License](https://img.shields.io/npm/l/@backtest-kit/sidekick.svg)](https://github.com/tripolskypetr/backtest-kit/blob/master/LICENSE)
10
10
 
11
- ๐Ÿ“š **[Backtest Kit Docs](https://backtest-kit.github.io/documents/article_07_ai_news_trading_signals.html)** | ๐ŸŒŸ **[GitHub](https://github.com/tripolskypetr/backtest-kit)**
11
+ ๐Ÿ“š **[Docs](https://backtest-kit.github.io/documents/article_07_ai_news_trading_signals.html)** ยท ๐ŸŒŸ **[Reference implementation](https://github.com/tripolskypetr/backtest-kit/tree/master/example)** ยท ๐Ÿ™ **[GitHub](https://github.com/tripolskypetr/backtest-kit)**
12
12
 
13
- ## โœจ Features
13
+ ```bash
14
+ npx -y @backtest-kit/sidekick my-trading-bot
15
+ cd my-trading-bot && npm start
16
+ ```
14
17
 
15
- - ๐Ÿš€ **Zero Config**: Get started with one command - no setup required
16
- - ๐Ÿ“Š **Multi-timeframe analysis** โ€” 4H daily trend filter (RSI + MACD + ADX) combined with 15m entry signals (EMA crossover + volume spike + momentum)
17
- - ๐Ÿ“œ **Pine Script indicators** โ€” strategies written in TradingView Pine Script v5, executed locally via `@backtest-kit/pinets`
18
- - ๐Ÿ›ก๏ธ **Risk management** โ€” SL/TP distance validation, Kelly-optimized partial profit taking (33/33/34%), breakeven trailing stop
19
- - ๐Ÿ”„ **Position lifecycle** โ€” full monitoring with scheduled/opened/closed/cancelled event logging
20
- - ๐Ÿ”Œ **Binance integration** โ€” OHLCV candles, order book depth, tick-precise price/quantity formatting via CCXT
21
- - ๐Ÿ• **Historical frames** โ€” predefined backtest periods covering bull runs, sharp drops, and sideways markets
22
- - ๐ŸŽจ **Web UI dashboard** โ€” interactive charting via `@backtest-kit/ui`
23
- - ๐Ÿ’พ **Persistent storage** โ€” crash-safe state with atomic persistence for both backtest and live modes
18
+ ---
24
19
 
25
- ## ๐Ÿš€ Quick Start
20
+ ## Init vs. Sidekick โ€” pick your level of control
26
21
 
27
- > **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.
22
+ `@backtest-kit/cli --init` keeps the boilerplate *inside* the CLI; your repo holds only strategy files. **Sidekick is the "eject":** it writes the entire wiring โ€” exchange adapter, frames, risk rules, actions, bootstrap, runner โ€” as plain, editable source in your project, with no CLI in the loop and nothing hidden. Choose Sidekick when you want to read and own every line, not just the strategy.
28
23
 
29
- ### Create a New Project
24
+ What you get out of the box: a working multi-timeframe Pine Script strategy (4H trend + 15m signals), SL/TP distance risk validation, partial profit taking + breakeven trailing stops, cache utilities and debug scripts, a `CLAUDE.md` for AI-assisted iteration, and environment config.
30
25
 
31
- ```bash
32
- npx -y @backtest-kit/sidekick my-trading-bot
33
- cd my-trading-bot
34
- npm start
35
- ```
26
+ - ๐Ÿš€ **Zero config** โ€” one command, no setup.
27
+ - ๐Ÿ“Š **Multi-timeframe** โ€” 4H trend filter (RSI+MACD+ADX) + 15m entries (EMA crossover + volume spike + momentum).
28
+ - ๐Ÿ“œ **Pine Script v5** โ€” strategies run locally via `@backtest-kit/pinets`, no TradingView.
29
+ - ๐Ÿ›ก๏ธ **Risk management** โ€” SL/TP distance validation, 33/33/34 partial profit, breakeven trailing.
30
+ - ๐Ÿ”„ **Full lifecycle** โ€” scheduled/opened/closed/cancelled event logging.
31
+ - ๐Ÿ”Œ **Binance via CCXT** โ€” OHLCV, order-book depth, tick-precise formatting.
32
+ - ๐Ÿ• **Historical frames** โ€” bull, sharp-drop, and sideways periods predefined.
33
+ - ๐ŸŽจ **Web dashboard** โ€” `@backtest-kit/ui` charting.
34
+ - ๐Ÿ’พ **Crash-safe storage** โ€” atomic persistence for backtest and live.
35
+
36
+ ---
37
+
38
+ ## The strategy it scaffolds
39
+
40
+ <details>
41
+ <summary>4H trend filter (timeframe_4h.pine)</summary>
42
+
43
+ Classifies the market regime from three indicators:
44
+
45
+ | Regime | Condition |
46
+ |--------|-----------|
47
+ | **AllowLong** | ADX > 25, MACD histogram > 0, DI+ > DIโˆ’, RSI > 50 |
48
+ | **AllowShort** | ADX > 25, MACD histogram < 0, DIโˆ’ > DI+, RSI < 50 |
49
+ | **AllowBoth** | Strong trend, no clear bull/bear regime |
50
+ | **NoTrades** | ADX โ‰ค 25 (weak trend) |
51
+
52
+ </details>
53
+
54
+ <details>
55
+ <summary>15m signal generator (timeframe_15m.pine)</summary>
56
+
57
+ EMA crossover confirmed by volume and momentum:
58
+
59
+ - **Long** โ€” EMA(5) crosses above EMA(13), RSI 40โ€“65, price above EMA(50), volume spike (>1.5ร— MA), positive momentum.
60
+ - **Short** โ€” EMA(5) crosses below EMA(13), RSI 35โ€“60, price below EMA(50), volume spike, negative momentum.
61
+ - **SL/TP** โ€” static 2% / 3% from entry. **Signal expiry** โ€” 5 bars.
62
+
63
+ </details>
64
+
65
+ <details>
66
+ <summary>Risk filters & position management</summary>
67
+
68
+ **Risk filters:** reject signals with SL distance < 0.2% or TP distance < 0.2% (slippage protection); enforce trend alignment (longs rejected in a bear regime, shorts in a bull regime).
69
+
70
+ **Position management:** partial profit taking scales out at three levels โ€” 33% at TP3, 33% at TP2, 34% at TP1; when breakeven is reached, the trailing stop is lowered by 3 points.
71
+
72
+ </details>
73
+
74
+ <details>
75
+ <summary>Backtest frames</summary>
76
+
77
+ | Frame | Period | Market note |
78
+ |-------|--------|-------------|
79
+ | `February2024` | Feb 1โ€“29, 2024 | Bull run |
80
+ | `October2025` | Oct 1โ€“31, 2025 | Sharp drop Oct 9โ€“11 |
81
+ | `November2025` | Nov 1โ€“30, 2025 | Sideways with downtrend |
82
+ | `December2025` | Dec 1โ€“31, 2025 | Sideways, no clear direction |
83
+
84
+ </details>
36
85
 
37
- That's it! You now have a working trading bot with:
38
- - Multi-timeframe Pine Script strategy (4H trend + 15m signals)
39
- - Risk management validation (SL/TP distance checks)
40
- - Partial profit taking and breakeven trailing stops
41
- - Cache utilities and debug scripts
42
- - CLAUDE.md for AI-assisted strategy iteration
43
- - Environment configuration
86
+ ---
44
87
 
45
- ## ๐Ÿ—๏ธ Generated Project Structure
88
+ ## Generated project structure
89
+
90
+ Everything below lands as editable source in your project โ€” this *is* the package's deliverable.
91
+
92
+ <details>
93
+ <summary>Full tree</summary>
46
94
 
47
95
  ```
48
96
  my-trading-bot/
@@ -51,9 +99,9 @@ my-trading-bot/
51
99
  โ”‚ โ”œโ”€โ”€ main/bootstrap.mjs # Mode dispatcher (backtest / paper / live)
52
100
  โ”‚ โ”œโ”€โ”€ config/
53
101
  โ”‚ โ”‚ โ”œโ”€โ”€ setup.mjs # Logger, storage, notifications, UI server
54
- โ”‚ โ”‚ โ”œโ”€โ”€ validate.mjs # Schema validation for all enums
55
- โ”‚ โ”‚ โ”œโ”€โ”€ params.mjs # Environment variables (Ollama API key)
56
- โ”‚ โ”‚ โ””โ”€โ”€ ccxt.mjs # Binance exchange singleton via CCXT
102
+ โ”‚ โ”‚ โ”œโ”€โ”€ validate.mjs # Schema validation for all enums
103
+ โ”‚ โ”‚ โ”œโ”€โ”€ params.mjs # Environment variables (Ollama API key)
104
+ โ”‚ โ”‚ โ””โ”€โ”€ ccxt.mjs # Binance exchange singleton via CCXT
57
105
  โ”‚ โ”œโ”€โ”€ logic/
58
106
  โ”‚ โ”‚ โ”œโ”€โ”€ strategy/main.strategy.mjs # Main strategy โ€” multi-TF signal logic
59
107
  โ”‚ โ”‚ โ”œโ”€โ”€ exchange/binance.exchange.mjs # Exchange schema โ€” candles, order book, formatting
@@ -69,10 +117,10 @@ my-trading-bot/
69
117
  โ”‚ โ”‚ โ”œโ”€โ”€ BacktestLowerStopOnBreakevenAction.mjs # Trailing stop on breakeven
70
118
  โ”‚ โ”‚ โ””โ”€โ”€ BacktestPositionMonitorAction.mjs # Position event logger
71
119
  โ”‚ โ”œโ”€โ”€ math/
72
- โ”‚ โ”‚ โ”œโ”€โ”€ timeframe_4h.math.mjs # 4H trend data โ€” RSI, MACD, ADX, DI+/DI-
120
+ โ”‚ โ”‚ โ”œโ”€โ”€ timeframe_4h.math.mjs # 4H trend data โ€” RSI, MACD, ADX, DI+/DIโˆ’
73
121
  โ”‚ โ”‚ โ””โ”€โ”€ timeframe_15m.math.mjs # 15m signal data โ€” EMA, ATR, volume, momentum
74
- โ”‚ โ”œโ”€โ”€ enum/ # String constants for type-safe schema refs
75
- โ”‚ โ””โ”€โ”€ utils/getArgs.mjs # CLI argument parser with defaults
122
+ โ”‚ โ”œโ”€โ”€ enum/ # String constants for type-safe schema refs
123
+ โ”‚ โ””โ”€โ”€ utils/getArgs.mjs # CLI argument parser with defaults
76
124
  โ”œโ”€โ”€ config/source/
77
125
  โ”‚ โ”œโ”€โ”€ timeframe_4h.pine # Pine Script v5 โ€” Daily Trend Filter (RSI/MACD/ADX)
78
126
  โ”‚ โ””โ”€โ”€ timeframe_15m.pine # Pine Script v5 โ€” Signal Strategy (EMA/ATR/Volume)
@@ -88,85 +136,44 @@ my-trading-bot/
88
136
  โ”‚ โ””โ”€โ”€ watch.sh # nvidia-smi monitor
89
137
  โ”œโ”€โ”€ CLAUDE.md # AI strategy development guide
90
138
  โ”œโ”€โ”€ .env # Environment variables
91
- โ””โ”€โ”€ package.json # Dependencies
139
+ โ””โ”€โ”€ package.json
92
140
  ```
93
141
 
94
- ## ๐Ÿ’ก Strategy Overview
95
-
96
- ### ๐ŸŽฏ 4H Trend Filter (`timeframe_4h.pine`)
97
-
98
- Determines the market regime using three indicators:
99
-
100
- | Regime | Condition |
101
- |--------|-----------|
102
- | **AllowLong** | ADX > 25, MACD histogram > 0, DI+ > DI-, RSI > 50 |
103
- | **AllowShort** | ADX > 25, MACD histogram < 0, DI- > DI+, RSI < 50 |
104
- | **AllowBoth** | Strong trend but no clear bull/bear regime |
105
- | **NoTrades** | ADX โ‰ค 25 (weak trend) |
106
-
107
- ### โšก 15m Signal Generator (`timeframe_15m.pine`)
108
-
109
- Generates entry signals with EMA crossover confirmed by volume and momentum:
142
+ </details>
110
143
 
111
- - **Long**: EMA(5) crosses above EMA(13), RSI 40โ€“65, price above EMA(50), volume spike (>1.5x MA), positive momentum
112
- - **Short**: EMA(5) crosses below EMA(13), RSI 35โ€“60, price below EMA(50), volume spike, negative momentum
113
- - **SL/TP**: Static 2%/3% from entry price
114
- - **Signal expiry**: 5 bars
144
+ ---
115
145
 
116
- ### ๐Ÿ›ก๏ธ Risk Filters
117
-
118
- - Reject signals where SL distance < 0.2% (slippage protection)
119
- - Reject signals where TP distance < 0.2% (slippage protection)
120
- - Trend alignment: long signals rejected in bear regime, short signals rejected in bull regime
121
-
122
- ### ๐Ÿ’น Position Management
123
-
124
- - **Partial profit taking**: Scale out at 3 levels โ€” 33% at TP3, 33% at TP2, 34% at TP1
125
- - **Breakeven trailing stop**: When breakeven is reached, lower trailing stop by 3 points
126
-
127
- ## ๐Ÿ• Backtest Frames
128
-
129
- | Frame | Period | Market Note |
130
- |-------|--------|-------------|
131
- | `February2024` | Feb 1โ€“29, 2024 | Bull run |
132
- | `October2025` | Oct 1โ€“31, 2025 | Sharp drop Oct 9โ€“11 |
133
- | `November2025` | Nov 1โ€“30, 2025 | Sideways with downtrend |
134
- | `December2025` | Dec 1โ€“31, 2025 | Sideways, no clear direction |
135
-
136
- ## ๐Ÿ’ก CLI Options
146
+ ## CLI options & dependencies
137
147
 
138
148
  ```bash
139
- # Create project with custom name
140
- npx -y @backtest-kit/sidekick my-bot
141
-
142
- # Create in current directory (must be empty)
143
- npx -y @backtest-kit/sidekick .
149
+ npx -y @backtest-kit/sidekick my-bot # named project
150
+ npx -y @backtest-kit/sidekick . # current directory (must be empty)
144
151
  ```
145
152
 
146
- ## ๐Ÿ“‹ Dependencies
153
+ <details>
154
+ <summary>Dependencies installed</summary>
147
155
 
148
156
  | Package | Purpose |
149
157
  |---------|---------|
150
- | [backtest-kit](https://libraries.io/npm/backtest-kit) | Core backtesting/trading framework |
151
- | [@backtest-kit/pinets](https://github.com/QuantForgeOrg/PineTS) | Pine Script v5 runtime for Node.js |
152
- | [@backtest-kit/ui](https://libraries.io/npm/backtest-kit) | Interactive charting dashboard |
153
- | [@backtest-kit/ollama](https://libraries.io/npm/backtest-kit) | LLM inference integration |
158
+ | [backtest-kit](https://www.npmjs.com/package/backtest-kit) | Core backtesting / trading framework |
159
+ | [@backtest-kit/pinets](https://www.npmjs.com/package/@backtest-kit/pinets) | Pine Script v5 runtime for Node.js |
160
+ | [@backtest-kit/ui](https://www.npmjs.com/package/@backtest-kit/ui) | Interactive charting dashboard |
161
+ | [@backtest-kit/ollama](https://www.npmjs.com/package/@backtest-kit/ollama) | LLM inference integration |
154
162
  | [ccxt](https://github.com/ccxt/ccxt) | Binance exchange connectivity |
155
163
  | [functools-kit](https://www.npmjs.com/package/functools-kit) | `singleshot`, `randomString` utilities |
156
164
  | [pinolog](https://www.npmjs.com/package/pinolog) | File-based structured logging |
157
165
  | [openai](https://www.npmjs.com/package/openai) | OpenAI API client |
158
166
  | [ollama](https://www.npmjs.com/package/ollama) | Ollama local LLM client |
159
167
 
168
+ </details>
169
+
160
170
  ## ๐Ÿ”— Links
161
171
 
162
- - [Backtest Kit Documentation](https://backtest-kit.github.io/documents/article_07_ai_news_trading_signals.html)
163
- - [GitHub Repository](https://github.com/tripolskypetr/backtest-kit)
164
- - [Demo Projects](https://github.com/tripolskypetr/backtest-kit/tree/master/demo)
165
- - [API Reference](https://backtest-kit.github.io/documents/article_07_ai_news_trading_signals.html)
172
+ [Documentation](https://backtest-kit.github.io/documents/article_07_ai_news_trading_signals.html) ยท [GitHub](https://github.com/tripolskypetr/backtest-kit) ยท [Reference implementation](https://github.com/tripolskypetr/backtest-kit/tree/master/example)
166
173
 
167
174
  ## ๐Ÿค Contribute
168
175
 
169
- Found a bug or want to add a feature? [Open an issue](https://github.com/tripolskypetr/backtest-kit/issues) or submit a PR!
176
+ Found a bug or want a feature? [Open an issue](https://github.com/tripolskypetr/backtest-kit/issues) or submit a PR.
170
177
 
171
178
  ## ๐Ÿ“œ License
172
179
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@backtest-kit/sidekick",
3
- "version": "13.6.0",
3
+ "version": "14.0.0",
4
4
  "description": "The easiest way to create a new Backtest Kit trading bot project. Like create-react-app, but for algorithmic trading with LLM integration and technical analysis.",
5
5
  "author": {
6
6
  "name": "Petr Tripolsky",
package/template/package.mustache CHANGED
@@ -9,17 +9,17 @@
9
9
  "start": "node ./src/index.mjs --backtest"
10
10
  },
11
11
  "dependencies": {
12
- "@backtest-kit/ollama": "^13.6.0",
13
- "@backtest-kit/pinets": "^13.6.0",
14
- "@backtest-kit/ui": "^13.6.0",
12
+ "@backtest-kit/ollama": "^14.0.0",
13
+ "@backtest-kit/pinets": "^14.0.0",
14
+ "@backtest-kit/ui": "^14.0.0",
15
15
  "@huggingface/inference": "^4.7.1",
16
16
  "@langchain/core": "^0.3.57",
17
17
  "@langchain/xai": "^0.0.2",
18
- "agent-swarm-kit": "^2.7.0",
19
- "backtest-kit": "^13.6.0",
18
+ "agent-swarm-kit": "^3.2.0",
19
+ "backtest-kit": "^14.0.0",
20
20
  "ccxt": "^4.4.41",
21
21
  "dotenv": "^16.4.7",
22
- "functools-kit": "^2.3.0",
22
+ "functools-kit": "^3.0.0",
23
23
  "ollama": "^0.6.0",
24
24
  "openai": "^4.97.0",
25
25
  "pinolog": "^1.0.5",