loom-agent 0.0.1__py3-none-any.whl

loom/builtin/tools/document_search.py

@@ -0,0 +1,111 @@
+"""文档搜索工具 - 主动检索版本"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+from loom.interfaces.tool import BaseTool
+
+try:
+    from loom.interfaces.retriever import BaseRetriever
+except ImportError:
+    BaseRetriever = None  # type: ignore
+
+
+class DocumentSearchInput(BaseModel):
+    """文档搜索输入参数"""
+
+    query: str = Field(description="Search query for documents")
+    top_k: int = Field(default=3, description="Number of documents to retrieve")
+
+
+class DocumentSearchTool(BaseTool):
+    """
+    文档搜索工具 - 作为普通工具供 Agent 主动调用
+
+    与 ContextRetriever 的区别:
+    - ContextRetriever: 自动检索（每次查询前）- 核心组件
+    - DocumentSearchTool: 主动检索（LLM 决定何时）- 工具
+
+    适用场景:
+    - Agent 需要动态决定何时检索文档
+    - 可能需要多次检索（不同查询）
+    - 与其他工具配合使用
+
+    示例:
+        retriever = VectorStoreRetriever(vector_store)
+        search_tool = DocumentSearchTool(retriever)
+
+        agent = Agent(
+            llm=llm,
+            tools=[search_tool, Calculator(), ...]
+        )
+
+        # Agent 会自己决定是否需要搜索文档
+        result = await agent.run("Calculate 10*20 and search for Python docs")
+    """
+
+    name = "search_documents"
+    description = (
+        "Search for relevant documents from the knowledge base. "
+        "Use this when you need specific information that might be in the documents. "
+        "Returns document content with relevance scores."
+    )
+    args_schema = DocumentSearchInput
+    is_concurrency_safe = True
+
+    def __init__(self, retriever: "BaseRetriever"):
+        """
+        Parameters:
+            retriever: 检索器实例 (例如 VectorStoreRetriever)
+        """
+        if BaseRetriever is None:
+            raise ImportError("Please install retriever dependencies")
+
+        self.retriever = retriever
+
+    async def run(self, query: str, top_k: int = 3, **kwargs: Any) -> str:
+        """
+        执行文档搜索
+
+        Parameters:
+            query: 搜索查询
+            top_k: 返回文档数量
+
+        Returns:
+            格式化的文档搜索结果
+        """
+        try:
+            docs = await self.retriever.retrieve(query, top_k=top_k)
+
+            if not docs:
+                return f"No relevant documents found for query: '{query}'"
+
+            # 格式化返回结果
+            lines = [f"Found {len(docs)} relevant document(s) for: '{query}'\n"]
+
+            for i, doc in enumerate(docs, 1):
+                lines.append(f"**Document {i}**")
+
+                # 元数据
+                if doc.metadata:
+                    source = doc.metadata.get("source", "Unknown")
+                    lines.append(f"Source: {source}")
+
+                # 相关性分数
+                if doc.score is not None:
+                    lines.append(f"Relevance: {doc.score:.2%}")
+
+                # 内容 (截断长文档)
+                content = doc.content
+                if len(content) > 500:
+                    content = content[:500] + "...\n[Content truncated for brevity]"
+
+                lines.append(f"\n{content}\n")
+
+            return "\n".join(lines)
+
+        except Exception as e:
+            return f"Error searching documents: {type(e).__name__}: {str(e)}"

loom/builtin/tools/glob.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import glob as _glob
+from pathlib import Path
+from typing import Any, List
+
+from pydantic import BaseModel, Field
+
+from loom.interfaces.tool import BaseTool
+
+
+class GlobArgs(BaseModel):
+    pattern: str = Field(description="Glob 匹配模式，例如 **/*.py")
+    cwd: str | None = Field(default=None, description="可选工作目录")
+
+
+class GlobTool(BaseTool):
+    name = "glob"
+    description = "按模式匹配文件路径"
+    args_schema = GlobArgs
+
+    async def run(self, **kwargs) -> Any:
+        args = self.args_schema(**kwargs)  # type: ignore
+        cwd = Path(args.cwd).expanduser() if args.cwd else Path.cwd()
+        paths: List[str] = [str(Path(p)) for p in _glob.glob(str(cwd / args.pattern), recursive=True)]
+        return "\n".join(paths)
+

loom/builtin/tools/grep.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any, List
+
+from pydantic import BaseModel, Field
+
+from loom.interfaces.tool import BaseTool
+
+
+class GrepArgs(BaseModel):
+    pattern: str = Field(description="正则表达式")
+    path: str | None = Field(default=None, description="目标文件")
+    glob_pattern: str | None = Field(default=None, description="Glob 模式（与 path 二选一）")
+    flags: str | None = Field(default="", description="i=IGNORECASE, m=MULTILINE")
+    encoding: str = Field(default="utf-8")
+
+
+class GrepTool(BaseTool):
+    name = "grep"
+    description = "在文件或文件集内检索正则匹配"
+    args_schema = GrepArgs
+
+    async def run(self, **kwargs) -> Any:
+        args = self.args_schema(**kwargs)  # type: ignore
+        flags = 0
+        if args.flags:
+            if "i" in args.flags:
+                flags |= re.IGNORECASE
+            if "m" in args.flags:
+                flags |= re.MULTILINE
+        regex = re.compile(args.pattern, flags)
+
+        files: List[Path] = []
+        if args.path:
+            files = [Path(args.path).expanduser()]
+        elif args.glob_pattern:
+            from glob import glob
+
+            files = [Path(p) for p in glob(args.glob_pattern, recursive=True)]
+        else:
+            return "必须提供 path 或 glob_pattern"
+
+        matches: List[str] = []
+        for f in files:
+            if not f.exists() or not f.is_file():
+                continue
+            try:
+                for i, line in enumerate(f.read_text(encoding=args.encoding, errors="replace").splitlines(), 1):
+                    if regex.search(line):
+                        matches.append(f"{f}:{i}: {line}")
+            except Exception as e:
+                matches.append(f"{f}: <error {e}>")
+        return "\n".join(matches)
+

loom/builtin/tools/http_request.py

@@ -0,0 +1,86 @@
+"""HTTP 请求工具 - 发送 HTTP 请求"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+from loom.interfaces.tool import BaseTool
+
+try:
+    import httpx
+except ImportError:
+    httpx = None  # type: ignore
+
+
+class HTTPRequestInput(BaseModel):
+    """HTTP 请求输入参数"""
+
+    url: str = Field(description="URL to request")
+    method: str = Field(default="GET", description="HTTP method (GET, POST, PUT, DELETE)")
+    headers: Optional[dict] = Field(default=None, description="Request headers")
+    body: Optional[str] = Field(default=None, description="Request body (for POST/PUT)")
+
+
+class HTTPRequestTool(BaseTool):
+    """
+    HTTP 请求工具 - 发送 HTTP 请求并返回响应
+
+    需要安装: pip install httpx
+    """
+
+    name = "http_request"
+    description = "Send HTTP requests (GET, POST, PUT, DELETE) to a URL and return the response"
+    args_schema = HTTPRequestInput
+    is_concurrency_safe = True
+
+    def __init__(self, timeout: int = 10) -> None:
+        if httpx is None:
+            raise ImportError("Please install httpx: pip install httpx")
+        self.timeout = timeout
+
+    async def run(
+        self,
+        url: str,
+        method: str = "GET",
+        headers: Optional[dict] = None,
+        body: Optional[str] = None,
+        **kwargs: Any,
+    ) -> str:
+        """执行 HTTP 请求"""
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                request_kwargs: dict = {"method": method.upper(), "url": url}
+
+                if headers:
+                    request_kwargs["headers"] = headers
+
+                if body and method.upper() in ["POST", "PUT", "PATCH"]:
+                    request_kwargs["content"] = body
+
+                response = await client.request(**request_kwargs)
+
+                # 格式化响应
+                result_lines = [
+                    f"HTTP {response.status_code}",
+                    f"URL: {url}",
+                    f"Method: {method.upper()}",
+                    "",
+                    "Headers:",
+                ]
+
+                for key, value in response.headers.items():
+                    result_lines.append(f"  {key}: {value}")
+
+                result_lines.append("")
+                result_lines.append("Body:")
+                result_lines.append(response.text[:1000])  # 限制输出长度
+
+                if len(response.text) > 1000:
+                    result_lines.append(f"\n... (truncated, total {len(response.text)} characters)")
+
+                return "\n".join(result_lines)
+
+        except Exception as e:
+            return f"HTTP request error: {type(e).__name__}: {str(e)}"

