shotgun-sh 0.2.29.dev2__py3-none-any.whl → 0.6.1.dev1__py3-none-any.whl

shotgun/attachments/__init__.py

@@ -0,0 +1,41 @@
+"""File attachment support for @path syntax.
+
+This module provides functionality for parsing and processing file attachments
+in user input using the @path syntax (e.g., @/path/to/file.pdf).
+"""
+
+from shotgun.attachments.models import (
+    AttachmentBarState,
+    AttachmentHint,
+    AttachmentParseResult,
+    AttachmentType,
+    FileAttachment,
+)
+from shotgun.attachments.parser import is_image_type, parse_attachment_reference
+from shotgun.attachments.processor import (
+    create_attachment_hint_display,
+    format_file_size,
+    get_attachment_icon,
+    get_provider_size_limit,
+    process_attachment,
+    validate_file_size,
+)
+
+__all__ = [
+    # Models
+    "AttachmentBarState",
+    "AttachmentHint",
+    "AttachmentParseResult",
+    "AttachmentType",
+    "FileAttachment",
+    # Parser
+    "is_image_type",
+    "parse_attachment_reference",
+    # Processor
+    "create_attachment_hint_display",
+    "format_file_size",
+    "get_attachment_icon",
+    "get_provider_size_limit",
+    "process_attachment",
+    "validate_file_size",
+]

shotgun/attachments/errors.py

@@ -0,0 +1,60 @@
+"""Attachment error message formatting utilities.
+
+Centralizes error message formatting for consistent user feedback.
+All attachment-related error messages should use these functions.
+"""
+
+from pathlib import Path
+
+# Warning emoji prefix for all error messages
+WARNING_PREFIX = "\u26a0\ufe0f"  # ⚠️
+
+
+def file_not_found(path: Path | str) -> str:
+    """Format file not found error message."""
+    return f"{WARNING_PREFIX} File not found: {path}"
+
+
+def not_a_file(path: Path | str) -> str:
+    """Format not a file (e.g., directory) error message."""
+    return f"{WARNING_PREFIX} Not a file: {path}"
+
+
+def unsupported_file_type(extension: str, supported: str) -> str:
+    """Format unsupported file type error message.
+
+    Args:
+        extension: The file extension (e.g., ".doc" or "(no extension)")
+        supported: Comma-separated list of supported extensions
+    """
+    return (
+        f"{WARNING_PREFIX} Unsupported file type: {extension} (supported: {supported})"
+    )
+
+
+def cannot_read_file(path: Path | str, reason: str | None = None) -> str:
+    """Format cannot read file error message.
+
+    Args:
+        path: Path to the file
+        reason: Optional reason (e.g., "permission denied")
+    """
+    if reason:
+        return f"{WARNING_PREFIX} Cannot read file: {path} ({reason})"
+    return f"{WARNING_PREFIX} Cannot read file: {path}"
+
+
+def could_not_resolve_path(path: str) -> str:
+    """Format path resolution error message."""
+    return f"{WARNING_PREFIX} Could not resolve path: {path}"
+
+
+def file_too_large(size: str, limit: str, provider: str) -> str:
+    """Format file too large error message.
+
+    Args:
+        size: Human-readable file size (e.g., "45.0 MB")
+        limit: Human-readable size limit (e.g., "32.0 MB")
+        provider: Provider name (e.g., "Anthropic")
+    """
+    return f"{WARNING_PREFIX} File too large: {size} (max: {limit} for {provider})"

shotgun/attachments/models.py

