@backtest-kit/sidekick 0.1.1 → 3.0.0

package/content/scripts/run_timeframe_15m.mjs

@@ -0,0 +1,77 @@
+import { addExchangeSchema } from "backtest-kit";
+import { singleshot, randomString } from "functools-kit";
+import { run, File, toMarkdown } from "@backtest-kit/pinets";
+import ccxt from "ccxt";
+
+const SIGNAL_SCHEMA = {
+  position: "Signal",
+  priceOpen: "Close",
+  priceTakeProfit: "TakeProfit",
+  priceStopLoss: "StopLoss",
+  minuteEstimatedTime: "EstimatedTime",
+  d_RSI: "d_RSI",
+  d_EmaFast: "d_EmaFast",
+  d_EmaSlow: "d_EmaSlow",
+  d_EmaTrend: "d_EmaTrend",
+  d_ATR: "d_ATR",
+  d_Volume: "d_Volume",
+  d_VolMA: "d_VolMA",
+  d_VolSpike: "d_VolSpike",
+  d_Mom: "d_Mom",
+  d_MomUp: "d_MomUp",
+  d_MomDown: "d_MomDown",
+  d_TrendUp: "d_TrendUp",
+  d_TrendDown: "d_TrendDown",
+  d_LongCond: "d_LongCond",
+  d_ShortCond: "d_ShortCond",
+  d_BarsSinceSignal: "d_BarsSinceSignal",
+};
+
+const SIGNAL_ID = randomString();
+
+const getExchange = singleshot(async () => {
+  const exchange = new ccxt.binance({
+    options: {
+      defaultType: "spot",
+      adjustForTimeDifference: true,
+      recvWindow: 60000,
+    },
+    enableRateLimit: true,
+  });
+  await exchange.loadMarkets();
+  return exchange;
+});
+
+addExchangeSchema({
+  exchangeName: "ccxt-exchange",
+  getCandles: async (symbol, interval, since, limit) => {
+    const exchange = await getExchange();
+    const candles = await exchange.fetchOHLCV(
+      symbol,
+      interval,
+      since.getTime(),
+      limit,
+    );
+    return candles.map(([timestamp, open, high, low, close, volume]) => ({
+      timestamp,
+      open,
+      high,
+      low,
+      close,
+      volume,
+    }));
+  },
+});
+
+const plots = await run(
+  File.fromPath("timeframe_15m.pine"),
+  {
+    symbol: "BTCUSDT",
+    timeframe: "15m",
+    limit: 60,
+  },
+  "ccxt-exchange",
+  new Date("2025-09-23T16:00:00.000Z"),
+);
+
+console.log(await toMarkdown(SIGNAL_ID, plots, SIGNAL_SCHEMA));

package/content/scripts/run_timeframe_4h.mjs