loom/builtin/tools/python_repl.py

@@ -0,0 +1,73 @@
+"""Python REPL 工具 - 执行 Python 代码"""
+
+from __future__ import annotations
+
+import sys
+from io import StringIO
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from loom.interfaces.tool import BaseTool
+
+
+class PythonREPLInput(BaseModel):
+    """Python REPL 输入参数"""
+
+    code: str = Field(description="Python code to execute")
+
+
+class PythonREPLTool(BaseTool):
+    """
+    Python REPL 工具 - 在隔离环境中执行 Python 代码
+
+    警告: 不要在生产环境中使用,存在安全风险!
+    """
+
+    name = "python_repl"
+    description = (
+        "Execute Python code and return the output. "
+        "Can be used for calculations, data processing, etc. "
+        "The code runs in a restricted environment."
+    )
+    args_schema = PythonREPLInput
+    is_concurrency_safe = False  # 代码执行不并发安全
+
+    async def run(self, code: str, **kwargs: Any) -> str:
+        """执行 Python 代码"""
+        # 安全性检查 - 禁止危险操作
+        dangerous_imports = ["os", "subprocess", "sys", "importlib", "__import__"]
+        for dangerous in dangerous_imports:
+            if dangerous in code:
+                return f"Security error: Import of '{dangerous}' is not allowed"
+
+        # 捕获标准输出
+        old_stdout = sys.stdout
+        sys.stdout = captured_output = StringIO()
+
+        try:
+            # 使用受限的全局命名空间
+            namespace: dict = {"__builtins__": __builtins__}
+
+            # 执行代码
+            exec(code, namespace)
+
+            # 获取输出
+            output = captured_output.getvalue()
+
+            if not output:
+                # 如果没有打印输出,尝试返回最后一个表达式的值
+                try:
+                    result = eval(code, namespace)
+                    if result is not None:
+                        output = str(result)
+                except Exception:
+                    output = "Code executed successfully (no output)"
+
+            return output.strip()
+
+        except Exception as e:
+            return f"Execution error: {type(e).__name__}: {str(e)}"
+
+        finally:
+            sys.stdout = old_stdout

