shotgun-sh 0.4.0.dev1__py3-none-any.whl → 0.6.2__py3-none-any.whl

shotgun/agents/tools/file_read_tools/multimodal_file_read.py

@@ -0,0 +1,167 @@
+"""Multimodal file reading tool that verifies files exist and returns paths.
+
+This tool verifies PDFs/images exist and returns their paths for the agent
+to include in `files_found`. The Router then loads these via `file_requests`.
+"""
+
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+from pydantic_ai import RunContext, ToolReturn
+
+from shotgun.agents.models import AgentDeps
+from shotgun.agents.tools.registry import ToolCategory, register_tool
+from shotgun.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+# MIME type mapping for supported file types
+MIME_TYPES: dict[str, str] = {
+    ".pdf": "application/pdf",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+}
+
+# Maximum file size for multimodal reading (32MB - Anthropic's limit)
+MAX_FILE_SIZE_BYTES = 32 * 1024 * 1024
+
+
+class MultimodalFileReadResult(BaseModel):
+    """Result from multimodal file read."""
+
+    success: bool = Field(description="Whether the file was successfully found")
+    file_path: str = Field(description="The absolute path to the file")
+    file_name: str = Field(default="", description="The file name")
+    file_size_bytes: int = Field(default=0, description="File size in bytes")
+    mime_type: str = Field(default="", description="MIME type of the file")
+    error: str | None = Field(default=None, description="Error message if failed")
+
+    def __str__(self) -> str:
+        if not self.success:
+            return f"Error: {self.error}"
+        return (
+            f"Found: {self.file_name} ({self.file_size_bytes} bytes, {self.mime_type})"
+        )
+
+
+def _get_mime_type(file_path: Path) -> str | None:
+    """Get MIME type for a file based on extension."""
+    suffix = file_path.suffix.lower()
+    return MIME_TYPES.get(suffix)
+
+
+def _format_file_size(size_bytes: int) -> str:
+    """Format file size in human-readable format."""
+    if size_bytes < 1024:
+        return f"{size_bytes} B"
+    elif size_bytes < 1024 * 1024:
+        return f"{size_bytes / 1024:.1f} KB"
+    else:
+        return f"{size_bytes / (1024 * 1024):.1f} MB"
+
+
+@register_tool(
+    category=ToolCategory.CODEBASE_UNDERSTANDING,
+    display_text="Reading file (multimodal)",
+    key_arg="file_path",
+)
+async def multimodal_file_read(
+    ctx: RunContext[AgentDeps],
+    file_path: str,
+) -> ToolReturn:
+    """Verify a PDF or image file exists and return its path.
+
+    This tool checks that the file exists and is a supported type (PDF, image),
+    then returns the absolute path. Include this path in your `files_found`
+    response so the Router can load it for visual analysis.
+
+    Args:
+        ctx: RunContext containing AgentDeps
+        file_path: Path to the file (absolute or relative to CWD)
+
+    Returns:
+        ToolReturn with file info and absolute path
+    """
+    logger.debug("Checking multimodal file: %s", file_path)
+
+    try:
+        # Resolve the path
+        path = Path(file_path).expanduser().resolve()
+
+        # Check if file exists
+        if not path.exists():
+            error_result = MultimodalFileReadResult(
+                success=False,
+                file_path=str(path),
+                error=f"File not found: {file_path}",
+            )
+            return ToolReturn(return_value=str(error_result))
+
+        if path.is_dir():
+            error_result = MultimodalFileReadResult(
+                success=False,
+                file_path=str(path),
+                error=f"'{file_path}' is a directory, not a file",
+            )
+            return ToolReturn(return_value=str(error_result))
+
+        # Check MIME type
+        mime_type = _get_mime_type(path)
+        if mime_type is None:
+            supported = ", ".join(MIME_TYPES.keys())
+            error_result = MultimodalFileReadResult(
+                success=False,
+                file_path=str(path),
+                error=f"Unsupported file type: {path.suffix}. Supported: {supported}",
+            )
+            return ToolReturn(return_value=str(error_result))
+
+        # Check file size
+        file_size = path.stat().st_size
+        if file_size > MAX_FILE_SIZE_BYTES:
+            error_result = MultimodalFileReadResult(
+                success=False,
+                file_path=str(path),
+                file_size_bytes=file_size,
+                error=f"File too large: {_format_file_size(file_size)} (max: {_format_file_size(MAX_FILE_SIZE_BYTES)})",
+            )
+            return ToolReturn(return_value=str(error_result))
+
+        logger.debug(
+            "Found multimodal file: %s (%s, %s)",
+            path.name,
+            _format_file_size(file_size),
+            mime_type,
+        )
+
+        # Return file info with absolute path
+        file_type = "PDF" if mime_type == "application/pdf" else "Image"
+        summary = f"""{file_type} found: {path.name}
+Size: {_format_file_size(file_size)}
+Type: {mime_type}
+Absolute path: {path}
+
+IMPORTANT: Include the absolute path above in your `files_found` response field.
+The Router will then be able to load and analyze this file's visual content."""
+
+        return ToolReturn(return_value=summary)
+
+    except PermissionError:
+        error_result = MultimodalFileReadResult(
+            success=False,
+            file_path=file_path,
+            error=f"Permission denied: {file_path}",
+        )
+        return ToolReturn(return_value=str(error_result))
+
+    except Exception as e:
+        logger.error("Error checking multimodal file: %s", str(e))
+        error_result = MultimodalFileReadResult(
+            success=False,
+            file_path=file_path,
+            error=f"Error: {str(e)}",
+        )
+        return ToolReturn(return_value=str(error_result))

