Metadata-Version: 2.4
Name: chidoribt
Version: 0.2.3
Summary: Multi-asset unified portfolio backtesting framework
License: MIT
Project-URL: Repository, https://github.com/MioQuant/chidoribt
Project-URL: Bug Tracker, https://github.com/MioQuant/chidoribt/issues
Keywords: backtesting,finance,trading,portfolio,quantitative
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23.0
Requires-Dist: pandas>=1.5.0
Provides-Extra: numba
Requires-Dist: numba>=0.56; extra == "numba"
Provides-Extra: tsdb
Requires-Dist: mini-tsdb>=0.1.0; extra == "tsdb"
Provides-Extra: postgres
Requires-Dist: psycopg2-binary>=2.9; extra == "postgres"
Provides-Extra: full
Requires-Dist: numba>=0.56; extra == "full"
Requires-Dist: mini-tsdb>=0.1.0; extra == "full"
Requires-Dist: psycopg2-binary>=2.9; extra == "full"
Dynamic: license-file

# ChidoriBT ⚡

**超高速多資產回測框架 / High-Performance Multi-Asset Backtesting Framework**

<p align="center">
  <img src="https://tse2.mm.bing.net/th/id/OIP.tzQLNs50GB5WLS5qufp1gAAAAA?cb=thfc1falcon&rs=1&pid=ImgDetMain&o=7&rm=3" alt="Chidori — 千鳥" width="200"/>
</p>

---

## 專案名稱由來

> **千鳥（Chidori）** — 精準、迅速，如閃電貫穿黑暗。

「千鳥」是忍術中以**極致速度**與**精準集中**著稱的雷遁之術，一擊命中要害，毫無遲滯。
ChidoriBT 的設計哲學正是如此：

- **快**：Numba JIT 編譯達接近機器碼速度，比基於 `backtesting.py` 改寫的多資產 Broker（multibacktesting）快 **265 ～ 883 倍**
- **準**：JIT 與純 Python 事件驅動路徑的最終資產差距 **< 0.03%**，計算一致有保障

---

## 效能基準（Benchmark）

> 測試規模：**100 支台股 × 726 個交易日**（2023–2025）  
> 策略：子母線型態（ChildParentStrategy）+ 止損 10% / 止盈 20%  
> 執行：`python run_speed_benchmark.py --stocks 100 --stop-loss 0.1 --take-profit 0.2`

| 路徑 | 引擎 | 均值 | 相對基準加速比 |
|------|------|:----:|:--------------:|
| **A** PatternBacktester 純 Python | ChidoriBT | 33 ms | **883×** |
| **B** Numba 固定倉位 kernel | ChidoriBT | 55 ms | 531× |
| **C** Python 等權矩陣 + Numba rebalance | ChidoriBT | 68 ms | 431× |
| **D** NumPy 等權矩陣 + Numba rebalance | ChidoriBT | 70 ms | 418× |
| **G** ChidoriBT JIT（fast=True） | ChidoriBT | 110 ms | 265× |
| **H** ChidoriBT 事件驅動（fast=False） | ChidoriBT | 104 ms | 281× |
| Baseline（ChildParentStrategy 全量） | ChidoriBT | 109 ms | 267× |
| **E** 基準：多資產 Broker 事件驅動 ¹ | multibacktesting（改自 backtesting.py） | **29 s** | 1×（基準）|