@@ -0,0 +1,107 @@
+"""Type contracts for file attachment support.
+
+These models define the shape of file attachment data throughout the system.
+"""
+
+from enum import StrEnum
+from pathlib import Path
+from typing import Literal, Protocol
+
+from pydantic import BaseModel, Field
+
+
+class AttachmentType(StrEnum):
+    """Supported attachment file types."""
+
+    PDF = "pdf"
+    PNG = "png"
+    JPG = "jpg"
+    JPEG = "jpeg"
+    GIF = "gif"
+    WEBP = "webp"
+
+
+class FileAttachment(BaseModel):
+    """Represents a file attachment pending submission.
+
+    This model tracks attachment state from parsing through submission.
+    """
+
+    file_path: Path = Field(..., description="Absolute path to the attached file")
+    file_name: str = Field(..., description="Display name (basename)")
+    file_type: AttachmentType = Field(..., description="File type enum")
+    file_size_bytes: int = Field(..., description="File size in bytes")
+    content_base64: str | None = Field(
+        default=None, description="Base64-encoded content (populated on submission)"
+    )
+    mime_type: str = Field(..., description="MIME type for API submission")
+
+
+class AttachmentHint(BaseModel):
+    """Hint message variant for displaying attachments in chat history.
+
+    Used by UIHint system to render attachment indicators in the conversation.
+    """
+
+    filename: str = Field(..., description="Display filename")
+    file_type: AttachmentType = Field(..., description="File type for icon selection")
+    file_size_display: str = Field(
+        ..., description="Human-readable size (e.g., '2.5 MB')"
+    )
+    kind: Literal["attachment"] = "attachment"
+
+
+class AttachmentBarState(BaseModel):
+    """State model for the AttachmentBar widget.
+
+    Tracks current attachment for display above the input.
+    """
+
+    attachment: FileAttachment | None = Field(
+        default=None, description="Currently attached file, or None if no attachment"
+    )
+
+
+class AttachmentParseResult(BaseModel):
+    """Result of parsing @path references from user input.
+
+    Contains the original text (with @path preserved) and any successfully
+    parsed attachment. The @path reference is kept in the text so the LLM
+    knows which file is being referenced.
+    """
+
+    original_text: str = Field(
+        ...,
+        description="Original input text with @path reference preserved for LLM context",
+    )
+    attachment: FileAttachment | None = Field(
+        default=None, description="Parsed attachment, or None if no valid @path found"
+    )
+    error_message: str | None = Field(
+        default=None,
+        description="Error message if parsing failed (file not found, unsupported type, etc.)",
+    )
+
+
+class AttachmentCapability(Protocol):
+    """Protocol for checking provider attachment capabilities.
+
+    Note: All three providers (OpenAI, Anthropic, Gemini) support both images
+    and PDFs. OpenAI requires vision-capable models (GPT-4o, GPT-4o mini,
+    GPT-5.2) for PDF support.
+    """
+
+    @property
+    def supports_images(self) -> bool:
+        """Whether provider supports image attachments."""
+        ...
+
+    @property
+    def supports_pdf(self) -> bool:
+        """Whether provider supports native PDF attachments."""
+        ...
+
+    @property
+    def max_file_size_bytes(self) -> int:
+        """Maximum file size in bytes for this provider."""
+        ...

shotgun/attachments/parser.py

