relay-code 0.1.0__py3-none-any.whl

tools/__init__.py

@@ -0,0 +1,14 @@
+"""Tools module for the Relay agent."""
+
+from tools.base import Tool, ToolKind, ToolResult, ToolInvocation, ToolConfirmation
+from tools.registry import ToolRegistry, create_default_registery
+
+__all__ = [
+    'Tool',
+    'ToolKind',
+    'ToolResult',
+    'ToolInvocation',
+    'ToolConfirmation',
+    'ToolRegistry',
+    'create_default_registery',
+]

tools/base.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+import abc
+from pathlib import Path
+from pydantic import BaseModel, ValidationError
+from pydantic.json_schema import model_json_schema
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from config.config import Config
+
+class ToolKind(str, Enum):
+    READ = "read"
+    WRITE = "write"
+    SHELL = "shell"
+    NETWORK = "network"
+    MEMORY = "memory"
+    MCP = "mcp"
+    GIT = "git"
+
+@dataclass
+class FileDiff:
+    path: Path
+    old_content: str
+    new_content: str
+
+    is_new_file: bool = False
+    is_deletion: bool = False
+
+    def create_diff(self) -> str:
+
+        import difflib
+
+        old_lines = self.old_content.splitlines(keepends=True)
+        new_lines = self.new_content.splitlines(keepends=True)
+
+        if old_lines and not old_lines[-1].endswith('\n'):
+            old_lines[-1] += '\n'
+        if new_lines and not new_lines[-1].endswith('\n'):
+            new_lines[-1] += '\n'
+        
+        old_name = '/dev/null' if self.is_new_file else str(self.path)
+        new_name = '/dev/null' if self.is_deletion else str(self.path)
+
+        diff = difflib.unified_diff(
+            old_lines,
+            new_lines,
+            fromfile=old_name,
+            tofile=new_name,
+        )
+
+        return "".join(diff)
+
+@dataclass
+class ToolResult:
+    success: bool
+    output: str
+    error: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    # if files are long, we have to truncate.
+    truncated: bool = False
+    diff: FileDiff | None = None
+    exit_code: int | None = None
+
+    @classmethod
+    def error_result(
+        cls,
+        error: str,
+        output: str = "",
+        **kwargs: Any
+    ):
+        return cls(
+            success=False,
+            output=output,
+            error=error,
+            **kwargs,
+        )
+
+    @classmethod
+    def success_result(
+        cls,
+        output: str,
+        **kwargs: Any
+    ):
+        return cls(
+            success=True,
+            output=output,
+            error=None,
+            **kwargs
+        )
+    
+    def to_model_output(self) -> str:
+        if self.success:
+            return self.output
+
+        return f"Error: {self.error}\n\nOutput:\n{self.output}"
+
+
+@dataclass
+class ToolConfirmation:
+    tool_name: str
+    params: dict[str, Any]
+    description: str
+    diff: FileDiff | None = None
+    affected_paths: list[Path] = field(default_factory=list)
+
+@dataclass
+class ToolInvocation:
+    params: dict[str, Any]
+    cwd: Path
+
+class Tool(abc.ABC):
+    name: str = "base_tool"
+    description: str = "Base tool"
+    kind: ToolKind = ToolKind.READ
+
+    def __init__(self, config: Config) -> None:
+        self.config = config
+
+    @property
+    def schema(self) -> dict[str, Any] | type['BaseModel']:
+        raise NotImplementedError("Error: Tool must defined a schema property or an attribute.")
+
+    @abc.abstractmethod
+    async def execute(self, invocation: ToolInvocation) -> ToolResult:
+        pass
+
+    def validate_params(self, params: dict[str, Any]) -> list[str]:
+        schema = self.schema
+        if isinstance(schema, type) and issubclass(schema, BaseModel):
+            try:
+                schema(**params)
+            except ValidationError as e:
+                errors = []
+                for error in e.errors():
+                    loc = ".".join(str(x) for x in error.get("loc", []))
+                    msg = error.get('msg', 'Validation Error')
+                    errors.append(f"Parameter '{loc}': {msg}")
+
+                return errors
+            except Exception as e:
+                return [str(e)]
+
+        return []
+
+    def is_mutating(self, params: dict[str, Any]) -> bool:
+        return self.kind in {ToolKind.WRITE, ToolKind.SHELL, ToolKind.NETWORK, ToolKind.MEMORY}
+
+    async def get_confirmation(self, invocation: ToolInvocation) -> ToolConfirmation | None:
+        if not self.is_mutating(invocation.params):
+            return None
+
+        return ToolConfirmation(
+            tool_name=self.name,
+            params=invocation.params,
+            description=f"Executed: {self.name}"
+        )
+
+    def to_openai_schema(self) -> dict[str, Any]:
+        schema = self.schema
+
+        if isinstance(schema, type) and issubclass(schema, BaseModel):
+            json_schema = model_json_schema(schema, mode='serialization')
+
+            return {
+                'name': self.name,
+                'description': self.description,
+                'parameters': {
+                    'type': 'object',
+                    'properties': json_schema.get('properties', {}),
+                    'required': json_schema.get('required', [])
+                }
+            }
+        if isinstance(schema, dict):
+            result = {
+                'name': self.name,
+                'description': self.description,
+            }
+
+            if 'parameters' in schema:
+                result['parameters'] = schema["parameters"]
+            else:
+                result["parameters"] = schema # type: ignore
+
+            return result
+
+        raise ValueError(f"Error: Invalid schema type for tool: {self.name}: {type(schema)}")

