quantnodes 3.0.0__py3-none-any.whl

QuantNodes/agent/tools/operator_lookup.py

@@ -0,0 +1,218 @@
+# coding=utf-8
+"""
+operator_lookup.py - 算子查询工具
+
+让 agent 动态发现 OperatorVocab 中的 162 个可用算子，
+获取算子签名、参数、示例，以及校验公式有效性。
+
+用法 (agent 调用)::
+
+    # 列出所有算子
+    operator_lookup(action="list_operators")
+    operator_lookup(action="list_operators", category="time")
+
+    # 获取算子详情
+    operator_lookup(action="get_operator_info", name="ts_mean")
+
+    # 校验公式
+    operator_lookup(action="validate_formula", formula="rank(ts_mean(close, 20))")
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Optional, Sequence
+
+from .base import Tool
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["OperatorLookupTool"]
+
+
+class OperatorLookupTool(Tool):
+    """算子查询工具 — 让 agent 发现可用算子
+
+    3 个 action:
+    - list_operators: 列出所有算子（可按类别过滤）
+    - get_operator_info: 获取单个算子详情（签名、参数、示例）
+    - validate_formula: 校验公式是否有效
+    """
+
+    def __init__(self) -> None:
+        pass
+
+    @property
+    def name(self) -> str:
+        return "operator_lookup"
+
+    @property
+    def description(self) -> str:
+        return (
+            "查询 QuantNodes OperatorVocab 中的可用算子（162 个）。"
+            "用于发现算子、获取用法说明、校验公式有效性。"
+            "生成 alpha 因子公式前，应先调用此工具获取可用算子列表。"
+        )
+
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "action": {
+                    "type": "string",
+                    "enum": [
+                        "list_operators",
+                        "get_operator_info",
+                        "validate_formula",
+                    ],
+                    "description": (
+                        "list_operators: 列出所有算子（可按 category 过滤）。"
+                        "get_operator_info: 获取单个算子详情。"
+                        "validate_formula: 校验公式是否有效。"
+                    ),
+                },
+                "category": {
+                    "type": "string",
+                    "enum": ["time", "point", "section", "multi_section"],
+                    "description": (
+                        "算子类别过滤（list_operators 时使用）。"
+                        "time=时间序列, point=逐点, section=截面, multi_section=多截面"
+                    ),
+                },
+                "name": {
+                    "type": "string",
+                    "description": "算子名（get_operator_info 时使用）",
+                },
+                "formula": {
+                    "type": "string",
+                    "description": "公式字符串（validate_formula 时使用）",
+                },
+            },
+            "required": ["action"],
+        }
+
+    @property
+    def read_only(self) -> bool:
+        return True
+
+    async def execute(
+        self,
+        action: str,
+        category: Optional[str] = None,
+        name: Optional[str] = None,
+        formula: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        """执行算子查询"""
+        try:
+            if action == "list_operators":
+                return self._list_operators(category)
+            elif action == "get_operator_info":
+                if not name:
+                    return {"error": "name 参数必填"}
+                return self._get_operator_info(name)
+            elif action == "validate_formula":
+                if not formula:
+                    return {"error": "formula 参数必填"}
+                return self._validate_formula(formula)
+            else:
+                return {"error": f"未知 action: {action}"}
+        except Exception as e:
+            logger.error("OperatorLookup failed: %s", e)
+            return {"error": str(e)}
+
+    def _list_operators(self, category: Optional[str] = None) -> Dict[str, Any]:
+        """列出所有算子（可按类别过滤）"""
+        from QuantNodes.research.quant_alpha.operator_vocab import (
+            list_vocab_operators,
+            get_vocab_metadata,
+        )
+
+        ops = list_vocab_operators(category=category)
+        result = []
+        for op_name in ops:
+            meta = get_vocab_metadata(op_name)
+            if meta:
+                result.append({
+                    "name": op_name,
+                    "category": meta.category,
+                    "signature": meta.signature,
+                    "doc": meta.doc,
+                })
+            else:
+                result.append({"name": op_name})
+
+        return {
+            "operators": result,
+            "total": len(result),
+            "category_filter": category,
+        }
+
+    def _get_operator_info(self, name: str) -> Dict[str, Any]:
+        """获取单个算子详情"""
+        from QuantNodes.research.quant_alpha.operator_vocab import get_vocab_metadata
+
+        meta = get_vocab_metadata(name)
+        if meta is None:
+            return {"error": f"算子 '{name}' 不存在"}
+
+        return {
+            "name": meta.name,
+            "category": meta.category,
+            "category_tags": meta.category_tags,
+            "signature": meta.signature,
+            "parameters": meta.parameters,
+            "doc": meta.doc,
+            "default_window": meta.default_window,
+            "examples": meta.examples,
+            "difficulty": meta.difficulty,
+            "output_dtype": meta.output_dtype,
+            "requires_group_by": meta.requires_group_by,
+            "composes_with": meta.composes_with,
+        }
+
+    def _validate_formula(self, formula: str) -> Dict[str, Any]:
+        """校验公式是否有效"""
+        from QuantNodes.research.quant_alpha.operator_vocab import OperatorVocab
+        import polars as pl
+
+        # 构造最小测试数据
+        test_data = pl.DataFrame({
+            "date": ["2020-01-01", "2020-01-02", "2020-01-03"] * 3,
+            "code": ["A"] * 3 + ["B"] * 3 + ["C"] * 3,
+            "open": [10.0] * 9,
+            "high": [10.5] * 9,
+            "low": [9.5] * 9,
+            "close": [10.0, 10.1, 10.2, 11.0, 11.1, 11.2, 12.0, 12.1, 12.2],
+            "vol": [1000.0] * 9,
+            "amount": [10000.0] * 9,
+        })
+
+        try:
+            vocab = OperatorVocab.default()
+            result = vocab.evaluate(
+                formula=formula,
+                data=test_data,
+                date_column="date",
+                code_column="code",
+            )
+            if result is not None and len(result) == len(test_data):
+                return {
+                    "formula": formula,
+                    "valid": True,
+                    "error": None,
+                    "result_length": len(result),
+                }
+            else:
+                return {
+                    "formula": formula,
+                    "valid": False,
+                    "error": "评估结果为空或长度不匹配",
+                }
+        except Exception as e:
+            return {
+                "formula": formula,
+                "valid": False,
+                "error": str(e),
+            }

QuantNodes/agent/tools/output_truncation.py

@@ -0,0 +1,77 @@
+# coding=utf-8
+"""
+输出截断模块
+
+提供输出长度控制功能。
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class TruncatedOutput:
+    """截断后的输出"""
+    content: str
+    truncated: bool
+    total_lines: int
+    total_bytes: int
+    kept_lines: int
+    kept_bytes: int
+
+
+def truncate_output(
+    output: str,
+    max_lines: int = 10000,
+    max_bytes: int = 1024 * 1024,
+) -> TruncatedOutput:
+    """截断输出
+
+    策略：
+    1. 保留前 max_lines/2 行
+    2. 保留后 max_lines/2 行
+    3. 中间用省略标记替代
+    4. 同时检查字节限制
+
+    Args:
+        output: 原始输出
+        max_lines: 最大行数
+        max_bytes: 最大字节数
+
+    Returns:
+        TruncatedOutput 对象
+    """
+    lines = output.split("\n")
+    total_lines = len(lines)
+    total_bytes = len(output.encode("utf-8"))
+
+    truncated = False
+    kept_lines = total_lines
+    kept_bytes = total_bytes
+
+    if total_lines > max_lines or total_bytes > max_bytes:
+        truncated = True
+        half = max_lines // 2
+        kept_lines = min(total_lines, max_lines)
+
+        if total_lines > max_lines:
+            kept_lines = max_lines
+            head = lines[:half]
+            tail = lines[-(max_lines - half):]
+            lines = head + ["... (truncated) ..."] + tail
+
+        result = "\n".join(lines)
+
+        if len(result.encode("utf-8")) > max_bytes:
+            result = result[:max_bytes] + "\n... (truncated by bytes) ..."
+            kept_bytes = max_bytes
+    else:
+        result = output
+
+    return TruncatedOutput(
+        content=result,
+        truncated=truncated,
+        total_lines=total_lines,
+        total_bytes=total_bytes,
+        kept_lines=kept_lines,
+        kept_bytes=kept_bytes,
+    )

