quantnodes 3.0.0__py3-none-any.whl

QuantNodes/agent/tools/strategy.py

@@ -0,0 +1,106 @@
+# coding=utf-8
+"""
+策略生成工具
+
+封装 QuantNodes AI 模块的 StrategyGenerator。
+"""
+
+from typing import Any, Dict
+import re
+
+from QuantNodes.agent.tools.base import Tool
+
+
+class StrategyTool(Tool):
+    """策略生成工具
+
+    将自然语言描述转换为 QuantNodes Pipeline 代码。
+
+    需要配置 LLM 客户端才能使用。如果未配置，将返回提示信息。
+    """
+
+    CODE_BLOCK_PATTERN = re.compile(r'```(?:python)?\s*(.*?)```', re.DOTALL)
+
+    def __init__(self, llm_client=None):
+        if llm_client is None:
+            from QuantNodes.ai.llm.gateway import get_llm_gateway
+            llm_client = get_llm_gateway()
+        self._llm_client = llm_client
+
+    @property
+    def name(self) -> str:
+        return "strategy"
+
+    @property
+    def description(self) -> str:
+        return "根据自然语言描述生成 QuantNodes Pipeline 代码"
+
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "description": {
+                    "type": "string",
+                    "description": "策略的自然语言描述，如'生成一个动量因子策略'"
+                },
+                "validate": {
+                    "type": "boolean",
+                    "description": "是否验证生成的代码",
+                    "default": True
+                }
+            },
+            "required": ["description"]
+        }
+
+    @property
+    def read_only(self) -> bool:
+        return False
+
+    async def execute(self, description: str, validate: bool = True, **kwargs) -> Dict[str, Any]:
+        result = {
+            "code": "",
+            "is_valid": False,
+            "errors": [],
+            "warnings": [],
+            "description": description
+        }
+
+        if self._llm_client is None:
+            result["message"] = (
+                "Strategy generation requires LLM client configuration. "
+                "Please provide an LLM client when initializing StrategyTool."
+            )
+            result["status"] = "needs_configuration"
+            return result
+
+        try:
+            from QuantNodes.ai.strategy_gen import StrategyGenerator
+            from QuantNodes.ai.sandbox import CodeSandbox
+
+            generator = StrategyGenerator(
+                llm_client=self._llm_client,
+                code_sandbox=CodeSandbox()
+            )
+
+            gen_result = generator.generate(description, validate=validate)
+
+            result["code"] = gen_result.code
+            result["is_valid"] = gen_result.is_valid
+
+            if gen_result.error_message:
+                result["errors"].append(gen_result.error_message)
+
+            if gen_result.warnings:
+                result["warnings"] = gen_result.warnings
+
+            result["status"] = "success"
+
+        except ImportError as e:
+            result["status"] = "error"
+            result["errors"] = ["AI module not available: %s" % str(e)]
+        except Exception as e:
+            result["status"] = "error"
+            result["errors"] = [str(e)]
+
+        return result

QuantNodes/agent/tools/task.py

