quantnodes 3.0.0__py3-none-any.whl

QuantNodes/agent/tools/factor.py

@@ -0,0 +1,231 @@
+# coding=utf-8
+"""
+因子分析工具
+
+提供 IC 分析、相关性分析等功能。
+"""
+
+from typing import Any, Dict
+
+from QuantNodes.agent.tools.base import Tool
+
+
+class FactorTool(Tool):
+    """因子分析工具
+
+    对因子进行 IC 分析、相关性分析等。
+
+    通过 CodeSandbox 安全执行因子代码，获取因子值，
+    然后计算 IC、ICIR 等统计指标。
+
+    factor_code 示例:
+        import polars as pl
+        result = pl.DataFrame({
+            "date": ["2024-01-01", "2024-01-01", "2024-01-02", "2024-01-02"],
+            "code": ["A", "B", "A", "B"],
+            "factor_value": [0.1, 0.2, 0.3, 0.4],
+            "forward_return": [0.05, 0.03, 0.02, 0.01],
+        })
+    """
+
+    def __init__(self):
+        pass
+
+    @property
+    def name(self) -> str:
+        return "factor"
+
+    @property
+    def description(self) -> str:
+        return (
+            "对因子进行IC分析、相关性分析等。"
+            "factor_code 中需将结果赋给 result 变量，"
+            "result 应包含 date, code, factor_value, forward_return 列。"
+        )
+
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "factor_code": {
+                    "type": "string",
+                    "description": (
+                        "因子的Python代码，结果应赋给 'result' 变量，"
+                        "包含 date/code/factor_value/forward_return 列"
+                    ),
+                },
+                "analysis_type": {
+                    "type": "string",
+                    "description": "分析类型：ic（IC分析）、correlation（相关性分析）、both",
+                    "enum": ["ic", "correlation", "both"],
+                    "default": "both"
+                },
+                "start_date": {
+                    "type": "string",
+                    "description": "分析开始日期"
+                },
+                "end_date": {
+                    "type": "string",
+                    "description": "分析结束日期"
+                }
+            },
+            "required": ["factor_code", "analysis_type"]
+        }
+
+    @property
+    def read_only(self) -> bool:
+        return True
+
+    async def execute(
+        self,
+        factor_code: str,
+        analysis_type: str = "both",
+        start_date: str = None,
+        end_date: str = None,
+        **kwargs
+    ) -> Dict[str, Any]:
+        result = {
+            "status": "success",
+            "analysis": {
+                "ic": {},
+                "correlation": {}
+            }
+        }
+
+        try:
+            from QuantNodes.ai.sandbox import CodeSandbox
+            import polars as pl
+
+            sandbox = CodeSandbox()
+            validation = sandbox.validate(factor_code)
+
+            if not validation.is_safe:
+                result["status"] = "error"
+                result["errors"] = validation.errors
+                result["security_status"] = "unsafe"
+                return result
+
+            result["security_status"] = "safe"
+
+            namespace = sandbox.validate_and_execute(factor_code)
+            factor_result = namespace.get("result")
+
+            if factor_result is None:
+                result["status"] = "error"
+                result["errors"] = [
+                    "No 'result' variable found. Factor code must assign to 'result', e.g.:\n"
+                    "result = pl.DataFrame({...})"
+                ]
+                return result
+
+            if not isinstance(factor_result, pl.DataFrame):
+                result["status"] = "error"
+                result["errors"] = [
+                    f"Expected Polars DataFrame, got {type(factor_result).__name__}. "
+                    "Factor code should create a Polars DataFrame."
+                ]
+                return result
+
+            required_cols = {"factor_value", "forward_return"}
+            missing = required_cols - set(factor_result.columns)
+            if missing:
+                result["status"] = "error"
+                result["errors"] = [
+                    f"Missing required columns: {missing}. "
+                    f"Available columns: {list(factor_result.columns)}. "
+                    "Result must have 'factor_value' and 'forward_return' columns."
+                ]
+                return result
+
+            if "date" in factor_result.columns and start_date and end_date:
+                factor_result = factor_result.filter(
+                    (pl.col("date") >= start_date) &
+                    (pl.col("date") <= end_date)
+                )
+
+            if analysis_type in ("ic", "both"):
+                result["analysis"]["ic"] = self._compute_ic(factor_result)
+
+            if analysis_type in ("correlation", "both"):
+                result["analysis"]["correlation"] = self._compute_correlation(factor_result)
+
+            result["data_rows"] = len(factor_result)
+            result["columns"] = list(factor_result.columns)
+
+        except Exception as e:
+            result["status"] = "error"
+            result["errors"] = [str(e)]
+
+        return result
+
+    def _compute_ic(self, df) -> Dict[str, Any]:
+        """计算 IC 分析结果"""
+        import polars as pl
+
+        if "date" not in df.columns:
+            factor = df["factor_value"]
+            fwd = df["forward_return"]
+            ic_val = factor.to_frame().select(pl.corr(factor, fwd)).to_series()[0]
+            rank_ic_val = factor.rank().to_frame().select(
+                pl.corr(factor.rank(), fwd.rank())
+            ).to_series()[0]
+            return {
+                "ic_mean": ic_val,
+                "ic_std": 0.0,
+                "icir": ic_val,
+                "rank_ic_mean": rank_ic_val,
+                "note": "Single cross-section IC (no date column for time-series analysis)",
+            }
+
+        ic_series = df.group_by("date").agg([
+            pl.corr("factor_value", "forward_return").alias("ic"),
+        ]).sort("date")
+
+        ic_values = ic_series["ic"].drop_nulls()
+        ic_mean = ic_values.mean()
+        ic_std = ic_values.std()
+        icir = ic_mean / (ic_std + 1e-8) if ic_std else 0.0
+
+        rank_ic_series = df.group_by("date").agg([
+            pl.corr(
+                pl.col("factor_value").rank(),
+                pl.col("forward_return").rank()
+            ).alias("rank_ic"),
+        ]).sort("date")
+
+        rank_ic_values = rank_ic_series["rank_ic"].drop_nulls()
+        rank_ic_mean = rank_ic_values.mean()
+
+        return {
+            "ic_mean": round(ic_mean, 6) if ic_mean is not None else None,
+            "ic_std": round(ic_std, 6) if ic_std is not None else None,
+            "icir": round(icir, 6) if icir is not None else None,
+            "rank_ic_mean": round(rank_ic_mean, 6) if rank_ic_mean is not None else None,
+            "ic_series": ic_series.to_dicts(),
+            "n_dates": len(ic_series),
+        }
+
+    def _compute_correlation(self, df) -> Dict[str, Any]:
+        """计算相关性分析"""
+        import polars as pl
+
+        result = {}
+
+        if "factor_value" in df.columns and "forward_return" in df.columns:
+            factor = df["factor_value"]
+            fwd = df["forward_return"]
+            corr = factor.to_frame().select(pl.corr(factor, fwd)).to_series()[0]
+            result["factor_return_corr"] = round(corr, 6) if corr is not None else None
+
+        numeric_cols = [c for c in df.columns if df[c].dtype in (
+            pl.Float32, pl.Float64, pl.Int32, pl.Int64
+        )]
+        if len(numeric_cols) >= 2:
+            corr_matrix = df.select(numeric_cols).corr()
+            result["correlation_matrix"] = {
+                "columns": numeric_cols,
+                "values": corr_matrix.to_dicts(),
+            }
+
+        return result

