quantnodes 3.0.0__py3-none-any.whl

QuantNodes/agent/tools/__init__.py

@@ -0,0 +1,173 @@
+# coding=utf-8
+"""
+工具系统模块
+
+Tool基类（继承自 HKUDS nanobot upstream Tool）/ 注册表 / 具体工具实现
+"""
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from .base import Tool, ToolExecutionResult
+from .context import ToolContext, ToolContextFactory
+from .registry import ToolRegistry
+from .echo import EchoTool
+from .sandbox import SandboxTool
+from .pipeline import PipelineTool
+from .strategy import StrategyTool
+from .backtest import BacktestTool
+from .factor import FactorTool
+from .config_backtest import ConfigBacktestTool
+from .wiki import WikiTool
+from .file_ops import FileOpsTool
+from .code_search import CodeSearchTool
+from .git_ops import GitOpsTool
+from .web_fetch import WebFetchTool
+from .web_search import WebSearchTool
+from .task import TaskTool
+from .alpha_evaluate import AlphaEvaluateTool
+from .alpha_backtest import AlphaBacktestTool
+from .operator_lookup import OperatorLookupTool
+
+logger = logging.getLogger(__name__)
+
+
+_QUANT_TOOL_FACTORIES = [
+    EchoTool,
+    SandboxTool,
+    PipelineTool,
+    StrategyTool,
+    BacktestTool,
+    FactorTool,
+    ConfigBacktestTool,
+    WikiTool,
+    FileOpsTool,
+    CodeSearchTool,
+    GitOpsTool,
+    WebFetchTool,
+    WebSearchTool,
+    TaskTool,
+    AlphaEvaluateTool,
+    AlphaBacktestTool,
+    OperatorLookupTool,
+]
+
+
+def register_all_quant_tools(
+    registry: ToolRegistry,
+    workspace: Path | None = None,
+    llm_client: Any = None,
+    model: str | None = None,
+) -> int:
+    """Register all 17 quant tool classes (echo/sandbox/.../operator_lookup) into a registry.
+
+    Returns the number of quant tools registered. Idempotent: re-registration
+    of an existing tool name is skipped (the upstream registry overwrites by
+    name, but we prefer explicit skip to surface duplicate-name bugs early).
+
+    Plugin discovery (P2 Step 10):
+        优先使用 entry_points (quantnodes.tools 组) 发现插件。
+        如 entry_points 为空 (dev 模式未安装), 回退到硬编码 _QUANT_TOOL_FACTORIES。
+        第三方插件可通过自己的 pyproject.toml 声明 entry_points 自动接入。
+
+    ``workspace`` is forwarded to tools that need it (``WikiTool``,
+    ``FileOpsTool``, ``CodeSearchTool``, ``GitOpsTool``, ``TaskTool``).
+    Other tools take no constructor args.
+
+    ``llm_client`` and ``model`` are forwarded to ``WorkflowTool`` (if
+    nanobot is available). When ``llm_client`` is provided, the
+    ``run_workflow`` tool is registered, enabling LLM-driven pipeline
+    execution via ``WorkflowRegistry``.
+
+    Usage from Agent.__init__::
+
+        from nanobot.agent.tools.registry import ToolRegistry
+        from QuantNodes.agent import register_all_quant_tools
+        register_all_quant_tools(self._loop.tools, workspace=self.workspace)
+    """
+    if workspace is None:
+        workspace = Path(".agent")
+    workspace = Path(workspace)
+
+    workspace_dep = {
+        "WikiTool": {"wiki_path": str(workspace / "wiki")},
+        "FileOpsTool": {"workspace": workspace},
+        "CodeSearchTool": {"workspace": workspace},
+        "GitOpsTool": {"workspace": workspace},
+        "TaskTool": {"workspace": workspace},
+    }
+
+    # 尝试通过 entry_points 发现插件 (P2 Step 10)
+    plugin_tools: dict[str, type] = {}
+    try:
+        from QuantNodes.core.plugin import discover_tools
+
+        plugin_tools = discover_tools()
+    except Exception as e:
+        logger.debug("Plugin discovery unavailable, using fallback: %s", e)
+
+    # 选择 tool factories 来源: 优先 entry_points, 否则回退硬编码
+    if plugin_tools:
+        tool_factories = list(plugin_tools.values())
+        logger.debug("Using %d tool plugins from entry_points", len(tool_factories))
+    else:
+        tool_factories = _QUANT_TOOL_FACTORIES
+
+    registered = 0
+    for factory in tool_factories:
+        kwargs = workspace_dep.get(factory.__name__, {})
+        try:
+            tool = factory(**kwargs) if kwargs else factory()
+        except (TypeError, Exception) as exc:
+            logger.warning("Failed to register quant tool %s: %s", factory.__name__, exc)
+            continue
+        if registry.has(tool.name):
+            continue
+        registry.register(tool)
+        registered += 1
+
+    # Register WorkflowTool (run_workflow) if llm_client is provided
+    if llm_client is not None:
+        try:
+            from ..workflows.tool import WorkflowTool
+
+            wt = WorkflowTool(
+                llm_client=llm_client,
+                model=model,
+                results_dir=workspace / "results",
+            )
+            if not registry.has(wt.name):
+                registry.register(wt)
+                registered += 1
+        except Exception as exc:
+            logger.warning("Failed to register WorkflowTool: %s", exc)
+
+    return registered
+
+
+__all__ = [
+    "Tool",
+    "ToolExecutionResult",
+    "ToolContext",
+    "ToolContextFactory",
+    "ToolRegistry",
+    "register_all_quant_tools",
+    "EchoTool",
+    "SandboxTool",
+    "PipelineTool",
+    "StrategyTool",
+    "BacktestTool",
+    "FactorTool",
+    "ConfigBacktestTool",
+    "WikiTool",
+    "FileOpsTool",
+    "CodeSearchTool",
+    "GitOpsTool",
+    "WebFetchTool",
+    "WebSearchTool",
+    "TaskTool",
+    "AlphaEvaluateTool",
+    "AlphaBacktestTool",
+    "OperatorLookupTool",
+]