shotgun/agents/tools/markdown_tools/__init__.py

@@ -0,0 +1,62 @@
+"""Markdown manipulation tools for Pydantic AI agents."""
+
+from .insert_section import insert_markdown_section
+from .models import (
+    CloseMatch,
+    HeadingList,
+    HeadingMatch,
+    MarkdownFileContext,
+    MarkdownHeading,
+    SectionMatchResult,
+    SectionNumber,
+)
+from .remove_section import remove_markdown_section
+from .replace_section import replace_markdown_section
+from .utils import (
+    decrement_section_number,
+    detect_line_ending,
+    extract_headings,
+    find_and_validate_section,
+    find_close_matches,
+    find_matching_heading,
+    find_section_bounds,
+    get_heading_level,
+    increment_section_number,
+    load_markdown_file,
+    normalize_section_content,
+    parse_section_number,
+    renumber_headings_after,
+    split_normalized_content,
+    write_markdown_file,
+)
+
+__all__ = [
+    # Tools
+    "replace_markdown_section",
+    "insert_markdown_section",
+    "remove_markdown_section",
+    # Models
+    "MarkdownHeading",
+    "HeadingList",
+    "HeadingMatch",
+    "CloseMatch",
+    "SectionNumber",
+    "MarkdownFileContext",
+    "SectionMatchResult",
+    # Utilities
+    "get_heading_level",
+    "extract_headings",
+    "find_matching_heading",
+    "find_close_matches",
+    "find_section_bounds",
+    "detect_line_ending",
+    "normalize_section_content",
+    "split_normalized_content",
+    "parse_section_number",
+    "increment_section_number",
+    "decrement_section_number",
+    "renumber_headings_after",
+    "load_markdown_file",
+    "find_and_validate_section",
+    "write_markdown_file",
+]

shotgun/agents/tools/markdown_tools/insert_section.py

