QuantGPT

<div align="center"> # Tool List **Agent-Driven Factor Research Engine — Autonomous Mining, Independent Validation on [QuantGPT Cloud](https://quant-gpt.com)** LLM Agent Autonomous Factor Mining → Batch Backtest → Multi-Dimensional Scoring → Anti-Overfitting Verification → [QuantGPT Cloud](https://quant-gpt.com) Independent Verification + Out-of-Sample Tracking | Zero Human Intervention Throughout [](https://github.com/Miasyster/quantgpt/actions/workflows/ci.yml) [](https://python.org) [](https://fastapi.tiangolo.com) [](https://react.dev) [](LICENSE) [Quick Start](docs/QUICKSTART.md) · [Architecture](docs/ARCHITECTURE.md) · [API Docs](docs/API_DOC.md) · [MCP Guide](docs/MCP_GUIDE.md) · [Factor Mining](docs/FACTOR_MINING.md) · [Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md) **WeChat / 微信交流群**: Add `quantgpt_ai` on WeChat to join the community <a href="https://star-history.com/#Miasyster/QuantGPT&Date"> <img src="docs/images/star-history.png" width="600" alt="Star History Chart" /> </a> </div> --- ## What Is QuantGPT QuantGPT is an **agent-driven factor research engine** — not a backtest library, not a chatbot wrapper. It gives an LLM Agent (Claude, via MCP) a complete toolkit to autonomously discover, evaluate, iterate, and validate alpha factors, with zero human intervention per research cycle. Factors that pass local validation are automatically uploaded to [**QuantGPT Cloud**](https://quant-gpt.com) for independent verification and out-of-sample tracking — ensuring research results are reproducible and auditable. The core architecture: ``` LLM Agent (Claude Code / Claude Desktop) │ ├── MCP Tools (15 个) ← Agent 的工具箱 │ ├── run_backtest ← 全市场分组回测 │ ├── score_factor ← 0-100 综合评分 │ ├── diagnose_factor ← 失败模式诊断 │ ├── run_anti_overfit ← 4 项反过拟合检验 │ ├── run_rolling_validation ← Walk-forward 验证 │ ├── validate_expression ← 语法校验 │ ├── list_operators ← 60+ 算子文档 │ ├── list_universes ← 股票池和基准 │ ├── wq_brain_submit ← WQ BRAIN 单因子提交 │ ├── wq_brain_batch_submit ← 批量参数扫描提交 │ ├── wq_brain_submit_by_ids ← 按 ID 提交 │ ├── wq_brain_list_alphas ← 查询已提交 alpha │ ├── wq_brain_check_alphas ← 检查 alpha 状态 │ └── wq_brain_finalize_submissions ← 最终提交确认 │ ├── QuantGPT Cloud ← 独立验证平台 (quant-gpt.com) │ ├── A 级因子自动上传 │ ├── 独立 IC/IR/Turnover 验证 │ ├── 样本外实时跟踪 │ ├── 因子去重（Self-Correlation 检测） │ └── 公开可审计的研究记录 │ ├── Evolution Engine ← 因子进化引擎 │ ├── MutationEngine (8 方向突变) │ ├── CrossoverEngine (高分因子交叉) │ ├── MetaEvolutionSelector (自适应策略) │ └── TrajectoryAnalyzer (轨迹分析) │ ├── WQ BRAIN Integration ← WorldQuant 直连（可选） │ ├── Dollar-neutral 模拟 │ └── 一键正式提交 │ └── Knowledge Base ← 跨会话知识积累 ├── rules/ (已验证规则) ├── findings/ (经验发现) └── failures/ (已证伪路径) ``` ### How It Differs from "AI Backtest Tools" Traditional tools (including ChatGPT + backtest library) follow the pattern: **humans think of factors → tools run backtests → humans review results**. The agent is the executor, and humans are the decision-makers. QuantGPT's pattern is: **humans define goals → agent autonomously researches → humans review outputs**. The agent is the researcher, and humans are the reviewers. This is not a difference in interface (natural language vs. code), but a difference in **decision-making power**. The agent autonomously decides: which direction to explore, what expressions to generate, which indicators to evaluate, when to iterate, when to abandon, and when to submit. ### Production Track Record | Metric | Value | |:-------|:------| | Cumulative Backtest Tasks | **370+** | | Single Iteration (8 Candidate Factors) | **~15 minutes** | | Expression Operators | **60+ (including nonlinear, ternary, and technical indicators)** | | Cloud Independent Verification | **A-level factors automatically uploaded to [quant-gpt.com](https://quant-gpt.com) for verification + out-of-sample tracking** | | WQ BRAIN Submission (optional) | **3 factors IS all PASS, submitted (best Fitness 1.26)** | --- ## Validated Results QuantGPT-produced factors undergo two layers of verification: local multi-dimensional scoring + [QuantGPT Cloud](https://quant-gpt.com) independent IC/IR verification. High-quality factors can also be submitted to WQ BRAIN. The following three factors have passed WQ BRAIN IS detection and been formally submitted: | Factor | Expression | WQ Sharpe | WQ Fitness | WQ Returns | IS Tests | Status | |:-------|:-----------|:---------:|:----------:|:----------:|:--------:|:------:| | **Debt-Momentum Composite** | `-1 * rank(ts_av_diff(close, 10)) + rank(debt / enterprise_value)` | **1.77** | **1.26** | **20.18%** | **ALL PASS** | **Submitted** | | **VWAP Decay Reversal** | `-1 * rank(ts_decay_linear(close / vwap, 10))` | **1.69** | **1.07** | **18.63%** | **ALL PASS** | **Submitted** | | **Returns-Volume Momentum** | `-1 * rank(ts_decay_linear(returns * volume / adv20, 5))` | **1.60** | **1.03** | **24.15%** | **ALL PASS** | **Submitted** | > The three factors represent different alpha sources: **Debt-Momentum** combines momentum reversal with fundamentals (debt/enterprise value), industry-neutralized; **VWAP Decay Reversal** captures price deviation from VWAP decay regression, market-neutralized; **Returns-Volume Momentum** captures yield and relative volume decay momentum, market-neutralized. The entire process is agent-autonomous. <p align="center"> <img src="example_factor/1-1.png" width="49%" alt="WQ BRAIN PnL — Debt-Momentum Composite (Submitted)" /> <img src="example_factor/1-2.png" width="49%" alt="WQ BRAIN IS Summary — Debt-Momentum Composite (Submitted)" /> </p> <p align="center"> _{Debt-Momentum Composite — Formally submitted: Sharpe 1.77, Fitness 1.26, Returns 20.18%, IS all PASS} </p> <p align="center"> <img src="example_factor/2-1.png" width="49%" alt="WQ BRAIN PnL — VWAP Decay Reversal (Submitted)" /> <img src="example_factor/2-2.png" width="49%" alt="WQ BRAIN IS Summary — VWAP Decay Reversal (Submitted)" /> </p> <p align="center"> _{VWAP Decay Reversal — Formally submitted: Sharpe 1.69, Fitness 1.07, Returns 18.63%, IS all PASS} </p> <p align="center"> <img src="example_factor/3-1.png" width="49%" alt="WQ BRAIN PnL — Returns-Volume Momentum (Submitted)" /> <img src="example_factor/3-2.png" width="49%" alt="WQ BRAIN IS Summary — Returns-Volume Momentum (Submitted)" /> </p> <p align="center"> _{Returns-Volume Momentum — Formally submitted: Sharpe 1.60, Fitness 1.03, Returns 24.15%, IS all PASS} </p> --- ## Autonomous Factor Mining — The Core Loop > **This is QuantGPT's defining capability.** > > The agent reads the knowledge base, designs hypotheses, conducts batch experiments, analyzes results, accumulates knowledge, and self-iterates, with each conclusion undergoing dual-model cross-validation. A-level factors are automatically uploaded to [QuantGPT Cloud](https://quant-gpt.com) for independent verification, establishing auditable out-of-sample tracking records. ### Research Cycle ``` ┌─────────────────────────────┐ │ Research Notes & Knowledge │ │ (Rules / Findings / Fails) │ └──────────┬──────────────────┘ │ read ▼ ┌──────────┐ ┌──────────────────────────┐ ┌──────────────────┐ │ Phase 0 │───▶│ Phase 1: Factor Design │───▶│ Phase 2: Batch │ │ Context │ │ Hypothesis → Expression │ │ Backtest (10-20 │ │ Loading │ │ 1-3 candidates per idea │ │ concurrent) │ └──────────┘ └──────────────────────────┘ └────────┬─────────┘ │ ┌─────────────────────────┘ ▼ ┌──────────────────────────────────────────┐ │ Phase 3: Four-Step Analysis │ │ │ │ ① Fact Collection (metrics vs baseline) │ │ ② Independent Judgment (Agent) │ │ ③ Cross-Review (DeepSeek Reasoner) │ │ ④ Consensus or Divergence Resolution │ └──────────────────┬───────────────────────┘ │ ┌──────────────┴──────────────┐ ▼ ▼ ┌─────────────────┐ ┌──────────────────┐ │ Phase 4: Update │ │ Phase 5: Stop? │ │ Notes + Knowledge│ │ Converged / │ │ Base │◀────────│ Time / Rounds │ └─────────────────┘ └──────────────────┘ │ │ no │ └──▶ back to Phase 1 ▼ ┌──────────────────┐ │ Phase 6: Report │ │ A/B factors + │ │ new knowledge │ └──────────────────┘ ``` ### Key Mechanisms <table> <tr> <td width="50%"> **Dual-LLM Cross-Review** Each conclusive judgment (adopt / not adopt / close direction) must undergo an independent review by a second LLM. The fact data and the reasoning chain of the first model are sent to DeepSeek Reasoner for independent evaluation of whether the reasoning is reasonable and whether there are missing perspectives. Consensus → direct output. Disagreement → presenting both sides' evidence, adopting a more conservative conclusion. This solves the core problem of single-model factor research: **confirmation bias**. </td> <td width="50%"> **Persistent Knowledge Base** ``` research_notes/knowledge/ ├── rules/ ← verified stable rules (must be followed) ├── findings/ ← empirical findings (reference) └── failures/ ← proven paths (prohibited from repetition) ``` The knowledge base accumulates across sessions. The 10th research session can directly utilize all findings from the previous 9 sessions, avoiding repeated experiments, adhering to verified rules, and bypassing proven paths. This is not chat history - it's **structured research assets**. </td> </tr> <tr> <td> **Batch Concurrent Evaluation** Submit 10-20 factor expressions at once, concurrent backtesting + three-wave retries. Results are sorted in descending order of fitness. When hs300 fitness < 0.1, automatically skip csi500 verification to save computing power. ```python from scripts.factor_miner import batch_evaluate results = batch_evaluate( server, expressions, params, max_concurrent=10 ) ``` </td> <td> **Research Discipline (Enforced)** Not suggestions, but hard rules: - Only change one variable per experiment - Check if already done before submission (notes + knowledge base) - Analyze conclusions labeled as "hypothesis only" - Record reasons for failed experiments - Expressions > 4 layers of nesting require additional justification - Simple and clear > complex and sophisticated </td> </tr> </table> > **The factors in Validated Results above are the output of this process.** Multiple rounds of iteration, A-level factors automatically uploaded to [QuantGPT Cloud](https://quant-gpt.com) for independent verification. See the full methodology in [Factor Mining Guide](docs/FACTOR_MINING.md). --- ## Architecture ``` ┌────────────────────────────────────────────────────────────────────┐ │ QuantGPT Research Engine │ ├─────────────┬──────────────────────────────┬───────────────────────┤ │ │ Core Engine │ │ │ Agent │ ┌──────────────────────┐ │ Data Layer │ │ Interface │ │ Expression Parser │ │ ┌─────────────────┐ │ │ │ │ 60+ operators │ │ │ baostock (free) │ │ │ MCP Tools │ │ Cloud + WQ compat. │ │ │ akshare (free) │ │ │ REST API │ └──────────┬───────────┘ │ │ PolarDB (opt) │ │ │ Web UI │ ┌──────────▼───────────┐ │ │ Parquet cache │ │ │ (monitor) │ │ Backtest Engine │ │ └─────────────────┘ │ │ │ │ Rank-based grouping │ │ │ │ │ │ Cloud aligned │ │ AI Layer │ │ │ └──────────┬───────────┘ │ ┌─────────────────┐ │ │ │ ┌──────────▼───────────┐ │ │ DeepSeek LLM │ │ │ │ │ Validation Suite │ │ │ Factor design │ │ │ │ │ Anti-overfit (4x) │ │ │ Cross-review │ │ │ │ │ Walk-forward │ │ │ Mutation engine │ │ │ │ │ QuantGPT Cloud │ │ └─────────────────┘ │ │ │ │ WQ BRAIN (optional) │ │ │ │ │ └──────────────────────┘ │ Storage │ │ │ │ ┌─────────────────┐ │ │ │ Evolution Engine │ │ SQLite (default)│ │ │ │ Trajectory → Meta-Evo → │ │ PostgreSQL (opt)│ │ │ │ Mutation / Crossover │ └─────────────────┘ │ ├─────────────┴──────────────────────────────┴───────────────────────┤ │ Agent Orchestrator: Claude Code skill loop / Claude Desktop MCP │ └────────────────────────────────────────────────────────────────────┘ ``` ### Tech Stack | Layer | Technology | |:------|:-----------| | Agent | Claude Code (skill loop) / Claude Desktop (MCP) | | Backend | Python 3.10+, FastAPI, uvicorn, SQLAlchemy 2.0 async | | Database | SQLite (default, zero-config) / PostgreSQL (optional) | | AI/LLM | DeepSeek (factor generation + cross-review) | | Market Data | baostock + akshare (free) → Parquet cache | | Cloud Validation | [QuantGPT Cloud](https://quant-gpt.com) — independent IC/IR verification | | Frontend | React 18 + TypeScript + Tailwind CSS 4 (monitoring dashboard) | | MCP | FastMCP (stdio / SSE / streamable-http) | | Report | QuantStats HTML | --- ## Key Engineering Decisions ### 1. Expression Parser — The Core Differentiator The self-developed expression parser (`expression_parser.py`, 1000+ lines) is the core of the entire system: - **60+ operators**: Sectional (`rank`, `zscore`), time-series (`ts_corr`, `decay_linear`), nonlinear (`sigmoid`, `tanh`, `sign_power`), conditional/ternary (`where`, `trade_when`, `? :`), technical indicators (`rsi`, `macd`, `atr`) - **Dual mode**: `mode="local"` opens all 60+ operators, `mode="wq"` only allows WQ BRAIN compatible subset (optional submission verification) - **Semantically correct sectional/time-series separation**: `rank()` grouped by `trade_date` (sectional), `ts_mean()` grouped by `stock_code` (time-series), automatically handling grouping logic - **Safety constraints**: recursion depth limit, window upper limit, expression length limit, preventing malicious input ### 2. Three-Layer Anti-Overfit System | Layer | Module | Method | |:------|:-------|:-------| | Statistical Tests | `anti_overfit.py` | IC stability + sub-sample stress test (bull/bear/oscillation) + placebo test + half-life estimation | | Walk-Forward | `rolling_validator.py` | Rolling train/valid/test window, evaluating sample-outside IC decay | | WQ Simulation | `wq_simulate.py` | Dollar-neutral long-short simulation, Sharpe/Turnover/Fitness calculation | | **QuantGPT Cloud** | `cloud_client.py` | **Independent verification — A-level factors automatically uploaded to [quant-gpt.com](https://quant-gpt.com) + IC/IR verification + sample-outside tracking** | | WQ BRAIN API (optional) | `wq_brain_client.py` | Direct connection to BRAIN platform — real simulation + one-click formal submission | ### 3. Evolutionary Factor Iteration Three-stage automatic search inspired by QuantaAlpha: ``` TrajectoryAnalyzer → MetaEvolutionSelector → Strategy Execution (quality indicator evaluation) (EXPLOIT/EXPLORE/ (MutationEngine ×8 directions RECOMBINE/SIMPLIFY) / CrossoverEngine) ``` 8 directional mutations: time window variation, operator replacement, complexity adjustment, sectional transformation superposition, etc. 5-dimensional scoring drives iteration direction. ### 4. Agent-First Access Model | Mode | Role | Use Case | |:-----|:-----|:---------| | **MCP (primary)** | Agent toolkit | Claude Code / Claude Desktop invoke all research tools, driving autonomous research loop | | **REST API** | Programmatic access | Batch backtesting, external system integration, CI/CD factor verification | | **Web UI** | Monitoring dashboard | Task monitoring, report viewing, factor library management | <details> <summary><b>MCP Tools (15)</b></summary> | Tool | Description | |:-----|:------------| | `list_operators` | All operator documentation | | `list_universes` | Stock pools and benchmarks | | `validate_expression` | Syntax verification | | `run_backtest` | Complete backtesting | | `score_factor` | Scoring (0–100, A/B/C/D) | | `diagnose_factor` | Failed mode diagnosis + improvement suggestions | | `run_anti_overfit` | 4 anti-overfitting tests | | `run_rolling_validation` | Walk-forward verification | </details> --- ## Competitive Landscape | Capability | JoinQuant | Backtrader | ChatGPT + Backtest | **QuantGPT** | |:-----------|:------:|:------:|:------:|:------:| | Research mode | Human writes code | Human writes code | Human prompts, tool executes | **Agent autonomously researches** | | Factor discovery | Manual | Manual | One-shot LLM | **Multi-round evolution + knowledge base** | | Anti-bias | Researcher judgment | None | None | **Dual-LLM mandatory cross-review** | | Knowledge accumulation | Personal notes | None | Lost between sessions | **Structured KB across sessions** | | Anti-overfit | -- | -- | -- | **4 statistical tests + walk-forward** | | Independent validation | -- | -- | -- | **[QuantGPT Cloud](https://quant-gpt.com) — independent IC/IR verification + sample-outside tracking** | | WQ BRAIN (optional) | -- | -- | -- | Operator-aligned + direct submission | | MCP / AI Agent | -- | -- | -- | **15 tools, skill-loop orchestration** | | Live trading | Yes | Limited | -- | -- | | Intraday data | Yes | Yes | -- | Daily only | --- ## Quick Start ### Option 1: Agent Mode (Recommended) ```bash git clone https://github.com/Miasyster/QuantGPT.git && cd QuantGPT make setup # creates venv, installs deps, generates .env make run # starts server at http://localhost:8003 ``` Add MCP configuration to Claude Code or Claude Desktop: ```json { "mcpServers": { "quantgpt": { "command": "python", "args": ["-m", "quantgpt"] } } } ``` Then let the Agent work: *"挖掘高质量因子，自动上传 Cloud 验证"* ### Option 2: Expression Mode (No LLM Required) ```bash # Direct expression backtest via API curl -X POST http://localhost:8003/api/v1/auto_backtest \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <token>" \ -d '{"expression": "rank(close / ts_mean(close, 20))", "universe": "hs300"}' ``` ### Windows Quick Start Windows users do not need `make` and `restart.sh`, manually execute: ```powershell # 1. Clone project git clone https://github.com/Miasyster/QuantGPT.git cd QuantGPT # 2. Create virtual environment and install dependencies python -m venv .venv .venv\Scripts\activate pip install -e . # Optional: install PostgreSQL support # pip install -e ".[postgresql]" # 3. Build frontend (requires Node.js, download LTS version from nodejs.org) cd frontend && npm install && npm run build && cd .. # 4. Start service python -m quantgpt --transport http # Open browser at http://localhost:8003 ``` > **Note:** > - Recommended Python 3.11 or 3.12 (3.14 too new, some dependencies may not be compatible) > - If port occupied: `netstat -ano | findstr :8003` check process, `taskkill /PID <pid> /F` kill > - Can also use WSL2 (`wsl --install`), experience consistent with macOS/Linux **Zero config by default**: SQLite database, baostock + akshare free data. See [full Quick Start guide](docs/QUICKSTART.md) for details. <details> <summary><b>Optional: DeepSeek API (for factor generation & cross-review)</b></summary> ```bash # Edit .env, add your DeepSeek API key (~$0.001 per query) DEEPSEEK_API_KEY=sk-your-key-here ``` </details> <details> <summary><b>Optional: PostgreSQL (for production)</b></summary> ```bash pip install "quantgpt[postgresql]" ``` Edit: DATABASE_URL=postgresql+quantgpt:password@localhost:5432/quantgpt alemb head ``` </details> <summary><b>Optional: Cloud (independent validation)</b></summary> ```bash # Edit .env — A-grade factors auto-upload for independent validation QUANTGPT_CLOUD_EMAIL=your_email@example.com QUANTGPT_CLOUD_PASSWORD=your_password ``` Register at [quant-gpt.com](https://quant-gpt.com), then add credentials to `.env`. A-grade factors will be automatically uploaded and independently validated (IC/IR/turnover/correlation checks). </details> <details> <summary><b>Expression Examples</b></summary> **Local backtest** — works out of the box with baostock/akshare data: ```python # 20-day momentum rank(close_mean(close, 20)) # rank(-1 * ts/ts_shift(close,1)- 20)) # Decay-weighted correlation decay_linear(rank(ts_corr(vwap, volume, 10)), 5) # Momentum + profitability composite -1 * rank(ts_av_diff(close, 10)) + rank(roe) ``` **WQ BRAIN remote (optional)** — these expressions use fields only available via WQ BRAIN submission: ```python # composite — BRAIN submitted, Fitness 1.26,1.77 -1 *_diff(close, 10 rank(debt / enterprise_value VWAP decay reversal — BRAIN submitted, Fitness 1.07, Sharpe 1.69 -1 * rank(ts_decay_linear(close / vwap, 10)) # Returns-volume momentum — BRAIN submitted, Fitness 1. Sharpe 1.60 -1 * rank(ts_decay_linear(returns * volume / adv20, 5)) ``` </details> --- ## Project Structure ``` quantgpt/ ├── quantgpt/ # Backend (Python) ├── expression_parser.py # parser (60+ ops, WQ compatible) │ ├── backtest.py # Rank-based group backtest engine │ ├── market_data.py # baostock/akshare cache │ ├── api_server.py # FastAPI REST API │ ├── m.py # FastMCP server tools — Agent's toolkit) ├── iteration.py # evolutionary iteration │ ├──.py # 8 directed │ ├── crossover_engine # High-score factor crossover ├── meta_evolution.py # Adaptive strategy selector │ ├──analyzer.py # Trajectory quality│ ├── anti_overfit # 4 statistical anti-over │ ├── rolling_validator # Walk-forward validation │ wq_simulate.py # Dollar-neutral simulator │ ├── wq_brain_client.py # WQ BRAIN API (optional) │ ├── cloud_client.py # QuantGPT Cloud upload + independent validation │ ├── neutralize.py # Industry & cap neutralization │ ├── daily_summary.py # LLM-powered daily market report │ └── routes/ # API route modules ├── frontend/ # React 18 + TypeScript + Tailwind CSS 4 │ └── src/components/ # Monitoring dashboard ├── scripts/ │ └── factor.py # Batch factor evaluation├── tests/ # 74 tests (parser + backtest + WQ simulate) ├── example_factor/ # BRAIN validation screenshots └── docs/ # Architecture, API, MCP, Mining guides ``` --- ## Limitations - **Daily frequency only** — no intraday backtesting - **A-share market only** — China mainland equities - **Agent quality depends on LLM** — better models produce --- ## License [MIT](LICENSE) — Copyright (c) 2026 Miasyster is the **original source** QuantGPT factor research engine. Derivative works should retain the copyright notice and comply with the MIT License terms. See [NOTICE](NOTICE) for details. _{*Past factor performance does not guarantee future returns. This project does not constitute investment advice.*}