@@ -0,0 +1,171 @@
+# coding=utf-8
+"""
+Task 工具
+
+提供简单的任务管理功能，支持创建、更新、列表任务。
+任务数据存储在 workspace/.quant_agent/tasks.json。
+"""
+
+import json
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .base import Tool
+from ._workspace import WorkspaceTool
+from QuantNodes.core.path_utils import ensure_parent
+
+
+class TaskTool(WorkspaceTool, Tool):
+    """任务管理工具
+
+    创建、更新、列表任务。数据持久化到 JSON 文件。
+    """
+
+    MAX_TASKS = 100
+
+    def __init__(self, workspace: str | Path):
+        super().__init__(workspace)
+        self._tasks_file = self.workspace / "tasks.json"
+
+    @property
+    def name(self) -> str:
+        return "task"
+
+    @property
+    def description(self) -> str:
+        return (
+            "任务管理工具：创建、更新、列表任务。"
+            "支持按状态筛选，任务持久化到 JSON 文件。"
+        )
+
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "action": {
+                    "type": "string",
+                    "enum": ["create_task", "update_task", "list_tasks"],
+                    "description": "操作类型",
+                },
+                "title": {
+                    "type": "string",
+                    "description": "任务标题（create_task 时必需）",
+                },
+                "description": {
+                    "type": "string",
+                    "description": "任务描述",
+                },
+                "priority": {
+                    "type": "string",
+                    "enum": ["low", "medium", "high"],
+                    "description": "任务优先级（默认 medium）",
+                    "default": "medium",
+                },
+                "task_id": {
+                    "type": "string",
+                    "description": "任务 ID（update_task 时必需）",
+                },
+                "status": {
+                    "type": "string",
+                    "enum": ["pending", "in_progress", "completed", "cancelled"],
+                    "description": "任务状态（update_task 时使用）",
+                },
+            },
+            "required": ["action"],
+        }
+
+    @property
+    def read_only(self) -> bool:
+        return False
+
+    def _load_tasks(self) -> List[Dict[str, Any]]:
+        """从 JSON 文件加载任务"""
+        if not self._tasks_file.exists():
+            return []
+        try:
+            return json.loads(self._tasks_file.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, Exception):
+            return []
+
+    def _save_tasks(self, tasks: List[Dict[str, Any]]) -> None:
+        """保存任务到 JSON 文件"""
+        ensure_parent(self._tasks_file)
+        self._tasks_file.write_text(
+            json.dumps(tasks, ensure_ascii=False, indent=2),
+            encoding="utf-8",
+        )
+
+    async def _dispatch(self, action: str, registry: Dict[str, Any], **kwargs: Any) -> Any:
+        """Override: return error dict on unknown action (matches legacy)."""
+        fn = registry.get(action)
+        if not fn:
+            return {"error": f"Unknown action: {action}"}
+        return await fn(**kwargs)
+
+    async def execute(self, action: str, **kwargs: Any) -> Any:
+        return await self._dispatch(action, {
+            "create_task": self._create_task,
+            "update_task": self._update_task,
+            "list_tasks": self._list_tasks,
+        }, **kwargs)
+
+    async def _create_task(
+        self,
+        title: str = "",
+        description: str = "",
+        priority: str = "medium",
+        **kw,
+    ) -> Dict[str, Any]:
+        if not title:
+            return {"error": "title is required"}
+
+        tasks = self._load_tasks()
+        if len(tasks) >= self.MAX_TASKS:
+            return {"error": f"Task limit reached ({self.MAX_TASKS})"}
+
+        now = datetime.now(timezone.utc).isoformat()
+        task = {
+            "id": uuid.uuid4().hex[:8],
+            "title": title,
+            "description": description,
+            "status": "pending",
+            "priority": priority,
+            "created_at": now,
+            "updated_at": now,
+        }
+        tasks.append(task)
+        self._save_tasks(tasks)
+
+        return {"status": "ok", "task": task}
+
+    async def _update_task(
+        self,
+        task_id: str = "",
+        status: Optional[str] = None,
+        description: Optional[str] = None,
+        **kw,
+    ) -> Dict[str, Any]:
+        if not task_id:
+            return {"error": "task_id is required"}
+
+        tasks = self._load_tasks()
+        for task in tasks:
+            if task["id"] == task_id:
+                if status:
+                    task["status"] = status
+                if description is not None:
+                    task["description"] = description
+                task["updated_at"] = datetime.now(timezone.utc).isoformat()
+                self._save_tasks(tasks)
+                return {"status": "ok", "task": task}
+
+        return {"error": f"Task not found: {task_id}"}
+
+    async def _list_tasks(self, status: Optional[str] = None, **kw) -> Dict[str, Any]:
+        tasks = self._load_tasks()
+        if status:
+            tasks = [t for t in tasks if t["status"] == status]
+        return {"tasks": tasks, "total": len(tasks)}

QuantNodes/agent/tools/web_fetch.py

@@ -0,0 +1,142 @@
+# coding=utf-8
+"""
+Web Fetch 工具
+
+抓取指定 URL 的网页内容，支持 text/html/markdown 格式。
+"""
+
+import re
+from typing import Any, Dict
+from urllib.parse import urlparse
+
+import httpx
+from bs4 import BeautifulSoup
+
+from .base import Tool
+
+
+class WebFetchTool(Tool):
+    """网页抓取工具
+
+    抓取指定 URL 的内容，支持纯文本、HTML、Markdown 格式。
+    """
+
+    MAX_CONTENT = 50 * 1024  # 50KB
+    TIMEOUT = 10.0
+    USER_AGENT = "Mozilla/5.0 (compatible; QuantNodes/1.0)"
+
+    def __init__(self) -> None:
+        # H9 (2026-06-20): per-instance AsyncClient for connection pooling.
+        # Previously each execute() opened a fresh client + paid a fresh
+        # TCP+TLS handshake. With many URLs in one agent run, that's
+        # multi-second savings.
+        self._client = httpx.AsyncClient(timeout=self.TIMEOUT, follow_redirects=True)
+
+    async def aclose(self) -> None:
+        """Close the underlying httpx client (call at end of session)."""
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    @property
+    def name(self) -> str:
+        return "web_fetch"
+
+    @property
+    def description(self) -> str:
+        return (
+            "抓取指定 URL 的网页内容。"
+            "支持 text（提取纯文本）、html（返回原始 HTML）格式。"
+            "禁止访问本地地址。"
+        )
+
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "url": {
+                    "type": "string",
+                    "description": "要抓取的 URL（必须是 http/https）",
+                },
+                "format": {
+                    "type": "string",
+                    "enum": ["text", "html"],
+                    "description": "返回格式：text 提取纯文本，html 返回原始 HTML",
+                    "default": "text",
+                },
+            },
+            "required": ["url"],
+        }
+
+    @property
+    def read_only(self) -> bool:
+        return True
+
+    def _is_safe_url(self, url: str) -> bool:
+        """检查 URL 是否安全（禁止本地地址）"""
+        try:
+            parsed = urlparse(url)
+            if parsed.scheme not in ("http", "https"):
+                return False
+            hostname = parsed.hostname or ""
+            if hostname in ("localhost", "127.0.0.1", "::1", "0.0.0.0"):
+                return False
+            if hostname.startswith("192.168.") or hostname.startswith("10."):
+                return False
+            return True
+        except Exception:
+            return False
+
+    async def execute(self, url: str = "", format: str = "text", **kwargs: Any) -> Any:
+        if not url:
+            return {"error": "url is required"}
+        if not self._is_safe_url(url):
+            return {"error": f"URL not allowed: {url}"}
+
+        try:
+            resp = await self._client.get(url, headers={"User-Agent": self.USER_AGENT})
+            resp.raise_for_status()
+        except httpx.TimeoutException:
+            return {"error": f"Request timed out ({self.TIMEOUT}s)"}
+        except httpx.HTTPStatusError as e:
+            return {"error": f"HTTP {e.response.status_code}: {e.response.reason_phrase}"}
+        except Exception as e:
+            return {"error": f"Request failed: {str(e)}"}
+
+        content_type = resp.headers.get("content-type", "")
+        html = resp.text
+
+        if format == "html":
+            text = html[:self.MAX_CONTENT]
+            return {
+                "url": url,
+                "status_code": resp.status_code,
+                "content_type": content_type,
+                "content": text,
+                "truncated": len(html) > self.MAX_CONTENT,
+            }
+
+        soup = BeautifulSoup(html, "lxml")
+
+        for tag in soup(["script", "style", "nav", "footer", "header", "aside"]):
+            tag.decompose()
+
+        text = soup.get_text(separator="\n", strip=True)
+        text = re.sub(r"\n{3,}", "\n\n", text)
+
+        if len(text) > self.MAX_CONTENT:
+            text = text[:self.MAX_CONTENT] + "\n...[truncated]"
+
+        title = ""
+        title_tag = soup.find("title")
+        if title_tag:
+            title = title_tag.get_text(strip=True)
+
+        return {
+            "url": url,
+            "status_code": resp.status_code,
+            "title": title,
+            "content": text,
+            "truncated": len(text) > self.MAX_CONTENT,
+        }

