@backtest-kit/sidekick 0.1.1 → 3.0.0

package/README.md

@@ -1,25 +1,26 @@
 # 🧿 @backtest-kit/sidekick
 
-> The easiest way to create a new Backtest Kit trading bot project. Like create-react-app, but for algorithmic trading.
+> 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.
 
-![bots](https://raw.githubusercontent.com/tripolskypetr/backtest-kit/HEAD/assets/bots.png)
+![screenshot](https://raw.githubusercontent.com/tripolskypetr/backtest-kit/HEAD/assets/screenshots/screenshot8.png)
 
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/tripolskypetr/backtest-kit)
 [![npm](https://img.shields.io/npm/v/@backtest-kit/sidekick.svg?style=flat-square)](https://npmjs.org/package/@backtest-kit/sidekick)
 [![License](https://img.shields.io/npm/l/@backtest-kit/sidekick.svg)](https://github.com/tripolskypetr/backtest-kit/blob/master/LICENSE)
 
-Create production-ready trading bots in seconds with pre-configured templates, LLM integration, and technical analysis.
-
 📚 **[Backtest Kit Docs](https://backtest-kit.github.io/documents/example_02_first_backtest.html)** | 🌟 **[GitHub](https://github.com/tripolskypetr/backtest-kit)**
 
 ## ✨ Features
 
 - 🚀 **Zero Config**: Get started with one command - no setup required
-- 📦 **Complete Template**: Includes backtest strategy, risk management, and LLM integration
-- 🤖 **AI-Powered**: Pre-configured with DeepSeek, Claude, and GPT-5 fallback chain
-- 📊 **Technical Analysis**: Built-in 50+ indicators via @backtest-kit/signals
-- 🔑 **Environment Setup**: Auto-generated .env with all API key placeholders
-- 📝 **Best Practices**: Production-ready code structure with examples
+- 📊 **Multi-timeframe analysis** — 4H daily trend filter (RSI + MACD + ADX) combined with 15m entry signals (EMA crossover + volume spike + momentum)
+- 📜 **Pine Script indicators** — strategies written in TradingView Pine Script v5, executed locally via `@backtest-kit/pinets`
+- 🛡️ **Risk management** — SL/TP distance validation, Kelly-optimized partial profit taking (33/33/34%), breakeven trailing stop
+- 🔄 **Position lifecycle** — full monitoring with scheduled/opened/closed/cancelled event logging
+- 🔌 **Binance integration** — OHLCV candles, order book depth, tick-precise price/quantity formatting via CCXT
+- 🕐 **Historical frames** — predefined backtest periods covering bull runs, sharp drops, and sideways markets
+- 🎨 **Web UI dashboard** — interactive charting via `@backtest-kit/ui`
+- 💾 **Persistent storage** — crash-safe state with atomic persistence for both backtest and live modes
 
 ## 🚀 Quick Start
 
@@ -32,12 +33,104 @@ npm start
 ```
 
 That's it! You now have a working trading bot with:
-- Complete backtest setup
-- LLM-powered strategy
-- Multi-timeframe technical analysis
-- Risk management validation
+- Multi-timeframe Pine Script strategy (4H trend + 15m signals)
+- Risk management validation (SL/TP distance checks)
+- Partial profit taking and breakeven trailing stops
+- Cache utilities and debug scripts
+- CLAUDE.md for AI-assisted strategy iteration
 - Environment configuration
 
+## 🏗️ Generated Project Structure
+
+```
+my-trading-bot/
+├── src/
+│   ├── index.mjs                  # Entry point — loads config, logic, bootstrap
+│   ├── main/bootstrap.mjs         # Mode dispatcher (backtest / paper / live)
+│   ├── config/
+│   │   ├── setup.mjs              # Logger, storage, notifications, UI server
+│   │   ├── validate.mjs           # Schema validation for all enums
+│   │   ├── params.mjs             # Environment variables (Ollama API key)
+│   │   └── ccxt.mjs               # Binance exchange singleton via CCXT
+│   ├── logic/
+│   │   ├── strategy/main.strategy.mjs    # Main strategy — multi-TF signal logic
+│   │   ├── exchange/binance.exchange.mjs # Exchange schema — candles, order book, formatting
+│   │   ├── frame/*.frame.mjs             # Backtest time frames (Feb 2024, Oct–Dec 2025)
+│   │   ├── risk/sl_distance.risk.mjs     # Stop-loss distance validation (≥0.2%)
+│   │   ├── risk/tp_distance.risk.mjs     # Take-profit distance validation (≥0.2%)
+│   │   └── action/
+│   │       ├── backtest_partial_profit_taking.action.mjs
+│   │       ├── backtest_lower_stop_on_breakeven.action.mjs
+│   │       └── backtest_position_monitor.action.mjs
+│   ├── classes/
+│   │   ├── BacktestPartialProfitTakingAction.mjs  # Scale out at 3 TP levels
+│   │   ├── BacktestLowerStopOnBreakevenAction.mjs # Trailing stop on breakeven
+│   │   └── BacktestPositionMonitorAction.mjs      # Position event logger
+│   ├── math/
+│   │   ├── timeframe_4h.math.mjs   # 4H trend data — RSI, MACD, ADX, DI+/DI-
+│   │   └── timeframe_15m.math.mjs  # 15m signal data — EMA, ATR, volume, momentum
+│   ├── enum/                        # String constants for type-safe schema refs
+│   └── utils/getArgs.mjs            # CLI argument parser with defaults
+├── config/source/
+│   ├── timeframe_4h.pine    # Pine Script v5 — Daily Trend Filter (RSI/MACD/ADX)
+│   └── timeframe_15m.pine   # Pine Script v5 — Signal Strategy (EMA/ATR/Volume)
+├── scripts/
+│   ├── run_timeframe_15m.mjs # Standalone 15m Pine Script runner
+│   ├── run_timeframe_4h.mjs  # Standalone 4H Pine Script runner
+│   └── cache/
+│       ├── cache_candles.mjs     # Pre-download OHLCV candles (1m/15m/4h)
+│       ├── validate_candles.mjs  # Verify cached candle data integrity
+│       └── cache_model.mjs       # Pull Ollama LLM model with progress bar
+├── docker/ollama/
+│   ├── docker-compose.yaml   # Ollama GPU container setup
+│   └── watch.sh              # nvidia-smi monitor
+├── CLAUDE.md                 # AI strategy development guide
+├── .env                      # Environment variables
+└── package.json              # Dependencies
+```
+
+## 💡 Strategy Overview
+
+### 🎯 4H Trend Filter (`timeframe_4h.pine`)
+
+Determines the market regime using three indicators:
+
+| Regime | Condition |
+|--------|-----------|
+| **AllowLong** | ADX > 25, MACD histogram > 0, DI+ > DI-, RSI > 50 |
+| **AllowShort** | ADX > 25, MACD histogram < 0, DI- > DI+, RSI < 50 |
+| **AllowBoth** | Strong trend but no clear bull/bear regime |
+| **NoTrades** | ADX ≤ 25 (weak trend) |
+
+### ⚡ 15m Signal Generator (`timeframe_15m.pine`)
+
+Generates entry signals with EMA crossover confirmed by volume and momentum:
+
+- **Long**: EMA(5) crosses above EMA(13), RSI 40–65, price above EMA(50), volume spike (>1.5x MA), positive momentum
+- **Short**: EMA(5) crosses below EMA(13), RSI 35–60, price below EMA(50), volume spike, negative momentum
+- **SL/TP**: Static 2%/3% from entry price
+- **Signal expiry**: 5 bars
+
+### 🛡️ Risk Filters
+
+- Reject signals where SL distance < 0.2% (slippage protection)
+- Reject signals where TP distance < 0.2% (slippage protection)
+- Trend alignment: long signals rejected in bear regime, short signals rejected in bull regime
+
+### 💹 Position Management
+
+- **Partial profit taking**: Scale out at 3 levels — 33% at TP3, 33% at TP2, 34% at TP1
+- **Breakeven trailing stop**: When breakeven is reached, lower trailing stop by 3 points
+
+## 🕐 Backtest Frames
+
+| Frame | Period | Market Note |
+|-------|--------|-------------|
+| `February2024` | Feb 1–29, 2024 | Bull run |
+| `October2025` | Oct 1–31, 2025 | Sharp drop Oct 9–11 |
+| `November2025` | Nov 1–30, 2025 | Sideways with downtrend |
+| `December2025` | Dec 1–31, 2025 | Sideways, no clear direction |
+
 ## 💡 CLI Options
 
 ```bash
@@ -48,6 +141,20 @@ npx -y @backtest-kit/sidekick my-bot
 npx -y @backtest-kit/sidekick .
 ```
 
+## 📋 Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| [backtest-kit](https://libraries.io/npm/backtest-kit) | Core backtesting/trading framework |
+| [@backtest-kit/pinets](https://github.com/QuantForgeOrg/PineTS) | Pine Script v5 runtime for Node.js |
+| [@backtest-kit/ui](https://libraries.io/npm/backtest-kit) | Interactive charting dashboard |
+| [@backtest-kit/ollama](https://libraries.io/npm/backtest-kit) | LLM inference integration |
+| [ccxt](https://github.com/ccxt/ccxt) | Binance exchange connectivity |
+| [functools-kit](https://www.npmjs.com/package/functools-kit) | `singleshot`, `randomString` utilities |
+| [pinolog](https://www.npmjs.com/package/pinolog) | File-based structured logging |
+| [openai](https://www.npmjs.com/package/openai) | OpenAI API client |
+| [ollama](https://www.npmjs.com/package/ollama) | Ollama local LLM client |
+
 ## 🔗 Links
 
 - [Backtest Kit Documentation](https://backtest-kit.github.io/documents/example_02_first_backtest.html)

package/content/config/source/timeframe_15m.pine

@@ -0,0 +1,114 @@
+//@version=5
+indicator("Signal Strategy 15m v1", overlay=true)
+
+plotcandle(open, high, low, close, 
+     color=close > open ? color.new(color.green, 70) : color.new(color.red, 70),
+     wickcolor=color.new(color.gray, 70),
+     bordercolor=color.new(color.gray, 70))
+
+
+// === INPUTS ===
+rsi_len = input.int(7, "RSI Length", minval=2)
+ema_fast_len = input.int(5, "EMA Fast", minval=1)
+ema_slow_len = input.int(13, "EMA Slow", minval=1)
+ema_trend_len = input.int(50, "EMA Trend", minval=1)
+atr_len = input.int(14, "ATR Length", minval=1)
+vol_ma_len = input.int(20, "Volume MA Length", minval=1)
+
+sl_mult = input.float(1.5, "SL ATR Multiplier", minval=0.5, step=0.1)
+tp_mult = input.float(2.5, "TP ATR Multiplier", minval=0.5, step=0.1)
+signal_valid_bars = input.int(5, "Signal Valid Bars", minval=1)
+
+// === INDICATORS ===
+rsi = ta.rsi(close, rsi_len)
+ema_fast = ta.ema(close, ema_fast_len)
+ema_slow = ta.ema(close, ema_slow_len)
+ema_trend = ta.ema(close, ema_trend_len)
+atr = ta.atr(atr_len)
+
+// Volume filter - выше среднего
+vol_ma = ta.sma(volume, vol_ma_len)
+vol_spike = volume > vol_ma * 1.5
+
+// Momentum confirmation
+mom = ta.mom(close, 3)
+mom_up = mom > 0
+mom_down = mom < 0
+
+// === TREND FILTER ===
+trend_up = close > ema_trend and ema_fast > ema_trend
+trend_down = close < ema_trend and ema_fast < ema_trend
+
+// === ENTRY CONDITIONS ===
+// Long: пересечение + RSI не перекуплен + тренд вверх + объём + momentum
+long_cond = ta.crossover(ema_fast, ema_slow) and rsi > 40 and rsi < 65 and trend_up and vol_spike and mom_up
+
+// Short: пересечение + RSI не перепродан + тренд вниз + объём + momentum  
+short_cond = ta.crossunder(ema_fast, ema_slow) and rsi < 60 and rsi > 35 and trend_down and vol_spike and mom_down
+
+// === SIGNAL MANAGEMENT ===
+var int bars_since_signal = 0
+var int last_signal = 0
+var float entry_price = na
+var float signal_atr = na
+
+if long_cond
+    last_signal := 1
+    bars_since_signal := 0
+    entry_price := close
+    signal_atr := atr
+else if short_cond
+    last_signal := -1
+    bars_since_signal := 0
+    entry_price := close
+    signal_atr := atr
+else
+    bars_since_signal += 1
+
+// Signal expires faster on 15m
+active_signal = bars_since_signal <= signal_valid_bars ? last_signal : 0
+
+// === DYNAMIC SL/TP based on ATR ===
+// sl = last_signal == 1 ? entry_price - signal_atr * sl_mult : last_signal == -1 ? entry_price + signal_atr * sl_mult : na
+// tp = last_signal == 1 ? entry_price + signal_atr * tp_mult : last_signal == -1 ? entry_price - signal_atr * tp_mult : na
+
+// === STATIC SL/TP for watch strategy ==
+sl = last_signal == -1 ? close * 1.02 : close * 0.98
+tp = last_signal == -1 ? close * 0.97 : close * 1.03
+
+// === VISUALIZATION ===
+line_color = active_signal == 1 ? color.green : active_signal == -1 ? color.red : color.gray
+
+plot(ema_fast, "EMA Fast", color=color.new(color.blue, 50), linewidth=1)
+plot(ema_slow, "EMA Slow", color=color.new(color.orange, 50), linewidth=1)
+plot(ema_trend, "EMA Trend", color=color.new(color.white, 70), linewidth=2)
+
+plotshape(long_cond, "Long", shape.triangleup, location.belowbar, color.green, size=size.small)
+plotshape(short_cond, "Short", shape.triangledown, location.abovebar, color.red, size=size.small)
+
+plot(close, "Active Signal", color=line_color, linewidth=6)
+
+// === OUTPUTS FOR BOT ===
+plot(close, "Close", display=display.data_window)
+plot(active_signal, "Signal", display=display.data_window)
+plot(sl, "StopLoss", display=display.data_window)
+plot(tp, "TakeProfit", display=display.data_window)
+plot(1440, "EstimatedTime", display=display.data_window)  // 24 hour for 15m TF
+
+// === DEBUG: INDICATOR DUMP ===
+plot(rsi, "d_RSI", display=display.data_window)
+plot(ema_fast, "d_EmaFast", display=display.data_window)
+plot(ema_slow, "d_EmaSlow", display=display.data_window)
+plot(ema_trend, "d_EmaTrend", display=display.data_window)
+plot(atr, "d_ATR", display=display.data_window)
+plot(volume, "d_Volume", display=display.data_window)
+plot(vol_ma, "d_VolMA", display=display.data_window)
+plot(vol_spike ? 1 : 0, "d_VolSpike", display=display.data_window)
+plot(mom, "d_Mom", display=display.data_window)
+plot(mom_up ? 1 : 0, "d_MomUp", display=display.data_window)
+plot(mom_down ? 1 : 0, "d_MomDown", display=display.data_window)
+plot(trend_up ? 1 : 0, "d_TrendUp", display=display.data_window)
+plot(trend_down ? 1 : 0, "d_TrendDown", display=display.data_window)
+plot(long_cond ? 1 : 0, "d_LongCond", display=display.data_window)
+plot(short_cond ? 1 : 0, "d_ShortCond", display=display.data_window)
+plot(bars_since_signal, "d_BarsSinceSignal", display=display.data_window)

package/content/config/source/timeframe_4h.pine

@@ -0,0 +1,57 @@
+//@version=5
+indicator("Daily Trend Filter", overlay=true)
+
+plotcandle(open, high, low, close, 
+     color=close > open ? color.new(color.green, 70) : color.new(color.red, 70),
+     wickcolor=color.new(color.gray, 70),
+     bordercolor=color.new(color.gray, 70))
+
+// === INPUTS ===
+rsi_len = input.int(14, "RSI Length", minval=2)
+macd_fast = input.int(12, "MACD Fast", minval=1)
+macd_slow = input.int(26, "MACD Slow", minval=1)
+macd_signal = input.int(9, "MACD Signal", minval=1)
+adx_len = input.int(14, "ADX Length", minval=1)
+adx_threshold = input.int(25, "ADX Threshold", minval=10)
+
+rsi_bull_threshold = input.int(50, "RSI Bull Threshold", minval=50, maxval=70)
+rsi_bear_threshold = input.int(50, "RSI Bear Threshold", minval=30, maxval=50)
+
+// === INDICATORS ===
+rsi = ta.rsi(close, rsi_len)
+[macd_line, signal_line, macd_hist] = ta.macd(close, macd_fast, macd_slow, macd_signal)
+[di_plus, di_minus, adx] = ta.dmi(adx_len, adx_len)
+
+// === TREND FILTER LOGIC ===
+strong_trend = adx > adx_threshold
+
+bull_regime = strong_trend and macd_hist > 0 and di_plus > di_minus and rsi > rsi_bull_threshold
+
+bear_regime = strong_trend and macd_hist < 0 and di_minus > di_plus and rsi < rsi_bear_threshold
+
+both_allowed = strong_trend and not bull_regime and not bear_regime
+no_trades = not strong_trend
+
+// === VISUALIZATION ===
+line_color = bull_regime ? color.green : 
+             bear_regime ? color.red : 
+             both_allowed ? color.gray :
+             color.orange
+
+plot(close, "Active Signal", color=line_color, linewidth=6)
+
+// === OUTPUTS FOR BOT ===
+plot(bull_regime ? 1 : 0, "AllowLong", display=display.data_window)
+plot(bear_regime ? 1 : 0, "AllowShort", display=display.data_window)
+plot(both_allowed ? 1 : 0, "AllowBoth", display=display.data_window)
+plot(no_trades ? 1 : 0, "NoTrades", display=display.data_window)
+plot(rsi, "RSI", display=display.data_window)
+plot(adx, "ADX", display=display.data_window)
+
+// === DEBUG: INDICATOR DUMP ===
+plot(macd_line, "d_MACDLine", display=display.data_window)
+plot(signal_line, "d_SignalLine", display=display.data_window)
+plot(macd_hist, "d_MACDHist", display=display.data_window)
+plot(di_plus, "d_DIPlus", display=display.data_window)
+plot(di_minus, "d_DIMinus", display=display.data_window)
+plot(strong_trend ? 1 : 0, "d_StrongTrend", display=display.data_window)