QuantNodes/agent/tools/file_ops.py

@@ -0,0 +1,201 @@
+# coding=utf-8
+"""
+文件操作工具
+
+提供安全的文件读/写/编辑/列表/glob 操作。
+路径限制在 workspace 内，防止 path traversal。
+"""
+
+from pathlib import Path
+from typing import Any, Dict
+
+from .base import Tool
+from ._workspace import WorkspaceTool
+from QuantNodes.core.path_utils import ensure_parent
+
+
+class FileOpsTool(WorkspaceTool, Tool):
+    """文件操作工具
+
+    安全地读取、写入、编辑文件，列出目录内容，glob 模式匹配。
+    所有路径限制在 workspace 内。
+    """
+
+    MAX_FILE_SIZE = 1 * 1024 * 1024  # 1MB
+
+    def __init__(self, workspace: str | Path):
+        super().__init__(workspace)
+
+    @property
+    def name(self) -> str:
+        return "file_ops"
+
+    @property
+    def description(self) -> str:
+        return (
+            "文件操作工具：读/写/编辑文件、列出目录、glob模式匹配。"
+            "所有路径限制在工作目录内。"
+        )
+
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "action": {
+                    "type": "string",
+                    "enum": ["read_file", "write_file", "edit_file", "list_files", "glob_files"],
+                    "description": "操作类型",
+                },
+                "path": {
+                    "type": "string",
+                    "description": "文件或目录路径（相对于工作目录）",
+                },
+                "content": {
+                    "type": "string",
+                    "description": "要写入的内容（write_file 时必需）",
+                },
+                "old_string": {
+                    "type": "string",
+                    "description": "要替换的旧字符串（edit_file 时必需）",
+                },
+                "new_string": {
+                    "type": "string",
+                    "description": "替换后的新字符串（edit_file 时必需）",
+                },
+                "pattern": {
+                    "type": "string",
+                    "description": "glob 模式（glob_files 时必需），如 **/*.py",
+                },
+                "offset": {
+                    "type": "integer",
+                    "description": "读取起始行号（从1开始）",
+                    "default": 1,
+                },
+                "limit": {
+                    "type": "integer",
+                    "description": "读取最大行数",
+                    "default": 2000,
+                },
+            },
+            "required": ["action"],
+        }
+
+    @property
+    def read_only(self) -> bool:
+        return False
+
+    def _safe_path(self, rel_path: str) -> Path:
+        """Resolve workspace-relative path (Phase J1: now inherited)."""
+        return WorkspaceTool._safe_path(self, rel_path)
+
+    async def execute(self, action: str, **kwargs: Any) -> Any:
+        return await self._dispatch(action, {
+            "read_file": self._read_file,
+            "write_file": self._write_file,
+            "edit_file": self._edit_file,
+            "list_files": self._list_files,
+            "glob_files": self._glob_files,
+        }, **kwargs)
+
+    async def _read_file(
+        self, path: str = "", offset: int = 1, limit: int = 2000, **kw,
+    ) -> Dict[str, Any]:
+        target = self._safe_path(path)
+        if not target.exists():
+            return {"error": f"File not found: {path}"}
+        if not target.is_file():
+            return {"error": f"Not a file: {path}"}
+        if target.stat().st_size > self.MAX_FILE_SIZE:
+            return {
+                "error": (
+                    f"File too large ({target.stat().st_size} bytes). "
+                    f"Max: {self.MAX_FILE_SIZE}"
+                )
+            }
+
+        lines = target.read_text(encoding="utf-8", errors="replace").splitlines(keepends=True)
+        total = len(lines)
+        sliced = lines[max(0, offset - 1) : offset - 1 + limit]
+        return {
+            "content": "".join(sliced),
+            "total_lines": total,
+            "offset": offset,
+            "lines_returned": len(sliced),
+        }
+
+    async def _write_file(
+        self, path: str = "", content: str = "", **kw,
+    ) -> Dict[str, Any]:
+        target = self._safe_path(path)
+        ensure_parent(target)
+        target.write_text(content, encoding="utf-8")
+        return {
+            "status": "ok",
+            "bytes_written": len(content.encode("utf-8")),
+            "path": str(target.relative_to(self.workspace)),
+        }
+
+    async def _edit_file(
+        self, path: str = "", old_string: str = "", new_string: str = "", **kw,
+    ) -> Dict[str, Any]:
+        if not old_string:
+            return {"error": "old_string is required"}
+        target = self._safe_path(path)
+        if not target.exists():
+            return {"error": f"File not found: {path}"}
+
+        original = target.read_text(encoding="utf-8")
+        count = original.count(old_string)
+        if count == 0:
+            return {"error": "old_string not found in file"}
+        if count > 1:
+            return {
+                "error": (
+                    f"old_string found {count} times. "
+                    "Provide more context to make it unique."
+                )
+            }
+
+        updated = original.replace(old_string, new_string, 1)
+        target.write_text(updated, encoding="utf-8")
+        return {
+            "status": "ok",
+            "replacements": 1,
+            "path": str(target.relative_to(self.workspace)),
+        }
+
+    async def _list_files(self, path: str = "", pattern: str = "", **kw) -> Dict[str, Any]:
+        target = self._safe_path(path or ".")
+        if not target.exists():
+            return {"error": f"Directory not found: {path}"}
+        if not target.is_dir():
+            return {"error": f"Not a directory: {path}"}
+
+        entries = []
+        for entry in sorted(target.iterdir()):
+            rel = str(entry.relative_to(self.workspace))
+            entries.append({
+                "name": entry.name,
+                "path": rel,
+                "type": "dir" if entry.is_dir() else "file",
+                "size": entry.stat().st_size if entry.is_file() else None,
+            })
+        return {"entries": entries[:200], "total": len(entries)}
+
+    async def _glob_files(self, pattern: str = "", path: str = "", **kw) -> Dict[str, Any]:
+        if not pattern:
+            return {"error": "pattern is required for glob_files"}
+        base = self._safe_path(path or ".")
+        if not base.exists():
+            return {"error": f"Directory not found: {path}"}
+
+        matches = sorted(base.glob(pattern))
+        results = []
+        for m in matches:
+            if m.is_file():
+                results.append({
+                    "path": str(m.relative_to(self.workspace)),
+                    "size": m.stat().st_size,
+                })
+        return {"matches": results[:100], "total": len(results)}

