llm-imageops 1.0.0__py3-none-any.whl

imageops/__init__.py

@@ -0,0 +1,98 @@
+"""ImageOps: Production-grade image preprocessing for LLMs."""
+
+from .config import ImageOpsConfig
+from .core import ImageProcessor, ProcessingResult, ImageOutput
+from .exceptions import *
+from .providers import get_provider, register_provider
+
+__version__ = "1.0.0"
+
+# Simple API
+async def process(
+    image_source: str,
+    provider: str = "anthropic",
+    output_format: str = "base64",
+    progress_callback=None,
+    **kwargs
+):
+    """
+    Simple one-line API to process images.
+    
+    Args:
+        image_source: File path or URL
+        provider: Provider name (default: "anthropic")
+        output_format: "base64" or "file" (default: "base64")
+        progress_callback: Optional async progress callback
+        **kwargs: Additional arguments
+        
+    Returns:
+        ProcessingResult object
+        
+    Example:
+        >>> result = await imageops.process("image.jpg", provider="anthropic")
+        >>> print(result.images[0].data[:50])  # First 50 chars of base64
+    """
+    async with ImageProcessor(provider=provider) as processor:
+        return await processor.process(
+            image_source,
+            output_format=output_format,
+            progress_callback=progress_callback,
+            **kwargs
+        )
+
+
+async def process_batch(
+    image_sources: list,
+    provider: str = "anthropic",
+    output_format: str = "base64",
+    **kwargs
+):
+    """
+    Process multiple images concurrently.
+    
+    Args:
+        image_sources: List of file paths or URLs
+        provider: Provider name (default: "anthropic")
+        output_format: "base64" or "file" (default: "base64")
+        **kwargs: Additional arguments
+        
+    Returns:
+        List of ProcessingResult objects
+        
+    Example:
+        >>> results = await imageops.process_batch(
+        ...     ["img1.jpg", "img2.jpg"],
+        ...     provider="anthropic"
+        ... )
+    """
+    async with ImageProcessor(provider=provider) as processor:
+        return await processor.process_batch(
+            image_sources,
+            output_format=output_format,
+            **kwargs
+        )
+
+
+__all__ = [
+    "ImageOpsConfig",
+    "ImageProcessor",
+    "ProcessingResult",
+    "ImageOutput",
+    "process",
+    "process_batch",
+    "get_provider",
+    "register_provider",
+    # Exceptions
+    "ImageOpsError",
+    "ImageDownloadError",
+    "ImageValidationError",
+    "ImageProcessingError",
+    "ImageCorruptedError",
+    "ImageTooLargeError",
+    "UnsupportedFormatError",
+    "CompressionFailedError",
+    "ProviderNotFoundError",
+    "TimeoutError",
+    "ResourceLimitError",
+]
+

imageops/config.py

