quantnodes 3.0.0__py3-none-any.whl

QuantNodes/research/factor_test/utils/performance_metrics.py

@@ -0,0 +1,175 @@
+# coding: utf-8
+"""评价指标工具 / Performance Metrics
+
+Migrated from ~/Public/单因子回测/factor_performance.py
+"""
+
+import pandas as pd
+import numpy as np
+from .constants import ANNUAL_DAYS
+
+
+def calc_max_drawdown(net_day: pd.Series) -> dict:
+    """计算最大回撤 (复利净值曲线)
+
+    Returns:
+        dict: MDD, MDD_date, Lastingtime, Endingtime, DD (每日回撤序列)
+    """
+    DD = 1 - net_day / net_day.cummax()
+    DD = DD.dropna()
+    if DD.empty:
+        return {'MDD': 0, 'MDD_date': None, 'Lastingtime': 0, 'Endingtime': 0, 'DD': DD}
+
+    MDD = DD.max()
+    maxdraw_idx = DD.idxmax()
+
+    # 最大回撤开始时间: 回撤为 0 的最后一天
+    try:
+        index_bg = DD.loc[:maxdraw_idx][DD.loc[:maxdraw_idx] == 0].index[-1]
+    except (IndexError, KeyError):
+        index_bg = DD.index[0]
+
+    lasting_time = (pd.Index(DD.index).get_indexer([maxdraw_idx])[0]
+                    - pd.Index(DD.index).get_indexer([index_bg])[0] + 1)
+
+    # 最大回撤结束时间: 回撤恢复为 0 的第一天
+    try:
+        index_end = DD.loc[maxdraw_idx:][DD.loc[maxdraw_idx:] == 0].idxmax()
+    except (ValueError, KeyError):
+        index_end = DD.index[-1]
+
+    ending_time = (pd.Index(DD.index).get_indexer([index_end])[0]
+                   - pd.Index(DD.index).get_indexer([maxdraw_idx])[0] + 1)
+
+    return {
+        'MDD': MDD,
+        'MDD_date': maxdraw_idx,
+        'Lastingtime': lasting_time,
+        'Endingtime': ending_time,
+        'DD': DD,
+    }
+
+
+def evaluation(
+    account_net: pd.Series, adj_dates: list, annual_days: int = ANNUAL_DAYS,
+) -> pd.DataFrame:
+    """输入净值曲线返回评价结果 (全期 + 分年)
+
+    Args:
+        account_net: 单利净值曲线
+        adj_dates: 调仓日列表
+        annual_days: M11 年化天数 (默认全局 ANNUAL_DAYS=250, 美股 252, 24h 365)
+
+    Returns:
+        DataFrame: Year, AnnualRt, AccumRt, SR, MDD, WinRatio, WinLossRatio, Calmar, ...
+    """
+    result = []
+    account_net = account_net.copy()
+    account_net.name = 'net'
+
+    if isinstance(account_net, pd.DataFrame):
+        account_net = account_net.iloc[:, 0]
+
+    # 日收益率
+    net = account_net.to_frame()
+    net['ret_daily'] = 0.0
+    if adj_dates[0] != net.index[0]:
+        all_dates = [net.index[0]] + adj_dates
+    else:
+        all_dates = adj_dates
+
+    for i in range(len(all_dates)):
+        current_date = all_dates[i]
+        next_date = all_dates[i + 1] if i < len(all_dates) - 1 else all_dates[-1]
+        current_net = net.loc[current_date:next_date, 'net']
+        current_net = current_net - current_net.iloc[0] + 1
+        net.loc[current_net.index[1:], 'ret_daily'] = current_net.pct_change()[1:]
+
+    daily_ret = net['ret_daily']
+
+    # 每期收益
+    every_return = account_net.loc[adj_dates].to_frame().diff(1)
+    adj_cycle = len(account_net.loc[adj_dates[0]:adj_dates[-1]]) / (len(adj_dates) - 1)
+
+    # 全期指标
+    accum_rt = account_net.iloc[-1] / account_net.iloc[0] - 1
+    annual_rt = every_return.mean().iloc[0] / adj_cycle * annual_days
+    annu_std = daily_ret.std(ddof=1) * np.sqrt(annual_days)
+    SR = np.nan if annu_std == 0 else annual_rt / annu_std
+    mdd = calc_max_drawdown(account_net)
+    winRatio = (every_return.dropna() > 0).mean().iloc[0]
+    winlossRatio = (every_return[every_return > 0].mean().iloc[0]
+                    / every_return[every_return < 0].mean().iloc[0] * -1)
+    calmar = np.nan if mdd['MDD'] == 0 else annual_rt / mdd['MDD']
+    trade_times = every_return.notna().sum().iloc[0]
+
+    result.append([
+        'all', annual_rt, accum_rt, SR, mdd['MDD'], winRatio, winlossRatio,
+        calmar, mdd['MDD_date'], mdd['Lastingtime'], mdd['Endingtime'], trade_times
+    ])
+
+    # 分年
+    account_net_df = account_net.to_frame()
+    account_net_df['trade_dt'] = account_net_df.index.values
+    account_net_df['year'] = pd.to_datetime(
+        account_net_df['trade_dt'].astype(str), format='%Y%m%d'
+    ).dt.year
+
+    every_return_cp = every_return.copy()
+    every_return_cp['year'] = list(map(
+        lambda x: pd.to_datetime(str(x), format='%Y%m%d').year,
+        every_return.index.tolist()
+    ))
+
+    for year_i in account_net_df['year'].unique():
+        account_net_i = account_net_df[account_net_df['year'] == year_i]['net']
+        every_return_i = every_return[every_return_cp['year'] == year_i]
+
+        accum_rt_i = every_return_i.sum().iloc[0]
+        annual_rt_i = every_return_i.mean().iloc[0] / adj_cycle * annual_days
+        annu_std_i = daily_ret[account_net_df['year'] == year_i].std(ddof=1) * np.sqrt(annual_days)
+        SR_i = np.nan if annu_std_i == 0 else annual_rt_i / annu_std_i
+
+        mdd_i = calc_max_drawdown(account_net_i) if len(account_net_i) > 1 else {'MDD': 0}
+
+        winRatio_i = (every_return_i.dropna() > 0).mean().iloc[0]
+        wl_i = every_return_i[every_return_i > 0].mean().iloc[0]
+        wl_j = every_return_i[every_return_i < 0].mean().iloc[0]
+        winlossRatio_i = wl_i / wl_j * -1 if pd.notna(wl_j) and wl_j != 0 else np.nan
+        calmar_i = np.nan if mdd_i['MDD'] == 0 else annual_rt_i / mdd_i['MDD']
+        trade_times_i = every_return_i.notna().sum().iloc[0]
+
+        result.append([
+            year_i, annual_rt_i, accum_rt_i, SR_i, mdd_i['MDD'], winRatio_i,
+            winlossRatio_i, calmar_i, mdd_i.get('MDD_date'), mdd_i.get('Lastingtime', 0),
+            mdd_i.get('Endingtime', 0), trade_times_i
+        ])
+
+    columns = [
+        'Year', 'AnnualRt', 'AccumRt', 'SR', 'MDD', 'WinRatio', 'WinLossRatio',
+        'Calmar', 'MDD_date', 'MDD_lastdays', 'MDD_recoverdays', 'Periods'
+    ]
+    return pd.DataFrame(result, columns=columns)
+
+
+def cal_net_simple(net: pd.Series, adj_dates: list) -> pd.Series:
+    """将复利净值转换为单利净值"""
+    data_net = net.to_frame()
+    data_net.columns = ['account']
+    data_net['simp'] = np.nan
+
+    # 第一个调仓日之前
+    data_net.loc[:adj_dates[1], 'simp'] = data_net.loc[:adj_dates[1], 'account']
+    benchmark_i = data_net.loc[adj_dates[1], 'account']
+
+    for i in range(1, len(adj_dates) - 1):
+        adj_i = adj_dates[i]
+        net_i = net.loc[adj_i:adj_dates[i + 1]]
+        ret_i = net_i / net_i.iloc[0] - 1
+        net_i_update = ret_i + benchmark_i
+        data_net.loc[adj_i:adj_dates[i + 1], 'simp'] = net_i_update.values
+        benchmark_i = data_net.loc[adj_dates[i + 1], 'simp']
+
+    result = data_net['simp'].to_frame()
+    result.columns = ['net']
+    return result['net']

