Metadata-Version: 2.4
Name: trading-backtest
Version: 0.1.0
Summary: Multi-market backtesting engine with data loaders, signal engines, and portfolio analytics
Author: Easy Trading
License: MIT
Project-URL: Homepage, https://github.com/haibingzhao/trading-backtest
Project-URL: Repository, https://github.com/haibingzhao/trading-backtest
Project-URL: Issues, https://github.com/haibingzhao/trading-backtest/issues
Project-URL: Changelog, https://github.com/haibingzhao/trading-backtest/blob/main/CHANGELOG.md
Project-URL: Upstream, https://github.com/HKUDS/Vibe-Trading
Keywords: backtest,trading,quantitative,finance,portfolio
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: jinja2>=3.0.0
Requires-Dist: defusedxml>=0.7.0
Requires-Dist: pyyaml>=6.0.0
Provides-Extra: a-share
Requires-Dist: tushare>=1.2.89; extra == "a-share"
Requires-Dist: akshare>=1.12.0; extra == "a-share"
Requires-Dist: baostock>=0.8.8; extra == "a-share"
Requires-Dist: mootdx>=0.4.0; extra == "a-share"
Provides-Extra: global-equity
Requires-Dist: yfinance>=0.2.30; extra == "global-equity"
Provides-Extra: crypto
Requires-Dist: ccxt>=4.0.0; extra == "crypto"
Provides-Extra: futu
Requires-Dist: futu-api>=6.0.0; extra == "futu"
Provides-Extra: cli
Requires-Dist: rich>=13.0.0; extra == "cli"
Provides-Extra: all
Requires-Dist: trading-backtest[a-share,cli,crypto,futu,global-equity]; extra == "all"
Dynamic: license-file

# trading-backtest

[中文文档](README_zh.md)

A multi-market backtesting engine supporting stocks, futures, forex, cryptocurrencies, and options across 7 market types.

## Features

- **Multi-market**: A-share, US/HK equity, China futures, global futures, forex, crypto, options
- **15+ data sources**: tushare, yfinance, akshare, ccxt, futu, and more — with automatic fallback
- **Flexible strategy interface**: Implement `SignalEngine.generate()` to plug in any custom strategy
- **Built-in strategy framework**: Regime detection, grid/trend sub-strategies, risk management
- **Portfolio optimizers**: Mean-variance, risk parity, max diversification, equal volatility
- **Statistical validation**: Monte Carlo simulation, Walk-Forward analysis, Time Series CV
- **Auto report generation**: HTML report with equity curve, trade log, and performance metrics

## Installation

```bash
# Core install
pip install trading-backtest

# With specific data source dependencies
pip install "trading-backtest[a-share]"       # China A-share (tushare, akshare, baostock)
pip install "trading-backtest[global-equity]" # US/HK equity (yfinance)
pip install "trading-backtest[crypto]"        # Crypto (ccxt)
pip install "trading-backtest[futu]"          # Futu API
pip install "trading-backtest[all]"           # All dependencies
```

## Quick Start

### 1. Create a run directory

```bash
mkdir -p runs/my_strategy/code
```

### 2. Write config (`runs/my_strategy/config.json`)

```json
{
  "codes": ["AAPL", "MSFT"],
  "start_date": "2023-01-01",
  "end_date": "2024-01-01",
  "source": "auto",
  "interval": "1D",
  "engine": "daily",
  "initial_cash": 1000000,
  "signal_params": {
    "ema_fast": 12,
    "ema_slow": 26
  }
}
```

### 3. Implement signal engine (`runs/my_strategy/code/signal_engine.py`)

```python
import pandas as pd

class SignalEngine:
    def __init__(self, ema_fast=12, ema_slow=26, **kwargs):
        self.ema_fast = ema_fast
        self.ema_slow = ema_slow

    def generate(self, data_map: dict[str, pd.DataFrame]) -> dict[str, pd.Series]:
        """
        Input:  data_map = {"AAPL": DataFrame, "MSFT": DataFrame}
                Each DataFrame has OHLCV columns with DatetimeIndex.
        Output: signal_map = {"AAPL": Series, "MSFT": Series}
                Signal values: +1 (long), -1 (short), 0 (flat)
        """
        signals = {}
        for code, df in data_map.items():
            fast = df["close"].ewm(span=self.ema_fast).mean()
            slow = df["close"].ewm(span=self.ema_slow).mean()
            signal = (fast > slow).astype(int) * 2 - 1
            signals[code] = signal
        return signals
```

