quantnodes 3.0.0__py3-none-any.whl

QuantNodes/research/factor_test/e2e/run_evolution_e2e.py

@@ -0,0 +1,309 @@
+# coding: utf-8
+"""E2E: 完整 12 节点 + 3 轮演化 + 报告生成。
+
+用法:
+    # 1. 准备数据 (HDF5)
+    python -m QuantNodes.research.factor_test.e2e.data_prep \\
+           --output-dir /tmp/e2e_data/
+
+    # 2. 运行 E2E
+    python -m QuantNodes.research.factor_test.e2e.run_evolution_e2e \\
+           --data-path /tmp/e2e_data/ \\
+           --directions momentum,reversal,volatility \\
+           --max-rounds 3
+
+输出:
+    {output_dir}/
+    ├── trajectory/                # TrajectoryPool (Parquet + JSON)
+    │   ├── trajectories.parquet
+    │   └── {entry_id}.json
+    ├── feedback.parquet           # FactorFeedback 持久化 (如启用)
+    ├── evolution_report.html      # 可视化报告
+    └── evolution_summary.json     # 演化统计
+
+E2E 验证:
+    1. PipelineRunner.from_dict() 不报错
+    2. 12 节点全部执行成功
+    3. QualityGate 拦截低质量因子
+    4. TrajectoryPool 写入 5+ entries (3 original + 1 mutation + 1 crossover)
+    5. Visualization HTML 包含 5 个 figure
+    6. RAG 评估指标 > 0 (说明检索非空)
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timedelta
+from pathlib import Path
+
+import pandas as pd
+
+from QuantNodes.core.knowledge import (
+    IdentityRetriever,
+    KnowledgeBase,
+    RAGEvaluator,
+)
+from QuantNodes.core.path_utils import ensure_dir
+from QuantNodes.core.visualization import generate_html
+from QuantNodes.research.factor_test.config import SingleFactorTestConfig
+from QuantNodes.research.factor_test.config_builder import (
+    SingleFactorTestConfigBuilder,
+)
+from QuantNodes.research.factor_test.pipeline_runner import PipelineRunner
+
+
+def _build_config(
+    data_path: str,
+    factor_name: str,
+    factor_dir: str,
+    directions: list[str],
+    output_dir: str,
+    max_rounds: int = 3,
+    enable_quality_gate: bool = True,
+) -> SingleFactorTestConfig:
+    """构造 SingleFactorTestConfig (M6: 移除未用的 enable_kb 参数)。
+
+    Phase 3.4: 改用 SingleFactorTestConfigBuilder 流式构造 (bitwise 等价)。
+    """
+    # H12: 不再硬编码 20260101/20260630, 默认 1 年前到 1 个月前 (滚动)
+    one_year_ago = int((datetime.now() - timedelta(days=365)).strftime('%Y%m%d'))
+    one_month_ago = int((datetime.now() - timedelta(days=30)).strftime('%Y%m%d'))
+    return (
+        SingleFactorTestConfigBuilder()
+        .factor(
+            factor_name, factor_dir,
+            hypothesis=directions[0] if directions else "momentum",
+            description=f"e2e test factor: {factor_name}",
+        )
+        .dates(one_year_ago, one_month_ago)
+        .adj_mode(["M", "end"])
+        .sample("all", "all")
+        .tradable(
+            no_st=True, no_suspended=True, no_up_down_limit=False,
+            min_ipo_days=360,
+        )
+        .preprocess(missing="", extreme="median", norm="zscore")
+        .neutralize(industry=False, risk=False, risk_factors=[])
+        .ic(min_group_size=5)
+        .groups(5, direction=1, floor_mode="group", hedge="equal")
+        .longshort(direction=1)
+        .score(enabled=True)
+        .risk_corr("")
+        .output(output_dir, fmt=["json"])
+        .feedback(enabled=False)
+        .quality_gate(enabled=enable_quality_gate)
+        .evolution(
+            enabled=True, max_rounds=max_rounds,
+            parent_selection_strategy="top_percent_plus_random",
+            top_percent_threshold=0.5,
+            metric="sharpe",
+            early_stop_patience=0,
+        )
+        .data_path(data_path)
+        .load_keys(
+            ["cp", "id_citic1", "mv_float", "st", "suspend", "ud_limit", "ipo_days"]
+        )
+        .build()
+    )
+
+
+
+def _inject_prepared_data(runner: PipelineRunner, data_path: Path) -> None:
+    """预填 _context['LoadData'], 跳过 LoadDataNode 真实 H5 读取。
+
+    名称: 从已 prepare 好的 H5 数据 (data_prep.py 输出) 注入到 ctx,
+    与"合成"无关 (R4 重命名: ``_inject_synthetic_data`` → ``_inject_prepared_data``).
+    """
+    # 读 H5 实际数据
+    cp = pd.read_hdf(data_path / "stk_daily.h5", key="cp")
+    st = pd.read_hdf(data_path / "stk_daily.h5", key="st")
+    suspend = pd.read_hdf(data_path / "stk_daily.h5", key="suspend")
+    ud_limit = pd.read_hdf(data_path / "stk_daily.h5", key="ud_limit")
+    ipo_days = pd.read_hdf(data_path / "stk_daily.h5", key="ipo_days")
+    industry = pd.read_hdf(data_path / "stk_daily.h5", key="id_citic1")
+    mv = pd.read_hdf(data_path / "stk_daily.h5", key="mv_float")
+    factor = pd.read_hdf(data_path / f"{runner.config.factor.name}.h5", key="data")
+    index_cp = pd.read_hdf(data_path / "index_daily.h5", key="index_cp")
+    stklist = pd.read_hdf(data_path / "stklist.h5", key="data")
+    trade_dt = pd.read_hdf(data_path / "trade_dt.h5", key="data")
+
+    runner._context["LoadData"] = {
+        "factor": factor,
+        "price": cp,
+        "id_citic1": industry,
+        "mv_float": mv,
+        "st": st,
+        "suspend": suspend,
+        "ud_limit": ud_limit,
+        "ipo_days": ipo_days,
+        "index_cp": index_cp,
+        "stklist": stklist,
+        "trade_dt": trade_dt,
+        "_loader": _build_loader(str(data_path)),
+    }
+
+
+# 向后兼容: R4 重命名前的旧名称
+_inject_synthetic_data = _inject_prepared_data
+
+
+def _build_loader(data_path: str):
+    """构造 DataLoader (供 RiskCorrelationNode 使用)。"""
+    from QuantNodes.research.factor_test.utils.data_loader import DataLoader
+    return DataLoader(data_path)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """构造 E2E 演化 CLI 参数解析器。"""
+    parser = argparse.ArgumentParser(description="E2E 演化运行")
+    parser.add_argument("--data-path", required=True, help="data_prep 输出目录")
+    parser.add_argument("--factor-name", default="momentum_20d", help="起始因子名")
+    parser.add_argument("--directions", default="momentum,reversal,volatility",
+                        help="逗号分隔的研究方向 (用作 RAG query + 初始 directions)")
+    parser.add_argument("--output-dir", default="/tmp/e2e_output/",
+                        help="输出目录 (报告 / trajectory / summary)")
+    parser.add_argument("--max-rounds", type=int, default=3)
+    parser.add_argument("--disable-quality-gate", action="store_true",
+                        help="禁用 QualityGate (默认启用)")
+    # M22-M23: 演化参数可配置 (默认保持原有值不变)
+    parser.add_argument("--rag-top-k", type=int, default=3,
+                        help="RAG 检索 Top-K (默认 3)")
+    parser.add_argument("--ancestor-depth", type=int, default=2,
+                        help="知识谱系祖先深度 (默认 2)")
+    parser.add_argument("--descendant-depth", type=int, default=2,
+                        help="知识谱系列脉深度 (默认 2)")
+    parser.add_argument("--no-compress", action="store_true",
+                        help="禁用谱系压缩 (默认启用)")
+    return parser
+
+
+def main():
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    data_path = Path(args.data_path)
+    output_dir = Path(args.output_dir)
+    ensure_dir(output_dir)
+    directions = [d.strip() for d in args.directions.split(",") if d.strip()]
+
+    print("=" * 70)
+    print("E2E 演化实验")
+    print(f"  data_path:  {data_path}")
+    print(f"  output_dir: {output_dir}")
+    print(f"  directions: {directions}")
+    print(f"  max_rounds: {args.max_rounds}")
+    print("=" * 70)
+
+    # 1. 构造 config + runner
+    cfg = _build_config(
+        data_path=str(data_path),
+        factor_name=args.factor_name,
+        factor_dir=f"{args.factor_name}.h5",
+        directions=directions,
+        output_dir=str(output_dir),
+        max_rounds=args.max_rounds,
+        enable_quality_gate=not args.disable_quality_gate,
+    )
+    runner = PipelineRunner(cfg)
+    _inject_prepared_data(runner, data_path)
+    print(f"\n[1/5] 注入 LoadData: factor={runner._context['LoadData']['factor'].shape}")
+
+    # 2. 先单次回测 (验证 12 节点)
+    print("\n[2/5] 单次回测 (验证 12 节点 + QualityGate)...")
+    try:
+        ctx = runner.run()
+        print(f"  ✓ 12 节点全部执行, ctx keys: {list(ctx.keys())}")
+        # 打印 IC
+        if "ICAnalyzer" in ctx:
+            ic_res = ctx["ICAnalyzer"].get("ic_result", {})
+            print(f"  IC均值: {ic_res.get('IC均值', 'N/A')}")
+    except Exception as e:
+        print(f"  ✗ 单次回测失败: {e}")
+        return 1
+
+    # 3. 设置演化组件
+    print("\n[3/5] 构造演化组件...")
+    pool = runner._build_trajectory_pool()
+    quality_gate = runner._build_quality_gate()
+
+    kb = KnowledgeBase(IdentityRetriever(), pool=pool)
+    evaluator = RAGEvaluator()
+    print(f"  ✓ TrajectoryPool: {pool.base_dir}")
+    print(f"  ✓ QualityGateNode: {'enabled' if quality_gate else 'disabled'}")
+    print("  ✓ KnowledgeBase + RAGEvaluator (TF-IDF always enabled)")
+
+    # 4. 演化循环
+    print(f"\n[4/5] 演化循环 ({args.max_rounds} 轮)...")
+    from QuantNodes.core.evolution import EvolutionLoop, EvolutionSetting as ES
+    settings = ES(
+        enabled=True, max_rounds=args.max_rounds,
+        parent_selection_strategy="top_percent_plus_random",
+        top_percent_threshold=0.5,
+        metric="sharpe", seed=42,
+    )
+    loop = EvolutionLoop(
+        settings, pool=pool,
+        quality_gate=quality_gate,
+        evaluate_fn=runner._evaluate_candidate,
+        knowledge_base=kb,
+        rag_evaluator=evaluator,
+        rag_top_k=args.rag_top_k,
+        max_ancestor_depth=args.ancestor_depth,
+        max_descendant_depth=args.descendant_depth,
+        use_compress=not args.no_compress,
+    )
+    result = loop.run(initial_directions=directions)
+    print(
+        f"  ✓ 演化完成: {result.rounds_completed} 轮, "
+        f"总数 {result.total_count}, 拒绝 {result.rejected_count}"
+    )
+    if kb is not None:
+        print(f"  ✓ KB 已索引 {len(kb)} entry")
+    print(f"  ✓ RAG 评估历史: {len(loop.rag_metrics_history)} 轮")
+    if loop.rag_metrics_history:
+        m = loop.rag_metrics_history[-1]
+        print(f"    Round {m['round']}: HR@5={m['hit_at_5']:.3f} NDCG@5={m['ndcg_at_5']:.3f}")
+
+    # 5. 报告生成
+    print("\n[5/5] 生成报告...")
+    report_path = output_dir / "evolution_report.html"
+    try:
+        generate_html(pool, metric="sharpe",
+                      title=f"E2E 演化报告: {data_path.name}",
+                      output_path=report_path)
+        print(f"  ✓ HTML 报告: {report_path} ({report_path.stat().st_size} bytes)")
+    except Exception as e:
+        print(f"  ✗ HTML 报告失败: {e}")
+
+    summary = {
+        "data_path": str(data_path),
+        "output_dir": str(output_dir),
+        "directions": directions,
+        "max_rounds": args.max_rounds,
+        "pool_size": pool.size,
+        "rounds_completed": result.rounds_completed,
+        "total_count": result.total_count,
+        "rejected_count": result.rejected_count,
+        "best_entries": [
+            {
+                "id": e.entry_id,
+                "name": e.feedback.factor_name if e.feedback else "",
+                "operation": e.operation,
+                "round": e.round_idx,
+                "sharpe": (e.metrics or {}).get("sharpe", 0),
+            }
+            for e in result.best_entries[:5]
+        ],
+        "rag_metrics_history": loop.rag_metrics_history,
+    }
+    summary_path = output_dir / "evolution_summary.json"
+    summary_path.write_text(json.dumps(summary, ensure_ascii=False, indent=2))
+    print(f"  ✓ JSON 摘要: {summary_path}")
+
+    print(f"\n{'=' * 70}\n✓ E2E 完成\n{'=' * 70}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

QuantNodes/research/factor_test/evolution_adapter.py

@@ -0,0 +1,231 @@
+# coding: utf-8
+"""演化适配器 / Evolution Adapter.
+
+把 ``PipelineRunner`` 与 ``QuantNodes.core.evolution`` 框架对接:
+
+- 构造 ``QualityGateNode`` (按 ``cfg.quality_gate.enabled``)
+- 构造 ``TrajectoryPool`` (按 ``cfg.evolution.enabled``)
+- 构造 ``EvolutionLoop`` (含 evaluate_fn)
+- ``evaluate_candidate`` / ``run_one_factor`` 子例程
+- ``run_evolution`` 主入口 (含 ProcessPool 快照预序列化 + Streaming 集成)
+
+Phase R2 (2026-06-19): 从 pipeline_runner.py 抽出, 单一职责.
+"""
+
+from __future__ import annotations
+
+import logging
+from contextlib import contextmanager
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional
+
+from QuantNodes.core.evolution import (
+    EvolutionLoop,
+    EvolutionResult,
+    EvolutionSetting,
+    FactorCandidate,
+)
+from QuantNodes.core.feedback import FactorFeedback
+from QuantNodes.core.monitoring import MetricCollector, generate_dashboard_html
+from QuantNodes.core.parallel.worker_process import prepare_snapshot
+from QuantNodes.core.quality_gate import (
+    FactorZoo,
+    QualityGateNode,
+    QualityGateSetting,
+)
+from QuantNodes.core.trajectory import TrajectoryPool
+from QuantNodes.research.factor_test.utils.metrics_extractor import (
+    extract_metrics_from_ctx,
+)
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from QuantNodes.research.factor_test.pipeline_runner import PipelineRunner
+
+
+def build_quality_gate(runner: "PipelineRunner") -> Optional[QualityGateNode]:
+    """根据 ``cfg.quality_gate.enabled`` 构造 ``QualityGateNode``."""
+    if not runner.config.quality_gate.enabled:
+        return None
+    zoo_path = (
+        Path(runner.config.quality_gate.zoo_path)
+        if runner.config.quality_gate.zoo_path
+        else None
+    )
+    zoo = FactorZoo(zoo_path) if zoo_path is not None else FactorZoo()
+    return QualityGateNode(QualityGateSetting(), zoo=zoo)
+
+
+def build_trajectory_pool(runner: "PipelineRunner") -> Optional[TrajectoryPool]:
+    """根据 ``cfg.evolution.enabled`` 构造 ``TrajectoryPool``."""
+    if not runner.config.evolution.enabled:
+        return None
+    if runner.config.evolution.pool_dir:
+        base = Path(runner.config.evolution.pool_dir)
+    else:
+        base = Path(runner.config.output.dir) / "trajectory"
+    return TrajectoryPool(base)
+
+
+def build_evolution_loop(
+    runner: "PipelineRunner",
+    pool: TrajectoryPool,
+    quality_gate: Optional[QualityGateNode],
+    workers: int = 1,
+) -> EvolutionLoop:
+    """构造 ``EvolutionLoop``, evaluate_fn 委托给 ``runner._evaluate_candidate``."""
+    settings = EvolutionSetting(
+        enabled=True,
+        max_rounds=runner.config.evolution.max_rounds,
+        parents_per_round=runner.config.evolution.parents_per_round,
+        parent_selection_strategy=runner.config.evolution.parent_selection_strategy,
+        top_percent_threshold=runner.config.evolution.top_percent_threshold,
+        metric=runner.config.evolution.metric,
+        early_stop_patience=runner.config.evolution.early_stop_patience,
+    )
+    return EvolutionLoop(
+        settings=settings,
+        pool=pool,
+        quality_gate=quality_gate,
+        evaluate_fn=runner._evaluate_candidate,
+        workers=workers,
+    )
+
+
+def evaluate_candidate(
+    runner: "PipelineRunner",
+    candidate: FactorCandidate,
+) -> tuple[bool, dict, FactorFeedback]:
+    """``EvolutionLoop`` 评估回调: 单次回测 + metrics + feedback.
+
+    Returns:
+        ``(passed, metrics, feedback)``
+    """
+    if not isinstance(candidate, FactorCandidate):
+        raise TypeError(f"expected FactorCandidate, got {type(candidate)}")
+
+    try:
+        ctx = run_one_factor(runner, candidate)
+    except Exception as e:  # noqa: BLE001
+        return False, {}, FactorFeedback(
+            factor_id=candidate.factor_id,
+            factor_name=candidate.name,
+            decision=False,
+            summary=f"evaluate failed: {e}",
+        )
+
+    passed = bool(ctx.get("status") != "rejected")
+    metrics = extract_metrics_from_ctx(ctx)
+    factor_id = str(candidate.factor_id)
+    factor_name = str(candidate.name)
+    feedback = FactorFeedback(
+        factor_id=factor_id,
+        factor_name=factor_name,
+        decision=passed,
+        summary="ok" if passed else "rejected",
+        metadata=metrics,
+    )
+    if runner.config.feedback.enabled and "Feedback" in ctx:
+        for node_fb in ctx["Feedback"].values():
+            for ch, ch_fb in node_fb.channels.items():
+                feedback.channels[ch] = ch_fb
+    return passed, metrics, feedback
+
+
+def run_one_factor(runner: "PipelineRunner", candidate: FactorCandidate) -> dict:
+    """执行单次回测 (12 节点), 临时把 candidate 的 expression / name 注入 ``cfg.factor``.
+
+    不写 TrajectoryPool, 仅返回 ctx.
+    """
+    if not isinstance(candidate, FactorCandidate):
+        raise TypeError(f"expected FactorCandidate, got {type(candidate)}")
+    with override_factor_config(runner, candidate):
+        return runner.run()
+
+
+@contextmanager
+def override_factor_config(runner: "PipelineRunner", candidate: FactorCandidate):
+    """Temporarily replace runner.config.factor.name (and expression if empty).
+
+    Phase J5 (2026-06-20): extracts the mutate-and-restore pattern from
+    run_one_factor() into a reusable context manager. Future callers
+    that need the same override (e.g. CLI flags, parallel workers) can
+    reuse without re-implementing the cleanup logic.
+    """
+    cfg = runner.config.factor
+    orig_name = cfg.name
+    cfg.name = candidate.name
+    if not getattr(cfg, "expression", ""):
+        try:
+            cfg.expression = candidate.expression  # type: ignore[attr-defined]
+        except Exception:
+            pass
+    try:
+        yield
+    finally:
+        cfg.name = orig_name
+
+
+def run_evolution(
+    runner: "PipelineRunner",
+    initial_directions: list[str] | None = None,
+    initial_candidates: list[FactorCandidate] | None = None,
+    workers: int = 1,
+) -> EvolutionResult:
+    """多轮演化主入口.
+
+    Args:
+        runner: ``PipelineRunner`` 实例
+        initial_directions: round 0 用的研究假设列表 (Hypothesizer 处理)
+        initial_candidates: round 0 用的直接候选 (跳过 Hypothesizer)
+        workers: 并行数 (1=串行, >1=ThreadPool/ProcessPool 并行)
+
+    Returns:
+        ``EvolutionResult``: best entries + 统计
+
+    Raises:
+        ValueError: ``cfg.evolution.enabled=False``
+    """
+    if not runner.config.evolution.enabled:
+        raise ValueError("config.evolution.enabled=False, 无法运行演化")
+
+    pool = build_trajectory_pool(runner)
+    quality_gate = build_quality_gate(runner)
+    loop = build_evolution_loop(runner, pool, quality_gate, workers=workers)
+
+    # workers > 1 + 有 _loader → 预序列化供 ProcessPool
+    if workers > 1 and "_loader" in runner._context.get("LoadData", {}):
+        snapshot = prepare_snapshot(
+            runner.config, runner._context,
+            factor_path=getattr(runner.config.factor, "factor_dir", None),
+        )
+        snap_path = Path(pool.base_dir) / "_snapshot.pkl"
+        snapshot.save(snap_path)
+        loop.snapshot_path = str(snap_path)
+        logger.info("  [ProcessPool] 预序列化快照: %s", snap_path)
+
+    # 连接 MetricCollector (streaming)
+    collector = MetricCollector()
+    loop.metric_collector = collector
+
+    result = loop.run(
+        initial_directions=initial_directions,
+        initial_candidates=initial_candidates,
+    )
+
+    # 演化结束后, 追加写入 JSON + 生成 streaming dashboard
+    if pool.size > 0:
+        metrics_json = pool.base_dir / "metrics.json"
+        collector.append_json(metrics_json)
+        logger.info("  [Streaming] 指标追加: %s", metrics_json)
+        dashboard_html = pool.base_dir.parent / "dashboard_streaming.html"
+        generate_dashboard_html(
+            collector,
+            title=f"演化 Dashboard (Streaming): {runner.config.factor.name}",
+            output_path=str(dashboard_html),
+            streaming=True,
+        )
+        logger.info("  [Streaming] Dashboard: %s", dashboard_html)
+
+    return result

QuantNodes/research/factor_test/feedback_wrapper.py

@@ -0,0 +1,102 @@
+# coding: utf-8
+"""FactorFeedback 包装器 / Feedback Wrapper.
+
+把 5 个分析节点 (IC/Group/LongShort/Score/RiskCorrelation) 的返回值
+统一包装成 ``FactorFeedback`` 对象, 聚合到 ``ctx['Feedback']``,
+并可选持久化到 Parquet.
+
+Phase R2 (2026-06-19): 从 pipeline_runner.py 抽出, 单一职责.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from QuantNodes.core.feedback import (
+    FactorFeedback,
+    FeedbackChannel,
+    FeedbackCollector,
+    LLMJudge,
+    ensure_feedback,
+)
+from QuantNodes.core.path_utils import ensure_dir
+from QuantNodes.research.factor_test.config import SingleFactorTestConfig
+
+
+ANALYSIS_NODES: tuple[str, ...] = (
+    "ICAnalyzer", "GroupAnalyzer", "LongShort", "FactorScore", "RiskCorrelation",
+)
+
+
+def build_feedback(
+    ctx: dict,
+    factor_id: str,
+    factor_name: str,
+    cfg: SingleFactorTestConfig,
+    judge: Optional[LLMJudge],
+) -> dict[str, FactorFeedback]:
+    """包装 5 个分析节点返回值为 FactorFeedback.
+
+    包装策略:
+        - 节点返回 dict → ``ensure_feedback()`` 创建 metadata-only FactorFeedback
+        - 节点已是 FactorFeedback → 直接用其 channels
+        - 都通过同一个 FeedbackCollector 聚合, 共享 ``factor_id``
+        - ``judge`` 不为 None 时追加 LLM 一致性通道
+    """
+    feedbacks: dict[str, FactorFeedback] = {}
+    for node_name in ANALYSIS_NODES:
+        result = ctx.get(node_name)
+        if result is None:
+            continue
+        collector = FeedbackCollector(factor_id, factor_name)
+        fb = ensure_feedback(result, factor_id, factor_name)
+        for _ch, ch_fb in fb.channels.items():
+            collector.add_feedback(ch_fb)
+        if not fb.channels:
+            collector.add(
+                channel=FeedbackChannel.VALUE,
+                passed=fb.decision,
+                detail=fb.summary or f"{node_name} 节点无显式通道反馈",
+                score=1.0 if fb.decision else 0.0,
+            )
+        if judge is not None:
+            hypothesis = getattr(cfg.factor, "hypothesis", "") or ""
+            description = getattr(cfg.factor, "description", "") or ""
+            expression = getattr(cfg.factor, "expression", "") or ""
+            if hypothesis or description or expression:
+                llm_fb = judge.judge(hypothesis, description, expression)
+                collector.add_feedback(llm_fb)
+        feedbacks[node_name] = collector.finalize(
+            summary=fb.summary or f"{node_name} 节点执行完成",
+        )
+    return feedbacks
+
+
+def maybe_persist_feedback(
+    feedbacks: dict[str, FactorFeedback],
+    cfg: SingleFactorTestConfig,
+) -> None:
+    """可选: 持久化 Feedback 到 Parquet.
+
+    Args:
+        feedbacks: ``build_feedback`` 返回的 dict
+        cfg: SingleFactorTestConfig, 需 ``cfg.feedback.output_dir`` 不为 None
+    """
+    if cfg.feedback.output_dir is None:
+        return
+    out = Path(cfg.feedback.output_dir)
+    ensure_dir(out)
+    parquet_path = out / "feedback.parquet"
+    for node_name, fb in feedbacks.items():
+        fb.save_parquet(parquet_path)
+
+
+def maybe_build_judge(cfg: SingleFactorTestConfig) -> Optional[LLMJudge]:
+    """若 ``cfg.feedback.judge_enabled`` 为 True, 构建 LLMJudge; 否则 None."""
+    if not cfg.feedback.judge_enabled:
+        return None
+    return LLMJudge(
+        model=cfg.feedback.judge_model,
+        max_correction_attempts=cfg.feedback.judge_max_attempts,
+    )

QuantNodes/research/factor_test/ifind_db/__init__.py

@@ -0,0 +1,7 @@
+# coding: utf-8
+"""iFinD Database - 包装同花顺 iFinD API 为 DataLoader 兼容接口"""
+
+from .ifind_database import IFinDDatabase
+from .fetcher import IFindFetcher, IFindFetcherStub
+
+__all__ = ['IFinDDatabase', 'IFindFetcher', 'IFindFetcherStub']