# quant-sdk

**Repository Path**: ereflect/quant-sdk

## Basic Information

- **Project Name**: quant-sdk
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-21
- **Last Updated**: 2026-04-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Quant Factor Mining + A-Share Paper Trading

轻量端到端量化框架：定义算子 → 组合/替换因子 → 按目标胜率校准信号 → A 股回测/模拟盘。

## 结构

```
quant/
├── data/         # 模拟数据 + A股 (akshare + CSV 缓存)
├── operators/    # 22 个截面/时序算子
├── alpha/        # 表达式 AST + 求值
├── eval/         # IC / Rank IC / IR / 多空收益
├── strategy/     # 因子组合 + 胜率校准信号
├── portfolio/    # T+1 回测引擎 + 本地模拟盘
├── search/       # 遗传规划因子挖掘
└── cli.py        # eval | examples | mine | combo | backtest | paper
```

## 安装

```bash
pip install -r requirements.txt
# akshare 可选；不装则用模拟数据 / 已缓存的 CSV
```

## CLI

### 1. 评估单因子

```bash
python -m quant.cli eval --expr rev5
python -m quant.cli eval --expr "rank(-correlation(close, volume, 5))"
```

### 2. 因子组合 / 替换

`--factors` 接受 `name=expr;name=expr` 或例子名 `rev5;mom10;vw_rev`。
`--method`：`equal` / `weighted` / `ic`（按近期 Rank-IC 自动加权）。

```bash
# 等权 / IC 加权
python -m quant.cli combo --factors "rev5;mom10;vw_rev" --method ic

# 显式权重
python -m quant.cli combo \
  --factors "f1=rank(-delta(close,5));f2=rank(-correlation(close,volume,5))" \
  --method weighted --weights "f1=0.7,f2=0.3"
```

替换子因子（脚本内）：

```python
from quant.strategy import FactorCombo
fc = FactorCombo({"a": "rank(close)", "b": "rank(volume)"}, method="ic")
fc.replace("a", "rank(-delta(close, 5))")   # 即时替换，结构不变
scores = fc.compute(panel)
```

### 3. 指定目标胜率回测

`--target-win-rate` 触发阈值校准：在候选分位数 `(0.5, 0.6, 0.7, 0.8, 0.85, 0.9, 0.95)`
中挑出**满足历史胜率下限且选股数 ≥ min-names** 的最低分位数。

```bash
python -m quant.cli backtest \
  --factors "rev5;mom10;vw_rev" --method ic \
  --target-win-rate 0.55 --min-names 3 --max-names 8 \
  --rebalance weekly --cash 500000
```

输出每个候选分位数的实测胜率/选股数 + 最终 NAV、Sharpe、最大回撤、交易笔数。
A 股交易约束已建模：T+1、佣金 0.0003 (≥5 元)、印花税 0.001（卖出）、100 股整手、次日开盘成交。

### 4. A 股本地模拟盘

```bash
# 首次：用 A 股真实数据（akshare 下载并缓存到 .cache/ashare/）
python -m quant.cli paper --ashare \
  --symbols-list "600519,000001,600036,000333,601318,002594,300750,601012" \
  --start 2024-01-01 \
  --factors "rev5;mom10;vw_rev" --method ic \
  --target-win-rate 0.55 --min-names 3 --max-names 6 \
  --cash 500000 --steps 5 --reset

# 之后每天追加一步（cron 友好，同一日重复 step 是幂等的）
python -m quant.cli paper --ashare ... --steps 1

# 查看账户
python -m quant.cli paper-show
```

模拟盘状态持久化在 `.cache/paper_state.json`（含现金、持仓、T+1 锁、成交流水、净值历史）。

### 5. 遗传规划自动挖掘

```bash
python -m quant.cli mine --pop 80 --generations 15 --top 10
```

## 表达式语法

字段：`open high low close volume vwap returns`

```
rank(x) ts_mean(x,n) ts_std(x,n) ts_rank(x,n) ts_argmax(x,n) ts_argmin(x,n)
delta(x,n) delay(x,n) correlation(x,y,n) covariance(x,y,n)
scale(x,a) signedpower(x,a) log(x) abs(x) sign(x)
+ - * /  -x
```

## 测试

```bash
python -m pytest tests/ -q
```