vibecore 0.2.0__py3-none-any.whl

vibecore/tools/file/__init__.py

@@ -0,0 +1,5 @@
+"""File-related tools for Vibecore agents."""
+
+from .tools import edit, multi_edit, read, write
+
+__all__ = ["edit", "multi_edit", "read", "write"]

vibecore/tools/file/executor.py

@@ -0,0 +1,282 @@
+"""File reading execution logic."""
+
+from typing import Any
+
+from .utils import PathValidationError, format_line_with_number, validate_file_path
+
+
+async def read_file(file_path: str, offset: int | None = None, limit: int | None = None) -> str:
+    """Read a file and return its contents in cat -n format.
+
+    Args:
+        file_path: The path to the file to read
+        offset: The line number to start reading from (1-based)
+        limit: The maximum number of lines to read
+
+    Returns:
+        The file contents with line numbers, or an error message
+    """
+    try:
+        # Validate the file path
+        validated_path = validate_file_path(file_path)
+
+        # Check if file exists
+        if not validated_path.exists():
+            return f"Error: File does not exist: {file_path}"
+
+        # Check if it's a file (not a directory)
+        if not validated_path.is_file():
+            return f"Error: Path is not a file: {file_path}"
+
+        # Check for Jupyter notebooks
+        if validated_path.suffix == ".ipynb":
+            return "Error: For Jupyter notebooks (.ipynb files), please use the NotebookRead tool instead"
+
+        # Set defaults
+        if offset is None:
+            offset = 1  # Line numbers start at 1
+        if limit is None:
+            limit = 2000
+
+        # Validate offset and limit
+        if offset < 1:
+            return "Error: Offset must be 1 or greater (line numbers start at 1)"
+        if limit < 1:
+            return "Error: Limit must be 1 or greater"
+
+        # Read the file
+        try:
+            with validated_path.open("r", encoding="utf-8", errors="replace") as f:
+                # Skip to the offset
+                for _ in range(offset - 1):
+                    line = f.readline()
+                    if not line:
+                        return f"Error: Offset {offset} is beyond the end of file"
+
+                # Read the requested lines
+                lines = []
+                line_num = offset
+                for _ in range(limit):
+                    line = f.readline()
+                    if not line:
+                        break
+                    lines.append(format_line_with_number(line_num, line))
+                    line_num += 1
+
+                # Handle empty file or no content in range
+                if not lines:
+                    if offset == 1:
+                        # Empty file
+                        return "<system-reminder>Warning: The file exists but has empty contents</system-reminder>"
+                    else:
+                        return f"Error: No content found starting from line {offset}"
+
+                return "\n".join(lines)
+
+        except PermissionError:
+            return f"Error: Permission denied reading file: {file_path}"
+        except Exception as e:
+            return f"Error reading file: {e}"
+
+    except PathValidationError as e:
+        return f"Error: {e}"
+    except Exception as e:
+        return f"Error: Unexpected error reading file: {e}"
+
+
+async def edit_file(file_path: str, old_string: str, new_string: str, replace_all: bool = False) -> str:
+    """Edit a file by replacing strings.
+
+    Args:
+        file_path: The path to the file to edit
+        old_string: The text to replace
+        new_string: The text to replace it with
+        replace_all: Replace all occurrences (default: False)
+
+    Returns:
+        Success message or error message
+    """
+    try:
+        # Validate the file path
+        validated_path = validate_file_path(file_path)
+
+        # Check if file exists
+        if not validated_path.exists():
+            return f"Error: File does not exist: {file_path}"
+
+        # Check if it's a file (not a directory)
+        if not validated_path.is_file():
+            return f"Error: Path is not a file: {file_path}"
+
+        # Check for Jupyter notebooks
+        if validated_path.suffix == ".ipynb":
+            return "Error: For Jupyter notebooks (.ipynb files), please use the NotebookEdit tool instead"
+
+        # Validate old_string != new_string
+        if old_string == new_string:
+            return "Error: old_string and new_string cannot be the same"
+
+        # Read the file
+        try:
+            with validated_path.open("r", encoding="utf-8") as f:
+                content = f.read()
+
+            # Check if old_string exists in the file
+            occurrences = content.count(old_string)
+            if occurrences == 0:
+                return f"Error: String not found in file: {old_string!r}"
+
+            # Check uniqueness if not replace_all
+            if not replace_all and occurrences > 1:
+                return (
+                    f"Error: Multiple occurrences ({occurrences}) of old_string found. "
+                    f"Use replace_all=True or provide more context to make the string unique"
+                )
+
+            # Perform the replacement
+            if replace_all:
+                new_content = content.replace(old_string, new_string)
+                replaced = occurrences
+            else:
+                new_content = content.replace(old_string, new_string, 1)
+                replaced = 1
+
+            # Write the file back
+            with validated_path.open("w", encoding="utf-8") as f:
+                f.write(new_content)
+
+            return f"Successfully replaced {replaced} occurrence(s) in {file_path}"
+
+        except PermissionError:
+            return f"Error: Permission denied accessing file: {file_path}"
+        except Exception as e:
+            return f"Error editing file: {e}"
+
+    except PathValidationError as e:
+        return f"Error: {e}"
+    except Exception as e:
+        return f"Error: Unexpected error editing file: {e}"
+
+
+async def multi_edit_file(file_path: str, edits: list[dict[str, Any]]) -> str:
+    """Edit a file by applying multiple replacements sequentially.
+
+    Args:
+        file_path: The path to the file to edit
+        edits: List of edit operations, each containing old_string, new_string, and optional replace_all
+
+    Returns:
+        Success message or error message
+    """
+    try:
+        # Validate the file path
+        validated_path = validate_file_path(file_path)
+
+        # Check if file exists
+        if not validated_path.exists():
+            return f"Error: File does not exist: {file_path}"
+
+        # Check if it's a file (not a directory)
+        if not validated_path.is_file():
+            return f"Error: Path is not a file: {file_path}"
+
+        # Check for Jupyter notebooks
+        if validated_path.suffix == ".ipynb":
+            return "Error: For Jupyter notebooks (.ipynb files), please use the NotebookEdit tool instead"
+
+        # Read the file
+        try:
+            with validated_path.open("r", encoding="utf-8") as f:
+                content = f.read()
+
+            # Apply each edit sequentially
+            total_replacements = 0
+            for i, edit in enumerate(edits):
+                old_string = str(edit["old_string"])
+                new_string = str(edit["new_string"])
+                replace_all = bool(edit.get("replace_all", False))
+
+                # Validate old_string != new_string
+                if old_string == new_string:
+                    return f"Error: Edit {i + 1}: old_string and new_string cannot be the same"
+
+                # Check if old_string exists in the current content
+                occurrences = content.count(old_string)
+                if occurrences == 0:
+                    return f"Error: Edit {i + 1}: String not found: {old_string!r}"
+
+                # Check uniqueness if not replace_all
+                if not replace_all and occurrences > 1:
+                    return (
+                        f"Error: Edit {i + 1}: Multiple occurrences ({occurrences}) of old_string found. "
+                        f"Use replace_all=True or provide more context to make the string unique"
+                    )
+
+                # Perform the replacement
+                if replace_all:
+                    content = content.replace(old_string, new_string)
+                    total_replacements += occurrences
+                else:
+                    content = content.replace(old_string, new_string, 1)
+                    total_replacements += 1
+
+            # Write the file back
+            with validated_path.open("w", encoding="utf-8") as f:
+                f.write(content)
+
+            return (
+                f"Successfully applied {len(edits)} edits with {total_replacements} total replacements in {file_path}"
+            )
+
+        except PermissionError:
+            return f"Error: Permission denied accessing file: {file_path}"
+        except Exception as e:
+            return f"Error editing file: {e}"
+
+    except PathValidationError as e:
+        return f"Error: {e}"
+    except Exception as e:
+        return f"Error: Unexpected error editing file: {e}"
+
+
+async def write_file(file_path: str, content: str) -> str:
+    """Write content to a file.
+
+    Args:
+        file_path: The path to the file to write
+        content: The content to write to the file
+
+    Returns:
+        Success message or error message
+    """
+    try:
+        # Validate the file path
+        validated_path = validate_file_path(file_path)
+
+        # Check if it's a directory
+        if validated_path.exists() and validated_path.is_dir():
+            return f"Error: Path is a directory: {file_path}"
+
+        # Check for Jupyter notebooks
+        if validated_path.suffix == ".ipynb":
+            return "Error: For Jupyter notebooks (.ipynb files), please use the NotebookEdit tool instead"
+
+        # Create parent directories if they don't exist
+        validated_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Write the file
+        try:
+            with validated_path.open("w", encoding="utf-8") as f:
+                f.write(content)
+
+            return f"Successfully wrote {len(content)} bytes to {file_path}"
+
+        except PermissionError:
+            return f"Error: Permission denied writing file: {file_path}"
+        except Exception as e:
+            return f"Error writing file: {e}"
+
+    except PathValidationError as e:
+        return f"Error: {e}"
+    except Exception as e:
+        return f"Error: Unexpected error writing file: {e}"

