quantnodes 3.0.0__py3-none-any.whl

QuantNodes/core/evolution/operators.py

@@ -0,0 +1,289 @@
+"""Evolution Operators — LLM-based + mock implementation.
+
+3 operators:
+    - Hypothesizer: 从 research direction 生成新因子候选 (round 0)
+    - Mutator: 从 parent 因子派生 mutation 子代
+    - Crosser: 从两个 parent 因子组合 crossover 子代
+"""
+from __future__ import annotations
+
+import json
+import re
+import uuid
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+
+@dataclass
+class FactorCandidate:
+    """因子候选 — EvolutionLoop 与 PipelineRunner 之间传递的最小单位。"""
+    factor_id: str
+    name: str
+    expression: str
+    hypothesis: str = ""
+    description: str = ""
+
+
+_HYPOTHESIZE_PROMPT = (
+    "你是一个量化研究员, 负责基于研究假设生成 alpha 因子。\n"
+    "研究假设: {hypothesis}\n"
+    "现有描述: {description}\n\n"
+    "请生成一个可执行的因子表达式 "
+    "(Python 语法, 引用基础特征: "
+    "open/high/low/close/volume/amount/vwap/turnover/mv_float)。\n"
+    "返回 JSON: {{\"name\": \"因子名\", \"expression\": \"代码表达式\", "
+    "\"description\": \"因子描述\"}}"
+)
+
+
+_MUTATE_PROMPT = """你是一个量化研究员, 负责对父因子做变异, 探索新变体。
+父因子: {parent_expression}
+父假设: {parent_hypothesis}
+父描述: {parent_description}
+
+请生成一个变异版本 (在保持核心逻辑前提下, 调整参数 / 调换算子 / 增加过滤)。
+返回 JSON: {{"name": "新因子名", "expression": "新表达式", "description": "新描述"}}"""
+
+
+_CROSSOVER_PROMPT = """你是一个量化研究员, 负责组合两个父因子产生新组合。
+父因子 1: {p1_expression} ({p1_description})
+父因子 2: {p2_expression} ({p2_description})
+
+请生成一个组合 (可加可减可相乘可平均), 保持经济意义。
+返回 JSON: {{"name": "组合因子名", "expression": "组合表达式", "description": "组合描述"}}"""
+
+
+class BaseOperator:
+    """Operator 基类, 统一 LLM 调用协议。"""
+
+    def __init__(
+        self,
+        model: str = "mock",
+        max_correction_attempts: int = 3,
+        seed: int = 42,
+        llm_callable: Optional[Callable] = None,
+    ):
+        self.model = model
+        self.max_correction_attempts = max_correction_attempts
+        self.seed = seed
+        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 _call(self, prompt: str) -> str:
+        if self._llm_callable is not None:
+            return self._llm_callable(prompt)
+        if self.model == "mock":
+            return json.dumps(_mock_variant(prompt))
+        raise NotImplementedError(
+            "真实 LLM 未实现, 请提供 llm_callable 或使用 model='mock'"
+        )
+
+
+class Hypothesizer(BaseOperator):
+    """从研究假设生成初始因子 (round 0)。"""
+
+    def __init__(
+        self, *args, knowledge_base=None, rag_top_k: int = 3,
+        max_ancestor_depth: int = 2, max_descendant_depth: int = 2,
+        use_compress: bool = False, compressor=None,
+        **kwargs,
+    ):
+        super().__init__(*args, **kwargs)
+        from ..knowledge import Compressor, KnowledgeBase
+        self.knowledge_base: KnowledgeBase | None = knowledge_base
+        self.rag_top_k = rag_top_k
+        self.max_ancestor_depth = max_ancestor_depth
+        self.max_descendant_depth = max_descendant_depth
+        self.use_compress = use_compress
+        self.compressor = compressor if compressor is not None else (
+            Compressor(model="mock") if use_compress else None
+        )
+
+    def hypothesize(
+        self,
+        direction: str,
+        description: str = "",
+    ) -> FactorCandidate:
+        # RAG: 若有 KB, 构造带历史示例的 prompt
+        if self.knowledge_base is not None and len(self.knowledge_base) > 0:
+            from ..knowledge import build_rag_prompt
+            prompt = build_rag_prompt(
+                direction=direction,
+                description=description,
+                kb=self.knowledge_base,
+                top_k=self.rag_top_k,
+                max_ancestor_depth=self.max_ancestor_depth,
+                max_descendant_depth=self.max_descendant_depth,
+                use_compress=self.use_compress,
+                compressor=self.compressor,
+            )
+        else:
+            prompt = _HYPOTHESIZE_PROMPT.format(
+                hypothesis=direction,
+                description=description,
+            )
+        for attempt in range(self.max_correction_attempts + 1):
+            try:
+                raw = self._call(prompt)
+                data = json.loads(raw)
+                return FactorCandidate(
+                    factor_id=str(uuid.uuid4()),
+                    name=str(data.get("name", f"h_{direction[:8]}")),
+                    expression=str(data["expression"]),
+                    hypothesis=direction,
+                    description=str(data.get("description", description)),
+                )
+            except (json.JSONDecodeError, KeyError, TypeError):
+                if attempt == self.max_correction_attempts:
+                    # 兜底: 用 mock 直接生成
+                    data = _mock_variant(prompt)
+                    return FactorCandidate(
+                        factor_id=str(uuid.uuid4()),
+                        name=str(data.get("name", f"h_{direction[:8]}")),
+                        expression=str(data["expression"]),
+                        hypothesis=direction,
+                        description=str(data.get("description", description)),
+                    )
+                continue
+        raise RuntimeError("unreachable")  # for type checker
+
+
+class Mutator(BaseOperator):
+    """从单个 parent 生成 mutation 子代。"""
+
+    def mutate(self, parent: FactorCandidate) -> FactorCandidate:
+        prompt = _MUTATE_PROMPT.format(
+            parent_expression=parent.expression,
+            parent_hypothesis=parent.hypothesis,
+            parent_description=parent.description,
+        )
+        for attempt in range(self.max_correction_attempts + 1):
+            try:
+                raw = self._call(prompt)
+                data = json.loads(raw)
+                return FactorCandidate(
+                    factor_id=str(uuid.uuid4()),
+                    name=str(data.get("name", f"m_{parent.name}")),
+                    expression=str(data["expression"]),
+                    hypothesis=parent.hypothesis,
+                    description=str(data.get("description", parent.description)),
+                )
+            except (json.JSONDecodeError, KeyError, TypeError):
+                if attempt == self.max_correction_attempts:
+                    data = _mock_variant(prompt)
+                    return FactorCandidate(
+                        factor_id=str(uuid.uuid4()),
+                        name=str(data.get("name", f"m_{parent.name}")),
+                        expression=str(data["expression"]),
+                        hypothesis=parent.hypothesis,
+                        description=str(data.get("description", parent.description)),
+                    )
+                continue
+        raise RuntimeError("unreachable")
+
+
+class Crosser(BaseOperator):
+    """从两个 parent 生成 crossover 子代。"""
+
+    def crossover(
+        self,
+        parent1: FactorCandidate,
+        parent2: FactorCandidate,
+    ) -> FactorCandidate:
+        prompt = _CROSSOVER_PROMPT.format(
+            p1_expression=parent1.expression,
+            p1_description=parent1.description,
+            p2_expression=parent2.expression,
+            p2_description=parent2.description,
+        )
+        for attempt in range(self.max_correction_attempts + 1):
+            try:
+                raw = self._call(prompt)
+                data = json.loads(raw)
+                return FactorCandidate(
+                    factor_id=str(uuid.uuid4()),
+                    name=str(data.get("name", f"x_{parent1.name}_{parent2.name}")),
+                    expression=str(data["expression"]),
+                    hypothesis=f"combo({parent1.hypothesis}, {parent2.hypothesis})",
+                    description=str(data.get(
+                        "description",
+                        f"combo of {parent1.name} + {parent2.name}",
+                    )),
+                )
+            except (json.JSONDecodeError, KeyError, TypeError):
+                if attempt == self.max_correction_attempts:
+                    data = _mock_variant(prompt)
+                    return FactorCandidate(
+                        factor_id=str(uuid.uuid4()),
+                        name=str(data.get("name", f"x_{parent1.name}_{parent2.name}")),
+                        expression=str(data["expression"]),
+                        hypothesis=f"combo({parent1.hypothesis}, {parent2.hypothesis})",
+                        description=str(data.get(
+                            "description",
+                            f"combo of {parent1.name} + {parent2.name}",
+                        )),
+                    )
+                continue
+        raise RuntimeError("unreachable")
+
+
+# ============================================================================
+# Mock variant generator (heuristic-based fallback)
+# ============================================================================
+
+_MUTATION_TEMPLATES = [
+    lambda e: f"({e}).rolling(5).mean()",
+    lambda e: f"({e}).diff()",
+    lambda e: f"({e}).rank(pct=True)",
+    lambda e: f"({e}) - ({e}).shift(5)",
+    lambda e: f"({e}) * 2",
+    lambda e: f"({e}).abs()",
+]
+
+_CROSSOVER_TEMPLATES = [
+    lambda a, b: f"({a}) + ({b})",
+    lambda a, b: f"({a}) - ({b})",
+    lambda a, b: f"({a}) * ({b})",
+    lambda a, b: f"(({a}) + ({b})) / 2",
+    lambda a, b: f"({a}).rank(pct=True) - ({b}).rank(pct=True)",
+]
+
+
+def _mock_variant(prompt: str) -> dict:
+    """基于 prompt 内容启发式生成变体。"""
+    # 提取父表达式 (按 "父因子: <expr>" 模式)
+    parent_match = re.search(r"父因子[:\s]+([^\n]+)", prompt)
+    parents_match = re.findall(r"父因子\s*\d*[:\s]+([^\n(]+)", prompt)
+    hyp_match = re.search(r"研究假设[:\s]+([^\n]+)", prompt)
+
+    hyp = hyp_match.group(1).strip() if hyp_match else "alpha"
+
+    if len(parents_match) >= 2:
+        # crossover
+        idx = sum(ord(c) for c in prompt) % len(_CROSSOVER_TEMPLATES)
+        tpl = _CROSSOVER_TEMPLATES[idx]
+        expr = tpl(parents_match[0].strip(), parents_match[1].strip())
+        return {
+            "name": f"x_mock_{idx}",
+            "expression": expr,
+            "description": f"combo of {parents_match[0][:20]} + {parents_match[1][:20]}",
+        }
+    if parent_match:
+        parent_expr = parent_match.group(1).strip()
+        idx = sum(ord(c) for c in prompt) % len(_MUTATION_TEMPLATES)
+        tpl = _MUTATION_TEMPLATES[idx]
+        return {
+            "name": f"m_mock_{idx}",
+            "expression": tpl(parent_expr),
+            "description": f"mutation of {parent_expr[:30]}",
+        }
+    # hypothesize fallback
+    return {
+        "name": f"h_mock_{hyp[:8]}",
+        "expression": "(close - close.shift(20)) / close.shift(20)",
+        "description": f"default expression for {hyp}",
+    }