@@ -0,0 +1,135 @@
+"""Configuration module with resource limits and security settings."""
+
+from typing import List, Optional
+from pydantic import Field, validator
+
+try:
+    from pydantic_settings import BaseSettings
+except ImportError:
+    try:
+        from pydantic import BaseSettings
+    except ImportError:
+        raise ImportError(
+            "pydantic-settings is required. Install with: pip install pydantic-settings"
+        )
+
+
+class ImageOpsConfig(BaseSettings):
+    """Global configuration with resource limits and security."""
+    
+    # Resource Limits
+    max_image_size_mb: float = Field(
+        100.0,
+        gt=0,
+        description="Maximum input image size in MB"
+    )
+    max_dimension: int = Field(
+        100000,
+        gt=0,
+        description="Maximum width or height in pixels"
+    )
+    max_batch_size: int = Field(
+        50,
+        ge=1,
+        le=1000,
+        description="Maximum number of images in batch"
+    )
+    
+    # Temp Management
+    temp_dir_pattern: str = Field(
+        "imageops_{thread_id}",
+        description="Pattern for temp directory naming"
+    )
+    auto_cleanup: bool = Field(
+        True,
+        description="Auto-cleanup temp files"
+    )
+    
+    # Performance
+    max_concurrent_ops: int = Field(
+        5,
+        ge=1,
+        le=20,
+        description="Max concurrent operations"
+    )
+    download_timeout: float = Field(
+        10.0,
+        gt=0,
+        description="Download timeout in seconds"
+    )
+    processing_timeout: float = Field(
+        300.0,
+        gt=0,
+        description="Max processing time per image in seconds"
+    )
+    
+    # Retry Logic
+    max_download_retries: int = Field(
+        3,
+        ge=0,
+        le=10,
+        description="Max download retries"
+    )
+    retry_backoff_factor: float = Field(
+        2.0,
+        ge=1.0,
+        description="Exponential backoff factor"
+    )
+    
+    # Compression
+    default_quality: int = Field(
+        90,
+        ge=1,
+        le=100,
+        description="Default JPEG quality"
+    )
+    quality_step: int = Field(
+        5,
+        ge=1,
+        le=20,
+        description="Quality reduction step"
+    )
+    min_quality: int = Field(
+        10,
+        ge=1,
+        le=100,
+        description="Minimum JPEG quality"
+    )
+    
+    # Logging
+    enable_logging: bool = Field(
+        True,
+        description="Enable logging"
+    )
+    log_level: str = Field(
+        "INFO",
+        description="Logging level"
+    )
+    log_file: Optional[str] = Field(
+        None,
+        description="Log file path"
+    )
+    
+    # Security
+    validate_paths: bool = Field(
+        True,
+        description="Validate file paths against traversal attacks"
+    )
+    allowed_formats: List[str] = Field(
+        default_factory=lambda: [".jpg", ".jpeg", ".png", ".gif", ".webp"],
+        description="Allowed image formats"
+    )
+    
+    @validator("log_level")
+    def validate_log_level(cls, v):
+        """Validate log level."""
+        valid_levels = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+        v_upper = v.upper()
+        if v_upper not in valid_levels:
+            raise ValueError(f"log_level must be one of {valid_levels}")
+        return v_upper
+    
+    class Config:
+        env_prefix = "IMAGEOPS_"
+        case_sensitive = False
+

imageops/core/__init__.py

@@ -0,0 +1,11 @@
+"""Core module."""
+
+from .processor import ImageProcessor
+from .result import ProcessingResult, ImageOutput
+
+__all__ = [
+    "ImageProcessor",
+    "ProcessingResult",
+    "ImageOutput",
+]
+

imageops/core/processor.py

