quantnodes 3.0.0__py3-none-any.whl

QuantNodes/research/__init__.py

@@ -0,0 +1,154 @@
+# coding=utf-8
+"""
+QuantNodes.research - Wiki 因子库代理层 + 研报复现
+
+功能3A: WikiFactorProxy (因子库基础设施)
+功能3B: ResearchReportReproducer (研报复现)
+
+**功能3C 已归档（v2.7.0+ Phase C）**：
+原 `factor_miner` / `factor_evaluator` / `auto_researcher` / `mcts_search`
+四个模块已移至 `QuantNodes.research._legacy_3c`，通过下方 shim 仍可导入
+但带强 DeprecationWarning。
+
+**新实现**：
+- 算子统一 → `QuantNodes.research.quant_alpha.operator_vocab.OperatorVocab` (162 算子)
+- MCTS 搜索 → `QuantNodes.research.quant_alpha.mcts.MCTSSearch` (5 通道反馈 + 谱系)
+- Alpha-GPT 工作流 → `QuantNodes.research.quant_alpha.workflow.AlphaGptWorkflow`
+"""
+
+from QuantNodes.research.wiki import (
+    WikiFactorProxy,
+    WikiFactor,
+    WikiLogic,
+    FactorSource,
+    FactorCategory,
+    LogicSource,
+    WikiProxyError,
+    QUANT_RELATION_TYPES,
+    init_factor_wiki,
+)
+
+# 功能3C — Phase C 归档（v2.7.0+）：4 个模块已移至 _legacy_3c/
+# 下面 4 个 import 通过 re-export 保持向后兼容，但每次导入触发 DeprecationWarning
+import warnings as _warnings
+
+_LEGACY3C_MIGRATION = (
+    "QuantNodes.research.{name} 已归档到 _legacy_3c/（Phase C, v2.7.0+）。"
+    "请迁移到 QuantNodes.research.quant_alpha.{target}。"
+)
+
+_LEGACY3C_TARGETS = {
+    "FactorMiner": "operator_vocab.OperatorVocab",
+    "FactorCandidate": "operator_vocab.OperatorVocab",
+    "FactorEvaluator": "operator_vocab.OperatorVocab",
+    "FactorEvaluationResult": "operator_vocab.OperatorVocab",
+    "EvalConfig": "operator_vocab.OperatorVocab",
+    "AutoResearcher": "workflow.AlphaGptWorkflow",
+    "AutoResearchResult": "workflow.AlphaGptResult",
+    "MCTSSearch": "mcts.MCTSSearch",
+    "MCTSNode": "mcts.MCTSNode",
+}
+
+
+class _LegacyShim:
+    """Lazy shim: import 时触发 DeprecationWarning，访问属性时再 import"""
+
+    def __init__(self, module_name: str, attrs: list, target: str):
+        self._module_name = module_name
+        self._attrs = attrs
+        self._target = target
+        self._warned = False
+        self._module = None
+
+    def _warn_once(self):
+        if not self._warned:
+            _warnings.warn(
+                _LEGACY3C_MIGRATION.format(
+                    name=self._module_name.split(".")[-1],
+                    target=self._target,
+                ),
+                DeprecationWarning,
+                stacklevel=3,
+            )
+            self._warned = True
+
+    def __getattr__(self, name: str):
+        if name not in self._attrs:
+            raise AttributeError(
+                f"module {__name__!r} has no attribute {name!r}"
+            )
+        self._warn_once()
+        if self._module is None:
+            import importlib
+            self._module = importlib.import_module(self._module_name)
+        return getattr(self._module, name)
+
+
+import sys as _sys
+_legacy_factor_evaluator = _LegacyShim(
+    "QuantNodes.research._legacy_3c.factor_evaluator",
+    ["EvalConfig", "FactorEvaluationResult", "FactorEvaluator"],
+    "operator_vocab.OperatorVocab",
+)
+_legacy_factor_miner = _LegacyShim(
+    "QuantNodes.research._legacy_3c.factor_miner",
+    ["FactorMiner", "FactorCandidate", "TEMPLATES", "DEFAULT_WINDOWS"],
+    "operator_vocab.OperatorVocab",
+)
+_legacy_auto_researcher = _LegacyShim(
+    "QuantNodes.research._legacy_3c.auto_researcher",
+    ["AutoResearcher", "AutoResearchResult"],
+    "workflow.AlphaGptWorkflow",
+)
+_legacy_mcts_search = _LegacyShim(
+    "QuantNodes.research._legacy_3c.mcts_search",
+    ["MCTSSearch", "MCTSNode"],
+    "mcts.MCTSSearch",
+)
+
+# Register in sys.modules for import resolution
+_sys.modules[__name__ + ".factor_evaluator"] = _legacy_factor_evaluator
+_sys.modules[__name__ + ".factor_miner"] = _legacy_factor_miner
+_sys.modules[__name__ + ".auto_researcher"] = _legacy_auto_researcher
+_sys.modules[__name__ + ".mcts_search"] = _legacy_mcts_search
+
+# Also set as attributes on the parent module for attribute access
+factor_evaluator = _legacy_factor_evaluator
+factor_miner = _legacy_factor_miner
+auto_researcher = _legacy_auto_researcher
+mcts_search = _legacy_mcts_search
+
+from QuantNodes.research.report_reproducer import (
+    ResearchReportReproducer,
+    ExtractedLogic,
+    ReproductionResult,
+    ReproductionReport,
+)
+
+__all__ = [
+    # 功能3A
+    "WikiFactorProxy",
+    "WikiFactor",
+    "WikiLogic",
+    "FactorSource",
+    "FactorCategory",
+    "LogicSource",
+    "WikiProxyError",
+    "QUANT_RELATION_TYPES",
+    "init_factor_wiki",
+    # 功能3B
+    "ResearchReportReproducer",
+    "ExtractedLogic",
+    "ReproductionResult",
+    "ReproductionReport",
+    # 功能3C
+    "AutoResearcher",
+    "AutoResearchResult",
+    "FactorMiner",
+    "FactorCandidate",
+    "FactorEvaluator",
+    "FactorEvaluationResult",
+    "EvalConfig",
+    "MCTSSearch",
+    "MCTSNode",
+]