QuantNodes/agent/tools/web_search.py

@@ -0,0 +1,114 @@
+# coding=utf-8
+"""
+Web Search 工具
+
+使用 DuckDuckGo HTML 端点执行网络搜索。
+"""
+
+from typing import Any, Dict, List
+
+import httpx
+from bs4 import BeautifulSoup
+
+from .base import Tool
+
+
+class WebSearchTool(Tool):
+    """网络搜索工具
+
+    使用 DuckDuckGo HTML 端点搜索关键词，返回搜索结果。
+    """
+
+    TIMEOUT = 10.0
+    USER_AGENT = "Mozilla/5.0 (compatible; QuantNodes/1.0)"
+    SEARCH_URL = "https://html.duckduckgo.com/html/"
+
+    def __init__(self) -> None:
+        # H9 (2026-06-20): per-instance AsyncClient for connection pooling.
+        self._client = httpx.AsyncClient(timeout=self.TIMEOUT, follow_redirects=True)
+
+    async def aclose(self) -> None:
+        """Close the underlying httpx client."""
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    @property
+    def name(self) -> str:
+        return "web_search"
+
+    @property
+    def description(self) -> str:
+        return (
+            "网络搜索工具：使用 DuckDuckGo 搜索关键词。"
+            "返回标题、URL、摘要。无需 API Key。"
+        )
+
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "搜索关键词",
+                },
+                "max_results": {
+                    "type": "integer",
+                    "description": "最大返回结果数（默认 5，最大 20）",
+                    "default": 5,
+                },
+            },
+            "required": ["query"],
+        }
+
+    @property
+    def read_only(self) -> bool:
+        return True
+
+    async def execute(self, query: str = "", max_results: int = 5, **kwargs: Any) -> Any:
+        if not query:
+            return {"error": "query is required"}
+
+        max_results = min(max(max_results, 1), 20)
+
+        try:
+            resp = await self._client.get(
+                self.SEARCH_URL,
+                params={"q": query},
+                headers={"User-Agent": self.USER_AGENT},
+            )
+            resp.raise_for_status()
+        except httpx.TimeoutException:
+            return {"error": f"Search timed out ({self.TIMEOUT}s)"}
+        except Exception as e:
+            return {"error": f"Search failed: {str(e)}"}
+
+        soup = BeautifulSoup(resp.text, "lxml")
+        results: List[Dict[str, str]] = []
+
+        for result_div in soup.select(".result"):
+            if len(results) >= max_results:
+                break
+
+            title_tag = result_div.select_one(".result__title a")
+            snippet_tag = result_div.select_one(".result__snippet")
+
+            if not title_tag:
+                continue
+
+            href = title_tag.get("href", "")
+            title = title_tag.get_text(strip=True)
+            snippet = snippet_tag.get_text(strip=True) if snippet_tag else ""
+
+            results.append({
+                "title": title,
+                "url": href,
+                "snippet": snippet,
+            })
+
+        return {
+            "query": query,
+            "results": results,
+            "total": len(results),
+        }