@@ -0,0 +1,179 @@
+"""Main ImageProcessor orchestrator."""
+
+import asyncio
+import logging
+from typing import List, Literal, Optional
+from ..config import ImageOpsConfig
+from ..providers import get_provider
+from ..utils import setup_logging, InputValidator, download_if_url, CleanupManager
+from ..strategies import process_sequential, ProgressCallback
+from ..exceptions import TimeoutError as ImageOpsTimeoutError
+
+logger = logging.getLogger("imageops")
+
+
+class ImageProcessor:
+    """Main image processor with context manager support."""
+    
+    def __init__(
+        self,
+        provider: str = "anthropic",
+        config: Optional[ImageOpsConfig] = None
+    ):
+        """
+        Initialize ImageProcessor.
+        
+        Args:
+            provider: Provider name (e.g., "anthropic")
+            config: Optional configuration
+        """
+        self.provider_name = provider
+        self.config = config or ImageOpsConfig()
+        self.provider = get_provider(provider)
+        self.cleanup_manager = CleanupManager()
+        self._setup_logging()
+    
+    def _setup_logging(self):
+        """Setup logging based on config."""
+        if self.config.enable_logging:
+            setup_logging(
+                level=self.config.log_level,
+                log_file=self.config.log_file
+            )
+    
+    async def __aenter__(self):
+        """Enter async context."""
+        logger.info(f"ImageProcessor started (provider: {self.provider_name})")
+        return self
+    
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Exit async context - cleanup all temp files."""
+        logger.info("ImageProcessor cleanup started")
+        await self.cleanup_manager.cleanup_all(ignore_errors=True)
+        logger.info("ImageProcessor cleanup complete")
+        return False
+    
+    async def process(
+        self,
+        image_source: str,
+        output_format: Literal["base64", "file"] = "base64",
+        progress_callback: Optional[ProgressCallback] = None,
+        timeout: Optional[float] = None,
+        thread_id: Optional[str] = None,
+        quality: int = 90,
+        **kwargs
+    ):
+        """
+        Process single image with timeout.
+        
+        Args:
+            image_source: File path or URL
+            output_format: "base64" or "file"
+            progress_callback: Optional progress callback
+            timeout: Processing timeout in seconds
+            thread_id: Optional thread ID for temp directories
+            quality: JPEG quality (1-100)
+            
+        Returns:
+            ProcessingResult object
+            
+        Raises:
+            TimeoutError: If processing exceeds timeout
+        """
+        timeout = timeout or self.config.processing_timeout
+        
+        try:
+            result = await asyncio.wait_for(
+                self._process_internal(
+                    image_source,
+                    output_format,
+                    progress_callback,
+                    thread_id,
+                    quality
+                ),
+                timeout=timeout
+            )
+            return result
+            
+        except asyncio.TimeoutError:
+            raise ImageOpsTimeoutError(
+                f"Processing timeout after {timeout}s: {image_source}"
+            )
+    
+    async def _process_internal(
+        self,
+        image_source: str,
+        output_format: Literal["base64", "file"],
+        progress_callback: Optional[ProgressCallback],
+        thread_id: Optional[str],
+        quality: int
+    ):
+        """Internal processing logic."""
+        # Download if URL
+        local_path, is_temp = await download_if_url(
+            image_source,
+            timeout=self.config.download_timeout,
+            max_retries=self.config.max_download_retries,
+            backoff_factor=self.config.retry_backoff_factor
+        )
+        
+        if is_temp:
+            self.cleanup_manager.track_file(local_path)
+        
+        # Validate file path
+        validated_path = InputValidator.validate_file_path(
+            local_path,
+            max_size_mb=self.config.max_image_size_mb
+        )
+        
+        # Process using sequential strategy
+        result = await process_sequential(
+            validated_path,
+            self.provider,
+            output_format,
+            thread_id,
+            progress_callback,
+            quality
+        )
+        
+        return result
+    
+    async def process_batch(
+        self,
+        image_sources: List[str],
+        output_format: Literal["base64", "file"] = "base64",
+        max_concurrent: Optional[int] = None,
+        **kwargs
+    ):
+        """
+        Process multiple images concurrently.
+        
+        Args:
+            image_sources: List of file paths or URLs
+            output_format: "base64" or "file"
+            max_concurrent: Max concurrent operations
+            
+        Returns:
+            List of ProcessingResult objects
+        """
+        # Validate batch size
+        if len(image_sources) > self.config.max_batch_size:
+            raise ValueError(
+                f"Batch size {len(image_sources)} exceeds limit "
+                f"of {self.config.max_batch_size}"
+            )
+        
+        max_concurrent = max_concurrent or self.config.max_concurrent_ops
+        semaphore = asyncio.Semaphore(max_concurrent)
+        
+        async def process_one(source: str):
+            async with semaphore:
+                return await self.process(source, output_format, **kwargs)
+        
+        results = await asyncio.gather(
+            *[process_one(source) for source in image_sources],
+            return_exceptions=True
+        )
+        
+        return results
+

imageops/core/result.py

@@ -0,0 +1,93 @@
+"""Result types and data classes."""
+
+from datetime import datetime
+from typing import Dict, List, Literal, Optional
+from pydantic import BaseModel, Field
+
+
+class ImageOutput(BaseModel):
+    """Single processed image output."""
+    
+    # Based on output_format parameter
+    data: str = Field(..., description="base64 string OR file path")
+    format: Literal["base64", "file"] = Field(..., description="Output format")
+    
+    # Metadata
+    media_type: str = Field(..., description="image/jpeg, image/png, etc.")
+    width: int = Field(..., gt=0, description="Image width in pixels")
+    height: int = Field(..., gt=0, description="Image height in pixels")
+    size_bytes: int = Field(..., ge=0, description="Image size in bytes")
+    
+    # Processing info
+    was_resized: bool = Field(False, description="Whether image was resized")
+    was_compressed: bool = Field(False, description="Whether image was compressed")
+    was_sliced: bool = Field(False, description="Whether image was sliced")
+    compression_quality: Optional[int] = Field(None, ge=1, le=100, description="Compression quality used")
+    
+    def to_data_uri(self) -> str:
+        """
+        Convert to data URI format with media type prefix.
+        
+        Returns:
+            Data URI string like: data:image/jpeg;base64,<base64_data>
+            
+        Example:
+            >>> img = ImageOutput(data="abc123...", format="base64", media_type="image/jpeg", ...)
+            >>> img.to_data_uri()
+            'data:image/jpeg;base64,abc123...'
+        """
+        if self.format != "base64":
+            raise ValueError("to_data_uri() only works with base64 format")
+        
+        return f"data:{self.media_type};base64,{self.data}"
+    
+    class Config:
+        frozen = True  # Immutable
+
+
+class ProcessingResult(BaseModel):
+    """Complete processing result."""
+    
+    success: bool = Field(..., description="Processing success status")
+    
+    # Outputs
+    images: List[ImageOutput] = Field(..., description="Single image OR multiple if sliced")
+    output_format: Literal["base64", "file"] = Field(..., description="Output format")
+    
+    # Original info
+    original_path: str = Field(..., description="Original input path")
+    original_metadata: Dict = Field(..., description="Original image metadata")
+    
+    # Processing stats
+    provider: str = Field(..., description="Provider name")
+    strategy_used: str = Field(..., description="Processing strategy used")
+    processing_time_ms: float = Field(..., ge=0, description="Processing time in milliseconds")
+    was_sliced: bool = Field(..., description="Whether image was sliced")
+    slice_count: int = Field(..., ge=1, description="Number of slices")
+    created_at: datetime = Field(default_factory=datetime.utcnow, description="Result creation timestamp")
+    
+    def to_anthropic_format(self) -> List[Dict]:
+        """
+        Convert to Anthropic message content format.
+        
+        Returns:
+            List of formatted image content dicts
+        """
+        return [
+            {
+                "type": "image",
+                "source": {
+                    "type": "base64" if img.format == "base64" else "url",
+                    "media_type": img.media_type,
+                    "data": img.data if img.format == "base64" else None
+                }
+            }
+            for img in self.images
+        ]
+    
+    async def cleanup(self):
+        """Clean up temp files if output_format='file'."""
+        if self.output_format == "file":
+            from ..utils.cleanup import cleanup_files
+            await cleanup_files([img.data for img in self.images])
+

imageops/exceptions.py

@@ -0,0 +1,57 @@
+"""Comprehensive exception hierarchy for imageops."""
+
+
+class ImageOpsError(Exception):
+    """Base exception for all imageops errors."""
+    pass
+
+
+class ImageDownloadError(ImageOpsError):
+    """Failed to download image from URL."""
+    pass
+
+
+class ImageValidationError(ImageOpsError):
+    """Image validation failed (format, size, etc.)."""
+    pass
+
+
+class ImageProcessingError(ImageOpsError):
+    """Error during image processing operations."""
+    pass
+
+
+class ImageCorruptedError(ImageOpsError):
+    """Image file is corrupted or unreadable."""
+    pass
+
+
+class ImageTooLargeError(ImageOpsError):
+    """Image exceeds size or dimension limits."""
+    pass
+
+
+class UnsupportedFormatError(ImageOpsError):
+    """Image format is not supported."""
+    pass
+
+
+class CompressionFailedError(ImageProcessingError):
+    """Cannot compress image to required size."""
+    pass
+
+
+class ProviderNotFoundError(ImageOpsError):
+    """Unknown or unsupported provider."""
+    pass
+
+
+class TimeoutError(ImageOpsError):
+    """Operation timed out."""
+    pass
+
+
+class ResourceLimitError(ImageOpsError):
+    """Resource limit exceeded (memory, file handles, etc.)."""
+    pass
+

imageops/operations/__init__.py

@@ -0,0 +1,20 @@
+"""Operations module."""
+
+from .compress import compress_to_size
+from .encode import encode_to_base64, get_image_with_media_type
+from .resize import resize_width, resize_height, fix_exif_orientation, handle_alpha_channel
+from .slice import slice_by_height, handle_animated_gif, handle_wide_panorama
+
+__all__ = [
+    "compress_to_size",
+    "encode_to_base64",
+    "get_image_with_media_type",
+    "resize_width",
+    "resize_height",
+    "fix_exif_orientation",
+    "handle_alpha_channel",
+    "slice_by_height",
+    "handle_animated_gif",
+    "handle_wide_panorama",
+]
+