QuantNodes/agent/tools/path_check.py

@@ -0,0 +1,43 @@
+# coding=utf-8
+"""
+路径检查模块
+
+提供项目边界检查功能。
+"""
+
+from pathlib import Path
+
+
+def is_within_project(filepath: str, project_root: str) -> bool:
+    """检查文件路径是否在项目目录内
+
+    Args:
+        filepath: 文件路径
+        project_root: 项目根目录
+
+    Returns:
+        True if within project, False otherwise
+    """
+    try:
+        file_path = Path(filepath).resolve()
+        project_path = Path(project_root).resolve()
+        return file_path.is_relative_to(project_path)
+    except (ValueError, OSError):
+        return False
+
+
+def assert_within_project(filepath: str, project_root: str) -> None:
+    """断言文件路径在项目目录内
+
+    Raises:
+        ExternalDirectoryError: 如果文件在项目外
+    """
+    if not is_within_project(filepath, project_root):
+        raise ExternalDirectoryError(
+            f"Access to external directory denied: {filepath}"
+        )
+
+
+class ExternalDirectoryError(Exception):
+    """外部目录访问错误"""
+    pass

QuantNodes/agent/tools/pipeline.py

@@ -0,0 +1,62 @@
+# coding=utf-8
+"""
+Pipeline工具 - Agent 工具版本
+
+验证 QuantNodes Pipeline 代码的正确性。
+
+实现: 委托给 QuantNodes.methods.pipeline.validate_pipeline，
+保持 Tool 接口 (async, dict 返回) 以兼容 Agent 工具注册。
+"""
+
+from typing import Any, Dict
+
+from QuantNodes.agent.tools.base import Tool
+
+
+class PipelineTool(Tool):
+    """Pipeline验证工具
+
+    验证 QuantNodes Pipeline 代码的正确性，包括：
+    - 语法检查
+    - 安全检查（CodeSandbox）
+    - 节点提取
+    """
+
+    def __init__(self):
+        pass
+
+    @property
+    def name(self) -> str:
+        return "pipeline"
+
+    @property
+    def description(self) -> str:
+        return "验证 QuantNodes Pipeline 代码的正确性，检查语法和结构"
+
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "description": "QuantNodes Pipeline Python代码"
+                }
+            },
+            "required": ["code"]
+        }
+
+    @property
+    def read_only(self) -> bool:
+        return True
+
+    async def execute(self, code: str, **kwargs) -> Dict[str, Any]:
+        from QuantNodes.methods.pipeline import validate_pipeline
+        result = validate_pipeline(code=code)
+        return {
+            "is_valid": result.is_valid,
+            "errors": result.errors,
+            "warnings": result.warnings,
+            "nodes": result.nodes,
+            "security_status": result.security_status,
+        }

