ProStock/README.md

# ProStock

A股量化投资框架，用于量化股票投资分析。

## 特性

- **数据管理**：Tushare API 行情数据获取，DuckDB 本地数据存储
- **因子引擎**：DSL 表达式驱动的高性能因子计算框架（基于 Polars）
- **机器学习**：支持 LightGBM 回归和 LambdaRank 排序学习
- **组件化设计**：灵活的数据处理器、股票池管理、过滤器组合

## 环境要求

- Python 3.10+
- uv 包管理器

## 安装

```bash
# 克隆项目
cd ProStock

# 使用 uv 安装依赖
uv pip install -e .
```

## 配置

创建 `config/.env.local` 文件：

```bash
# Tushare Token（必需）
TUSHARE_TOKEN=your_token_here

# 数据存储路径（可选，默认 data/）
DATA_PATH=data

# API 速率限制（可选，默认 100）
RATE_LIMIT=100

# 并发线程数（可选，默认 10）
THREADS=10
```

## 快速开始

### 1. 同步股票数据

```python
from src.data.sync import sync_all

# 增量同步（默认）
sync_all()

# 强制全量同步
sync_all(force_full=True)

# 自定义线程数
sync_all(max_workers=20)
```

### 2. 计算因子

```python
from src.factors import FactorEngine

# 初始化引擎
engine = FactorEngine()

# 添加因子（推荐使用字符串表达式）
engine.add_factor("ma20", "ts_mean(close, 20)")
engine.add_factor("alpha", "cs_rank(ts_mean(close, 5) - ts_mean(close, 20))")

# 计算因子值
result = engine.compute(["ma20", "alpha"], "20240101", "20240131")
```

### 3. 训练模型

```python
from src.training import Trainer, DateSplitter, StockPoolManager
from src.training.components.models import LightGBMModel

# 创建模型
model = LightGBMModel(params={
    "objective": "regression",
    "num_leaves": 20,
    "learning_rate": 0.01,
    "n_estimators": 1000,
})

# 创建数据划分器
splitter = DateSplitter(
    train_start="20200101",
    train_end="20231231",
    val_start="20240101",
    val_end="20241231",
    test_start="20250101",
    test_end="20251231",
)

# 创建训练器并训练
trainer = Trainer(
    model=model,
    splitter=splitter,
    target_col="future_return_5",
    feature_cols=["ma_5", "ma_20", "volume_ratio"],
)

trainer.train(data)
results = trainer.get_results()
```

## 项目结构

```
ProStock/
├── src/
│   ├── config/           # 配置管理
│   ├── data/             # 数据获取与存储
│   │   ├── api_wrappers/ # Tushare API 封装
│   │   ├── storage.py    # DuckDB 存储
│   │   └── sync.py       # 数据同步调度
│   ├── factors/          # 因子计算框架
│   │   ├── engine/       # 执行引擎
│   │   ├── metadata/     # 因子元数据管理
│   │   ├── dsl.py        # DSL 表达式层
│   │   └── translator.py  # Polars 翻译器
│   └── training/         # 训练模块
│       ├── core/         # 训练核心
│       └── components/   # 组件（模型、处理器、过滤器）
├── tests/                # 测试文件
├── data/                 # 数据存储
└── docs/                 # 文档
```

## 因子框架

### 支持的函数

**时间序列函数 (ts_*)**：
- `ts_mean`, `ts_std`, `ts_max`, `ts_min`, `ts_sum`
- `ts_delay`, `ts_delta`
- `ts_corr`, `ts_cov`, `ts_rank`

**截面函数 (cs_*)**：
- `cs_rank` - 截面排名
- `cs_zscore` - Z-Score 标准化
- `cs_neutralize` - 行业/市值中性化
- `cs_winsorize` - 缩尾处理

**数学函数**：
- `log`, `exp`, `sqrt`, `sign`, `abs`
- `max_`, `min_`, `clip`
- `if_`, `where`

### 因子元数据管理

```python
from src.factors.metadata import FactorManager

# 初始化管理器
manager = FactorManager()

# 添加因子
manager.add_factor({
    "factor_id": "F_001",
    "name": "mom_5d",
    "desc": "5日价格动量",
    "dsl": "cs_rank(close / ts_delay(close, 5) - 1)",
    "category": "momentum",
})

# 查询因子
df = manager.get_factors_by_name("mom_5d")
```

## 常见任务

```bash
# 运行所有测试
uv run pytest

# 同步财务数据
uv run python -c "from src.data.api_wrappers.financial_data import sync_financial; sync_financial()"

# 批量注册因子
uv run python src/scripts/register_factors.py
```

## 依赖项

- pandas >= 2.0.0
- polars >= 0.20.0
- numpy >= 1.24.0
- tushare >= 2.0.0
- pydantic >= 2.0.0
- lightgbm >= 4.0.0
- pytest

## 文档

更多详细信息请参阅 `docs/` 目录：

- [因子表达式文档](docs/factor_expressions_document.md)
- [API 接口规范](docs/api/API_INTERFACE_SPEC.md)
- [财务数据接口](docs/api/FINANCIAL_API_SPEC.md)

## 许可证

MIT