@@ -0,0 +1,148 @@
+"""Tool for inserting content into markdown sections."""
+
+from pydantic_ai import RunContext
+
+from shotgun.agents.models import AgentDeps, FileOperationType
+from shotgun.agents.tools.file_management import _validate_agent_scoped_path
+from shotgun.agents.tools.registry import ToolCategory, register_tool
+from shotgun.logging_config import get_logger
+
+from .utils import (
+    find_and_validate_section,
+    get_heading_level,
+    load_markdown_file,
+    parse_section_number,
+    renumber_headings_after,
+    split_normalized_content,
+    write_markdown_file,
+)
+
+logger = get_logger(__name__)
+
+
+@register_tool(
+    category=ToolCategory.ARTIFACT_MANAGEMENT,
+    display_text="Inserting content",
+    key_arg="filename",
+    secondary_key_arg="new_heading",
+)
+async def insert_markdown_section(
+    ctx: RunContext[AgentDeps],
+    filename: str,
+    after_heading: str,
+    content: str,
+    new_heading: str | None = None,
+) -> str:
+    """Insert content at the end of a Markdown section.
+
+    PREFER THIS TOOL over rewriting the entire file - it is faster, less costly,
+    and less error-prone. Use this to append content to an existing section.
+
+    Uses fuzzy matching on headings so minor typos are tolerated.
+    Inserts content just before the next heading at the same or higher level.
+
+    Note: If new_heading contains a section number (e.g., "### 4.4 New Section"),
+    subsequent numbered sections at the same level will be automatically incremented
+    to maintain proper numbering order.
+
+    Args:
+        ctx: Run context with agent dependencies
+        filename: Path to the Markdown file (relative to .shotgun directory)
+        after_heading: The heading to insert after (e.g., '## Requirements'). Fuzzy matched.
+        content: The content to insert at the end of the section
+        new_heading: Optional heading for the inserted content (creates a subsection)
+
+    Returns:
+        Success message or error message
+    """
+    logger.debug("Inserting content into section '%s' in: %s", after_heading, filename)
+
+    try:
+        # Validate path with agent scoping
+        file_path = _validate_agent_scoped_path(filename, ctx.deps.agent_mode)
+
+        # Load and parse the markdown file
+        file_ctx = await load_markdown_file(file_path, filename)
+        if isinstance(file_ctx, str):
+            return file_ctx  # Error message
+
+        # Find and validate the target section
+        match = find_and_validate_section(file_ctx, after_heading)
+        if not match.is_success:
+            return match.error  # type: ignore[return-value]
+
+        # Build insert content
+        insert_content_lines = split_normalized_content(content)
+
+        # Build the insert lines
+        insert_lines: list[str] = [""]  # Blank line separator before new content
+
+        if new_heading:
+            insert_lines.append(new_heading)
+            insert_lines.append("")  # Blank line after heading
+
+        insert_lines.extend(insert_content_lines)
+
+        # Add trailing blank line if not at EOF
+        if match.end_line < len(file_ctx.lines):
+            insert_lines.append("")
+
+        # Insert before section end (before next heading or EOF)
+        new_lines = (
+            file_ctx.lines[: match.end_line]
+            + insert_lines
+            + file_ctx.lines[match.end_line :]
+        )
+
+        # If new_heading has a section number, renumber subsequent sections
+        if new_heading:
+            new_heading_level = get_heading_level(new_heading)
+            if new_heading_level:
+                section_num = parse_section_number(new_heading)
+                if section_num:
+                    # Calculate the line number where subsequent sections start
+                    # (after the inserted content)
+                    renumber_start = match.end_line + len(insert_lines)
+                    new_lines = renumber_headings_after(
+                        new_lines,
+                        start_line=renumber_start,
+                        heading_level=new_heading_level,
+                        increment=True,
+                    )
+
+        # Write the modified file
+        await write_markdown_file(file_ctx, new_lines)
+
+        # Track the file operation
+        ctx.deps.file_tracker.add_operation(file_path, FileOperationType.UPDATED)
+
+        logger.debug(
+            "Successfully inserted content into section '%s' in %s",
+            match.heading.text,  # type: ignore[union-attr]
+            filename,
+        )
+
+        lines_added = len(insert_lines)
+        confidence_display = f"{int(match.confidence * 100)}%"
+
+        if new_heading:
+            return (
+                f"Successfully inserted '{new_heading}' into '{match.heading.text}' in {filename} "  # type: ignore[union-attr]
+                f"(matched with {confidence_display} confidence, {lines_added} lines added)"
+            )
+        else:
+            return (
+                f"Successfully inserted content into '{match.heading.text}' in {filename} "  # type: ignore[union-attr]
+                f"(matched with {confidence_display} confidence, {lines_added} lines added)"
+            )
+
+    except ValueError as e:
+        # Path validation errors
+        error_msg = f"Error inserting into '{filename}': {e}"
+        logger.error("Section insertion failed: %s", error_msg)
+        return error_msg
+
+    except Exception as e:
+        error_msg = f"Error inserting into '{filename}': {e}"
+        logger.error("Section insertion failed: %s", error_msg)
+        return error_msg

