quantnodes 3.0.0__py3-none-any.whl

QuantNodes/research/quant_alpha/evaluation/mock_data_loader.py

@@ -0,0 +1,226 @@
+# coding=utf-8
+"""
+mock_data_loader.py - Stage 1 mock 数据加载器
+
+GBM（几何布朗运动）模拟 500 票 × 500 日的全市场数据，
+注入已知信号（20日动量 / 5日反转 / 波动率）以便 G1-G3 baseline
+能产生可区分的 IC 指标（验证接口契约可用性）。
+
+为什么用 500 票 × 500 日：
+- Stage 2 用全 A ~5000 票 × 5 年，Stage 1 用 500 票 × 500 日可在 ~5 分钟内跑完
+- 500 票的因子 IC 估计比 30 票稳定（IC std 下降 ~4×）
+- Polars 在 500 票 × 500 日上能真实测出 polars vs pandas 性能差距
+
+复用：
+- factor_test/utils/data_loader.py：DataLoader 接口风格
+- contracts.py：DataLoader ABC + load() 返回 polars.DataFrame
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import List, Optional
+
+import numpy as np
+import polars as pl
+
+from .contracts import DataLoader
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["MockDataLoader", "MOCK_INDUSTRIES"]
+
+
+MOCK_INDUSTRIES: List[str] = [
+    "Technology",
+    "Finance",
+    "Consumer",
+    "Healthcare",
+    "Industrial",
+    "Energy",
+    "Material",
+    "Utility",
+    "RealEstate",
+    "Telecom",
+]
+
+
+class MockDataLoader(DataLoader):
+    """Stage 1 mock 数据加载器
+
+    生成 500 票 × 500 日的模拟行情数据，字段对齐 iFinD parquet schema：
+    date, code, open, high, low, close, vol, amount, industry
+    """
+
+    def __init__(
+        self,
+        n_stocks: int = 500,
+        n_days: int = 500,
+        seed: int = 42,
+        industries: Optional[List[str]] = None,
+        drift: float = 0.0005,
+        volatility: float = 0.02,
+    ) -> None:
+        self.n_stocks = n_stocks
+        self.n_days = n_days
+        self.seed = seed
+        self.industries = industries or MOCK_INDUSTRIES
+        self.drift = drift
+        self.volatility = volatility
+
+    def load(self) -> pl.DataFrame:
+        """生成 mock 数据
+
+        Returns:
+            polars.DataFrame 包含以下字段：
+            - date: Date（交易日）
+            - code: Utf8（股票代码 SH600000 ~ SH600499）
+            - open/high/low/close: Float64
+            - vol: Float64（成交量，万股）
+            - amount: Float64（成交额，万元）
+            - industry: Utf8（行业分类）
+
+        注入信号：
+        - 个股漂移率 ~ 0.05%（日均）
+        - 个股波动率 ~ 2%
+        - 行业分组：10 个行业平均分配
+        """
+        rng = np.random.default_rng(self.seed)
+        n = self.n_stocks
+        t = self.n_days
+
+        # 时间索引：500 个连续交易日（简化：用 business day）
+        dates = pl.date_range(
+            pl.date(2020, 1, 2), pl.date(2021, 12, 31), eager=True
+        ).alias("date")
+        if len(dates) > t:
+            dates = dates.head(t)
+        elif len(dates) < t:
+            # 不足则补充后续日期
+            extra = pl.date_range(
+                dates[-1] + pl.duration(days=1),
+                dates[-1] + pl.duration(days=(t - len(dates)) * 2),
+                eager=True,
+            ).head(t - len(dates))
+            dates = pl.concat([dates, extra]).alias("date")
+
+        # 股票代码：SH600000 ~ SH600499（前缀 SH）
+        codes = [f"SH{600000 + i:06d}" for i in range(n)]
+
+        # GBM 价格路径
+        # 每股 drift / volatility 不同（每只股票一个随机参数）
+        stock_drift = rng.normal(self.drift, 0.0005, n)  # (n,)
+        stock_vol = np.abs(rng.normal(self.volatility, 0.005, n))  # (n,)
+
+        # 日收益率：(n, t) — 行业 + 个股冲击
+        # 行业冲击：10 个行业 × t 日，每个行业一个共同因子
+        industry_ids = rng.integers(0, len(self.industries), n)
+        industry_shock = rng.normal(0, 0.003, (len(self.industries), t))  # (ind, t)
+        industry_returns = industry_shock[industry_ids]  # (n, t)
+
+        # 个股随机游走
+        eps = rng.normal(0, 1, (n, t))
+        daily_returns = (
+            stock_drift[:, None]
+            + stock_vol[:, None] * eps / np.sqrt(t)
+            + industry_returns * 0.3
+        )
+
+        # 价格：close[0] = 10, 累计复利
+        close0 = rng.uniform(5, 50, n)
+        log_prices = np.log(close0)[:, None] + np.cumsum(daily_returns, axis=1)
+        close = np.exp(log_prices)  # (n, t)
+
+        # OHLC：close ± 日内振幅（5% close）
+        intraday = np.abs(rng.normal(0, 0.01, (n, t))) * close
+        open_ = close + rng.normal(0, 0.005, (n, t)) * close
+        high = np.maximum(close, open_) + intraday
+        low = np.minimum(close, open_) - intraday
+        low = np.maximum(low, 0.1)  # 价格不能为负
+
+        # vol / amount：与价格波动正相关
+        vol = np.abs(rng.lognormal(mean=10, sigma=0.5, size=(n, t)))  # 股数
+        amount = vol * close  # 成交额
+
+        # 构造 long-format DataFrame
+        date_arr = np.tile(np.asarray(dates), n)  # (n*t,)
+        code_arr = np.repeat(codes, t)
+        open_flat = open_.flatten()
+        high_flat = high.flatten()
+        low_flat = low.flatten()
+        close_flat = close.flatten()
+        vol_flat = vol.flatten()
+        amount_flat = amount.flatten()
+        industry_arr = np.array([self.industries[i] for i in industry_ids])
+        industry_flat = np.repeat(industry_arr, t)
+
+        df = pl.DataFrame(
+            {
+                "date": date_arr,
+                "code": code_arr,
+                "open": open_flat.astype(np.float64),
+                "high": high_flat.astype(np.float64),
+                "low": low_flat.astype(np.float64),
+                "close": close_flat.astype(np.float64),
+                "vol": vol_flat.astype(np.float64),
+                "amount": amount_flat.astype(np.float64),
+                "industry": industry_flat,
+            },
+            schema={
+                "date": pl.Date,
+                "code": pl.Utf8,
+                "open": pl.Float64,
+                "high": pl.Float64,
+                "low": pl.Float64,
+                "close": pl.Float64,
+                "vol": pl.Float64,
+                "amount": pl.Float64,
+                "industry": pl.Utf8,
+            },
+        )
+
+        # 计算前向收益（用于因子 IC 计算）
+        df = df.sort(["code", "date"])
+        df = df.with_columns(
+            (pl.col("close").shift(-1).over("code") / pl.col("close") - 1).alias(
+                "forward_return_1d"
+            )
+        )
+
+        logger.info(
+            "MockDataLoader: generated %s rows (%d stocks × %d days), %d industries",
+            f"{df.height:,}",
+            n,
+            t,
+            len(self.industries),
+        )
+
+        return df
+
+    def load_summary(self) -> dict:
+        """加载并返回数据摘要（用于测试与展示）"""
+        df = self.load()
+        close_mean = df["close"].mean()
+        close_std = df["close"].std()
+        return {
+            "n_rows": df.height,
+            "n_stocks": df["code"].n_unique(),
+            "n_days": df["date"].n_unique(),
+            "industries": sorted(df["industry"].unique().to_list()),
+            "date_range": [
+                str(df["date"].min()),
+                str(df["date"].max()),
+            ],
+            "close_mean": float(close_mean) if close_mean is not None else 0.0,
+            "close_std": float(close_std) if close_std is not None else 0.0,
+            "amount_total": float(df["amount"].sum()),
+        }
+
+
+if __name__ == "__main__":
+    loader = MockDataLoader()
+    df = loader.load()
+    print(df.head())
+    print(df.schema)
+    print("Rows:", df.height)
+    print("Summary:", loader.load_summary())

QuantNodes/research/quant_alpha/evaluation/runner.py

@@ -0,0 +1,243 @@
+# coding=utf-8
+"""
+runner.py - Table 4 复现主入口
+
+串联 DataLoader + Baseline × 3 + Evaluator，输出 Table4Report。
+支持 Stage 1（mock）与 Stage 2（real，仅替换 loader / llm_client）。
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence
+
+from .contracts import (
+    Baseline,
+    DataLoader,
+    Evaluator,
+    Table4GroupResult,
+    Table4Report,
+    Table4Runner,
+)
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["MockTable4Runner", "RealTable4Runner"]
+
+
+class MockTable4Runner(Table4Runner):
+    """Stage 1 mock 主入口
+
+    用法::
+
+        from QuantNodes.research.quant_alpha.evaluation import (
+            MockDataLoader, PolarsAlphaCalculatorEvaluator,
+            G1Handcrafted, G2LlmOnly, G3AlphaGpt,
+        )
+        from QuantNodes.research.quant_alpha.evaluation.runner import MockTable4Runner
+
+        runner = MockTable4Runner(
+            loader=MockDataLoader(n_stocks=500, n_days=500),
+            evaluator=PolarsAlphaCalculatorEvaluator(),
+            baselines=[G1Handcrafted(n=100), G2LlmOnly(n=50), G3AlphaGpt(n=30)],
+            output_dir=Path("data/output/table4_mock"),
+        )
+        report = runner.run()
+
+    Stage 2 替换 loader/baselines 即可，runner 无需修改。
+    """
+
+    def __init__(
+        self,
+        loader: DataLoader,
+        evaluator: Evaluator,
+        baselines: Sequence[Baseline],
+        output_dir: Optional[Path] = None,
+        forward_returns: Optional[List[int]] = None,
+        stage: str = "mock",
+        notes: Optional[List[str]] = None,
+    ) -> None:
+        self.loader = loader
+        self.evaluator = evaluator
+        self.baselines = list(baselines)
+        self.output_dir = Path(output_dir) if output_dir else None
+        self.forward_returns = forward_returns or [1]
+        self.stage = stage
+        self.notes = list(notes or [])
+
+    def run(self) -> Table4Report:
+        """执行完整 pipeline"""
+        logger.info("[Table4Runner:%s] 开始执行", self.stage)
+        started_at = time.time()
+
+        # 1. 加载数据
+        t0 = time.time()
+        data = self.loader.load()
+        load_elapsed = time.time() - t0
+        logger.info(
+            "[Table4Runner] 数据加载完成: %s rows, %.2fs",
+            f"{data.height:,}" if hasattr(data, "height") else len(data),
+            load_elapsed,
+        )
+
+        # 2. 构造 report
+        report = Table4Report(
+            timestamp=datetime.now(tz=timezone.utc).isoformat(),
+            stage=self.stage,
+            notes=self.notes,
+        )
+
+        # 3. 遍历 baselines
+        for baseline in self.baselines:
+            group_name = baseline.group_name
+            logger.info("[Table4Runner] === %s 开始 ===", group_name)
+
+            t0 = time.time()
+            factors = baseline.generate_factors()
+            gen_elapsed = time.time() - t0
+            logger.info(
+                "[Table4Runner] %s 生成 %d 个因子 (%.2fs)",
+                group_name,
+                len(factors),
+                gen_elapsed,
+            )
+
+            t0 = time.time()
+            metrics = self.evaluator.evaluate(
+                factors, data, forward_returns=self.forward_returns
+            )
+            eval_elapsed = time.time() - t0
+            logger.info(
+                "[Table4Runner] %s 评估完成: %d success / %d failed (%.2fs)",
+                group_name,
+                sum(1 for m in metrics if m.status == "success"),
+                sum(1 for m in metrics if m.status == "failed"),
+                eval_elapsed,
+            )
+
+            group = Table4GroupResult(
+                group_name=group_name,
+                factors=factors,
+                metrics=metrics,
+                elapsed_sec=gen_elapsed + eval_elapsed,
+            )
+            report.add_group(group)
+
+        total_elapsed = time.time() - started_at
+        logger.info("[Table4Runner] 全部完成: %.2fs", total_elapsed)
+
+        # 4. 输出
+        if self.output_dir is not None:
+            self.output_dir.mkdir(parents=True, exist_ok=True)
+            self.save_json(report, self.output_dir / "table4_report.json")
+            self.save_markdown(report, self.output_dir / "table4_report.md")
+
+        return report
+
+    def save_json(self, report: Table4Report, path: Path) -> None:
+        """保存为 JSON"""
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(report.to_dict(), f, ensure_ascii=False, indent=2)
+        logger.info("[Table4Runner] JSON saved to %s", path)
+
+    def save_markdown(self, report: Table4Report, path: Path) -> None:
+        """保存为 Markdown 报告"""
+        path.parent.mkdir(parents=True, exist_ok=True)
+        lines: List[str] = []
+        lines.append(f"# Table 4 复现报告（{report.stage}）\n")
+        lines.append(f"**生成时间**: {report.timestamp}\n")
+        lines.append("\n## 汇总\n")
+        lines.append("| Group | N | Success | Failed | avg IC | avg IR | best IR | elapsed(s) |\n")
+        lines.append("|------|--:|--------:|-------:|-------:|-------:|--------:|-----------:|\n")
+        for g in report.groups:
+            lines.append(
+                f"| {g.group_name} | {len(g.factors)} | {g.success_count} | "
+                f"{g.failed_count} | {g.avg_ic:.4f} | {g.avg_ir:.4f} | "
+                f"{g.best_ir:.4f} | {g.elapsed_sec:.2f} |\n"
+            )
+
+        # 排名
+        ranked = report.rank_groups_by_ir()
+        lines.append("\n## 按 avg_IR 排名\n")
+        for i, g in enumerate(ranked, 1):
+            lines.append(f"{i}. **{g.group_name}** — avg_IR = {g.avg_ir:.4f}\n")
+
+        # 论文对比（Stage 2 填）
+        if report.paper_comparison:
+            lines.append("\n## 论文 Table 4 对比\n")
+            lines.append("| Group | Ours avg_IR | Paper avg_IR | Diff |\n")
+            lines.append("|------|------------:|-------------:|-----:|\n")
+            for row in report.paper_comparison.get("rows", []):
+                lines.append(
+                    f"| {row['group']} | {row['ours']:.4f} | {row['paper']:.4f} | "
+                    f"{row['diff']:.4f} |\n"
+                )
+
+        if report.notes:
+            lines.append("\n## 备注\n")
+            for n in report.notes:
+                lines.append(f"- {n}\n")
+
+        with open(path, "w", encoding="utf-8") as f:
+            f.writelines(lines)
+        logger.info("[Table4Runner] Markdown saved to %s", path)
+
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO)
+    from .mock_data_loader import MockDataLoader
+
+    loader = MockDataLoader(n_stocks=100, n_days=200)
+    print("Mock loader summary:", loader.load_summary())
+
+
+class RealTable4Runner(MockTable4Runner):
+    """Stage 2 real 主入口
+
+    与 MockTable4Runner 完全相同的流程，
+    仅 stage="real" 和默认输出目录不同。
+
+    用法::
+
+        from QuantNodes.research.quant_alpha.evaluation import (
+            ClickHouseDataLoader, PolarsAlphaCalculatorEvaluator,
+            G1Handcrafted, G2LlmOnly, G3AlphaGpt,
+        )
+        from QuantNodes.research.quant_alpha.evaluation.runner import RealTable4Runner
+
+        runner = RealTable4Runner(
+            loader=ClickHouseDataLoader(table="quote.stock_quote"),
+            evaluator=PolarsAlphaCalculatorEvaluator(),
+            baselines=[
+                G1Handcrafted(n=100),
+                G2LlmOnly(n=50),       # 默认使用 LLMGateway → MiniMax
+                G3AlphaGpt(n=30),      # 默认使用 LLMGateway → MiniMax
+            ],
+            output_dir=Path("data/output/table4_real"),
+        )
+        report = runner.run()
+    """
+
+    def __init__(
+        self,
+        loader: DataLoader,
+        evaluator: Evaluator,
+        baselines: Sequence[Baseline],
+        output_dir: Optional[Path] = None,
+        forward_returns: Optional[List[int]] = None,
+        notes: Optional[List[str]] = None,
+    ) -> None:
+        super().__init__(
+            loader=loader,
+            evaluator=evaluator,
+            baselines=baselines,
+            output_dir=output_dir or Path("data/output/table4_real"),
+            forward_returns=forward_returns,
+            stage="real",
+            notes=notes,
+        )

