quantnodes 3.0.0__py3-none-any.whl

QuantNodes/core/plugin.py

@@ -0,0 +1,135 @@
+# coding=utf-8
+"""
+core/plugin.py — 插件发现机制 (Tier 0: Foundation)
+
+通过 Python 标准 entry_points 机制发现第三方 quantnodes 插件。
+
+设计目标:
+- 第三方包可在自己的 pyproject.toml 中声明:
+    [project.entry-points."quantnodes.tools"]
+    my_tool = "my_pkg.tools:MyTool"
+- 运行时通过 discover_tools() / discover_operators() 自动加载
+- 与 nanobot upstream 风格一致 (其已用 entry_points)
+- 向后兼容: 未声明 entry_points 时回退到硬编码列表
+
+回退策略:
+- discover_*() 返回 dict (name -> factory)
+- 如 entry_points 完全为空, 返回空 dict (调用方需 fallback 到硬编码)
+- 如 entry_points 部分加载失败, 记录 warning 但继续
+
+使用示例:
+    from QuantNodes.core.plugin import discover_tools, discover_operators
+
+    # 发现所有工具 (含第三方插件)
+    tools = discover_tools()
+    for name, factory in tools.items():
+        tool = factory()
+        registry.register(tool)
+
+    # 发现所有算子 (自定义算子可通过 entry_points 注册)
+    ops = discover_operators()
+    for op_name in ops:
+        # op_name 是已注册的算子名
+        ...
+"""
+
+from __future__ import annotations
+
+import importlib.metadata as md
+import logging
+from typing import Any, Callable, Dict, List, Type
+
+logger = logging.getLogger(__name__)
+
+
+# entry_points 组名常量
+TOOLS_GROUP = "quantnodes.tools"
+OPERATORS_GROUP = "quantnodes.operators"
+
+
+def discover_tools() -> Dict[str, Type]:
+    """通过 entry_points 发现所有 quantnodes.tools 插件
+
+    Returns:
+        dict: {entry_name: Tool class}，可调用 class() 实例化。
+              如 entry_points 为空，返回空 dict。
+              如部分插件加载失败，跳过并记录 warning。
+
+    Example:
+        >>> tools = discover_tools()
+        >>> SandboxTool = tools["sandbox"]
+        >>> tool = SandboxTool()
+    """
+    result: Dict[str, Type] = {}
+    eps = md.entry_points(group=TOOLS_GROUP)
+    for ep in eps:
+        try:
+            cls = ep.load()
+            result[ep.name] = cls
+        except Exception as e:
+            logger.warning(
+                "Failed to load tool plugin %r from %r: %s",
+                ep.name,
+                ep.value,
+                e,
+            )
+    return result
+
+
+def discover_operators() -> List[str]:
+    """通过 entry_points 发现所有 quantnodes.operators 插件名
+
+    Returns:
+        list[str]: 已注册的算子名列表。
+                   如 entry_points 为空，返回空 list。
+
+    Note:
+        算子 plugin 的 entry value 应该是形如 "my_pkg.ops:get_op_names" 的可调用对象，
+        调用后返回该包注册的算子名列表。
+    """
+    result: List[str] = []
+    eps = md.entry_points(group=OPERATORS_GROUP)
+    for ep in eps:
+        try:
+            loader = ep.load()
+            op_names = loader()
+            if isinstance(op_names, (list, tuple)):
+                result.extend(str(n) for n in op_names)
+            else:
+                logger.warning(
+                    "Operator plugin %r did not return a list: got %r",
+                    ep.name,
+                    type(op_names),
+                )
+        except Exception as e:
+            logger.warning(
+                "Failed to load operator plugin %r from %r: %s",
+                ep.name,
+                ep.value,
+                e,
+            )
+    return result
+
+
+def discover_all() -> Dict[str, Dict[str, Any]]:
+    """一次性发现所有 quantnodes.* 插件
+
+    Returns:
+        dict: {
+            "tools": {name: cls, ...},
+            "operators": [name, ...],
+        }
+    """
+    return {
+        "tools": discover_tools(),
+        "operators": discover_operators(),
+    }
+
+
+__all__ = [
+    "TOOLS_GROUP",
+    "OPERATORS_GROUP",
+    "discover_tools",
+    "discover_operators",
+    "discover_all",
+]

QuantNodes/core/quality_gate/__init__.py