tools/core/__init__.py

@@ -0,0 +1,44 @@
+from tools.core.directories import ListDirectoriesTool
+from tools.core.read import ReadFileTool
+from tools.core.write import WriteFileTool
+from tools.core.edit import EditTool
+from tools.core.shell import ShellTool
+from tools.core.grep import GrepTool
+from tools.core.glob import GlobTool
+from tools.core.todo import TodoTool
+
+from tools.network.search import WebSearchTool
+from tools.network.fetch import WebFetchTool
+
+from tools.memory.memory import MemoryTool
+
+from tools.base import Tool
+
+__all__ = [
+    'ReadFileTool',
+    'WriteFileTool',
+    'EditTool',
+    'ShellTool',
+    'ListDirectoriesTool',
+    'GrepTool',
+    'GlobTool',
+    'WebSearchTool',
+    'WebFetchTool',
+    'TodoTool',
+    'MemoryTool',
+]
+
+def get_all_core_tools() -> list[Tool]:
+    return [
+        ReadFileTool,
+        WriteFileTool,
+        EditTool,
+        ShellTool,
+        ListDirectoriesTool,
+        GrepTool,
+        GlobTool,
+        WebSearchTool,
+        WebFetchTool,
+        TodoTool,
+        MemoryTool,
+    ]

tools/core/directories.py

@@ -0,0 +1,65 @@
+from tools.base import Tool, ToolInvocation, ToolKind, ToolResult
+from pydantic import BaseModel, Field
+
+from utils.paths import resolve_path
+
+class ListDirectoriesParams(BaseModel):
+    path: str = Field(
+        '.',
+        description='Directory path to list (default: current directory)'
+    )
+    
+    include_hidden: bool = Field(
+        False,
+        description="Whether to include hidden files and directories (ex: .git, .env) (default: false)"
+    )
+
+class ListDirectoriesTool(Tool):
+    name = 'list_directories'
+    description = 'List contents of a directory'
+    kind = ToolKind.READ
+    schema = ListDirectoriesParams
+
+    async def execute(self, invocation: ToolInvocation) -> ToolResult:
+        params = ListDirectoriesParams(**invocation.params)
+
+        dir_path = resolve_path(invocation.cwd, params.path)\
+        
+        if not dir_path.exists() or not dir_path.is_dir():
+            return ToolResult.error_result(
+                f'Directory does not exist: {dir_path}'
+            )
+        try:
+            items = sorted(dir_path.iterdir(), key=lambda p: (not p.is_dir(), p.name.lower()))
+        except Exception as e:
+            return ToolResult.error_result(
+                f'Error listing directory: {e}'
+        )
+
+        if not params.include_hidden:
+            items = [item for item in items if not item.name.startswith(".")]
+        
+        if not items:
+            return ToolResult.success_result(
+                'Directory is empty',
+                metadata = {
+                    'path': str(dir_path),
+                    'entries': 0
+                }
+            )
+        
+        lines = []
+
+        for item in items:
+            if item.is_dir():
+                lines.append(f'{item.name}/')
+            else:
+                lines.append(item.name)
+        
+        return ToolResult.success_result(
+            '\n'.join(lines),
+            metadata = {
+                'path': str(dir_path),
+                'entries': len(items)
+            }
+        )