QuantNodes/research/factor_test/utils/safe_load.py

@@ -0,0 +1,106 @@
+"""Safe data-load helpers (Phase J3+J4, 2026-06-20).
+
+Consolidates 11 ``try: ... except Exception: pass`` patterns that swallow
+H5 / CSV load failures silently. Each helper logs a warning instead of
+silently dropping data, so users can debug "where did my factor go?".
+
+Used by:
+  - LoadDataNode (load_data_node.py): 4 silent-fail sites (price,
+    load_keys fallback, index_cp, etc.)
+  - FactorNeutralizeNode: 1 risk-factor load fallback
+  - RiskCorrelationNode: 1 risk-factor load fallback
+  - GroupAnalyzerNode: 1 hedge_path load
+
+All helpers return None on failure (instead of raising), so existing
+control flow is preserved. Switch to logger.warning() from silent pass.
+"""
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+
+def safe_load_h5(
+    loader: object,
+    filename: str,
+    key: str,
+    *,
+    axis_type: str = "stock",
+    add_index: bool = True,
+) -> "pd.DataFrame | None":
+    """Load a single H5 key, returning None on failure.
+
+    Args:
+        loader: DataLoader instance.
+        filename: H5 filename relative to loader.api (e.g. 'stk_daily.h5').
+        key: H5 key (auto-prefixed with '/' if missing).
+        axis_type: 'stock' or 'index' (passed to loader.add_index).
+        add_index: if True, also add stock/index axis index to result.
+
+    Returns:
+        DataFrame or None on KeyError/FileNotFoundError/Exception.
+        Logs at DEBUG level on failure (visible only when logging enabled).
+    """
+    try:
+        data = loader.load_h5(filename, key)
+        if add_index and hasattr(loader, "add_index"):
+            return loader.add_index(data, axis_type=axis_type)
+        return data
+    except Exception as e:
+        logger.debug("safe_load_h5(%s, %s) failed: %s", filename, key, e)
+        return None
+
+
+def try_load_panels(
+    loader: object,
+    key: str,
+    *,
+    axis_type: str = "stock",
+    candidates: tuple[str, ...] = ("stk_daily.h5", "index_daily.h5"),
+) -> "pd.DataFrame | None":
+    """Try each candidate filename, return first non-None panel.
+
+    Used when a key may exist in either stk_daily.h5 or index_daily.h5
+    and we don't know which one ahead of time.
+
+    Returns None if none of the candidates have the key (logs at DEBUG).
+    """
+    for fn in candidates:
+        result = safe_load_h5(loader, fn, key, axis_type=axis_type)
+        if result is not None:
+            return result
+    logger.debug("try_load_panels(%s) - key not in any candidate %s", key, candidates)
+    return None
+
+
+def safe_load_custom(
+    loader: object,
+    data_dir: tuple,
+) -> "pd.DataFrame | None":
+    """Wrap loader.load_custom(), return None on failure.
+
+    Replaces bare ``except Exception: pass`` around load_custom calls.
+    """
+    try:
+        return loader.load_custom(data_dir)
+    except Exception as e:
+        logger.debug("safe_load_custom(%s) failed: %s", data_dir, e)
+        return None
+
+
+def safe_load_factor(
+    loader: object,
+    factor_dir: str,
+    factor_name: str,
+) -> "pd.DataFrame | None":
+    """Wrap loader.load_factor(), return None on failure."""
+    try:
+        return loader.load_factor(factor_dir, factor_name)
+    except Exception as e:
+        logger.debug("safe_load_factor(%s, %s) failed: %s", factor_dir, factor_name, e)
+        return None

