quantnodes 3.0.0__py3-none-any.whl

QuantNodes/research/quant_alpha/adapters/expression.py

@@ -0,0 +1,387 @@
+# coding=utf-8
+"""
+adapters/expression.py - 极简 Expression AST（AlphaGen 兼容子集）
+
+AlphaGen (KDD 2023) 使用 token 化的 Expression AST 表示因子公式。
+本模块提供极简子集，足以让 PolarsAlphaCalculator 正常工作。
+
+完整的 AlphaGen Expression 包含 ~22 个算子：
+    Ref, Add, Sub, Mul, Div, Greater, Less, Neg, Abs, Log, Sign, Sqrt,
+    Mean, Std, Var, Skew, Kurt, Max, Min, Sum, Med, Mad,
+    Rank, Delta, Quantile, Condition, ...
+
+本子集（11 个）覆盖 AlphaGen 80% 用例：
+    - Feature: 引用基础字段
+    - Ref: 时序滞后
+    - BinaryOp (Add/Sub/Mul/Div/Greater/Less)
+    - UnaryOp (Abs/Neg/Log/Sign/Sqrt)
+    - RollingOp (Mean/Std/Sum/Max/Min/Skew/Kurt/Med/Rank/Delta)
+
+对未覆盖的算子，PolarsAlphaCalculator.expression_to_formula() 会
+fallback 到通用算子映射。
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, List, Optional, Union
+
+
+class Expression(ABC):
+    """因子表达式抽象基类
+
+    所有 Expression 必须实现：
+    - to_string(): 转为 QuantNodes 公式字符串（给 OperatorVocab）
+    - children: 子表达式列表（用于递归遍历）
+    """
+
+    @abstractmethod
+    def to_string(self) -> str:
+        """转为 QuantNodes 公式字符串
+
+        Returns:
+            公式字符串（如 "close - close.shift(5)"）
+        """
+        raise NotImplementedError
+
+    @property
+    @abstractmethod
+    def children(self) -> List["Expression"]:
+        """子表达式列表"""
+        raise NotImplementedError
+
+    def __repr__(self) -> str:
+        return f"Expr({self.to_string()})"
+
+
+# ==============================================================================
+# 基础表达式
+# ==============================================================================
+
+
+class Feature(Expression):
+    """基础字段引用：$close, $open, $high, $low, $vwap, $volume
+
+    Examples:
+        Feature("close")  # → "$close" / "close"
+    """
+    def __init__(self, field: str):
+        self.field = field
+
+    def to_string(self) -> str:
+        return self.field
+
+    @property
+    def children(self) -> List[Expression]:
+        return []
+
+
+class Literal(Expression):
+    """字面量值
+
+    Examples:
+        Literal(1e-12)  # → "1e-12"
+        Literal(0.5)     # → "0.5"
+    """
+    def __init__(self, value: Union[int, float]):
+        self.value = value
+
+    def to_string(self) -> str:
+        # 整数直接显示，浮点保留精度
+        if isinstance(self.value, int) or (
+            isinstance(self.value, float) and self.value.is_integer()
+        ):
+            return str(int(self.value))
+        return repr(self.value)
+
+    @property
+    def children(self) -> List[Expression]:
+        return []
+
+
+def _to_expr(x: Any) -> Expression:
+    """自动把字面量转 Expression"""
+    if isinstance(x, Expression):
+        return x
+    if isinstance(x, (int, float)):
+        return Literal(x)
+    raise TypeError(f"Cannot convert {type(x).__name__} to Expression")
+
+
+class Ref(Expression):
+    """时序滞后：Ref($close, 5) = 5 日前 close
+
+    Examples:
+        Ref(Feature("close"), 5)  # → "close.shift(5)"
+    """
+    def __init__(self, expr: Expression, lag: int):
+        self.expr = expr
+        self.lag = lag
+
+    def to_string(self) -> str:
+        return f"{self.expr.to_string()}.shift({self.lag})"
+
+    @property
+    def children(self) -> List[Expression]:
+        return [self.expr]
+
+
+# ==============================================================================
+# 二元操作
+# ==============================================================================
+
+
+class BinaryOp(Expression):
+    """二元操作：add, sub, mul, div, gt, lt, signedpower"""
+    _OP_MAP = {
+        "add": "+",
+        "sub": "-",
+        "mul": "*",
+        "div": "/",
+        "gt": ">",
+        "lt": "<",
+        "signedpower": "**",
+    }
+
+    def __init__(self, left, right, op: str):
+        if op not in self._OP_MAP:
+            raise ValueError(
+                f"Unsupported op: {op}. Supported: {list(self._OP_MAP.keys())}"
+            )
+        self.left = _to_expr(left)
+        self.right = _to_expr(right)
+        self.op = op
+
+    def to_string(self) -> str:
+        symbol = self._OP_MAP[self.op]
+        return f"({self.left.to_string()} {symbol} {self.right.to_string()})"
+
+    @property
+    def children(self) -> List[Expression]:
+        return [self.left, self.right]
+
+
+# 便捷构造（接受 Expression 或字面量）
+def Add(left, right) -> BinaryOp:
+    return BinaryOp(left, right, "add")
+
+
+def Sub(left, right) -> BinaryOp:
+    return BinaryOp(left, right, "sub")
+
+
+def Mul(left, right) -> BinaryOp:
+    return BinaryOp(left, right, "mul")
+
+
+def Div(left, right) -> BinaryOp:
+    return BinaryOp(left, right, "div")
+
+
+def Greater(left, right) -> BinaryOp:
+    return BinaryOp(left, right, "gt")
+
+
+def Less(left, right) -> BinaryOp:
+    return BinaryOp(left, right, "lt")
+
+
+# ==============================================================================
+# 一元操作
+# ==============================================================================
+
+
+class UnaryOp(Expression):
+    """一元操作：abs, neg, log, sign, sqrt, rank, zscore, winsorize"""
+    _OP_MAP = {
+        "abs": "abs",
+        "neg": "-",  # 一元负号特殊处理
+        "log": "log",
+        "sign": "sign",
+        "sqrt": "sqrt",
+        "rank": "rank",
+        "zscore": "zscore",
+        "winsorize": "winsorize",
+    }
+
+    def __init__(self, expr, op: str):
+        if op not in self._OP_MAP:
+            raise ValueError(
+                f"Unsupported op: {op}. Supported: {list(self._OP_MAP.keys())}"
+            )
+        self.expr = _to_expr(expr)
+        self.op = op
+
+    def to_string(self) -> str:
+        op_str = self._OP_MAP[self.op]
+        if self.op == "neg":
+            return f"(-{self.expr.to_string()})"
+        return f"{op_str}({self.expr.to_string()})"
+
+    @property
+    def children(self) -> List[Expression]:
+        return [self.expr]
+
+
+# 便捷构造
+def Abs(expr: Expression) -> UnaryOp:
+    return UnaryOp(expr, "abs")
+
+
+def Neg(expr: Expression) -> UnaryOp:
+    return UnaryOp(expr, "neg")
+
+
+def Log(expr: Expression) -> UnaryOp:
+    return UnaryOp(expr, "log")
+
+
+def Sign(expr: Expression) -> UnaryOp:
+    return UnaryOp(expr, "sign")
+
+
+def Sqrt(expr: Expression) -> UnaryOp:
+    return UnaryOp(expr, "sqrt")
+
+
+def Rank(expr: Expression) -> UnaryOp:
+    return UnaryOp(expr, "rank")
+
+
+def Zscore(expr: Expression) -> UnaryOp:
+    return UnaryOp(expr, "zscore")
+
+
+def Winsorize(expr: Expression) -> UnaryOp:
+    return UnaryOp(expr, "winsorize")
+
+
+def Rank(expr: Expression) -> UnaryOp:
+    return UnaryOp(expr, "rank")
+
+
+def Zscore(expr: Expression) -> UnaryOp:
+    return UnaryOp(expr, "zscore")
+
+
+def Winsorize(expr: Expression) -> UnaryOp:
+    return UnaryOp(expr, "winsorize")
+
+
+# ==============================================================================
+# 滚动操作
+# ==============================================================================
+
+
+class RollingOp(Expression):
+    """滚动操作：mean, std, var, max, min, sum, skew, kurt, median, rank, delta, corr, cov
+
+    Examples:
+        RollingOp(Feature("close"), window=20, op="mean")
+        # → "ts_mean(close, 20)"
+    """
+    _OP_MAP = {
+        "mean": "ts_mean",
+        "std": "ts_std",
+        "var": "ts_var",
+        "max": "ts_max",
+        "min": "ts_min",
+        "sum": "ts_sum",
+        "skew": "ts_skew",
+        "kurt": "ts_kurt",
+        "median": "ts_median",
+        "rank": "ts_rank",
+        "delta": "ts_delta",
+        "corr": "ts_corr",
+        "cov": "ts_cov",
+    }
+
+    def __init__(self, expr, window: int, op: str):
+        if op not in self._OP_MAP:
+            raise ValueError(
+                f"Unsupported rolling op: {op}. "
+                f"Supported: {list(self._OP_MAP.keys())}"
+            )
+        self.expr = _to_expr(expr)
+        self.window = window
+        self.op = op
+
+    def to_string(self) -> str:
+        func = self._OP_MAP[self.op]
+        return f"{func}({self.expr.to_string()}, {self.window})"
+
+    @property
+    def children(self) -> List[Expression]:
+        return [self.expr]
+
+
+# 便捷构造
+def Mean(expr: Expression, window: int) -> RollingOp:
+    return RollingOp(expr, window, "mean")
+
+
+def Std(expr: Expression, window: int) -> RollingOp:
+    return RollingOp(expr, window, "std")
+
+
+def Sum(expr: Expression, window: int) -> RollingOp:
+    return RollingOp(expr, window, "sum")
+
+
+def Max(expr: Expression, window: int) -> RollingOp:
+    return RollingOp(expr, window, "max")
+
+
+def Min(expr: Expression, window: int) -> RollingOp:
+    return RollingOp(expr, window, "min")
+
+
+def Delta(expr: Expression, window: int) -> RollingOp:
+    return RollingOp(expr, window, "delta")
+
+
+# ==============================================================================
+# 工具函数
+# ==============================================================================
+
+
+def expression_to_formula(expr: Expression) -> str:
+    """便利函数：Expression → 公式字符串
+
+    Args:
+        expr: Expression 对象
+
+    Returns:
+        QuantNodes 公式字符串
+    """
+    return expr.to_string()
+
+
+def collect_feature_fields(expr: Expression) -> List[str]:
+    """递归收集表达式中所有 Feature 字段"""
+    fields: List[str] = []
+
+    def _walk(e: Expression) -> None:
+        if isinstance(e, Feature):
+            if e.field not in fields:
+                fields.append(e.field)
+        for child in e.children:
+            _walk(child)
+
+    _walk(expr)
+    return fields
+
+
+def collect_rolling_windows(expr: Expression) -> List[int]:
+    """递归收集表达式中所有 RollingOp 的窗口"""
+    windows: List[int] = []
+
+    def _walk(e: Expression) -> None:
+        if isinstance(e, RollingOp):
+            if e.window not in windows:
+                windows.append(e.window)
+        for child in e.children:
+            _walk(child)
+
+    _walk(expr)
+    return windows

QuantNodes/research/quant_alpha/alpha101_design/__init__.py

@@ -0,0 +1,50 @@
+# coding=utf-8
+"""
+alpha101_design - Alpha 101 设计哲学借鉴（M3 PR）
+
+Alpha 101 (Kakushadze 2015, arXiv:1601.00991) 提供了 101 个公式化 alpha
+因子的设计范式。本子包**借鉴其设计哲学**而非直接移植公式集
+（实际因子集由 llmwikify 在他处生成）。
+
+内容：
+- DESIGN_PHILOSOPHY: Alpha 101 核心设计原则（8 条）
+- CORE_OPERATORS: 10-20 个核心算子子集（经济意义）
+- FEW_SHOT_EXAMPLES: 5-10 个示例公式（用于 Alpha-GPT 启动 prompt）
+
+M3 范围：仅做借鉴（设计文档 + few-shot）。
+完整因子集实现 → 路线 6 (Alpha-GPT) 阶段。
+"""
+
+from __future__ import annotations
+
+from QuantNodes.research.quant_alpha.alpha101_design.philosophy import (
+    DESIGN_PHILOSOPHY,
+    CORE_OPERATORS,
+    A_SHARE_COMPATIBILITY,
+    get_philosophy_by_id,
+    get_operator_by_name,
+    get_a_share_compatible_count,
+)
+from QuantNodes.research.quant_alpha.alpha101_design.few_shot_examples import (
+    ALPHA101_FEW_SHOT_EXAMPLES,
+    list_examples,
+    get_example,
+    get_few_shot_prompt,
+    get_categories,
+)
+
+__all__ = [
+    # 设计哲学
+    "DESIGN_PHILOSOPHY",
+    "CORE_OPERATORS",
+    "A_SHARE_COMPATIBILITY",
+    "get_philosophy_by_id",
+    "get_operator_by_name",
+    "get_a_share_compatible_count",
+    # few-shot 示例
+    "ALPHA101_FEW_SHOT_EXAMPLES",
+    "list_examples",
+    "get_example",
+    "get_few_shot_prompt",
+    "get_categories",
+]

QuantNodes/research/quant_alpha/alpha101_design/few_shot_examples.py

@@ -0,0 +1,243 @@
+# coding=utf-8
+"""
+few_shot_examples.py - Alpha 101 few-shot 示例（用于 Alpha-GPT 启动 prompt）
+
+提供 5-10 个代表性公式示例，供 M5+ 的 Alpha-GPT 路线使用。
+本 M3 PR 仅做示例定义，不做实际评估（评估由 Alpha-GPT 路线完成）。
+
+示例选样标准：
+- 覆盖 8 条设计原则
+- 覆盖 16 个核心算子
+- A 股可移植（避开 Delay-0）
+- 复杂度从简单（1-2 算子）到复杂（5+ 算子）
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class FewShotExample:
+    """Alpha 101 few-shot 示例"""
+    id: str  # 示例 ID (EX1-EX10)
+    name: str  # 简短名称
+    formula: str  # 公式
+    description: str  # 含义
+    category: str  # momentum / reversal / volume_price / volatility / intraday
+    design_principles: List[str]  # 引用的设计原则 ID (P1-P8)
+    operators_used: List[str]  # 使用的核心算子
+    alpha101_ref: str  # Alpha 101 #N 引用
+    a_share_compatible: bool = True
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+# ==============================================================================
+# 10 个精选 few-shot 示例
+# ==============================================================================
+
+ALPHA101_FEW_SHOT_EXAMPLES: List[FewShotExample] = [
+    # ============ 简单示例（1-2 算子）============
+    FewShotExample(
+        id="EX1",
+        name="日内动量",
+        formula="(close - open) / ((high - low) + 0.001)",
+        description=(
+            "日内收益率除以日内振幅。"
+            "衡量收盘相对开盘的优势，结合日内波动率标准化。"
+            "值越大表示日内动量越强。"
+        ),
+        category="intraday",
+        design_principles=["P1", "P2"],
+        operators_used=["point:pointwise"],
+        alpha101_ref="#101",
+        a_share_compatible=True,
+    ),
+    FewShotExample(
+        id="EX2",
+        name="截面动量（5 日）",
+        formula="rank(close / ts_lag(close, 5) - 1)",
+        description=(
+            "5 日动量做截面 rank。"
+            "捕捉过去 5 天涨幅最大的股票，趋势跟随策略。"
+        ),
+        category="momentum",
+        design_principles=["P2", "P3"],
+        operators_used=["ts_lag", "rank"],
+        alpha101_ref="#N/A",
+        a_share_compatible=True,
+    ),
+    FewShotExample(
+        id="EX3",
+        name="量价背离",
+        formula="-1 * ts_corr(open, vol, 10)",
+        description=(
+            "开盘价与成交量的 10 日滚动相关系数取负。"
+            "捕捉量价背离现象：股价涨但成交量不增时，预示反转。"
+        ),
+        category="volume_price",
+        design_principles=["P2", "P8"],
+        operators_used=["ts_corr"],
+        alpha101_ref="#6",
+        a_share_compatible=True,
+    ),
+
+    # ============ 中等示例（3-4 算子）============
+    FewShotExample(
+        id="EX4",
+        name="Alpha 101 #1 简化版",
+        formula="rank(ts_argmax(signedpower(close, 2), 5)) - 0.5",
+        description=(
+            "5 日内 close² 最大值出现的位置做截面 rank 并居中。"
+            "极端值在最近 = 强动量；5 天前 = 弱动量。"
+            "体现了 signedpower 保留符号 + argmax 提取位置的核心思想。"
+        ),
+        category="momentum",
+        design_principles=["P3", "P4", "P5"],
+        operators_used=["rank", "ts_argmax", "signedpower"],
+        alpha101_ref="#1 (简化版)",
+        a_share_compatible=True,
+    ),
+    FewShotExample(
+        id="EX5",
+        name="量增价跌反转",
+        formula="sign(ts_delta(vol, 1)) * (-1 * ts_delta(close, 1))",
+        description=(
+            "量增 + 价跌 = -1（卖出信号）。"
+            "量缩 + 价涨 = +1（买入信号）。"
+            "其他情况 = 0（无信号）。"
+            "这是 Alpha 101 #12 完整版。"
+        ),
+        category="volume_price",
+        design_principles=["P1", "P2"],
+        operators_used=["sign", "ts_delta"],
+        alpha101_ref="#12",
+        a_share_compatible=True,
+    ),
+    FewShotExample(
+        id="EX6",
+        name="波动率加权动量",
+        formula="rank(ts_mean(close, 8) - ts_mean(close, 21) + ts_std(close, 8))",
+        description=(
+            "8 日均线相对 21 日均线的偏离度，加上 8 日波动率。"
+            "高偏离 + 高波动 = 强动量或反转信号。"
+            "（Alpha 101 #21 简化版）"
+        ),
+        category="momentum",
+        design_principles=["P1", "P3"],
+        operators_used=["rank", "ts_mean", "ts_std"],
+        alpha101_ref="#21 (简化版)",
+        a_share_compatible=True,
+    ),
+
+    # ============ 复杂示例（5+ 算子）============
+    FewShotExample(
+        id="EX7",
+        name="波动率反转（ArgMax 提取）",
+        formula="rank(ts_argmax(signedpower(close, 2), 5) - ts_argmax(signedpower(close, 2), 20))",
+        description=(
+            "5 日 vs 20 日的 signedpower 极值位置差。"
+            "差值大 = 最近 5 日的极值更新（趋势延续或反转）。"
+            "差值小 = 20 日前就有极值（趋势已成熟）。"
+        ),
+        category="reversal",
+        design_principles=["P3", "P4", "P5"],
+        operators_used=["rank", "ts_argmax", "signedpower"],
+        alpha101_ref="#N/A (派生)",
+        a_share_compatible=True,
+    ),
+    FewShotExample(
+        id="EX8",
+        name="量价加权反转",
+        formula="ts_corr(close, vol, 10) * ts_mean(vol, 20)",
+        description=(
+            "10 日量价相关 + 20 日均量。"
+            "捕捉量价同向 + 高量能时的反转机会。"
+        ),
+        category="volume_price",
+        design_principles=["P1", "P2"],
+        operators_used=["ts_corr", "ts_mean"],
+        alpha101_ref="#N/A (派生)",
+        a_share_compatible=True,
+    ),
+    FewShotExample(
+        id="EX9",
+        name="线性加权动量",
+        formula="rank(decay_linear(close / ts_lag(close, 5) - 1, 10))",
+        description=(
+            "5 日收益率做 10 日线性衰减加权（近期权重高）。"
+            "捕捉短期动量的持续性。"
+        ),
+        category="momentum",
+        design_principles=["P2", "P3", "P6"],
+        operators_used=["rank", "decay_linear", "ts_lag"],
+        alpha101_ref="#N/A (派生)",
+        a_share_compatible=True,
+    ),
+    FewShotExample(
+        id="EX10",
+        name="Alpha 101 #89 完整版",
+        formula="rank(decay_linear(ts_sum(close, 10) / 10, 10))",
+        description=(
+            "10 日 close 求和 / 10 = 10 日均价（与 ts_mean 等价）。"
+            "再 10 日线性衰减加权（近期权重高）。"
+            "最后截面 rank。"
+            "这是 Alpha 101 #89 的 polars 表达。"
+        ),
+        category="momentum",
+        design_principles=["P3", "P6"],
+        operators_used=["rank", "decay_linear", "ts_sum"],
+        alpha101_ref="#89",
+        a_share_compatible=True,
+    ),
+]
+
+
+# ==============================================================================
+# 辅助函数
+# ==============================================================================
+
+
+def list_examples(category: Optional[str] = None) -> List[FewShotExample]:
+    """列出所有示例（可按 category 过滤）"""
+    if category is None:
+        return list(ALPHA101_FEW_SHOT_EXAMPLES)
+    return [e for e in ALPHA101_FEW_SHOT_EXAMPLES if e.category == category]
+
+
+def get_example(example_id: str) -> Optional[FewShotExample]:
+    """按 ID 查示例"""
+    for e in ALPHA101_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}\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 ALPHA101_FEW_SHOT_EXAMPLES))