Metadata-Version: 2.4
Name: chidoribt
Version: 0.1.0
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
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"

# ChidoriBT

**Multi-asset unified portfolio backtesting framework**

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（與 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/          # 向量化指標
```

---

## License

MIT