QuantNodes/core/evolution/settings.py

@@ -0,0 +1,44 @@
+"""Evolution 配置 — 演化主循环相关设置。"""
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class OperatorSetting(BaseModel):
+    """LLM Operator 配置 (hypothesize / mutate / crossover)。"""
+    enabled: bool = Field(default=True, description="启用该 operator")
+    model: str = Field(default="mock", description="LLM 模型 (mock/deepseek-v3/...)")
+    max_correction_attempts: int = Field(default=3, description="LLM 解析失败最大重试")
+    seed: int = Field(default=42, description="mock 模式随机种子")
+
+
+class EvolutionSetting(BaseModel):
+    """演化主循环配置 (集成到 SingleFactorTestConfig)。"""
+    enabled: bool = Field(default=False, description="是否启用演化模式")
+    max_rounds: int = Field(default=3, description="演化总轮数 (不含 round 0 原始)")
+    parents_per_round: int = Field(default=1, description="每轮选几个 parent (crossover=2)")
+    parent_selection_strategy: str = Field(
+        default="top_percent_plus_random",
+        description="选择策略 (best/random/weighted/weighted_inverse/top_percent_plus_random)",
+    )
+    top_percent_threshold: float = Field(
+        default=0.3, description="top_percent_plus_random 的 top 比例"
+    )
+    metric: str = Field(default="sharpe", description="用于排序/加权的指标")
+    pool_dir: Optional[str] = Field(
+        default=None, description="TrajectoryPool 目录 (None=output.dir/trajectory)"
+    )
+    early_stop_patience: int = Field(default=0, description="连续 N 轮无改善则停 (0=不启用)")
+    top_n: int = Field(default=10, description="最终 best_entries 返回 Top-N (EvolutionResult)")
+    hypothesizer: OperatorSetting = Field(default_factory=OperatorSetting)
+    mutator: OperatorSetting = Field(default_factory=OperatorSetting)
+    crosser: OperatorSetting = Field(default_factory=OperatorSetting)
+
+    def any_operator_enabled(self) -> bool:
+        return (
+            self.hypothesizer.enabled
+            or self.mutator.enabled
+            or self.crosser.enabled
+        )