# Alpha Transformer ()

基于AI的Alpha变种自动生成器，将一个种子Alpha转换为多个具有不同逻辑和参数的新Alpha表达式。

## 功能概述

****的核心思想是：给定一个种子Alpha作为参考，结合大量已知的Alpha模板和AI能力，自动生成多个具有不同策略逻辑的新Alpha表达式。这些变种可以用于：
- 策略多元化（避免单一策略风险）
- 参数优化（探索最优参数组合）
- 逻辑变体（发现新的市场规律）

## 工作原理详解

### 整体流程

```
种子Alpha → 获取详情 → AI生成模板 → 填充参数 → 验证输出
    ↓           ↓            ↓           ↓         ↓
  原始ID    settings    逻辑变体    表达式组合   JSON结果
            expression   + expression
            datafields
```

### 第一阶段：获取种子Alpha信息

当用户输入Alpha ID后，系统会：

1. **连接BRAIN平台** - 使用提供的用户名密码认证
2. **获取Alpha详情** - 通过API获取以下信息：
   - `settings`: Alpha的配置参数（region, universe, delay等）
   - `expression`: Alpha的具体表达式代码
   - `description`: Alpha的策略描述
   - `operators`: 使用的算子列表（ts_mean, group_rank等）
   - `data_fields`: 使用的数据字段（close, volume等）

3. **解析表达式结构** - 分析Alpha代码中的：
   - 占位符类型（数据字段、时间窗口、分组方式等）
   - 算子组合模式
   - 数据依赖关系

### 第二阶段：AI生成模板

这是**的核心**。系统会：

1. **构建提示词** - 将以下内容发送给LLM：
   ```
   种子Alpha详情（settings + expression + 使用的算子）
   + 模板摘要（template_summary.md中的90+个模板）
   + 生成指令（要求生成X个变种模板）
   ```

2. **LLM推理** - AI根据以下信息生成新模板：
   - 种子Alpha的核心逻辑是什么？
   - template_summary中有哪些类似或可组合的模板？
   - 如何创造性地变形生成新模板？

3. **模板输出** - LLM返回的每个模板包含：
   - `template_expression`: 使用占位符的模板表达式
     - 例如：`group_rank(<data_field/> / ts_mean(<data_field/>, <window/>))`
   - `template_explanation`: 模板的核心思想和逻辑说明

### 第三阶段：模板填充

对每个生成的模板，系统会：

1. **识别占位符** - 解析模板中的所有`<placeholder/>`：
   ```python
   # 常见的占位符类型
   <data_field/>    # 数据字段（如 close, volume, pe_ratio）
   <window/>        # 时间窗口（如 20, 60, 120）
   <group/>          # 分组方式（如 industry, sector）
   <operator/>       # 操作符（如 ts_mean, rank）
   ```

2. **获取候选数据** - 从BRAIN API获取：
   - 符合条件的数据字段列表（top_n个）
   - 可用的窗口参数
   - 支持的分组方式

3. **组合生成** - 笛卡尔积组合所有候选：
   ```python
   # 如果模板有2个<data_field/>和3个<window/>
   # 则生成 50 * 50 * 3 = 7500 个表达式（示例）
   
   # 实际会限制总数，避免组合爆炸
   ```

4. **设置继承** - 新生成的表达式会继承种子Alpha的：
   - Region（地区）
   - Universe（股票池）
   - Delay（延迟）
   - Neutralization（中性化方式）

### 第四阶段：验证与输出

1. **表达式验证** - 验证生成的表达式是否合法：
   - 语法检查
   - 数据依赖检查
   - 算子兼容性检查

2. **结果分类** - 分成三类输出：
   - **Alpha_candidates.json**: 模板级别的结果
     - 包含模板表达式和每个占位符的候选列表
     - 可用于进一步手动编辑或参数调整
   
   - **Alpha_generated_expressions_success.json**: 成功生成的表达式
     - 具体的、可直接使用的Alpha表达式
     - 可导入BRAIN或回测器
   
   - **Alpha_generated_expressions_error.json**: 失败的表达式
     - 生成或验证过程中出错的表达式
     - 用于排查模板问题

