quantnodes 3.0.0__py3-none-any.whl

QuantNodes/core/feedback/__init__.py

@@ -0,0 +1,38 @@
+"""FactorFeedback — 结构化反馈框架。
+
+公开 API:
+    - FeedbackChannel (Enum): 5 通道
+    - ChannelFeedback (dataclass): 单通道信号
+    - FactorFeedback (dataclass): 完整反馈
+    - FeedbackCollector: 聚合器
+    - LLMJudge: LLM 一致性评判
+    - ensure_feedback: dict → FactorFeedback 包装
+    - collect_execution / collect_shape / collect_code / collect_value: 4 通道采集器
+"""
+from .dataclass import (
+    ChannelFeedback,
+    FactorFeedback,
+    FeedbackChannel,
+    ensure_feedback,
+)
+from .collector import FeedbackCollector
+from .llm_judge import LLMJudge
+from .channels import (
+    collect_execution,
+    collect_shape,
+    collect_code,
+    collect_value,
+)
+
+__all__ = [
+    "FeedbackChannel",
+    "ChannelFeedback",
+    "FactorFeedback",
+    "FeedbackCollector",
+    "LLMJudge",
+    "ensure_feedback",
+    "collect_execution",
+    "collect_shape",
+    "collect_code",
+    "collect_value",
+]

QuantNodes/core/feedback/channels.py

