quantnodes 3.0.0__py3-none-any.whl

QuantNodes/research/quant_alpha/alpha158_design/few_shot_examples.py

@@ -0,0 +1,219 @@
+# coding=utf-8
+"""
+few_shot_examples.py - Alpha 158/360 few-shot 示例（用于 Alpha-GPT 启动 prompt）
+
+提供 5-10 个代表性特征示例（覆盖 4 类），供 M5+ 的 Alpha-GPT 路线使用。
+本 M3 PR 仅做示例定义。
+
+示例选样标准：
+- 覆盖 4 类（KBAR / Price / Volume / Rolling）
+- 简单 → 复杂
+- 经典 + 衍生
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class FewShotExample:
+    """Alpha 158/360 few-shot 示例"""
+    id: str  # 示例 ID (FX1-FX10)
+    name: str  # 简短名称
+    formula: str  # 公式
+    description: str  # 含义
+    category: str  # KBAR / Price / Volume / Rolling
+    operators_used: List[str]  # 使用的算子
+    qlib_ref: str  # Qlib 引用
+    alpha158_or_360: str = "alpha158"  # 属于哪个特征集
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+# ==============================================================================
+# 10 个精选 few-shot 示例（覆盖 4 类）
+# ==============================================================================
+
+
+ALPHA158_FEW_SHOT_EXAMPLES: List[FewShotExample] = [
+    # ============ KBAR (2 个) ============
+    FewShotExample(
+        id="FX1",
+        name="日内实体占比 KMID",
+        formula="(close - open) / open",
+        description=(
+            "今日实体（close-open）占开盘价的比例。"
+            "正值=阳线，负值=阴线。"
+            "Alpha 158 KBAR 特征第 1 个。"
+        ),
+        category="KBAR",
+        operators_used=["point"],
+        qlib_ref="$KMID",
+    ),
+    FewShotExample(
+        id="FX2",
+        name="日内振幅 KLEN",
+        formula="(high - low) / open",
+        description=(
+            "日内最高减最低的振幅除以开盘价。"
+            "捕捉日内波动率。"
+        ),
+        category="KBAR",
+        operators_used=["point"],
+        qlib_ref="$KLEN",
+    ),
+
+    # ============ Price (2 个) ============
+    FewShotExample(
+        id="FX3",
+        name="昨日开盘相对今日收盘",
+        formula="open.shift(1) / close",
+        description=(
+            "昨日开盘价 / 今日收盘价。"
+            "捕捉隔夜 gap 和当日走势。"
+        ),
+        category="Price",
+        operators_used=["ts_lag"],
+        qlib_ref="$OPEN1",
+    ),
+    FewShotExample(
+        id="FX4",
+        name="3 日前最高相对今日收盘",
+        formula="high.shift(3) / close",
+        description=(
+            "3 日前最高价 / 今日收盘价。"
+            "Alpha 158 Price 特征 4 字段 × 5 延迟中的一个。"
+        ),
+        category="Price",
+        operators_used=["ts_lag"],
+        qlib_ref="$HIGH3",
+    ),
+
+    # ============ Volume (1 个) ============
+    FewShotExample(
+        id="FX5",
+        name="3 日前成交量比",
+        formula="volume.shift(3) / (volume + 1e-12)",
+        description=(
+            "3 日前成交量 / 今日成交量。"
+            "Alpha 158 Volume 5 特征之一。"
+        ),
+        category="Volume",
+        operators_used=["ts_lag"],
+        qlib_ref="$VOLUME3",
+    ),
+
+    # ============ Rolling (5 个) ============
+    FewShotExample(
+        id="FX6",
+        name="20 日均线",
+        formula="close.rolling(20).mean()",
+        description=(
+            "20 日收盘价简单移动平均。"
+            "Alpha 158 Rolling MA 之一（25 op × 5 window = 125 MA 类特征）。"
+        ),
+        category="Rolling",
+        operators_used=["ts_mean"],
+        qlib_ref="$MA20",
+    ),
+    FewShotExample(
+        id="FX7",
+        name="20 日变化率 ROC",
+        formula="close / close.shift(20) - 1",
+        description=(
+            "20 日收益率：今日 close / 20 日前 close - 1。"
+            "Alpha 158 Rolling ROC 之一。"
+        ),
+        category="Rolling",
+        operators_used=["ts_lag"],
+        qlib_ref="$ROC20",
+    ),
+    FewShotExample(
+        id="FX8",
+        name="20 日波动率 STD",
+        formula="close.rolling(20).std()",
+        description=(
+            "20 日收盘价标准差（年化前需 × sqrt(252)）。"
+            "Alpha 158 Rolling STD 之一。"
+        ),
+        category="Rolling",
+        operators_used=["ts_std"],
+        qlib_ref="$STD20",
+    ),
+    FewShotExample(
+        id="FX9",
+        name="量价 20 日相关 CORR",
+        formula="close.rolling(20).corr(volume)",
+        description=(
+            "20 日量价滚动相关系数。"
+            "Alpha 158 Rolling CORR 之一。"
+            "量价同涨同跌为 +1，反向 -1。"
+        ),
+        category="Rolling",
+        operators_used=["ts_corr"],
+        qlib_ref="$CORR20",
+    ),
+    FewShotExample(
+        id="FX10",
+        name="20 日极值位置 IMAX",
+        formula="ts_argmax(high, 20)",
+        description=(
+            "20 日内最高价出现的位置（距今天数）。"
+            "值小（最近创新高）= 强动量。"
+            "Alpha 158 Rolling IMAX 之一。"
+        ),
+        category="Rolling",
+        operators_used=["ts_argmax"],
+        qlib_ref="$IMAX20",
+    ),
+]
+
+
+# ==============================================================================
+# 辅助函数
+# ==============================================================================
+
+
+def list_examples(category: Optional[str] = None) -> List[FewShotExample]:
+    """列出所有示例（可按 category 过滤）"""
+    if category is None:
+        return list(ALPHA158_FEW_SHOT_EXAMPLES)
+    return [e for e in ALPHA158_FEW_SHOT_EXAMPLES if e.category == category]
+
+
+def get_example(example_id: str) -> Optional[FewShotExample]:
+    """按 ID 查示例"""
+    for e in ALPHA158_FEW_SHOT_EXAMPLES:
+        if e.id == example_id:
+            return e
+    return None
+
+
+def get_few_shot_prompt(
+    n: int = 5,
+    category: Optional[str] = None,
+) -> str:
+    """构造 few-shot prompt（用于 Alpha-GPT 启动 prompt）
+
+    Args:
+        n: 示例数量
+        category: 可选 category 过滤
+
+    Returns:
+        多行字符串，每行一个示例
+    """
+    examples = list_examples(category)[:n]
+    lines = []
+    for e in examples:
+        lines.append(
+            f"# {e.id} {e.name} [{e.category}]\n"
+            f"formula: {e.formula}\n"
+            f"description: {e.description}\n"
+        )
+    return "\n".join(lines)
+
+
+def get_categories() -> List[str]:
+    """获取所有 category"""
+    return list(set(e.category for e in ALPHA158_FEW_SHOT_EXAMPLES))

QuantNodes/research/quant_alpha/alpha158_design/philosophy.py

@@ -0,0 +1,240 @@
+# coding=utf-8
+"""
+philosophy.py - Alpha 158/360 特征设计哲学 + 4 类模板
+
+vs 直接移植 158/360 公式：本文件**仅做借鉴**，提取：
+- 4 类特征的设计哲学（KBAR / Price / Volume / Rolling）
+- 每类的公式模板（参数化）
+- 类别间的依赖关系
+
+参考：
+- Yang, X. et al. (2020). "Qlib." arXiv:2009.11189
+- qlib.contrib.data.handler.Alpha158/Alpha360
+- WeChat article: 四大量化因子库
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+# 默认窗口
+DEFAULT_WINDOWS = [5, 10, 20, 30, 60]
+
+# Alpha 360 默认 lookback 范围
+ALPHA360_LOOKBACK_RANGE = list(range(60))  # 0-59
+
+
+@dataclass
+class CategoryTemplate:
+    """特征类别的设计模板
+
+    Attributes:
+        name: 类别名
+        total_features: 该类别的特征总数（Alpha 158 子集）
+        philosophy: 设计哲学描述
+        formula_template: 公式模板（含 {field} / {window} 等占位符）
+        parameters: 可调参数
+        examples: 几个公式示例
+        category_id: 类别 ID
+    """
+    category_id: str  # KBAR / Price / Volume / Rolling
+    name: str
+    total_features: int
+    philosophy: str
+    formula_template: str
+    parameters: Dict[str, List[Any]] = field(default_factory=dict)
+    examples: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+# ==============================================================================
+# 4 类特征模板（Alpha 158）
+# ==============================================================================
+
+FEATURE_CATEGORIES: List[CategoryTemplate] = [
+    CategoryTemplate(
+        category_id="KBAR",
+        name="K线形态",
+        total_features=9,
+        philosophy=(
+            "KBAR 特征捕捉单根 K 线的几何信息（实体长度、上下影线、价格重心）。"
+            "所有 KBAR 特征都做归一化（除以 open 或 high-low 振幅），"
+            "消除价格水平影响。"
+        ),
+        formula_template=(
+            # 单根 K 线的几何特征
+            "({expr}) / {denominator}"
+        ),
+        parameters={
+            "denominator": ["open", "$close - $open + 1e-12", "high - low + 1e-12"],
+        },
+        examples=[
+            "KMID = (close - open) / open",  # 实体占比
+            "KLEN = (high - low) / open",  # 振幅
+            "KMID2 = (close - open) / ((high - low) + 1e-12)",  # 实体占振幅
+            "KSFT = (2 * close - high - low) / open",  # 重心偏移
+            "KUP = (high - max(open, close)) / open",  # 上影线
+            "KLOW = (min(open, close) - low) / open",  # 下影线
+        ],
+        metadata={"qlib": "KBAR", "factors": 9},
+    ),
+    CategoryTemplate(
+        category_id="Price",
+        name="价格时序",
+        total_features=20,
+        philosophy=(
+            "Price 特征是历史价格相对当前价格的归一化值。"
+            "形式：Ref($field, d) / $close，field ∈ {OPEN, HIGH, LOW, VWAP}，"
+            "d ∈ {0, 1, 2, 3, 4}。4 字段 × 5 延迟 = 20 特征。"
+            "无截面算子（pure time-series）。"
+        ),
+        formula_template="Ref({field}, {delay}) / $close",
+        parameters={
+            "field": ["open", "high", "low", "vwap"],
+            "delay": [0, 1, 2, 3, 4],
+        },
+        examples=[
+            "OPEN0 = open / close",  # 今日开盘 / 今日收盘
+            "OPEN1 = open.shift(1) / close",  # 昨日开盘 / 今日收盘
+            "HIGH0 = high / close",
+            "LOW0 = low / close",
+            "VWAP0 = vwap / close",
+        ],
+        metadata={"qlib": "Price", "factors": 20},
+    ),
+    CategoryTemplate(
+        category_id="Volume",
+        name="成交量时序",
+        total_features=5,
+        philosophy=(
+            "Volume 特征是历史成交量相对当前成交量的比值。"
+            "形式：Ref($volume, d) / ($volume + 1e-12)，d ∈ {0, 1, 2, 3, 4}。"
+            "捕捉量能变化：d=0 是今日成交；d=1-4 是历史成交。"
+        ),
+        formula_template="Ref({field}, {delay}) / ({field} + 1e-12)",
+        parameters={
+            "field": ["volume"],
+            "delay": [0, 1, 2, 3, 4],
+        },
+        examples=[
+            "VOL0 = volume / (volume + 1e-12)",  # 今日量 / 今日量 ≈ 1
+            "VOL1 = volume.shift(1) / (volume + 1e-12)",  # 昨日量 / 今日量
+            "VOL2 = volume.shift(2) / (volume + 1e-12)",
+        ],
+        metadata={"qlib": "Volume", "factors": 5},
+    ),
+    CategoryTemplate(
+        category_id="Rolling",
+        name="滚动统计",
+        total_features=124,
+        philosophy=(
+            "Rolling 特征是 25 种统计指标 × 5 个时间窗口（5/10/20/30/60）的笛卡尔积。"
+            "统计指标：ROC, MA, STD, BETA(Slope), RSQR, RESI, MAX, MIN, QTLU, QTLD, "
+            "RANK, RSV, IMAX, IMIN, IMXD, CORR, CORD, CNTP, CNTN, SUMP, SUMN, "
+            "VMA, VSTD, WVMA, VSUMP, VSUMN。"
+            "这些特征可同时喂给 LightGBM/XGBoost/LSTM 等 ML 模型。"
+        ),
+        formula_template=(
+            "rolling_{op}({field}, {window})"
+        ),
+        parameters={
+            "op": [
+                "roc",      # 变化率: close / lag(close, w) - 1
+                "ma",       # 移动平均
+                "std",      # 标准差
+                "beta",     # 斜率（回归系数）
+                "rsqr",     # R²
+                "resi",     # 残差
+                "max",      # 最大值
+                "min",      # 最小值
+                "qtlu",     # 上分位数（0.7）
+                "qtld",     # 下分位数（0.3）
+                "rank",     # 滚动 rank
+                "rsv",      # RSV (类 KDJ 随机指标)
+                "imax",     # argmax 位置
+                "imin",     # argmin 位置
+                "imxd",     # argmax - argmin
+                "corr",     # 相关（双字段）
+                "cntp",     # count positive
+                "cntn",     # count negative
+                "sump",     # sum positive
+                "sumn",     # sum negative
+                "vma",      # 量能 MA
+                "vstd",     # 量能 std
+                "wvma",     # weighted VMA
+                "vsump",    # 量能 sum positive
+                "vsumn",    # 量能 sum negative
+            ],
+            "window": [5, 10, 20, 30, 60],
+            "field": ["close", "open", "high", "low", "vwap", "volume"],
+        },
+        examples=[
+            "ROC(close, 5) = close / close.shift(5) - 1",
+            "MA(close, 20) = close.rolling(20).mean()",
+            "STD(close, 20) = close.rolling(20).std()",
+            "BETA(close, volume, 20) = rolling_beta(close, volume, 20)",
+            "CORR(close, volume, 20) = rolling_corr(close, volume, 20)",
+            "CNTP(close, 20) = count(close > close.shift(1), 20)",
+            "IMAX(high, 30) = argmax(high, 30)",
+        ],
+        metadata={"qlib": "Rolling", "factors": 124, "ops": 25, "windows": 5},
+    ),
+]
+
+
+# ==============================================================================
+# Alpha 360 模板
+# ==============================================================================
+
+
+@dataclass
+class Alpha360Template:
+    """Alpha 360 模板（6 字段 × 60 lookback = 360 特征）"""
+    fields: List[str] = field(default_factory=lambda: ["close", "open", "high", "low", "vwap", "volume"])
+    lookback_range: List[int] = field(default_factory=lambda: list(range(60)))
+    total_features: int = 360
+    philosophy: str = (
+        "Alpha 360 把 6 个原始字段在 60 个 lookback 时间步上的值作为特征。"
+        "价格字段除以当日 close 归一化，成交量字段除以当日成交量归一化。"
+        "形成 (60, 6) 的二维矩阵，天然适合序列深度学习模型（GRU/LSTM/Transformer）。"
+    )
+
+    def formula_template(self) -> str:
+        """公式模板"""
+        return "Ref({field}, {delay}) / {denominator}"
+
+
+ALPHA360_TEMPLATE = Alpha360Template()
+
+
+# ==============================================================================
+# 辅助函数
+# ==============================================================================
+
+
+def get_template_by_category(category_id: str) -> Optional[CategoryTemplate]:
+    """按 category_id 查模板"""
+    for t in FEATURE_CATEGORIES:
+        if t.category_id == category_id:
+            return t
+    return None
+
+
+def get_template_by_name(name: str) -> Optional[CategoryTemplate]:
+    """按 name 查模板"""
+    for t in FEATURE_CATEGORIES:
+        if t.name == name:
+            return t
+    return None
+
+
+def list_categories() -> List[str]:
+    """列出所有 category_id"""
+    return [t.category_id for t in FEATURE_CATEGORIES]
+
+
+def total_feature_count() -> int:
+    """Alpha 158 总特征数（=158）"""
+    return sum(t.total_features for t in FEATURE_CATEGORIES)

