quantnodes 3.0.0__py3-none-any.whl

QuantNodes/research/quant_alpha/logic_mining/sources.py

@@ -0,0 +1,149 @@
+# coding=utf-8
+"""
+sources.py - Logic Mining 数据源适配
+
+支持从 alpha101_design / alpha158_design / Alpha191 等数据源
+提取公式用于逻辑抽取。
+
+Usage::
+
+    from QuantNodes.research.quant_alpha.logic_mining.sources import (
+        get_formulas_from_source, SOURCES,
+    )
+
+    formulas = get_formulas_from_source("alpha101", max_count=20)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["SOURCES", "get_formulas_from_source", "list_available_sources"]
+
+
+# 预定义的 Alpha101 代表性公式（量价类）
+ALPHA101_FORMULAS: Dict[str, str] = {
+    "alpha001": "rank(ts_argmax(signedpower(where(close < delay(close, 1), 1, -1) * (close - ts_min(close, 5)), 2), 5)) - 0.5",
+    "alpha006": "-ts_corr(open, volume, 10)",
+    "alpha012": "sign(delta(volume, 1)) * (-1 * delta(close, 1))",
+    "alpha018": "-rank(rank(std(abs(close - open), 5) + (close - open) + rank(corr(close, ts_mean(volume, 20), 5))))",
+    "alpha033": "rank(-1 + open / close)",
+    "alpha038": "-rank(ts_mean(close, 10) / ts_mean(close, 20) * rank(volume))",
+    "alpha041": "power(high * low, 0.5) - ts_mean(power(high * low, 0.5), 3)",
+    "alpha054": "-1 * rank((low - close) * power(volume, 0.5) / power(ts_mean(volume, 20), 0.5))",
+    "alpha055": "-1 * corr(rank(sub((high + low) / 2, ts_mean(high, 20))), rank(volume), 10)",
+    "alpha066": "-1 * ts_corr(close, ts_mean(volume, 20), 5)",
+    "alpha078": "rank(ts_corr(ts_mean(ts_mean(volume, 30), 37), ts_mean(close, 20), 7))",
+    "alpha085": "rank(ts_corr(high, volume, 5))",
+    "alpha088": "rank(ts_argmax(close - delay(close, 1), 30))",
+    "alpha095": "std(volume, 20) / std(close, 20)",
+    "alpha101": "rank(ts_mean(delta(close, 1), 5) - delta(ts_mean(close, 20), 5) / ts_mean(close, 20))",
+}
+
+# 预定义的 Alpha158 模板类别（来自 alpha158_design）
+ALPHA158_TEMPLATE_CATEGORIES: List[Dict[str, str]] = [
+    {"id": "KBAR", "name": "K线形态", "example": "rank(ts_mean(close - open, 20))"},
+    {"id": "PRICE", "name": "价格时序", "example": "ts_mean(close / delay(close, 5) - 1, 20)"},
+    {"id": "VOLUME", "name": "成交量时序", "example": "rank(volume / ts_mean(volume, 20))"},
+    {"id": "ROLLING", "name": "滚动统计", "example": "rank(ts_std(returns, 20))"},
+    {"id": "MOMENTUM", "name": "动量", "example": "rank(close / delay(close, 20) - 1)"},
+    {"id": "REVERSAL", "name": "反转", "example": "-rank(close / delay(close, 5) - 1)"},
+    {"id": "VOLATILITY", "name": "波动率", "example": "rank(ts_std(close, 20) / ts_mean(close, 20))"},
+    {"id": "LIQUIDITY", "name": "流动性", "example": "rank(volume / amount)"},
+]
+
+# 数据源注册表
+SOURCES: Dict[str, Dict[str, Any]] = {
+    "alpha101": {
+        "name": "WorldQuant Alpha101",
+        "description": "WorldQuant 101 formulaic alphas",
+        "formulas": ALPHA101_FORMULAS,
+        "count": len(ALPHA101_FORMULAS),
+    },
+    "alpha158": {
+        "name": "Qlib Alpha158",
+        "description": "Qlib 158 standard features (templates)",
+        "templates": ALPHA158_TEMPLATE_CATEGORIES,
+        "count": len(ALPHA158_TEMPLATE_CATEGORIES),
+    },
+}
+
+
+def get_formulas_from_source(
+    source_lib: str,
+    max_count: int = 20,
+    only_volume_price: bool = True,
+) -> List[Dict[str, str]]:
+    """从指定数据源获取公式
+
+    Args:
+        source_lib: 来源库名称 ("alpha101" / "alpha158" / "alpha191")
+        max_count: 最大数量
+        only_volume_price: 仅返回量价类公式（过滤掉含财务/基本面数据的）
+
+    Returns:
+        List of {"id": ..., "formula": ...}
+    """
+    if source_lib not in SOURCES:
+        logger.warning("Unknown source: %s, available: %s", source_lib, list(SOURCES.keys()))
+        return []
+
+    source = SOURCES[source_lib]
+    results = []
+
+    if source_lib == "alpha101":
+        for fid, formula in source["formulas"].items():
+            if only_volume_price and not _is_volume_price(formula):
+                continue
+            results.append({"id": fid, "formula": formula, "lib": source_lib})
+            if len(results) >= max_count:
+                break
+
+    elif source_lib == "alpha158":
+        for tmpl in source["templates"]:
+            if only_volume_price and not _is_volume_price(tmpl["example"]):
+                continue
+            results.append({
+                "id": tmpl["id"],
+                "formula": tmpl["example"],
+                "lib": source_lib,
+                "name": tmpl["name"],
+            })
+            if len(results) >= max_count:
+                break
+
+    elif source_lib == "alpha191":
+        # Alpha191 占位（PR-6 实现）
+        logger.info("alpha191 not yet implemented, returning empty list")
+        return []
+
+    logger.info("Loaded %d formulas from %s", len(results), source_lib)
+    return results
+
+
+def _is_volume_price(formula: str) -> bool:
+    """简单判断是否为量价类公式（排除财务/基本面类）"""
+    formula_lower = formula.lower()
+    # 排除包含财务指标的关键词
+    exclude_keywords = [
+        "earnings", "revenue", "profit", "bv", "market_cap",
+        "pb", "pe", "ps", "dividend", "roe", "roa",
+        "营业收入", "净利润", "市值", "市盈率",
+    ]
+    for kw in exclude_keywords:
+        if kw in formula_lower:
+            return False
+    return True
+
+
+def list_available_sources() -> List[str]:
+    """列出所有可用的数据源"""
+    return list(SOURCES.keys())
+
+
+def get_source_info(source_lib: str) -> Optional[Dict[str, Any]]:
+    """获取数据源详细信息"""
+    return SOURCES.get(source_lib)

QuantNodes/research/quant_alpha/mcts/__init__.py

@@ -0,0 +1,66 @@
+# coding=utf-8
+"""
+mcts - QuantAlpha MCTS 因子搜索子包
+
+参考 AlphaJungle 论文思路：
+- 把候选因子组织成搜索树
+- 每个节点有多维评价
+- UCB1 选择策略
+- 维度化反馈指导扩展方向
+- 频繁子树规避
+
+M2 改进（vs 旧 mcts_search.py）：
+- 7 硬编码 EXTENSION_OPS → 26 动态生成（从 OperatorVocab 162 算子）
+- 无谱系 → 完整 entry_id + parent_id（可映射 TrajectoryEntry）
+- 单一 dimension_scores → 5 通道 FactorFeedback 完整框架
+"""
+
+from __future__ import annotations
+
+from QuantNodes.research.quant_alpha.mcts.extension_ops import (
+    ExtensionOp,
+    ExtensionOpPool,
+    DEFAULT_WINDOWS,
+)
+from QuantNodes.research.quant_alpha.mcts.feedback import (
+    MCTSFeedbackConfig,
+    collect_all_channels,
+    collect_code_channel,
+    collect_execution_channel,
+    collect_llm_channel,
+    collect_shape_channel,
+    collect_value_channel,
+)
+from QuantNodes.research.quant_alpha.mcts.search import (
+    MCTSSearch,
+    MCTSSearchConfig,
+    MCTSSearchResult,
+)
+from QuantNodes.research.quant_alpha.mcts.tree import (
+    MCTSTree,
+    MCTSNode,
+    NodeStatus,
+)
+
+__all__ = [
+    # 操作池
+    "ExtensionOp",
+    "ExtensionOpPool",
+    "DEFAULT_WINDOWS",
+    # 反馈
+    "MCTSFeedbackConfig",
+    "collect_all_channels",
+    "collect_code_channel",
+    "collect_execution_channel",
+    "collect_llm_channel",
+    "collect_shape_channel",
+    "collect_value_channel",
+    # 搜索
+    "MCTSSearch",
+    "MCTSSearchConfig",
+    "MCTSSearchResult",
+    # 树
+    "MCTSTree",
+    "MCTSNode",
+    "NodeStatus",
+]

QuantNodes/research/quant_alpha/mcts/cache.py

@@ -0,0 +1,262 @@
+# coding=utf-8
+"""MCTSCache — 持久化共享缓存，跨运行复用公式评估结果。
+
+缓存布局：
+    {cache_root}/{data_fingerprint}/
+        cache.json          # 反馈条目（人类可读）
+        series_cache.pkl    # {formula: pl.Series} 字典（二进制，快速）
+
+Usage::
+
+    from QuantNodes.research.quant_alpha.mcts.cache import MCTSCache, MCTSCacheConfig
+
+    cache = MCTSCache(MCTSCacheConfig(enabled=True))
+    cache.load(data)  # 加载缓存
+
+    # 使用缓存
+    if cache.has_series(formula):
+        result = cache.get_series(formula)
+    else:
+        result = evaluate(formula, data)
+        cache.put_series(formula, result)
+
+    cache.save()  # 持久化
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import pickle
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, Optional, Set
+
+import polars as pl
+
+from QuantNodes.core.feedback import FactorFeedback
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_CACHE_ROOT = Path.home() / ".quantnodes" / "mcts_cache"
+
+
+@dataclass
+class MCTSCacheConfig:
+    """缓存配置。"""
+    cache_root: Path = DEFAULT_CACHE_ROOT
+    enabled: bool = True
+    max_series_entries: int = 5000
+    max_series_bytes: int = 500_000_000  # 500MB
+
+
+class MCTSCache:
+    """持久化共享缓存，用于 MCTS 公式评估。
+
+    特性：
+    - 数据指纹自动失效：不同数据 = 不同缓存目录
+    - 混合存储：JSON（反馈）+ pickle（Series）
+    - 增量更新：只保存新评估的公式
+    - 向后兼容：cache=None 保持当前行为
+    """
+
+    def __init__(self, config: Optional[MCTSCacheConfig] = None):
+        self.config = config or MCTSCacheConfig()
+        self._formula_cache: Dict[str, pl.Series] = {}
+        self._feedback_cache: Dict[str, FactorFeedback] = {}
+        self._cache_dir: Optional[Path] = None
+        self._dirty = False
+
+    # ----------------------------------------------------------
+    # 数据指纹
+    # ----------------------------------------------------------
+
+    @staticmethod
+    def compute_data_fingerprint(data: pl.DataFrame) -> str:
+        """计算 DataFrame 的稳定哈希。
+
+        使用：shape、column names、dtypes、首尾行采样。
+        两个相同指纹的 DataFrame 对同一公式会产生相同的 pl.Series。
+        """
+        parts = [
+            str(data.shape),
+            str(sorted(data.columns)),
+            str(sorted(str(d) for d in data.dtypes)),
+        ]
+        sample_size = min(100, len(data))
+        if sample_size > 0:
+            # 转换为字符串以确保确定性
+            head_str = str(data.head(sample_size).rows())
+            tail_str = str(data.tail(sample_size).rows())
+            parts.append(hashlib.md5(head_str.encode()).hexdigest())
+            parts.append(hashlib.md5(tail_str.encode()).hexdigest())
+        return hashlib.md5("|".join(parts).encode()).hexdigest()[:16]
+
+    # ----------------------------------------------------------
+    # 加载 / 保存
+    # ----------------------------------------------------------
+
+    def load(self, data: pl.DataFrame) -> None:
+        """从磁盘加载缓存。
+
+        如果没有缓存或数据指纹不匹配，从空缓存开始。
+        """
+        if not self.config.enabled:
+            return
+
+        fp = self.compute_data_fingerprint(data)
+        self._cache_dir = self.config.cache_root / fp
+        json_path = self._cache_dir / "cache.json"
+        pkl_path = self._cache_dir / "series_cache.pkl"
+
+        if not self._cache_dir.exists():
+            logger.info("No MCTS cache found at %s, starting fresh", self._cache_dir)
+            return
+
+        # 加载反馈
+        if json_path.exists():
+            try:
+                raw = json.loads(json_path.read_text(encoding="utf-8"))
+                self._feedback_cache = {
+                    k: FactorFeedback.from_dict(v)
+                    for k, v in raw.get("entries", {}).items()
+                }
+                logger.info(
+                    "Loaded %d feedback entries from %s",
+                    len(self._feedback_cache), json_path,
+                )
+            except Exception as e:
+                logger.warning("Failed to load feedback cache: %s", e)
+
+        # 加载 Series
+        if pkl_path.exists():
+            try:
+                with open(pkl_path, "rb") as f:
+                    self._formula_cache = pickle.load(f)
+                logger.info(
+                    "Loaded %d series entries from %s",
+                    len(self._formula_cache), pkl_path,
+                )
+            except Exception as e:
+                logger.warning("Failed to load series cache: %s", e)
+
+        self._dirty = False
+
+    def save(self) -> None:
+        """持久化当前缓存到磁盘。"""
+        if not self.config.enabled or self._cache_dir is None:
+            return
+        if not self._dirty:
+            return
+
+        self._cache_dir.mkdir(parents=True, exist_ok=True)
+
+        # 保存反馈为 JSON
+        json_path = self._cache_dir / "cache.json"
+        payload = {
+            "version": 1,
+            "created_at": time.strftime("%Y-%m-%dT%H:%M:%S"),
+            "entry_count": len(self._feedback_cache),
+            "series_count": len(self._formula_cache),
+            "entries": {
+                k: v.to_dict() for k, v in self._feedback_cache.items()
+            },
+        }
+        json_path.write_text(
+            json.dumps(payload, ensure_ascii=False, indent=2),
+            encoding="utf-8",
+        )
+
+        # 保存 Series 为 pickle
+        pkl_path = self._cache_dir / "series_cache.pkl"
+        with open(pkl_path, "wb") as f:
+            pickle.dump(self._formula_cache, f, protocol=pickle.HIGHEST_PROTOCOL)
+
+        logger.info(
+            "Saved MCTS cache: %d formulas, %d feedback entries to %s",
+            len(self._formula_cache), len(self._feedback_cache), self._cache_dir,
+        )
+        self._dirty = False
+
+    # ----------------------------------------------------------
+    # 字典式 API（直接替换 _formula_cache / _feedback_cache）
+    # ----------------------------------------------------------
+
+    def get_series(self, formula: str) -> Optional[pl.Series]:
+        """获取公式的评估结果。"""
+        return self._formula_cache.get(formula)
+
+    def put_series(self, formula: str, series: pl.Series) -> None:
+        """存储公式的评估结果。"""
+        self._formula_cache[formula] = series
+        self._dirty = True
+
+    def has_series(self, formula: str) -> bool:
+        """检查公式是否已评估。"""
+        return formula in self._formula_cache
+
+    def get_feedback(self, formula: str) -> Optional[FactorFeedback]:
+        """获取公式的 5 通道反馈。"""
+        return self._feedback_cache.get(formula)
+
+    def put_feedback(self, formula: str, fb: FactorFeedback) -> None:
+        """存储公式的 5 通道反馈。"""
+        self._feedback_cache[formula] = fb
+        self._dirty = True
+
+    def has_feedback(self, formula: str) -> bool:
+        """检查公式是否已有反馈。"""
+        return formula in self._feedback_cache
+
+    def clear(self) -> None:
+        """清空内存缓存。"""
+        self._formula_cache.clear()
+        self._feedback_cache.clear()
+        self._dirty = False
+
+    @property
+    def formula_count(self) -> int:
+        """缓存的公式数量。"""
+        return len(self._formula_cache)
+
+    @property
+    def feedback_count(self) -> int:
+        """缓存的反馈数量。"""
+        return len(self._feedback_cache)
+
+    # ----------------------------------------------------------
+    # 失效 / 清理
+    # ----------------------------------------------------------
+
+    def invalidate(self) -> None:
+        """删除当前数据集的整个缓存目录。"""
+        if self._cache_dir and self._cache_dir.exists():
+            import shutil
+            shutil.rmtree(self._cache_dir)
+            logger.info("Invalidated MCTS cache at %s", self._cache_dir)
+        self.clear()
+        self._cache_dir = None
+
+    def prune(self, keep_formulas: Set[str]) -> int:
+        """移除不在 keep_formulas 中的条目。返回移除数量。"""
+        removed = 0
+        for formula in list(self._formula_cache.keys()):
+            if formula not in keep_formulas:
+                del self._formula_cache[formula]
+                removed += 1
+        for formula in list(self._feedback_cache.keys()):
+            if formula not in keep_formulas:
+                del self._feedback_cache[formula]
+                removed += 1
+        if removed:
+            self._dirty = True
+        return removed
+
+
+__all__ = [
+    "MCTSCache",
+    "MCTSCacheConfig",
+    "DEFAULT_CACHE_ROOT",
+]