QuantNodes/agent/tools/registry.py

@@ -0,0 +1,150 @@
+# coding=utf-8
+"""
+工具注册表
+
+管理工具的注册、查询与执行
+"""
+
+from typing import Any, Dict, List
+import asyncio
+
+from .base import Tool, ToolExecutionResult
+
+
+class ToolRegistry:
+    """工具注册表与执行入口"""
+
+    def __init__(self):
+        self._tools: Dict[str, Tool] = {}
+        self._cached_schemas: List[Dict[str, Any]] | None = None
+
+    def register(self, tool: Tool) -> None:
+        """注册工具"""
+        self._tools[tool.name] = tool
+        self._cached_schemas = None
+
+    def unregister(self, name: str) -> None:
+        """注销工具"""
+        if name in self._tools:
+            del self._tools[name]
+            self._cached_schemas = None
+
+    def get(self, name: str) -> Tool | None:
+        """获取工具"""
+        return self._tools.get(name)
+
+    def list_tools(self) -> List[Tool]:
+        """列出所有已注册工具"""
+        return list(self._tools.values())
+
+    def get_tool_schemas(self) -> List[Dict[str, Any]]:
+        """Return OpenAI function-calling schemas for all tools (cached).
+
+        v3.0.0 contract: if a tool cannot produce a schema (e.g. the
+        local ``Tool`` ABC when ``nanobot-ai`` is not installed), we
+        fall back to a minimal ``{"type": "function", "function": {"name": ..., "description": ..., "parameters": {"type": "object", "properties": {}}}}``
+        shape so the registry's schema list is always usable.
+        """
+        if self._cached_schemas is None:
+            schemas: List[Dict[str, Any]] = []
+            for tool in self._tools.values():
+                try:
+                    schemas.append(tool.to_openai_schema())
+                except Exception:
+                    # Fallback: minimal schema from raw fields
+                    schemas.append({
+                        "type": "function",
+                        "function": {
+                            "name": tool.name,
+                            "description": tool.description,
+                            "parameters": tool.parameters,
+                        },
+                    })
+            self._cached_schemas = schemas
+        return self._cached_schemas
+
+    async def execute_tool(self, name: str, **kwargs: Any) -> ToolExecutionResult:
+        """Execute a single tool by name.
+
+        v3.0.0 contract: we attempt to call ``tool.cast_params(kwargs)`` and
+        ``tool.validate_params(params)`` for forward-compat with the
+        upstream nanobot Tool API. If those methods don't exist on the
+        tool (e.g. local ``Tool`` ABC when ``nanobot-ai`` is not
+        installed, or third-party tools that don't implement them), we
+        gracefully fall back to passing the raw ``kwargs`` to
+        ``tool.execute()``.
+        """
+        tool = self._tools.get(name)
+        if not tool:
+            return ToolExecutionResult(
+                tool_name=name,
+                success=False,
+                content=None,
+                error=f"Tool '{name}' not found"
+            )
+
+        try:
+            # Optional pre-processing hooks. Missing methods are OK —
+            # the bare v3.0.0 ``Tool`` ABC doesn't define them.
+            params: Dict[str, Any] = kwargs
+            cast = getattr(tool, "cast_params", None)
+            if callable(cast):
+                params = cast(kwargs)
+            validate = getattr(tool, "validate_params", None)
+            if callable(validate):
+                errors = validate(params)
+                if errors:
+                    return ToolExecutionResult(
+                        tool_name=name,
+                        success=False,
+                        content=None,
+                        error=f"Parameter validation failed: {', '.join(errors)}"
+                    )
+
+            result = await tool.execute(**params)
+            return ToolExecutionResult(
+                tool_name=name,
+                success=True,
+                content=result
+            )
+        except Exception as e:
+            return ToolExecutionResult(
+                tool_name=name,
+                success=False,
+                content=None,
+                error=str(e)
+            )
+
+    async def execute_tools_parallel(
+        self,
+        tool_calls: List[Dict[str, Any]],
+    ) -> List[ToolExecutionResult]:
+        """并发执行多个工具（只读工具并发，有副作用工具串行）"""
+        results: List[ToolExecutionResult] = []
+
+        # 分组：只读工具并发执行，其他串行
+        read_only_calls: List[Dict[str, Any]] = []
+        write_calls: List[Dict[str, Any]] = []
+
+        for call in tool_calls:
+            tool = self._tools.get(call.get("name", ""))
+            if tool and tool.read_only:
+                read_only_calls.append(call)
+            else:
+                write_calls.append(call)
+
+        # 并发执行只读工具
+        if read_only_calls:
+            tasks = [
+                self.execute_tool(call["name"], **call.get("arguments", {}))
+                for call in read_only_calls
+            ]
+            results.extend(await asyncio.gather(*tasks))
+
+        # 串行执行有副作用工具
+        for call in write_calls:
+            name = call.get("name", "")
+            result = await self.execute_tool(name, **call.get("arguments", {}))
+            results.append(result)
+
+        return results