vibecore/tools/file/tools.py

@@ -0,0 +1,184 @@
+"""File reading tool for Vibecore agents."""
+
+from agents import RunContextWrapper, function_tool
+from pydantic import BaseModel
+
+from vibecore.context import VibecoreContext
+
+from .executor import edit_file, multi_edit_file, read_file, write_file
+
+
+class EditOperation(BaseModel):
+    """Represents a single edit operation."""
+
+    old_string: str
+    new_string: str
+    replace_all: bool = False
+
+
+@function_tool
+async def read(
+    ctx: RunContextWrapper[VibecoreContext],
+    file_path: str,
+    offset: int | None = None,
+    limit: int | None = None,
+) -> str:
+    """Reads a file from the local filesystem. You can access any file directly by using this tool.
+    Assume this tool is able to read all files on the machine. If the User provides a path to a file assume
+    that path is valid. It is okay to read a file that does not exist; an error will be returned.
+
+    Usage:
+    - The file_path parameter must be an absolute path, not a relative path
+    - By default, it reads up to 2000 lines starting from the beginning of the file
+    - You can optionally specify a line offset and limit (especially handy for long files), but it's
+      recommended to read the whole file by not providing these parameters
+    - Any lines longer than 2000 characters will be truncated
+    - Results are returned using cat -n format, with line numbers starting at 1
+    - For Jupyter notebooks (.ipynb files), use the NotebookRead instead
+    - You have the capability to call multiple tools in a single response. It is always better to
+      speculatively read multiple files as a batch that are potentially useful.
+    - If you read a file that exists but has empty contents you will receive a system reminder warning
+      in place of file contents.
+
+    Args:
+        ctx: The run context wrapper
+        file_path: The absolute path to the file to read
+        offset: The line number to start reading from. Only provide if the file is too large to read at once
+        limit: The number of lines to read. Only provide if the file is too large to read at once.
+
+    Returns:
+        The file contents with line numbers in cat -n format, or an error message
+    """
+    return await read_file(file_path, offset, limit)
+
+
+@function_tool
+async def edit(
+    ctx: RunContextWrapper[VibecoreContext],
+    file_path: str,
+    old_string: str,
+    new_string: str,
+    replace_all: bool = False,
+) -> str:
+    """Performs exact string replacements in files.
+
+    Usage:
+    - You must use your `Read` tool at least once in the conversation before editing. This tool will error if you
+      attempt an edit without reading the file.
+    - When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears
+      AFTER the line number prefix. The line number prefix format is: spaces + line number + tab. Everything after
+      that tab is the actual file content to match. Never include any part of the line number prefix in the
+      old_string or new_string.
+    - ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+    - Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
+    - The edit will FAIL if `old_string` is not unique in the file. Either provide a larger string with more
+      surrounding context to make it unique or use `replace_all` to change every instance of `old_string`.
+    - Use `replace_all` for replacing and renaming strings across the file. This parameter is useful if you want to
+      rename a variable for instance.
+
+    Args:
+        ctx: The run context wrapper
+        file_path: The absolute path to the file to modify
+        old_string: The text to replace
+        new_string: The text to replace it with (must be different from old_string)
+        replace_all: Replace all occurences of old_string (default false)
+
+    Returns:
+        Success message or error message
+    """
+    return await edit_file(file_path, old_string, new_string, replace_all)
+
+
+@function_tool
+async def multi_edit(
+    ctx: RunContextWrapper[VibecoreContext],
+    file_path: str,
+    edits: list[EditOperation],
+) -> str:
+    """This is a tool for making multiple edits to a single file in one operation. It is built on top of the Edit
+    tool and allows you to perform multiple find-and-replace operations efficiently. Prefer this tool over the Edit
+    tool when you need to make multiple edits to the same file.
+
+    Before using this tool:
+
+    1. Use the Read tool to understand the file's contents and context
+    2. Verify the directory path is correct
+
+    To make multiple file edits, provide the following:
+    1. file_path: The absolute path to the file to modify (must be absolute, not relative)
+    2. edits: An array of edit operations to perform, where each edit contains:
+       - old_string: The text to replace (must match the file contents exactly, including all whitespace and
+         indentation)
+       - new_string: The edited text to replace the old_string
+       - replace_all: Replace all occurences of old_string. This parameter is optional and defaults to false.
+
+    IMPORTANT:
+    - All edits are applied in sequence, in the order they are provided
+    - Each edit operates on the result of the previous edit
+    - All edits must be valid for the operation to succeed - if any edit fails, none will be applied
+    - This tool is ideal when you need to make several changes to different parts of the same file
+    - For Jupyter notebooks (.ipynb files), use the NotebookEdit instead
+
+    CRITICAL REQUIREMENTS:
+    1. All edits follow the same requirements as the single Edit tool
+    2. The edits are atomic - either all succeed or none are applied
+    3. Plan your edits carefully to avoid conflicts between sequential operations
+
+    WARNING:
+    - The tool will fail if edits.old_string doesn't match the file contents exactly (including whitespace)
+    - The tool will fail if edits.old_string and edits.new_string are the same
+    - Since edits are applied in sequence, ensure that earlier edits don't affect the text that later edits are
+      trying to find
+
+    When making edits:
+    - Ensure all edits result in idiomatic, correct code
+    - Do not leave the code in a broken state
+    - Always use absolute file paths (starting with /)
+    - Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
+    - Use replace_all for replacing and renaming strings across the file. This parameter is useful if you want to
+      rename a variable for instance.
+
+    If you want to create a new file, use:
+    - A new file path, including dir name if needed
+    - First edit: empty old_string and the new file's contents as new_string
+    - Subsequent edits: normal edit operations on the created content
+
+    Args:
+        ctx: The run context wrapper
+        file_path: The absolute path to the file to modify
+        edits: Array of edit operations to perform sequentially on the file
+
+    Returns:
+        Success message or error message
+    """
+    # Convert EditOperation objects to dictionaries
+    edit_dicts = [edit.model_dump() for edit in edits]
+    return await multi_edit_file(file_path, edit_dicts)
+
+
+@function_tool
+async def write(
+    ctx: RunContextWrapper[VibecoreContext],
+    file_path: str,
+    content: str,
+) -> str:
+    """Writes a file to the local filesystem.
+
+    Usage:
+    - This tool will overwrite the existing file if there is one at the provided path.
+    - If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail
+      if you did not read the file first.
+    - ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+    - NEVER proactively create documentation files (*.md) or README files. Only create documentation files if
+      explicitly requested by the User.
+    - Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.
+
+    Args:
+        ctx: The run context wrapper
+        file_path: The absolute path to the file to write (must be absolute, not relative)
+        content: The content to write to the file
+
+    Returns:
+        Success message or error message
+    """
+    return await write_file(file_path, content)

