QuantResearch

Personal Quant Research Workbench for Claude Code

English | 中文

---

QuantResearch is a local quantitative research workbench built around qlib (data & factors), vectorbt (backtesting engine), and a clean CLI. It is designed to be used with Claude Code — open the project, tell Claude what you want to research, and Claude executes the commands.

What it does

• Maintain local market data for CN/US/HK indices, ETFs, and stocks
• Run technical strategy backtests (KDJ, Bollinger, MACD, RSI, MA Cross, DCA)
• Cross-sectional factor analysis (IC, RankIC, quantile returns, long-short)
• Factor combination (equal-weight or ICIR-weighted)
• Factor-based portfolio backtesting (stock selection simulation)
• Generate Chinese decision reports and signal snapshots
• All results saved as Markdown + JSON

What it does NOT do

• No frontend UI
• No automated trading
• No broker APIs
• No "heavy platform" ambitions

Quick Start

# Prerequisites: Python 3.12+
pip install -r requirements.txt

# Initialize
python main.py init-db

# Register sample instruments
python main.py seed-instruments --csv-path data/instruments.sample.csv

# Build data for CSI 300 index
python main.py ensure-history --symbol 000300 --market CN --asset-type INDEX

# Build qlib dataset
python main.py refresh-qlib

# Run a strategy backtest
python main.py strategy-backtest --strategy kdj --symbol 000300 --market CN --asset-type INDEX --start 2024-01-01 --end 2026-04-30

# Analyze a factor
python main.py factor-analyze --factor-name "20d Vol" --expression "Std(\$close,20)/\$close"

# See all commands
python main.py --help

Setup Expectations

• Recommended environment: Python 3.12+ in your own virtual environment or conda environment
• Install dependencies: pip install -r requirements.txt
• dump_bin.py (qlib's CSV-to-bin converter) is vendored at vendor/qlib/scripts/dump_bin.py — no need to clone the qlib repo separately. Dependencies are fire, tqdm, loguru, and qlib.utils, all covered by requirements.txt
• data/instruments.sample.csv is only a starter sample; real research needs your own local universe and history

Smart qlib Dataset Refresh

The refresh_qlib() function automatically detects whether the qlib .bin dataset needs rebuilding:

• Data already current → skips rebuild entirely (< 0.1s)
• Data exists but has gaps → incremental update (append-only, via dump_update)
• No data yet → full build (via dump_all)
• Use --force-refresh-qlib on analysis commands to force a full rebuild
• Use --skip-auto-refresh-qlib to skip data preparation and use existing data as-is
• refresh-qlib defaults to full rebuild; use --incremental for skip-or-update mode

Using with Claude Code

1. Open this project in Claude Code
2. Say: "Build data for CSI 300 constituents" — Claude runs the data pipeline
3. Say: "Analyze the 20-day volatility factor" — Claude runs factor analysis
4. Say: "Compare KDJ vs MACD on Hikvision" — Claude runs strategy comparison

Claude reads CLAUDE.md to understand available commands and workflows.

Architecture

Data Sources (akshare / yfinance / mootdx)
        ↓
    SQLite (market_data.sqlite3)
        ↓
  CSV / Parquet export
        ↓
   qlib .bin dataset
        ↓
   ┌─ Technical strategy backtest (pandas / vectorbt)
   ├─ Factor analysis (IC / RankIC / quantile)
   ├─ Factor combination (equal / ICIR weighted)
   └─ Factor portfolio backtest
        ↓
   Reports (Markdown + JSON)

License

MIT