abstractcore 2.4.4__py3-none-any.whl → 2.4.6__py3-none-any.whl

abstractcore/media/utils/image_scaler.py

@@ -0,0 +1,306 @@
+"""
+Image scaling utility for AbstractCore media handling.
+
+Provides intelligent image scaling based on model-specific requirements
+and capabilities for vision models.
+"""
+
+from typing import Tuple, Optional, Union, Dict, Any
+from enum import Enum
+from pathlib import Path
+import logging
+
+try:
+    from PIL import Image, ImageOps
+    PIL_AVAILABLE = True
+except ImportError:
+    PIL_AVAILABLE = False
+
+from ..base import MediaProcessingError
+
+
+class ScalingMode(Enum):
+    """Image scaling modes."""
+    FIT = "fit"          # Scale to fit within target size, maintaining aspect ratio
+    FILL = "fill"        # Scale to fill target size, may crop, maintaining aspect ratio
+    STRETCH = "stretch"  # Stretch to exact target size, may distort aspect ratio
+    PAD = "pad"          # Scale to fit and pad with background to exact target size
+    CROP_CENTER = "crop_center"  # Scale to fill and crop from center
+
+
+class ModelOptimizedScaler:
+    """
+    Intelligent image scaler that optimizes images for specific vision models.
+
+    Uses model capability information to determine optimal scaling strategies.
+    """
+
+    def __init__(self):
+        self.logger = logging.getLogger(__name__)
+
+        if not PIL_AVAILABLE:
+            raise MediaProcessingError("PIL (Pillow) is required for image scaling")
+
+    def get_optimal_resolution(self, model_name: str, original_size: Tuple[int, int],
+                             model_capabilities: Optional[Dict[str, Any]] = None) -> Tuple[int, int]:
+        """
+        Get optimal resolution for a specific model.
+
+        Args:
+            model_name: Name of the model
+            original_size: Original image size (width, height)
+            model_capabilities: Model capability information
+
+        Returns:
+            Optimal target size (width, height)
+        """
+        if model_capabilities is None:
+            model_capabilities = self._get_model_capabilities(model_name)
+
+        max_resolution = model_capabilities.get("max_image_resolution", "variable")
+        image_patch_size = model_capabilities.get("image_patch_size", 16)
+        adaptive_windowing = model_capabilities.get("adaptive_windowing", False)
+
+        # Handle different resolution strategies
+        if max_resolution == "variable":
+            return self._optimize_variable_resolution(original_size, image_patch_size)
+        elif max_resolution == "896x896":
+            return (896, 896)
+        elif max_resolution == "3584x3584":
+            return self._optimize_large_resolution(original_size, (3584, 3584), image_patch_size)
+        elif "x" in str(max_resolution):
+            # Parse specific resolution like "1568x1568"
+            w, h = map(int, str(max_resolution).split("x"))
+            return (w, h)
+        else:
+            # Default fallback
+            return self._optimize_variable_resolution(original_size, image_patch_size)
+
+    def _optimize_variable_resolution(self, original_size: Tuple[int, int],
+                                    patch_size: int = 16) -> Tuple[int, int]:
+        """Optimize for variable resolution models like Qwen3-VL."""
+        width, height = original_size
+
+        # For variable resolution, aim for reasonable size that's efficient
+        # while maintaining good quality
+        max_dimension = 1024  # Good balance for most use cases
+
+        # Scale down if too large
+        if max(width, height) > max_dimension:
+            if width > height:
+                new_width = max_dimension
+                new_height = int(height * (max_dimension / width))
+            else:
+                new_height = max_dimension
+                new_width = int(width * (max_dimension / height))
+        else:
+            new_width, new_height = width, height
+
+        # Round to nearest patch size multiple for efficiency
+        new_width = ((new_width + patch_size - 1) // patch_size) * patch_size
+        new_height = ((new_height + patch_size - 1) // patch_size) * patch_size
+
+        return (new_width, new_height)
+
+    def _optimize_large_resolution(self, original_size: Tuple[int, int],
+                                 max_size: Tuple[int, int],
+                                 patch_size: int = 14) -> Tuple[int, int]:
+        """Optimize for large resolution models like Qwen2.5-VL."""
+        width, height = original_size
+        max_width, max_height = max_size
+
+        # Scale to fit within max size while maintaining aspect ratio
+        scale = min(max_width / width, max_height / height)
+
+        if scale < 1:  # Only scale down, never up
+            new_width = int(width * scale)
+            new_height = int(height * scale)
+        else:
+            new_width, new_height = width, height
+
+        # Round to nearest patch size multiple
+        new_width = ((new_width + patch_size - 1) // patch_size) * patch_size
+        new_height = ((new_height + patch_size - 1) // patch_size) * patch_size
+
+        return (new_width, new_height)
+
+    def scale_image(self, image: Image.Image, target_size: Tuple[int, int],
+                   mode: ScalingMode = ScalingMode.FIT,
+                   background_color: Tuple[int, int, int] = (255, 255, 255)) -> Image.Image:
+        """
+        Scale image to target size using specified mode.
+
+        Args:
+            image: PIL Image to scale
+            target_size: Target size (width, height)
+            mode: Scaling mode
+            background_color: Background color for padding (RGB)
+
+        Returns:
+            Scaled PIL Image
+        """
+        target_width, target_height = target_size
+
+        if mode == ScalingMode.FIT:
+            # Scale to fit within target size, maintaining aspect ratio
+            image.thumbnail((target_width, target_height), Image.Resampling.LANCZOS)
+            return image
+
+        elif mode == ScalingMode.FILL:
+            # Scale to fill target size, may crop
+            return ImageOps.fit(image, target_size, Image.Resampling.LANCZOS)
+
+        elif mode == ScalingMode.STRETCH:
+            # Stretch to exact target size
+            return image.resize(target_size, Image.Resampling.LANCZOS)
+
+        elif mode == ScalingMode.PAD:
+            # Scale to fit and pad to exact size
+            image.thumbnail((target_width, target_height), Image.Resampling.LANCZOS)
+
+            # Create new image with background color
+            new_image = Image.new('RGB', target_size, background_color)
+
+            # Paste scaled image centered
+            paste_x = (target_width - image.width) // 2
+            paste_y = (target_height - image.height) // 2
+            new_image.paste(image, (paste_x, paste_y))
+
+            return new_image
+
+        elif mode == ScalingMode.CROP_CENTER:
+            # Scale to fill and crop from center
+            return ImageOps.fit(image, target_size, Image.Resampling.LANCZOS, centering=(0.5, 0.5))
+
+        else:
+            raise MediaProcessingError(f"Unknown scaling mode: {mode}")
+
+    def scale_for_model(self, image: Image.Image, model_name: str,
+                       scaling_mode: ScalingMode = ScalingMode.FIT,
+                       model_capabilities: Optional[Dict[str, Any]] = None) -> Image.Image:
+        """
+        Scale image optimally for a specific model.
+
+        Args:
+            image: PIL Image to scale
+            model_name: Name of the target model
+            scaling_mode: How to scale the image
+            model_capabilities: Model capability information
+
+        Returns:
+            Optimally scaled PIL Image for the model
+        """
+        original_size = image.size
+        target_size = self.get_optimal_resolution(model_name, original_size, model_capabilities)
+
+        self.logger.debug(f"Scaling image for {model_name}: {original_size} -> {target_size}")
+
+        # For fixed resolution models, always use PAD mode to maintain exact size
+        if model_capabilities and model_capabilities.get("max_image_resolution") == "896x896":
+            scaling_mode = ScalingMode.PAD
+
+        return self.scale_image(image, target_size, scaling_mode)
+
+    def _get_model_capabilities(self, model_name: str) -> Dict[str, Any]:
+        """
+        Get model capabilities from the capabilities JSON.
+
+        Args:
+            model_name: Name of the model
+
+        Returns:
+            Model capabilities dictionary
+        """
+        try:
+            from ..capabilities import get_media_capabilities
+            return get_media_capabilities(model_name).__dict__
+        except ImportError:
+            # Fallback capability detection
+            return self._fallback_model_capabilities(model_name)
+
+    def _fallback_model_capabilities(self, model_name: str) -> Dict[str, Any]:
+        """Fallback capability detection when capabilities module not available."""
+        model_lower = model_name.lower()
+
+        # Gemma models - fixed 896x896
+        if any(gem in model_lower for gem in ["gemma3", "gemma-3n"]):
+            return {
+                "max_image_resolution": "896x896",
+                "image_patch_size": 16,
+                "adaptive_windowing": True
+            }
+
+        # Qwen2.5-VL models - up to 3584x3584
+        elif "qwen2.5" in model_lower and "vl" in model_lower:
+            return {
+                "max_image_resolution": "3584x3584",
+                "image_patch_size": 14,
+                "pixel_grouping": "28x28"
+            }
+
+        # Qwen3-VL models - variable resolution
+        elif "qwen3" in model_lower and "vl" in model_lower:
+            return {
+                "max_image_resolution": "variable",
+                "image_patch_size": 16,
+                "pixel_grouping": "32x32"
+            }
+
+        # Claude models - up to 1568x1568
+        elif "claude" in model_lower:
+            return {
+                "max_image_resolution": "1568x1568",
+                "image_patch_size": 14
+            }
+
+        # Default fallback
+        else:
+            return {
+                "max_image_resolution": "variable",
+                "image_patch_size": 16
+            }
+
+
+# Convenience functions for easy usage
+_scaler_instance = None
+
+def get_scaler() -> ModelOptimizedScaler:
+    """Get shared scaler instance."""
+    global _scaler_instance
+    if _scaler_instance is None:
+        _scaler_instance = ModelOptimizedScaler()
+    return _scaler_instance
+
+def scale_image_for_model(image: Union[Image.Image, str, Path],
+                         model_name: str,
+                         scaling_mode: ScalingMode = ScalingMode.FIT) -> Image.Image:
+    """
+    Convenience function to scale an image for a specific model.
+
+    Args:
+        image: PIL Image, or path to image file
+        model_name: Name of the target model
+        scaling_mode: How to scale the image
+
+    Returns:
+        Optimally scaled PIL Image
+    """
+    if isinstance(image, (str, Path)):
+        image = Image.open(image)
+
+    scaler = get_scaler()
+    return scaler.scale_for_model(image, model_name, scaling_mode)
+
+def get_optimal_size_for_model(model_name: str, original_size: Tuple[int, int]) -> Tuple[int, int]:
+    """
+    Get optimal image size for a specific model.
+
+    Args:
+        model_name: Name of the target model
+        original_size: Original image size (width, height)
+
+    Returns:
+        Optimal target size (width, height)
+    """
+    scaler = get_scaler()
+    return scaler.get_optimal_resolution(model_name, original_size)

abstractcore/providers/anthropic_provider.py

@@ -47,8 +47,7 @@ class AnthropicProvider(BaseProvider):
         # Initialize tool handler
         self.tool_handler = UniversalToolHandler(model)
 
-        # Store configuration (remove duplicate max_tokens)
-        self.temperature = kwargs.get("temperature", 0.7)
+        # Store provider-specific configuration
         self.top_p = kwargs.get("top_p", 1.0)
         self.top_k = kwargs.get("top_k", None)
 
@@ -132,6 +131,19 @@ class AnthropicProvider(BaseProvider):
         if kwargs.get("top_k") or self.top_k:
             call_params["top_k"] = kwargs.get("top_k", self.top_k)
 
+        # Handle seed parameter (Anthropic doesn't support seed natively)
+        seed_value = kwargs.get("seed", self.seed)
+        if seed_value is not None:
+            import warnings
+            warnings.warn(
+                f"Seed parameter ({seed_value}) is not supported by Anthropic Claude API. "
+                f"For deterministic outputs, use temperature=0.0 which may provide more consistent results, "
+                f"though true determinism is not guaranteed.",
+                UserWarning,
+                stacklevel=3
+            )
+            self.logger.warning(f"Seed {seed_value} requested but not supported by Anthropic API")
+
         # Handle structured output using the "tool trick"
         structured_tool_name = None
         if response_model and PYDANTIC_AVAILABLE:

abstractcore/providers/base.py

@@ -570,8 +570,32 @@ class BaseProvider(AbstractCoreInterface, ABC):
         result_kwargs = kwargs.copy()
         result_kwargs["max_output_tokens"] = effective_max_output
 
+        # Add unified generation parameters with fallback hierarchy: kwargs → instance → defaults
+        result_kwargs["temperature"] = result_kwargs.get("temperature", self.temperature)
+        if self.seed is not None:
+            result_kwargs["seed"] = result_kwargs.get("seed", self.seed)
+
         return result_kwargs
 
+    def _extract_generation_params(self, **kwargs) -> Dict[str, Any]:
+        """
+        Extract generation parameters with consistent fallback hierarchy.
+        
+        Returns:
+            Dict containing temperature, seed, and other generation parameters
+        """
+        params = {}
+        
+        # Temperature (always present)
+        params["temperature"] = kwargs.get("temperature", self.temperature)
+        
+        # Seed (only if not None)
+        seed_value = kwargs.get("seed", self.seed)
+        if seed_value is not None:
+            params["seed"] = seed_value
+            
+        return params
+
     def _get_provider_max_tokens_param(self, kwargs: Dict[str, Any]) -> int:
         """
         Extract the appropriate max tokens parameter for this provider.

abstractcore/providers/huggingface_provider.py

@@ -68,6 +68,7 @@ class HuggingFaceProvider(BaseProvider):
         # Initialize tool handler
         self.tool_handler = UniversalToolHandler(model)
 
+        # Store provider-specific configuration
         self.n_gpu_layers = n_gpu_layers
         self.model_type = None  # Will be "transformers" or "gguf"
         self.device = device
@@ -537,14 +538,15 @@ class HuggingFaceProvider(BaseProvider):
         # Generation parameters using unified system
         generation_kwargs = self._prepare_generation_kwargs(**kwargs)
         max_new_tokens = self._get_provider_max_tokens_param(generation_kwargs)
-        temperature = kwargs.get("temperature", 0.7)
+        temperature = kwargs.get("temperature", self.temperature)
         top_p = kwargs.get("top_p", 0.9)
+        seed_value = kwargs.get("seed", self.seed)
 
         try:
             if stream:
-                return self._stream_generate_transformers_with_tools(input_text, max_new_tokens, temperature, top_p, tools, kwargs.get('tool_call_tags'))
+                return self._stream_generate_transformers_with_tools(input_text, max_new_tokens, temperature, top_p, tools, kwargs.get('tool_call_tags'), seed_value)
             else:
-                response = self._single_generate_transformers(input_text, max_new_tokens, temperature, top_p)
+                response = self._single_generate_transformers(input_text, max_new_tokens, temperature, top_p, seed_value)
 
                 # Handle tool execution for prompted models
                 if tools and self.tool_handler.supports_prompted and response.content:
@@ -651,11 +653,16 @@ class HuggingFaceProvider(BaseProvider):
         generation_kwargs = {
             "messages": chat_messages,
             "max_tokens": max_output_tokens,  # This is max_output_tokens for llama-cpp
-            "temperature": kwargs.get("temperature", 0.7),
+            "temperature": kwargs.get("temperature", self.temperature),
             "top_p": kwargs.get("top_p", 0.9),
             "stream": stream
         }
 
+        # Add seed if provided (GGUF/llama-cpp supports seed)
+        seed_value = kwargs.get("seed", self.seed)
+        if seed_value is not None:
+            generation_kwargs["seed"] = seed_value
+
         # Handle tools - both native and prompted support
         has_native_tools = False
         if tools:
@@ -846,9 +853,16 @@ class HuggingFaceProvider(BaseProvider):
                     )
 
     def _single_generate_transformers(self, input_text: str, max_new_tokens: int,
-                                     temperature: float, top_p: float) -> GenerateResponse:
+                                     temperature: float, top_p: float, seed: Optional[int] = None) -> GenerateResponse:
         """Generate single response using transformers (original implementation)"""
         try:
+            # Set seed for deterministic generation if provided
+            if seed is not None:
+                import torch
+                torch.manual_seed(seed)
+                if torch.cuda.is_available():
+                    torch.cuda.manual_seed_all(seed)
+
             outputs = self.pipeline(
                 input_text,
                 max_new_tokens=max_new_tokens,
@@ -902,11 +916,11 @@ class HuggingFaceProvider(BaseProvider):
         }
 
     def _stream_generate_transformers(self, input_text: str, max_new_tokens: int,
-                                     temperature: float, top_p: float, tool_call_tags: Optional[str] = None) -> Iterator[GenerateResponse]:
+                                     temperature: float, top_p: float, tool_call_tags: Optional[str] = None, seed: Optional[int] = None) -> Iterator[GenerateResponse]:
         """Stream response using transformers (simulated, original implementation) with tool tag rewriting support"""
         try:
             # HuggingFace doesn't have native streaming, so we simulate it
-            full_response = self._single_generate_transformers(input_text, max_new_tokens, temperature, top_p)
+            full_response = self._single_generate_transformers(input_text, max_new_tokens, temperature, top_p, seed)
 
             if full_response.content:
                 # Apply tool tag rewriting if enabled
@@ -1039,12 +1053,12 @@ class HuggingFaceProvider(BaseProvider):
     def _stream_generate_transformers_with_tools(self, input_text: str, max_new_tokens: int,
                                                temperature: float, top_p: float,
                                                tools: Optional[List[Dict[str, Any]]] = None,
-                                               tool_call_tags: Optional[str] = None) -> Iterator[GenerateResponse]:
+                                               tool_call_tags: Optional[str] = None, seed: Optional[int] = None) -> Iterator[GenerateResponse]:
         """Stream generate with tool execution at the end"""
         collected_content = ""
 
         # Stream the response content
-        for chunk in self._stream_generate_transformers(input_text, max_new_tokens, temperature, top_p, tool_call_tags):
+        for chunk in self._stream_generate_transformers(input_text, max_new_tokens, temperature, top_p, tool_call_tags, seed):
             collected_content += chunk.content
             yield chunk
 

abstractcore/providers/lmstudio_provider.py

@@ -196,11 +196,16 @@ class LMStudioProvider(BaseProvider):
             "model": self.model,
             "messages": chat_messages,
             "stream": stream,
-            "temperature": kwargs.get("temperature", 0.7),
+            "temperature": kwargs.get("temperature", self.temperature),
             "max_tokens": max_output_tokens,  # LMStudio uses max_tokens for output tokens
             "top_p": kwargs.get("top_p", 0.9),
         }
 
+        # Add seed if provided (LMStudio supports seed via OpenAI-compatible API)
+        seed_value = kwargs.get("seed", self.seed)
+        if seed_value is not None:
+            payload["seed"] = seed_value
+
         if stream:
             # Return streaming response - BaseProvider will handle tag rewriting via UnifiedStreamProcessor
             return self._stream_generate(payload)

abstractcore/providers/mlx_provider.py

@@ -189,14 +189,15 @@ class MLXProvider(BaseProvider):
         # MLX generation parameters using unified system
         generation_kwargs = self._prepare_generation_kwargs(**kwargs)
         max_tokens = self._get_provider_max_tokens_param(generation_kwargs)
-        temperature = kwargs.get("temperature", 0.7)
+        temperature = kwargs.get("temperature", self.temperature)
         top_p = kwargs.get("top_p", 0.9)
+        seed_value = kwargs.get("seed", self.seed)
 
         try:
             if stream:
-                return self._stream_generate_with_tools(full_prompt, max_tokens, temperature, top_p, tools, kwargs.get('tool_call_tags'))
+                return self._stream_generate_with_tools(full_prompt, max_tokens, temperature, top_p, tools, kwargs.get('tool_call_tags'), seed_value)
             else:
-                response = self._single_generate(full_prompt, max_tokens, temperature, top_p)
+                response = self._single_generate(full_prompt, max_tokens, temperature, top_p, seed_value)
 
                 # Handle tool execution for prompted models
                 if tools and self.tool_handler.supports_prompted and response.content:
@@ -256,9 +257,15 @@ class MLXProvider(BaseProvider):
 
         return full_prompt
 
-    def _single_generate(self, prompt: str, max_tokens: int, temperature: float, top_p: float) -> GenerateResponse:
+    def _single_generate(self, prompt: str, max_tokens: int, temperature: float, top_p: float, seed: Optional[int] = None) -> GenerateResponse:
         """Generate single response"""
 
+        # Handle seed parameter (MLX supports seed via mx.random.seed)
+        if seed is not None:
+            import mlx.core as mx
+            mx.random.seed(seed)
+            self.logger.debug(f"Set MLX random seed to {seed} for deterministic generation")
+
         # Try different MLX API signatures
         try:
             # Try new mlx-lm API
@@ -305,9 +312,15 @@ class MLXProvider(BaseProvider):
             "total_tokens": total_tokens
         }
 
-    def _stream_generate(self, prompt: str, max_tokens: int, temperature: float, top_p: float, tool_call_tags: Optional[str] = None) -> Iterator[GenerateResponse]:
+    def _stream_generate(self, prompt: str, max_tokens: int, temperature: float, top_p: float, tool_call_tags: Optional[str] = None, seed: Optional[int] = None) -> Iterator[GenerateResponse]:
         """Generate real streaming response using MLX stream_generate with tool tag rewriting support"""
         try:
+            # Handle seed parameter (MLX supports seed via mx.random.seed)
+            if seed is not None:
+                import mlx.core as mx
+                mx.random.seed(seed)
+                self.logger.debug(f"Set MLX random seed to {seed} for deterministic streaming generation")
+
             # Initialize tool tag rewriter if needed
             rewriter = None
             buffer = ""
@@ -366,12 +379,12 @@ class MLXProvider(BaseProvider):
     def _stream_generate_with_tools(self, full_prompt: str, max_tokens: int,
                                    temperature: float, top_p: float,
                                    tools: Optional[List[Dict[str, Any]]] = None,
-                                   tool_call_tags: Optional[str] = None) -> Iterator[GenerateResponse]:
+                                   tool_call_tags: Optional[str] = None, seed: Optional[int] = None) -> Iterator[GenerateResponse]:
         """Stream generate with tool execution at the end"""
         collected_content = ""
 
         # Stream the response content
-        for chunk in self._stream_generate(full_prompt, max_tokens, temperature, top_p, tool_call_tags):
+        for chunk in self._stream_generate(full_prompt, max_tokens, temperature, top_p, tool_call_tags, seed):
             collected_content += chunk.content
             yield chunk
 

abstractcore/providers/ollama_provider.py

@@ -132,11 +132,16 @@ class OllamaProvider(BaseProvider):
             "model": self.model,
             "stream": stream,
             "options": {
-                "temperature": kwargs.get("temperature", 0.7),
+                "temperature": kwargs.get("temperature", self.temperature),
                 "num_predict": max_output_tokens,  # Ollama uses num_predict for max output tokens
             }
         }
 
+        # Add seed if provided (Ollama supports seed for deterministic outputs)
+        seed_value = kwargs.get("seed", self.seed)
+        if seed_value is not None:
+            payload["options"]["seed"] = seed_value
+
         # Add structured output support (Ollama native JSON schema)
         if response_model and PYDANTIC_AVAILABLE:
             json_schema = response_model.model_json_schema()

abstractcore/providers/openai_provider.py

@@ -50,8 +50,7 @@ class OpenAIProvider(BaseProvider):
         # Preflight check: validate model exists
         self._validate_model_exists()
 
-        # Store configuration (remove duplicate max_tokens)
-        self.temperature = kwargs.get("temperature", 0.7)
+        # Store provider-specific configuration
         self.top_p = kwargs.get("top_p", 1.0)
         self.frequency_penalty = kwargs.get("frequency_penalty", 0.0)
         self.presence_penalty = kwargs.get("presence_penalty", 0.0)
@@ -125,6 +124,11 @@ class OpenAIProvider(BaseProvider):
             call_params["top_p"] = kwargs.get("top_p", self.top_p)
             call_params["frequency_penalty"] = kwargs.get("frequency_penalty", self.frequency_penalty)
             call_params["presence_penalty"] = kwargs.get("presence_penalty", self.presence_penalty)
+            
+            # Add seed if provided (OpenAI supports seed for deterministic outputs)
+            seed_value = kwargs.get("seed", self.seed)
+            if seed_value is not None:
+                call_params["seed"] = seed_value
 
         # Handle different token parameter names for different model families
         if self._uses_max_completion_tokens():