QuantNodes/research/_legacy_3c/__init__.py

@@ -0,0 +1,61 @@
+# coding=utf-8
+"""
+_legacy_3c - 功能 3C 归档包（Phase C, v2.7.0+）
+
+包含原 v2.x 的 4 个自动因子挖掘模块（已弃用）：
+- factor_evaluator: 12-lambda namespace 评估器
+- factor_miner: 4 模板族（momentum/reversal/volume/volatility）
+- auto_researcher: AutoResearcher 主类
+- mcts_search: 7 硬编码 EXTENSION_OPS 的 MCTS
+
+**迁移指南**：
+
+| v2.x (此处) | v2.7.0+ (quant_alpha) |
+|-------------|----------------------|
+| `factor_evaluator.FactorEvaluator` | `quant_alpha.operator_vocab.OperatorVocab` |
+| `factor_miner.FactorMiner` | `quant_alpha.operator_vocab.OperatorVocab` (162 算子) |
+| `mcts_search.MCTSSearch` | `quant_alpha.mcts.MCTSSearch` (26 动态操作 + 5 通道反馈) |
+| `auto_researcher.AutoResearcher` | `quant_alpha.workflow.AlphaGptWorkflow` |
+
+修复的 3 个 latent bug（vs 旧实现）：
+1. `ts_corr/ts_cov` 之前调用不存在的 `Series.rolling_corr` → 用 `pl.rolling_corr`
+2. `rank/zscore` 之前全局而非 per-date → 默认 per-date 截面
+3. 之前异常被静默吞掉 → 现在显式 raise
+
+这些模块在 v3.0 (Phase C 完全归档) 后将被移除。
+"""
+
+from .factor_evaluator import (
+    FactorEvaluator,
+    FactorEvaluationResult,
+    EvalConfig,
+)
+from .factor_miner import (
+    FactorMiner,
+    FactorCandidate,
+    TEMPLATES,
+    DEFAULT_WINDOWS,
+)
+from .mcts_search import (
+    MCTSSearch,
+    MCTSNode,
+)
+from .auto_researcher import (
+    AutoResearcher,
+    AutoResearchResult,
+)
+
+
+__all__ = [
+    "FactorEvaluator",
+    "FactorEvaluationResult",
+    "EvalConfig",
+    "FactorMiner",
+    "FactorCandidate",
+    "TEMPLATES",
+    "DEFAULT_WINDOWS",
+    "MCTSSearch",
+    "MCTSNode",
+    "AutoResearcher",
+    "AutoResearchResult",
+]

QuantNodes/research/_legacy_3c/auto_researcher.py