vibecore/tools/file/utils.py

@@ -0,0 +1,78 @@
+"""Path validation utilities for file tools."""
+
+from pathlib import Path
+
+
+class PathValidationError(Exception):
+    """Raised when a path validation fails."""
+
+    pass
+
+
+def validate_file_path(file_path: str, base_dir: Path | None = None) -> Path:
+    """Validate and resolve a file path, ensuring it's within the allowed directory.
+
+    Args:
+        file_path: The file path to validate (can be relative or absolute)
+        base_dir: The base directory to restrict access to (defaults to CWD)
+
+    Returns:
+        The validated absolute Path object
+
+    Raises:
+        PathValidationError: If the path is invalid or outside the allowed directory
+    """
+    if base_dir is None:
+        base_dir = Path.cwd()
+
+    base_dir = base_dir.resolve()
+
+    try:
+        # Convert to Path object
+        path = Path(file_path)
+
+        # If relative, make it absolute relative to base_dir
+        if not path.is_absolute():
+            path = base_dir / path
+
+        # Resolve to get the canonical path (resolves symlinks, .., etc)
+        resolved_path = path.resolve()
+
+        # Check if the resolved path is within the base directory
+        # This prevents directory traversal attacks
+        try:
+            resolved_path.relative_to(base_dir)
+        except ValueError:
+            raise PathValidationError(
+                f"Path '{file_path}' is outside the allowed directory. "
+                f"Access is restricted to '{base_dir}' and its subdirectories."
+            ) from None
+
+        return resolved_path
+
+    except Exception as e:
+        if isinstance(e, PathValidationError):
+            raise
+        raise PathValidationError(f"Invalid path '{file_path}': {e}") from e
+
+
+def format_line_with_number(line_num: int, line: str, max_length: int = 2000) -> str:
+    """Format a line with line number in cat -n style.
+
+    Args:
+        line_num: The line number (1-based)
+        line: The line content
+        max_length: Maximum length for the line content
+
+    Returns:
+        Formatted line with line number
+    """
+    # Truncate line if too long
+    if len(line) > max_length:
+        line = line[:max_length] + "... (truncated)"
+
+    # Remove trailing newline for consistent formatting
+    line = line.rstrip("\n")
+
+    # Format with right-aligned line number (6 spaces wide) followed by tab
+    return f"{line_num:6d}\t{line}"

