quantnodes 3.0.0__tar.gz → 3.0.2__tar.gz

{quantnodes-3.0.0 → quantnodes-3.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantnodes
-Version: 3.0.0
+Version: 3.0.2
 Summary: AI-native quantitative research framework with symbolic computation and SQL pushdown
 Author-email: sn0wfree <snowfreedom0815@gmail.com>
 License: MIT

quantnodes-3.0.2/QuantNodes/agent/skills_quant/logic-mining/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: logic-mining
+description: 市场逻辑驱动的自动化因子挖掘 — Logic Mining + Γ 约束内层生成 + Wiki 沉淀。
+---
+
+# Logic Mining (v3.0.1)
+
+驱动 QuantNodes Logic Mining 端到端工作流：选取 source → 3-stage LLM 抽取逻辑 → 编译 Γ 约束 → 内层 Alpha-GPT 受约束生成因子 → 外层重构 → 写入 Wiki。
+
+## 工作流
+
+1. **选 source 与定逻辑种子** — 调用 `sources.list_available_sources` 列数据源 (`alpha101` / `alpha158` / `alpha191`)，`sources.get_formulas_from_source(lib, max_count=N, only_volume_price=True)` 加载前 N 条公式
+2. **3-stage 抽取逻辑** — 对每条公式:
+   - 调用 `LogicMiningPipeline.run(formula, source_lib=lib)` 走 3 个 sub-agent (structure / semantics / abstraction)
+   - 返回 `LogicAbstractionResult` 含 `structured_logic` (`WikiLogicStructured`)
+3. **编译 Γ 约束** — 调用 `logic_mining.compile_to_constraint(logic.structured, source_logic=name)` 生成 `CompiledConstraint`
+4. **注入 Alpha-GPT** — 在 `AlphaGptConfig.gamma = gamma` 透传；下游 `_step_formula_translator` 拒绝任何不符合 Γ 的公式
+5. **内层循环** — 调用 `AlphaGptWorkflow(config=...).run()`，产出 inner_results 与 per-logic `LogicPerformanceEvidence`
+6. **外层重构** — 调用 `MarketLogicGenerator.generate(library, current_logic, history, evidence, round_idx)` 与 `MarketLogicRefinementDirection.refine(...)` 进入下一轮 Algorithm 2 编排
+7. **沉淀 Wiki** — 调用 `wiki_write` 写入 `Logic/` 页面，附 Γ + evidence
+
+## 工具集
+
+| 工具 | 用途 |
+|------|------|
+| `logic_mine` | `mine_logic_from_formula(formula, source_lib, llm_client)` 走 3-stage |
+| `logic_compile` | `compile_to_constraint(logic, source_logic)` 生成 Γ |
+| `logic_refine` | `MarketLogicRefinementDirection.refine(current_logic, history, evidence)` |
+| `logic_validate` | `gamma.validate(formula_str)` 校验公式是否过 Γ |
+| `logic_library_build` | `build_initial_logic_library(source_libs, llm_client, max_per_lib)` |
+| `wiki_write` | 写入 Wiki Logic 页面 |
+
+## 验收标准
+
+- 初始逻辑库 ≥ 5 条 (从 alpha101 / alpha158 抽取)
+- 每条逻辑最终 γ.validate(formula) 在示例上通过
+- per-logic evidence 包含 `n_factors_explored` / `best_ir` / `best_ic`
+- IR 上升 → 窗口收窄 20% (Phase 3 P0-3 修复)
+- best_ic != best_ir (Phase 3 P0-2 修复)
+- alpha191 source 不再静默 (Phase 3 P0-1 修复)
+- silent fallback 通过 `pipeline.metrics` / `result.diagnostics` 暴露 (Phase 2)
+- 可选 `strict=StrictConfig(...)` 把失败升级为异常
+
+## 反模式
+
+- 不要直接调用 inner AlphaGptWorkflow 而跳过 3-stage logic 抽取（失去 Logic Mining 意义）
+- 不要忽略 `result.parse_error` / `result.diagnostics` 字段（silent fallback 信号）
+- 不要用 `best_ic` 字段当 IR 读 (v3.0.0 时期旧 docstring 是错的, P0-2 已修)
+- 不要在 IR 上升时反转 sign（这是 IR 下降的响应）
+- 不要修改 alpha191 数据源逻辑，它是 OHLCV-only 守卫

{quantnodes-3.0.0 → quantnodes-3.0.2}/QuantNodes/cli/commands/__init__.py

@@ -29,6 +29,7 @@ def _register_all() -> None:
     from QuantNodes.cli.commands.agent import AgentCommand
     from QuantNodes.cli.commands.evolve import EvolveCommand
     from QuantNodes.cli.commands.alpha import AlphaMctsCommand, AlphaGptCommand, AlphaPipelineCommand
+    from QuantNodes.cli.commands.mine_logics import MineLogicsCommand
     from QuantNodes.cli.commands.factor import (
         FactorInfoCommand,
         FactorBestCommand,
@@ -53,6 +54,7 @@ def _register_all() -> None:
         AlphaMctsCommand(),
         AlphaGptCommand(),
         AlphaPipelineCommand(),
+        MineLogicsCommand(),
         FactorInfoCommand(),
         FactorBestCommand(),
         FactorVisualCommand(),

quantnodes-3.0.2/QuantNodes/cli/commands/mine_logics.py

@@ -0,0 +1,196 @@
+# coding=utf-8
+"""
+CLI 命令: mine-logics — 并发批量逻辑挖掘 (v3.0.2)
+
+Usage:
+    quantnodes mine-logics --max-per-lib 5 --workers 2 --live
+    quantnodes mine-logics --source-libs alpha101,alpha191 --max-per-lib 10
+    quantnodes mine-logics --wiki-path wiki_auto --output-dir data/mine_runs
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from QuantNodes.cli.command import Command
+from QuantNodes.research.quant_alpha.logic_mining.batch import (
+    ThreadSafeMetrics,
+    mine_logic_library_v2,
+)
+from QuantNodes.research.quant_alpha.logic_mining.report import MetricsReportBuilder
+
+
+class MineLogicsCommand(Command):
+    """quantnodes mine-logics - 并发批量逻辑挖掘
+
+    并发挖掘 alpha101/alpha158/alpha191 的逻辑结构，
+    生成 Logic pages 到 Wiki，输出 JSON + Markdown 报告。
+
+    默认使用 NullLLMClient（离线模式）；加 --live 走真实 LLM。
+    """
+    name = "mine-logics"
+    description = "并发批量逻辑挖掘（v3.0.2）"
+
+    def add_arguments(self, subparsers: object) -> None:
+        parser: argparse.ArgumentParser = subparsers.add_parser(
+            self.name,
+            help=self.description,
+            description=(
+                "基于 LogicMiningPipeline 三段式 Agent 的并发批量挖掘。\n"
+                "支持幂等重跑（跳过已存在 Logic pages）。\n"
+                "默认离线模式（NullLLMClient）；加 --live 走真实 LLM。"
+            ),
+        )
+        parser.add_argument(
+            "--source-libs",
+            type=str,
+            default="alpha101,alpha158,alpha191",
+            help="逗号分隔的来源库列表（默认 alpha101,alpha158,alpha191）",
+        )
+        parser.add_argument(
+            "--max-per-lib",
+            type=int,
+            default=10,
+            help="每个来源库最多挖掘多少条公式（默认 10）",
+        )
+        parser.add_argument(
+            "--workers",
+            type=int,
+            default=4,
+            help="并发线程数（默认 4）",
+        )
+        parser.add_argument(
+            "--wiki-path",
+            type=str,
+            default="wiki_auto",
+            help="Wiki 根目录（默认 wiki_auto）",
+        )
+        parser.add_argument(
+            "--output-dir",
+            type=str,
+            default="data/mine_runs",
+            help="报告输出目录（默认 data/mine_runs）",
+        )
+        parser.add_argument(
+            "--live",
+            action="store_true",
+            help="使用真实 LLM（默认离线 NullLLMClient）",
+        )
+        parser.add_argument(
+            "--strict",
+            action="store_true",
+            help="启用严格模式（LLM/parse/structured 异常上抛）",
+        )
+        parser.add_argument(
+            "--no-skip",
+            action="store_true",
+            help="不跳过已存在的 Logic pages（默认幂等跳过）",
+        )
+        parser.add_argument(
+            "--quiet", "-q",
+            action="store_true",
+            help="安静模式（不打印进度）",
+        )
+
+    def run(self, args: argparse.Namespace) -> int:
+        source_libs = [s.strip() for s in args.source_libs.split(",") if s.strip()]
+        if not source_libs:
+            print("Error: --source-libs is empty", file=sys.stderr)
+            return 2
+
+        output_dir = Path(args.output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        # 选择 LLM 客户端
+        llm_client = None
+        if args.live:
+            try:
+                from QuantNodes.ai.llm.gateway import get_llm_gateway
+                llm_client = get_llm_gateway()
+                print(f"[mine-logics] Live mode: LLM gateway initialized")
+            except Exception as exc:
+                print(f"Error: Failed to initialize LLM gateway: {exc}", file=sys.stderr)
+                return 2
+        else:
+            print("[mine-logics] Offline mode: using NullLLMClient")
+
+        # 构建 metrics + strict
+        metrics = ThreadSafeMetrics()
+        strict = None
+        if args.strict:
+            from QuantNodes.research.quant_alpha.logic_mining.metrics import StrictConfig
+            strict = StrictConfig(call=True, parse=True, structured=True)
+
+        # 进度回调
+        def _on_progress(done: int, total: int, fid: str) -> None:
+            if not args.quiet:
+                print(f"  [{done}/{total}] {fid}", flush=True)
+
+        print(f"[mine-logics] Source libs: {source_libs}")
+        print(f"[mine-logics] max_per_lib={args.max_per_lib}, workers={args.workers}")
+        print(f"[mine-logics] wiki_path={args.wiki_path}")
+        print()
+
+        t0 = time.perf_counter()
+        try:
+            batch = mine_logic_library_v2(
+                source_libs=source_libs,
+                llm_client=llm_client,
+                max_per_lib=args.max_per_lib,
+                workers=args.workers,
+                metrics=metrics,
+                strict=strict,
+                wiki_path=args.wiki_path,
+                skip_existing=not args.no_skip,
+                on_progress=_on_progress,
+            )
+        except Exception as exc:
+            print(f"Fatal error: {exc}", file=sys.stderr)
+            return 2
+
+        # 生成报告
+        report = MetricsReportBuilder.from_batch(batch)
+        ts = datetime.utcnow().strftime("%Y%m%d_%H%M%S")
+        json_path = output_dir / f"metrics_{ts}.json"
+        md_path = output_dir / f"metrics_{ts}.md"
+        report.to_json(json_path)
+        md_text = report.to_markdown()
+        md_path.write_text(md_text, encoding="utf-8")
+
+        # 打印摘要
+        print()
+        print(f"[mine-logics] Done in {batch.wall_clock_s:.2f}s")
+        print(f"  Attempted: {len(batch.attempted_ids)}")
+        print(f"  Mined:     {batch.n_mined}")
+        print(f"  Skipped:   {batch.n_skipped}")
+        print(f"  Failed:    {batch.n_failed}")
+        if batch.warnings:
+            for w in batch.warnings:
+                print(f"  Warning:   {w}")
+        print(f"  Reports:   {json_path} / {md_path}")
+
+        # Wiki 写入
+        if batch.pool and batch.n_mined > 0:
+            try:
+                from QuantNodes.research.wiki import WikiFactorProxy
+                proxy = WikiFactorProxy(wiki_path=args.wiki_path)
+                n_written = batch.pool.to_wiki(proxy)
+                print(f"  Wiki:      {n_written} Logic pages written to {args.wiki_path}/")
+                failed = batch.pool.failed_writes()
+                if failed:
+                    print(f"  Wiki failures: {len(failed)}")
+            except Exception as exc:
+                print(f"  Wiki write failed: {exc}", file=sys.stderr)
+
+        # 退出码
+        if batch.n_failed > 0:
+            return 1  # 部分成功
+        if batch.n_mined == 0 and batch.n_skipped == 0:
+            return 2  # 空结果
+        return 0  # 全部成功

{quantnodes-3.0.0 → quantnodes-3.0.2}/QuantNodes/research/quant_alpha/__init__.py

@@ -32,6 +32,12 @@ from QuantNodes.research.quant_alpha.operator_vocab import (
     get_vocab_metadata,
 )
 
+# v3.0.2 自动化挖掘 API
+from QuantNodes.research.quant_alpha.factor_pool import (
+    FactorEntry,
+    FactorPool,
+)
+
 __all__ = [
     # 主类
     "OperatorVocab",
@@ -42,4 +48,7 @@ __all__ = [
     "list_vocab_operators",
     "get_vocab_operator",
     "get_vocab_metadata",
+    # v3.0.2 FactorPool
+    "FactorEntry",
+    "FactorPool",
 ]