@@ -0,0 +1,257 @@
+"""Attachment path parser for @path syntax in user input.
+
+Parses file references from user input text. Supported formats:
+- Absolute paths: @/absolute/path.pdf
+- Home directory: @~/Documents/file.png
+- Explicit relative: @./relative.jpg, @../parent/file.gif
+- Bare relative: @tmp/file.pdf, @path/to/file.png
+- Filename only: @document.pdf, @image.png
+
+Without the @ prefix, file paths are passed through to the LLM which
+can use its own file tools to handle them.
+"""
+
+import logging
+import re
+from pathlib import Path
+
+from shotgun.attachments.errors import (
+    cannot_read_file,
+    could_not_resolve_path,
+    file_not_found,
+    not_a_file,
+    unsupported_file_type,
+)
+from shotgun.attachments.models import (
+    AttachmentParseResult,
+    AttachmentType,
+    FileAttachment,
+)
+
+logger = logging.getLogger(__name__)
+
+# Regex pattern for @path syntax
+# Matches:
+# - Explicit prefixes: @/absolute, @~/, @./, @../
+# - Bare relative paths: @tmp/file, @path/to/file
+# - Filenames with supported extensions: @file.pdf, @image.png
+# Excludes trailing punctuation that commonly follows paths in sentences
+ATTACHMENT_PATH_PATTERN = re.compile(
+    r"@("
+    r"(?:/|~|\.\.?/)[^\s?!,;:\"')\]]+"  # /path, ~/path, ./path, ../path
+    r"|"
+    r"\w[^\s?!,;:\"')\]@]*/[^\s?!,;:\"')\]]+"  # path/to/file (bare relative)
+    r"|"
+    r"\w[\w.-]*\.(?:pdf|png|jpe?g|gif|webp)"  # file.pdf (filename with extension)
+    r")",
+    re.IGNORECASE,
+)
+
+# Supported file extensions mapped to AttachmentType
+SUPPORTED_EXTENSIONS: dict[str, AttachmentType] = {
+    ".pdf": AttachmentType.PDF,
+    ".png": AttachmentType.PNG,
+    ".jpg": AttachmentType.JPG,
+    ".jpeg": AttachmentType.JPEG,
+    ".gif": AttachmentType.GIF,
+    ".webp": AttachmentType.WEBP,
+}
+
+# MIME types for each attachment type
+MIME_TYPES: dict[AttachmentType, str] = {
+    AttachmentType.PDF: "application/pdf",
+    AttachmentType.PNG: "image/png",
+    AttachmentType.JPG: "image/jpeg",
+    AttachmentType.JPEG: "image/jpeg",
+    AttachmentType.GIF: "image/gif",
+    AttachmentType.WEBP: "image/webp",
+}
+
+
+def _extract_path_reference(text: str) -> str | None:
+    """Extract the first @path reference from text.
+
+    Args:
+        text: Input text to search.
+
+    Returns:
+        The path string (without @) if found, None otherwise.
+    """
+    match = ATTACHMENT_PATH_PATTERN.search(text)
+    if match:
+        return match.group(1)
+    return None
+
+
+def _resolve_path(path_str: str) -> Path:
+    """Resolve a path string to an absolute Path.
+
+    Handles:
+    - Absolute paths: /path/to/file
+    - Home directory: ~/path/to/file
+    - Relative paths: ./file or ../file
+
+    Args:
+        path_str: Path string from user input.
+
+    Returns:
+        Resolved absolute Path object.
+    """
+    path = Path(path_str)
+
+    # Expand ~ to user home directory
+    if path_str.startswith("~"):
+        path = path.expanduser()
+
+    # Resolve to absolute path (handles ./ and ../)
+    return path.resolve()
+
+
+def _validate_file_extension(path: Path) -> AttachmentType | None:
+    """Validate file has a supported extension.
+
+    Args:
+        path: Path to validate.
+
+    Returns:
+        AttachmentType if extension is supported, None otherwise.
+    """
+    extension = path.suffix.lower()
+    return SUPPORTED_EXTENSIONS.get(extension)
+
+
+def _get_mime_type(attachment_type: AttachmentType) -> str:
+    """Get MIME type for an attachment type.
+
+    Args:
+        attachment_type: The attachment type enum.
+
+    Returns:
+        MIME type string (e.g., "application/pdf").
+    """
+    return MIME_TYPES[attachment_type]
+
+
+def is_image_type(attachment_type: AttachmentType) -> bool:
+    """Check if attachment type is an image format.
+
+    Args:
+        attachment_type: The attachment type to check.
+
+    Returns:
+        True if PNG, JPG, JPEG, GIF, or WEBP; False for PDF.
+    """
+    return attachment_type != AttachmentType.PDF
+
+
+def parse_attachment_reference(text: str) -> AttachmentParseResult:
+    """Parse @path reference from user input text.
+
+    Extracts the first @path reference from the input text, validates the file
+    exists and has a supported extension, and returns parsing result.
+
+    The original text is preserved with the @path reference intact so the LLM
+    knows which file is being referenced.
+
+    Args:
+        text: User input text that may contain an @path reference.
+
+    Returns:
+        AttachmentParseResult with:
+        - original_text: The input text unchanged (with @path preserved)
+        - attachment: FileAttachment if valid file found, None otherwise
+        - error_message: Error description if parsing failed, None if successful
+
+    Examples:
+        >>> result = parse_attachment_reference("Analyze @/path/to/doc.pdf")
+        >>> result.original_text
+        'Analyze @/path/to/doc.pdf'
+        >>> result.attachment.file_name
+        'doc.pdf'
+    """
+    # Extract path reference from text
+    path_str = _extract_path_reference(text)
+
+    # No @path reference found - not an error, just no attachment
+    if path_str is None:
+        return AttachmentParseResult(
+            original_text=text,
+            attachment=None,
+            error_message=None,
+        )
+
+    # Resolve to absolute path
+    try:
+        resolved_path = _resolve_path(path_str)
+    except Exception as e:
+        logger.warning(f"Failed to resolve path '{path_str}': {e}")
+        return AttachmentParseResult(
+            original_text=text,
+            attachment=None,
+            error_message=could_not_resolve_path(path_str),
+        )
+
+    # Check if file exists
+    if not resolved_path.exists():
+        return AttachmentParseResult(
+            original_text=text,
+            attachment=None,
+            error_message=file_not_found(resolved_path),
+        )
+
+    # Check if it's a file (not a directory)
+    if not resolved_path.is_file():
+        return AttachmentParseResult(
+            original_text=text,
+            attachment=None,
+            error_message=not_a_file(resolved_path),
+        )
+
+    # Validate file extension
+    attachment_type = _validate_file_extension(resolved_path)
+    if attachment_type is None:
+        extension = resolved_path.suffix or "(no extension)"
+        supported = ", ".join(ext.lstrip(".") for ext in SUPPORTED_EXTENSIONS.keys())
+        return AttachmentParseResult(
+            original_text=text,
+            attachment=None,
+            error_message=unsupported_file_type(extension, supported),
+        )
+
+    # Check file is readable
+    try:
+        file_size = resolved_path.stat().st_size
+    except PermissionError:
+        return AttachmentParseResult(
+            original_text=text,
+            attachment=None,
+            error_message=cannot_read_file(resolved_path, "permission denied"),
+        )
+    except OSError as e:
+        logger.warning(f"Failed to stat file '{resolved_path}': {e}")
+        return AttachmentParseResult(
+            original_text=text,
+            attachment=None,
+            error_message=cannot_read_file(resolved_path),
+        )
+
+    # Create successful attachment (content_base64 will be populated by processor)
+    attachment = FileAttachment(
+        file_path=resolved_path,
+        file_name=resolved_path.name,
+        file_type=attachment_type,
+        file_size_bytes=file_size,
+        content_base64=None,
+        mime_type=_get_mime_type(attachment_type),
+    )
+
+    logger.debug(
+        f"Parsed attachment: {attachment.file_name} "
+        f"({attachment.file_type.value}, {file_size} bytes)"
+    )
+
+    return AttachmentParseResult(
+        original_text=text,
+        attachment=attachment,
+        error_message=None,
+    )