shotgun/agents/tools/markdown_tools/models.py

@@ -0,0 +1,86 @@
+"""Pydantic models for markdown tools."""
+
+from pathlib import Path
+
+from pydantic import BaseModel
+
+
+class MarkdownHeading(BaseModel):
+    """Represents a heading found in a Markdown file."""
+
+    line_number: int
+    text: str
+    level: int
+
+    @property
+    def normalized_text(self) -> str:
+        """Return heading text without # prefix, stripped and lowercased."""
+        return self.text.lstrip("#").strip().lower()
+
+
+HeadingList = list[MarkdownHeading]
+
+
+class HeadingMatch(BaseModel):
+    """Result of a successful heading match."""
+
+    heading: MarkdownHeading
+    confidence: float
+
+
+class CloseMatch(BaseModel):
+    """A close match result for error messages."""
+
+    heading_text: str
+    confidence: float
+
+
+class SectionNumber(BaseModel):
+    """Parsed section number from a heading.
+
+    Examples:
+        - "## 3. Title" -> prefix="3", has_trailing_dot=True
+        - "### 4.4 Title" -> prefix="4.4", has_trailing_dot=False
+        - "#### 1.2.3.4 Title" -> prefix="1.2.3.4", has_trailing_dot=False
+    """
+
+    prefix: str  # The number part, e.g., "4.4" or "3"
+    has_trailing_dot: bool  # Whether it ends with a dot before the title
+
+
+class MarkdownFileContext(BaseModel):
+    """Context for a loaded markdown file ready for section operations.
+
+    This encapsulates the common state needed by all section manipulation tools:
+    file path, content split into lines, line ending style, and extracted headings.
+    """
+
+    file_path: Path
+    filename: str  # Original filename for error messages
+    lines: list[str]
+    line_ending: str
+    headings: HeadingList
+
+    model_config = {"arbitrary_types_allowed": True}
+
+
+class SectionMatchResult(BaseModel):
+    """Result of finding and validating a section match.
+
+    Either contains a successful match with the heading and bounds,
+    or an error message explaining why the match failed.
+    """
+
+    # Success fields (all present when error is None)
+    heading: MarkdownHeading | None = None
+    confidence: float = 0.0
+    start_line: int = 0
+    end_line: int = 0
+
+    # Error field (present when match failed)
+    error: str | None = None
+
+    @property
+    def is_success(self) -> bool:
+        """Return True if this is a successful match."""
+        return self.error is None and self.heading is not None

shotgun/agents/tools/markdown_tools/remove_section.py