tools/core/edit.py

@@ -0,0 +1,162 @@
+from pathlib import Path
+
+from tools.base import FileDiff, Tool, ToolInvocation, ToolKind, ToolResult
+from pydantic import BaseModel, Field
+
+from utils.paths import ensure_parent_dir, resolve_path
+
+class EditParams(BaseModel):
+    path: str = Field(
+        ...,
+        description='Path to the file to edit (relative to working directory) or an absolute path.'
+    )
+    old_string: str = Field(
+        "",
+        description='The exact text to find and replace and must match excatly including all whitespace and indentation, for new files this should be empty'
+    )
+    new_string: str = Field(
+        ...,
+        description='The text to replace old_string with. Can be empty to delete.'
+    )
+    replace_all: bool = Field(
+        False,
+        description='Replace all occurrences of old_string default is false'
+    )
+
+class EditTool(Tool):
+    name = "edit"
+    description = (
+        "Edit a file by replacing text, the old_string varaible must match exactly"
+        "( including whitespace and indentation ) and must be unique in the file"
+        "unless replace_all is true, use thsi for precise, surgical edits"
+        "For creating new files or complete rewrites, use write instead"
+    )
+    kind = ToolKind.WRITE
+    schema = EditParams # type: ignore
+
+    async def execute(
+            self, 
+            invocation: ToolInvocation
+    ) -> ToolResult:
+
+        params = EditParams(**invocation.params)
+        path = resolve_path(invocation.cwd, params.path)
+
+        if not path.exists():
+            if params.old_string:
+                return ToolResult.error_result(
+                    f'File does not exist: {path}. To create a new file, use an empty old_string.'
+                )
+
+            ensure_parent_dir(path)
+            path.write_text(params.new_string, encoding='utf-8')
+
+            line_count = len(params.new_string.splitlines())
+
+            return ToolResult.success_result(
+                f'Created: {path} {line_count} lines',
+                diff=FileDiff(
+                    path=path,
+                    old_content="",
+                    new_content=params.new_string,
+                    is_new_file=True,
+                ),
+                metadata = {
+                    'path': str(path),
+                    'is_new_file': True,
+                    'lines': line_count
+                }
+            )
+        
+        old_content = path.read_text(encoding='utf-8')
+
+        if not params.old_string:
+            return ToolResult.error_result(
+                'old_string is empty but file exists. Provide old_string to edit, or use write to overwrite the file.'
+            )
+        
+        occurrence_count = old_content.count(params.old_string)
+
+        if occurrence_count == 0:
+            return self._no_match_error(params.old_string, old_content, path)
+        
+        if occurrence_count > 1 and not params.replace_all:
+            return ToolResult.error_result(
+                f"old_string found {occurrence_count} times in {path}. "
+                f"Either: \n"
+                f"1. Provide more context to make the match unique or\n"
+                f"2. Set replace_all=true to replace all occurrences",
+                metadata={
+                    "occurence_count": occurrence_count,
+                },
+            )
+
+        if params.replace_all:
+            new_content = old_content.replace(params.old_string, params.new_string)
+            replace_count = occurrence_count
+        else:
+            new_content = old_content.replace(params.old_string, params.new_string, 1)
+            replace_count = 1
+
+        if new_content == old_content:
+            return ToolResult.error_result(
+                "No change made - old_string equals new_string"
+            )
+
+        try:
+            path.write_text(new_content, encoding="utf-8")
+        except IOError as e:
+            return ToolResult.error_result(f"failed to write file: {e}")
+
+        old_lines = len(old_content.splitlines())
+        new_lines = len(new_content.splitlines())
+        line_diff = new_lines - old_lines
+
+        diff_msg = ""
+
+        if line_diff > 0:
+            diff_msg = f" (+{line_diff} lines)"
+        elif line_diff < 0:
+            diff_msg = f" ({line_diff} lines)"
+
+        return ToolResult.success_result(
+            f"Edited {path}: replaced {replace_count} occurrence(s){diff_msg}",
+            diff=FileDiff(path=path, old_content=old_content, new_content=new_content),
+            metadata={
+                "path": str(path),
+                "replaced_count": replace_count,
+                "line_diff": line_diff,
+            },
+        )
+
+    def _no_match_error(self, old_string: str, content: str, path: Path) -> ToolResult:
+        lines = content.splitlines()
+
+        partial_matches = []
+        search_terms = old_string.split()[:5]
+
+        if search_terms:
+            first_term = search_terms[0]
+            for i, line in enumerate(lines, 1):
+                if first_term in line:
+                    partial_matches.append((i, line.strip()[:80]))
+                    if len(partial_matches) >= 3:
+                        break
+
+        error_msg = f"old_string not found in {path}."
+
+        if partial_matches:
+            error_msg += "\n\nPossible similar lines:"
+            for line_num, line_preview in partial_matches:
+                error_msg += f"\n  Line {line_num}: {line_preview}"
+            error_msg += "\n\nMake sure old_string matches exactly (including whitespace and indentation)."
+        else:
+            error_msg += (
+                " Make sure the text matches exactly, including:\n"
+                "- All whitespace and indentation\n"
+                "- Line breaks\n"
+                "- Any invisible characters\n"
+                "Try re-reading the file using read tool and then editing."
+            )
+
+        return ToolResult.error_result(error_msg)