@@ -0,0 +1,182 @@
+"""4 通道反馈采集器: execution / shape / code / value。
+
+每个函数返回 ChannelFeedback, 可被 FeedbackCollector.add() 直接消费。
+"""
+from __future__ import annotations
+
+import ast
+
+import numpy as np
+import pandas as pd
+
+from ..constants import BASE_FEATURE_NAMES as _BASE_FEATURE_NAMES
+from .dataclass import ChannelFeedback, FeedbackChannel
+
+
+def collect_execution(
+    stdout: str,
+    stderr: str,
+    exit_code: int,
+    max_output_chars: int = 500,
+) -> ChannelFeedback:
+    """EXECUTION 通道: 沙箱执行结果。
+
+    Args:
+        stdout/stderr: 沙箱输出
+        exit_code: 进程退出码
+        max_output_chars: stdout/stderr 截断长度 (M2)
+    """
+    passed = exit_code == 0
+    detail = (
+        f"exit={exit_code}\n"
+        f"stdout: {str(stdout)[:max_output_chars]}\n"
+        f"stderr: {str(stderr)[:max_output_chars]}"
+    )
+    score = 1.0 if passed else 0.0
+    return ChannelFeedback(
+        channel=FeedbackChannel.EXECUTION,
+        passed=passed,
+        detail=detail,
+        score=score,
+        metadata={"exit_code": int(exit_code)},
+    )
+
+
+def collect_shape(actual_shape: tuple, expected_shape: tuple) -> ChannelFeedback:
+    """SHAPE 通道: 形状一致性。"""
+    passed = tuple(actual_shape) == tuple(expected_shape)
+    detail = f"actual={tuple(actual_shape)}, expected={tuple(expected_shape)}"
+    score = 1.0 if passed else 0.0
+    return ChannelFeedback(
+        channel=FeedbackChannel.SHAPE,
+        passed=passed,
+        detail=detail,
+        score=score,
+    )
+
+
+def collect_code(
+    expression: str,
+    symbol_length_threshold: int = 200,
+    base_features_threshold: int = 5,
+    free_args_ratio_threshold: float = 0.5,
+) -> ChannelFeedback:
+    """CODE 通道: AST 静态检查 (防过拟合)。
+
+    检查项:
+        - 表达式长度 <= symbol_length_threshold
+        - 基础特征数 <= base_features_threshold
+        - 自由参数 (Name) 占比 <= free_args_ratio_threshold
+    """
+    try:
+        tree = ast.parse(expression)
+    except SyntaxError as e:
+        return ChannelFeedback(
+            channel=FeedbackChannel.CODE,
+            passed=False,
+            detail=f"语法错误: {e}",
+            score=0.0,
+        )
+
+    symbol_length = len(expression)
+    base_features = _count_base_features(tree)
+    free_args_ratio = _calc_free_args_ratio(tree, base_features)
+
+    violations: list[str] = []
+    if symbol_length > symbol_length_threshold:
+        violations.append(f"length={symbol_length}>{symbol_length_threshold}")
+    if base_features > base_features_threshold:
+        violations.append(f"features={base_features}>{base_features_threshold}")
+    if free_args_ratio > free_args_ratio_threshold:
+        violations.append(f"free_args={free_args_ratio:.2f}>{free_args_ratio_threshold}")
+
+    passed = len(violations) == 0
+    detail = "; ".join(violations) if violations else \
+        f"OK (length={symbol_length}, features={base_features}, free_args={free_args_ratio:.2f})"
+    score = 1.0 if passed else 0.0
+    return ChannelFeedback(
+        channel=FeedbackChannel.CODE,
+        passed=passed,
+        detail=detail,
+        score=score,
+        metadata={
+            "symbol_length": symbol_length,
+            "base_features": base_features,
+            "free_args_ratio": free_args_ratio,
+        },
+    )
+
+
+def collect_value(
+    values: pd.Series,
+    nan_threshold: float = 0.3,
+    std_threshold: float = 1e-6,
+) -> ChannelFeedback:
+    """VALUE 通道: 数值分布合理性。
+
+    检查项:
+        - NaN 比例 <= nan_threshold (默认 30%)
+        - Inf 数量 == 0
+        - 标准差 > std_threshold
+    """
+    s = pd.Series(values).dropna()
+    if len(s) == 0:
+        return ChannelFeedback(
+            channel=FeedbackChannel.VALUE,
+            passed=False,
+            detail="全部 NaN, 无有效数值",
+            score=0.0,
+        )
+
+    nan_pct = float(pd.Series(values).isna().mean())
+    inf_count = int(np.isinf(pd.Series(values).fillna(0)).sum())
+    mean_val = float(s.mean())
+    std_val = float(s.std()) if len(s) > 1 else 0.0
+
+    violations: list[str] = []
+    if nan_pct > nan_threshold:
+        violations.append(f"NaN={nan_pct:.2%}>{nan_threshold:.0%}")
+    if inf_count > 0:
+        violations.append(f"Inf={inf_count}>0")
+    if std_val <= std_threshold:
+        violations.append(f"std={std_val:.6f}<={std_threshold}")
+
+    passed = len(violations) == 0
+    detail = "; ".join(violations) if violations else \
+        f"OK (NaN={nan_pct:.2%}, mean={mean_val:.4f}, std={std_val:.4f})"
+    score = 1.0 if passed else 0.0
+    return ChannelFeedback(
+        channel=FeedbackChannel.VALUE,
+        passed=passed,
+        detail=detail,
+        score=score,
+        metadata={
+            "nan_pct": nan_pct,
+            "inf_count": inf_count,
+            "mean": mean_val,
+            "std": std_val,
+        },
+    )
+
+
+def _count_base_features(tree: ast.AST) -> int:
+    """统计表达式中唯一的基础特征名数量。"""
+    names: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Name):
+            names.add(node.id)
+    return len(names & _BASE_FEATURE_NAMES)
+
+
+def _calc_free_args_ratio(tree: ast.AST, base_features: int) -> float:
+    """计算自由参数 (非基础特征) 占比。"""
+    total_names = 0
+    free_args = 0
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Name):
+            total_names += 1
+            if node.id not in _BASE_FEATURE_NAMES:
+                free_args += 1
+    if total_names == 0:
+        return 0.0
+    return free_args / total_names

QuantNodes/core/feedback/collector.py