loom/builtin/tools/read_file.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from loom.interfaces.tool import BaseTool
+
+
+class ReadArgs(BaseModel):
+    path: str = Field(description="文件路径")
+    max_bytes: int | None = Field(default=200_000, description="最大读取字节数，默认200KB")
+    encoding: str = Field(default="utf-8", description="文本编码")
+
+
+class ReadFileTool(BaseTool):
+    name = "read_file"
+    description = "读取文本文件内容"
+    args_schema = ReadArgs
+
+    async def run(self, **kwargs) -> Any:
+        args = self.args_schema(**kwargs)  # type: ignore
+        p = Path(args.path).expanduser()
+        data = p.read_bytes()
+        if args.max_bytes is not None and len(data) > args.max_bytes:
+            data = data[: args.max_bytes]
+        try:
+            return data.decode(args.encoding, errors="replace")
+        except Exception:
+            return data.decode("utf-8", errors="replace")
+

loom/builtin/tools/task.py

@@ -0,0 +1,158 @@
+"""Task 工具 - 启动 SubAgent 执行子任务"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Optional, Dict, List
+
+from pydantic import BaseModel, Field
+
+from loom.interfaces.tool import BaseTool
+from loom.core.permissions import PermissionManager
+from loom.agents.registry import get_agent_by_type as get_registered_agent_by_type
+from loom.utils.agent_loader import (
+    get_agent_by_type as get_file_agent_by_type,
+)  # fallback to file-based packs
+from loom.agents.refs import AgentRef, ModelRef
+
+if TYPE_CHECKING:
+    from loom.components.agent import Agent
+
+
+class TaskInput(BaseModel):
+    """Task 工具输入参数"""
+
+    description: str = Field(description="Short description of the task (3-5 words)")
+    prompt: str = Field(description="Detailed task instructions for the sub-agent")
+    subagent_type: str | None = Field(
+        default=None, description="Optional: agent type from .loom/.claude agent packs"
+    )
+    model_name: str | None = Field(
+        default=None, description="Optional: override model name for this sub-agent"
+    )
+
+
+class TaskTool(BaseTool):
+    """
+    Task 工具 - 启动 SubAgent 执行专项任务
+
+    对应 Claude Code 的 Task 工具和 SubAgent 机制
+    """
+
+    name = "task"
+    description = (
+        "Launch a sub-agent to handle a specific subtask independently. "
+        "Useful for parallel execution or specialized processing. "
+        "The sub-agent has its own execution environment and tool access."
+    )
+    args_schema = TaskInput
+    is_concurrency_safe = True
+
+    def __init__(
+        self,
+        agent_factory: Optional[callable] = None,
+        max_iterations: int = 20,
+    ) -> None:
+        """
+        Parameters:
+        - agent_factory: 创建 SubAgent 的工厂函数
+        - max_iterations: SubAgent 最大迭代次数
+        """
+        self.agent_factory = agent_factory
+        self.max_iterations = max_iterations
+
+    async def run(
+        self,
+        description: str,
+        prompt: str,
+        subagent_type: str | None = None,
+        model_name: str | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """执行子任务"""
+        if not self.agent_factory:
+            return "Error: Task tool not configured with agent_factory"
+
+        try:
+            # 解析 Agent Packs（若提供 subagent_type）
+            agent_system_instructions: Optional[str] = None
+            allowed_tools: Optional[List[str]] = None
+            effective_model: Optional[str] = model_name
+
+            if subagent_type:
+                # 1) Prefer programmatic registry
+                cfg = get_registered_agent_by_type(subagent_type)
+                if cfg:
+                    agent_system_instructions = cfg.system_instructions or None
+                    if isinstance(cfg.tools, list):
+                        allowed_tools = list(cfg.tools)
+                    elif cfg.tools == "*":
+                        allowed_tools = None
+                    if effective_model is None and cfg.model_name:
+                        effective_model = cfg.model_name
+                else:
+                    # 2) Fallback to file-based packs (optional)
+                    fcfg = get_file_agent_by_type(subagent_type)
+                    if fcfg:
+                        agent_system_instructions = fcfg.system_prompt or None
+                        if isinstance(fcfg.tools, list):
+                            allowed_tools = fcfg.tools
+                        elif fcfg.tools == "*":
+                            allowed_tools = None
+                        if effective_model is None and fcfg.model_name:
+                            effective_model = fcfg.model_name
+
+            # 构造权限策略（若需要限制工具）
+            permission_policy: Optional[Dict[str, str]] = None
+            if allowed_tools is not None:
+                policy: Dict[str, str] = {"default": "deny"}
+                for t in allowed_tools:
+                    policy[t] = "allow"
+                permission_policy = policy
+
+            # 创建 SubAgent 实例（尽量传递可选参数；不支持则回退）
+            try:
+                sub_agent: Agent = self.agent_factory(  # type: ignore[call-arg]
+                    max_iterations=self.max_iterations,
+                    system_instructions=agent_system_instructions,
+                    permission_policy=permission_policy,
+                    model_name=effective_model,
+                )
+            except TypeError:
+                # 回退到最小签名
+                sub_agent = self.agent_factory(max_iterations=self.max_iterations)  # type: ignore[call-arg]
+
+                # 如果无法通过构造器注入权限，则运行时替换权限管理器
+                if permission_policy is not None:
+                    sub_agent.executor.permission_manager = PermissionManager(
+                        policy=permission_policy
+                    )
+                    sub_agent.executor.tool_pipeline.permission_manager = (
+                        sub_agent.executor.permission_manager
+                    )
+
+            # 运行子任务（系统提示已注入到 sub_agent，输入仍为原始 prompt）
+            result = await sub_agent.run(prompt)
+
+            # 格式化返回结果
+            return f"**SubAgent Task: {description}**\n\nResult:\n{result}"
+
+        except Exception as e:
+            return f"SubAgent execution error: {type(e).__name__}: {str(e)}"
+
+    # Framework-friendly API: set by reference instead of strings
+    async def run_ref(
+        self,
+        *,
+        description: str,
+        prompt: str,
+        agent: AgentRef | None = None,
+        model: ModelRef | None = None,
+    ) -> str:
+        subagent_type = agent.agent_type if isinstance(agent, AgentRef) else None
+        model_name = model.name if isinstance(model, ModelRef) else None
+        return await self.run(
+            description=description,
+            prompt=prompt,
+            subagent_type=subagent_type,
+            model_name=model_name,
+        )

loom/builtin/tools/web_search.py

@@ -0,0 +1,64 @@
+"""Web 搜索工具 - 使用 DuckDuckGo (无需 API key)"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from loom.interfaces.tool import BaseTool
+
+try:
+    from duckduckgo_search import DDGS
+except ImportError:
+    DDGS = None  # type: ignore
+
+
+class WebSearchInput(BaseModel):
+    """Web 搜索输入参数"""
+
+    query: str = Field(description="Search query")
+    max_results: int = Field(default=5, description="Maximum number of results to return")
+
+
+class WebSearchTool(BaseTool):
+    """
+    Web 搜索工具 - 使用 DuckDuckGo
+
+    需要安装: pip install duckduckgo-search
+    """
+
+    name = "web_search"
+    description = "Search the web using DuckDuckGo. Returns titles, snippets, and URLs."
+    args_schema = WebSearchInput
+    is_concurrency_safe = True
+
+    def __init__(self) -> None:
+        if DDGS is None:
+            raise ImportError(
+                "Please install duckduckgo-search: pip install duckduckgo-search"
+            )
+
+    async def run(self, query: str, max_results: int = 5, **kwargs: Any) -> str:
+        """执行搜索"""
+        try:
+            with DDGS() as ddgs:
+                results = list(ddgs.text(query, max_results=max_results))
+
+            if not results:
+                return f"No results found for query: {query}"
+
+            # 格式化输出
+            output_lines = [f"Search results for '{query}':\n"]
+            for i, result in enumerate(results, 1):
+                title = result.get("title", "No title")
+                snippet = result.get("body", "")
+                url = result.get("href", "")
+                output_lines.append(f"{i}. **{title}**")
+                output_lines.append(f"   {snippet}")
+                output_lines.append(f"   URL: {url}\n")
+
+            return "\n".join(output_lines)
+
+        except Exception as e:
+            return f"Search error: {str(e)}"