## template_summary.txt 的作用

### 文件内容

`template_summary.md`是一个包含**90+个精选Alpha模板**的文档，每个模板包含：

1. **Hypothesis（假设）** - 策略的核心思想
   ```
   "After news is released, if a stock takes a longer time to rise,
    it may show strong evidence of upward momentum"
   ```

2. **Expression（表达式）** - 具体的Alpha代码
   ```
   `ts_backfill(vec_avg(nws12_prez_4l),504)`
   ```

3. **Settings（设置）** - 推荐使用的配置
   ```
   Region: USA, Universe: TOP500, Delay: 1
   ```

4. **逻辑链深度解析** - 为什么这个Alpha有效
   ```
   - 时序相对性: ts_backfill处理新闻数据的稀疏性
   - 算子深意: vec_avg聚合多维情绪
   ```

5. **优化方向** - 如何进一步改进
   ```
   - 去噪: 增加winsorize或rank
   - 从属信号: 叠加Social Media Effect
   ```

### 模板分类

文件中的模板来自多个来源：

1. **Learn系列** - BRAIN官方教程中的示例
   - Learn101: 基础Alpha示例
   - Learn102: 中级Alpha示例
   - Learn103: 高级Alpha示例

2. **《151 Trading Strategies》** - 学术论文中的策略
   - 动量策略
   - 价值策略
   - 波动率策略

3. **社区精选** - 论坛中高评分的Alpha

### 为什么修改它能生成不同结果？

**是的，这是生成不同Alpha变种的关键！**

当你修改`template_summary.md`时：

| 修改内容 | 影响 |
|---------|------|
| **增加新模板** | LLM有更多参考，生成更多样化的变种 |
| **删除旧模板** | 生成的变种会集中在剩余模板上 |
| **修改模板说明** | LLM对模板的理解改变，生成的变种逻辑不同 |
| **调整模板格式** | 可能影响LLM的解析和理解 |

### 如何优化template_summary

**建议策略：**

1. **按主题分类** - 如果你想生成某类策略的变种
   ```markdown
   ## 动量策略
   [相关的5-10个模板]
   
   ## 价值策略
   [相关的5-10个模板]
   ```

2. **加入自己的Alpha** - 如果你有成功的Alpha
   ```markdown
   ## 我的成功策略
   **Expression**: `group_rank(close / ts_mean(close, 20))`
   **核心思想**: 均线偏离策略
   ```

3. **保持格式一致** - 确保每个模板都包含：
   - 清晰的假设
   - 具体表达式
   - 逻辑解析

4. **定期更新** - 随着策略进化，不断添加新的有效模板

## 快速开始

### 1. 安装依赖

```bash
cd /Users/jack/source/mySpace/mycode/my_project/py/alpha/WqApp/simple72
pip install -r requirements.txt
```

### 2. 启动服务

```bash
python main.py
```

服务将在 http://localhost:8000 启动

### 3. 使用Web界面

1. 打开浏览器访问 http://localhost:8000
2. 填写表单：
   - **Alpha ID**: 输入种子Alpha的ID（格式如 `ak2YPVxv`）
   - **LLM API Key**: 你的LLM服务API密钥
   - **LLM Base URL**: LLM服务地址
     - Kimi: `https://api.moonshot.cn/v1`
     - OpenAI: `https://api.openai.com/v1`
     - 其他: `https://your-llm-service.com/v1`
   - **LLM Model**: 模型名称（如 `kimi-k2.5`, `gpt-4`）
   - **BRAIN Username/Password**: 你的BRAIN平台账号
3. 点击"生成变种"
4. 等待处理完成（通常3-10分钟）
5. 查看或复制JSON结果

### 4. 使用API

```bash
curl -X POST http://localhost:8000/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "alpha_id": "ak2YPVxv",
    "llm_api_key": "your-api-key",
    "llm_base_url": "https://api.moonshot.cn/v1",
    "llm_model": "kimi-k2.5",
    "brain_username": "your-brain-user",
    "brain_password": "your-brain-pass",
    "top_n_datafield": 50
  }'
```