### 4. Run backtest

```bash
python -m backtest.runner runs/my_strategy
```

### 5. View results

Output in `runs/my_strategy/artifacts/`:
- `report.html` — Visual HTML report
- `equity.csv` — Equity curve
- `trades.csv` — Trade log
- `metrics.csv` — Performance metrics

## Using the Built-in Strategy Framework

For a batteries-included approach, use the built-in strategy with one line:

```python
# runs/my_strategy/code/signal_engine.py
from backtest.strategy import DefaultSignalEngine as SignalEngine
```

Configure via `signal_params` in `config.json`:

```json
{
  "signal_params": {
    "allow_short": true,
    "risk_per_trade": 0.05,
    "trend_strength_threshold": 22,
    "max_drawdown_halt": 0.10
  }
}
```

## Configuration Reference

| Field | Required | Description |
|-------|----------|-------------|
| `codes` | ✅ | List of instrument codes |
| `start_date` | ✅ | Start date (YYYY-MM-DD) |
| `end_date` | ✅ | End date (YYYY-MM-DD) |
| `source` | ❌ | Data source, default `auto` |
| `interval` | ❌ | Bar interval: `1m/5m/15m/30m/1H/4H/1D` |
| `engine` | ❌ | Engine type: `daily/options` |
| `initial_cash` | ❌ | Starting capital (default: 1000000) |
| `signal_params` | ❌ | Parameters passed to SignalEngine |
| `benchmark` | ❌ | Benchmark symbol (e.g. `SPY`) |

### Symbol Format

| Market | Examples |
|--------|----------|
| A-share | `000001.SZ`, `600519.SH` |
| US equity | `AAPL`, `MSFT` |
| HK equity | `00700.HK`, `09988.HK` |
| Futures | `IF2312`, `CU2401` |
| Crypto | `BTC-USDT`, `ETH-USDT` |
| Forex | `USD/CNY`, `EUR/USD` |

## Engine Architecture

```
BaseEngine (base.py)
├── ChinaAEngine          # A-share (T+1, price limits)
├── GlobalEquityEngine    # US/HK equity (T+0)
├── CryptoEngine          # Crypto (24/7)
├── ChinaFuturesEngine    # China futures
├── GlobalFuturesEngine   # Global futures
├── ForexEngine           # Forex
├── CompositeEngine       # Cross-market portfolio
└── OptionsPortfolioEngine # Options portfolio
```

## Environment Variables

Copy `.env.example` to `.env` and configure your API keys:

```bash
cp .env.example .env
```

Key variables:
- `TUSHARE_TOKEN` — Tushare API token (A-share data)
- `TIINGO_API_KEY` — Tiingo API key (US equity)
- `TRADING_BACKTEST_DATA_CACHE=1` — Enable local Parquet cache

See `.env.example` for the full list.

## Development

```bash
# Setup
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[all]"
pip install pytest ruff mypy

# Test
pytest tests/ -v

# Lint
ruff check backtest/

# Type check
mypy backtest/
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for full development guidelines.

## Project Structure

```
trading-backtest/
├── backtest/
│   ├── engines/          # Market-specific engines
│   ├── loaders/          # Data source adapters
│   ├── optimizers/       # Portfolio optimizers
│   ├── strategy/         # Built-in strategy framework
│   ├── templates/        # Report & strategy templates
│   ├── runner.py         # CLI entry point
│   ├── metrics.py        # Performance metrics
│   └── models.py         # Data models
├── examples/             # Example strategies
├── tests/                # Unit tests
├── .github/workflows/    # CI/CD
└── pyproject.toml        # Project config
```

## Acknowledgements

This project is forked from [HKUDS/Vibe-Trading](https://github.com/HKUDS/Vibe-Trading). We thank the original authors for their excellent work.

## License

[MIT](LICENSE)