loom/builtin/tools/write_file.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from loom.interfaces.tool import BaseTool
+
+
+class WriteArgs(BaseModel):
+    path: str = Field(description="文件路径")
+    content: str = Field(description="写入内容")
+    encoding: str = Field(default="utf-8", description="文本编码")
+    overwrite: bool = Field(default=True, description="是否覆盖")
+
+
+class WriteFileTool(BaseTool):
+    name = "write_file"
+    description = "写入文本到文件（可能覆盖）"
+    args_schema = WriteArgs
+
+    async def run(self, **kwargs) -> Any:
+        args = self.args_schema(**kwargs)  # type: ignore
+        p = Path(args.path).expanduser()
+        if p.exists() and not args.overwrite:
+            return f"File exists and overwrite=False: {p}"
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(args.content, encoding=args.encoding)
+        return f"Wrote {len(args.content)} chars to {str(p)}"
+

loom/callbacks/base.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+
+
+class BaseCallback:
+    async def on_event(self, event_type: str, payload: Dict[str, Any]) -> None:
+        return None
+

loom/callbacks/logging.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from .base import BaseCallback
+
+
+class LoggingCallback(BaseCallback):
+    async def on_event(self, event_type: str, payload: Dict[str, Any]) -> None:
+        # 最小实现：打印事件
+        print(f"[loom] {event_type}: {payload}")
+