vibecore/tools/python/__init__.py

@@ -0,0 +1 @@
+"""Python code execution tools."""

vibecore/tools/python/backends/__init__.py

@@ -0,0 +1 @@
+"""Matplotlib backends for terminal rendering."""

vibecore/tools/python/backends/terminal_backend.py

@@ -0,0 +1,58 @@
+"""Terminal backend for matplotlib that captures images for later display."""
+
+from io import BytesIO
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from matplotlib.backend_bases import FigureManagerBase  # type: ignore[import-not-found]
+    from matplotlib.backends.backend_agg import FigureCanvasAgg  # type: ignore[import-not-found]
+else:
+    try:
+        from matplotlib.backend_bases import FigureManagerBase
+        from matplotlib.backends.backend_agg import FigureCanvasAgg
+    except ImportError:
+        # Create dummy classes if matplotlib is not installed
+        FigureManagerBase = object  # type: ignore[misc,assignment]
+        FigureCanvasAgg = object  # type: ignore[misc,assignment]
+
+__all__ = ["FigureCanvas", "FigureManager", "clear_captured_images", "get_captured_images"]
+
+# Global list to store captured images
+_captured_images: list[bytes] = []
+
+
+class TerminalImageFigureManager(FigureManagerBase):
+    """Figure manager that captures plots for later display."""
+
+    def show(self):
+        global _captured_images
+
+        # Save figure to BytesIO buffer
+        buf = BytesIO()
+        self.canvas.figure.savefig(buf, format="png", bbox_inches="tight", dpi=150)
+        buf.seek(0)
+
+        # Store the image buffer in the global list
+        _captured_images.append(buf.getvalue())
+
+
+class TerminalImageFigureCanvas(FigureCanvasAgg):
+    """Figure canvas for terminal image backend."""
+
+    manager_class = TerminalImageFigureManager  # type: ignore[assignment]
+
+
+# Provide the standard names that matplotlib is expecting
+FigureCanvas = TerminalImageFigureCanvas
+FigureManager = TerminalImageFigureManager
+
+
+def get_captured_images() -> list[bytes]:
+    """Get the list of captured images."""
+    return _captured_images.copy()
+
+
+def clear_captured_images() -> None:
+    """Clear the list of captured images."""
+    global _captured_images
+    _captured_images.clear()