@@ -0,0 +1,32 @@
+"""QualityGate — 3 门质量检查 (Complexity / Redundancy / Consistency)。
+
+公开 API:
+    - QualityGateSetting / ComplexitySetting / RedundancySetting / ConsistencySetting
+    - FactorZoo: AST hash 库
+    - ComplexityChecker / RedundancyChecker / ConsistencyChecker
+    - QualityGateNode: 集成 3 门的节点
+"""
+from .settings import (
+    ComplexitySetting,
+    ConsistencySetting,
+    QualityGateSetting,
+    RedundancySetting,
+)
+from .zoo import FactorZoo, ast_hash
+from .complexity import ComplexityChecker
+from .redundancy import RedundancyChecker
+from .consistency import ConsistencyChecker
+from .node import QualityGateNode
+
+__all__ = [
+    "ComplexitySetting",
+    "ConsistencySetting",
+    "QualityGateSetting",
+    "RedundancySetting",
+    "FactorZoo",
+    "ast_hash",
+    "ComplexityChecker",
+    "RedundancyChecker",
+    "ConsistencyChecker",
+    "QualityGateNode",
+]

QuantNodes/core/quality_gate/complexity.py

@@ -0,0 +1,94 @@
+"""ComplexityChecker — AST 静态检查, 防过拟合。"""
+from __future__ import annotations
+
+import ast
+
+from ..constants import BASE_FEATURE_NAMES as _BASE_FEATURE_NAMES
+from ..feedback import ChannelFeedback, FeedbackChannel
+from .settings import ComplexitySetting
+
+
+class ComplexityChecker:
+    """复杂度门: AST 静态检查 (length / base features / free args ratio)。"""
+
+    def __init__(self, settings: ComplexitySetting | None = None):
+        self.settings = settings or ComplexitySetting()
+
+    def check(self, expression: str) -> ChannelFeedback:
+        """返回 ChannelFeedback (CODE 通道)。"""
+        if not self.settings.enabled:
+            return ChannelFeedback(
+                channel=FeedbackChannel.CODE,
+                passed=True,
+                detail="complexity disabled",
+            )
+
+        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)
+
+        violations: list[str] = []
+        if symbol_length > self.settings.symbol_length_threshold:
+            violations.append(
+                f"length={symbol_length}>{self.settings.symbol_length_threshold}"
+            )
+        if base_features > self.settings.base_features_threshold:
+            violations.append(
+                f"features={base_features}>{self.settings.base_features_threshold}"
+            )
+        if free_args_ratio > self.settings.free_args_ratio_threshold:
+            violations.append(
+                f"free_args={free_args_ratio:.2f}>{self.settings.free_args_ratio_threshold}"
+            )
+
+        passed = len(violations) == 0
+        if violations:
+            detail = "; ".join(violations)
+        else:
+            detail = (
+                f"OK (length={symbol_length}, features={base_features},"
+                f" 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 _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) -> float:
+    """计算自由参数 (非基础特征) 占比。"""
+    total = 0
+    free = 0
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Name):
+            total += 1
+            if node.id not in _BASE_FEATURE_NAMES:
+                free += 1
+    return (free / total) if total > 0 else 0.0

QuantNodes/core/quality_gate/consistency.py

@@ -0,0 +1,26 @@
+"""ConsistencyChecker — LLM 验证 hypothesis ↔ description ↔ expression。"""
+from __future__ import annotations
+
+from ..feedback import ChannelFeedback, FeedbackChannel, LLMJudge
+from .settings import ConsistencySetting
+
+
+class ConsistencyChecker:
+    """一致性门: 复用 FactorFeedback 的 LLMJudge。"""
+
+    def __init__(self, settings: ConsistencySetting | None = None, judge: LLMJudge | None = None):
+        self.settings = settings or ConsistencySetting()
+        self._judge = judge if judge is not None else LLMJudge(
+            model=self.settings.model,
+            max_correction_attempts=self.settings.max_correction_attempts,
+        )
+
+    def check(self, hypothesis: str, description: str, expression: str) -> ChannelFeedback:
+        """返回 ChannelFeedback (LLM 通道)。"""
+        if not self.settings.enabled:
+            return ChannelFeedback(
+                channel=FeedbackChannel.LLM,
+                passed=True,
+                detail="consistency disabled",
+            )
+        return self._judge.judge(hypothesis, description, expression)

QuantNodes/core/quality_gate/node.py