@@ -0,0 +1,289 @@
+# coding=utf-8
+"""
+AutoResearcher - 自动因子研究系统
+
+编排因子挖掘、评估、去重、存储的完整流程。
+支持3个阶段: 模板枚举 → MCTS搜索 → LLM增强
+
+⚠️ DeprecationWarning (v2.7.0+, since 2026-06-23):
+    本模块进入 deprecation 周期。新代码请迁移到
+    `QuantNodes.research.quant_alpha.AutoResearcher` (M5+ PR)。
+
+    迁移理由：
+    - 完整 OperatorVocab 集成
+    - 跨路线整合（Alpha 101/158 + MCTS + LLM）
+    - 完整元数据 + 谱系追踪
+
+    Phase 时间表：
+    - Phase A (current): 本文件仍可用，行为完全兼容
+    - Phase B (M5+): 本类变 thin wrapper
+    - Phase C (v3.0): 归档到 _legacy_3c/
+"""
+
+from __future__ import annotations
+
+import time
+import warnings
+from dataclasses import dataclass, field
+from typing import List
+
+import polars as pl
+
+warnings.warn(
+    "QuantNodes.research.auto_researcher 已弃用 (DeprecationWarning)。"
+    "M5+ PR 将提供新实现 QuantNodes.research.quant_alpha.AutoResearcher。",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+from QuantNodes.research._legacy_3c.factor_miner import FactorMiner
+from QuantNodes.research._legacy_3c.factor_evaluator import (
+    EvalConfig,
+    FactorEvaluationResult,
+    FactorEvaluator,
+)
+from QuantNodes.research._legacy_3c.mcts_search import MCTSSearch
+from QuantNodes.research.wiki import (
+    FactorCategory,
+    FactorSource,
+    WikiFactor,
+    WikiFactorProxy,
+)
+
+
+@dataclass
+class AutoResearchResult:
+    """自动挖掘结果"""
+    valid_factors: List[FactorEvaluationResult] = field(default_factory=list)
+    all_evaluated: List[FactorEvaluationResult] = field(default_factory=list)
+    rejected_count: int = 0
+    deduplicated_count: int = 0
+    elapsed_seconds: float = 0.0
+    report_markdown: str = ""
+
+
+class AutoResearcher:
+    """自动因子研究系统
+
+    阶段1: 模板枚举 + 6维度评估 + 相关性去重
+    阶段2: MCTS 搜索 (见 mcts_search.py)
+    """
+
+    def __init__(self, wiki_path: str):
+        self.wiki_path = wiki_path
+        self.proxy = WikiFactorProxy(wiki_path)
+        self.miner = FactorMiner()
+        self.evaluator = FactorEvaluator()
+
+    def run(
+        self,
+        data: pl.DataFrame,
+        eval_config: EvalConfig = None,
+        date_column: str = "date",
+        code_column: str = "code",
+        forward_return_column: str = "forward_return",
+        max_factors: int = 100,
+        store_to_wiki: bool = True,
+        use_mcts: bool = False,
+        mcts_iterations: int = 50,
+    ) -> AutoResearchResult:
+        """执行完整挖掘流程
+
+        Args:
+            data: 行情数据 (需包含 date, code, close, vol, forward_return 等列)
+            eval_config: 评估配置
+            date_column: 日期列名
+            code_column: 股票代码列名
+            forward_return_column: 前瞻收益率列名
+            max_factors: 最大候选因子数
+            store_to_wiki: 是否存入 Wiki
+            use_mcts: 是否使用 MCTS 搜索 (阶段2)
+            mcts_iterations: MCTS 迭代次数
+
+        Returns:
+            AutoResearchResult
+        """
+        start = time.time()
+        config = eval_config or EvalConfig()
+
+        # 1. 获取可用列
+        available_cols = [
+            c for c in data.columns
+            if c not in (date_column, code_column, forward_return_column)
+        ]
+
+        # 2. 阶段1: 模板枚举
+        candidates = self.miner.generate(
+            available_columns=available_cols,
+            config=type("Cfg", (), {
+                "max_factors": max_factors,
+                "windows": [5, 10, 20, 60],
+            })(),
+        )
+
+        evaluated: List[FactorEvaluationResult] = []
+        existing_factors: List[pl.Series] = []
+
+        for candidate in candidates:
+            result = self.evaluator.evaluate(
+                candidate=candidate,
+                data=data,
+                date_column=date_column,
+                code_column=code_column,
+                forward_return_column=forward_return_column,
+                existing_factors=existing_factors if existing_factors else None,
+            )
+            evaluated.append(result)
+            if result.is_valid and result.factor_values is not None:
+                existing_factors.append(result.factor_values)
+
+        # 3. 阶段2: MCTS 搜索 (可选)
+        if use_mcts:
+            mcts = MCTSSearch(evaluator=self.evaluator, eval_config=config)
+            seed_formulas = [
+                r.candidate.formula for r in evaluated
+                if r.is_valid
+            ][:10]
+            mcts_results = mcts.search(
+                data=data,
+                seed_formulas=seed_formulas,
+                iterations=mcts_iterations,
+                date_column=date_column,
+                code_column=code_column,
+                forward_return_column=forward_return_column,
+            )
+            evaluated.extend(mcts_results)
+
+        # 4. 筛选有效因子
+        valid = [r for r in evaluated if r.is_valid]
+
+        # 5. 相关性去重
+        deduplicated = self.evaluator.deduplicate(valid, config.corr_threshold)
+
+        # 6. 存入 Wiki
+        if store_to_wiki:
+            for result in deduplicated:
+                self._store_to_wiki(result)
+
+        # 7. 生成报告
+        elapsed = time.time() - start
+        report = self._generate_report(deduplicated, evaluated, elapsed)
+
+        return AutoResearchResult(
+            valid_factors=deduplicated,
+            all_evaluated=evaluated,
+            rejected_count=len(candidates) - len(valid),
+            deduplicated_count=len(valid) - len(deduplicated),
+            elapsed_seconds=elapsed,
+            report_markdown=report,
+        )
+
+    def mine_single_factor(
+        self,
+        formula: str,
+        data: pl.DataFrame,
+        description: str = "",
+        date_column: str = "date",
+        code_column: str = "code",
+        forward_return_column: str = "forward_return",
+        store_to_wiki: bool = False,
+    ) -> FactorEvaluationResult:
+        """验证单个因子公式"""
+        candidate = self.miner.generate_single(
+            formula=formula,
+            description=description,
+            category=FactorCategory.OTHER,
+        )
+
+        result = self.evaluator.evaluate(
+            candidate=candidate,
+            data=data,
+            date_column=date_column,
+            code_column=code_column,
+            forward_return_column=forward_return_column,
+        )
+
+        if result.is_valid and store_to_wiki:
+            self._store_to_wiki(result)
+
+        return result
+
+    def _store_to_wiki(self, result: FactorEvaluationResult):
+        """将验证通过的因子存入 Wiki"""
+        factor = WikiFactor(
+            name=result.candidate.name,
+            formula=result.candidate.formula,
+            source=FactorSource.AUTO_RESEARCH,
+            category=result.candidate.category,
+            tags=[result.candidate.template_name],
+            ic_mean=result.ic_mean,
+            ic_std=result.ic_std,
+            icir=result.icir,
+            rank_ic_mean=result.rank_ic_mean,
+            turnover=result.turnover,
+            metadata={
+                "stability_score": result.stability_score,
+                "monotonicity_score": result.monotonicity_score,
+                "coverage": result.coverage,
+                "overall_score": result.overall_score,
+                "group_returns": result.group_returns,
+            },
+        )
+        self.proxy.store_factor(factor)
+
+    def _generate_report(
+        self,
+        valid: List[FactorEvaluationResult],
+        all_evaluated: List[FactorEvaluationResult],
+        elapsed: float,
+    ) -> str:
+        """生成 Markdown 挖掘报告"""
+        lines = [
+            "# AutoResearch 因子挖掘报告",
+            "",
+            f"**总耗时**: {elapsed:.1f}s",
+            f"**候选因子数**: {len(all_evaluated)}",
+            f"**通过验证**: {len(valid)}",
+            f"**通过率**: {len(valid) / max(len(all_evaluated), 1) * 100:.1f}%",
+            "",
+            "## 通过验证的因子",
+            "",
+        ]
+
+        if not valid:
+            lines.append("无因子通过验证。")
+        else:
+            lines.append("| 因子 | IC | ICIR | 稳定性 | 单调性 | 换手率 | 评分 |")
+            lines.append("|------|-----|------|--------|--------|--------|------|")
+            for r in sorted(valid, key=lambda x: x.overall_score, reverse=True):
+                lines.append(
+                    f"| {r.candidate.name} "
+                    f"| {r.ic_mean:.4f} "
+                    f"| {r.icir:.4f} "
+                    f"| {r.stability_score:.2f} "
+                    f"| {r.monotonicity_score:.2f} "
+                    f"| {r.turnover:.3f} "
+                    f"| {r.overall_score:.3f} |"
+                )
+
+        lines.append("")
+        lines.append("## 详细信息")
+        lines.append("")
+
+        for i, r in enumerate(valid[:10], 1):  # 最多显示10个
+            lines.append(f"### {i}. {r.candidate.name}")
+            lines.append(f"- **公式**: `{r.candidate.formula}`")
+            lines.append(f"- **描述**: {r.candidate.description}")
+            lines.append(f"- **模板**: {r.candidate.template_name}")
+            lines.append(f"- **IC Mean**: {r.ic_mean:.4f}")
+            lines.append(f"- **IC IR**: {r.icir:.4f}")
+            lines.append(f"- **Rank IC**: {r.rank_ic_mean:.4f}")
+            lines.append(f"- **稳定性**: {r.stability_score:.2f}")
+            lines.append(f"- **单调性**: {r.monotonicity_score:.2f}")
+            lines.append(f"- **换手率**: {r.turnover:.3f}")
+            lines.append(f"- **覆盖率**: {r.coverage:.2f}")
+            if r.group_returns:
+                lines.append(f"- **分组收益**: {[f'{x:.4f}' for x in r.group_returns]}")
+            lines.append("")
+
+        return "\n".join(lines)