wqb-server

BRAIN 表达式模板解码器 - Flask Web 应用程序

一个全面的 Flask Web 应用程序，用于解码字符串模板，具备语法检查、语法高亮显示，并与 WorldQuant BRAIN 平台无缝集成以获取真实操作员数据。

🚀 功能

核心功能

• 模板检测：自动检测表达式中的 <template_name/> 模式
• 语法检查：实时验证分号、注释和语法
• 语法高亮：带行号和自动完成的颜色编码显示
• 模板解码：生成表达式的两种模式
  • 完全迭代：生成所有可能的模板变量组合
  • 随机迭代：生成指定大小的随机样本
• 导出选项：复制结果或下载为文本文件

模板类型

• Op（操作符） - 蓝色按钮，与 BRAIN 操作符集成
• Data（数据字段） - 绿色按钮，用于数据字段配置
  
• Normal（参数） - 灰色按钮，用于一般参数

BRAIN 集成

• 内置 API 集成：直接连接到 WorldQuant BRAIN API，支持 CORS
• 186+ 操作符：访问所有操作符类别（算术、排名、减少、时间序列等）
• 800+ 数据字段：来自基础数据集，支持搜索和过滤
• 高级搜索：按类别过滤操作符并按名称搜索
• 多选界面：专业的操作符选择，带视觉反馈

🛠️ 设置与安装

先决条件

• Python 3.7 或更高版本
• pip（Python 包管理器）
• WorldQuant BRAIN 账户（用于 BRAIN 集成功能）

快速开始

1. 克隆或下载此代码库到本地机器

2. 运行应用程序（依赖项将自动安装！）:

在 Windows 上：

   # 双击 run_app.bat 或在终端运行：
   run_app.bat

在 macOS/Linux 上：

   # 首次使脚本可执行：
   chmod +x run_app.sh
   
   # 运行应用程序：
   ./run_app.sh

或直接用 Python 运行：

   python app.py

1. 自动依赖安装：

   • 应用程序将自动检查缺失的依赖项
   • 如果缺少任何软件包，将从 requirements.txt 安装
   • 对于中国用户：依赖项将从清华大学镜像自动下载，以加快安装速度
   • 无需手动安装！

2. 打开应用程序：

   • Flask 服务器在 http://localhost:5000 启动
   • 打开您的网络浏览器并导航到 http://localhost:5000
   • 一切都已集成 - 无需单独的代理服务器！

对于中国用户

该应用程序自动使用清华大学的 PyPI 镜像进行更快的下载。如果您希望手动安装依赖项：

Windows：

# 使用清华镜像的安装脚本
setup_tsinghua.bat

macOS/Linux：

# 使可执行并运行
chmod +x setup_tsinghua.sh
./setup_tsinghua.sh

使用清华镜像的手动安装：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt

配置其他镜像： 您可以通过编辑 mirror_config.txt 更改镜像源。该文件包括几个流行的中国镜像：

• 清华大学 - 默认
• 阿里云
• 豆瓣
• 中国科学技术大学

手动安装

如果自动安装失败，您可以手动安装：

# 从 requirements.txt 安装依赖项
pip install -r requirements.txt

# 或单独安装软件包
pip install flask==2.3.3 flask-cors==4.0.0 requests==2.31.0 pandas==2.0.3

# 启动应用程序
python app.py

注意：该应用程序包括自动依赖检查，当您运行它时将尝试安装缺失的软件包。

🔗 BRAIN 集成

设置

1. 无需单独设置 - BRAIN API 集成已内置于 Flask 应用程序中
2. 连接到 BRAIN：点击网页界面中的“连接到 BRAIN”按钮
3. 输入凭据：使用您的 WorldQuant BRAIN 用户名和密码
4. 自动加载操作符：系统会获取所有可用的操作符（186+）

使用 BRAIN 操作符

1. 配置模板：将模板类型设置为 “Op”
2. 选择来自 BRAIN：在模板配置中点击“从 BRAIN 中选择”按钮
3. 搜索和过滤：使用搜索框和类别过滤器查找操作符
4. 多选：选择多个操作符并将其应用于您的模板
5. 生成组合：解码模板以获取所有可能的操作符组合

📝 使用指南

1. 表达式编辑器

• 在主编辑器中输入或粘贴您的表达式
• 语法将自动检查并提供视觉反馈
• 模板将实时检测并高亮显示
• 输入 < 以获取模板建议的自动完成

2. 模板管理

• 检测到的模板出现在右侧面板中
• 点击模板类型按钮（Op/Data/Normal）进行配置
• 视觉指示器显示已配置 (✓) 与未配置 (•) 的模板
• 点击模板名称查看当前配置

3. 模板配置

• 普通模板：手动输入以逗号分隔的值
• 操作符模板：从 BRAIN 操作符中选择或手动输入
• 数据模板：输入数据字段规格

4. 模板解码

生成表达式的两个选项：

• full_iteration：生成所有可能的组合
  • 使用笛卡尔积创建每一种可能的组合
  • 显示前 999 个结果，并为大数据集提供搜索功能
• random_iteration：生成随机样本
  • 指定随机表达式数量（默认为 10）
  • 首先生成所有组合，然后随机选择指定数量
  • 有助于测试或当您只需要部分可能性时