@@ -0,0 +1,97 @@
+"""QualityGateNode — 集成 3 个 checkers, 输出 passed + FactorFeedback。"""
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from ..feedback import (
+    FeedbackCollector,
+)
+from .complexity import ComplexityChecker
+from .consistency import ConsistencyChecker
+from .redundancy import RedundancyChecker
+from .settings import QualityGateSetting
+from .zoo import FactorZoo
+
+
+class QualityGateNode:
+    """质量门节点 — pre-backtest 检查。
+
+    输入: context['FactorCandidate'] = {
+        'factor_id': str,
+        'name': str,
+        'expression': str,
+        'hypothesis': str,
+        'description': str,
+    }
+    输出: {
+        'passed': bool,
+        'feedback': FactorFeedback,
+        'channels': dict[FeedbackChannel, ChannelFeedback],
+    }
+    """
+
+    def __init__(
+        self,
+        settings: QualityGateSetting | None = None,
+        zoo: FactorZoo | None = None,
+    ):
+        self.settings = settings or QualityGateSetting()
+        self._complexity = ComplexityChecker(self.settings.complexity)
+        self._redundancy = RedundancyChecker(
+            self.settings.redundancy,
+            zoo=zoo if zoo is not None else FactorZoo(self.settings.redundancy.zoo_path),
+        )
+        self._consistency = ConsistencyChecker(self.settings.consistency)
+
+    def check(
+        self,
+        candidate: dict[str, Any],
+    ) -> dict[str, Any]:
+        """同步检查入口, 不依赖 BaseNode 框架 (便于单测)。
+
+        Args:
+            candidate: 因子候选 dict (含 expression / hypothesis / description)
+
+        Returns:
+            dict: {'passed', 'feedback', 'channels'}
+        """
+        if "expression" not in candidate:
+            raise ValueError("FactorCandidate 缺少 'expression' 字段")
+
+        factor_id = candidate.get("factor_id") or str(uuid.uuid4())
+        factor_name = candidate.get("name", "unnamed")
+        expression = candidate["expression"]
+        hypothesis = candidate.get("hypothesis", "")
+        description = candidate.get("description", "")
+
+        collector = FeedbackCollector(factor_id, factor_name)
+
+        if self.settings.complexity.enabled:
+            collector.add_feedback(self._complexity.check(expression))
+        if self.settings.redundancy.enabled:
+            collector.add_feedback(self._redundancy.check(expression))
+        if self.settings.consistency.enabled:
+            collector.add_feedback(
+                self._consistency.check(hypothesis, description, expression)
+            )
+
+        feedback = collector.finalize()
+        return {
+            "passed": feedback.decision,
+            "feedback": feedback,
+            "channels": feedback.channels,
+        }
+
+    def execute(self, context: dict | None = None, **kwargs) -> dict[str, Any]:
+        """节点风格入口, 从 context['FactorCandidate'] 读取。
+
+        Raises:
+            ValueError: FactorCandidate 缺失
+        """
+        if context is None:
+            context = kwargs.get("context", {})
+        candidate = context.get("FactorCandidate")
+        if not candidate:
+            raise ValueError("FactorCandidate 缺失 (context['FactorCandidate'] 不存在)")
+        return self.check(candidate)

QuantNodes/core/quality_gate/redundancy.py

@@ -0,0 +1,51 @@
+"""RedundancyChecker — 与 Zoo 已有因子 AST hash 汉明距离 < 阈值则拒绝。"""
+from __future__ import annotations
+
+from ..feedback import ChannelFeedback, FeedbackChannel
+from .settings import RedundancySetting
+from .zoo import FactorZoo
+
+
+class RedundancyChecker:
+    """冗余门: 与 Zoo 中已有因子的 AST 哈希距离。"""
+
+    def __init__(self, settings: RedundancySetting | None = None, zoo: FactorZoo | None = None):
+        self.settings = settings or RedundancySetting()
+        self.zoo = zoo if zoo is not None else FactorZoo(self.settings.zoo_path)
+
+    def check(self, expression: str) -> ChannelFeedback:
+        """返回 ChannelFeedback (VALUE 通道)。"""
+        if not self.settings.enabled:
+            return ChannelFeedback(
+                channel=FeedbackChannel.VALUE,
+                passed=True,
+                detail="redundancy disabled",
+            )
+
+        if len(self.zoo) == 0:
+            return ChannelFeedback(
+                channel=FeedbackChannel.VALUE,
+                passed=True,
+                detail="Zoo 为空, 无需检查",
+                metadata={"zoo_size": 0},
+            )
+
+        distances = self.zoo.hamming_to(expression)
+        min_dist = distances[0][0]
+        nearest = distances[0][2]
+        passed = min_dist >= self.settings.threshold
+        detail = (
+            f"min_hamming_dist={min_dist}, threshold={self.settings.threshold}, "
+            f"zoo_size={len(self.zoo)}, nearest={nearest[:50]!r}"
+        )
+        return ChannelFeedback(
+            channel=FeedbackChannel.VALUE,
+            passed=passed,
+            detail=detail,
+            score=1.0 if passed else 0.0,
+            metadata={
+                "min_hamming_dist": int(min_dist),
+                "threshold": int(self.settings.threshold),
+                "zoo_size": len(self.zoo),
+            },
+        )

