wqbkit 0.2.2__tar.gz → 0.2.5__tar.gz

wqbkit-0.2.5/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write  # for trusted publishing (optional, if configured)
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*

wqbkit-0.2.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Crotes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wqbkit-0.2.5/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: wqbkit
+Version: 0.2.5
+Summary: WorldQuant Brain Alpha Research Automation Toolkit
+Project-URL: Homepage, https://github.com/Crotes/wqbkit
+Project-URL: Issues, https://github.com/Crotes/wqbkit/issues
+Author-email: Crotes <Crotes@yeah.net>
+License: MIT License
+        
+        Copyright (c) 2025 Crotes
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: alpha,finance,quantitative,research,trading,worldquant
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.10
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: psycopg2-binary
+Requires-Dist: python-dotenv
+Requires-Dist: pytz
+Requires-Dist: requests
+Requires-Dist: scipy
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: tqdm
+Requires-Dist: wqb
+Provides-Extra: dev
+Requires-Dist: jupyter; extra == 'dev'
+Requires-Dist: matplotlib; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# wqbkit
+
+WorldQuant Brain (WQB) Alpha Research Automation Toolkit
+
+**[English](#overview) | [中文](#概述)**
+
+---
+
+## Overview
+
+`wqbkit` is a Python toolkit that automates alpha research workflows on the [WorldQuant Brain](https://www.worldquantbrain.com) (WQB) platform. It covers the entire alpha lifecycle — from simulation and scoring to correlation analysis and genetic expression evolution.
+
+### Key Features
+
+| Module | Description |
+|--------|-------------|
+| `AlphaDbCore` | WQB authentication, HTTP request wrapper with exponential backoff retry |
+| `AlphaSimulator` | Multi-threaded batch simulation scheduler with queue-based result handling |
+| `AlphaMachine` | Genetic iteration pipeline — pruning, deduplication, and next-generation expression factories |
+| `AlphaCalcCorr` | Multi-metric correlation engine (self / ppac / prod / self_web) with greedy max-independent-set |
+| `SuperAlphaSimulator` | Dedicated simulator for SUPER-type alphas |
+| `AlphaDyeing` | SUPER alpha construction and combo template management |
+| `sc_send` | Bark (iOS) push notification for long-running jobs |
+
+---
+
+## Installation
+
+```bash
+pip install wqbkit
+```
+
+### Prerequisites
+
+- Python >= 3.10
+- PostgreSQL (optional, for local alpha metadata caching)
+- `wqb` SDK — WorldQuant Brain official Python client
+
+```bash
+pip install wqb
+```
+
+---
+
+## Quick Start
+
+```python
+from wqbkit import AlphaDbCore, AlphaCalcCorr, AlphaGenerator
+
+# Initialize core (auto-loads .env if present)
+core = AlphaDbCore()
+
+# Run correlation analysis
+calcor = AlphaCalcCorr()
+self_corr = calcor.calculate(alpha_ids, 'self')
+
+# Generate next-generation expressions
+generator = AlphaGenerator()
+new_exprs = generator.second_order_factory(
+    expression="ts_mean(close, 20)",
+    region="USA",
+    atom=True
+)
+```
+
+---
+
+## Configuration
+
+Create a `.env` file in your working directory:
+
+```env
+# Database (optional)
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=WorldQuant
+DB_USER=your_db_user
+DB_PASSWORD=your_db_password
+
+# WQB Credentials
+WQB_USERNAME=your_wqb_username
+WQB_PASSWORD=your_wqb_password
+WQB_API_BASE_URL=https://www.worldquantbrain.com
+
+# Logging & Retry
+LOG_LEVEL=INFO
+MAX_RETRIES=5
+RETRY_DELAY_BASE=2
+
+# Bark Push (optional)
+BARK_KEY=your_bark_device_key
+```
+
+`wqbkit` automatically loads `.env` on import via `python-dotenv`.
+
+---
+
+## API Reference
+
+### Core Classes
+
+```python
+from wqbkit import (
+    AlphaBaseCore,       # WQB session + HTTP + retry
+    AlphaDbCore,         # AlphaBaseCore + DB + PnL cache
+    AlphaCalcCorr,       # Correlation analysis engine
+    AlphaGenerator,      # Expression factory (0/1/2/3-order)
+    AlphaSimulator,      # Multi-threaded simulation scheduler
+    AlphaMachine,        # Genetic iteration pipeline
+    AlphaDyeing,         # SUPER alpha builder
+    SuperAlphaSimulator, # SUPER alpha simulator
+    sc_send,             # Push notification helper
+    schemas,             # Data models: FactorData, TaskData, SimulationData, FieldDate
+)
+```
+
+### Correlation Analysis
+
+```python
+from wqbkit import AlphaCalcCorr
+
+calcor = AlphaCalcCorr()
+
+# Compute correlations
+corrs = calcor.calculate(alpha_ids, metric='self')      # self-correlation
+corrs = calcor.calculate(alpha_ids, metric='ppac')      # ppac correlation
+corrs = calcor.calculate(alpha_ids, metric='prod')      # prod correlation
+
+# Max independent alpha set (greedy approximation)
+independent_alphas = calcor.max_independent_alphas(alpha_ids, threshold=0.7)
+```
+
+### Alpha Simulation
+
+```python
+from wqbkit import AlphaSimulator
+from wqbkit.schemas import FactorData
+
+sim = AlphaSimulator()
+
+# Single alpha simulation
+result = sim.simulate(expression="rank(close)", region="USA", universe="TOP3000")
+
+# Batch simulation from database queue
+sim.run_batch_simulation(task_id=123)
+```
+
+### Database Models
+
+```python
+from wqbkit import schemas
+
+factor = schemas.FactorData(
+    expression="rank(close)",
+    region="USA",
+    universe="TOP3000",
+    neutralization="SUBINDUSTRY",
+    decay=4,
+)
+```
+
+---
+
+## Project Structure
+
+```
+wqbkit/
+├── app/
+│   ├── core/          # AlphaBaseCore, AlphaDbCore, decorators, logger, URLs
+│   ├── database/      # SQLAlchemy models, AlphaDBManager, schemas
+│   └── utils/         # Token extraction helpers
+└── modules/
+    ├── regular_alpha/ # AlphaSimulator, AlphaMachine, AlphaGenerator
+    ├── super_alpha/   # SuperAlphaSimulator, AlphaDyeing, SuperAlphaCreator
+    ├── correlation/   # AlphaCalcCorr (self/ppac/prod/self_web)
+    ├── message/       # Bark push notifications
+    └── competitions/  # Osmosis V1/V2/V3 toolkit
+```
+
+---
+
+## License
+
+MIT
+
+---
+
+## 概述
+
+`wqbkit` 是一个用于自动化 [WorldQuant Brain](https://www.worldquantbrain.com) 平台 Alpha 研究的 Python 工具包，覆盖 Alpha 全生命周期：模拟、评分、去相关、遗传迭代进化。
+
+### 核心功能
+
+| 模块 | 说明 |
+|------|------|
+| `AlphaDbCore` | WQB 认证、HTTP 封装、指数退避重试 |
+| `AlphaSimulator` | 多线程批量模拟调度器，队列式结果处理 |
+| `AlphaMachine` | 遗传迭代管线：剪枝、去重、下一代表达式工厂 |
+| `AlphaCalcCorr` | 多指标相关性引擎（self/ppac/prod/self_web），贪心最大独立集 |
+| `SuperAlphaSimulator` | SUPER 类型 Alpha 专用模拟器 |
+| `AlphaDyeing` | SUPER Alpha 构造与 combo 模板管理 |
+| `sc_send` | Bark (iOS) 推送通知，用于长时任务提醒 |
+
+### 快速开始
+
+```python
+from wqbkit import AlphaDbCore, AlphaCalcCorr, AlphaGenerator
+
+core = AlphaDbCore()
+calcor = AlphaCalcCorr()
+new_exprs = AlphaGenerator().second_order_factory("ts_mean(close, 20)", region="USA")
+```

wqbkit-0.2.5/README.md

@@ -0,0 +1,212 @@
+# wqbkit
+
+WorldQuant Brain (WQB) Alpha Research Automation Toolkit
+
+**[English](#overview) | [中文](#概述)**
+
+---
+
+## Overview
+
+`wqbkit` is a Python toolkit that automates alpha research workflows on the [WorldQuant Brain](https://www.worldquantbrain.com) (WQB) platform. It covers the entire alpha lifecycle — from simulation and scoring to correlation analysis and genetic expression evolution.
+
+### Key Features
+
+| Module | Description |
+|--------|-------------|
+| `AlphaDbCore` | WQB authentication, HTTP request wrapper with exponential backoff retry |
+| `AlphaSimulator` | Multi-threaded batch simulation scheduler with queue-based result handling |
+| `AlphaMachine` | Genetic iteration pipeline — pruning, deduplication, and next-generation expression factories |
+| `AlphaCalcCorr` | Multi-metric correlation engine (self / ppac / prod / self_web) with greedy max-independent-set |
+| `SuperAlphaSimulator` | Dedicated simulator for SUPER-type alphas |
+| `AlphaDyeing` | SUPER alpha construction and combo template management |
+| `sc_send` | Bark (iOS) push notification for long-running jobs |
+
+---
+
+## Installation
+
+```bash
+pip install wqbkit
+```
+
+### Prerequisites
+
+- Python >= 3.10
+- PostgreSQL (optional, for local alpha metadata caching)
+- `wqb` SDK — WorldQuant Brain official Python client
+
+```bash
+pip install wqb
+```
+
+---
+
+## Quick Start
+
+```python
+from wqbkit import AlphaDbCore, AlphaCalcCorr, AlphaGenerator
+
+# Initialize core (auto-loads .env if present)
+core = AlphaDbCore()
+
+# Run correlation analysis
+calcor = AlphaCalcCorr()
+self_corr = calcor.calculate(alpha_ids, 'self')
+
+# Generate next-generation expressions
+generator = AlphaGenerator()
+new_exprs = generator.second_order_factory(
+    expression="ts_mean(close, 20)",
+    region="USA",
+    atom=True
+)
+```
+
+---
+
+## Configuration
+
+Create a `.env` file in your working directory:
+
+```env
+# Database (optional)
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=WorldQuant
+DB_USER=your_db_user
+DB_PASSWORD=your_db_password
+
+# WQB Credentials
+WQB_USERNAME=your_wqb_username
+WQB_PASSWORD=your_wqb_password
+WQB_API_BASE_URL=https://www.worldquantbrain.com
+
+# Logging & Retry
+LOG_LEVEL=INFO
+MAX_RETRIES=5
+RETRY_DELAY_BASE=2
+
+# Bark Push (optional)
+BARK_KEY=your_bark_device_key
+```
+
+`wqbkit` automatically loads `.env` on import via `python-dotenv`.
+
+---
+
+## API Reference
+
+### Core Classes
+
+```python
+from wqbkit import (
+    AlphaBaseCore,       # WQB session + HTTP + retry
+    AlphaDbCore,         # AlphaBaseCore + DB + PnL cache
+    AlphaCalcCorr,       # Correlation analysis engine
+    AlphaGenerator,      # Expression factory (0/1/2/3-order)
+    AlphaSimulator,      # Multi-threaded simulation scheduler
+    AlphaMachine,        # Genetic iteration pipeline
+    AlphaDyeing,         # SUPER alpha builder
+    SuperAlphaSimulator, # SUPER alpha simulator
+    sc_send,             # Push notification helper
+    schemas,             # Data models: FactorData, TaskData, SimulationData, FieldDate
+)
+```
+
+### Correlation Analysis
+
+```python
+from wqbkit import AlphaCalcCorr
+
+calcor = AlphaCalcCorr()
+
+# Compute correlations
+corrs = calcor.calculate(alpha_ids, metric='self')      # self-correlation
+corrs = calcor.calculate(alpha_ids, metric='ppac')      # ppac correlation
+corrs = calcor.calculate(alpha_ids, metric='prod')      # prod correlation
+
+# Max independent alpha set (greedy approximation)
+independent_alphas = calcor.max_independent_alphas(alpha_ids, threshold=0.7)
+```
+
+### Alpha Simulation
+
+```python
+from wqbkit import AlphaSimulator
+from wqbkit.schemas import FactorData
+
+sim = AlphaSimulator()
+
+# Single alpha simulation
+result = sim.simulate(expression="rank(close)", region="USA", universe="TOP3000")
+
+# Batch simulation from database queue
+sim.run_batch_simulation(task_id=123)
+```
+
+### Database Models
+
+```python
+from wqbkit import schemas
+
+factor = schemas.FactorData(
+    expression="rank(close)",
+    region="USA",
+    universe="TOP3000",
+    neutralization="SUBINDUSTRY",
+    decay=4,
+)
+```
+
+---
+
+## Project Structure
+
+```
+wqbkit/
+├── app/
+│   ├── core/          # AlphaBaseCore, AlphaDbCore, decorators, logger, URLs
+│   ├── database/      # SQLAlchemy models, AlphaDBManager, schemas
+│   └── utils/         # Token extraction helpers
+└── modules/
+    ├── regular_alpha/ # AlphaSimulator, AlphaMachine, AlphaGenerator
+    ├── super_alpha/   # SuperAlphaSimulator, AlphaDyeing, SuperAlphaCreator
+    ├── correlation/   # AlphaCalcCorr (self/ppac/prod/self_web)
+    ├── message/       # Bark push notifications
+    └── competitions/  # Osmosis V1/V2/V3 toolkit
+```
+
+---
+
+## License
+
+MIT
+
+---
+
+## 概述
+
+`wqbkit` 是一个用于自动化 [WorldQuant Brain](https://www.worldquantbrain.com) 平台 Alpha 研究的 Python 工具包，覆盖 Alpha 全生命周期：模拟、评分、去相关、遗传迭代进化。
+
+### 核心功能
+
+| 模块 | 说明 |
+|------|------|
+| `AlphaDbCore` | WQB 认证、HTTP 封装、指数退避重试 |
+| `AlphaSimulator` | 多线程批量模拟调度器，队列式结果处理 |
+| `AlphaMachine` | 遗传迭代管线：剪枝、去重、下一代表达式工厂 |
+| `AlphaCalcCorr` | 多指标相关性引擎（self/ppac/prod/self_web），贪心最大独立集 |
+| `SuperAlphaSimulator` | SUPER 类型 Alpha 专用模拟器 |
+| `AlphaDyeing` | SUPER Alpha 构造与 combo 模板管理 |
+| `sc_send` | Bark (iOS) 推送通知，用于长时任务提醒 |
+
+### 快速开始
+
+```python
+from wqbkit import AlphaDbCore, AlphaCalcCorr, AlphaGenerator
+
+core = AlphaDbCore()
+calcor = AlphaCalcCorr()
+new_exprs = AlphaGenerator().second_order_factory("ts_mean(close, 20)", region="USA")
+```

wqbkit-0.2.5/__init__.py

@@ -0,0 +1,57 @@
+"""WorldQuant Brain Alpha Research Toolkit"""
+
+from wqbkit.app.config import PROJECT_ROOT
+from dotenv import load_dotenv
+
+# 显式加载项目根目录的 .env（适用于 editable install 模式）
+# load_dotenv 默认 override=False，不会覆盖已存在的环境变量
+_env_path = PROJECT_ROOT / ".env"
+if _env_path.exists():
+    load_dotenv(_env_path)
+else:
+    load_dotenv()
+
+__version__ = "0.2.5"
+
+# ---------- Public API ----------
+# 核心基础设施
+from wqbkit.app.core.alpha_base_core import AlphaBaseCore
+from wqbkit.app.core.alpha_db_core import AlphaDbCore
+
+# 数据模型
+from wqbkit.app.database import schemas
+
+# 业务模块
+from wqbkit.modules.correlation.alpha_calc_corr import AlphaCalcCorr
+from wqbkit.modules.regular_alpha.alpha_machine.alpha_generator import AlphaGenerator
+from wqbkit.modules.regular_alpha.alpha_machine.alpha_machine import AlphaMachine
+from wqbkit.modules.regular_alpha.alpha_simulator.alpha_simulator import AlphaSimulator
+from wqbkit.modules.super_alpha.alpha_dyeing import AlphaDyeing
+from wqbkit.modules.super_alpha.super_alpha_simulator import SuperAlphaSimulator
+from wqbkit.modules.message.alpha_message_sender import sc_send
+from wqbkit.modules.competitions.Osmosis.osmosis_selector_v3 import OsmosisAlphaSelectorV3
+from wqbkit.modules.competitions.Osmosis.osmosis_allocator_v3 import OsmosisAllocatorV3
+from wqbkit.modules.competitions.Osmosis.osmosis_clear_v3 import OsmosisClearV3
+from wqbkit.modules.competitions.Osmosis.osmosis_runner_v3 import OsmosisRunnerV3
+
+__all__ = [
+    "__version__",
+    # 核心
+    "AlphaBaseCore",
+    "AlphaDbCore",
+    # 数据模型
+    "schemas",
+    # 业务模块
+    "AlphaCalcCorr",
+    "AlphaGenerator",
+    "AlphaMachine",
+    "AlphaSimulator",
+    "AlphaDyeing",
+    "SuperAlphaSimulator",
+    "sc_send",
+    # Osmosis V3
+    "OsmosisAlphaSelectorV3",
+    "OsmosisAllocatorV3",
+    "OsmosisClearV3",
+    "OsmosisRunnerV3",
+]

wqbkit-0.2.5/app/config.py

@@ -0,0 +1,54 @@
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# 项目根目录（wqbkit/app/config.py -> app -> wqbkit -> root）
+PROJECT_ROOT: Path = Path(__file__).resolve().parents[2]
+DATA_DIR: Path = PROJECT_ROOT / "data"
+LOGS_DIR: Path = PROJECT_ROOT / "logs"
+
+
+class Config:
+    """应用配置，统一读取环境变量。"""
+
+    DB_HOST: str = os.getenv("DB_HOST", "localhost")
+    DB_PORT: str = os.getenv("DB_PORT", "5432")
+    DB_NAME: str = os.getenv("DB_NAME", "WorldQuant")
+    DB_USER: str = os.getenv("DB_USER", "postgres")
+    DB_PASSWORD: str = os.getenv("DB_PASSWORD", "")
+
+    WQB_USERNAME: str = os.getenv("WQB_USERNAME", "")
+    WQB_PASSWORD: str = os.getenv("WQB_PASSWORD", "")
+    WQB_API_BASE_URL: str = os.getenv("WQB_API_BASE_URL", "https://api.worldquantbrain.com")
+
+    LOG_LEVEL: str = os.getenv("LOG_LEVEL", "INFO")
+
+    MAX_RETRIES: int = int(os.getenv("MAX_RETRIES", "5"))
+    RETRY_DELAY_BASE: int = int(os.getenv("RETRY_DELAY_BASE", "2"))
+
+    BARK_KEY: str = os.getenv("BARK_KEY", "")
+    BARK_BASE_URL: str = os.getenv("BARK_BASE_URL", "https://api.day.app")
+
+    DEFAULT_CONSULTANT_DAY: str = os.getenv("DEFAULT_CONSULTANT_DAY", "2025-04-19")
+
+    # -------------------------------------------------------------------------
+    # 应用级统一常量（非 env，集中管理以避免跨模块重复硬编码）
+    # -------------------------------------------------------------------------
+    MAX_WORKERS: int = 10
+    TOTAL_SCORE: int = 100_000
+    DEFAULT_PAGE_LIMIT: int = 100
+    DEFAULT_PAGE_OFFSET: int = 0
+    DEFAULT_DYEING_WORKERS: int = 3
+
+    @property
+    def DATABASE_URI(self) -> str:
+        return (
+            f"postgresql://{self.DB_USER}:{self.DB_PASSWORD}"
+            f"@{self.DB_HOST}:{self.DB_PORT}/{self.DB_NAME}"
+        )
+
+
+config = Config()

wqbkit-0.2.5/app/core/__init__.py

@@ -0,0 +1,5 @@
+from .alpha_base_core import AlphaBaseCore
+from .alpha_db_core import AlphaDbCore
+from .decorators import retry_decorator
+from .wqb_urls import *
+