@@ -0,0 +1,114 @@
+"""Tool for removing markdown sections."""
+
+from pydantic_ai import RunContext
+
+from shotgun.agents.models import AgentDeps, FileOperationType
+from shotgun.agents.tools.file_management import _validate_agent_scoped_path
+from shotgun.agents.tools.registry import ToolCategory, register_tool
+from shotgun.logging_config import get_logger
+
+from .utils import (
+    find_and_validate_section,
+    load_markdown_file,
+    parse_section_number,
+    renumber_headings_after,
+    write_markdown_file,
+)
+
+logger = get_logger(__name__)
+
+
+@register_tool(
+    category=ToolCategory.ARTIFACT_MANAGEMENT,
+    display_text="Removing section",
+    key_arg="filename",
+    secondary_key_arg="section_heading",
+)
+async def remove_markdown_section(
+    ctx: RunContext[AgentDeps],
+    filename: str,
+    section_heading: str,
+) -> str:
+    """Remove an entire section from a Markdown file.
+
+    Uses fuzzy matching on headings so minor typos are tolerated.
+    Removes from the target heading down to (but not including) the next
+    heading at the same or higher level.
+
+    Note: If the removed section has a numbered heading (e.g., "### 4.4 Title"),
+    subsequent numbered sections at the same level will be automatically
+    decremented to maintain proper numbering order.
+
+    Args:
+        ctx: Run context with agent dependencies
+        filename: Path to the Markdown file (relative to .shotgun directory)
+        section_heading: The heading to find and remove. Fuzzy matched.
+
+    Returns:
+        Success message or error message
+    """
+    logger.debug("Removing section '%s' from: %s", section_heading, filename)
+
+    try:
+        # Validate path with agent scoping
+        file_path = _validate_agent_scoped_path(filename, ctx.deps.agent_mode)
+
+        # Load and parse the markdown file
+        file_ctx = await load_markdown_file(file_path, filename)
+        if isinstance(file_ctx, str):
+            return file_ctx  # Error message
+
+        # Find and validate the target section
+        match = find_and_validate_section(file_ctx, section_heading)
+        if not match.is_success:
+            return match.error  # type: ignore[return-value]
+
+        removed_lines = match.end_line - match.start_line
+
+        # Check if the removed section has a numbered heading
+        section_num = parse_section_number(match.heading.text)  # type: ignore[union-attr]
+        heading_level = match.heading.level  # type: ignore[union-attr]
+
+        # Remove the section
+        new_lines = (
+            file_ctx.lines[: match.start_line] + file_ctx.lines[match.end_line :]
+        )
+
+        # If the removed section had a numbered heading, decrement subsequent sections
+        if section_num:
+            new_lines = renumber_headings_after(
+                new_lines,
+                start_line=match.start_line,
+                heading_level=heading_level,
+                increment=False,
+            )
+
+        # Write the modified file
+        await write_markdown_file(file_ctx, new_lines)
+
+        # Track the file operation
+        ctx.deps.file_tracker.add_operation(file_path, FileOperationType.UPDATED)
+
+        logger.debug(
+            "Successfully removed section '%s' from %s",
+            match.heading.text,  # type: ignore[union-attr]
+            filename,
+        )
+
+        confidence_display = f"{int(match.confidence * 100)}%"
+
+        return (
+            f"Successfully removed section '{match.heading.text}' from {filename} "  # type: ignore[union-attr]
+            f"(matched with {confidence_display} confidence, {removed_lines} lines removed)"
+        )
+
+    except ValueError as e:
+        # Path validation errors
+        error_msg = f"Error removing section from '{filename}': {e}"
+        logger.error("Section removal failed: %s", error_msg)
+        return error_msg
+
+    except Exception as e:
+        error_msg = f"Error removing section from '{filename}': {e}"
+        logger.error("Section removal failed: %s", error_msg)
+        return error_msg

shotgun/agents/tools/markdown_tools/replace_section.py