QuantNodes/core/quality_gate/settings.py

@@ -0,0 +1,43 @@
+"""QualityGate 配置 — 3 个独立可配门 + 总配置。"""
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class ComplexitySetting(BaseModel):
+    """COMPLEXITY 门配置 — 防过拟合 (AST 静态检查)。"""
+    enabled: bool = Field(default=True, description="启用复杂度门")
+    symbol_length_threshold: int = Field(default=200, description="表达式字符串长度上限")
+    base_features_threshold: int = Field(default=5, description="基础特征数上限")
+    free_args_ratio_threshold: float = Field(default=0.5, description="自由参数占比上限")
+
+
+class RedundancySetting(BaseModel):
+    """REDUNDANCY 门配置 — 防重复 (AST hash + 汉明距离)。"""
+    enabled: bool = Field(default=True, description="启用冗余门")
+    threshold: int = Field(default=5, description="最小汉明距离阈值")
+    zoo_path: Optional[str] = Field(default=None, description="因子 Zoo 路径 (None=内存)")
+
+
+class ConsistencySetting(BaseModel):
+    """CONSISTENCY 门配置 — LLM 验证 hypothesis ↔ description ↔ expression。"""
+    enabled: bool = Field(default=False, description="启用一致性门 (需 LLM, 默认关闭)")
+    model: str = Field(default="mock", description="LLM 模型名")
+    max_correction_attempts: int = Field(default=3, description="解析失败最大重试次数")
+
+
+class QualityGateSetting(BaseModel):
+    """质量门总配置。"""
+    complexity: ComplexitySetting = Field(default_factory=ComplexitySetting)
+    redundancy: RedundancySetting = Field(default_factory=RedundancySetting)
+    consistency: ConsistencySetting = Field(default_factory=ConsistencySetting)
+
+    def any_enabled(self) -> bool:
+        """是否有任何门启用。"""
+        return (
+            self.complexity.enabled
+            or self.redundancy.enabled
+            or self.consistency.enabled
+        )

QuantNodes/core/quality_gate/zoo.py

@@ -0,0 +1,98 @@
+"""FactorZoo — 历史通过因子的 AST hash 库。"""
+from __future__ import annotations
+
+import ast
+import hashlib
+from pathlib import Path
+from typing import Iterator
+
+import pandas as pd
+from QuantNodes.core.path_utils import ensure_parent
+
+
+def ast_hash(expression: str) -> int:
+    """AST 规范化 hash (跨进程确定)。
+
+    使用 `hashlib.sha256` 替代 Python 内置 `hash()` (后者受 `PYTHONHASHSEED` 影响,
+    跨进程不幂等, 会导致 ProcessPool 模式下的 redundancy check 静默失效)。
+
+    注: `ast.dump(annotate_fields=False)` 移除字段名 ('id', 'arg'),
+    只保留节点类型和基本字面量, 实现"结构等价即同 hash"。
+    """
+    tree = ast.parse(expression)
+    payload = ast.dump(tree, annotate_fields=False).encode("utf-8")
+    digest = hashlib.sha256(payload).digest()
+    return int.from_bytes(digest[:8], "big", signed=False)
+
+
+class FactorZoo:
+    """因子 Zoo — 存储历史通过因子的 AST hash。
+
+    Args:
+        path: Parquet 持久化路径 (None=纯内存, 不持久化)
+    """
+
+    def __init__(self, path: Path | str | None = None):
+        self.path = Path(path) if path is not None else None
+        self._entries: dict[int, str] = {}  # hash -> expression
+        if self.path is not None and self.path.exists():
+            self._load()
+
+    def add(self, expression: str) -> int:
+        """添加一个因子, 返回其 hash; 重复 hash 不重复添加。"""
+        h = ast_hash(expression)
+        if h not in self._entries:
+            self._entries[h] = expression
+            self._save()
+        return h
+
+    def contains(self, expression: str) -> bool:
+        """检查表达式是否已在 Zoo 中 (完全相同 AST 结构)。"""
+        return ast_hash(expression) in self._entries
+
+    def hamming_to(self, expression: str) -> list[tuple[int, int, str]]:
+        """返回与 Zoo 中所有 hash 的汉明距离列表 [(dist, hash, expr), ...]。"""
+        new_h = ast_hash(expression)
+        results = []
+        for h, expr in self._entries.items():
+            dist = bin(new_h ^ h).count("1")
+            results.append((dist, h, expr))
+        results.sort(key=lambda x: x[0])
+        return results
+
+    def min_hamming(self, expression: str) -> int:
+        """返回与 Zoo 中最近因子的汉明距离 (Zoo 为空时返回 +inf)。"""
+        if not self._entries:
+            return float("inf")  # type: ignore[return-value]
+        return self.hamming_to(expression)[0][0]
+
+    def clear(self) -> None:
+        """清空 Zoo (谨慎)。"""
+        self._entries.clear()
+        self._save()
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    def __iter__(self) -> Iterator[tuple[int, str]]:
+        return iter(self._entries.items())
+
+    def _save(self) -> None:
+        if self.path is None or not self._entries:
+            return
+        ensure_parent(self.path)
+        df = pd.DataFrame(
+            [(h, e) for h, e in self._entries.items()],
+            columns=["hash", "expression"],
+        )
+        df.to_parquet(self.path, index=False)
+
+    def _load(self) -> None:
+        if self.path is None or not self.path.exists():
+            return
+        try:
+            df = pd.read_parquet(self.path)
+        except Exception:
+            return
+        for _, row in df.iterrows():
+            self._entries[int(row["hash"])] = str(row["expression"])

