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

shotgun/agents/tools/web_search/openai.py

@@ -1,5 +1,7 @@
 """OpenAI web search tool implementation."""
 
+import asyncio
+
 from openai import AsyncOpenAI
 from opentelemetry import trace
 
@@ -15,6 +17,9 @@ logger = get_logger(__name__)
 # Global prompt loader instance
 prompt_loader = PromptLoader()
 
+# Timeout for web search API call (in seconds)
+WEB_SEARCH_TIMEOUT = 120  # 2 minutes
+
 
 @register_tool(
     category=ToolCategory.WEB_RESEARCH,
@@ -64,29 +69,43 @@ async def openai_web_search_tool(query: str) -> str:
         )
 
         client = AsyncOpenAI(api_key=api_key)
-        response = await client.responses.create(
-            model="gpt-5-mini",
-            input=[
-                {"role": "user", "content": [{"type": "input_text", "text": prompt}]}
-            ],
-            text={
-                "format": {"type": "text"},
-                "verbosity": "high",
-            },  # Increased from medium
-            reasoning={"effort": "medium", "summary": "auto"},
-            tools=[
-                {
-                    "type": "web_search",
-                    "user_location": {"type": "approximate"},
-                    "search_context_size": "high",  # Increased from low for more context
-                }
-            ],
-            store=False,
-            include=[
-                "reasoning.encrypted_content",
-                "web_search_call.action.sources",  # pyright: ignore[reportArgumentType]
-            ],
-        )
+
+        # Wrap API call with timeout to prevent indefinite hangs
+        try:
+            response = await asyncio.wait_for(
+                client.responses.create(
+                    model="gpt-5-mini",
+                    input=[
+                        {
+                            "role": "user",
+                            "content": [{"type": "input_text", "text": prompt}],
+                        }
+                    ],
+                    text={
+                        "format": {"type": "text"},
+                        "verbosity": "high",
+                    },
+                    reasoning={"effort": "medium", "summary": "auto"},
+                    tools=[
+                        {
+                            "type": "web_search",
+                            "user_location": {"type": "approximate"},
+                            "search_context_size": "high",
+                        }
+                    ],
+                    store=False,
+                    include=[
+                        "reasoning.encrypted_content",
+                        "web_search_call.action.sources",  # pyright: ignore[reportArgumentType]
+                    ],
+                ),
+                timeout=WEB_SEARCH_TIMEOUT,
+            )
+        except asyncio.TimeoutError:
+            error_msg = f"Web search timed out after {WEB_SEARCH_TIMEOUT} seconds"
+            logger.warning("⏱️ %s", error_msg)
+            span.set_attribute("output.value", f"**Error:**\n {error_msg}\n")
+            return error_msg
 
         result_text = response.output_text or "No content returned"
 

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,
+    )