backtest-kit 1.1.7 → 1.1.9

package/README.md

@@ -1,89 +1,284 @@
 # 🧿 Backtest Kit
 
-> A production-ready TypeScript framework for backtesting and live trading strategies with crash-safe state persistence, signal validation, and memory-optimized architecture.
+> **A production-ready TypeScript framework for backtesting and live trading strategies with crash-safe state persistence, signal validation, and memory-optimized architecture.**
 
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/tripolskypetr/backtest-kit)
+[![npm](https://img.shields.io/npm/v/backtest-kit.svg?style=flat-square)](https://npmjs.org/package/backtest-kit)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)]()
-[![Architecture](https://img.shields.io/badge/architecture-clean-orange)]()
-
-## Features
-
-- 🚀 **Production-Ready Architecture** - Backtest/live mode, robust error recovery
-- 💾 **Crash-Safe Persistence** - Atomic file writes with automatic state recovery
-- ✅ **Signal Validation** - Comprehensive validation prevents invalid trades
-- 🔄 **Async Generators** - Memory-efficient streaming for backtest and live execution
-- 📊 **VWAP Pricing** - Volume-weighted average price from last 5 1m candles
-- 🎯 **Signal Lifecycle** - Type-safe state machine (idle → opened → active → closed)
-- 📈 **Accurate PNL** - Calculation with fees (0.1%) and slippage (0.1%)
-- 🧠 **Interval Throttling** - Prevents signal spam at strategy level
-- ⚡ **Memory Optimized** - Prototype methods + memoization + streaming
-- 🔌 **Flexible Architecture** - Plug your own exchanges and strategies
-- 📝 **Markdown Reports** - Auto-generated trading reports with statistics (win rate, avg PNL, Sharpe Ratio, Standard Deviation, Certainty Ratio, Expected Yearly Returns, Risk-Adjusted Returns)
-- 🛑 **Graceful Shutdown** - Live.background() waits for open positions to close before stopping
-- 💉 **Strategy Dependency Injection** - addStrategy() enables DI pattern for trading strategies
-- 🔍 **Schema Reflection API** - listExchanges(), listStrategies(), listFrames() for runtime introspection
-- 🧪 **Comprehensive Test Coverage** - 50+ unit tests covering validation, PNL, callbacks, reports, and event system
-- 💾 **Zero Data Download** - Unlike Freqtrade, no need to download gigabytes of historical data - plug any data source (CCXT, database, API)
-- 🔒 **Safe Math & Robustness** - All metrics protected against NaN/Infinity with unsafe numeric checks, returns N/A for invalid calculations
-
-## Installation
+
+Build sophisticated trading systems with confidence. Backtest Kit empowers you to develop, test, and deploy algorithmic trading strategies with enterprise-grade reliability—featuring atomic state persistence, comprehensive validation, and memory-efficient execution. Whether you're backtesting historical data or running live strategies, this framework provides the tools you need to trade with precision.
+
+📚 **[API Reference](https://github.com/tripolskypetr/backtest-kit)** | 🌟 **[Quick Start](#quick-start)**
+
+## 🎯 Supported Order Types
+
+Backtest Kit supports multiple execution styles to match real trading behavior:
+
+## ✨ Why Choose Backtest Kit?
+
+- 🚀 **Production-Ready Architecture**: Seamlessly switch between backtest and live modes with robust error recovery and graceful shutdown mechanisms. Your strategy code remains identical across environments. ✅
+
+- 💾 **Crash-Safe Persistence**: Atomic file writes with automatic state recovery ensure no duplicate signals or lost data—even after crashes. Resume execution exactly where you left off. 🔄
+
+- ✅ **Signal Validation**: Comprehensive validation prevents invalid trades before execution. Catches price logic errors (TP/SL), throttles signal spam, and ensures data integrity. 🛡️
+
+- 🔄 **Async Generator Architecture**: Memory-efficient streaming for backtest and live execution. Process years of historical data without loading everything into memory. ⚡
+
+- 📊 **VWAP Pricing**: Volume-weighted average price from last 5 1-minute candles ensures realistic backtest results that match live execution. 📈
+
+- 🎯 **Type-Safe Signal Lifecycle**: State machine with compile-time guarantees (idle → opened → active → closed). No runtime state confusion. 🔒
+
+- 📈 **Accurate PNL Calculation**: Realistic profit/loss with configurable fees (0.1%) and slippage (0.1%). Track gross and net returns separately. 💰
+
+- ⏰ **Time-Travel Context**: Async context propagation allows same strategy code to run in backtest (with historical time) and live (with real-time) without modifications. 🌐
+
+- 📝 **Auto-Generated Reports**: Markdown reports with statistics (win rate, avg PNL, Sharpe Ratio, standard deviation, certainty ratio, expected yearly returns, risk-adjusted returns). 📊
+
+- 📊 **Revenue Profiling**: Built-in performance tracking with aggregated statistics (avg, min, max, stdDev, P95, P99) for bottleneck analysis. ⚡
+
+- 🏃 **Strategy Comparison (Walker)**: Compare multiple strategies in parallel with automatic ranking and statistical analysis. Find your best performer. 🏆
+
+- 🔥 **Portfolio Heatmap**: Multi-symbol performance analysis with extended metrics (Profit Factor, Expectancy, Win/Loss Streaks, Avg Win/Loss) sorted by Sharpe Ratio. 📉
+
+- 💰 **Position Sizing Calculator**: Built-in position sizing methods (Fixed Percentage, Kelly Criterion, ATR-based) with risk management constraints. 💵
+
+- 🛡️ **Risk Management System**: Portfolio-level risk controls with custom validation logic, concurrent position limits, and cross-strategy coordination. 🔐
+
+- 💾 **Zero Data Download**: Unlike Freqtrade, no need to download gigabytes of historical data—plug any data source (CCXT, database, API). 🚀
+
+- 🔌 **Pluggable Persistence**: Replace default file-based persistence with custom adapters (Redis, MongoDB, PostgreSQL) for distributed systems and high-performance scenarios. 💾
+
+- 🔒 **Safe Math & Robustness**: All metrics protected against NaN/Infinity with unsafe numeric checks. Returns N/A for invalid calculations. ✨
+
+- 🧪 **Comprehensive Test Coverage**: 109 unit and integration tests covering validation, PNL, callbacks, reports, performance tracking, walker, heatmap, position sizing, risk management, and event system. ✅
+
+---
+
+### ✅ Built-in Order Types
+
+-   **Market** — instant execution using current VWAP
+    
+-   **Limit** — entry at a specified `priceOpen`
+    
+-   **Take Profit (TP)** — automatic exit at the target price
+    
+-   **Stop Loss (SL)** — protective exit at the stop level
+    
+-   **OCO (TP + SL)** — linked exits; one cancels the other
+    
+-   **Time-Expired** — automatic closure after `minuteEstimatedTime` ⏱️
+    
+
+### ➕ Extendable Order Types
+
+Easy to add without modifying the core:
+
+-   **Stop / Stop-Limit** — entry triggered by `triggerPrice`
+    
+-   **Trailing Stop** — dynamic SL based on market movement
+    
+-   **Conditional Entry** — enter only if price breaks a level (`above` / `below`)
+    
+-   **Post-Only / Reduce-Only** — exchange-level execution flags
+
+---
+
+## 🚀 Getting Started
+
+### Installation
+
+Get up and running in seconds:
 
 ```bash
 npm install backtest-kit
 ```
 
-## Quick Start
+### Quick Example
 
-### 1. Register Exchange Data Source
+Here's a taste of what `backtest-kit` can do—create a simple moving average crossover strategy with crash-safe persistence:
 
 ```typescript
-import { addExchange } from "backtest-kit";
-import ccxt from "ccxt"; // Example using CCXT library
+import {
+  addExchange,
+  addStrategy,
+  addFrame,
+  Backtest,
+  listenSignalBacktest,
+  listenError,
+  listenDoneBacktest
+} from "backtest-kit";
+import ccxt from "ccxt";
 
+// 1. Register exchange data source
 addExchange({
   exchangeName: "binance",
-
-  // Fetch historical candles
   getCandles: async (symbol, interval, since, limit) => {
     const exchange = new ccxt.binance();
     const ohlcv = await exchange.fetchOHLCV(symbol, interval, since.getTime(), limit);
-
     return ohlcv.map(([timestamp, open, high, low, close, volume]) => ({
-      timestamp,
-      open,
-      high,
-      low,
-      close,
-      volume,
+      timestamp, open, high, low, close, volume
     }));
   },
+  formatPrice: async (symbol, price) => price.toFixed(2),
+  formatQuantity: async (symbol, quantity) => quantity.toFixed(8),
+});
 
-  // Format price according to exchange rules (e.g., 2 decimals for BTC)
-  formatPrice: async (symbol, price) => {
-    const exchange = new ccxt.binance();
-    const market = exchange.market(symbol);
-    return exchange.priceToPrecision(symbol, price);
+// 2. Register trading strategy
+addStrategy({
+  strategyName: "sma-crossover",
+  interval: "5m", // Throttling: signals generated max once per 5 minutes
+  getSignal: async (symbol) => {
+    // Your signal generation logic
+    return {
+      position: "long",
+      note: "BTC breakout",
+      priceOpen: 50000,
+      priceTakeProfit: 51000,  // Must be > priceOpen for long
+      priceStopLoss: 49000,     // Must be < priceOpen for long
+      minuteEstimatedTime: 60,  // Signal duration in minutes
+    };
   },
-
-  // Format quantity according to exchange rules (e.g., 8 decimals)
-  formatQuantity: async (symbol, quantity) => {
-    const exchange = new ccxt.binance();
-    return exchange.amountToPrecision(symbol, quantity);
+  callbacks: {
+    onOpen: (symbol, signal, currentPrice, backtest) => {
+      console.log(`[${backtest ? "BT" : "LIVE"}] Signal opened:`, signal.id);
+    },
+    onClose: (symbol, signal, priceClose, backtest) => {
+      console.log(`[${backtest ? "BT" : "LIVE"}] Signal closed:`, priceClose);
+    },
   },
 });
+
+// 3. Add timeframe generator
+addFrame({
+  frameName: "1d-backtest",
+  interval: "1m",
+  startDate: new Date("2024-01-01T00:00:00Z"),
+  endDate: new Date("2024-01-02T00:00:00Z"),
+});
+
+// 4. Run backtest in background
+Backtest.background("BTCUSDT", {
+  strategyName: "sma-crossover",
+  exchangeName: "binance",
+  frameName: "1d-backtest"
+});
+
+// Listen to closed signals
+listenSignalBacktest((event) => {
+  if (event.action === "closed") {
+    console.log("PNL:", event.pnl.pnlPercentage);
+  }
+});
+
+// Listen to backtest completion
+listenDoneBacktest((event) => {
+  console.log("Backtest completed:", event.symbol);
+  Backtest.dump(event.strategyName); // ./logs/backtest/sma-crossover.md
+});
+```
+
+The feature of this library is dependency inversion for component injection. Exchanges, strategies, frames, and risk profiles are lazy-loaded during runtime, so you can declare them in separate modules and connect them with string constants 🧩
+
+```typescript
+export enum ExchangeName {
+  Binance = "binance",
+  Bybit = "bybit",
+}
+
+export enum StrategyName {
+  SMACrossover = "sma-crossover",
+  RSIStrategy = "rsi-strategy",
+}
+
+export enum FrameName {
+  OneDay = "1d-backtest",
+  OneWeek = "1w-backtest",
+}
+
+// ...
+
+addStrategy({
+  strategyName: StrategyName.SMACrossover,
+  interval: "5m",
+  // ...
+});
+
+Backtest.background("BTCUSDT", {
+  strategyName: StrategyName.SMACrossover,
+  exchangeName: ExchangeName.Binance,
+  frameName: FrameName.OneDay
+});
 ```
 
-**Alternative: Database implementation**
+---
+
+## 🌟 Key Features
+
+- 🤝 **Mode Switching**: Seamlessly switch between backtest and live modes with identical strategy code. 🔄
+- 📜 **Crash Recovery**: Atomic persistence ensures state recovery after crashes—no duplicate signals. 🗂️
+- 🛠️ **Custom Validators**: Define validation rules with strategy-level throttling and price logic checks. 🔧
+- 🛡️ **Signal Lifecycle**: Type-safe state machine prevents invalid state transitions. 🚑
+- 📦 **Dependency Inversion**: Lazy-load components at runtime for modular, scalable designs. 🧩
+- 🔍 **Schema Reflection**: Runtime introspection with `listExchanges()`, `listStrategies()`, `listFrames()`. 📊
+
+---
+
+## 🎯 Use Cases
+
+- 📈 **Algorithmic Trading**: Backtest and deploy systematic trading strategies with confidence. 💹
+- 🤖 **Strategy Development**: Rapid prototyping with automatic validation and PNL tracking. 🛠️
+- 📊 **Performance Analysis**: Compare strategies with Walker and analyze portfolios with Heatmap. 📉
+- 💼 **Portfolio Management**: Multi-symbol trading with risk controls and position sizing. 🏦
+
+---
+
+## 📖 API Highlights
+
+- 🛠️ **`addExchange`**: Define exchange data sources (CCXT, database, API). 📡
+- 🤖 **`addStrategy`**: Create trading strategies with custom signals and callbacks. 💡
+- 🌐 **`addFrame`**: Configure timeframes for backtesting. 📅
+- 🔄 **`Backtest` / `Live`**: Run strategies in backtest or live mode (generator or background). ⚡
+- 🏃 **`Walker`**: Compare multiple strategies in parallel with ranking. 🏆
+- 🔥 **`Heat`**: Portfolio-wide performance analysis across multiple symbols. 📊
+- 💰 **`PositionSize`**: Calculate position sizes with Fixed %, Kelly Criterion, or ATR-based methods. 💵
+- 🛡️ **`addRisk`**: Portfolio-level risk management with custom validation logic. 🔐
+- 💾 **`PersistBase`**: Base class for custom persistence adapters (Redis, MongoDB, PostgreSQL). 🗄️
+- 🔌 **`PersistSignalAdapter` / `PersistRiskAdapter`**: Register custom adapters for signal and risk persistence. 🔄
+
+Check out the sections below for detailed examples! 📚
+
+---
+
+## 🛠 Advanced Features
+
+### 1. Register Exchange Data Source
+
+You can plug any data source—CCXT for live data or a database for faster backtesting:
 
 ```typescript
 import { addExchange } from "backtest-kit";
-import { db } from "./database"; // Your database client
+import ccxt from "ccxt";
 
+// Option 1: CCXT (live or historical)
 addExchange({
-  exchangeName: "binance-db",
+  exchangeName: "binance",
+  getCandles: async (symbol, interval, since, limit) => {
+    const exchange = new ccxt.binance();
+    const ohlcv = await exchange.fetchOHLCV(symbol, interval, since.getTime(), limit);
+    return ohlcv.map(([timestamp, open, high, low, close, volume]) => ({
+      timestamp, open, high, low, close, volume
+    }));
+  },
+  formatPrice: async (symbol, price) => price.toFixed(2),
+  formatQuantity: async (symbol, quantity) => quantity.toFixed(8),
+});
+
+// Option 2: Database (faster backtesting)
+import { db } from "./database";
 
+addExchange({
+  exchangeName: "binance-db",
   getCandles: async (symbol, interval, since, limit) => {
-    // Fetch from database for faster backtesting
     return await db.query(`
       SELECT timestamp, open, high, low, close, volume
       FROM candles
@@ -92,7 +287,6 @@ addExchange({
       LIMIT $4
     `, [symbol, interval, since, limit]);
   },
-
   formatPrice: async (symbol, price) => price.toFixed(2),
   formatQuantity: async (symbol, quantity) => quantity.toFixed(8),
 });
@@ -100,6 +294,8 @@ addExchange({
 
 ### 2. Register Trading Strategy
 
+Define your signal generation logic with automatic validation:
+
 ```typescript
 import { addStrategy } from "backtest-kit";
 
@@ -108,7 +304,6 @@ addStrategy({
   interval: "5m", // Throttling: signals generated max once per 5 minutes
   getSignal: async (symbol) => {
     // Your signal generation logic
-    // Validation happens automatically (prices, TP/SL logic)
     return {
       position: "long",
       note: "BTC breakout",
@@ -129,62 +324,48 @@ addStrategy({
 });
 ```
 
-### 3. Add Timeframe Generator
+### 3. Run Backtest
 
-```typescript
-import { addFrame } from "backtest-kit";
-
-addFrame({
-  frameName: "1d-backtest",
-  interval: "1m",
-  startDate: new Date("2024-01-01T00:00:00Z"),
-  endDate: new Date("2024-01-02T00:00:00Z"),
-  callbacks: {
-    onTimeframe: (timeframe, startDate, endDate, interval) => {
-      console.log(`Generated ${timeframe.length} timeframes from ${startDate} to ${endDate}`);
-    },
-  },
-});
-```
-
-### 4. Run Backtest
+Run strategies in background mode (infinite loop) or manually iterate with async generators:
 
 ```typescript
-import { Backtest, listenSignalBacktest, listenError, listenDone } from "backtest-kit";
+import { Backtest, listenSignalBacktest, listenDoneBacktest } from "backtest-kit";
 
-// Run backtest in background
+// Option 1: Background mode (recommended)
 const stopBacktest = Backtest.background("BTCUSDT", {
   strategyName: "my-strategy",
   exchangeName: "binance",
   frameName: "1d-backtest"
 });
 
-// Listen to closed signals
 listenSignalBacktest((event) => {
   if (event.action === "closed") {
     console.log("PNL:", event.pnl.pnlPercentage);
   }
 });
 
-// Listen to errors
-listenError((error) => {
-  console.error("Error:", error.message);
+listenDoneBacktest((event) => {
+  console.log("Backtest completed:", event.symbol);
+  Backtest.dump(event.strategyName); // ./logs/backtest/my-strategy.md
 });
 
-// Listen to completion
-listenDone((event) => {
-  if (event.backtest) {
-    console.log("Backtest completed:", event.symbol);
-    // Generate and save report
-    Backtest.dump(event.strategyName); // ./logs/backtest/my-strategy.md
-  }
-});
+// Option 2: Manual iteration (for custom control)
+for await (const result of Backtest.run("BTCUSDT", {
+  strategyName: "my-strategy",
+  exchangeName: "binance",
+  frameName: "1d-backtest"
+})) {
+  console.log("PNL:", result.pnl.pnlPercentage);
+  if (result.pnl.pnlPercentage < -5) break; // Early termination
+}
 ```
 
-### 5. Run Live Trading (Crash-Safe)
+### 4. Run Live Trading (Crash-Safe)
+
+Live mode automatically persists state to disk with atomic writes:
 
 ```typescript
-import { Live, listenSignalLive, listenError, listenDone } from "backtest-kit";
+import { Live, listenSignalLive } from "backtest-kit";
 
 // Run live trading in background (infinite loop, crash-safe)
 const stop = Live.background("BTCUSDT", {
@@ -192,7 +373,6 @@ const stop = Live.background("BTCUSDT", {
   exchangeName: "binance"
 });
 
-// Listen to all signal events
 listenSignalLive((event) => {
   if (event.action === "opened") {
     console.log("Signal opened:", event.signal.id);
@@ -203,923 +383,711 @@ listenSignalLive((event) => {
       reason: event.closeReason,
       pnl: event.pnl.pnlPercentage,
     });
-
-    // Auto-save report
-    Live.dump(event.strategyName);
-  }
-});
-
-// Listen to errors
-listenError((error) => {
-  console.error("Error:", error.message);
-});
-
-// Listen to completion
-listenDone((event) => {
-  if (!event.backtest) {
-    console.log("Live trading stopped:", event.symbol);
+    Live.dump(event.strategyName); // Auto-save report
   }
 });
 
 // Stop when needed: stop();
 ```
 
-**Crash Recovery:** If process crashes, restart with same code - state automatically recovered from disk (no duplicate signals).
-
-### 6. Alternative: Async Generators (Optional)
-
-For manual control over execution flow:
-
-```typescript
-import { Backtest, Live } from "backtest-kit";
+**Crash Recovery:** If process crashes, restart with same code—state automatically recovered from disk (no duplicate signals).
 
-// Manual backtest iteration
-for await (const result of Backtest.run("BTCUSDT", {
-  strategyName: "my-strategy",
-  exchangeName: "binance",
-  frameName: "1d-backtest"
-})) {
-  console.log("PNL:", result.pnl.pnlPercentage);
-  if (result.pnl.pnlPercentage < -5) break; // Early termination
-}
+### 5. Strategy Comparison with Walker
 
-// Manual live iteration (infinite loop)
-for await (const result of Live.run("BTCUSDT", {
-  strategyName: "my-strategy",
-  exchangeName: "binance"
-})) {
-  if (result.action === "closed") {
-    console.log("PNL:", result.pnl.pnlPercentage);
-  }
-}
-```
-
-### 7. Schema Reflection API (Optional)
-
-Retrieve registered schemas at runtime for debugging, documentation, or building dynamic UIs:
+Walker runs multiple strategies in parallel and ranks them by a selected metric:
 
 ```typescript
-import {
-  addExchange,
-  addStrategy,
-  addFrame,
-  listExchanges,
-  listStrategies,
-  listFrames
-} from "backtest-kit";
+import { addWalker, Walker, listenWalkerComplete } from "backtest-kit";
 
-// Register schemas with notes
-addExchange({
+// Register walker schema
+addWalker({
+  walkerName: "btc-walker",
   exchangeName: "binance",
-  note: "Binance cryptocurrency exchange with database backend",
-  getCandles: async (symbol, interval, since, limit) => [...],
-  formatPrice: async (symbol, price) => price.toFixed(2),
-  formatQuantity: async (symbol, quantity) => quantity.toFixed(8),
+  frameName: "1d-backtest",
+  strategies: ["strategy-a", "strategy-b", "strategy-c"],
+  metric: "sharpeRatio", // Metric to compare strategies
+  callbacks: {
+    onStrategyStart: (strategyName, symbol) => {
+      console.log(`Starting strategy: ${strategyName}`);
+    },
+    onStrategyComplete: (strategyName, symbol, stats) => {
+      console.log(`${strategyName} completed:`, stats.sharpeRatio);
+    },
+    onComplete: (results) => {
+      console.log("Best strategy:", results.bestStrategy);
+      console.log("Best metric:", results.bestMetric);
+    },
+  },
 });
 
-addStrategy({
-  strategyName: "sma-crossover",
-  note: "Simple moving average crossover strategy (50/200)",
-  interval: "5m",
-  getSignal: async (symbol) => ({...}),
+// Run walker in background
+Walker.background("BTCUSDT", {
+  walkerName: "btc-walker"
 });
 
-addFrame({
-  frameName: "january-2024",
-  note: "Full month backtest for January 2024",
-  interval: "1m",
-  startDate: new Date("2024-01-01"),
-  endDate: new Date("2024-02-01"),
+// Listen to walker completion
+listenWalkerComplete((results) => {
+  console.log("Walker completed:", results.bestStrategy);
+  Walker.dump("BTCUSDT", results.walkerName); // Save report
 });
 
-// List all registered schemas
-const exchanges = await listExchanges();
-console.log("Available exchanges:", exchanges.map(e => ({
-  name: e.exchangeName,
-  note: e.note
-})));
-// Output: [{ name: "binance", note: "Binance cryptocurrency exchange..." }]
-
-const strategies = await listStrategies();
-console.log("Available strategies:", strategies.map(s => ({
-  name: s.strategyName,
-  note: s.note,
-  interval: s.interval
-})));
-// Output: [{ name: "sma-crossover", note: "Simple moving average...", interval: "5m" }]
-
-const frames = await listFrames();
-console.log("Available frames:", frames.map(f => ({
-  name: f.frameName,
-  note: f.note,
-  period: `${f.startDate.toISOString()} - ${f.endDate.toISOString()}`
-})));
-// Output: [{ name: "january-2024", note: "Full month backtest...", period: "2024-01-01..." }]
+// Get raw comparison data
+const results = await Walker.getData("BTCUSDT", "btc-walker");
+console.log(results);
+// Returns:
+// {
+//   bestStrategy: "strategy-b",
+//   bestMetric: 1.85,
+//   strategies: [
+//     { strategyName: "strategy-a", stats: { sharpeRatio: 1.23, ... }, metric: 1.23 },
+//     { strategyName: "strategy-b", stats: { sharpeRatio: 1.85, ... }, metric: 1.85 },
+//     { strategyName: "strategy-c", stats: { sharpeRatio: 0.98, ... }, metric: 0.98 }
+//   ]
+// }
+
+// Generate markdown report
+const markdown = await Walker.getReport("BTCUSDT", "btc-walker");
+console.log(markdown);
 ```
 
-**Use cases:**
-- Generate documentation automatically from registered schemas
-- Build admin dashboards showing available strategies and exchanges
-- Create CLI tools with auto-completion based on registered schemas
-- Validate configuration files against registered schemas
+**Available metrics for comparison:**
+- `sharpeRatio` - Risk-adjusted return (default)
+- `winRate` - Win percentage
+- `avgPnl` - Average PNL percentage
+- `totalPnl` - Total PNL percentage
+- `certaintyRatio` - avgWin / |avgLoss|
 
-## Architecture Overview
+### 6. Portfolio Heatmap
 
-The framework follows **clean architecture** with:
+Heat provides portfolio-wide performance analysis across multiple symbols:
 
-- **Client Layer** - Pure business logic without DI (ClientStrategy, ClientExchange, ClientFrame)
-- **Service Layer** - DI-based services organized by responsibility
-  - **Schema Services** - Registry pattern for configuration
-  - **Connection Services** - Memoized client instance creators
-  - **Global Services** - Context wrappers for public API
-  - **Logic Services** - Async generator orchestration (backtest/live)
-- **Persistence Layer** - Crash-safe atomic file writes with `PersistSignalAdaper`
+```typescript
+import { Heat, Backtest } from "backtest-kit";
+
+// Run backtests for multiple symbols
+for (const symbol of ["BTCUSDT", "ETHUSDT", "SOLUSDT", "BNBUSDT"]) {
+  for await (const _ of Backtest.run(symbol, {
+    strategyName: "my-strategy",
+    exchangeName: "binance",
+    frameName: "2024-backtest"
+  })) {}
+}
 
-See [ARCHITECTURE.md](./ARCHITECTURE.md) for detailed documentation.
+// Get raw heatmap data
+const stats = await Heat.getData("my-strategy");
+console.log(stats);
+// Returns:
+// {
+//   symbols: [
+//     {
+//       symbol: "BTCUSDT",
+//       totalPnl: 15.5,           // Total profit/loss %
+//       sharpeRatio: 2.10,        // Risk-adjusted return
+//       profitFactor: 2.50,       // Wins / Losses ratio
+//       expectancy: 1.85,         // Expected value per trade
+//       winRate: 72.3,            // Win percentage
+//       avgWin: 2.45,             // Average win %
+//       avgLoss: -0.95,           // Average loss %
+//       maxDrawdown: -2.5,        // Maximum drawdown %
+//       maxWinStreak: 5,          // Consecutive wins
+//       maxLossStreak: 2,         // Consecutive losses
+//       totalTrades: 45,
+//       winCount: 32,
+//       lossCount: 13,
+//       avgPnl: 0.34,
+//       stdDev: 1.62
+//     },
+//     // ... more symbols sorted by Sharpe Ratio
+//   ],
+//   totalSymbols: 4,
+//   portfolioTotalPnl: 45.3,      // Portfolio-wide total PNL
+//   portfolioSharpeRatio: 1.85,   // Portfolio-wide Sharpe
+//   portfolioTotalTrades: 120
+// }
 
-## Signal Validation
+// Generate markdown report
+const markdown = await Heat.getReport("my-strategy");
+console.log(markdown);
 
-All signals are validated automatically before execution:
+// Save to disk (default: ./logs/heatmap/my-strategy.md)
+await Heat.dump("my-strategy");
+```
 
-```typescript
-// ✅ Valid long signal
-{
-  position: "long",
-  priceOpen: 50000,
-  priceTakeProfit: 51000,  // ✅ 51000 > 50000
-  priceStopLoss: 49000,     // ✅ 49000 < 50000
-  minuteEstimatedTime: 60,  // ✅ positive
-}
+**Heatmap Report Example:**
+```markdown
+# Portfolio Heatmap: my-strategy
 
-// ❌ Invalid long signal - throws error
-{
-  position: "long",
-  priceOpen: 50000,
-  priceTakeProfit: 49000,  // ❌ 49000 < 50000 (must be higher for long)
-  priceStopLoss: 51000,    // ❌ 51000 > 50000 (must be lower for long)
-}
+**Total Symbols:** 4 | **Portfolio PNL:** +45.30% | **Portfolio Sharpe:** 1.85 | **Total Trades:** 120
 
-// ✅ Valid short signal
-{
-  position: "short",
-  priceOpen: 50000,
-  priceTakeProfit: 49000,  // ✅ 49000 < 50000 (profit goes down for short)
-  priceStopLoss: 51000,    // ✅ 51000 > 50000 (stop loss goes up for short)
-}
+| Symbol | Total PNL | Sharpe | PF | Expect | WR | Avg Win | Avg Loss | Max DD | W Streak | L Streak | Trades |
+|--------|-----------|--------|-------|--------|-----|---------|----------|--------|----------|----------|--------|
+| BTCUSDT | +15.50% | 2.10 | 2.50 | +1.85% | 72.3% | +2.45% | -0.95% | -2.50% | 5 | 2 | 45 |
+| ETHUSDT | +12.30% | 1.85 | 2.15 | +1.45% | 68.5% | +2.10% | -1.05% | -3.10% | 4 | 2 | 38 |
+| SOLUSDT | +10.20% | 1.65 | 1.95 | +1.20% | 65.2% | +1.95% | -1.15% | -4.20% | 3 | 3 | 25 |
+| BNBUSDT | +7.30% | 1.40 | 1.75 | +0.95% | 62.5% | +1.75% | -1.20% | -3.80% | 3 | 2 | 12 |
 ```
 
-Validation errors include detailed messages for debugging.
+**Column Descriptions:**
+- **Total PNL** - Total profit/loss percentage across all trades
+- **Sharpe** - Risk-adjusted return (higher is better)
+- **PF** - Profit Factor: sum of wins / sum of losses (>1.0 is profitable)
+- **Expect** - Expectancy: expected value per trade
+- **WR** - Win Rate: percentage of winning trades
+- **Avg Win** - Average profit on winning trades
+- **Avg Loss** - Average loss on losing trades
+- **Max DD** - Maximum drawdown (largest peak-to-trough decline)
+- **W Streak** - Maximum consecutive winning trades
+- **L Streak** - Maximum consecutive losing trades
+- **Trades** - Total number of trades for this symbol
 
-## Custom Persistence Adapter
+### 7. Position Sizing Calculator
 
-By default, signals are persisted to disk using atomic file writes (`./logs/data/signal/`). You can override the persistence layer with a custom adapter (e.g., Redis, MongoDB):
+Position Sizing Calculator helps determine optimal position sizes based on risk management rules:
 
 ```typescript
-import { PersistBase, PersistSignalAdaper, ISignalData, EntityId } from "backtest-kit";
-import Redis from "ioredis";
+import { addSizing, PositionSize } from "backtest-kit";
+
+// Fixed Percentage Risk - risk fixed % of account per trade
+addSizing({
+  sizingName: "conservative",
+  note: "Conservative 2% risk per trade",
+  method: "fixed-percentage",
+  riskPercentage: 2,                // Risk 2% of account per trade
+  maxPositionPercentage: 10,        // Max 10% of account in single position (optional)
+  minPositionSize: 0.001,           // Min 0.001 BTC position (optional)
+  maxPositionSize: 1.0,             // Max 1.0 BTC position (optional)
+});
 
-// Create custom Redis adapter
-class RedisPersist extends PersistBase {
-  private redis = new Redis({
-    host: "localhost",
-    port: 6379,
-  });
+// Kelly Criterion - optimal bet sizing based on edge
+addSizing({
+  sizingName: "kelly-quarter",
+  note: "Kelly Criterion with 25% multiplier for safety",
+  method: "kelly-criterion",
+  kellyMultiplier: 0.25,            // Use 25% of full Kelly (recommended for safety)
+  maxPositionPercentage: 15,        // Cap position at 15% of account (optional)
+  minPositionSize: 0.001,           // Min 0.001 BTC position (optional)
+  maxPositionSize: 2.0,             // Max 2.0 BTC position (optional)
+});
 
-  async waitForInit(initial: boolean): Promise<void> {
-    // Initialize Redis connection if needed
-    await this.redis.ping();
-  }
+// ATR-based - volatility-adjusted position sizing
+addSizing({
+  sizingName: "atr-dynamic",
+  note: "ATR-based sizing with 2x multiplier",
+  method: "atr-based",
+  riskPercentage: 2,                // Risk 2% of account
+  atrMultiplier: 2,                 // Use 2x ATR as stop distance
+  maxPositionPercentage: 12,        // Max 12% of account (optional)
+  minPositionSize: 0.001,           // Min 0.001 BTC position (optional)
+  maxPositionSize: 1.5,             // Max 1.5 BTC position (optional)
+});
 
-  async readValue(entityId: EntityId): Promise<ISignalData> {
-    const key = `${this.entityName}:${entityId}`;
-    const data = await this.redis.get(key);
+// Calculate position sizes
+const quantity1 = await PositionSize.fixedPercentage(
+  "BTCUSDT",
+  10000,      // Account balance: $10,000
+  50000,      // Entry price: $50,000
+  49000,      // Stop loss: $49,000
+  { sizingName: "conservative" }
+);
+console.log(`Position size: ${quantity1} BTC`);
+
+const quantity2 = await PositionSize.kellyCriterion(
+  "BTCUSDT",
+  10000,      // Account balance: $10,000
+  50000,      // Entry price: $50,000
+  0.55,       // Win rate: 55%
+  1.5,        // Win/loss ratio: 1.5
+  { sizingName: "kelly-quarter" }
+);
+console.log(`Position size: ${quantity2} BTC`);
+
+const quantity3 = await PositionSize.atrBased(
+  "BTCUSDT",
+  10000,      // Account balance: $10,000
+  50000,      // Entry price: $50,000
+  500,        // ATR: $500
+  { sizingName: "atr-dynamic" }
+);
+console.log(`Position size: ${quantity3} BTC`);
+```
 
-    if (!data) {
-      throw new Error(`Entity ${this.entityName}:${entityId} not found`);
-    }
+**When to Use Each Method:**
 
-    return JSON.parse(data);
-  }
+1. **Fixed Percentage** - Simple risk management, consistent risk per trade
+   - Best for: Beginners, conservative strategies
+   - Risk: Fixed 1-2% per trade
 
-  async hasValue(entityId: EntityId): Promise<boolean> {
-    const key = `${this.entityName}:${entityId}`;
-    const exists = await this.redis.exists(key);
-    return exists === 1;
-  }
+2. **Kelly Criterion** - Optimal bet sizing based on win rate and win/loss ratio
+   - Best for: Strategies with known edge, statistical advantage
+   - Risk: Use fractional Kelly (0.25-0.5) to reduce volatility
 
-  async writeValue(entityId: EntityId, entity: ISignalData): Promise<void> {
-    const key = `${this.entityName}:${entityId}`;
-    await this.redis.set(key, JSON.stringify(entity));
-  }
-}
+3. **ATR-based** - Volatility-adjusted sizing, accounts for market conditions
+   - Best for: Swing trading, volatile markets
+   - Risk: Position size scales with volatility
 
-// Register custom adapter
-PersistSignalAdaper.usePersistSignalAdapter(RedisPersist);
+### 8. Risk Management
 
-// Now all signal persistence uses Redis
-Live.background("BTCUSDT", {
-  strategyName: "my-strategy",
-  exchangeName: "binance"
+Risk Management provides portfolio-level risk controls across strategies:
+
+```typescript
+import { addRisk } from "backtest-kit";
+
+// Simple concurrent position limit
+addRisk({
+  riskName: "conservative",
+  note: "Conservative risk profile with max 3 concurrent positions",
+  validations: [
+    ({ activePositionCount }) => {
+      if (activePositionCount >= 3) {
+        throw new Error("Maximum 3 concurrent positions allowed");
+      }
+    },
+  ],
+  callbacks: {
+    onRejected: (symbol, params) => {
+      console.warn(`Signal rejected for ${symbol}:`, params);
+    },
+    onAllowed: (symbol, params) => {
+      console.log(`Signal allowed for ${symbol}`);
+    },
+  },
 });
-```
 
-**Key methods to implement:**
-- `waitForInit(initial)` - Initialize storage connection
-- `readValue(entityId)` - Read entity from storage
-- `hasValue(entityId)` - Check if entity exists
-- `writeValue(entityId, entity)` - Write entity to storage
+// Symbol-based filtering
+addRisk({
+  riskName: "no-meme-coins",
+  note: "Block meme coins from trading",
+  validations: [
+    ({ symbol }) => {
+      const memeCoins = ["DOGEUSDT", "SHIBUSDT", "PEPEUSDT"];
+      if (memeCoins.includes(symbol)) {
+        throw new Error(`Meme coin ${symbol} not allowed`);
+      }
+    },
+  ],
+});
 
-The adapter is registered globally and applies to all strategies.
+// Time-based trading windows
+addRisk({
+  riskName: "trading-hours",
+  note: "Only trade during market hours (9 AM - 5 PM UTC)",
+  validations: [
+    ({ timestamp }) => {
+      const date = new Date(timestamp);
+      const hour = date.getUTCHours();
+
+      if (hour < 9 || hour >= 17) {
+        throw new Error("Trading only allowed 9 AM - 5 PM UTC");
+      }
+    },
+  ],
+});
 
-## Interval Throttling
+// Multi-strategy coordination with position inspection
+addRisk({
+  riskName: "strategy-coordinator",
+  note: "Limit exposure per strategy and inspect active positions",
+  validations: [
+    ({ activePositions, strategyName, symbol }) => {
+      // Count positions for this specific strategy
+      const strategyPositions = activePositions.filter(
+        (pos) => pos.strategyName === strategyName
+      );
+
+      if (strategyPositions.length >= 2) {
+        throw new Error(`Strategy ${strategyName} already has 2 positions`);
+      }
 
-Prevent signal spam with automatic throttling:
+      // Check if we already have a position on this symbol
+      const symbolPositions = activePositions.filter(
+        (pos) => pos.symbol === symbol
+      );
 
-```typescript
+      if (symbolPositions.length > 0) {
+        throw new Error(`Already have position on ${symbol}`);
+      }
+    },
+  ],
+});
+
+// Use risk profile in strategy
 addStrategy({
   strategyName: "my-strategy",
-  interval: "5m", // Signals generated max once per 5 minutes
+  interval: "5m",
+  riskName: "conservative", // Apply risk profile
   getSignal: async (symbol) => {
-    // This function will be called max once per 5 minutes
-    // Even if tick() is called every second
-    return signal;
+    // Signal generation logic
+    return { /* ... */ };
   },
 });
 ```
 
-Supported intervals: `"1m"`, `"3m"`, `"5m"`, `"15m"`, `"30m"`, `"1h"`
+### 9. Custom Persistence Adapters (Optional)
 
-## Markdown Reports
+By default, backtest-kit uses file-based persistence with atomic writes. You can replace this with custom adapters (e.g., Redis, MongoDB, PostgreSQL) for distributed systems or high-performance scenarios.
 
-Generate detailed trading reports with statistics:
+#### Understanding the Persistence System
 
-### Backtest Reports
-
-```typescript
-import { Backtest } from "backtest-kit";
-
-// Run backtest
-const stopBacktest = Backtest.background("BTCUSDT", {
-  strategyName: "my-strategy",
-  exchangeName: "binance",
-  frameName: "1d-backtest"
-});
+The library uses three persistence layers:
 
-// Get raw statistical data (Controller)
-const stats = await Backtest.getData("my-strategy");
-console.log(stats);
-// Returns:
-// {
-//   signalList: [...],           // All closed signals
-//   totalSignals: 10,
-//   winCount: 7,
-//   lossCount: 3,
-//   winRate: 70.0,               // Percentage (higher is better)
-//   avgPnl: 1.23,                // Average PNL % (higher is better)
-//   totalPnl: 12.30,             // Total PNL % (higher is better)
-//   stdDev: 2.45,                // Standard deviation (lower is better)
-//   sharpeRatio: 0.50,           // Risk-adjusted return (higher is better)
-//   annualizedSharpeRatio: 9.55, // Sharpe × √365 (higher is better)
-//   certaintyRatio: 1.75,        // avgWin / |avgLoss| (higher is better)
-//   expectedYearlyReturns: 156   // Estimated yearly trades (higher is better)
-// }
+1. **PersistBase** - Base class for all persistence operations (file-based by default)
+2. **PersistSignalAdapter** - Manages signal state persistence (used by Live mode)
+3. **PersistRiskAdapter** - Manages active positions for risk management
 
-// Generate markdown report (View)
-const markdown = await Backtest.getReport("my-strategy");
-console.log(markdown);
+#### Default File-Based Persistence
 
-// Save to disk (default: ./logs/backtest/my-strategy.md)
-await Backtest.dump("my-strategy");
+By default, data is stored in JSON files:
 
-// Save to custom path
-await Backtest.dump("my-strategy", "./custom/path");
+```
+./logs/data/
+  signal/
+    my-strategy/
+      BTCUSDT.json      # Signal state for BTCUSDT
+      ETHUSDT.json      # Signal state for ETHUSDT
+  risk/
+    conservative/
+      positions.json     # Active positions for risk profile
 ```
 
-**getData() returns BacktestStatistics:**
-- `signalList` - Array of all closed signals
-- `totalSignals` - Total number of closed signals
-- `winCount` / `lossCount` - Number of winning/losing trades
-- `winRate` - Win percentage (higher is better)
-- `avgPnl` - Average PNL percentage (higher is better)
-- `totalPnl` - Total PNL percentage (higher is better)
-- `stdDev` - Standard deviation / volatility (lower is better)
-- `sharpeRatio` - Risk-adjusted return (higher is better)
-- `annualizedSharpeRatio` - Sharpe Ratio × √365 (higher is better)
-- `certaintyRatio` - avgWin / |avgLoss| (higher is better)
-- `expectedYearlyReturns` - Estimated number of trades per year (higher is better)
-
-**getReport() includes:**
-- All metrics from getData() formatted as markdown
-- All signal details (prices, TP/SL, PNL, duration, close reason)
-- Timestamps for each signal
-- "Higher is better" / "Lower is better" annotations
-
-### Live Trading Reports
+#### Create Custom Adapter (Redis Example)
 
 ```typescript
-import { Live } from "backtest-kit";
+import { PersistBase, PersistSignalAdaper, PersistRiskAdapter } from "backtest-kit";
+import Redis from "ioredis";
 
-// Get raw statistical data (Controller)
-const stats = await Live.getData("my-strategy");
-console.log(stats);
-// Returns:
-// {
-//   eventList: [...],            // All events (idle, opened, active, closed)
-//   totalEvents: 15,
-//   totalClosed: 5,
-//   winCount: 3,
-//   lossCount: 2,
-//   winRate: 60.0,               // Percentage (higher is better)
-//   avgPnl: 1.23,                // Average PNL % (higher is better)
-//   totalPnl: 6.15,              // Total PNL % (higher is better)
-//   stdDev: 1.85,                // Standard deviation (lower is better)
-//   sharpeRatio: 0.66,           // Risk-adjusted return (higher is better)
-//   annualizedSharpeRatio: 12.61,// Sharpe × √365 (higher is better)
-//   certaintyRatio: 2.10,        // avgWin / |avgLoss| (higher is better)
-//   expectedYearlyReturns: 365   // Estimated yearly trades (higher is better)
-// }
+const redis = new Redis();
 
-// Generate markdown report (View)
-const markdown = await Live.getReport("my-strategy");
+// Custom Redis-based persistence adapter
+class RedisPersist extends PersistBase {
+  // Initialize Redis connection
+  async waitForInit(initial: boolean): Promise<void> {
+    // Redis connection is already established
+    console.log(`Redis persistence initialized for ${this.entityName}`);
+  }
 
-// Save to disk (default: ./logs/live/my-strategy.md)
-await Live.dump("my-strategy");
-```
+  // Read entity from Redis
+  async readValue<T>(entityId: string | number): Promise<T> {
+    const key = `${this.entityName}:${entityId}`;
+    const data = await redis.get(key);
 
-**getData() returns LiveStatistics:**
-- `eventList` - Array of all events (idle, opened, active, closed)
-- `totalEvents` - Total number of events
-- `totalClosed` - Total number of closed signals
-- `winCount` / `lossCount` - Number of winning/losing trades
-- `winRate` - Win percentage (higher is better)
-- `avgPnl` - Average PNL percentage (higher is better)
-- `totalPnl` - Total PNL percentage (higher is better)
-- `stdDev` - Standard deviation / volatility (lower is better)
-- `sharpeRatio` - Risk-adjusted return (higher is better)
-- `annualizedSharpeRatio` - Sharpe Ratio × √365 (higher is better)
-- `certaintyRatio` - avgWin / |avgLoss| (higher is better)
-- `expectedYearlyReturns` - Estimated number of trades per year (higher is better)
-
-**getReport() includes:**
-- All metrics from getData() formatted as markdown
-- Signal-by-signal details with current state
-- "Higher is better" / "Lower is better" annotations
-
-**Report example:**
-```markdown
-# Live Trading Report: my-strategy
-
-Total events: 15
-Closed signals: 5
-Win rate: 60.00% (3W / 2L) (higher is better)
-Average PNL: +1.23% (higher is better)
-Total PNL: +6.15% (higher is better)
-Standard Deviation: 1.85% (lower is better)
-Sharpe Ratio: 0.66 (higher is better)
-Annualized Sharpe Ratio: 12.61 (higher is better)
-Certainty Ratio: 2.10 (higher is better)
-Expected Yearly Returns: 365 trades (higher is better)
-
-| Timestamp | Action | Symbol | Signal ID | Position | ... | PNL (net) | Close Reason |
-|-----------|--------|--------|-----------|----------|-----|-----------|--------------|
-| ...       | CLOSED | BTCUSD | abc-123   | LONG     | ... | +2.45%    | take_profit  |
-```
+    if (!data) {
+      throw new Error(`Entity ${this.entityName}:${entityId} not found`);
+    }
 
-## Event Listeners
+    return JSON.parse(data) as T;
+  }
 
-Subscribe to signal events with filtering support. Useful for running strategies in background while reacting to specific events.
+  // Check if entity exists in Redis
+  async hasValue(entityId: string | number): Promise<boolean> {
+    const key = `${this.entityName}:${entityId}`;
+    const exists = await redis.exists(key);
+    return exists === 1;
+  }
 
-### Background Execution with Event Listeners
+  // Write entity to Redis
+  async writeValue<T>(entityId: string | number, entity: T): Promise<void> {
+    const key = `${this.entityName}:${entityId}`;
+    const serializedData = JSON.stringify(entity);
+    await redis.set(key, serializedData);
 
-```typescript
-import { Backtest, listenSignalBacktest } from "backtest-kit";
+    // Optional: Set TTL (time to live)
+    // await redis.expire(key, 86400); // 24 hours
+  }
 
-// Run backtest in background (doesn't yield results)
-Backtest.background("BTCUSDT", {
-  strategyName: "my-strategy",
-  exchangeName: "binance",
-  frameName: "1d-backtest"
-});
+  // Remove entity from Redis
+  async removeValue(entityId: string | number): Promise<void> {
+    const key = `${this.entityName}:${entityId}`;
+    const result = await redis.del(key);
 
-// Listen to all backtest events
-const unsubscribe = listenSignalBacktest((event) => {
-  if (event.action === "closed") {
-    console.log("Signal closed:", {
-      pnl: event.pnl.pnlPercentage,
-      reason: event.closeReason
-    });
+    if (result === 0) {
+      throw new Error(`Entity ${this.entityName}:${entityId} not found for deletion`);
+    }
   }
-});
 
-// Stop listening when done
-// unsubscribe();
-```
+  // Remove all entities for this entity type
+  async removeAll(): Promise<void> {
+    const pattern = `${this.entityName}:*`;
+    const keys = await redis.keys(pattern);
 
-### Listen Once with Filter
+    if (keys.length > 0) {
+      await redis.del(...keys);
+    }
+  }
 
-```typescript
-import { Backtest, listenSignalBacktestOnce } from "backtest-kit";
+  // Iterate over all entity values
+  async *values<T>(): AsyncGenerator<T> {
+    const pattern = `${this.entityName}:*`;
+    const keys = await redis.keys(pattern);
 
-// Run backtest in background
-Backtest.background("BTCUSDT", {
-  strategyName: "my-strategy",
-  exchangeName: "binance",
-  frameName: "1d-backtest"
-});
+    // Sort keys alphanumerically
+    keys.sort((a, b) => a.localeCompare(b, undefined, {
+      numeric: true,
+      sensitivity: "base"
+    }));
 
-// Wait for first take profit event
-listenSignalBacktestOnce(
-  (event) => event.action === "closed" && event.closeReason === "take_profit",
-  (event) => {
-    console.log("First take profit hit!", event.pnl.pnlPercentage);
-    // Automatically unsubscribes after first match
+    for (const key of keys) {
+      const data = await redis.get(key);
+      if (data) {
+        yield JSON.parse(data) as T;
+      }
+    }
   }
-);
-```
 
-### Live Trading with Event Listeners
+  // Iterate over all entity IDs
+  async *keys(): AsyncGenerator<string> {
+    const pattern = `${this.entityName}:*`;
+    const keys = await redis.keys(pattern);
 
-```typescript
-import { Live, listenSignalLive, listenSignalLiveOnce } from "backtest-kit";
-
-// Run live trading in background (infinite loop)
-const cancel = Live.background("BTCUSDT", {
-  strategyName: "my-strategy",
-  exchangeName: "binance"
-});
+    // Sort keys alphanumerically
+    keys.sort((a, b) => a.localeCompare(b, undefined, {
+      numeric: true,
+      sensitivity: "base"
+    }));
 
-// Listen to all live events
-listenSignalLive((event) => {
-  if (event.action === "opened") {
-    console.log("Signal opened:", event.signal.id);
-  }
-  if (event.action === "closed") {
-    console.log("Signal closed:", event.pnl.pnlPercentage);
+    for (const key of keys) {
+      // Extract entity ID from key (remove prefix)
+      const entityId = key.slice(this.entityName.length + 1);
+      yield entityId;
+    }
   }
-});
+}
 
-// React to first stop loss once
-listenSignalLiveOnce(
-  (event) => event.action === "closed" && event.closeReason === "stop_loss",
-  (event) => {
-    console.error("Stop loss hit!", event.pnl.pnlPercentage);
-    // Send alert, dump report, etc.
-  }
-);
+// Register Redis adapter for signal persistence
+PersistSignalAdaper.usePersistSignalAdapter(RedisPersist);
 
-// Stop live trading after some condition
-// cancel();
+// Register Redis adapter for risk persistence
+PersistRiskAdapter.usePersistRiskAdapter(RedisPersist);
 ```
 
-### Listen to All Signals (Backtest + Live)
+#### Custom Adapter Registration (Before Running Strategies)
 
 ```typescript
-import { listenSignal, listenSignalOnce, Backtest, Live } from "backtest-kit";
-
-// Listen to both backtest and live events
-listenSignal((event) => {
-  console.log("Event:", event.action, event.strategyName);
-});
-
-// Wait for first loss from any source
-listenSignalOnce(
-  (event) => event.action === "closed" && event.pnl.pnlPercentage < 0,
-  (event) => {
-    console.log("First loss detected:", event.pnl.pnlPercentage);
-  }
-);
+import { PersistSignalAdaper, PersistRiskAdapter, Live } from "backtest-kit";
 
-// Run both modes
-Backtest.background("BTCUSDT", {
-  strategyName: "my-strategy",
-  exchangeName: "binance",
-  frameName: "1d-backtest"
-});
+// IMPORTANT: Register adapters BEFORE running any strategies
+PersistSignalAdaper.usePersistSignalAdapter(RedisPersist);
+PersistRiskAdapter.usePersistRiskAdapter(RedisPersist);
 
+// Now run live trading with Redis persistence
 Live.background("BTCUSDT", {
   strategyName: "my-strategy",
   exchangeName: "binance"
 });
 ```
 
-**Available event listeners:**
+#### MongoDB Adapter Example
 
-- `listenSignal(callback)` - Subscribe to all signal events (backtest + live)
-- `listenSignalOnce(filter, callback)` - Subscribe once with filter predicate
-- `listenSignalBacktest(callback)` - Subscribe to backtest signals only
-- `listenSignalBacktestOnce(filter, callback)` - Subscribe to backtest signals once
-- `listenSignalLive(callback)` - Subscribe to live signals only
-- `listenSignalLiveOnce(filter, callback)` - Subscribe to live signals once
-- `listenError(callback)` - Subscribe to background execution errors
-- `listenDone(callback)` - Subscribe to background completion events
-- `listenDoneOnce(filter, callback)` - Subscribe to background completion once
+```typescript
+import { PersistBase } from "backtest-kit";
+import { MongoClient, Collection } from "mongodb";
 
-All listeners return an `unsubscribe` function. All callbacks are processed sequentially using queued async execution.
+const client = new MongoClient("mongodb://localhost:27017");
+const db = client.db("backtest-kit");
 
-### Listen to Background Completion
+class MongoPersist extends PersistBase {
+  private collection: Collection;
 
-```typescript
-import { listenDone, listenDoneOnce, Backtest, Live } from "backtest-kit";
-
-// Listen to all completion events
-listenDone((event) => {
-  console.log("Execution completed:", {
-    mode: event.backtest ? "backtest" : "live",
-    symbol: event.symbol,
-    strategy: event.strategyName,
-    exchange: event.exchangeName,
-  });
-
-  // Auto-generate report on completion
-  if (event.backtest) {
-    Backtest.dump(event.strategyName);
-  } else {
-    Live.dump(event.strategyName);
+  constructor(entityName: string, baseDir: string) {
+    super(entityName, baseDir);
+    this.collection = db.collection(this.entityName);
   }
-});
 
-// Wait for specific backtest to complete
-listenDoneOnce(
-  (event) => event.backtest && event.symbol === "BTCUSDT",
-  (event) => {
-    console.log("BTCUSDT backtest finished");
-    // Start next backtest or live trading
-    Live.background(event.symbol, {
-      strategyName: event.strategyName,
-      exchangeName: event.exchangeName,
-    });
+  async waitForInit(initial: boolean): Promise<void> {
+    await client.connect();
+    // Create index for faster lookups
+    await this.collection.createIndex({ entityId: 1 }, { unique: true });
+    console.log(`MongoDB persistence initialized for ${this.entityName}`);
   }
-);
 
-// Run backtests
-Backtest.background("BTCUSDT", {
-  strategyName: "my-strategy",
-  exchangeName: "binance",
-  frameName: "1d-backtest"
-});
-```
-
-## API Reference
-
-### High-Level Functions
+  async readValue<T>(entityId: string | number): Promise<T> {
+    const doc = await this.collection.findOne({ entityId });
 
-#### Schema Registration
+    if (!doc) {
+      throw new Error(`Entity ${this.entityName}:${entityId} not found`);
+    }
 
-```typescript
-// Register exchange
-addExchange(exchangeSchema: IExchangeSchema): void
+    return doc.data as T;
+  }
 
-// Register strategy
-addStrategy(strategySchema: IStrategySchema): void
+  async hasValue(entityId: string | number): Promise<boolean> {
+    const count = await this.collection.countDocuments({ entityId });
+    return count > 0;
+  }
 
-// Register timeframe generator
-addFrame(frameSchema: IFrameSchema): void
-```
+  async writeValue<T>(entityId: string | number, entity: T): Promise<void> {
+    await this.collection.updateOne(
+      { entityId },
+      { $set: { entityId, data: entity, updatedAt: new Date() } },
+      { upsert: true }
+    );
+  }
 
-#### Exchange Data
+  async removeValue(entityId: string | number): Promise<void> {
+    const result = await this.collection.deleteOne({ entityId });
 
-```typescript
-// Get historical candles
-const candles = await getCandles("BTCUSDT", "1h", 5);
-// Returns: [
-//   { timestamp: 1704067200000, open: 42150.5, high: 42380.2, low: 42100.0, close: 42250.8, volume: 125.43 },
-//   { timestamp: 1704070800000, open: 42250.8, high: 42500.0, low: 42200.0, close: 42450.3, volume: 98.76 },
-//   { timestamp: 1704074400000, open: 42450.3, high: 42600.0, low: 42400.0, close: 42580.5, volume: 110.22 },
-//   { timestamp: 1704078000000, open: 42580.5, high: 42700.0, low: 42550.0, close: 42650.0, volume: 95.18 },
-//   { timestamp: 1704081600000, open: 42650.0, high: 42750.0, low: 42600.0, close: 42720.0, volume: 102.35 }
-// ]
-
-// Get VWAP from last 5 1m candles
-const vwap = await getAveragePrice("BTCUSDT");
-// Returns: 42685.34
-
-// Get current date in execution context
-const date = await getDate();
-// Returns: 2024-01-01T12:00:00.000Z (in backtest mode, returns frame's current timestamp)
-// Returns: 2024-01-15T10:30:45.123Z (in live mode, returns current wall clock time)
-
-// Get current mode
-const mode = await getMode();
-// Returns: "backtest" or "live"
-
-// Format price/quantity for exchange
-const price = await formatPrice("BTCUSDT", 42685.3456789);
-// Returns: "42685.35" (formatted to exchange precision)
-
-const quantity = await formatQuantity("BTCUSDT", 0.123456789);
-// Returns: "0.12345" (formatted to exchange precision)
-```
+    if (result.deletedCount === 0) {
+      throw new Error(`Entity ${this.entityName}:${entityId} not found for deletion`);
+    }
+  }
 
-### Service APIs
+  async removeAll(): Promise<void> {
+    await this.collection.deleteMany({});
+  }
 
-#### Backtest API
+  async *values<T>(): AsyncGenerator<T> {
+    const cursor = this.collection.find({}).sort({ entityId: 1 });
 
-```typescript
-import { Backtest, BacktestStatistics } from "backtest-kit";
-
-// Stream backtest results
-Backtest.run(
-  symbol: string,
-  context: {
-    strategyName: string;
-    exchangeName: string;
-    frameName: string;
+    for await (const doc of cursor) {
+      yield doc.data as T;
+    }
   }
-): AsyncIterableIterator<IStrategyTickResultClosed>
 
-// Run in background without yielding results
-Backtest.background(
-  symbol: string,
-  context: { strategyName, exchangeName, frameName }
-): Promise<() => void> // Returns cancellation function
+  async *keys(): AsyncGenerator<string> {
+    const cursor = this.collection.find({}, { projection: { entityId: 1 } }).sort({ entityId: 1 });
 
-// Get raw statistical data (Controller)
-Backtest.getData(strategyName: string): Promise<BacktestStatistics>
-
-// Generate markdown report (View)
-Backtest.getReport(strategyName: string): Promise<string>
+    for await (const doc of cursor) {
+      yield String(doc.entityId);
+    }
+  }
+}
 
-// Save report to disk
-Backtest.dump(strategyName: string, path?: string): Promise<void>
+// Register MongoDB adapter
+PersistSignalAdaper.usePersistSignalAdapter(MongoPersist);
+PersistRiskAdapter.usePersistRiskAdapter(MongoPersist);
 ```
 
-#### Live Trading API
+#### Direct Persistence API Usage (Advanced)
 
-```typescript
-import { Live, LiveStatistics } from "backtest-kit";
-
-// Stream live results (infinite)
-Live.run(
-  symbol: string,
-  context: {
-    strategyName: string;
-    exchangeName: string;
-  }
-): AsyncIterableIterator<IStrategyTickResult>
+You can also use PersistBase directly for custom data storage:
 
-// Run in background without yielding results
-Live.background(
-  symbol: string,
-  context: { strategyName, exchangeName }
-): Promise<() => void> // Returns cancellation function
+```typescript
+import { PersistBase } from "backtest-kit";
 
-// Get raw statistical data (Controller)
-Live.getData(strategyName: string): Promise<LiveStatistics>
+// Create custom persistence for trading logs
+const tradingLogs = new PersistBase("trading-logs", "./logs/custom");
 
-// Generate markdown report (View)
-Live.getReport(strategyName: string): Promise<string>
+// Initialize
+await tradingLogs.waitForInit(true);
 
-// Save report to disk
-Live.dump(strategyName: string, path?: string): Promise<void>
-```
+// Write log entry
+await tradingLogs.writeValue("log-1", {
+  timestamp: Date.now(),
+  message: "Strategy started",
+  metadata: { symbol: "BTCUSDT", strategy: "sma-crossover" }
+});
 
-## Type Definitions
+// Read log entry
+const log = await tradingLogs.readValue("log-1");
+console.log(log);
 
-### Statistics Types
+// Check if log exists
+const exists = await tradingLogs.hasValue("log-1");
+console.log(`Log exists: ${exists}`);
 
-```typescript
-// Backtest statistics (exported from "backtest-kit")
-interface BacktestStatistics {
-  signalList: IStrategyTickResultClosed[];  // All closed signals
-  totalSignals: number;
-  winCount: number;
-  lossCount: number;
-  winRate: number | null;               // Win percentage (higher is better)
-  avgPnl: number | null;                // Average PNL % (higher is better)
-  totalPnl: number | null;              // Total PNL % (higher is better)
-  stdDev: number | null;                // Standard deviation (lower is better)
-  sharpeRatio: number | null;           // Risk-adjusted return (higher is better)
-  annualizedSharpeRatio: number | null; // Sharpe × √365 (higher is better)
-  certaintyRatio: number | null;        // avgWin / |avgLoss| (higher is better)
-  expectedYearlyReturns: number | null; // Estimated yearly trades (higher is better)
+// Iterate over all logs
+for await (const log of tradingLogs.values()) {
+  console.log("Log:", log);
 }
 
-// Live statistics (exported from "backtest-kit")
-interface LiveStatistics {
-  eventList: TickEvent[];               // All events (idle, opened, active, closed)
-  totalEvents: number;
-  totalClosed: number;
-  winCount: number;
-  lossCount: number;
-  winRate: number | null;               // Win percentage (higher is better)
-  avgPnl: number | null;                // Average PNL % (higher is better)
-  totalPnl: number | null;              // Total PNL % (higher is better)
-  stdDev: number | null;                // Standard deviation (lower is better)
-  sharpeRatio: number | null;           // Risk-adjusted return (higher is better)
-  annualizedSharpeRatio: number | null; // Sharpe × √365 (higher is better)
-  certaintyRatio: number | null;        // avgWin / |avgLoss| (higher is better)
-  expectedYearlyReturns: number | null; // Estimated yearly trades (higher is better)
+// Get all log IDs
+for await (const logId of tradingLogs.keys()) {
+  console.log("Log ID:", logId);
 }
-```
 
-### Signal Data
-
-```typescript
-interface ISignalRow {
-  id: string;                     // UUID v4 auto-generated
-  position: "long" | "short";
-  note?: string;
-  priceOpen: number;
-  priceTakeProfit: number;
-  priceStopLoss: number;
-  minuteEstimatedTime: number;
-  exchangeName: string;
-  strategyName: string;
-  timestamp: number;              // Signal creation timestamp
-  symbol: string;                 // Trading pair (e.g., "BTCUSDT")
+// Filter logs
+for await (const log of tradingLogs.filter((l: any) => l.metadata.symbol === "BTCUSDT")) {
+  console.log("BTC Log:", log);
 }
-```
 
-### Tick Results (Discriminated Union)
-
-```typescript
-type IStrategyTickResult =
-  | {
-      action: "idle";
-      signal: null;
-      strategyName: string;
-      exchangeName: string;
-      currentPrice: number;
-    }
-  | {
-      action: "opened";
-      signal: ISignalRow;
-      strategyName: string;
-      exchangeName: string;
-      currentPrice: number;
-    }
-  | {
-      action: "active";
-      signal: ISignalRow;
-      currentPrice: number;
-      strategyName: string;
-      exchangeName: string;
-    }
-  | {
-      action: "closed";
-      signal: ISignalRow;
-      currentPrice: number;
-      closeReason: "take_profit" | "stop_loss" | "time_expired";
-      closeTimestamp: number;
-      pnl: {
-        pnlPercentage: number;
-        priceOpen: number;        // Entry price adjusted with slippage and fees
-        priceClose: number;       // Exit price adjusted with slippage and fees
-      };
-      strategyName: string;
-      exchangeName: string;
-    };
-```
+// Take first 5 logs
+for await (const log of tradingLogs.take(5)) {
+  console.log("Recent Log:", log);
+}
 
-### PNL Calculation
+// Remove specific log
+await tradingLogs.removeValue("log-1");
 
-```typescript
-// Constants
-PERCENT_SLIPPAGE = 0.1% // 0.001
-PERCENT_FEE = 0.1%      // 0.001
-
-// LONG position
-priceOpenWithCosts = priceOpen * (1 + slippage + fee)
-priceCloseWithCosts = priceClose * (1 - slippage - fee)
-pnl% = (priceCloseWithCosts - priceOpenWithCosts) / priceOpenWithCosts * 100
-
-// SHORT position
-priceOpenWithCosts = priceOpen * (1 - slippage + fee)
-priceCloseWithCosts = priceClose * (1 + slippage + fee)
-pnl% = (priceOpenWithCosts - priceCloseWithCosts) / priceOpenWithCosts * 100
+// Remove all logs
+await tradingLogs.removeAll();
 ```
 
-## Production Readiness
+#### When to Use Custom Adapters
 
-### ✅ Production-Ready Features
+1. **Redis** - Best for high-performance distributed systems with multiple instances
+   - Fast read/write operations
+   - Built-in TTL (automatic cleanup)
+   - Pub/sub for real-time updates
 
-1. **Crash-Safe Persistence** - Atomic file writes with automatic recovery
-2. **Signal Validation** - Comprehensive validation prevents invalid trades
-3. **Type Safety** - Discriminated unions eliminate runtime type errors
-4. **Memory Efficiency** - Prototype methods + async generators + memoization
-5. **Interval Throttling** - Prevents signal spam
-6. **Live Trading Ready** - Full implementation with real-time progression
-7. **Error Recovery** - Stateless process with disk-based state
+2. **MongoDB** - Best for complex queries and analytics
+   - Rich query language
+   - Aggregation pipelines
+   - Scalable for large datasets
 
-## Advanced Examples
+3. **PostgreSQL** - Best for ACID transactions and relational data
+   - Strong consistency guarantees
+   - Complex joins and queries
+   - Mature ecosystem
 
-### Multi-Symbol Live Trading
-
-```typescript
-import { Live } from "backtest-kit";
-
-const symbols = ["BTCUSDT", "ETHUSDT", "SOLUSDT"];
-
-// Run all symbols in parallel
-await Promise.all(
-  symbols.map(async (symbol) => {
-    for await (const result of Live.run(symbol, {
-      strategyName: "my-strategy",
-      exchangeName: "binance"
-    })) {
-      console.log(`[${symbol}]`, result.action);
-
-      // Generate reports periodically
-      if (result.action === "closed") {
-        await Live.dump("my-strategy");
-      }
-    }
-  })
-);
-```
+4. **File-based (default)** - Best for single-instance deployments
+   - No dependencies
+   - Simple debugging (inspect JSON files)
+   - Sufficient for most use cases
 
-### Backtest Progress Listener
+#### Testing Custom Adapters
 
 ```typescript
-import { listenProgress, Backtest } from "backtest-kit";
-
-listenProgress((event) => {
-  console.log(`Progress: ${(event.progress * 100).toFixed(2)}%`);
-  console.log(`${event.processedFrames} / ${event.totalFrames} frames`);
-  console.log(`Strategy: ${event.strategyName}, Symbol: ${event.symbol}`);
-});
-
-Backtest.background("BTCUSDT", {
-  strategyName: "my-strategy",
-  exchangeName: "binance",
-  frameName: "1d-backtest"
-});
-```
+import { test } from "worker-testbed";
+import { PersistBase } from "backtest-kit";
 
-### Early Termination
+test("Custom Redis adapter works correctly", async ({ pass, fail }) => {
+  const persist = new RedisPersist("test-entity", "./logs/test");
 
-**Using async generator with break:**
+  await persist.waitForInit(true);
 
-```typescript
-import { Backtest } from "backtest-kit";
-
-for await (const result of Backtest.run("BTCUSDT", {
-  strategyName: "my-strategy",
-  exchangeName: "binance",
-  frameName: "1d-backtest"
-})) {
-  if (result.closeReason === "stop_loss") {
-    console.log("Stop loss hit - terminating backtest");
+  // Write
+  await persist.writeValue("key1", { data: "value1" });
 
-    // Save final report before exit
-    await Backtest.dump("my-strategy");
-    break; // Generator stops immediately
+  // Read
+  const value = await persist.readValue("key1");
+  if (value.data === "value1") {
+    pass("Redis adapter read/write works");
+  } else {
+    fail("Redis adapter failed");
   }
-}
-```
-
-**Using background mode with stop() function:**
 
-```typescript
-import { Backtest, Live, listenSignalLiveOnce } from "backtest-kit";
-
-// Backtest.background returns a stop function
-const stopBacktest = await Backtest.background("BTCUSDT", {
-  strategyName: "my-strategy",
-  exchangeName: "binance",
-  frameName: "1d-backtest"
-});
-
-// Stop backtest after some condition
-setTimeout(() => {
-  console.log("Stopping backtest...");
-  stopBacktest(); // Stops the background execution
-}, 5000);
-
-// Live.background also returns a stop function
-const stopLive = Live.background("BTCUSDT", {
-  strategyName: "my-strategy",
-  exchangeName: "binance"
+  // Cleanup
+  await persist.removeValue("key1");
 });
-
-// Stop live trading after detecting stop loss
-listenSignalLiveOnce(
-  (event) => event.action === "closed" && event.closeReason === "stop_loss",
-  (event) => {
-    console.log("Stop loss detected - stopping live trading");
-    stopLive(); // Stops the infinite loop
-  }
-);
 ```
 
-## Use Cases
+---
+
+## ✅ Tested & Reliable
 
-- **Algorithmic Trading** - Backtest and deploy strategies with crash recovery
-- **Strategy Research** - Test hypotheses on historical data
-- **Signal Generation** - Use with ML models or technical indicators
-- **Portfolio Management** - Track multiple strategies across symbols
-- **Educational Projects** - Learn trading system architecture
+`backtest-kit` comes with a robust test suite covering:
+- 🛡️ **Validation**: Ensures all components (exchanges, strategies, frames, risk profiles) are properly configured. ✅
+- 🚑 **Recovery**: Handles edge cases like invalid signals or empty outputs. 🛠️
+- 🔄 **Navigation**: Smoothly switches between backtest and live modes without errors. 🌐
+- ⚡ **Performance**: Efficient memory usage and history management. 📈
 
-## Contributing
+**109 unit and integration tests** covering:
+- Signal validation and throttling
+- PNL calculation with fees and slippage
+- Crash recovery and state persistence
+- Callback execution order
+- Markdown report generation
+- Walker strategy comparison
+- Heatmap portfolio analysis
+- Position sizing calculations
+- Risk management validation
+- Event system
 
-Pull requests are welcome. For major changes, please open an issue first.
+---
 
-## License
+## 🤝 Contribute
 
-MIT
+We'd love your input! Fork the repo, submit a PR, or open an issue on **[GitHub](https://github.com/tripolskypetr/backtest-kit)**. 🙌
 
-## Links
+## 📜 License
 
-- [Architecture Documentation](./ARCHITECTURE.md)
-- [TypeScript Documentation](https://www.typescriptlang.org/)
-- [Dependency Injection](https://github.com/tripolskypetr/di-kit)
+MIT © [tripolskypetr](https://github.com/tripolskypetr) 🖋️