QuantNodes/research/quant_alpha/evaluation/__init__.py

@@ -0,0 +1,47 @@
+# coding=utf-8
+"""Table 4 复现的 evaluation 子包
+
+Stage 1 mock + Stage 2 real 复用同一接口契约（contracts.py）。
+
+主要组件：
+- contracts.py：4 dataclass + 4 ABC（接口契约）
+- mock_data_loader.py：Stage 1 500 票 GBM 数据生成
+- clickhouse_data_loader.py：Stage 2 ClickHouse 数据加载
+- evaluators/polars_evaluator.py：基于 alpha_evaluate tool 的 PolarsEvaluator
+- baselines/g1_handcrafted.py：动态从 OperatorVocab 生成 100 公式
+- baselines/g2_llm_only.py：LLM 直接生成公式 (mock / 真实)
+- baselines/g3_alpha_gpt.py：包 AlphaGptWorkflow（M5）
+- runner.py：MockTable4Runner + RealTable4Runner 主入口
+"""
+
+from .contracts import (
+    Baseline,
+    DataLoader,
+    Evaluator,
+    FactorMetrics,
+    FactorSpec,
+    Table4GroupResult,
+    Table4Report,
+    Table4Runner,
+)
+from .evaluators import PolarsAlphaCalculatorEvaluator
+from .mock_data_loader import MOCK_INDUSTRIES, MockDataLoader
+from .clickhouse_data_loader import ClickHouseDataLoader
+from .runner import MockTable4Runner, RealTable4Runner
+
+__all__ = [
+    "DataLoader",
+    "Evaluator",
+    "Baseline",
+    "Table4Runner",
+    "FactorSpec",
+    "FactorMetrics",
+    "Table4GroupResult",
+    "Table4Report",
+    "PolarsAlphaCalculatorEvaluator",
+    "MockDataLoader",
+    "ClickHouseDataLoader",
+    "MockTable4Runner",
+    "RealTable4Runner",
+    "MOCK_INDUSTRIES",
+]