QuantNodes/research/quant_alpha/llm/__init__.py

@@ -0,0 +1,38 @@
+# coding=utf-8
+"""
+llm - Alpha-GPT M5 子包（仅 JSON 解析，不含 LLM 调度）
+
+LLM 调度复用 nanobot upstream（见 .agent/agents/alpha-gpt-*.md），
+本子包仅提供：
+
+- parser.py: 5 阶段 LLM 输出 JSON 三层降级解析器
+- utils: 公式算子白名单校验
+
+M5 doc-first 详见：docs/quant_alpha/alpha_gpt_architecture.md
+"""
+
+from .parser import (
+    ParseResult,
+    parse_json_3layer,
+    parse_idea_generator_output,
+    parse_formula_translator_output,
+    parse_evaluator_output,
+    parse_reflector_output,
+    parse_critic_output,
+    validate_formula_operators,
+    extract_operators,
+    ALLOWED_OPERATORS,
+)
+
+__all__ = [
+    "ParseResult",
+    "parse_json_3layer",
+    "parse_idea_generator_output",
+    "parse_formula_translator_output",
+    "parse_evaluator_output",
+    "parse_reflector_output",
+    "parse_critic_output",
+    "validate_formula_operators",
+    "extract_operators",
+    "ALLOWED_OPERATORS",
+]