@@ -0,0 +1,119 @@
+"""Tool for replacing markdown sections."""
+
+from pydantic_ai import RunContext
+
+from shotgun.agents.models import AgentDeps, FileOperationType
+from shotgun.agents.tools.file_management import _validate_agent_scoped_path
+from shotgun.agents.tools.registry import ToolCategory, register_tool
+from shotgun.logging_config import get_logger
+
+from .utils import (
+    find_and_validate_section,
+    load_markdown_file,
+    split_normalized_content,
+    write_markdown_file,
+)
+
+logger = get_logger(__name__)
+
+
+@register_tool(
+    category=ToolCategory.ARTIFACT_MANAGEMENT,
+    display_text="Replacing section",
+    key_arg="filename",
+    secondary_key_arg="section_heading",
+)
+async def replace_markdown_section(
+    ctx: RunContext[AgentDeps],
+    filename: str,
+    section_heading: str,
+    new_contents: str,
+    new_heading: str | None = None,
+) -> str:
+    """Replace an entire section in a Markdown file.
+
+    PREFER THIS TOOL over rewriting the entire file - it is faster, less costly,
+    and less error-prone.
+
+    Uses fuzzy matching on headings so minor typos are tolerated.
+    Replaces from the target heading down to (but not including) the next
+    heading at the same or higher level.
+
+    Args:
+        ctx: Run context with agent dependencies
+        filename: Path to the Markdown file (relative to .shotgun directory)
+        section_heading: The heading to find (e.g., '## Requirements'). Fuzzy matched.
+        new_contents: The new content for the section body (not including the heading)
+        new_heading: Optional new heading text to replace the old one
+
+    Returns:
+        Success message or error message
+    """
+    logger.debug("Replacing section '%s' in: %s", section_heading, filename)
+
+    try:
+        # Validate path with agent scoping
+        file_path = _validate_agent_scoped_path(filename, ctx.deps.agent_mode)
+
+        # Load and parse the markdown file
+        file_ctx = await load_markdown_file(file_path, filename)
+        if isinstance(file_ctx, str):
+            return file_ctx  # Error message
+
+        # Find and validate the target section
+        match = find_and_validate_section(file_ctx, section_heading)
+        if not match.is_success:
+            return match.error  # type: ignore[return-value]
+
+        old_section_lines = match.end_line - match.start_line
+
+        # Build new section
+        final_heading = new_heading if new_heading else match.heading.text  # type: ignore[union-attr]
+        new_content_lines = split_normalized_content(new_contents)
+
+        # Build the new section: heading + blank line + content
+        new_section_lines = [final_heading, ""]
+        new_section_lines.extend(new_content_lines)
+
+        # Add trailing blank line if not at EOF
+        if match.end_line < len(file_ctx.lines):
+            new_section_lines.append("")
+
+        # Replace section
+        new_lines = (
+            file_ctx.lines[: match.start_line]
+            + new_section_lines
+            + file_ctx.lines[match.end_line :]
+        )
+
+        # Write the modified file
+        await write_markdown_file(file_ctx, new_lines)
+
+        # Track the file operation
+        ctx.deps.file_tracker.add_operation(file_path, FileOperationType.UPDATED)
+
+        logger.debug(
+            "Successfully replaced section '%s' in %s",
+            match.heading.text,  # type: ignore[union-attr]
+            filename,
+        )
+
+        new_section_line_count = len(new_section_lines)
+        confidence_display = f"{int(match.confidence * 100)}%"
+
+        return (
+            f"Successfully replaced section '{match.heading.text}' in {filename} "  # type: ignore[union-attr]
+            f"(matched with {confidence_display} confidence, "
+            f"{old_section_lines} lines -> {new_section_line_count} lines)"
+        )
+
+    except ValueError as e:
+        # Path validation errors
+        error_msg = f"Error replacing section in '{filename}': {e}"
+        logger.error("Section replacement failed: %s", error_msg)
+        return error_msg
+
+    except Exception as e:
+        error_msg = f"Error replacing section in '{filename}': {e}"
+        logger.error("Section replacement failed: %s", error_msg)
+        return error_msg