tools/core/glob.py

@@ -0,0 +1,92 @@
+import os
+from pathlib import Path
+
+from tools.base import Tool, ToolInvocation, ToolKind, ToolResult
+from pydantic import BaseModel, Field
+
+from utils.paths import is_binary_file, resolve_path
+
+class GlobParams(BaseModel):
+
+    pattern: str = Field(
+        ...,
+        description='Glob pattern to match for.'
+    )
+
+    path: str = Field(
+        '.',
+        description='Directory path to search in (default: current directory)'
+    )
+
+class GlobTool(Tool):
+    name = 'glob'
+    description = 'Find files matching a glob pattern. Supports ** for recursive search and matching.'
+    kind = ToolKind.READ
+    schema = GlobParams # type: ignore
+
+    async def execute(self, invocation: ToolInvocation) -> ToolResult:
+        params = GlobParams(**invocation.params)
+
+        search_path = resolve_path(invocation.cwd, params.path)\
+        
+        if not search_path.exists() or not search_path.is_dir():
+            return ToolResult.error_result(
+                f'Directory does not exist: {search_path}'
+            )
+        try:
+            matches = list(search_path.glob(params.pattern))
+            matches = [p for p in matches if p.is_file()]
+        except Exception as e:
+            return ToolResult.error_result(
+                f'Error searching: {e}'
+        )
+
+        output_lines: list = []
+
+        for file_path in matches[:1000]:
+
+            try:
+                relative_path = file_path.relative_to(
+                    invocation.cwd
+                )
+            except Exception:
+                relative_path = file_path
+        
+            output_lines.append(str(relative_path))
+
+        if len(matches) > 1000:
+            output_lines.append(f"...(limited to 1000 results)")
+        return ToolResult.success_result(
+            '\n'.join(output_lines),
+            metadata = {
+                'path': str(search_path),
+                'matches': len(matches),
+            }
+        )
+    
+    def _find_files(self, search_path: Path) -> list[Path]:
+
+        files = []
+        
+        for root, dirs, filenames in os.walk(search_path):
+            dirs[:] = [
+                d for d in dirs if d not in 
+            {
+                'node_modules',
+                '__pycache__',
+                '.git',
+                '.venv',
+                'venv',
+            }
+        ]
+            for filename in filenames:
+                if filename.startswith('.'):
+                    continue
+                
+                file_path = Path(root) / filename
+                if not is_binary_file(file_path):
+                    files.append(file_path)
+                    if len(files) >= 500:
+                        return files
+        
+        return files