@@ -0,0 +1,91 @@
+"""FeedbackCollector — 聚合多通道反馈的便捷类。"""
+from __future__ import annotations
+
+import time
+from typing import Optional
+
+from .dataclass import ChannelFeedback, FactorFeedback, FeedbackChannel
+
+
+class FeedbackCollector:
+    """聚合多个通道的反馈信号, finalize() 返回 FactorFeedback。"""
+
+    def __init__(self, factor_id: str, factor_name: str):
+        self.factor_id = factor_id
+        self.factor_name = factor_name
+        self._channels: dict[FeedbackChannel, ChannelFeedback] = {}
+        self._t0 = time.perf_counter()
+
+    def add(
+        self,
+        channel: FeedbackChannel,
+        passed: bool,
+        detail: str,
+        score: float = 1.0,
+        **metadata,
+    ) -> "FeedbackCollector":
+        """添加一个通道的反馈, 支持链式调用。"""
+        self._channels[channel] = ChannelFeedback(
+            channel=channel,
+            passed=passed,
+            detail=detail,
+            score=score,
+            metadata=dict(metadata),
+        )
+        return self
+
+    def add_feedback(self, fb: ChannelFeedback) -> "FeedbackCollector":
+        """添加一个完整的 ChannelFeedback 对象。"""
+        self._channels[fb.channel] = fb
+        return self
+
+    def has(self, channel: FeedbackChannel) -> bool:
+        return channel in self._channels
+
+    def get(self, channel: FeedbackChannel) -> Optional[ChannelFeedback]:
+        return self._channels.get(channel)
+
+    def finalize(
+        self,
+        decision: Optional[bool] = None,
+        summary: str = "",
+        agg_mode: str = "all",  # M3: "all" (AND) | "any" (OR) | "majority"
+        **metadata,
+    ) -> FactorFeedback:
+        """聚合所有通道, 返回 FactorFeedback。
+
+        Args:
+            decision: 显式决策 (None=按 agg_mode 自动)
+            summary: 一句话总结 (空=自动生成)
+            agg_mode: M3 聚合方式
+                - "all" (默认): 全部通过才算通过
+                - "any": 任一通过就算通过
+                - "majority": 多数通过才算通过
+            **metadata: 附加到 FactorFeedback.metadata
+        """
+        if decision is None:
+            if not self._channels:
+                decision = True
+            elif agg_mode == "all":
+                decision = all(fb.passed for fb in self._channels.values())
+            elif agg_mode == "any":
+                decision = any(fb.passed for fb in self._channels.values())
+            elif agg_mode == "majority":
+                passed_count = sum(1 for fb in self._channels.values() if fb.passed)
+                decision = passed_count > len(self._channels) / 2
+            else:
+                raise ValueError(f"未知 agg_mode: {agg_mode}")
+
+        if not summary:
+            failed = [ch.value for ch, fb in self._channels.items() if not fb.passed]
+            summary = f"失败通道: {', '.join(failed)}" if failed else "全部通过"
+
+        return FactorFeedback(
+            factor_id=self.factor_id,
+            factor_name=self.factor_name,
+            channels=dict(self._channels),
+            decision=decision,
+            summary=summary,
+            duration_ms=(time.perf_counter() - self._t0) * 1000,
+            metadata=dict(metadata),
+        )

QuantNodes/core/feedback/dataclass.py