shotgun/attachments/processor.py

@@ -0,0 +1,193 @@
+"""Attachment processor for file validation and encoding.
+
+Provides functions to validate file sizes against provider limits
+and encode file contents to base64 for API submission.
+"""
+
+import base64
+import logging
+from pathlib import Path
+
+import aiofiles
+
+from shotgun.agents.config.models import ProviderType
+from shotgun.attachments.errors import (
+    cannot_read_file,
+    file_not_found,
+    file_too_large,
+)
+from shotgun.attachments.models import AttachmentType, FileAttachment
+
+logger = logging.getLogger(__name__)
+
+# Provider file size limits in bytes
+PROVIDER_SIZE_LIMITS: dict[ProviderType, int] = {
+    ProviderType.OPENAI: 20 * 1024 * 1024,  # 20MB
+    ProviderType.ANTHROPIC: 32 * 1024 * 1024,  # 32MB
+    ProviderType.GOOGLE: 4 * 1024 * 1024,  # 4MB
+}
+
+# Default limit for unknown providers (most restrictive)
+DEFAULT_SIZE_LIMIT: int = 4 * 1024 * 1024  # 4MB
+
+
+def get_provider_size_limit(provider: ProviderType) -> int:
+    """Get the maximum file size limit for a provider.
+
+    Args:
+        provider: The LLM provider type.
+
+    Returns:
+        Maximum file size in bytes.
+    """
+    return PROVIDER_SIZE_LIMITS.get(provider, DEFAULT_SIZE_LIMIT)
+
+
+def format_file_size(size_bytes: int) -> str:
+    """Format file size in human-readable format.
+
+    Args:
+        size_bytes: File size in bytes.
+
+    Returns:
+        Human-readable string (e.g., "2.5 MB", "512 KB", "128 B").
+    """
+    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"
+
+
+def validate_file_size(
+    attachment: FileAttachment,
+    provider: ProviderType,
+) -> tuple[bool, str | None]:
+    """Validate file size against provider limit.
+
+    Args:
+        attachment: The file attachment to validate.
+        provider: The target LLM provider.
+
+    Returns:
+        Tuple of (is_valid, error_message).
+        If valid: (True, None)
+        If invalid: (False, "File size {size} exceeds {provider} limit of {limit}")
+    """
+    limit = get_provider_size_limit(provider)
+
+    if attachment.file_size_bytes > limit:
+        size_str = format_file_size(attachment.file_size_bytes)
+        limit_str = format_file_size(limit)
+        provider_name = provider.value.capitalize()
+        return (
+            False,
+            file_too_large(size_str, limit_str, provider_name),
+        )
+
+    return (True, None)
+
+
+async def encode_file_to_base64(file_path: Path) -> str:
+    """Asynchronously read and encode file contents to base64.
+
+    Args:
+        file_path: Path to the file to encode.
+
+    Returns:
+        Base64-encoded string of file contents.
+
+    Raises:
+        FileNotFoundError: If file does not exist.
+        PermissionError: If file cannot be read.
+        OSError: If file read fails.
+    """
+    async with aiofiles.open(file_path, "rb") as f:
+        content = await f.read()
+
+    if not content:
+        return ""
+
+    return base64.b64encode(content).decode("utf-8")
+
+
+async def process_attachment(
+    attachment: FileAttachment,
+    provider: ProviderType,
+) -> tuple[FileAttachment, str | None]:
+    """Validate and process an attachment for submission.
+
+    Validates file size against provider limits and encodes content to base64.
+    All supported attachment types (PDF, PNG, JPG, JPEG, GIF, WEBP) work with
+    all providers (OpenAI, Anthropic, Google) via BinaryContent.
+
+    Args:
+        attachment: The file attachment to process.
+        provider: The target LLM provider.
+
+    Returns:
+        Tuple of (processed_attachment, error_message).
+        If successful: (attachment_with_base64_content, None)
+        If failed: (original_attachment, error_message)
+    """
+    # Validate file size
+    is_valid, error = validate_file_size(attachment, provider)
+    if not is_valid:
+        return (attachment, error)
+
+    # Encode file to base64
+    try:
+        content_base64 = await encode_file_to_base64(attachment.file_path)
+    except FileNotFoundError:
+        return (attachment, file_not_found(attachment.file_path))
+    except PermissionError:
+        return (attachment, cannot_read_file(attachment.file_path, "permission denied"))
+    except OSError as e:
+        logger.warning(f"Failed to read file '{attachment.file_path}': {e}")
+        return (attachment, cannot_read_file(attachment.file_path))
+
+    # Create new attachment with base64 content
+    processed = FileAttachment(
+        file_path=attachment.file_path,
+        file_name=attachment.file_name,
+        file_type=attachment.file_type,
+        file_size_bytes=attachment.file_size_bytes,
+        content_base64=content_base64,
+        mime_type=attachment.mime_type,
+    )
+
+    logger.debug(
+        f"Processed attachment: {processed.file_name} "
+        f"({len(content_base64)} base64 chars)"
+    )
+
+    return (processed, None)
+
+
+def create_attachment_hint_display(attachment: FileAttachment) -> str:
+    """Create display string for attachment in chat history.
+
+    Args:
+        attachment: The file attachment.
+
+    Returns:
+        Formatted display string (e.g., "document.pdf (2.5 MB)").
+    """
+    size_str = format_file_size(attachment.file_size_bytes)
+    return f"{attachment.file_name} ({size_str})"
+
+
+def get_attachment_icon(attachment_type: AttachmentType) -> str:
+    """Get the appropriate icon for an attachment type.
+
+    Args:
+        attachment_type: The type of attachment.
+
+    Returns:
+        Icon string for display.
+    """
+    if attachment_type == AttachmentType.PDF:
+        return "\U0001f4c4"  # document emoji
+    else:
+        return "\U0001f5bc\ufe0f"  # framed picture emoji

shotgun/cli/clear.py

@@ -1,13 +1,13 @@
 """Clear command for shotgun CLI."""
 
 import asyncio
-from pathlib import Path
 
 import typer
 from rich.console import Console
 
 from shotgun.agents.conversation import ConversationManager
 from shotgun.logging_config import get_logger
+from shotgun.utils import get_shotgun_home
 
 app = typer.Typer(
     name="clear", help="Clear the conversation history", no_args_is_help=False
@@ -26,7 +26,7 @@ def clear() -> None:
     """
     try:
         # Get conversation file path
-        conversation_file = Path.home() / ".shotgun-sh" / "conversation.json"
+        conversation_file = get_shotgun_home() / "conversation.json"
 
         # Check if file exists
         if not conversation_file.exists():