tools/core/grep.py

@@ -0,0 +1,128 @@
+import os
+from pathlib import Path
+import re
+
+from tools.base import Tool, ToolInvocation, ToolKind, ToolResult
+from pydantic import BaseModel, Field
+
+from utils.paths import is_binary_file, resolve_path
+
+class GrepParams(BaseModel):
+
+    pattern: str = Field(
+        ...,
+        description='Regular expression pattern to search for.'
+    )
+
+    path: str = Field(
+        '.',
+        description='File or Directory path to search in (default: current directory)'
+    )
+    
+    case_insensitive: bool = Field(
+        False,
+        description="Case-insensitive search (default: false)"
+    )
+
+class GrepTool(Tool):
+    name = 'grep'
+    description = 'Searching for a regex pattern in the file content and will return the matching lines with file paths and line numbers.'
+    kind = ToolKind.READ
+    schema = GrepParams
+
+    async def execute(self, invocation: ToolInvocation) -> ToolResult:
+        params = GrepParams(**invocation.params)
+
+        search_path = resolve_path(invocation.cwd, params.path)\
+        
+        if not search_path.exists() or not search_path.is_dir():
+            return ToolResult.error_result(
+                f'Path does not exist: {search_path}'
+            )
+        try:
+            flags = re.IGNORECASE if params.case_insensitive else 0
+            pattern = re.compile(params.pattern, flags)
+        except re.error as e:
+            return ToolResult.error_result(
+                f'Invalid regex pattern: {e}'
+        )
+
+        if search_path.is_dir():
+            files = self._find_files(search_path)
+        else:
+            files = [search_path]
+        
+        output_lines: list = []
+        matches: int = 0
+
+        for file_path in files:
+
+            try:
+                content = file_path.read_text(
+                    encoding='utf-8'
+                )
+            except Exception:
+                continue
+        
+            lines = content.splitlines()
+            file_matches = False
+
+            for i, line in enumerate(lines, start=1):
+                if pattern.search(line):
+                    matches += 1
+                    if not file_matches:
+                        relative_path = file_path.relative_to(invocation.cwd)
+                        output_lines.append(f'┈┈ {relative_path} ┈┈')
+                        file_matches = True
+                    
+                    output_lines.append(f"{i}:{line}")
+            
+            if file_matches:
+                output_lines.append("")
+        
+        if not output_lines:
+
+            return ToolResult.success_result(
+                f'No matches found for pattern: "{params.pattern}"',
+                metadata = {
+                'path': str(search_path),
+                'matches': 0,
+                'files_searched': len(files)
+                }
+            )
+
+        return ToolResult.success_result(
+            '\n'.join(output_lines),
+            metadata = {
+                'path': str(search_path),
+                'matches': matches,
+                'files_searched': len(files)
+            }
+        )
+    
+    def _find_files(self, search_path: Path) -> list[Path]:
+
+        files = []
+        
+        for root, dirs, filenames in os.walk(search_path):
+            dirs[:] = [
+                d for d in dirs if d not in 
+            {
+                'node_modules',
+                '__pycache__',
+                '.git',
+                '.venv',
+                'venv',
+            }
+        ]
+            for filename in filenames:
+                if filename.startswith('.'):
+                    continue
+                
+                file_path = Path(root) / filename
+                if not is_binary_file(file_path):
+                    files.append(file_path)
+                    if len(files) >= 500:
+                        return files
+        
+        return files