## API端点

### GET /
- **功能**: 主页面
- **返回**: HTML页面

### POST /api/generate
- **功能**: 生成Alpha变种
- **请求体**:
  ```json
  {
    "alpha_id": "string (必填)",
    "llm_api_key": "string (必填)",
    "llm_base_url": "string (必填)",
    "llm_model": "string (必填)",
    "brain_username": "string (必填)",
    "brain_password": "string (必填)",
    "top_n_datafield": "int (可选，默认50)",
    "user_region": "string (可选)",
    "user_universe": "string (可选)",
    "user_delay": "int (可选)",
    "user_category": "string (可选)",
    "user_data_type": "string (可选，默认MATRIX)"
  }
  ```
- **响应**:
  ```json
  {
    "success": true,
    "alpha_id": "种子Alpha ID",
    "candidates": [...],
    "expressions_success": [...],
    "expressions_error": [...]
  }
  ```

### GET /api/health
- **功能**: 健康检查
- **响应**: `{"status": "healthy", "service": "alpha-transformer"}`

## 项目结构

```
simple72/
├── main.py                      # FastAPI应用入口
├── requirements.txt             # 依赖清单
├── Tranformer/                  # Transformer核心模块
│   ├── Transformer.py           # 主逻辑（~5000行）
│   │   ├── generate_alpha_description()  # 获取Alpha详情
│   │   ├── generate_new_alphas()        # 生成新Alpha
│   │   ├── propose_alpha_templates()     # LLM生成模板
│   │   ├── populate_template()          # 填充模板
│   │   └── validate_expression()        # 验证表达式
│   ├── ace_lib.py              # BRAIN API客户端
│   ├── helpful_functions.py    # 辅助函数
│   ├── validator.py            # 表达式验证器
│   ├── template_summary.md    # 模板摘要（可自定义）
│   └── output/                 # 输出目录
│       ├── Alpha_candidates.json
│       ├── Alpha_generated_expressions_success.json
│       └── Alpha_generated_expressions_error.json
└── templates/
    └── index.html              # 前端页面
```

## 高级配置

### 调整生成数量

修改`top_n_datafield`参数：
- 值越大 → 生成的表达式越多，但处理时间越长
- 值越小 → 生成更快，但可能错过好的变种
- 建议值：30-100之间

### 自定义模板摘要

编辑`Tranformer/template_summary.md`：
- 添加你认为有效的Alpha模板
- 按策略类型分类整理
- 保持每个模板的格式一致性

### 限制生成范围

通过可选参数限制生成范围：
- `user_region`: 只在特定地区生成
- `user_universe`: 只在特定股票池生成
- `user_delay`: 只使用特定的延迟设置

## 常见问题

### Q: 生成失败怎么办？
A: 检查以下几点：
1. BRAIN账号密码是否正确
2. LLM API Key是否有效
3. Alpha ID是否存在且可访问
4. 查看返回的error字段

### Q: 生成的结果都是类似的？
A: 尝试：
1. 修改`template_summary.md`，添加更多样化的模板
2. 调整`top_n_datafield`，增加数据字段候选
3. 使用不同的种子Alpha

### Q: 生成时间太长？
A: 这是正常的，因为：
- LLM调用需要时间
- BRAIN API查询数据字段
- 表达式组合和验证

可以：
- 减少`top_n_datafield`
- 简化`template_summary.md`
- 使用本地部署的LLM

## 技术栈

- **后端**: FastAPI + asyncio
- **LLM调用**: OpenAI SDK (AsyncOpenAI)
- **BRAIN连接**: requests Session
- **前端**: 原生HTML/CSS/JavaScript
- **验证**: 自定义表达式验证器

## 许可证

MIT License

## 参考资源

- [WorldQuant BRAIN 文档](https://www.worldquantbrain.com/)
- [BRAIN表达式语法](https://www.worldquantbrain.com/data/expressions)
- [BRAIN算子列表](https://www.worldquantbrain.com/data/operators)