QuantNodes/research/quant_alpha/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog - QuantAlpha
+
+All notable changes to QuantAlpha subpackage will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-23 (M1)
+
+### Added
+
+- **OperatorVocab 主类**：统一算子查询/调用/元数据化接口
+  - `OperatorVocab.default()`：模块级单例
+  - `OperatorVocab(config)`：自定义配置
+  - `build_namespace(data, date_column, code_column, cross_sectional=True)`：构造 eval 沙箱
+  - `list_operators(category=None)`：列出算子
+  - `get_operator(name)`：按名称获取
+  - `get_metadata(name)`：按名称获取元数据
+  - `evaluate(formula, data, ...)`：端到端评估（先 build_namespace 再 eval）
+
+- **5 个新算子**（修复 Alpha 101 关键缺口）：
+  - `signedpower(x, a)` = `sign(x) * abs(x) ** a`
+  - `ts_decay_linear(x, d)` = `decay_linear(x, d)` 别名
+  - `IndNeutralize(x, ind_class)` = `industry_neutralize(x, ind_class)` 别名
+  - `ts_skew(x, w)` = `rolling_skew(x, w)` 别名
+  - `ts_kurt(x, w)` = `rolling_kurt(x, w)` 别名
+
+- **算子元数据 schema 扩展**（从 5 字段到 12 字段）：
+  - 旧字段：name, category, func, doc, signature, parameters
+  - 新字段：difficulty, category_tags, default_window, requires_group_by, output_dtype, examples, composes_with
+
+- **per-date over() 语义修复**：
+  - `rank(x)` → `x.rank().over(date_column)`（per-date）
+  - `zscore(x)` → `(x - x.mean().over(date)) / (x.std().over(date) + 1e-8)`（per-date）
+  - `winsorize(x, l, u)` → per-date quantile clip
+  - `IndNeutralize(x, ind)` → per-date demean
+  - 提供 `cross_sectional=False` 关闭开关（兼容旧全局语义）
+
+- **DeprecationWarning**：旧 4 个文件加 import-time warning：
+  - `QuantNodes/research/factor_miner.py`
+  - `QuantNodes/research/factor_evaluator.py`
+  - `QuantNodes/research/mcts_search.py`
+  - `QuantNodes/research/auto_researcher.py`
+
+- **migration.md**：旧 API → 新 API 完整映射表
+
+### Fixed
+
+- **BUG 1（API 不存在）**：`pl.Series.rolling_corr` / `rolling_cov` 不存在
+- **BUG 2（维度错误）**：`rank` / `zscore` 全局计算而非 per-date
+- **BUG 3（静默失败）**：异常被 `except: return None` 吞掉 → 改为完整错误抛出
+
+### Changed
+
+- 旧 4 文件仍可用，行为完全兼容（旧 12-lambda 保留为内部实现，可通过 `cross_sectional=False` 切换回全局语义）
+
+### Deprecated
+
+- `QuantNodes.research.factor_miner.FactorMiner` → use `QuantNodes.research.quant_alpha.OperatorVocab`
+- `QuantNodes.research.factor_evaluator.FactorEvaluator` → use `QuantNodes.research.quant_alpha.OperatorVocab`
+- `QuantNodes.research.mcts_search.MCTSSearch` → use `QuantNodes.research.quant_alpha.mcts.MCTSSearch` (M2)
+- `QuantNodes.research.auto_researcher.AutoResearcher` → use `QuantNodes.research.quant_alpha.AutoResearcher` (M5+)
+
+### Performance
+
+- 算子可用数：从 12 → 285（+ 23×）
+- 元数据字段：从 5 → 12（+ 7 字段 LLM 友好）
+- per-date 正确性：修复维度 bug 后 IC 计算准确
+
+### Migration Path
+
+- **Phase A** (M1, current): 旧 4 文件 + DeprecationWarning，新子包并行
+- **Phase B** (M5+): 旧类变 thin wrapper，行为等价
+- **Phase C** (v3.0.0): 旧实现归档到 `_legacy_3c/`，破坏性变更
+
+---
+
+[Unreleased]: https://github.com/sn0wfree/QuantNodes/compare/v2.7.0...HEAD
+[0.1.0]: https://github.com/sn0wfree/QuantNodes/releases/tag/quant_alpha-v0.1.0