QuantNodes/agent/tools/_workspace.py

@@ -0,0 +1,51 @@
+"""WorkspaceTool mixin — Phase J1 (2026-06-20).
+
+Consolidates the 4-times-repeated pattern across agent tools:
+  - self.workspace = Path(workspace).resolve()
+  - _safe_path(rel_path) guard against ../ path traversal
+
+Used by:
+  - CodeSearchTool
+  - FileOpsTool
+  - GitOpsTool
+  - TaskTool
+
+Filling the gap: git_ops and task originally did NOT have a _safe_path
+guard (relied on Git's own safety or just trusting the input). Now
+both inherit WorkspaceTool so they can use the same guard.
+
+The mixin does NOT inherit from Tool — that's the job of the subclass.
+Just include it in the inheritance list:
+    class CodeSearchTool(WorkspaceTool, Tool):
+        ...
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+class WorkspaceTool:
+    """Mix-in providing workspace path + path-traversal-safe resolver.
+
+    Subclasses MUST call ``super().__init__(workspace)`` or assign
+    ``self.workspace`` themselves; the mixin only stores/guards it.
+    """
+
+    workspace: Path
+
+    def __init__(self, workspace: str | Path) -> None:
+        self.workspace = Path(workspace).resolve()
+
+    def _safe_path(self, rel_path: str = "") -> Path:
+        """Resolve a workspace-relative path, blocking '../' escapes.
+
+        Returns the workspace root when rel_path is empty.
+        Raises ValueError if the resolved path is outside the workspace.
+        """
+        if not rel_path:
+            return self.workspace
+        rel_path = rel_path.lstrip("/")
+        target = (self.workspace / rel_path).resolve()
+        if not str(target).startswith(str(self.workspace)):
+            raise ValueError(f"Path traversal not allowed: {rel_path}")
+        return target

QuantNodes/agent/tools/alpha_backtest.py

@@ -0,0 +1,328 @@
+# coding=utf-8
+"""
+alpha_backtest.py - Alpha 公式 Trading 回测工具
+
+Alpha-GPT 工作流的【Evaluator】可选工具。
+对 top-K 候选公式做完整 Trading 回测，返回年化收益 / Sharpe / 最大回撤。
+
+复用：
+- 现有 BacktestTool 思路（CodeSandbox → Strategy → Broker）
+- 但更轻量：直接用 top-K 等权组合，不需要完整 Pipeline
+
+Usage::
+
+    tool = AlphaBacktestTool()
+    result = await tool.execute(
+        formulas=["rank(-ts_mean(returns, 20))"],
+        data=df,
+        top_k=10,
+        initial_cash=1_000_000,
+    )
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence
+
+import numpy as np
+
+from .base import Tool
+
+logger = logging.getLogger(__name__)
+
+
+class AlphaBacktestTool(Tool):
+    """Alpha 公式 Trading 回测工具（top-K 等权组合）"""
+
+    def __init__(self) -> None:
+        pass
+
+    @property
+    def name(self) -> str:
+        return "alpha_backtest"
+
+    @property
+    def description(self) -> str:
+        return (
+            "对 alpha 公式做 Trading 回测。"
+            "对每公式计算 top-K 等权组合的：年化收益 / Sharpe / 最大回撤 / 胜率。"
+            "输入 formulas 列表 + 数据 + top_k。"
+        )
+
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "formulas": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "待回测的公式列表（建议 ≤ 20）",
+                },
+                "data_path": {
+                    "type": "string",
+                    "description": "数据路径（parquet/csv）",
+                },
+                "top_k": {
+                    "type": "integer",
+                    "default": 10,
+                    "description": "每期持有 top-K 股票（默认 10）",
+                },
+                "bottom_k": {
+                    "type": "integer",
+                    "default": 0,
+                    "description": "做空 bottom-K（0=不做空，默认 0）",
+                },
+                "rebalance_freq": {
+                    "type": "integer",
+                    "default": 5,
+                    "description": "调仓频率（交易日，默认 5 = 周度）",
+                },
+                "initial_cash": {
+                    "type": "number",
+                    "default": 1_000_000.0,
+                    "description": "初始资金（默认 100 万）",
+                },
+                "commission": {
+                    "type": "number",
+                    "default": 0.001,
+                    "description": "手续费率（默认 0.001）",
+                },
+                "date_column": {
+                    "type": "string",
+                    "default": "date",
+                    "description": "日期列名",
+                },
+                "code_column": {
+                    "type": "string",
+                    "default": "code",
+                    "description": "股票代码列名",
+                },
+            },
+            "required": ["formulas"],
+        }
+
+    @property
+    def read_only(self) -> bool:
+        return True
+
+    async def execute(
+        self,
+        formulas: Sequence[str],
+        data_path: Optional[str] = None,
+        top_k: int = 10,
+        bottom_k: int = 0,
+        rebalance_freq: int = 5,
+        initial_cash: float = 1_000_000.0,
+        commission: float = 0.001,
+        date_column: str = "date",
+        code_column: str = "code",
+        data: Any = None,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        try:
+            import polars as pl
+            from QuantNodes.research.quant_alpha.adapters import (
+                PolarsAlphaCalculator,
+            )
+            from QuantNodes.agent.tools.alpha_evaluate import AlphaEvaluateTool
+
+            df = AlphaEvaluateTool._resolve_data(
+                data, data_path, date_column, code_column
+            )
+            if df is None:
+                return {"backtests": [], "summary": {"error": "no data"}}
+
+            forward_returns_dict = AlphaEvaluateTool._build_forward_returns(
+                df, [1], date_column, code_column,
+            )
+
+            calc = PolarsAlphaCalculator(
+                data=df,
+                forward_returns=forward_returns_dict,
+                date_column=date_column,
+                code_column=code_column,
+            )
+
+            backtests: List[Dict[str, Any]] = []
+            for formula in formulas:
+                backtests.append(
+                    self._backtest_one(
+                        calc,
+                        formula,
+                        top_k=top_k,
+                        bottom_k=bottom_k,
+                        rebalance_freq=rebalance_freq,
+                        initial_cash=initial_cash,
+                        commission=commission,
+                        date_column=date_column,
+                        code_column=code_column,
+                    )
+                )
+
+            successful = [b for b in backtests if b["status"] == "success"]
+            sharpes = [
+                b["backtest"]["sharpe"] for b in successful if b["backtest"]["sharpe"] is not None
+            ]
+            return {
+                "backtests": backtests,
+                "summary": {
+                    "total": len(backtests),
+                    "success": len(successful),
+                    "failed": len(backtests) - len(successful),
+                    "avg_sharpe": float(np.mean(sharpes)) if sharpes else 0.0,
+                    "best_sharpe": float(np.max(sharpes)) if sharpes else 0.0,
+                },
+            }
+        except Exception as exc:
+            logger.exception("alpha_backtest failed")
+            return {"backtests": [], "summary": {"error": str(exc)}}
+
+    def _backtest_one(
+        self,
+        calc: Any,
+        formula: str,
+        top_k: int,
+        bottom_k: int,
+        rebalance_freq: int,
+        initial_cash: float,
+        commission: float,
+        date_column: str,
+        code_column: str,
+    ) -> Dict[str, Any]:
+        try:
+            import polars as pl
+
+            from QuantNodes.agent.tools.alpha_evaluate import AlphaEvaluateTool
+
+            expr = AlphaEvaluateTool._parse_simple_formula(formula)
+            factor_series = calc._evaluate_factor(expr)
+            if factor_series is None:
+                return {
+                    "formula": formula,
+                    "status": "failed",
+                    "backtest": {},
+                    "error_msg": "factor evaluation returned None",
+                }
+
+            dates = sorted(calc.data[date_column].unique().to_list())
+            if len(dates) < 2:
+                return {
+                    "formula": formula,
+                    "status": "failed",
+                    "backtest": {},
+                    "error_msg": "not enough dates",
+                }
+
+            work = calc.data.select([date_column, code_column, "close"]).with_columns(
+                factor_series.alias("_factor")
+            )
+            fwd = calc.forward_returns[1]
+            work = work.with_columns(fwd.alias("_fwd"))
+
+            holdings_returns: List[float] = []
+            cash = initial_cash
+            equity_curve: List[float] = [initial_cash]
+            entry_days: List[int] = list(range(0, len(dates) - 1, rebalance_freq))
+            prev_longs: List[str] = []
+            prev_shorts: List[str] = []
+
+            for entry_idx in entry_days:
+                if entry_idx + 1 >= len(dates):
+                    break
+                entry_date = dates[entry_idx]
+                exit_date = dates[entry_idx + 1]
+
+                day_slice = work.filter(pl.col(date_column) == entry_date)
+                ranked = day_slice.filter(pl.col("_factor").is_not_null()).sort(
+                    "_factor", descending=True
+                )
+                longs = ranked.head(top_k)[code_column].to_list()
+                shorts = (
+                    ranked.tail(bottom_k)[code_column].to_list() if bottom_k > 0 else []
+                )
+
+                if not longs:
+                    continue
+
+                next_close = work.filter(
+                    (pl.col(date_column) == exit_date)
+                    & pl.col(code_column).is_in(longs + shorts)
+                )
+
+                if bottom_k > 0 and shorts:
+                    long_ret = (
+                        next_close.filter(pl.col(code_column).is_in(longs))["_fwd"]
+                        .drop_nulls()
+                        .mean()
+                    )
+                    short_ret = (
+                        -next_close.filter(pl.col(code_column).is_in(shorts))["_fwd"]
+                        .drop_nulls()
+                        .mean()
+                    )
+                    period_ret = float((long_ret or 0) + (short_ret or 0)) / 2.0
+                else:
+                    long_ret = next_close.filter(pl.col(code_column).is_in(longs))[
+                        "_fwd"
+                    ].drop_nulls().mean()
+                    period_ret = float(long_ret or 0)
+
+                changed = len(set(longs) ^ set(prev_longs)) + len(set(shorts) ^ set(prev_shorts))
+                total = max(1, len(longs) + len(shorts))
+                turnover = changed / total
+                cost = turnover * commission
+                net_ret = period_ret - cost
+                cash *= 1.0 + net_ret
+                holdings_returns.append(net_ret)
+                equity_curve.append(cash)
+                prev_longs, prev_shorts = longs, shorts
+
+            if not holdings_returns:
+                return {
+                    "formula": formula,
+                    "status": "failed",
+                    "backtest": {},
+                    "error_msg": "no valid periods",
+                }
+
+            rets = np.array(holdings_returns)
+            ann_factor = 252.0 / rebalance_freq
+            annual_return = float(np.mean(rets) * ann_factor)
+            sharpe = (
+                float(np.mean(rets) / (np.std(rets) + 1e-12) * np.sqrt(ann_factor))
+                if np.std(rets) > 1e-12
+                else 0.0
+            )
+            equity = np.array(equity_curve)
+            running_max = np.maximum.accumulate(equity)
+            drawdown = (equity - running_max) / running_max
+            max_dd = float(np.min(drawdown)) if drawdown.size else 0.0
+            wins = int(np.sum(rets > 0))
+            win_rate = wins / len(rets) if len(rets) else 0.0
+
+            return {
+                "formula": formula,
+                "status": "success",
+                "backtest": {
+                    "annual_return": annual_return,
+                    "sharpe": sharpe,
+                    "max_drawdown": max_dd,
+                    "win_rate": float(win_rate),
+                    "n_periods": len(rets),
+                    "equity_curve": equity_curve[:: max(1, len(equity_curve) // 50)],
+                },
+                "error_msg": None,
+            }
+        except Exception as exc:
+            return {
+                "formula": formula,
+                "status": "failed",
+                "backtest": {},
+                "error_msg": str(exc),
+            }
+
+
+__all__ = ["AlphaBacktestTool"]