@@ -0,0 +1,68 @@
+import { addExchangeSchema } from "backtest-kit";
+import { singleshot, randomString } from "functools-kit";
+import { run, File, toMarkdown } from "@backtest-kit/pinets";
+import ccxt from "ccxt";
+
+const SIGNAL_SCHEMA = {
+  allowLong: "AllowLong",
+  allowShort: "AllowShort",
+  allowBoth: "AllowBoth",
+  noTrades: "NoTrades",
+  rsi: "RSI",
+  adx: "ADX",
+  d_MACDLine: "d_MACDLine",
+  d_SignalLine: "d_SignalLine",
+  d_MACDHist: "d_MACDHist",
+  d_DIPlus: "d_DIPlus",
+  d_DIMinus: "d_DIMinus",
+  d_StrongTrend: "d_StrongTrend",
+};
+
+const SIGNAL_ID = randomString();
+
+const getExchange = singleshot(async () => {
+  const exchange = new ccxt.binance({
+    options: {
+      defaultType: "spot",
+      adjustForTimeDifference: true,
+      recvWindow: 60000,
+    },
+    enableRateLimit: true,
+  });
+  await exchange.loadMarkets();
+  return exchange;
+});
+
+addExchangeSchema({
+  exchangeName: "ccxt-exchange",
+  getCandles: async (symbol, interval, since, limit) => {
+    const exchange = await getExchange();
+    const candles = await exchange.fetchOHLCV(
+      symbol,
+      interval,
+      since.getTime(),
+      limit,
+    );
+    return candles.map(([timestamp, open, high, low, close, volume]) => ({
+      timestamp,
+      open,
+      high,
+      low,
+      close,
+      volume,
+    }));
+  },
+});
+
+const plots = await run(
+  File.fromPath("timeframe_4h.pine"),
+  {
+    symbol: "BTCUSDT",
+    timeframe: "4h",
+    limit: 60,
+  },
+  "ccxt-exchange",
+  new Date("2025-09-23T23:00:00.000Z"),
+);
+
+console.log(await toMarkdown(SIGNAL_ID, plots, SIGNAL_SCHEMA));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backtest-kit/sidekick",
-  "version": "0.1.1",
+  "version": "3.0.0",
   "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.",
   "author": {
     "name": "Petr Tripolsky",
@@ -37,7 +37,7 @@
     "src",
     "scripts",
     "template",
-    "types",
+    "content",
     "README.md"
   ],
   "repository": {

package/scripts/init.mjs

@@ -110,7 +110,7 @@ async function main() {
 
   const projectPath = path.resolve(process.cwd(), projectName);
   const srcTemplatePath = path.resolve(__dirname, '..', 'src');
-  const typesTemplatePath = path.resolve(__dirname, '..', 'types');
+  const contentPath = path.resolve(__dirname, '..', 'content');
   const templateDir = path.resolve(__dirname, '..', 'template');
 
   // Template data for Mustache
@@ -141,16 +141,32 @@ async function main() {
 
     // Copy source template files using glob
     {
-      log.info('Copying template files...');
+      log.info('Copying source files...');
       await copyFiles(srcTemplatePath, path.join(projectPath, 'src'));
-      log.success('Copied template files');
+      log.success('Copied source files');
     }
 
-    // Copy types template files
+    // Copy content files (config/, scripts/, docker/)
     {
-      log.info('Copying types files...');
-      await copyFiles(typesTemplatePath, path.join(projectPath, 'types'));
-      log.success('Copied types files');
+      log.info('Copying content files...');
+      await copyFiles(contentPath, projectPath);
+      log.success('Copied content files');
+    }
+
+    // Create types/backtest-kit.d.ts from template
+    {
+      log.info('Creating types/backtest-kit.d.ts...');
+      await fs.mkdir(path.join(projectPath, 'types'), { recursive: true });
+      const typesContent = await renderTemplate(
+        path.join(templateDir, 'types.mustache'),
+        templateData
+      );
+      await fs.writeFile(
+        path.join(projectPath, 'types', 'backtest-kit.d.ts'),
+        typesContent,
+        'utf-8'
+      );
+      log.success('Created types/backtest-kit.d.ts');
     }
 
     // Create package.json from template
@@ -216,7 +232,6 @@ async function main() {
         'utf-8'
       );
       log.success('Created README.md');
-      console.log();
     }
 
     // Create jsconfig.json from template
@@ -234,6 +249,22 @@ async function main() {
       log.success('Created jsconfig.json');
     }
 
+    // Create CLAUDE.md from template
+    {
+      log.info('Creating CLAUDE.md...');
+      const claudeContent = await renderTemplate(
+        path.join(templateDir, 'CLAUDE.mustache'),
+        templateData
+      );
+      await fs.writeFile(
+        path.join(projectPath, 'CLAUDE.md'),
+        claudeContent,
+        'utf-8'
+      );
+      log.success('Created CLAUDE.md');
+      console.log();
+    }
+
     // Install dependencies
     {
       await runNpmInstall(projectPath);
@@ -249,7 +280,7 @@ async function main() {
       console.log('Inside that directory, you can run several commands:');
       console.log();
       console.log(`  ${pc.cyan('npm start')}`);
-      console.log('    Starts the trading bot.');
+      console.log('    Runs the default backtest.');
       console.log();
       console.log('We suggest that you begin by typing:');
       console.log();

package/src/classes/BacktestLowerStopOnBreakevenAction.mjs

@@ -0,0 +1,18 @@
+import { ActionBase, commitTrailingStop } from "backtest-kit";
+
+/**
+ * Lowers trailing-stop by 3 points when breakeven is reached (ignores volatility)
+ * @implements {bt.IPublicAction}
+ */
+export class BacktestLowerStopOnBreakevenAction extends ActionBase {
+  /**
+   * 
+   * @param {bt.BreakevenContract} param0 
+   */
+  async breakevenAvailable({ symbol, currentPrice }) {
+    // Lower trailing-stop by 3 points (negative value brings stop-loss closer to entry)
+    await commitTrailingStop(symbol, -3, currentPrice);
+  }
+}
+
+export default BacktestLowerStopOnBreakevenAction;

package/src/classes/{PartialProfitTakingAction.mjs → BacktestPartialProfitTakingAction.mjs}

@@ -2,8 +2,13 @@ import { ActionBase, Constant, commitPartialProfit } from "backtest-kit";
 
 /**
  * Scale out at Kelly-optimized levels
+ * @implements {bt.IPublicAction}
  */
-export class PartialProfitTakingAction extends ActionBase {
+export class BacktestPartialProfitTakingAction extends ActionBase {
+  /**
+   * 
+   * @param {bt.PartialProfitContract} param0 
+   */
   async partialProfitAvailable({ symbol, level }) {
     if (level === Constant.TP_LEVEL3) {
       await commitPartialProfit(symbol, 33);
@@ -17,4 +22,4 @@ export class PartialProfitTakingAction extends ActionBase {
   }
 }
 
-export default PartialProfitTakingAction;
+export default BacktestPartialProfitTakingAction;

package/src/classes/BacktestPositionMonitorAction.mjs

@@ -0,0 +1,57 @@
+import { ActionBase } from "backtest-kit";
+
+/**
+ * Monitors position lifecycle and logs open/close events in backtest mode
+ * @implements {bt.IPublicAction}
+ */
+export class BacktestPositionMonitorAction extends ActionBase {
+  /**
+   * @param {bt.IStrategyTickResult} event 
+   */
+  async signalBacktest(event) {
+    switch (event.action) {
+      case "scheduled":
+        console.log(`[POSITION SCHEDULED] ${event.symbol}`);
+        console.log(`  Strategy: ${event.strategyName}`);
+        console.log(`  Current Price: ${event.currentPrice}`);
+        console.log(`  Entry Price: ${event.signal.priceOpen}`);
+        console.log(`  Signal ID: ${event.signal.id}`);
+        console.log(`  Direction: ${event.signal.position}`);
+        console.log(`  Stop Loss: ${event.signal.priceStopLoss}`);
+        console.log(`  Take Profit: ${event.signal.priceTakeProfit}`);
+        break;
+
+      case "opened":
+        console.log(`[POSITION OPENED] ${event.symbol}`);
+        console.log(`  Strategy: ${event.strategyName}`);
+        console.log(`  Entry Price: ${event.currentPrice}`);
+        console.log(`  Signal ID: ${event.signal.id}`);
+        console.log(`  Direction: ${event.signal.position}`);
+        console.log(`  Stop Loss: ${event.signal.priceStopLoss}`);
+        console.log(`  Take Profit: ${event.signal.priceTakeProfit}`);
+        break;
+
+      case "closed":
+        console.log(`[POSITION CLOSED] ${event.symbol}`);
+        console.log(`  Strategy: ${event.strategyName}`);
+        console.log(`  Entry Price (adj): ${event.pnl.priceOpen}`);
+        console.log(`  Exit Price (adj): ${event.pnl.priceClose}`);
+        console.log(`  Signal ID: ${event.signal.id}`);
+        console.log(`  Close Reason: ${event.closeReason}`);
+        console.log(`  PnL: ${event.pnl.pnlPercentage.toFixed(2)}%`);
+        console.log(`  Win: ${event.pnl.pnlPercentage > 0 ? "YES" : "NO"}`);
+        break;
+
+      case "cancelled":
+        console.log(`[POSITION CANCELLED] ${event.symbol}`);
+        console.log(`  Strategy: ${event.strategyName}`);
+        console.log(`  Signal ID: ${event.signal.id}`);
+        console.log(`  Current Price: ${event.currentPrice}`);
+        console.log(`  Cancel Reason: ${event.reason}`);
+        console.log(`  Cancelled At: ${new Date(event.closeTimestamp).toISOString()}`);
+        break;
+    }
+  }
+}
+
+export default BacktestPositionMonitorAction;

package/src/config/params.mjs

@@ -0,0 +1 @@
+export const CC_OLLAMA_API_KEY = process.env.CC_OLLAMA_API_KEY || "";

package/src/config/setup.mjs

@@ -1,4 +1,15 @@
-import { Markdown, Report, setLogger } from "backtest-kit"
+import {
+  Markdown,
+  Report,
+  Notification,
+  Storage,
+  setLogger,
+  StorageLive,
+  StorageBacktest,
+  NotificationLive,
+  NotificationBacktest,
+} from "backtest-kit";
+import { serve } from "@backtest-kit/ui";
 import { createLogger } from "pinolog";
 
 {
@@ -11,9 +22,24 @@ import { createLogger } from "pinolog";
   });
 }
 
+{
+  Storage.enable();
+  Notification.enable();
+}
+
 {
   Markdown.disable();
   Report.enable();
 }
 
+{
+  StorageLive.usePersist();
+  StorageBacktest.usePersist();
+}
+
+{
+  NotificationLive.usePersist();
+  NotificationBacktest.usePersist();
+}
 
+serve();

package/src/enum/ActionName.mjs

@@ -1,3 +1,5 @@
 export default {
-  PartialProfitTakingAction: "partial_profit_taking_action",
+  BacktestPartialProfitTakingAction: "backtest_partial_profit_taking_action",
+  BacktestLowerStopOnBreakevenAction: "backtest_lower_stop_on_breakeven_action",
+  BacktestPositionMonitorAction: "backtest_position_monitor_action",
 };

package/src/enum/FrameName.mjs

@@ -1,4 +1,5 @@
 export default {
+  February2024: "feb_2024_frame",
   October2025: "oct_2025_frame",
   November2025: "nov_2025_frame",
   December2025: "dec_2025_frame",

package/src/enum/RiskName.mjs

@@ -1,4 +1,4 @@
 export default {
   TakeProfitDistanceRisk: "tp_distance_risk",
-  RiskRewardRatioRisk: "rr_ratio_risk",
+  StopLossDistanceRisk: "sl_distance_risk",
 };

package/src/logic/action/backtest_lower_stop_on_breakeven.action.mjs

@@ -0,0 +1,9 @@
+import { addActionSchema } from "backtest-kit";
+import ActionName from "../../enum/ActionName.mjs";
+import { BacktestLowerStopOnBreakevenAction } from "../../classes/BacktestLowerStopOnBreakevenAction.mjs";
+
+addActionSchema({
+  actionName: ActionName.BacktestLowerStopOnBreakevenAction,
+  handler: BacktestLowerStopOnBreakevenAction,
+  note: "Lower trailing-stop by 3 points when breakeven is reached",
+});

package/src/logic/action/backtest_partial_profit_taking.action.mjs

@@ -0,0 +1,9 @@
+import { addActionSchema } from "backtest-kit";
+import ActionName from "../../enum/ActionName.mjs";
+import { BacktestPartialProfitTakingAction } from "../../classes/BacktestPartialProfitTakingAction.mjs";
+
+addActionSchema({
+  actionName: ActionName.BacktestPartialProfitTakingAction,
+  handler: BacktestPartialProfitTakingAction,
+  note: "Scale out at Kelly-optimized levels (33%, 33%, 34%)",
+});

package/src/logic/action/backtest_position_monitor.action.mjs

@@ -0,0 +1,9 @@
+import { addActionSchema } from "backtest-kit";
+import ActionName from "../../enum/ActionName.mjs";
+import { BacktestPositionMonitorAction } from "../../classes/BacktestPositionMonitorAction.mjs";
+
+addActionSchema({
+  actionName: ActionName.BacktestPositionMonitorAction,
+  handler: BacktestPositionMonitorAction,
+  note: "Monitors and logs position lifecycle events (open/close/scheduled)",
+});

package/src/logic/exchange/binance.exchange.mjs

@@ -12,8 +12,13 @@ addExchangeSchema({
       symbol,
       interval,
       since.getTime(),
-      limit
+      limit,
     );
+    if (
+      candles.flatMap((candle) => candle).some((value) => value === undefined)
+    ) {
+      throw new Error("Invalid candles found");
+    }
     return candles.map(([timestamp, open, high, low, close, volume]) => ({
       timestamp,
       open,
@@ -55,5 +60,10 @@ addExchangeSchema({
         quantity: String(quantity),
       })),
     };
-  }
+  },
+  callbacks: {
+    onCandleData(symbol, interval, since) {
+      console.log(`Received candle data for symbol: ${symbol}, interval: ${interval}, since: ${since.toUTCString()}`);
+    }
+  },
 });

package/src/logic/frame/feb_2024.frame.mjs

@@ -0,0 +1,10 @@
+import { addFrameSchema } from "backtest-kit";
+import FrameName from "../../enum/FrameName.mjs";
+
+addFrameSchema({
+  frameName: FrameName.February2024,
+  interval: "1m",
+  startDate: new Date("2024-02-01T00:00:00Z"),
+  endDate: new Date("2024-02-29T23:59:59Z"),
+  note: "Bull run period",
+});

package/src/logic/index.mjs

@@ -1,12 +1,15 @@
 import "./exchange/binance.exchange.mjs";
 
-import "./action/partial_profit_taking.action.mjs";
+import "./action/backtest_partial_profit_taking.action.mjs";
+import "./action/backtest_lower_stop_on_breakeven.action.mjs";
+import "./action/backtest_position_monitor.action.mjs";
 
 import "./frame/dec_2025.frame.mjs";
 import "./frame/nov_2025.frame.mjs";
 import "./frame/oct_2025.frame.mjs";
+import "./frame/feb_2024.frame.mjs";
 
-import "./risk/rr_ratio.risk.mjs";
+import "./risk/sl_distance.risk.mjs";
 import "./risk/tp_distance.risk.mjs";
 
 import "./strategy/main.strategy.mjs";

package/src/logic/risk/sl_distance.risk.mjs

@@ -0,0 +1,32 @@
+import { addRiskSchema } from "backtest-kit";
+import RiskName from "../../enum/RiskName.mjs";
+
+const SLIPPAGE_THRESHOLD = 0.2;
+
+addRiskSchema({
+  riskName: RiskName.StopLossDistanceRisk,
+  validations: [
+    {
+      validate: ({ currentSignal, currentPrice }) => {
+        const {
+          priceOpen = currentPrice,
+          priceStopLoss,
+          position,
+        } = currentSignal;
+        if (!priceOpen) {
+          return;
+        }
+        // Calculate SL distance percentage
+        const slDistance =
+          position === "long"
+            ? ((priceOpen - priceStopLoss) / priceOpen) * 100
+            : ((priceStopLoss - priceOpen) / priceOpen) * 100;
+
+        if (slDistance < SLIPPAGE_THRESHOLD) {
+          throw new Error(`SL distance ${slDistance.toFixed(2)}% < 1%`);
+        }
+      },
+      note: "SL distance must be at least 1%",
+    },
+  ],
+});

package/src/logic/risk/tp_distance.risk.mjs

@@ -1,16 +1,18 @@
 import { addRiskSchema } from "backtest-kit";
 import RiskName from "../../enum/RiskName.mjs";
 
+const SLIPPAGE_THRESHOLD = 0.2;
+
 addRiskSchema({
   riskName: RiskName.TakeProfitDistanceRisk,
   validations: [
     {
-      validate: ({ pendingSignal, currentPrice }) => {
+      validate: ({ currentSignal, currentPrice }) => {
         const {
           priceOpen = currentPrice,
           priceTakeProfit,
           position,
-        } = pendingSignal;
+        } = currentSignal;
         if (!priceOpen) {
           return;
         }
@@ -20,7 +22,7 @@ addRiskSchema({
             ? ((priceTakeProfit - priceOpen) / priceOpen) * 100
             : ((priceOpen - priceTakeProfit) / priceOpen) * 100;
 
-        if (tpDistance < 1) {
+        if (tpDistance < SLIPPAGE_THRESHOLD) {
           throw new Error(`TP distance ${tpDistance.toFixed(2)}% < 1%`);
         }
       },

package/src/logic/strategy/main.strategy.mjs

@@ -1,7 +1,8 @@
 import { addStrategySchema } from "backtest-kit";
-import { ollama } from "@backtest-kit/ollama";
+import { randomString } from "functools-kit";
 
-import { commitHistorySetup } from "../../func/market.func.mjs";
+import * as math_15m from "../../math/timeframe_15m.math.mjs";
+import * as math_4h from "../../math/timeframe_4h.math.mjs";
 
 import StrategyName from "../../enum/StrategyName.mjs";
 import RiskName from "../../enum/RiskName.mjs";
@@ -10,20 +11,38 @@ addStrategySchema({
   strategyName: StrategyName.MainStrategy,
   interval: "5m",
   getSignal: async (symbol) => {
-    const messages = [];
+
+    const signalId = randomString();
+    
+    const data_4h = await math_4h.getData(signalId, symbol);
+
+    if (data_4h.noTrades) {
+      return null;
+    }
+
+    const data_15m = await math_15m.getData(signalId, symbol);
+
+    if (data_15m.position === 0) {
+      return null;
+    }
+
+    if (data_4h.allowShort && data_15m.position === 1) {
+      return null;
+    }
+
+    if (data_4h.allowLong && data_15m.position === -1) {
+      return null;
+    }
 
     {
-      await commitHistorySetup(symbol, messages);
+      math_15m.dumpPlot(signalId, symbol);
+      math_4h.dumpPlot(signalId, symbol);
     }
 
-    return await ollama(
-      messages,
-      "glm-4.6:cloud",
-      process.env.CC_OLLAMA_API_KEY
-    );
+    return await math_15m.getSignal(signalId, symbol);
   },
   riskList: [
     RiskName.TakeProfitDistanceRisk, 
-    RiskName.RiskRewardRatioRisk
+    RiskName.StopLossDistanceRisk
   ],
 });

package/src/main/bootstrap.mjs

@@ -0,0 +1,52 @@
+import { Backtest, listenError, overrideStrategySchema } from "backtest-kit";
+
+import { getArgs } from "../utils/getArgs.mjs";
+
+import ActionName from "../enum/ActionName.mjs";
+
+const beginBacktest = async () => {
+  const { symbol, frameName, strategyName, exchangeName } = getArgs();
+
+  overrideStrategySchema({
+    strategyName,
+    actions: [
+      ActionName.BacktestPartialProfitTakingAction,
+      ActionName.BacktestLowerStopOnBreakevenAction,
+      ActionName.BacktestPositionMonitorAction,
+    ],
+  });
+
+  Backtest.background(symbol, {
+    strategyName,
+    frameName,
+    exchangeName,
+  });
+};
+
+const beginPaper = async () => {
+  throw new Error("Todo: implement");
+};
+
+const beginLive = async () => {
+  throw new Error("Todo: implement");
+};
+
+const main = async () => {
+  const { backtest, live, paper } = getArgs();
+
+  if (backtest) {
+    await beginBacktest();
+  }
+
+  if (paper) {
+    await beginPaper();
+  }
+
+  if (live) {
+    await beginLive();
+  }
+};
+
+listenError(console.log);
+
+main();