QuantNodes/agent/tools/sandbox.py

@@ -0,0 +1,62 @@
+# coding=utf-8
+"""
+沙箱工具 - Agent 工具版本
+
+封装 QuantNodes AI 模块的 CodeSandbox，用于代码安全验证。
+
+实现: 委托给 self._sandbox.validate() (CodeSandbox 实例)。
+原本重复的 methods/sandbox.validate_code 现已删除，
+此模块通过 _sandbox 属性复用 CodeSandbox，避免逻辑重复。
+"""
+
+from typing import Any, Dict
+
+from QuantNodes.ai.sandbox import CodeSandbox as QNCodeSandbox
+from QuantNodes.agent.tools.base import Tool
+
+
+class SandboxTool(Tool):
+    """代码安全沙箱工具
+
+    提供代码安全校验，防止执行危险操作。
+    """
+
+    def __init__(self, allow_warnings: bool = False, max_code_length: int = 10000):
+        self._sandbox = QNCodeSandbox(
+            allow_warnings=allow_warnings,
+            max_code_length=max_code_length
+        )
+
+    @property
+    def name(self) -> str:
+        return "sandbox"
+
+    @property
+    def description(self) -> str:
+        return "验证Python代码的安全性，检查危险操作。不执行代码，只返回验证结果"
+
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "description": "待验证的Python代码"
+                }
+            },
+            "required": ["code"]
+        }
+
+    @property
+    def read_only(self) -> bool:
+        return True
+
+    async def execute(self, code: str, **kwargs) -> Dict[str, Any]:
+        result = self._sandbox.validate(code)
+        return {
+            "is_safe": result.is_safe,
+            "errors": result.errors,
+            "warnings": result.warnings,
+            "warnings_only": result.warnings_only,
+        }