QuantNodes/core/serializable.py

@@ -0,0 +1,116 @@
+# coding=utf-8
+"""
+Serializable Mixin 模块
+
+提供统一的序列化/反序列化接口：
+- serialize() / deserialize() 统一 API
+- @serializable 注册装饰器
+- 注册表机制用于反序列化
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Type, TypeVar
+
+
+T = TypeVar('T')
+
+_REGISTRY: Dict[str, Type] = {}
+
+
+def serializable(cls: Type[T]) -> Type[T]:
+    """
+    注册装饰器：标记类为可序列化
+
+    用法：
+        @serializable
+        class MyClass(Serializable):
+            ...
+
+    所有使用此装饰器的类都会注册到全局注册表中，
+    支持通过 deserialize() 反序列化。
+    """
+    _REGISTRY[cls.__name__] = cls
+    return cls
+
+
+class Serializable(ABC):
+    """
+    可序列化对象的 Mixin 基类
+
+    子类必须实现：
+    - _get_serializable_fields(): 返回需要序列化的字段
+    - _from_dict_impl(): 从字典反序列化
+
+    提供统一的 API：
+    - serialize(): 序列化为字典
+    - deserialize(): 从字典反序列化
+    """
+
+    _schema_version: str = "1.0"
+
+    @abstractmethod
+    def _get_serializable_fields(self) -> Dict[str, Any]:
+        """
+        子类实现：返回需要序列化的字段
+
+        Returns:
+            包含序列化字段的字典，不包含 type 和 _schema_version
+        """
+        pass
+
+    @classmethod
+    @abstractmethod
+    def _from_dict_impl(cls, data: Dict[str, Any]) -> Serializable:
+        """
+        子类实现：从字典反序列化
+
+        Args:
+            data: 序列化字典（已包含 type 和 _schema_version）
+
+        Returns:
+            反序列化重建的对象
+        """
+        pass
+
+    def serialize(self) -> Dict[str, Any]:
+        """
+        统一序列化方法
+
+        Returns:
+            包含 type, _schema_version 和子类字段的字典
+        """
+        return {
+            "type": self.__class__.__name__,
+            "_schema_version": self._schema_version,
+            **self._get_serializable_fields(),
+        }
+
+    @classmethod
+    def deserialize(cls: Type[T], data: Dict[str, Any]) -> T:
+        """
+        统一反序列化方法
+
+        Args:
+            data: serialize() 返回的字典
+
+        Returns:
+            反序列化重建的对象
+
+        Raises:
+            ValueError: 缺少 type 或类型未知
+        """
+        type_name = data.get("type")
+        if not type_name:
+            raise ValueError("Missing 'type' in serialized data")
+
+        target = _REGISTRY.get(type_name)
+        if not target:
+            available = list(_REGISTRY.keys())
+            raise ValueError(
+                f"Unknown serializable type: {type_name}. "
+                f"Available types: {available}"
+            )
+
+        return target._from_dict_impl(data)