> ¹ **基準說明（Path E）**：基準引擎為作者基於原版 [`backtesting.py`](https://github.com/kernc/backtesting.py)
> **改寫的多資產版本**（multibacktesting），以 panel DataFrame 一次傳入所有股票，透過其 Broker 事件驅動架構執行回測。
> 雖然已擴充為多資產，但原版逐 bar 事件迴圈的設計使其在大量資產時效能受限，正是 ChidoriBT 的優化起點。

**結論**：ChidoriBT 原生多資產支援，最快路徑（A）比 multibacktesting Broker 快 **883 倍**；  
即便是功能最完整的 Python 事件驅動路徑（H），也快 **281 倍**。

---

ChidoriBT is a high-performance Python backtesting library for multi-asset portfolio strategies. It supports vectorized (NumPy/Numba) execution, flexible data ingestion (DataFrame, PostgreSQL, Mini-TSDB), and produces detailed trade/equity analytics.

---

## Installation

**Core（DataFrame 傳入，無額外依賴）：**

```bash
pip install chidoribt
```

**含 Numba JIT 加速（建議）：**

```bash
pip install "chidoribt[numba]"
```

**含 PostgreSQL 資料載入：**

```bash
pip install "chidoribt[postgres]"
```

**含 Mini-TSDB 時序資料庫：**

```bash
pip install "chidoribt[tsdb]"
```

**全功能安裝：**

```bash
pip install "chidoribt[full]"
```

---

## 快速開始

### 方式一：直接傳入 DataFrame（OHLCV 格式，與原版 backtesting.py 欄位相容）

```python
import pandas as pd
from chidoribt import ChidoriBT
from chidoribt.strategies.base import MultiAssetStrategy

# 單資產 OHLCV DataFrame（欄位：Open, High, Low, Close, Volume）
ohlcv_df = pd.read_csv("AAPL.csv", index_col="date", parse_dates=True)

bt = ChidoriBT(data=ohlcv_df, cash=100_000, commission=0.001)
result = bt.run()

print(result["metrics"])
# {'total_return': 0.42, 'sharpe': 1.35, 'max_drawdown': -0.18, ...}
```

### 方式二：多資產 stacked DataFrame

```python
from chidoribt import ChidoriBT
from chidoribt.core import PanelData

# stacked DataFrame 欄位：stock_id, date, Open, High, Low, Close, Volume
panel = PanelData.from_dataframe(stacked_df)

bt = ChidoriBT(data=panel, strategy=MyStrategy, cash=100_000)
result = bt.run()
equity_curve = result["equity_curve"]   # pd.Series，index 為日期
trades_df    = result["trades"]         # pd.DataFrame，每筆交易記錄
```

### 方式三：Mini-TSDB 載入（需 `pip install "chidoribt[tsdb]"`）

> 首次使用需執行 `migrate_pg_to_tsdb.py` 將 PostgreSQL 資料遷移至 Mini-TSDB。

```python
from chidoribt.data import StockTSDBLoader
from chidoribt import ChidoriBT
from chidoribt.core import PanelData

loader = StockTSDBLoader("./data/tsdb")
raw_df = loader.load(start_date="2023-01-01", end_date="2025-12-31")

bt = ChidoriBT(
    data=PanelData.from_dataframe(raw_df),
    strategy=MyStrategy,
    cash=100_000,
)
result = bt.run()
```

### 方式四：PostgreSQL 載入（需 `pip install "chidoribt[postgres]"`）

```python
from chidoribt.data import StockPostgresLoader
from chidoribt import ChidoriBT
from chidoribt.core import PanelData

loader = StockPostgresLoader()  # 讀取環境變數 DB_HOST / DB_PORT / DB_NAME
raw_df = loader.load(start_date="2023-01-01", end_date="2025-12-31")

bt = ChidoriBT(
    data=PanelData.from_dataframe(raw_df),
    strategy=MyStrategy,
    cash=100_000,
)
result = bt.run()
```

---

## 自訂策略

```python
from chidoribt.strategies.base import MultiAssetStrategy

class MyStrategy(MultiAssetStrategy):
    def init(self):
        # 初始化指標
        pass

    def next(self, i: int, data):
        # 每個時間步執行
        for asset in self.assets:
            close = data.Close[asset][i]
            ma20  = data.MA_20[asset][i]
            if close > ma20:
                self.buy(asset, size=100)
            elif close < ma20:
                self.sell(asset, size=100)
```

---

## 執行模式

| 模式 | `mode` 參數 | 說明 |
|---|---|---|
| 統一資金池（預設） | `"portfolio"` | 所有資產共享資金，主打模式 |
| 等權再平衡 | `"rebalance"` | 每日依等權分配再平衡 |

```python
# Numba JIT 加速（預設 fast=True）
result = bt.run(mode="portfolio", fast=True)

# 純 Python 路徑（含完整 audit log）
result = bt.run(mode="portfolio", fast=False)
fills_df  = result["fills"]   # 每筆成交記錄
orders_df = result["orders"]  # 每筆下單記錄
```

---

## 回傳結果欄位

```python
result = bt.run()

result["equity_curve"]  # pd.Series — 每日資金曲線
result["trades"]        # pd.DataFrame — 每筆已平倉交易
result["fills"]         # pd.DataFrame — 每筆成交（fast=False 時）
result["metrics"]       # dict — 績效指標
```

**`metrics` 常用欄位：**

| 欄位 | 說明 |
|---|---|
| `total_return` | 總報酬率 |
| `sharpe` | 年化 Sharpe ratio |
| `max_drawdown` | 最大回撤 |
| `win_rate` | 勝率 |
| `n_trades` | 總交易筆數 |

---

## Mini-TSDB 資料遷移

若已有 PostgreSQL 歷史資料，可使用遷移腳本一次性搬移：

```bash
# 初次遷移
python migrate_pg_to_tsdb.py --tsdb-dir ./data/tsdb

# 清除舊資料後重新遷移（timestamp 格式不正確時使用）
python migrate_pg_to_tsdb.py --tsdb-dir ./data/tsdb --clean

# 查看 TSDB 內容
python migrate_pg_to_tsdb.py --tsdb-dir ./data/tsdb --list
```

---

## 套件架構

```
chidoribt/
├── __init__.py          # ChidoriBT, PanelData（公開 API）
├── engine.py            # 主引擎
├── core/                # PanelData, UnifiedPortfolio, Allocators
├── strategies/          # MultiAssetStrategy base + 範例策略
├── analytics/           # 績效指標計算
├── data/                # 資料載入子套件
│   ├── __init__.py      # lazy import + 友善錯誤訊息
│   ├── _postgres.py     # StockPostgresLoader（psycopg2，optional）
│   └── _tsdb.py         # StockTSDBLoader（mini-tsdb，optional）
├── adapters/            # 內部 adapter 層
├── utils/               # trade_logger 等工具
└── vectorized/          # 向量化指標
```

---