@@ -0,0 +1,239 @@
+"""FactorFeedback 数据类 — 5 通道结构化反馈。
+
+QuantaAlpha `CoSTEERSingleFeedback` 的 QuantNodes 适配版本。
+"""
+from __future__ import annotations
+
+import json
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+from ..constants import EXTENDED_METRIC_KEYS as KNOWN_METRICS
+from QuantNodes.core.path_utils import ensure_parent
+
+
+class FeedbackChannel(str, Enum):
+    """5+3 通道反馈信号。"""
+    EXECUTION = "execution"
+    SHAPE = "shape"
+    CODE = "code"
+    VALUE = "value"
+    LLM = "llm"
+    # 金融约束通道
+    LOOKAHEAD = "lookahead"    # 前瞻偏差检测
+    DECAY = "decay"            # IC 衰减率约束
+    TURNOVER = "turnover"      # 换手率阈值
+
+
+@dataclass
+class ChannelFeedback:
+    """单通道反馈信号。"""
+    channel: FeedbackChannel
+    passed: bool
+    detail: str
+    score: float = 1.0
+    metadata: dict = field(default_factory=dict)
+
+    def values(self):
+        """供 FeedbackCollector.add() 拆解: (passed, detail, score).
+
+        metadata 通过 ChannelFeedback 自身访问, 不在此拆解。
+        """
+        return (self.passed, self.detail, self.score)
+
+
+@dataclass
+class FactorFeedback:
+    """完整因子反馈 — QuantaAlpha CoSTEERSingleFeedback 等价物。"""
+    factor_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    factor_name: str = ""
+    channels: dict[FeedbackChannel, ChannelFeedback] = field(default_factory=dict)
+    decision: bool = False
+    summary: str = ""
+    timestamp: datetime = field(default_factory=datetime.now)
+    duration_ms: float = 0.0
+    metadata: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        """序列化为可 JSON 化的字典。"""
+        return {
+            "factor_id": self.factor_id,
+            "factor_name": self.factor_name,
+            "channels": {
+                ch.value: {
+                    "channel": fb.channel.value,
+                    "passed": fb.passed,
+                    "detail": fb.detail,
+                    "score": fb.score,
+                    "metadata": dict(fb.metadata),
+                }
+                for ch, fb in self.channels.items()
+            },
+            "decision": self.decision,
+            "summary": self.summary,
+            "timestamp": self.timestamp.isoformat(),
+            "duration_ms": self.duration_ms,
+            "metadata": dict(self.metadata),
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "FactorFeedback":
+        """从字典反序列化。"""
+        return cls(
+            factor_id=d["factor_id"],
+            factor_name=d["factor_name"],
+            channels={
+                FeedbackChannel(k): ChannelFeedback(
+                    channel=FeedbackChannel(v["channel"]),
+                    passed=v["passed"],
+                    detail=v["detail"],
+                    score=v["score"],
+                    metadata=v.get("metadata", {}),
+                )
+                for k, v in d.get("channels", {}).items()
+            },
+            decision=d["decision"],
+            summary=d.get("summary", ""),
+            timestamp=datetime.fromisoformat(d["timestamp"]),
+            duration_ms=d.get("duration_ms", 0.0),
+            metadata=d.get("metadata", {}),
+        )
+
+    def save_json(self, path: Path) -> None:
+        """保存为 JSON 格式 (供调试)。"""
+        path = Path(path)
+        ensure_parent(path)
+        with path.open("w", encoding="utf-8") as f:
+            json.dump(self.to_dict(), f, ensure_ascii=False, indent=2)
+
+    @classmethod
+    def load_json(cls, path: Path) -> "FactorFeedback":
+        """从 JSON 加载。"""
+        with Path(path).open("r", encoding="utf-8") as f:
+            return cls.from_dict(json.load(f))
+
+    def to_parquet_row(self) -> dict:
+        """展平为单行 dict 供 Parquet 写入。"""
+        row = {
+            "factor_id": self.factor_id,
+            "factor_name": self.factor_name,
+            "decision": self.decision,
+            "summary": self.summary,
+            "duration_ms": self.duration_ms,
+            "timestamp": self.timestamp.isoformat(),
+            "metadata": json.dumps(self.metadata, ensure_ascii=False),
+        }
+        for ch in FeedbackChannel:
+            prefix = ch.value
+            fb = self.channels.get(ch)
+            row[f"{prefix}_passed"] = bool(fb.passed) if fb else None
+            row[f"{prefix}_score"] = float(fb.score) if fb else None
+            row[f"{prefix}_detail"] = str(fb.detail) if fb else None
+        return row
+
+    def save_parquet(self, path: Path) -> None:
+        """追加到 Parquet 文件 (或创建新文件)。"""
+        path = Path(path)
+        ensure_parent(path)
+        new_row = pd.DataFrame([self.to_parquet_row()])
+        if path.exists():
+            existing = pd.read_parquet(path)
+            combined = pd.concat([existing, new_row], ignore_index=True)
+        else:
+            combined = new_row
+        combined.to_parquet(path, index=False)
+
+    @classmethod
+    def load_parquet(cls, path: Path) -> list["FactorFeedback"]:
+        """从 Parquet 加载为 FactorFeedback 列表。"""
+        df = pd.read_parquet(path)
+        results = []
+        for _, row in df.iterrows():
+            channels = {}
+            for ch in FeedbackChannel:
+                prefix = ch.value
+                if pd.notna(row.get(f"{prefix}_passed")):
+                    metadata = {}
+                    if prefix == "execution" and "exit_code" in row:
+                        metadata["exit_code"] = int(row["exit_code"])
+                    channels[ch] = ChannelFeedback(
+                        channel=ch,
+                        passed=bool(row[f"{prefix}_passed"]),
+                        detail=str(row[f"{prefix}_detail"]),
+                        score=float(row[f"{prefix}_score"]),
+                        metadata=metadata,
+                    )
+            try:
+                metadata = json.loads(row.get("metadata", "{}"))
+            except (json.JSONDecodeError, TypeError):
+                metadata = {}
+            results.append(cls(
+                factor_id=str(row["factor_id"]),
+                factor_name=str(row["factor_name"]),
+                channels=channels,
+                decision=bool(row["decision"]),
+                summary=str(row["summary"]),
+                timestamp=datetime.fromisoformat(str(row["timestamp"])),
+                duration_ms=float(row["duration_ms"]),
+                metadata=metadata,
+            ))
+        return results
+
+
+def ensure_feedback(result: Any, factor_id: str, factor_name: str) -> FactorFeedback:
+    """把节点返回的 dict 包装为 FactorFeedback (兼容现有节点)。
+
+    Args:
+        result: 节点返回值 (FactorFeedback / dict / 其他)
+        factor_id: 因子 UUID
+        factor_name: 因子名称
+
+    Returns:
+        FactorFeedback
+
+    Raises:
+        TypeError: result 类型不支持
+    """
+    if isinstance(result, FactorFeedback):
+        if not result.factor_id:
+            result.factor_id = factor_id
+        if not result.factor_name:
+            result.factor_name = factor_name
+        return result
+    if isinstance(result, dict):
+        metadata = {k: _safe_scalar(result[k]) for k in KNOWN_METRICS if k in result}
+        return FactorFeedback(
+            factor_id=factor_id,
+            factor_name=factor_name,
+            decision=True,
+            summary=f"dict 返回, {len(result)} 个字段",
+            metadata=metadata,
+        )
+    raise TypeError(f"节点返回类型不支持: {type(result).__name__}")
+
+
+def _safe_scalar(v: Any) -> Any:
+    """转 pd.Series/np.ndarray 标量为 Python scalar。"""
+    if isinstance(v, pd.Series):
+        if len(v) == 0:
+            return None
+        v = v.iloc[0]
+    if isinstance(v, (np.ndarray,)):
+        if v.size == 0:
+            return None
+        v = v.flat[0]
+    if isinstance(v, (np.integer,)):
+        return int(v)
+    if isinstance(v, (np.floating,)):
+        f = float(v)
+        return f if np.isfinite(f) else None
+    if isinstance(v, (np.bool_,)):
+        return bool(v)
+    return v

QuantNodes/core/feedback/llm_judge.py

@@ -0,0 +1,138 @@
+"""LLMJudge — LLM 一致性评判 (Week 1 mock 实现)。
+
+Mock 模式: 简单启发式检查 (hypothesis + expression 长度相关)
+真实模式 (后续): 调用 deepseek-v3 / Claude / GPT-4o
+"""
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+from .dataclass import ChannelFeedback, FeedbackChannel
+
+
+class LLMJudge:
+    """LLM 一致性评判器 — hypothesis ↔ description ↔ expression。
+
+    Args:
+        model: 模型名 (mock/real)
+        max_correction_attempts: 解析失败时重试次数
+        llm_callable: 真实 LLM 调用函数, 接受 prompt 返回 string
+    """
+
+    def __init__(
+        self,
+        model: str = "mock",
+        max_correction_attempts: int = 3,
+        llm_callable: Optional[callable] = None,
+    ):
+        self.model = model
+        self.max_correction_attempts = max_correction_attempts
+        if llm_callable is None and model != "mock":
+            raise ValueError(
+                f"model={model!r} requires an explicit llm_callable. "
+                "Inject via get_llm_gateway() at the call site."
+            )
+        self._llm_callable = llm_callable
+
+    def judge(
+        self,
+        hypothesis: str,
+        description: str,
+        expression: str,
+    ) -> ChannelFeedback:
+        """评判三者一致性。"""
+        prompt = self._build_prompt(hypothesis, description, expression)
+        for attempt in range(self.max_correction_attempts + 1):
+            try:
+                raw = self._call(prompt)
+                result = json.loads(raw)
+                return ChannelFeedback(
+                    channel=FeedbackChannel.LLM,
+                    passed=bool(result["consistent"]),
+                    detail=str(result.get("reason", "")),
+                    score=float(result.get("score", 1.0 if result["consistent"] else 0.0)),
+                    metadata={"model": self.model, "attempt": attempt + 1},
+                )
+            except (json.JSONDecodeError, KeyError, TypeError) as e:
+                if attempt == self.max_correction_attempts:
+                    return ChannelFeedback(
+                        channel=FeedbackChannel.LLM,
+                        passed=False,
+                        detail=f"LLM 解析失败: {e}",
+                        score=0.0,
+                        metadata={"model": self.model, "attempt": attempt + 1},
+                    )
+                continue
+
+    def _build_prompt(self, h: str, d: str, e: str) -> str:
+        return (
+            "判断以下三者是否逻辑一致:\n"
+            f"Hypothesis (研究假设): {h}\n"
+            f"Description (因子描述): {d}\n"
+            f"Expression (代码表达式): {e}\n\n"
+            '返回 JSON: {"consistent": true/false, "reason": "理由", "score": 0-1}'
+        )
+
+    def _call(self, prompt: str) -> str:
+        """调用 LLM (mock 或真实)。"""
+        if self._llm_callable is not None:
+            return self._llm_callable(prompt)
+        if self.model == "mock":
+            return self._mock_call(prompt)
+        raise NotImplementedError(
+            "真实 LLM 调用未实现, 请提供 llm_callable 或使用 model='mock'"
+        )
+
+    @staticmethod
+    def _mock_call(prompt: str) -> str:
+        """Mock 实现: 启发式检查。
+
+        规则:
+            - hypothesis 和 description 都为空 -> 不一致
+            - expression 为空 -> 不一致
+            - 出现 'momentum' / '反转' 关键词 + 表达式含 'returns' -> 一致
+            - 其他: 简单长度匹配
+        """
+        h = _extract_field(prompt, "Hypothesis")
+        d = _extract_field(prompt, "Description")
+        e = _extract_field(prompt, "Expression")
+
+        if not e:
+            return json.dumps({"consistent": False, "reason": "表达式为空", "score": 0.0})
+        if not h and not d:
+            return json.dumps({
+                "consistent": False,
+                "reason": "hypothesis 和 description 都为空",
+                "score": 0.0,
+            })
+
+        keywords_h = {"momentum", "反转", "反转", "波动", "volume", "量价", "动量"}
+        text = (h + " " + d).lower()
+        matched = sum(1 for kw in keywords_h if kw.lower() in text)
+        if matched > 0 and ("returns" in e or "close" in e or "open" in e):
+            return json.dumps({
+                "consistent": True,
+                "reason": "关键词匹配, 假设与表达式使用相关字段",
+                "score": 0.85,
+            })
+        return json.dumps({
+            "consistent": True,
+            "reason": "mock 默认通过 (无法判定)",
+            "score": 0.7,
+        })
+
+
+def _extract_field(prompt: str, field_name: str) -> str:
+    """Extract a single field value from a prompt.
+
+    Format: '<FieldName> ... : <value>\\n<next line>\\n...'.
+    Captures the rest of the line after ':' (may be empty).
+    """
+    lines = prompt.split("\n")
+    for line in lines:
+        if line.startswith(field_name):
+            if ":" not in line:
+                return ""
+            return line.split(":", 1)[1].strip()
+    return ""