QuantNodes/agent/tools/shell_safety.py

@@ -0,0 +1,63 @@
+# coding=utf-8
+"""
+Shell 安全模块
+
+提供命令超时、执行控制等功能。
+"""
+
+import asyncio
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class ShellConfig:
+    """Shell 执行配置"""
+    timeout_seconds: int = 120
+    max_output_bytes: int = 1024 * 1024
+    max_output_lines: int = 10000
+    project_root: Optional[str] = None
+
+
+async def execute_with_timeout(
+    command: str,
+    cwd: Optional[str] = None,
+    timeout: int = 120,
+    env: Optional[dict] = None,
+) -> tuple[int, str, str]:
+    """执行 shell 命令（带超时）
+
+    Args:
+        command: 要执行的命令
+        cwd: 工作目录
+        timeout: 超时秒数
+        env: 环境变量
+
+    Returns:
+        (exit_code, stdout, stderr)
+    """
+    proc = await asyncio.create_subprocess_shell(
+        command,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+        cwd=cwd,
+        env=env,
+    )
+
+    try:
+        stdout, stderr = await asyncio.wait_for(
+            proc.communicate(),
+            timeout=timeout,
+        )
+        return proc.returncode or 0, stdout.decode(), stderr.decode()
+    except asyncio.TimeoutError:
+        proc.kill()
+        await proc.wait()
+        raise ShellTimeoutError(
+            f"Command timed out after {timeout}s: {command[:100]}"
+        )
+
+
+class ShellTimeoutError(Exception):
+    """Shell 命令超时"""
+    pass