superqode 0.1.5__py3-none-any.whl

superqode/tools/base.py

@@ -0,0 +1,324 @@
+"""
+Base Tool System - Minimal, Standard Interface.
+
+Design:
+- OpenAI-compatible tool format (works with any provider via LiteLLM)
+- No opinionated prompts - just tool name, description, parameters
+- Transparent execution - what you call is what runs
+
+Performance features:
+- Streaming output support for long-running tools
+- Progress callbacks for UI updates
+- Async-first design for non-blocking execution
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Dict, List, Optional, Callable, Union
+from pathlib import Path
+import json
+
+
+# Type aliases for callbacks
+OutputCallback = Callable[[str], Union[None, Awaitable[None]]]
+ProgressCallback = Callable[[float, str], Union[None, Awaitable[None]]]
+
+
+@dataclass
+class ToolContext:
+    """Context passed to tool execution.
+
+    Minimal context - just what's needed for execution.
+    No hidden state, no magic.
+
+    Streaming support:
+        on_output: Called with output chunks as they're produced
+        on_progress: Called with (progress_fraction, status_message)
+
+    tool_registry: Set by the agent loop so tools like BatchTool can execute other tools.
+    """
+
+    session_id: str
+    working_directory: Path
+    # Optional: for permission checks (user can enable/disable)
+    require_confirmation: bool = False
+    # Callback for streaming output (optional) - can be sync or async
+    on_output: Optional[OutputCallback] = None
+    # Callback for progress updates (0.0 to 1.0, plus status message)
+    on_progress: Optional[ProgressCallback] = None
+    # Optional: registry for BatchTool to resolve and run other tools
+    tool_registry: Optional["ToolRegistry"] = None
+    # Delegation depth for SubAgentTool (0=top, incremented for child sessions; max 3)
+    delegation_depth: int = 0
+
+    async def emit_output(self, text: str) -> None:
+        """Emit output to the callback if set."""
+        if self.on_output:
+            result = self.on_output(text)
+            if hasattr(result, "__await__"):
+                await result
+
+    async def emit_progress(self, fraction: float, status: str = "") -> None:
+        """Emit progress update to the callback if set.
+
+        Args:
+            fraction: Progress from 0.0 to 1.0
+            status: Optional status message
+        """
+        if self.on_progress:
+            result = self.on_progress(fraction, status)
+            if hasattr(result, "__await__"):
+                await result
+
+
+@dataclass
+class ToolResult:
+    """Result from tool execution.
+
+    Simple, transparent result format.
+    """
+
+    success: bool
+    output: str
+    error: Optional[str] = None
+    # Metadata for debugging/logging (not sent to model)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def to_message(self) -> str:
+        """Convert to message content for the model."""
+        if self.success:
+            return self.output
+        else:
+            return f"Error: {self.error}\n{self.output}" if self.output else f"Error: {self.error}"
+
+
+class Tool(ABC):
+    """Base class for all tools.
+
+    Minimal interface:
+    - name: Tool identifier
+    - description: What it does (sent to model)
+    - parameters: JSON Schema (sent to model)
+    - execute(): Run the tool
+
+    NO:
+    - Complex initialization
+    - Hidden system prompts
+    - Opinionated formatting
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Tool name (e.g., 'read_file')."""
+        pass
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """Tool description for the model. Keep it simple and factual."""
+        pass
+
+    @property
+    @abstractmethod
+    def parameters(self) -> Dict[str, Any]:
+        """JSON Schema for parameters."""
+        pass
+
+    @abstractmethod
+    async def execute(self, args: Dict[str, Any], ctx: ToolContext) -> ToolResult:
+        """Execute the tool with given arguments."""
+        pass
+
+    def to_openai_format(self) -> Dict[str, Any]:
+        """Convert to OpenAI function calling format.
+
+        This is the standard format that works with:
+        - OpenAI (GPT-4, GPT-5)
+        - Anthropic (Claude)
+        - Google (Gemini)
+        - All LiteLLM-supported providers
+        """
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+
+class ToolRegistry:
+    """Registry of available tools.
+
+    Simple dict-based registry. No magic, no auto-discovery.
+    """
+
+    def __init__(self):
+        self._tools: Dict[str, Tool] = {}
+
+    def register(self, tool: Tool) -> None:
+        """Register a tool."""
+        self._tools[tool.name] = tool
+
+    def get(self, name: str) -> Optional[Tool]:
+        """Get a tool by name."""
+        return self._tools.get(name)
+
+    def list(self) -> List[Tool]:
+        """List all registered tools."""
+        return list(self._tools.values())
+
+    def to_openai_format(self) -> List[Dict[str, Any]]:
+        """Get all tools in OpenAI format."""
+        return [tool.to_openai_format() for tool in self._tools.values()]
+
+    @classmethod
+    def default(cls) -> "ToolRegistry":
+        """Create registry with default minimal tools."""
+        from .file_tools import ReadFileTool, WriteFileTool, ListDirectoryTool
+        from .edit_tools import EditFileTool, InsertTextTool
+        from .shell_tools import BashTool
+        from .search_tools import GrepTool, GlobTool
+
+        registry = cls()
+
+        # Core file operations
+        registry.register(ReadFileTool())
+        registry.register(WriteFileTool())
+        registry.register(ListDirectoryTool())
+
+        # Editing
+        registry.register(EditFileTool())
+        registry.register(InsertTextTool())
+
+        # Shell
+        registry.register(BashTool())
+
+        # Search
+        registry.register(GrepTool())
+        registry.register(GlobTool())
+
+        return registry
+
+    @classmethod
+    def full(cls) -> "ToolRegistry":
+        """Create registry with all available tools."""
+        from .file_tools import ReadFileTool, WriteFileTool, ListDirectoryTool
+        from .edit_tools import EditFileTool, InsertTextTool, PatchTool, MultiEditTool
+        from .shell_tools import BashTool
+        from .search_tools import GrepTool, GlobTool, CodeSearchTool
+        from .diagnostics import DiagnosticsTool
+        from .network_tools import FetchTool, DownloadTool
+        from .agent_tools import SubAgentTool, TaskCoordinatorTool
+        from .lsp_tools import LSPTool
+        from .web_tools import WebSearchTool, WebFetchTool
+        from .question_tool import QuestionTool, ConfirmTool
+        from .todo_tools import TodoWriteTool, TodoReadTool
+        from .batch_tool import BatchTool
+
+        registry = cls()
+
+        # Core file operations
+        registry.register(ReadFileTool())
+        registry.register(WriteFileTool())
+        registry.register(ListDirectoryTool())
+
+        # Editing (basic + advanced)
+        registry.register(EditFileTool())
+        registry.register(InsertTextTool())
+        registry.register(PatchTool())
+        registry.register(MultiEditTool())
+
+        # TODO management
+        registry.register(TodoWriteTool())
+        registry.register(TodoReadTool())
+
+        # Batch (parallel tool execution)
+        registry.register(BatchTool())
+
+        # Shell
+        registry.register(BashTool())
+
+        # Search (basic + semantic)
+        registry.register(GrepTool())
+        registry.register(GlobTool())
+        registry.register(CodeSearchTool())
+
+        # Diagnostics
+        registry.register(DiagnosticsTool())
+
+        # Network
+        registry.register(FetchTool())
+        registry.register(DownloadTool())
+
+        # Web tools (search + enhanced fetch)
+        registry.register(WebSearchTool())
+        registry.register(WebFetchTool())
+
+        # Agent tools
+        registry.register(SubAgentTool())
+        registry.register(TaskCoordinatorTool())
+
+        # LSP tools
+        registry.register(LSPTool())
+
+        # Interactive tools
+        registry.register(QuestionTool())
+        registry.register(ConfirmTool())
+
+        return registry
+
+    @classmethod
+    def standard(cls) -> "ToolRegistry":
+        """Create registry with standard tools (no network/agent)."""
+        from .file_tools import ReadFileTool, WriteFileTool, ListDirectoryTool
+        from .edit_tools import EditFileTool, InsertTextTool, PatchTool, MultiEditTool
+        from .shell_tools import BashTool
+        from .search_tools import GrepTool, GlobTool, CodeSearchTool
+        from .diagnostics import DiagnosticsTool
+        from .lsp_tools import LSPTool
+        from .question_tool import QuestionTool, ConfirmTool
+        from .todo_tools import TodoWriteTool, TodoReadTool
+        from .batch_tool import BatchTool
+
+        registry = cls()
+
+        # Core file operations
+        registry.register(ReadFileTool())
+        registry.register(WriteFileTool())
+        registry.register(ListDirectoryTool())
+
+        # Editing
+        registry.register(EditFileTool())
+        registry.register(InsertTextTool())
+        registry.register(PatchTool())
+        registry.register(MultiEditTool())
+
+        # TODO management
+        registry.register(TodoWriteTool())
+        registry.register(TodoReadTool())
+
+        # Batch (parallel tool execution)
+        registry.register(BatchTool())
+
+        # Shell
+        registry.register(BashTool())
+
+        # Search
+        registry.register(GrepTool())
+        registry.register(GlobTool())
+        registry.register(CodeSearchTool())
+
+        # Diagnostics
+        registry.register(DiagnosticsTool())
+
+        # LSP tools
+        registry.register(LSPTool())
+
+        # Interactive tools
+        registry.register(QuestionTool())
+        registry.register(ConfirmTool())
+
+        return registry

superqode/tools/batch_tool.py

@@ -0,0 +1,133 @@
+"""
+Batch Tool - Execute multiple tools in parallel.
+Enables parallel execution of up to 10 tools. Recursive batch calls are blocked.
+"""
+
+import asyncio
+from typing import Any, Dict, List
+
+from .base import Tool, ToolResult, ToolContext
+
+MAX_CONCURRENT = 10
+BATCH_TOOL_NAME = "batch"
+
+
+class BatchTool(Tool):
+    """Execute multiple tool calls in parallel."""
+
+    @property
+    def name(self) -> str:
+        return BATCH_TOOL_NAME
+
+    @property
+    def description(self) -> str:
+        return (
+            "Execute multiple tool calls in parallel (up to 10). "
+            "Provide a list of {tool, parameters} objects. "
+            "Useful for parallel reads, searches, or independent operations. "
+            "Cannot include batch itself. Results are returned together."
+        )
+
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "tool_calls": {
+                    "type": "array",
+                    "description": "Array of tool calls to execute in parallel",
+                    "minItems": 1,
+                    "maxItems": MAX_CONCURRENT,
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "tool": {
+                                "type": "string",
+                                "description": "Name of the tool to execute",
+                            },
+                            "parameters": {
+                                "type": "object",
+                                "description": "Parameters for the tool",
+                                "additionalProperties": True,
+                            },
+                        },
+                        "required": ["tool", "parameters"],
+                    },
+                }
+            },
+            "required": ["tool_calls"],
+        }
+
+    async def execute(self, args: Dict[str, Any], ctx: ToolContext) -> ToolResult:
+        tool_calls = args.get("tool_calls", [])
+        if not tool_calls:
+            return ToolResult(success=False, output="", error="At least one tool call is required")
+
+        if len(tool_calls) > MAX_CONCURRENT:
+            return ToolResult(
+                success=False,
+                output="",
+                error=f"At most {MAX_CONCURRENT} tool calls allowed, got {len(tool_calls)}",
+            )
+
+        # Block recursive batch
+        names = [t.get("tool") or t.get("tool_name") for t in tool_calls]
+        if BATCH_TOOL_NAME in names:
+            return ToolResult(
+                success=False,
+                output="",
+                error="Recursive batch calls are not allowed",
+            )
+
+        registry = getattr(ctx, "tool_registry", None)
+        if not registry:
+            return ToolResult(
+                success=False,
+                output="",
+                error="Batch tool requires a tool registry in context",
+            )
+
+        async def run_one(tc: Dict[str, Any]) -> ToolResult:
+            name = tc.get("tool") or tc.get("tool_name", "")
+            params = tc.get("parameters") or tc.get("params") or {}
+            tool = registry.get(name)
+            if not tool:
+                return ToolResult(success=False, output="", error=f"Unknown tool: {name}")
+            try:
+                return await tool.execute(params, ctx)
+            except Exception as e:
+                return ToolResult(success=False, output="", error=f"Tool error: {str(e)}")
+
+        tasks = [run_one(t) for t in tool_calls]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        # Convert exceptions to ToolResult
+        out_results: List[ToolResult] = []
+        for i, r in enumerate(results):
+            if isinstance(r, Exception):
+                name = tool_calls[i].get("tool", "?")
+                out_results.append(ToolResult(success=False, output="", error=f"{name}: {str(r)}"))
+            else:
+                out_results.append(r)
+
+        # Format output
+        lines = []
+        for i, (tc, res) in enumerate(zip(tool_calls, out_results)):
+            name = tc.get("tool", "?")
+            status = "OK" if res.success else "FAILED"
+            lines.append(f"[{i + 1}] {name}: {status}")
+            lines.append(res.output if res.success else (res.error or ""))
+            lines.append("")
+        output = "\n".join(lines).strip()
+
+        return ToolResult(
+            success=all(r.success for r in out_results),
+            output=output,
+            error=None if all(r.success for r in out_results) else "One or more tools failed",
+            metadata={
+                "results": [
+                    {"success": r.success, "output": r.output, "error": r.error}
+                    for r in out_results
+                ]
+            },
+        )