QuantNodes/research/quant_alpha/README.md

@@ -0,0 +1,142 @@
+# QuantAlpha
+
+> 自动化因子挖掘引擎 — 从"人工设计"到"机器发现"的范式升级
+
+[![Status](https://img.shields.io/badge/status-M1%20in%20progress-yellow)]()
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue)]()
+[![Coverage](https://img.shields.io/badge/coverage-%E2%89%A580%25-brightgreen)]()
+
+---
+
+## 1. 是什么
+
+**QuantAlpha** 是 QuantNodes 的自动化因子挖掘子包，参考业界 4 大因子库演进链：
+
+| 因子库 | 年份 | 范式 |
+|--------|------|------|
+| Alpha 101 | 2015 | 公式化因子 |
+| Alpha 158/360 | 2020 | ML 友好特征 |
+| AutoAlpha | 2020 | 层次化进化 |
+| AlphaGen / Alpha-GPT | 2023+ | RL / LLM 驱动 |
+
+完整规划见 [`docs/quant_alpha/PROJECT_PLAN.md`](../../docs/quant_alpha/PROJECT_PLAN.md)。
+
+---
+
+## 2. 当前状态：M1 (OperatorVocab)
+
+### 2.1 解决的问题
+
+QuantNodes 实际有 **285 个算子**（157 L0 + 109 talib + 20 L1 composite），但自动挖掘链路只能访问 **12 个硬编码 lambda**：
+
+- `factor_evaluator.py:202-215` 的 namespace 是 12 个手写 lambda
+- 3 个 latent bug：
+  - `ts_corr` / `ts_cov` 用 `Series.rolling_corr`（Series 上不存在）
+  - `rank` / `zscore` 全局计算（不是 per-date 截面）
+  - 异常被 `except: return None` 静默吞掉
+
+### 2.2 M1 交付
+
+- ✅ **OperatorVocab**：统一算子查询/调用/元数据化接口
+- ✅ **5 个新算子**：`signedpower` / `ts_decay_linear` / `IndNeutralize` / `ts_skew` / `ts_kurt`
+- ✅ **per-date over() 修复**：默认走 per-date，可通过 `cross_sectional=False` 关闭
+- ✅ **算子元数据 schema 扩展**：7 个新字段（difficulty / category_tags / default_window / requires_group_by / output_dtype / examples / composes_with）
+- ✅ **DeprecationWarning**：旧 4 文件加 warning，进入 deprecation 周期
+- ✅ **migration.md**：旧 API → 新 API 完整映射
+
+### 2.3 快速开始
+
+```python
+from QuantNodes.research.quant_alpha import OperatorVocab
+import polars as pl
+
+# 构造数据
+df = pl.DataFrame({
+    "date": [...],
+    "code": [...],
+    "close": [...],
+    "open": [...],
+    "high": [...],
+    "low": [...],
+    "vol": [...],
+})
+
+# 构造 eval namespace（285 个算子 + per-date over()）
+vocab = OperatorVocab.default()
+namespace = vocab.build_namespace(
+    data=df,
+    date_column="date",
+    code_column="code",
+    cross_sectional=True,  # 默认 per-date
+)
+
+# 评估公式
+result = vocab.evaluate(
+    "rank(ts_argmax(signedpower(close, 2), 5))",
+    data=df,
+    date_column="date",
+)
+
+# 列出所有算子
+all_ops = vocab.list_operators()
+ts_ops = vocab.list_operators(category="time")
+print(f"总算子数: {len(all_ops)}, 时序算子: {len(ts_ops)}")
+
+# 查询元数据
+meta = vocab.get_metadata("ts_argmax")
+print(f"difficulty={meta.difficulty}, requires_group_by={meta.requires_group_by}")
+```
+
+### 2.4 旧 API 迁移
+
+| 旧 API | 新 API | 行为差异 |
+|--------|--------|----------|
+| `from QuantNodes.research.factor_evaluator import FactorEvaluator` | `from QuantNodes.research.quant_alpha import OperatorVocab` | 行为等价 + 修复 3 bug |
+| `FactorEvaluator(config).evaluate(candidate, data)` | `OperatorVocab.default().evaluate(candidate, data)` | 算子从 12 增到 285 |
+| `eval(formula, namespace, data)` (12 ops) | `vocab.build_namespace(data)` (285 ops) | per-date over() 修复 |
+| `rank: col.rank()` (全局) | `rank: col.rank().over(date_column)` (per-date) | 修复维度 bug |
+
+完整迁移指南见 [`docs/quant_alpha/migration.md`](../../docs/quant_alpha/migration.md)。
+
+---
+
+## 3. 后续路线
+
+| 里程碑 | 周 | 路线 | 交付物 |
+|--------|----|----|--------|
+| M1 | 1 | 路线 0 | OperatorVocab + 5 算子 + per-date over() |
+| M2 | 2 | 路线 7 | MCTS + 5 通道反馈 |
+| M3 | 3 | 路线 1+2 借鉴 | alpha101/158 设计文档 + few-shot |
+| M4 | 4 | 路线 4 | PolarsAlphaCalculator 适配器 |
+| M5 | 5-6 | 路线 6 启动 | 算子元数据回填 + 3 智能体 + 4 层 RAG |
+| M6 | 7-10 | 路线 6 完成 | Alpha-GPT 完整工作流 |
+| M7 | 11 | 整合 | 跨路线 A/B + v2.7.0 release |
+
+---
+
+## 4. 测试
+
+```bash
+# 单元测试
+pytest tests/quant_alpha/ -v
+
+# 覆盖率
+pytest tests/quant_alpha/ --cov=QuantNodes.research.quant_alpha --cov-report=term-missing
+
+# 集成测试（含旧 4 文件兼容）
+pytest tests/quant_alpha/ tests/research/ -v
+```
+
+---
+
+## 5. 文档
+
+- [`docs/quant_alpha/PROJECT_PLAN.md`](../../docs/quant_alpha/PROJECT_PLAN.md) - 完整调研与规划
+- [`docs/quant_alpha/migration.md`](../../docs/quant_alpha/migration.md) - 旧 API → 新 API 迁移指南
+- [`CHANGELOG.md`](./CHANGELOG.md) - 子包变更日志
+
+---
+
+## 6. 许可
+
+MIT License（与 QuantNodes 主项目一致）

QuantNodes/research/quant_alpha/__init__.py

@@ -0,0 +1,45 @@
+# coding=utf-8
+"""
+QuantAlpha - 自动化因子挖掘引擎
+
+从"人工设计因子"到"机器发现因子"的范式升级。
+
+参考 4 大因子库演进链（见 docs/quant_alpha/PROJECT_PLAN.md）：
+- Alpha 101 (WorldQuant 2015) - 公式化因子范式
+- Alpha 158/360 (Qlib 2020) - ML 友好特征集
+- AutoAlpha (清华 2020) - 层次化进化
+- AlphaGen/Alpha-GPT (2023+) - RL/LLM 驱动
+
+M1 PR 范围（v2.7.0+）：
+- 算子词表 OperatorVocab：统一 285 个算子的查询/调用接口
+- 5 个新算子：signedpower / ts_decay_linear / IndNeutralize / ts_skew / ts_kurt
+- per-date over() 语义修复：修复旧 12-lambda namespace 的 3 个 latent bug
+- 旧 4 文件 DeprecationWarning：标记进入 deprecation 周期
+
+M2+ 路线：MCTS+5通道反馈 / Alpha 101+158/360 借鉴 / PolarsAlphaCalculator / Alpha-GPT。
+"""
+
+from __future__ import annotations
+
+# M1 公开 API
+from QuantNodes.research.quant_alpha.operator_vocab import (
+    OperatorVocab,
+    OperatorVocabConfig,
+    OperatorMetadata,
+    build_namespace,
+    list_vocab_operators,
+    get_vocab_operator,
+    get_vocab_metadata,
+)
+
+__all__ = [
+    # 主类
+    "OperatorVocab",
+    "OperatorVocabConfig",
+    "OperatorMetadata",
+    # 便捷函数
+    "build_namespace",
+    "list_vocab_operators",
+    "get_vocab_operator",
+    "get_vocab_metadata",
+]

QuantNodes/research/quant_alpha/adapters/__init__.py

@@ -0,0 +1,99 @@
+# coding=utf-8
+"""
+adapters - AlphaGen 兼容适配器
+
+让任何 RL 训练（AlphaGen / Alpha² / 自研）通过标准接口
+使用 QuantNodes 算子 + factor_test 评估。
+
+参考：AlphaGen (KDD 2023) 抽象接口 AlphaCalculator
+
+M4 范围：
+- Expression AST（极简子集，11 个算子）
+- BaseAlphaCalculator ABC（7 个抽象方法）
+- PolarsAlphaCalculator（参考实现，用 polars + OperatorVocab）
+- expression_to_formula 转换器
+
+后续路线（Phase 2）：
+- 全栈 AlphaGen 复刻（40+ 人天）
+- Alpha² 完整实现（45+ 人天）
+- 自主 RL 训练（基于 PolarsAlphaCalculator）
+"""
+
+from __future__ import annotations
+
+from QuantNodes.research.quant_alpha.adapters.calculator import (
+    BaseAlphaCalculator,
+    PolarsAlphaCalculator,
+)
+from QuantNodes.research.quant_alpha.adapters.expression import (
+    # 基础
+    Expression,
+    Feature,
+    Literal,
+    Ref,
+    # 二元
+    BinaryOp,
+    Add,
+    Sub,
+    Mul,
+    Div,
+    Greater,
+    Less,
+    # 一元
+    UnaryOp,
+    Abs,
+    Neg,
+    Log,
+    Sign,
+    Sqrt,
+    # 滚动
+    RollingOp,
+    Mean,
+    Std,
+    Sum,
+    Max,
+    Min,
+    Delta,
+    # 工具
+    expression_to_formula,
+    collect_feature_fields,
+    collect_rolling_windows,
+)
+
+__all__ = [
+    # ABC
+    "BaseAlphaCalculator",
+    "PolarsAlphaCalculator",
+    # Expression 基类
+    "Expression",
+    "Feature",
+    "Literal",
+    "Ref",
+    # 二元
+    "BinaryOp",
+    "Add",
+    "Sub",
+    "Mul",
+    "Div",
+    "Greater",
+    "Less",
+    # 一元
+    "UnaryOp",
+    "Abs",
+    "Neg",
+    "Log",
+    "Sign",
+    "Sqrt",
+    # 滚动
+    "RollingOp",
+    "Mean",
+    "Std",
+    "Sum",
+    "Max",
+    "Min",
+    "Delta",
+    # 工具
+    "expression_to_formula",
+    "collect_feature_fields",
+    "collect_rolling_windows",
+]