quantnodes 3.0.0__py3-none-any.whl

QuantNodes/research/quant_alpha/logic_mining/parser.py

@@ -0,0 +1,287 @@
+# coding=utf-8
+"""
+parser.py - Logic Mining 输出解析
+
+解析三个 Agent 的输出 JSON，包含 Schema 校验和默认值。
+
+Usage::
+
+    from QuantNodes.research.quant_alpha.logic_mining.parser import (
+        parse_formula_structure, parse_financial_semantics,
+        parse_market_logic, _mock_structure_response, _mock_semantics_response,
+        _mock_abstraction_response,
+    )
+
+    structure = parse_formula_structure(llm_output)
+    semantics = parse_financial_semantics(llm_output)
+    logic = parse_market_logic(llm_output)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "ParseResult",
+    "parse_json_response",
+    "parse_formula_structure",
+    "parse_financial_semantics",
+    "parse_market_logic",
+    "_mock_structure_response",
+    "_mock_semantics_response",
+    "_mock_abstraction_response",
+]
+
+
+@dataclass
+class ParseResult:
+    """JSON 解析结果"""
+    ok: bool
+    data: Optional[Dict[str, Any]] = None
+    error: Optional[str] = None
+    raw: str = ""
+
+
+def parse_json_response(raw: str) -> ParseResult:
+    """三层 fallback JSON parser
+
+    1. 直接 json.loads
+    2. 从 markdown ```json ... ``` 中提取
+    3. 从文本中找第一个 {...} 块
+
+    Args:
+        raw: LLM 输出文本
+
+    Returns:
+        ParseResult
+    """
+    if not raw:
+        return ParseResult(ok=False, error="empty response", raw=raw)
+
+    # 第 1 层: 直接 JSON
+    try:
+        return ParseResult(ok=True, data=json.loads(raw), raw=raw)
+    except json.JSONDecodeError:
+        pass
+
+    # 第 2 层: 从 ```json ... ``` 中提取
+    md_match = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", raw, re.DOTALL)
+    if md_match:
+        try:
+            return ParseResult(ok=True, data=json.loads(md_match.group(1)), raw=raw)
+        except json.JSONDecodeError:
+            pass
+
+    # 第 3 层: 找第一个 {...} 块
+    brace_match = re.search(r"\{.*\}", raw, re.DOTALL)
+    if brace_match:
+        try:
+            return ParseResult(ok=True, data=json.loads(brace_match.group(0)), raw=raw)
+        except json.JSONDecodeError:
+            pass
+
+    return ParseResult(ok=False, error="Cannot parse JSON after 3 layers", raw=raw)
+
+
+def parse_formula_structure(raw: str) -> ParseResult:
+    """解析 FormulaStructureAgent 输出
+
+    期望格式:
+    {
+        "operations": ["rank", "ts_corr"],
+        "window_length": 10,
+        "has_ranking": true,
+        "has_normalization": false
+    }
+    """
+    result = parse_json_response(raw)
+    if not result.ok:
+        return result
+
+    data = result.data
+    if not isinstance(data, dict):
+        return ParseResult(ok=False, error="data is not a dict", raw=raw)
+
+    # 必填字段验证
+    if "operations" not in data:
+        return ParseResult(ok=False, error="missing 'operations' field", raw=raw)
+
+    # 填充默认值
+    validated = {
+        "operations": data.get("operations", []),
+        "window_length": data.get("window_length", 0),
+        "has_ranking": data.get("has_ranking", False),
+        "has_normalization": data.get("has_normalization", False),
+    }
+
+    return ParseResult(ok=True, data=validated, raw=raw)
+
+
+def parse_financial_semantics(raw: str) -> ParseResult:
+    """解析 FinancialSemanticsMappingAgent 输出
+
+    期望格式:
+    {
+        "price_role": "initial reaction",
+        "volume_role": "participation",
+        "time_pattern": "persistent co-movement",
+        "behavior_interpretation": "lack of confirmation indicates reversal"
+    }
+    """
+    result = parse_json_response(raw)
+    if not result.ok:
+        return result
+
+    data = result.data
+    if not isinstance(data, dict):
+        return ParseResult(ok=False, error="data is not a dict", raw=raw)
+
+    validated = {
+        "price_role": data.get("price_role", "unknown"),
+        "volume_role": data.get("volume_role", "unknown"),
+        "time_pattern": data.get("time_pattern", "unknown"),
+        "behavior_interpretation": data.get("behavior_interpretation", "unknown"),
+    }
+
+    return ParseResult(ok=True, data=validated, raw=raw)
+
+
+def parse_market_logic(raw: str) -> ParseResult:
+    """解析 MarketLogicAbstractionAgent 输出
+
+    期望格式:
+    {
+        "predicates": [{"variable": "open", "op": "rank", "threshold": 0}],
+        "behavior": {"target": "forward_return_5", "direction": -1, "horizon": 5},
+        "operator_whitelist": ["rank", "ts_corr", "sign"],
+        "parameter_ranges": {"ts_corr": [5, 30]},
+        "sign_constraint": -1
+    }
+    """
+    result = parse_json_response(raw)
+    if not result.ok:
+        return result
+
+    data = result.data
+    if not isinstance(data, dict):
+        return ParseResult(ok=False, error="data is not a dict", raw=raw)
+
+    # 必填字段验证
+    if "predicates" not in data or "behavior" not in data:
+        return ParseResult(ok=False, error="missing 'predicates' or 'behavior'", raw=raw)
+
+    return ParseResult(ok=True, data=data, raw=raw)
+
+
+# ==============================================================================
+# Mock 响应（用于离线测试）
+# ==============================================================================
+
+
+def _mock_structure_response(formula: str) -> str:
+    """生成 FormulaStructureAgent 的 mock 响应"""
+    import re as _re
+
+    # 提取算子
+    ops = set(_re.findall(r"\b([a-zA-Z_]\w*)\s*\(", formula))
+    ops.discard("if")
+    ops.discard("else")
+
+    # 提取最大窗口
+    nums = [int(n) for n in _re.findall(r",\s*(\d+)\s*\)", formula)]
+    max_window = max(nums) if nums else 0
+
+    return json.dumps({
+        "operations": sorted(ops),
+        "window_length": max_window,
+        "has_ranking": "rank(" in formula,
+        "has_normalization": any(op in formula for op in ["zscore", "normalize"]),
+    })
+
+
+def _mock_semantics_response(formula: str) -> str:
+    """生成 FinancialSemanticsMappingAgent 的 mock 响应"""
+    # 基于算子推断语义
+    has_corr = "corr(" in formula or "ts_corr" in formula
+    has_volume = "vol" in formula.lower() or "amount" in formula
+    has_ts_mean = "ts_mean(" in formula
+    has_rank = "rank(" in formula
+
+    price_role = "mean reversion" if "delta(" in formula else "trend indicator"
+    volume_role = "participation" if has_volume else "not used"
+    time_pattern = (
+        "windowed co-movement" if has_corr else
+        "moving average" if has_ts_mean else "single point"
+    )
+    behavior = (
+        "divergence signal" if has_corr and has_volume else
+        "momentum/reversal indicator" if has_rank else
+        "neutral"
+    )
+
+    return json.dumps({
+        "price_role": price_role,
+        "volume_role": volume_role,
+        "time_pattern": time_pattern,
+        "behavior_interpretation": behavior,
+    })
+
+
+def _mock_abstraction_response(
+    formula: str,
+    structure: Dict[str, Any],
+    semantics: Dict[str, Any],
+) -> str:
+    """生成 MarketLogicAbstractionAgent 的 mock 响应"""
+    # 基于公式特征生成结构化逻辑
+    operations = structure.get("operations", [])
+    has_volume = semantics.get("volume_role", "not used") != "not used"
+    has_corr = "ts_corr" in operations or "corr" in operations
+    has_ts_mean = "ts_mean" in operations
+
+    # 行为推断
+    if has_corr and has_volume:
+        direction = -1  # 量价背离 → 反转
+        target = "forward_return_5"
+        horizon = 5
+        predicates = [
+            {"variable": "open", "op": "rank", "threshold": 0},
+            {"variable": "volume", "op": "rank", "threshold": 0},
+            {"variable": "open", "op": "ts_corr", "threshold": -0.5,
+             "window": 10, "second_variable": "volume"},
+        ]
+        whitelist = ["rank", "ts_corr", "sign", "sub", "mul", "div"]
+        param_ranges = {"ts_corr": [5, 30]}
+        sign = -1
+    elif has_ts_mean:
+        direction = -1
+        target = "forward_return_5"
+        horizon = 5
+        predicates = [
+            {"variable": "close", "op": "ts_mean", "threshold": 0, "window": 20},
+        ]
+        whitelist = ["ts_mean", "rank", "sub", "div", "sign"]
+        param_ranges = {"ts_mean": [5, 60]}
+        sign = -1
+    else:
+        direction = 1
+        target = "forward_return_1"
+        horizon = 1
+        predicates = [{"variable": "close", "op": "rank", "threshold": 0}]
+        whitelist = operations if operations else ["rank"]
+        param_ranges = {}
+        sign = 1
+
+    return json.dumps({
+        "predicates": predicates,
+        "behavior": {"target": target, "direction": direction, "horizon": horizon},
+        "operator_whitelist": whitelist,
+        "parameter_ranges": param_ranges,
+        "sign_constraint": sign,
+    })

QuantNodes/research/quant_alpha/logic_mining/pipelines.py

@@ -0,0 +1,297 @@
+# coding=utf-8
+"""
+pipelines.py - Logic Mining 三段式 Agent Pipeline
+
+基于 AlphaLogics 论文 (arXiv 2603.20247) §3.1 实现。
+
+三段式流程:
+  FormulaStructureAgent → FinancialSemanticsMappingAgent → MarketLogicAbstractionAgent
+  → WikiLogicStructured
+
+Usage::
+
+    from QuantNodes.research.quant_alpha.logic_mining.pipelines import (
+        LogicMiningPipeline, mine_logic_from_formula, build_initial_logic_library,
+    )
+
+    # 单条公式
+    logic = mine_logic_from_formula(
+        formula="-ts_corr(rank(open), rank(volume), 10)",
+        source_lib="alpha101",
+    )
+
+    # 批量构建逻辑库
+    logics = build_initial_logic_library(
+        source_libs=("alpha101", "alpha158"),
+        max_per_lib=20,
+    )
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+
+from QuantNodes.research.quant_alpha.logic_mining.models import (
+    LogicBehavior,
+    LogicCondition,
+    LogicAbstractionResult,
+    WikiLogicStructured,
+)
+from QuantNodes.research.quant_alpha.logic_mining.parser import (
+    parse_financial_semantics,
+    parse_formula_structure,
+    parse_market_logic,
+    _mock_structure_response,
+    _mock_semantics_response,
+    _mock_abstraction_response,
+)
+from QuantNodes.research.quant_alpha.logic_mining.sources import get_formulas_from_source
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "LogicMiningPipeline",
+    "mine_logic_from_formula",
+    "build_initial_logic_library",
+]
+
+
+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_structure_prompt(formula: str) -> str:
+    """FormulaStructureAgent prompt"""
+    return (
+        f"Analyze the structure of this alpha formula:\n"
+        f"  {formula}\n\n"
+        f"Output STRICT JSON with these fields:\n"
+        f"- operations: list of function names used\n"
+        f"- window_length: largest numeric window parameter\n"
+        f"- has_ranking: true if rank() is used\n"
+        f"- has_normalization: true if zscore/normalize is used\n\n"
+        f"Example output:\n"
+        f'{{"operations": ["rank", "ts_corr", "sign"], '
+        f'"window_length": 10, "has_ranking": true, "has_normalization": false}}'
+    )
+
+
+def _build_semantics_prompt(formula: str, structure: Dict[str, Any]) -> str:
+    """FinancialSemanticsMappingAgent prompt"""
+    ops = structure.get("operations", [])
+    return (
+        f"Given formula: {formula}\n"
+        f"Operations: {ops}\n\n"
+        f"Map to financial semantics. Output STRICT JSON:\n"
+        f"- price_role: role of price (e.g., 'trend', 'reversion', 'momentum')\n"
+        f"- volume_role: role of volume ('participation', 'confirmation', 'not used')\n"
+        f"- time_pattern: time pattern ('windowed', 'moving average', 'cumulative')\n"
+        f"- behavior_interpretation: behavior interpretation (e.g., 'divergence signal')\n\n"
+        f'Example: {{"price_role": "trend", "volume_role": "participation", '
+        f'"time_pattern": "windowed", "behavior_interpretation": "divergence signal"}}'
+    )
+
+
+def _build_abstraction_prompt(
+    formula: str,
+    structure: Dict[str, Any],
+    semantics: Dict[str, Any],
+) -> str:
+    """MarketLogicAbstractionAgent prompt"""
+    return (
+        f"Abstract this alpha into a formal market logic H = ⟨𝒞, ℬ⟩.\n\n"
+        f"Formula: {formula}\n"
+        f"Structure: {structure}\n"
+        f"Semantics: {semantics}\n\n"
+        f"Output STRICT JSON:\n"
+        f"- predicates: list of {{variable, op, threshold, window, second_variable}}\n"
+        f"- behavior: {{target, direction, horizon}}  (target='forward_return_5', direction=+1/-1)\n"
+        f"- operator_whitelist: list of allowed operators\n"
+        f"- parameter_ranges: {{op: [min, max]}}\n"
+        f"- sign_constraint: +1/-1 or null\n\n"
+        f'Example: {{"predicates": [{{"variable": "open", "op": "ts_corr", '
+        f'"threshold": -0.5, "window": 10, "second_variable": "volume"}}], '
+        f'"behavior": {{"target": "forward_return_5", "direction": -1, "horizon": 5}}, '
+        f'"operator_whitelist": ["rank", "ts_corr", "sign"], '
+        f'"parameter_ranges": {{"ts_corr": [5, 30]}}, '
+        f'"sign_constraint": -1}}'
+    )
+
+
+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"),
+    )
+
+
+class LogicMiningPipeline:
+    """Logic Mining 三段式 Pipeline
+
+    FormulaStructureAgent → FinancialSemanticsMappingAgent → MarketLogicAbstractionAgent
+    """
+
+    def __init__(self, llm_client: Any = None):
+        self.llm_client = llm_client
+
+    def run(self, formula: str, source_lib: str = "alpha101") -> LogicAbstractionResult:
+        """运行三段式 Pipeline
+
+        Args:
+            formula: 因子公式字符串
+            source_lib: 来源库名称
+
+        Returns:
+            LogicAbstractionResult
+        """
+        result = LogicAbstractionResult(
+            source_formula=formula,
+            source_lib=source_lib,
+        )
+
+        # Step 1: FormulaStructureAgent
+        structure_resp = _call_llm(
+            self.llm_client,
+            "logic-mining-structure",
+            _build_structure_prompt(formula),
+            _mock_structure_response(formula),
+        )
+        struct_result = parse_formula_structure(structure_resp)
+        if not struct_result.ok:
+            logger.warning("FormulaStructureAgent parse failed: %s", struct_result.error)
+            result.formula_structure = {"operations": [], "window_length": 0,
+                                        "has_ranking": False, "has_normalization": False}
+        else:
+            result.formula_structure = struct_result.data
+
+        # Step 2: FinancialSemanticsMappingAgent
+        semantics_resp = _call_llm(
+            self.llm_client,
+            "logic-mining-semantics",
+            _build_semantics_prompt(formula, result.formula_structure),
+            _mock_semantics_response(formula),
+        )
+        sem_result = parse_financial_semantics(semantics_resp)
+        if not sem_result.ok:
+            logger.warning("FinancialSemanticsMappingAgent parse failed: %s", sem_result.error)
+            result.financial_semantics = {
+                "price_role": "unknown", "volume_role": "unknown",
+                "time_pattern": "unknown", "behavior_interpretation": "unknown",
+            }
+        else:
+            result.financial_semantics = sem_result.data
+
+        # Step 3: MarketLogicAbstractionAgent
+        abstract_resp = _call_llm(
+            self.llm_client,
+            "logic-mining-abstraction",
+            _build_abstraction_prompt(formula, result.formula_structure, result.financial_semantics),
+            _mock_abstraction_response(formula, result.formula_structure, result.financial_semantics),
+        )
+        abs_result = parse_market_logic(abstract_resp)
+        if not abs_result.ok:
+            logger.warning("MarketLogicAbstractionAgent parse failed: %s", abs_result.error)
+            return result
+
+        try:
+            result.structured_logic = _structured_from_dict(abs_result.data)
+        except (KeyError, TypeError) as e:
+            logger.warning("Failed to build WikiLogicStructured: %s", e)
+
+        return result
+
+
+def mine_logic_from_formula(
+    formula: str,
+    source_lib: str = "alpha101",
+    llm_client: Any = None,
+) -> LogicAbstractionResult:
+    """从单条公式抽取市场逻辑（三段式）
+
+    Args:
+        formula: 因子公式字符串
+        source_lib: 来源库
+        llm_client: LLM 客户端 (None 时使用 mock)
+
+    Returns:
+        LogicAbstractionResult
+    """
+    pipeline = LogicMiningPipeline(llm_client=llm_client)
+    return pipeline.run(formula, source_lib)
+
+
+def build_initial_logic_library(
+    source_libs: Tuple[str, ...] = ("alpha101", "alpha158"),
+    llm_client: Any = None,
+    max_per_lib: int = 20,
+    only_volume_price: bool = True,
+) -> List[LogicAbstractionResult]:
+    """构建初始逻辑库
+
+    Args:
+        source_libs: 来源库列表
+        llm_client: LLM 客户端
+        max_per_lib: 每个库最多提取多少条
+        only_volume_price: 仅提取量价类
+
+    Returns:
+        List of LogicAbstractionResult
+    """
+    pipeline = LogicMiningPipeline(llm_client=llm_client)
+    results = []
+
+    for lib in source_libs:
+        formulas = get_formulas_from_source(
+            lib, max_count=max_per_lib, only_volume_price=only_volume_price
+        )
+        logger.info("Mining %d formulas from %s", len(formulas), lib)
+
+        for f in formulas:
+            try:
+                result = pipeline.run(f["formula"], lib)
+                if result.structured_logic is not None:
+                    results.append(result)
+            except Exception as e:
+                logger.warning("Failed to mine logic for %s: %s", f.get("id"), e)
+
+    logger.info("Built initial logic library: %d logics", len(results))
+    return results