aloop 0.1.1__py3-none-any.whl

tools/explore.py

@@ -0,0 +1,254 @@
+"""Exploration tool for parallel context gathering."""
+
+import asyncio
+from typing import TYPE_CHECKING, Any, Dict, List
+
+from llm import LLMMessage
+
+from .base import BaseTool
+
+if TYPE_CHECKING:
+    from agent.base import BaseAgent
+
+
+# General exploration prompt supporting both code and web exploration
+GENERAL_EXPLORER_PROMPT = """<role>
+You are an exploration agent gathering information for a task.
+Your job is to discover relevant information WITHOUT making any changes.
+</role>
+
+<exploration_focus>
+Aspect: {aspect}
+Description: {description}
+</exploration_focus>
+
+<instructions>
+1. Use available information-gathering tools:
+   - Code exploration: glob_files, grep_content, read_file, code_navigator
+   - Web exploration: web_search, web_fetch
+
+2. Focus ONLY on the specified exploration aspect
+3. Report your findings concisely and specifically
+4. Do NOT make any changes to files
+5. Do NOT try to solve problems - just gather information
+
+Your output should be a structured summary of what you discovered.
+</instructions>
+
+Explore and report your findings:"""
+
+
+class ExploreTool(BaseTool):
+    """Tool for parallel exploration of code and web resources.
+
+    This tool enables the main agent to gather context through parallel
+    exploration sub-agents. Each exploration task runs in isolation and
+    returns a compressed summary.
+
+    Key features:
+    - Parallel execution of multiple exploration tasks
+    - Code exploration: file structure, patterns, dependencies
+    - Web exploration: search results, webpage content
+    - Compressed summaries to preserve context space
+    """
+
+    # Configuration
+    MAX_PARALLEL_EXPLORATIONS = 3
+    MAX_RESULT_CHARS = 1500
+
+    # Allowed tools for exploration (read-only + network)
+    EXPLORATION_TOOLS = {
+        "glob_files",
+        "grep_content",
+        "read_file",
+        "code_navigator",
+        "web_search",
+        "web_fetch",
+    }
+
+    def __init__(self, agent: "BaseAgent"):
+        """Initialize exploration tool.
+
+        Args:
+            agent: The parent agent instance that will run explorations
+        """
+        self.agent = agent
+
+    @property
+    def name(self) -> str:
+        return "explore_context"
+
+    @property
+    def description(self) -> str:
+        return """Gather context through parallel exploration of code and web resources.
+
+Use this tool when you need to:
+- Explore code structure, patterns, or dependencies
+- Search the web for documentation, APIs, or solutions
+- Gather information from multiple sources in parallel
+- Understand a codebase before making changes
+
+DO NOT use this for:
+- Making changes to files (use regular edit tools)
+- Simple, single-file reads (use read_file directly)
+- Tasks that don't require exploration
+
+Input parameters:
+- tasks (required): Array of exploration tasks, each with:
+  - aspect: Brief name of what to explore (e.g., "file_structure", "api_docs")
+  - description: Detailed description of what to find
+
+The tool runs explorations in parallel and returns compressed summaries."""
+
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        return {
+            "tasks": {
+                "type": "array",
+                "description": "List of exploration tasks to run in parallel",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "aspect": {
+                            "type": "string",
+                            "description": "Brief name of the exploration aspect",
+                        },
+                        "description": {
+                            "type": "string",
+                            "description": "Detailed description of what to explore",
+                        },
+                    },
+                    "required": ["aspect", "description"],
+                },
+            }
+        }
+
+    def to_anthropic_schema(self) -> Dict[str, Any]:
+        """Convert to Anthropic tool schema format."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "input_schema": {
+                "type": "object",
+                "properties": self.parameters,
+                "required": ["tasks"],
+            },
+        }
+
+    async def execute(self, tasks: List[Dict[str, str]]) -> str:
+        """Execute parallel exploration tasks.
+
+        Args:
+            tasks: List of exploration tasks with 'aspect' and 'description' keys
+
+        Returns:
+            Combined exploration results as a string
+        """
+        if not tasks:
+            return "Error: No exploration tasks provided"
+
+        # Limit the number of parallel explorations
+        tasks = tasks[: self.MAX_PARALLEL_EXPLORATIONS]
+
+        # Get exploration-only tools
+        all_tools = self.agent.tool_executor.get_tool_schemas()
+        exploration_tools = [
+            t
+            for t in all_tools
+            if t.get("name") in self.EXPLORATION_TOOLS
+            or t.get("function", {}).get("name") in self.EXPLORATION_TOOLS
+        ]
+
+        # Run explorations in parallel
+        results = await self._run_parallel_explorations(tasks, exploration_tools)
+
+        # Format and return results
+        return self._format_results(results)
+
+    async def _run_parallel_explorations(
+        self, tasks: List[Dict[str, str]], tools: List[Dict[str, Any]]
+    ) -> Dict[str, str]:
+        """Run multiple exploration tasks in parallel.
+
+        Args:
+            tasks: List of exploration tasks
+            tools: Available exploration tools
+
+        Returns:
+            Dict mapping aspect names to results
+        """
+
+        async def run_single(task: Dict[str, str]) -> tuple:
+            aspect = task.get("aspect", "unknown")
+            description = task.get("description", "")
+            try:
+                result = await self._run_exploration(aspect, description, tools)
+                return aspect, result
+            except asyncio.CancelledError:
+                raise
+            except Exception as e:
+                return aspect, f"Exploration failed: {str(e)}"
+
+        # Use TaskGroup for parallel execution
+        # Since run_single catches all exceptions internally (except CancelledError),
+        # any ExceptionGroup raised here indicates cancellation which should propagate
+        results = {}
+        async with asyncio.TaskGroup() as tg:
+            task_list = [tg.create_task(run_single(t)) for t in tasks]
+
+        for task in task_list:
+            aspect, result = task.result()
+            results[aspect] = result
+
+        return results
+
+    async def _run_exploration(
+        self, aspect: str, description: str, tools: List[Dict[str, Any]]
+    ) -> str:
+        """Run a single exploration using isolated mini-loop.
+
+        Args:
+            aspect: The aspect being explored
+            description: Description of the exploration focus
+            tools: Available exploration tools
+
+        Returns:
+            Exploration result string
+        """
+        # Build exploration prompt
+        prompt = GENERAL_EXPLORER_PROMPT.format(aspect=aspect, description=description)
+
+        messages = [LLMMessage(role="user", content=prompt)]
+
+        # Run exploration in isolated context
+        result = await self.agent._react_loop(
+            messages=messages,
+            tools=tools,
+            use_memory=False,  # Don't use main memory
+            save_to_memory=False,  # Don't save to main memory
+        )
+
+        return result
+
+    def _format_results(self, results: Dict[str, str]) -> str:
+        """Format exploration results into a combined summary.
+
+        Args:
+            results: Dict mapping aspect names to result strings
+
+        Returns:
+            Formatted combined results
+        """
+        if not results:
+            return "No exploration results."
+
+        parts = ["# Exploration Results\n"]
+
+        for aspect, result in results.items():
+            # Truncate long results
+            if len(result) > self.MAX_RESULT_CHARS:
+                result = result[: self.MAX_RESULT_CHARS] + "... [truncated]"
+
+            parts.append(f"## {aspect}\n{result}\n")
+
+        return "\n".join(parts)

tools/file_ops.py

@@ -0,0 +1,150 @@
+"""File operation tools for reading, writing, and searching files."""
+
+import asyncio
+import glob
+import os
+from typing import Any, Dict
+
+import aiofiles
+import aiofiles.os
+
+from .base import BaseTool
+
+
+class FileReadTool(BaseTool):
+    """Read contents of a file from the filesystem."""
+
+    @property
+    def name(self) -> str:
+        return "read_file"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Read contents of a file. For large files, use offset and limit "
+            "parameters to read specific portions."
+        )
+
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        return {
+            "file_path": {
+                "type": "string",
+                "description": "Path to the file to read",
+            },
+            "offset": {
+                "type": "integer",
+                "description": "Line number to start from (0-indexed). Default: 0",
+            },
+            "limit": {
+                "type": "integer",
+                "description": "Maximum number of lines to read. If not set, reads entire file.",
+            },
+        }
+
+    async def execute(self, file_path: str, offset: int = 0, limit: int = None) -> str:
+        """Read file with optional pagination."""
+        try:
+            # Pre-check file size
+            file_size = await aiofiles.os.path.getsize(file_path)
+            estimated_tokens = file_size // self.CHARS_PER_TOKEN
+
+            # If file too large and no pagination, return error
+            if estimated_tokens > self.MAX_TOKENS and limit is None:
+                return (
+                    f"Error: File content (~{estimated_tokens} tokens) exceeds "
+                    f"maximum allowed tokens ({self.MAX_TOKENS}). Please use offset "
+                    f"and limit parameters to read specific portions of the file, "
+                    f"or use grep_content to search for specific content."
+                )
+
+            async with aiofiles.open(file_path, encoding="utf-8") as f:
+                if limit is None:
+                    return await f.read()
+                # Pagination mode
+                lines = await f.readlines()
+                total_lines = len(lines)
+                selected = lines[offset : offset + limit]
+                result = "".join(selected)
+                # Add context about total lines
+                if offset > 0 or offset + limit < total_lines:
+                    result = f"[Lines {offset+1}-{min(offset+limit, total_lines)} of {total_lines}]\n{result}"
+                return result
+
+        except FileNotFoundError:
+            return f"Error: File '{file_path}' not found"
+        except Exception as e:
+            return f"Error reading file: {str(e)}"
+
+
+class FileWriteTool(BaseTool):
+    """Write content to a file (creates or overwrites)."""
+
+    @property
+    def name(self) -> str:
+        return "write_file"
+
+    @property
+    def description(self) -> str:
+        return "Write content to a file (creates or overwrites)"
+
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        return {
+            "file_path": {
+                "type": "string",
+                "description": "Path where to write the file",
+            },
+            "content": {
+                "type": "string",
+                "description": "Content to write to the file",
+            },
+        }
+
+    async def execute(self, file_path: str, content: str) -> str:
+        """Write content to file."""
+        try:
+            # Create directory if it doesn't exist
+            await aiofiles.os.makedirs(os.path.dirname(file_path) or ".", exist_ok=True)
+            async with aiofiles.open(file_path, "w", encoding="utf-8") as f:
+                await f.write(content)
+            return f"Successfully wrote to {file_path}"
+        except Exception as e:
+            return f"Error writing file: {str(e)}"
+
+
+class FileSearchTool(BaseTool):
+    """Search for files matching a pattern in a directory."""
+
+    @property
+    def name(self) -> str:
+        return "search_files"
+
+    @property
+    def description(self) -> str:
+        return "Search for files matching a pattern in a directory"
+
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        return {
+            "directory": {
+                "type": "string",
+                "description": "Directory to search in (default: current directory)",
+            },
+            "pattern": {
+                "type": "string",
+                "description": "File name pattern (e.g., '*.py', 'test_*')",
+            },
+        }
+
+    async def execute(self, directory: str = ".", pattern: str = "*") -> str:
+        """Search for files matching pattern."""
+        try:
+            search_path = os.path.join(directory, "**", pattern)
+            files = await asyncio.to_thread(lambda: glob.glob(search_path, recursive=True))
+            if files:
+                return "\n".join(files)
+            else:
+                return "No files found matching pattern"
+        except Exception as e:
+            return f"Error searching files: {str(e)}"