• 每个模板必须至少具有一个配置值
• 结果将显示，并提供复制和下载选项

💡 示例表达式

positive_sentiment = rank(<backfill_op/>(<positive_sentiment/>,<days/>));
negative_sentiment = rank(<backfill_op/>(<negative_sentiment/>, <days/>));
sentiment_difference = <compare_op/>(positive_sentiment, negative_sentiment);
<time_series_operator/>(sentiment_difference, <days/>)

示例配置

• <days/> → 7, 14, 30
• <compare_op/> → ts_max, ts_min（从 BRAIN 中选择）
• <time_series_operator/> → ts_delta, ts_mean（从 BRAIN 中选择）

生成输出

解码器将生成所有组合：

ts_delta(ts_max(7), 7)
ts_delta(ts_max(14), 14)
ts_delta(ts_max(30), 30)
ts_delta(ts_min(7), 7)
ts_delta(ts_min(14), 14)
ts_delta(ts_min(30), 30)
ts_mean(ts_max(7), 7)
...等等

🎯 语法规则

• 使用 /* */ 进行多行注释
• 语句以 ; 结束（最后一行除外）
• 不允许使用类、对象、指针或函数
• 最后一行是 BRAIN 模拟器的 Alpha 表达式

🏗️ 技术架构

Flask 应用程序结构

BRAINProject/
├── app.py                 # 拥有自动依赖安装的 Flask 应用程序
├── templates/
│   └── index.html        # 主要网页界面模板
├── static/
│   ├── styles.css        # 应用程序样式
│   ├── script.js         # 核心应用程序逻辑
│   ├── decoder.js        # 模板解码算法
│   └── brain.js          # BRAIN API 集成模块
├── requirements.txt      # Python 依赖项
├── mirror_config.txt     # PyPI 镜像配置
├── run_app.bat           # Windows 启动脚本
├── run_app.sh            # Unix/macOS 启动脚本
├── setup_tsinghua.bat    # 使用清华镜像的 Windows 设置（适用于中国）
├── setup_tsinghua.sh     # 使用清华镜像的 Unix 设置（适用于中国）
├── brain_function_tester.ipynb  # 用于测试的 Jupyter 笔记本
└── README.md             # 本文件

关键组件

• Flask 后端：处理 BRAIN API 身份验证和数据获取
• 模板引擎：Jinja2 模板用于动态内容
• 静态资源：高效提供 CSS 和 JavaScript
• CORS 处理：内置跨域请求支持
• 会话管理：安全的会话处理以进行 BRAIN 身份验证

API 端点

• GET / - 主要应用程序页面
• POST /api/authenticate - BRAIN 身份验证
• GET /api/operators - 获取 BRAIN 操作符，支持分页
• GET /api/datafields - 获取 BRAIN 数据字段
• GET /api/status - 检查身份验证状态
• POST /api/logout - 从 BRAIN 登出

🔧 高级特性

操作符获取

• 强大的分页：自动处理 BRAIN API 分页
• 类别支持：获取所有类别的操作符
• 错误处理：多种应急策略以确保可靠的数据加载
• 调试：内置端点用于 API 响应分析

模板处理

• 实时检测：在输入时检测模板
• 视觉反馈：颜色编码的语法高亮
• 状态指示器：清晰的视觉提示模板配置状态
• 验证：确保在解码前所有模板都已配置

用户体验

• 专业 UI：干净、现代的界面设计
• 响应式设计：适用于桌面和平板设备
• 键盘快捷键：高效的模板自动完成
• 导出选项：复制单个结果或下载所有结果

🐛 故障排除

常见问题

1. Flask 服务器无法启动：

   • 检查 Python 版本（需要 3.7+）
   • 安装缺失的依赖项：pip install -r requirements.txt

2. BRAIN 连接失败：

   • 验证您的 BRAIN 凭据
   • 检查网络连接
   • 确保没有防火墙阻止外发 HTTPS 请求

3. 模板未检测到：

   • 检查模板语法：<template_name/>
   • 使用按钮手动刷新模板

4. 没有加载操作符：

   • 验证 BRAIN 身份验证是否成功
   • 检查浏览器控制台是否有错误信息
   • 尝试登出并重新认证

调试模式

在调试模式下运行应用程序以获取详细错误信息：

python app.py
# 应用程序默认启用调试模式

📈 性能

• 高效加载：操作符在身份验证时加载一次
• 分页处理：自动获取所有数据，无论 API 分页如何
• 会话管理：持久会话提升用户体验
• 优化前端：最小的 JavaScript 依赖加快加载速度

🔐 安全

• 会话安全：Flask 安全会话，支持可配置的密钥
• 凭据处理：凭据不被存储，仅用于 API 身份验证
• CORS 保护：正确配置的跨域请求处理
• 输入验证：模板语法验证和语法检查

🚧 未来增强功能

• 模板库：保存和共享模板配置
• 高级过滤：更复杂的操作符和数据字段过滤
• 批量操作：同时处理多个表达式
• API 集成：连接其他金融数据提供商
• 导出格式：支持 JSON、CSV 和其他输出格式

---

注意：该 Flask 应用程序取代了之前的 HTML+代理架构，提供了更强大和集成的 BRAIN 模板解码解决方案。