QuantNodes/research/quant_alpha/evaluation/baselines/__init__.py

@@ -0,0 +1,8 @@
+# coding=utf-8
+"""Baselines 子包（G1 / G2 / G3）"""
+
+from .g1_handcrafted import G1Handcrafted
+from .g2_llm_only import G2LlmOnly
+from .g3_alpha_gpt import G3AlphaGpt
+
+__all__ = ["G1Handcrafted", "G2LlmOnly", "G3AlphaGpt"]

QuantNodes/research/quant_alpha/evaluation/baselines/g1_handcrafted.py

@@ -0,0 +1,135 @@
+# coding=utf-8
+"""
+g1_handcrafted.py - G1 baseline：动态从 OperatorVocab 生成 100 个手工公式
+
+G1 = "手工构造（Handcrafted）"，代表 101/158 等论文公开的算子组合。
+Stage 1 动态生成（不硬编码），从 OperatorVocab 抽取合法组合。
+
+为什么动态生成：
+- 避免硬编码 100 公式导致难以维护
+- OperatorVocab 已注册 162 算子（M1），动态组合可生成大量候选
+- 与 G2（mock LLM 直接生成）和 G3（AlphaGptWorkflow）形成对照
+
+公式生成规则（仅限 alpha_evaluate tool 支持的算子）：
+- 字段：close / vol / amount
+- 时间窗口：ts_mean / ts_std / delta（window ∈ {3, 5, 10, 20}）
+- 二元组合：Add / Sub / Mul / Div
+- 一元：abs / log / sign / neg
+- 嵌套深度 ≤ 2
+"""
+
+from __future__ import annotations
+
+import logging
+import random
+from typing import List, Optional
+
+from ..contracts import Baseline, FactorSpec
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["G1Handcrafted"]
+
+
+FIELDS = ["close", "vol", "amount"]
+WINDOWS = [3, 5, 10, 20]
+TIME_OPS = ["ts_mean", "ts_std", "delta"]
+CROSS_OPS = ["abs", "log", "sign", "sqrt"]
+BINARY_OPS = ["Add", "Sub", "Mul", "Div"]
+
+
+def _gen_leaf(rng: random.Random) -> str:
+    """生成叶子节点：字段或字段上的时间窗口算子"""
+    field = rng.choice(FIELDS)
+    if rng.random() < 0.7:  # 70% 包时间窗口
+        op = rng.choice(TIME_OPS)
+        window = rng.choice(WINDOWS)
+        return f"{op}({field}, {window})"
+    return field
+
+
+def _gen_formula(rng: random.Random, max_depth: int = 2) -> str:
+    """生成一条公式字符串"""
+    leaf_left = _gen_leaf(rng)
+    leaf_right = _gen_leaf(rng)
+
+    # 50% 应用 cross-sectional 算子
+    if rng.random() < 0.3:
+        cross = rng.choice(CROSS_OPS)
+        leaf_left = f"{cross}({leaf_left})"
+
+    if max_depth <= 1 or rng.random() < 0.6:
+        # 单层
+        if rng.random() < 0.5:
+            return leaf_left
+        op = rng.choice(BINARY_OPS)
+        return f"{op}({leaf_left}, {leaf_right})"
+    else:
+        # 双层嵌套
+        op1 = rng.choice(BINARY_OPS)
+        op2 = rng.choice(BINARY_OPS)
+        leaf3 = _gen_leaf(rng)
+        return f"{op1}({op2}({leaf_left}, {leaf_right}), {leaf3})"
+
+
+class G1Handcrafted(Baseline):
+    """G1 Handcrafted baseline
+
+    从 OperatorVocab 动态组合生成 n 个手工因子。
+    Stage 1 与 Stage 2 共用（不依赖数据 / LLM）。
+    """
+
+    def __init__(self, n: int = 100, seed: int = 42) -> None:
+        self.n = n
+        self.seed = seed
+
+    @property
+    def group_name(self) -> str:
+        return "G1_Handcrafted"
+
+    def generate_factors(self, n: Optional[int] = None) -> List[FactorSpec]:
+        """动态生成 n 个因子（formula_id 唯一）"""
+        n = n or self.n
+        rng = random.Random(self.seed)
+
+        factors: List[FactorSpec] = []
+        seen_formulas: set = set()
+
+        attempts = 0
+        while len(factors) < n and attempts < n * 5:
+            attempts += 1
+            formula = _gen_formula(rng)
+            if formula in seen_formulas:
+                continue
+            seen_formulas.add(formula)
+
+            category = self._infer_category(formula)
+            factors.append(
+                FactorSpec(
+                    formula_id=f"G1_{len(factors):03d}",
+                    formula=formula,
+                    source="g1_handcrafted",
+                    category=category,
+                    complexity=formula.count("("),
+                    meta={"seed": self.seed},
+                )
+            )
+
+        logger.info(
+            "[G1] generated %d factors (attempts=%d)", len(factors), attempts
+        )
+        return factors
+
+    @staticmethod
+    def _infer_category(formula: str) -> str:
+        if "ts_mean" in formula and "delta" not in formula:
+            return "momentum"
+        if "delta" in formula:
+            return "momentum"
+        if "ts_std" in formula:
+            return "volatility"
+        if "vol" in formula:
+            return "volume"
+        if "abs" in formula:
+            return "reversal"
+        return "value"