QuantNodes/agent/tools/git_ops.py

@@ -0,0 +1,190 @@
+# coding=utf-8
+"""
+Git 操作工具
+
+提供 git status/diff/log/commit 操作。
+限制在 workspace 目录内执行。
+"""
+
+import asyncio
+from pathlib import Path
+from typing import Any, Dict, List
+
+from .base import Tool
+from ._workspace import WorkspaceTool
+
+
+class GitOpsTool(WorkspaceTool, Tool):
+    """Git 操作工具
+
+    安全地执行 git 命令：status、diff、log、commit。
+    """
+
+    def __init__(self, workspace: str | Path):
+        super().__init__(workspace)
+
+    @property
+    def name(self) -> str:
+        return "git_ops"
+
+    @property
+    def description(self) -> str:
+        return "Git 操作工具：查看状态、差异、提交历史、创建提交"
+
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "action": {
+                    "type": "string",
+                    "enum": ["git_status", "git_diff", "git_log", "git_commit"],
+                    "description": "Git 操作类型",
+                },
+                "path": {
+                    "type": "string",
+                    "description": "文件路径（可选，用于 git_diff）",
+                },
+                "message": {
+                    "type": "string",
+                    "description": "提交消息（git_commit 时必需）",
+                },
+                "files": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "要提交的文件列表（可选，默认提交所有变更）",
+                },
+                "n": {
+                    "type": "integer",
+                    "description": "显示最近 n 条提交（git_log 时使用）",
+                    "default": 10,
+                },
+            },
+            "required": ["action"],
+        }
+
+    @property
+    def read_only(self) -> bool:
+        return False
+
+    @property
+    def concurrency_safe(self) -> bool:
+        return False
+
+    async def _run_git(self, *args: str) -> Dict[str, Any]:
+        """执行 git 命令"""
+        cmd = ["git", "-C", str(self.workspace)] + list(args)
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=30)
+            return {
+                "returncode": proc.returncode,
+                "stdout": stdout.decode("utf-8", errors="replace").strip(),
+                "stderr": stderr.decode("utf-8", errors="replace").strip(),
+            }
+        except asyncio.TimeoutError:
+            return {"error": "Git command timed out after 30s"}
+        except FileNotFoundError:
+            return {"error": "Git is not installed or not in PATH"}
+
+    async def execute(self, action: str, **kwargs: Any) -> Any:
+        return await self._dispatch(action, {
+            "git_status": self._git_status,
+            "git_diff": self._git_diff,
+            "git_log": self._git_log,
+            "git_commit": self._git_commit,
+        }, **kwargs)
+
+    async def _git_status(self, **kw) -> Dict[str, Any]:
+        result = await self._run_git("status", "--porcelain")
+        if result.get("error"):
+            return result
+        if result["returncode"] != 0:
+            return {"error": result["stderr"] or "git status failed"}
+
+        lines = result["stdout"].splitlines() if result["stdout"] else []
+        files = []
+        for line in lines:
+            if len(line) >= 3:
+                status = line[:2].strip()
+                filepath = line[3:]
+                files.append({"status": status, "path": filepath})
+
+        return {"clean": len(files) == 0, "files": files, "total": len(files)}
+
+    async def _git_diff(self, path: str = "", **kw) -> Dict[str, Any]:
+        args = ["diff"]
+        if path:
+            args.extend(["--", path])
+        result = await self._run_git(*args)
+        if result.get("error"):
+            return result
+        if result["returncode"] != 0:
+            return {"error": result["stderr"] or "git diff failed"}
+
+        return {"diff": result["stdout"], "has_changes": bool(result["stdout"])}
+
+    async def _git_log(self, n: int = 10, **kw) -> Dict[str, Any]:
+        result = await self._run_git(
+            "log", f"-{n}", "--pretty=format:%H|%an|%ae|%ad|%s", "--date=short"
+        )
+        if result.get("error"):
+            return result
+        if result["returncode"] != 0:
+            return {"error": result["stderr"] or "git log failed"}
+
+        commits = []
+        for line in result["stdout"].splitlines():
+            parts = line.split("|", 4)
+            if len(parts) == 5:
+                commits.append({
+                    "hash": parts[0][:8],
+                    "author": parts[1],
+                    "email": parts[2],
+                    "date": parts[3],
+                    "message": parts[4],
+                })
+
+        return {"commits": commits, "total": len(commits)}
+
+    async def _git_commit(self, message: str = "", files: List[str] = None, **kw) -> Dict[str, Any]:
+        if not message:
+            return {"error": "message is required for git_commit"}
+
+        # Stage files
+        if files:
+            for f in files:
+                result = await self._run_git("add", "--", f)
+                if result.get("error"):
+                    return result
+        else:
+            result = await self._run_git("add", "-A")
+            if result.get("error"):
+                return result
+
+        # Check if there's anything to commit
+        status_result = await self._run_git("status", "--porcelain")
+        if status_result.get("stdout") == "":
+            return {"error": "Nothing to commit (working tree clean)"}
+
+        # Commit
+        result = await self._run_git("commit", "-m", message)
+        if result.get("error"):
+            return result
+        if result["returncode"] != 0:
+            return {"error": result["stderr"] or "git commit failed"}
+
+        # Get commit hash
+        hash_result = await self._run_git("rev-parse", "--short", "HEAD")
+        commit_hash = hash_result.get("stdout", "unknown")
+
+        return {
+            "status": "ok",
+            "commit": commit_hash,
+            "message": message,
+            "files": files or "all",
+        }