quantnodes 3.0.0__py3-none-any.whl

QuantNodes/research/quant_alpha/logic_mining/generator.py

@@ -0,0 +1,366 @@
+# coding=utf-8
+"""
+generator.py - 外层循环的两个 Agent
+
+基于 AlphaLogics 论文 (arXiv 2603.20247) §3.3 实现。
+
+两个外层 Agent:
+  - MarketLogicGeneratorAgent: 生成新/重构逻辑
+  - MarketLogicRefinementDirectionAgent: 逻辑层反馈
+
+Usage::
+
+    from QuantNodes.research.quant_alpha.logic_mining.generator import (
+        MarketLogicGenerator, MarketLogicRefinementDirection,
+    )
+
+    generator = MarketLogicGenerator(llm_client=llm)
+    new_logic = generator.generate(library, history, evidence)
+
+    refiner = MarketLogicRefinementDirection(llm_client=llm)
+    feedback = refiner.refine(current_logic, history, evidence)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Tuple
+
+from QuantNodes.research.quant_alpha.logic_mining.models import (
+    LogicBehavior,
+    LogicCondition,
+    LogicPerformanceEvidence,
+    WikiLogicStructured,
+)
+from QuantNodes.research.quant_alpha.logic_mining.parser import (
+    parse_json_response,
+)
+
+# WikiLogic 在 research.wiki 中定义，会引用 logic_mining.models，
+# 故在此延迟导入以避免循环依赖。
+def _get_wiki_logic_class():
+    from QuantNodes.research.wiki import WikiLogic
+    return WikiLogic
+
+def _get_logic_source_class():
+    from QuantNodes.research.wiki import LogicSource
+    return LogicSource
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "MarketLogicGenerator",
+    "MarketLogicRefinementDirection",
+    "generate_logic_name",
+]
+
+
+def _call_llm(llm_client: Any, agent_id: str, prompt: str, default_response: str) -> str:
+    """调用 LLM，无客户端或失败时返回 mock"""
+    if llm_client is None:
+        return default_response
+    try:
+        if hasattr(llm_client, "complete"):
+            return llm_client.complete(agent_id=agent_id, prompt=prompt)
+        return llm_client(prompt)
+    except Exception as e:
+        logger.warning("LLM call failed for %s: %s, falling back to mock", agent_id, e)
+        return default_response
+
+
+def _build_generator_prompt(
+    library: List[WikiLogic],
+    current_logic: Optional[WikiLogic],
+    history: List[WikiLogic],
+    evidence: List[LogicPerformanceEvidence],
+    round_idx: int,
+) -> str:
+    """MarketLogicGeneratorAgent prompt"""
+    lib_names = [l.name for l in library[:10]]
+    history_names = [l.name for l in history[:10]]
+    ev_summary = [
+        {"round": e.refinement_round, "best_ir": e.best_ir, "n": e.n_factors_explored}
+        for e in evidence[:10]
+    ]
+
+    return (
+        f"Generate a NEW market logic H_new for round {round_idx}.\n\n"
+        f"Current library (top 10): {lib_names}\n"
+        f"History: {history_names}\n"
+        f"Evidence history: {ev_summary}\n\n"
+        f"Output STRICT JSON:\n"
+        f"{{\n"
+        f'  "name": "logic_name_v{round_idx}",\n'
+        f'  "predicates": [{{"variable": "close", "op": "ts_mean", '
+        f'"threshold": 0, "window": 20}}],\n'
+        f'  "behavior": {{"target": "forward_return_5", "direction": -1, "horizon": 5}},\n'
+        f'  "operator_whitelist": ["ts_mean", "rank", "sub", "div"],\n'
+        f'  "parameter_ranges": {{"ts_mean": [5, 60]}},\n'
+        f'  "sign_constraint": -1\n'
+        f"}}"
+    )
+
+
+def _build_refiner_prompt(
+    current_logic: WikiLogic,
+    history: List[WikiLogic],
+    evidence: List[LogicPerformanceEvidence],
+) -> str:
+    """MarketLogicRefinementDirectionAgent prompt"""
+    ev_current = current_logic.performance_evidence
+    current_ir = ev_current.best_ir if ev_current else 0.0
+
+    return (
+        f"Provide refinement direction for current logic.\n\n"
+        f"Current logic: {current_logic.name}\n"
+        f"Current best_ir: {current_ir}\n"
+        f"History: {[l.name for l in history[:5]]}\n"
+        f"Evidence: {[(e.refinement_round, e.best_ir) for e in evidence[:5]]}\n\n"
+        f"Output STRICT JSON:\n"
+        f"{{\n"
+        f'  "diagnosis": "logic_too_broad or logic_too_narrow or well_calibrated",\n'
+        f'  "direction": "tighten_threshold or broaden_operators or refine_window",\n'
+        f'  "suggested_changes": {{"parameter_ranges": {{"ts_mean": [10, 30]}}}}\n'
+        f"}}"
+    )
+
+
+def _structured_from_dict(data: Dict[str, Any]) -> WikiLogicStructured:
+    """从 dict 构建 WikiLogicStructured"""
+    predicates = []
+    for p in data.get("predicates", []):
+        predicates.append(LogicCondition(
+            variable=p["variable"],
+            op=p["op"],
+            threshold=p.get("threshold", 0.0),
+            window=p.get("window"),
+            weight=p.get("weight", 1.0),
+            second_variable=p.get("second_variable"),
+        ))
+
+    beh_data = data.get("behavior", {})
+    behavior = LogicBehavior(
+        target=beh_data.get("target", "forward_return_5"),
+        direction=beh_data.get("direction", 1),
+        horizon=beh_data.get("horizon", 5),
+    )
+
+    param_ranges = None
+    if data.get("parameter_ranges"):
+        param_ranges = {k: tuple(v) for k, v in data["parameter_ranges"].items()}
+
+    return WikiLogicStructured(
+        predicates=predicates,
+        behavior=behavior,
+        operator_whitelist=data.get("operator_whitelist"),
+        parameter_ranges=param_ranges,
+        sign_constraint=data.get("sign_constraint"),
+    )
+
+
+def generate_logic_name(base: str, round_idx: int) -> str:
+    """生成逻辑名称"""
+    return f"{base}_v{round_idx}"
+
+
+@dataclass
+class MarketLogicGenerator:
+    """MarketLogicGeneratorAgent
+
+    在初始轮基于 ℋ_init 发散生成；后续轮基于 ℋ_lib + 历史证据做有方向的生成/重构。
+    """
+    llm_client: Any = None
+    base_name: str = "alpha_logic"
+
+    def generate(
+        self,
+        library: List[WikiLogic],
+        current_logic: Optional[WikiLogic] = None,
+        history: Optional[List[WikiLogic]] = None,
+        evidence: Optional[List[LogicPerformanceEvidence]] = None,
+        round_idx: int = 1,
+    ) -> WikiLogic:
+        """生成新逻辑
+
+        Args:
+            library: 当前全部逻辑库 ℋ_lib
+            current_logic: 当前逻辑 H_current
+            history: 历史逻辑列表
+            evidence: 历史证据列表
+            round_idx: 轮次
+
+        Returns:
+            新的 WikiLogic
+        """
+        history = history or []
+        evidence = evidence or []
+
+        # Mock 响应：基于 evidence 趋势生成
+        mock_response = self._mock_generate_response(
+            library, current_logic, history, evidence, round_idx
+        )
+
+        # 调用 LLM
+        prompt = _build_generator_prompt(library, current_logic, history, evidence, round_idx)
+        raw = _call_llm(
+            self.llm_client, "market-logic-generator", prompt, mock_response
+        )
+        result = parse_json_response(raw)
+        if not result.ok:
+            logger.warning("MarketLogicGenerator parse failed: %s, using mock data", result.error)
+            data = json.loads(mock_response)
+        else:
+            data = result.data
+
+        # 构建 WikiLogic
+        name = data.get("name") or generate_logic_name(self.base_name, round_idx)
+        try:
+            structured = _structured_from_dict(data)
+        except Exception as e:
+            logger.warning("Failed to build WikiLogicStructured: %s", e)
+            structured = None
+
+        parent = current_logic.name if current_logic else None
+        WikiLogic = _get_wiki_logic_class()
+        LogicSource = _get_logic_source_class()
+        return WikiLogic(
+            name=name,
+            content=f"Auto-generated logic at round {round_idx}",
+            source=LogicSource.RESEARCH_REPORT,
+            extracted_formula=None,
+            validation_status="pending",
+            structured=structured,
+            parent_logic=parent,
+            refinement_round=round_idx,
+            created_at=datetime.now().isoformat(),
+        )
+
+    def _mock_generate_response(
+        self,
+        library: List[WikiLogic],
+        current_logic: Optional[WikiLogic],
+        history: List[WikiLogic],
+        evidence: List[LogicPerformanceEvidence],
+        round_idx: int,
+    ) -> str:
+        """Mock 响应：基于历史证据趋势生成"""
+        # 基于当前逻辑变体
+        if current_logic and current_logic.structured:
+            base_predicates = [p.to_dict() for p in current_logic.structured.predicates]
+            beh = current_logic.structured.behavior.to_dict()
+            whitelist = current_logic.structured.operator_whitelist or ["rank"]
+            param_ranges = None
+            if current_logic.structured.parameter_ranges:
+                param_ranges = {
+                    k: list(v)
+                    for k, v in current_logic.structured.parameter_ranges.items()
+                }
+            sign = current_logic.structured.sign_constraint
+        else:
+            base_predicates = [{"variable": "close", "op": "ts_mean", "threshold": 0, "window": 20}]
+            beh = {"target": "forward_return_5", "direction": -1, "horizon": 5}
+            whitelist = ["ts_mean", "rank", "sub", "div", "sign"]
+            param_ranges = {"ts_mean": [5, 60]}
+            sign = -1
+
+        # 根据 evidence 调整
+        if evidence and len(evidence) >= 2:
+            # IR 提升则保持方向，否则反转
+            if evidence[-1].best_ir > evidence[-2].best_ir:
+                # 继续优化
+                pass
+            else:
+                # 反转方向
+                sign = -sign if sign else 1
+
+        return json.dumps({
+            "name": generate_logic_name(self.base_name, round_idx),
+            "predicates": base_predicates,
+            "behavior": beh,
+            "operator_whitelist": whitelist,
+            "parameter_ranges": param_ranges or {},
+            "sign_constraint": sign,
+        })
+
+
+@dataclass
+class MarketLogicRefinementDirection:
+    """MarketLogicRefinementDirectionAgent
+
+    综合所有该逻辑名下因子的回测表现，识别"逻辑过宽/过窄/与市场结构错配"的部分。
+    """
+    llm_client: Any = None
+
+    def refine(
+        self,
+        current_logic: WikiLogic,
+        history: Optional[List[WikiLogic]] = None,
+        evidence: Optional[List[LogicPerformanceEvidence]] = None,
+    ) -> Dict[str, Any]:
+        """生成逻辑层反馈
+
+        Args:
+            current_logic: 当前逻辑
+            history: 历史逻辑
+            evidence: 历史证据
+
+        Returns:
+            {
+                "diagnosis": str,
+                "direction": str,
+                "suggested_changes": Dict
+            }
+        """
+        history = history or []
+        evidence = evidence or []
+
+        # Mock 响应
+        mock_response = self._mock_refine_response(current_logic, evidence)
+
+        # 调用 LLM
+        prompt = _build_refiner_prompt(current_logic, history, evidence)
+        raw = _call_llm(
+            self.llm_client, "market-logic-refinement", prompt, mock_response
+        )
+        result = parse_json_response(raw)
+        if not result.ok:
+            logger.warning("Refinement parse failed: %s, using mock", result.error)
+            data = json.loads(mock_response)
+        else:
+            data = result.data
+
+        return {
+            "diagnosis": data.get("diagnosis", "well_calibrated"),
+            "direction": data.get("direction", "no_change"),
+            "suggested_changes": data.get("suggested_changes", {}),
+        }
+
+    def _mock_refine_response(
+        self,
+        current_logic: WikiLogic,
+        evidence: List[LogicPerformanceEvidence],
+    ) -> str:
+        """Mock 响应：基于 IR 趋势给出建议"""
+        if not evidence:
+            diagnosis = "well_calibrated"
+            direction = "no_change"
+        elif len(evidence) >= 2 and evidence[-1].best_ir < evidence[-2].best_ir:
+            diagnosis = "logic_too_broad"
+            direction = "tighten_threshold"
+        elif len(evidence) >= 2 and evidence[-1].best_ir == evidence[-2].best_ir:
+            diagnosis = "saturated"
+            direction = "refine_window"
+        else:
+            diagnosis = "well_calibrated"
+            direction = "no_change"
+
+        return json.dumps({
+            "diagnosis": diagnosis,
+            "direction": direction,
+            "suggested_changes": {
+                "parameter_ranges": {"ts_mean": [10, 30]},
+            },
+        })

QuantNodes/research/quant_alpha/logic_mining/models.py

@@ -0,0 +1,252 @@
+# coding=utf-8
+"""
+models.py - 逻辑结构化数据模型
+
+基于 AlphaLogics 论文的逻辑表示 H = ⟨𝒞, ℬ⟩。
+
+Usage::
+
+    from QuantNodes.research.quant_alpha.logic_mining.models import (
+        LogicCondition, LogicBehavior, WikiLogicStructured,
+    )
+
+    logic = WikiLogicStructured(
+        predicates=[
+            LogicCondition(variable="open", op="rank", threshold=0),
+            LogicCondition(variable="volume", op="ts_corr", threshold=-0.5, window=10),
+        ],
+        behavior=LogicBehavior(target="forward_return_5", direction=-1, horizon=5),
+        operator_whitelist=["rank", "ts_corr", "sign"],
+        parameter_ranges={"ts_corr": (5, 30)},
+        sign_constraint=-1,
+    )
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+
+__all__ = [
+    "LogicCondition",
+    "LogicBehavior",
+    "WikiLogicStructured",
+    "LogicPerformanceEvidence",
+    "LogicAbstractionResult",
+]
+
+
+@dataclass
+class LogicCondition:
+    """单条谓词 (v, op, θ, w)
+
+    对应论文中的条件谓词: variable op threshold
+    """
+
+    variable: str           # 市场变量名: "close", "volume", "open", "high", "low"
+    op: str                 # 算子名: "ts_corr", "ts_mean", "rank"
+    threshold: float        # 阈值 θ
+    window: Optional[int] = None  # 时序算子的窗口 d
+    weight: float = 1.0     # 权重 w
+    second_variable: Optional[str] = None  # 双变量算子的第二个变量
+
+    def to_dict(self) -> Dict[str, Any]:
+        """转换为字典"""
+        d = {
+            "variable": self.variable,
+            "op": self.op,
+            "threshold": self.threshold,
+            "weight": self.weight,
+        }
+        if self.window is not None:
+            d["window"] = self.window
+        if self.second_variable is not None:
+            d["second_variable"] = self.second_variable
+        return d
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> LogicCondition:
+        """从字典创建"""
+        return cls(
+            variable=data["variable"],
+            op=data["op"],
+            threshold=data.get("threshold", 0.0),
+            window=data.get("window"),
+            weight=data.get("weight", 1.0),
+            second_variable=data.get("second_variable"),
+        )
+
+
+@dataclass
+class LogicBehavior:
+    """ℬ = (y, d, h): 行为三元组
+
+    - target: 预测目标 (forward_return_1/5/20)
+    - direction: 信号方向 (+1/-1)
+    - horizon: 持有期天数
+    """
+
+    target: str             # "forward_return_1" / "forward_return_5" / "forward_return_20"
+    direction: int          # +1(信号方向与目标一致)/ -1(反向)
+    horizon: int            # 持有期天数
+
+    def to_dict(self) -> Dict[str, Any]:
+        """转换为字典"""
+        return {
+            "target": self.target,
+            "direction": self.direction,
+            "horizon": self.horizon,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> LogicBehavior:
+        """从字典创建"""
+        return cls(
+            target=data["target"],
+            direction=data["direction"],
+            horizon=data["horizon"],
+        )
+
+
+@dataclass
+class WikiLogicStructured:
+    """H_struct: 规范化后的结构化逻辑
+
+    对应论文中的逻辑表示 H = ⟨𝒞, ℬ⟩。
+    可通过 compile_to_constraint() 编译为 Γ 约束。
+    """
+
+    predicates: List[LogicCondition]  # 条件谓词列表 (𝒞)
+    behavior: LogicBehavior           # 行为目标 (ℬ)
+    operator_whitelist: Optional[List[str]] = None  # 允许的算子族
+    parameter_ranges: Optional[Dict[str, Tuple[float, float]]] = None  # 参数范围
+    sign_constraint: Optional[int] = None  # +1 / -1 / None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """转换为字典（便于 JSON 序列化）"""
+        d: Dict[str, Any] = {
+            "predicates": [p.to_dict() for p in self.predicates],
+            "behavior": self.behavior.to_dict(),
+        }
+        if self.operator_whitelist is not None:
+            d["operator_whitelist"] = self.operator_whitelist
+        if self.parameter_ranges is not None:
+            d["parameter_ranges"] = {
+                k: list(v) for k, v in self.parameter_ranges.items()
+            }
+        if self.sign_constraint is not None:
+            d["sign_constraint"] = self.sign_constraint
+        return d
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> WikiLogicStructured:
+        """从字典创建"""
+        predicates = [LogicCondition.from_dict(p) for p in data.get("predicates", [])]
+        behavior = LogicBehavior.from_dict(data["behavior"])
+
+        param_ranges = None
+        if "parameter_ranges" in data and data["parameter_ranges"] is not None:
+            param_ranges = {
+                k: tuple(v) for k, v in data["parameter_ranges"].items()
+            }
+
+        return cls(
+            predicates=predicates,
+            behavior=behavior,
+            operator_whitelist=data.get("operator_whitelist"),
+            parameter_ranges=param_ranges,
+            sign_constraint=data.get("sign_constraint"),
+        )
+
+    def get_operators(self) -> List[str]:
+        """从谓词中提取所有使用的算子"""
+        ops = set()
+        for p in self.predicates:
+            ops.add(p.op)
+        return sorted(ops)
+
+    def get_variables(self) -> List[str]:
+        """从谓词中提取所有使用的变量"""
+        vars_ = set()
+        for p in self.predicates:
+            vars_.add(p.variable)
+            if p.second_variable:
+                vars_.add(p.second_variable)
+        return sorted(vars_)
+
+
+@dataclass
+class LogicPerformanceEvidence:
+    """聚合的 per-logic 回测证据 E^Logic
+
+    对应论文中每条逻辑下所有因子的回测证据聚合。
+
+    Attributes:
+        n_factors_explored: 探索过的因子数
+        best_ir: 最佳 IR
+        best_ic: 最佳 IC
+        best_factor_id: 最佳因子 ID
+        mean_ir: 平均 IR
+        refinement_round: 第几轮聚合的证据
+        timestamp: 时间戳
+    """
+    n_factors_explored: int = 0
+    best_ir: float = 0.0
+    best_ic: float = 0.0
+    best_factor_id: Optional[str] = None
+    mean_ir: float = 0.0
+    refinement_round: int = 0
+    timestamp: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """转换为字典"""
+        return {
+            "n_factors_explored": self.n_factors_explored,
+            "best_ir": self.best_ir,
+            "best_ic": self.best_ic,
+            "best_factor_id": self.best_factor_id,
+            "mean_ir": self.mean_ir,
+            "refinement_round": self.refinement_round,
+            "timestamp": self.timestamp,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> LogicPerformanceEvidence:
+        """从字典创建"""
+        return cls(
+            n_factors_explored=data.get("n_factors_explored", 0),
+            best_ir=data.get("best_ir", 0.0),
+            best_ic=data.get("best_ic", 0.0),
+            best_factor_id=data.get("best_factor_id"),
+            mean_ir=data.get("mean_ir", 0.0),
+            refinement_round=data.get("refinement_round", 0),
+            timestamp=data.get("timestamp"),
+        )
+
+
+@dataclass
+class LogicAbstractionResult:
+    """Logic Mining 三段式 Agent 的输出
+
+    Attributes:
+        formula_structure: FormulaStructureAgent 输出
+        financial_semantics: FinancialSemanticsMappingAgent 输出
+        structured_logic: MarketLogicAbstractionAgent 输出
+        source_formula: 原始公式
+        source_lib: 来源库 ("alpha101" / "alpha158" / "alpha191")
+    """
+    formula_structure: Dict[str, Any] = field(default_factory=dict)
+    financial_semantics: Dict[str, Any] = field(default_factory=dict)
+    structured_logic: Optional[WikiLogicStructured] = None
+    source_formula: str = ""
+    source_lib: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        """转换为字典"""
+        return {
+            "formula_structure": self.formula_structure,
+            "financial_semantics": self.financial_semantics,
+            "structured_logic": self.structured_logic.to_dict() if self.structured_logic else None,
+            "source_formula": self.source_formula,
+            "source_lib": self.source_lib,
+        }