abstractcore 2.5.0__py3-none-any.whl → 2.5.3__py3-none-any.whl

abstractcore/providers/lmstudio_provider.py

@@ -25,6 +25,7 @@ class LMStudioProvider(BaseProvider):
 
     def __init__(self, model: str = "local-model", base_url: str = "http://localhost:1234/v1", **kwargs):
         super().__init__(model, **kwargs)
+        self.provider = "lmstudio"
 
         # Initialize tool handler
         self.tool_handler = UniversalToolHandler(model)
@@ -201,12 +202,34 @@ class LMStudioProvider(BaseProvider):
             "max_tokens": max_output_tokens,  # LMStudio uses max_tokens for output tokens
             "top_p": kwargs.get("top_p", 0.9),
         }
+        
+        # Add additional generation parameters if provided (OpenAI-compatible)
+        if "frequency_penalty" in kwargs:
+            payload["frequency_penalty"] = kwargs["frequency_penalty"]
+        if "presence_penalty" in kwargs:
+            payload["presence_penalty"] = kwargs["presence_penalty"]
+        if "repetition_penalty" in kwargs:
+            # Some models support repetition_penalty directly
+            payload["repetition_penalty"] = kwargs["repetition_penalty"]
 
         # 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
 
+        # Add structured output support (OpenAI-compatible format)
+        # LMStudio supports native structured outputs using the response_format parameter
+        # This provides server-side guaranteed schema compliance
+        if response_model and PYDANTIC_AVAILABLE:
+            json_schema = response_model.model_json_schema()
+            payload["response_format"] = {
+                "type": "json_schema",
+                "json_schema": {
+                    "name": response_model.__name__,
+                    "schema": json_schema
+                }
+            }
+
         if stream:
             # Return streaming response - BaseProvider will handle tag rewriting via UnifiedStreamProcessor
             return self._stream_generate(payload)
@@ -412,8 +435,21 @@ class LMStudioProvider(BaseProvider):
         return handler
 
     def list_available_models(self, **kwargs) -> List[str]:
-        """List available models from LMStudio server."""
+        """
+        List available models from LMStudio server.
+
+        Args:
+            **kwargs: Optional parameters including:
+                - base_url: LMStudio server URL
+                - input_capabilities: List of ModelInputCapability enums to filter by input capability
+                - output_capabilities: List of ModelOutputCapability enums to filter by output capability
+
+        Returns:
+            List of model names, optionally filtered by capabilities
+        """
         try:
+            from .model_capabilities import filter_models_by_capabilities
+
             # Use provided base_url or fall back to instance base_url
             base_url = kwargs.get('base_url', self.base_url)
 
@@ -421,7 +457,21 @@ class LMStudioProvider(BaseProvider):
             if response.status_code == 200:
                 data = response.json()
                 models = [model["id"] for model in data.get("data", [])]
-                return sorted(models)
+                models = sorted(models)
+
+                # Apply new capability filtering if provided
+                input_capabilities = kwargs.get('input_capabilities')
+                output_capabilities = kwargs.get('output_capabilities')
+                
+                if input_capabilities or output_capabilities:
+                    models = filter_models_by_capabilities(
+                        models, 
+                        input_capabilities=input_capabilities,
+                        output_capabilities=output_capabilities
+                    )
+
+
+                return models
             else:
                 self.logger.warning(f"LMStudio API returned status {response.status_code}")
                 return []

abstractcore/providers/mlx_provider.py

@@ -11,6 +11,14 @@ try:
 except ImportError:
     PYDANTIC_AVAILABLE = False
     BaseModel = None
+
+# Try to import Outlines (native structured output for MLX models)
+try:
+    import outlines
+    OUTLINES_AVAILABLE = True
+except ImportError:
+    OUTLINES_AVAILABLE = False
+
 from .base import BaseProvider
 from ..core.types import GenerateResponse
 from ..exceptions import ProviderAPIError, ModelNotFoundError, format_model_error
@@ -21,12 +29,20 @@ from ..events import EventType
 class MLXProvider(BaseProvider):
     """MLX provider for Apple Silicon models with full integration"""
 
-    def __init__(self, model: str = "mlx-community/Mistral-7B-Instruct-v0.1-4bit", **kwargs):
+    def __init__(self, model: str = "mlx-community/Mistral-7B-Instruct-v0.1-4bit",
+                 structured_output_method: str = "auto", **kwargs):
         super().__init__(model, **kwargs)
+        self.provider = "mlx"
 
         # Handle timeout parameter for local models
         self._handle_timeout_parameter(kwargs)
 
+        # Structured output method: "auto", "native_outlines", "prompted"
+        # auto: Use Outlines if available, otherwise prompted (default)
+        # native_outlines: Force Outlines (error if unavailable)
+        # prompted: Always use prompted fallback (fastest, still 100% success)
+        self.structured_output_method = structured_output_method
+
         # Initialize tool handler
         self.tool_handler = UniversalToolHandler(model)
 
@@ -143,7 +159,7 @@ class MLXProvider(BaseProvider):
                           stream: bool = False,
                           response_model: Optional[Type[BaseModel]] = None,
                           **kwargs) -> Union[GenerateResponse, Iterator[GenerateResponse]]:
-        """Internal generation with MLX"""
+        """Internal generation with MLX and optional Outlines native structured output"""
 
         if not self.llm or not self.tokenizer:
             return GenerateResponse(
@@ -152,6 +168,64 @@ class MLXProvider(BaseProvider):
                 finish_reason="error"
             )
 
+        # Native structured output via Outlines (if configured and available)
+        should_use_outlines = (
+            response_model and
+            PYDANTIC_AVAILABLE and
+            not stream and
+            self.structured_output_method != "prompted"  # Skip if explicitly prompted
+        )
+
+        if should_use_outlines:
+            # Check if Outlines is required but unavailable
+            if self.structured_output_method == "native_outlines" and not OUTLINES_AVAILABLE:
+                return GenerateResponse(
+                    content="Error: structured_output_method='native_outlines' requires Outlines library. Install with: pip install abstractcore[mlx]",
+                    model=self.model,
+                    finish_reason="error"
+                )
+
+            # Try Outlines if available (auto or native_outlines mode)
+            if OUTLINES_AVAILABLE:
+                try:
+                    # Cache Outlines MLX model wrapper to avoid re-initialization
+                    if not hasattr(self, '_outlines_model') or self._outlines_model is None:
+                        self.logger.debug("Creating Outlines MLX model wrapper for native structured output")
+                        self._outlines_model = outlines.from_mlxlm(self.llm, self.tokenizer)
+
+                    # Build full prompt (same as normal generation)
+                    processed_prompt = prompt
+                    full_prompt = self._build_prompt(processed_prompt, messages, system_prompt, tools)
+
+                    # Create constrained generator with JSON schema
+                    self.logger.debug(f"Using Outlines native structured output for {response_model.__name__}")
+                    generator = self._outlines_model(
+                        full_prompt,
+                        outlines.json_schema(response_model),
+                        max_tokens=kwargs.get("max_tokens", self.max_tokens or 512)
+                    )
+
+                    # Validate and return
+                    validated_obj = response_model.model_validate(generator)
+
+                    return GenerateResponse(
+                        content=validated_obj.model_dump_json(),
+                        model=self.model,
+                        finish_reason="stop",
+                        validated_object=validated_obj
+                    )
+                except Exception as e:
+                    # If native_outlines was explicitly requested, don't fall back
+                    if self.structured_output_method == "native_outlines":
+                        return GenerateResponse(
+                            content=f"Error: Outlines native structured output failed: {str(e)}",
+                            model=self.model,
+                            finish_reason="error"
+                        )
+                    # Otherwise fall back to prompted approach
+                    self.logger.debug(f"Outlines generation failed, falling back to prompted: {e}")
+                    # Continue with normal generation below
+
         # Handle media content first if present
         processed_prompt = prompt
         if media:
@@ -420,8 +494,19 @@ class MLXProvider(BaseProvider):
 
     @classmethod
     def list_available_models(cls, **kwargs) -> List[str]:
-        """List available MLX models from HuggingFace cache."""
+        """
+        List available MLX models from HuggingFace cache.
+
+        Args:
+            **kwargs: Optional parameters including:
+                - input_capabilities: List of ModelInputCapability enums to filter by input capability
+                - output_capabilities: List of ModelOutputCapability enums to filter by output capability
+
+        Returns:
+            List of model names, optionally filtered by capabilities
+        """
         from pathlib import Path
+        from .model_capabilities import filter_models_by_capabilities
 
         try:
             hf_cache = Path.home() / ".cache" / "huggingface" / "hub"
@@ -439,7 +524,21 @@ class MLXProvider(BaseProvider):
                     if "mlx" in model_name.lower():
                         models.append(model_name)
 
-            return sorted(models)
+            models = sorted(models)
+
+            # Apply new capability filtering if provided
+            input_capabilities = kwargs.get('input_capabilities')
+            output_capabilities = kwargs.get('output_capabilities')
+            
+            if input_capabilities or output_capabilities:
+                models = filter_models_by_capabilities(
+                    models, 
+                    input_capabilities=input_capabilities,
+                    output_capabilities=output_capabilities
+                )
+
+
+            return models
 
         except Exception:
             return []

abstractcore/providers/model_capabilities.py

@@ -0,0 +1,352 @@
+"""
+Model capability definitions for input and output filtering.
+
+This module provides clear enums for filtering models based on what types of
+input they can process and what types of output they can generate.
+
+Key Concepts:
+- Input Capabilities: What data types can the model accept and analyze?
+- Output Capabilities: What data types can the model generate?
+
+Examples:
+    >>> from abstractcore.providers.model_capabilities import ModelInputCapability, ModelOutputCapability
+    >>> from abstractcore.providers import OllamaProvider
+    >>> 
+    >>> # Get models that can analyze images
+    >>> vision_models = OllamaProvider.list_available_models(
+    ...     input_capabilities=[ModelInputCapability.IMAGE]
+    ... )
+    >>> 
+    >>> # Get embedding models
+    >>> embedding_models = OllamaProvider.list_available_models(
+    ...     output_capabilities=[ModelOutputCapability.EMBEDDINGS]
+    ... )
+    >>> 
+    >>> # Get vision models that generate text (most common case)
+    >>> vision_text_models = OllamaProvider.list_available_models(
+    ...     input_capabilities=[ModelInputCapability.TEXT, ModelInputCapability.IMAGE],
+    ...     output_capabilities=[ModelOutputCapability.TEXT]
+    ... )
+"""
+
+from enum import Enum
+from typing import List, Set, Optional, Dict, Any
+from ..architectures.detection import get_model_capabilities
+
+
+class ModelInputCapability(Enum):
+    """
+    Enumeration of input data types that models can process and analyze.
+    
+    These capabilities define what types of input data a model can accept
+    and understand. Most multimodal models support TEXT plus one or more
+    additional input types.
+    
+    Values:
+        TEXT: Model can process text input (all models support this)
+        IMAGE: Model can analyze and understand images (vision models)
+        AUDIO: Model can process and analyze audio input
+        VIDEO: Model can analyze video content
+    
+    Examples:
+        >>> # Text-only model
+        >>> text_only = [ModelInputCapability.TEXT]
+        >>> 
+        >>> # Vision model (supports both text and images)
+        >>> vision_model = [ModelInputCapability.TEXT, ModelInputCapability.IMAGE]
+        >>> 
+        >>> # Audio model (supports both text and audio)
+        >>> audio_model = [ModelInputCapability.TEXT, ModelInputCapability.AUDIO]
+    """
+    
+    TEXT = "text"
+    """Model can process and understand text input (supported by all models)"""
+    
+    IMAGE = "image"
+    """Model can analyze and understand image input (vision models)"""
+    
+    AUDIO = "audio"
+    """Model can process and analyze audio input"""
+    
+    VIDEO = "video"
+    """Model can analyze and understand video input"""
+
+
+class ModelOutputCapability(Enum):
+    """
+    Enumeration of output data types that models can generate.
+    
+    These capabilities define what types of output a model can produce.
+    Currently, AbstractCore supports text generation and embedding generation.
+    
+    Values:
+        TEXT: Model generates text responses (most common)
+        EMBEDDINGS: Model generates vector embeddings (embedding models)
+    
+    Examples:
+        >>> # Regular chat/completion model
+        >>> text_model = [ModelOutputCapability.TEXT]
+        >>> 
+        >>> # Embedding model
+        >>> embedding_model = [ModelOutputCapability.EMBEDDINGS]
+    
+    Note:
+        Future versions may include IMAGE, AUDIO, VIDEO for generative models.
+    """
+    
+    TEXT = "text"
+    """Model generates text responses (chat, completion, etc.)"""
+    
+    EMBEDDINGS = "embeddings"
+    """Model generates vector embeddings for semantic search/similarity"""
+
+
+def get_model_input_capabilities(model_name: str) -> List[ModelInputCapability]:
+    """
+    Determine what input capabilities a model supports.
+    
+    Args:
+        model_name: Name of the model to check
+        
+    Returns:
+        List of input capabilities the model supports
+        
+    Examples:
+        >>> caps = get_model_input_capabilities("gpt-4-vision-preview")
+        >>> print(caps)
+        [<ModelInputCapability.TEXT: 'text'>, <ModelInputCapability.IMAGE: 'image'>]
+        
+        >>> caps = get_model_input_capabilities("gpt-4")
+        >>> print(caps)
+        [<ModelInputCapability.TEXT: 'text'>]
+    """
+    try:
+        capabilities = get_model_capabilities(model_name)
+    except Exception:
+        # If we can't get capabilities, assume text-only
+        return [ModelInputCapability.TEXT]
+    
+    input_caps = [ModelInputCapability.TEXT]  # All models support text
+    
+    if capabilities.get("vision_support", False):
+        input_caps.append(ModelInputCapability.IMAGE)
+    
+    if capabilities.get("audio_support", False):
+        input_caps.append(ModelInputCapability.AUDIO)
+    
+    if capabilities.get("video_support", False):
+        input_caps.append(ModelInputCapability.VIDEO)
+    
+    return input_caps
+
+
+def get_model_output_capabilities(model_name: str) -> List[ModelOutputCapability]:
+    """
+    Determine what output capabilities a model supports.
+    
+    Args:
+        model_name: Name of the model to check
+        
+    Returns:
+        List of output capabilities the model supports
+        
+    Examples:
+        >>> caps = get_model_output_capabilities("gpt-4")
+        >>> print(caps)
+        [<ModelOutputCapability.TEXT: 'text'>]
+        
+        >>> caps = get_model_output_capabilities("text-embedding-3-small")
+        >>> print(caps)
+        [<ModelOutputCapability.EMBEDDINGS: 'embeddings'>]
+    """
+    try:
+        capabilities = get_model_capabilities(model_name)
+    except Exception:
+        # If we can't get capabilities, assume text generation
+        return [ModelOutputCapability.TEXT]
+    
+    # Check if it's explicitly marked as an embedding model
+    if capabilities.get("model_type") == "embedding":
+        return [ModelOutputCapability.EMBEDDINGS]
+    
+    # Check for embedding model name patterns
+    model_lower = model_name.lower()
+    embedding_patterns = [
+        "embedding", "embed", "embeddings", 
+        "text-embedding", "sentence-transformer",
+        "all-minilm", "nomic-embed", "granite-embedding",
+        "qwen3-embedding", "embeddinggemma"
+    ]
+    
+    if any(pattern in model_lower for pattern in embedding_patterns):
+        return [ModelOutputCapability.EMBEDDINGS]
+    
+    # Default to text generation
+    return [ModelOutputCapability.TEXT]
+
+
+def model_matches_input_capabilities(
+    model_name: str, 
+    required_capabilities: List[ModelInputCapability]
+) -> bool:
+    """
+    Check if a model supports all required input capabilities.
+    
+    Args:
+        model_name: Name of the model to check
+        required_capabilities: List of required input capabilities
+        
+    Returns:
+        True if model supports all required capabilities, False otherwise
+        
+    Examples:
+        >>> # Check if model supports both text and image input
+        >>> required = [ModelInputCapability.TEXT, ModelInputCapability.IMAGE]
+        >>> model_matches_input_capabilities("gpt-4-vision-preview", required)
+        True
+        
+        >>> model_matches_input_capabilities("gpt-4", required)
+        False
+    """
+    if not required_capabilities:
+        return True
+    
+    model_caps = get_model_input_capabilities(model_name)
+    model_caps_set = set(model_caps)
+    required_set = set(required_capabilities)
+    
+    return required_set.issubset(model_caps_set)
+
+
+def model_matches_output_capabilities(
+    model_name: str, 
+    required_capabilities: List[ModelOutputCapability]
+) -> bool:
+    """
+    Check if a model supports all required output capabilities.
+    
+    Args:
+        model_name: Name of the model to check
+        required_capabilities: List of required output capabilities
+        
+    Returns:
+        True if model supports all required capabilities, False otherwise
+        
+    Examples:
+        >>> # Check if model generates text
+        >>> required = [ModelOutputCapability.TEXT]
+        >>> model_matches_output_capabilities("gpt-4", required)
+        True
+        
+        >>> # Check if model generates embeddings
+        >>> required = [ModelOutputCapability.EMBEDDINGS]
+        >>> model_matches_output_capabilities("text-embedding-3-small", required)
+        True
+        >>> model_matches_output_capabilities("gpt-4", required)
+        False
+    """
+    if not required_capabilities:
+        return True
+    
+    model_caps = get_model_output_capabilities(model_name)
+    model_caps_set = set(model_caps)
+    required_set = set(required_capabilities)
+    
+    return required_set.issubset(model_caps_set)
+
+
+def filter_models_by_capabilities(
+    models: List[str],
+    input_capabilities: Optional[List[ModelInputCapability]] = None,
+    output_capabilities: Optional[List[ModelOutputCapability]] = None
+) -> List[str]:
+    """
+    Filter a list of models based on input and output capability requirements.
+    
+    Args:
+        models: List of model names to filter
+        input_capabilities: Required input capabilities (None = no filtering)
+        output_capabilities: Required output capabilities (None = no filtering)
+        
+    Returns:
+        Filtered list of model names that match all requirements
+        
+    Examples:
+        >>> models = ["gpt-4", "gpt-4-vision-preview", "text-embedding-3-small"]
+        >>> 
+        >>> # Get vision models
+        >>> vision_models = filter_models_by_capabilities(
+        ...     models, 
+        ...     input_capabilities=[ModelInputCapability.IMAGE]
+        ... )
+        >>> print(vision_models)
+        ['gpt-4-vision-preview']
+        >>> 
+        >>> # Get embedding models
+        >>> embedding_models = filter_models_by_capabilities(
+        ...     models,
+        ...     output_capabilities=[ModelOutputCapability.EMBEDDINGS]
+        ... )
+        >>> print(embedding_models)
+        ['text-embedding-3-small']
+        >>> 
+        >>> # Get text generation models
+        >>> text_models = filter_models_by_capabilities(
+        ...     models,
+        ...     output_capabilities=[ModelOutputCapability.TEXT]
+        ... )
+        >>> print(text_models)
+        ['gpt-4', 'gpt-4-vision-preview']
+    """
+    filtered_models = []
+    
+    for model_name in models:
+        try:
+            # Check input capabilities
+            if input_capabilities and not model_matches_input_capabilities(model_name, input_capabilities):
+                continue
+                
+            # Check output capabilities
+            if output_capabilities and not model_matches_output_capabilities(model_name, output_capabilities):
+                continue
+                
+            filtered_models.append(model_name)
+        except Exception:
+            # If we can't get capabilities, skip this model
+            # (it likely doesn't have an entry in model_capabilities.json)
+            continue
+    
+    return filtered_models
+
+
+def get_capability_summary(model_name: str) -> Dict[str, Any]:
+    """
+    Get a comprehensive summary of a model's input and output capabilities.
+    
+    Args:
+        model_name: Name of the model to analyze
+        
+    Returns:
+        Dictionary containing input and output capabilities
+        
+    Examples:
+        >>> summary = get_capability_summary("gpt-4-vision-preview")
+        >>> print(summary)
+        {
+            'model_name': 'gpt-4-vision-preview',
+            'input_capabilities': ['text', 'image'],
+            'output_capabilities': ['text'],
+            'is_multimodal': True,
+            'is_embedding_model': False
+        }
+    """
+    input_caps = get_model_input_capabilities(model_name)
+    output_caps = get_model_output_capabilities(model_name)
+    
+    return {
+        'model_name': model_name,
+        'input_capabilities': [cap.value for cap in input_caps],
+        'output_capabilities': [cap.value for cap in output_caps],
+        'is_multimodal': len(input_caps) > 1,
+        'is_embedding_model': ModelOutputCapability.EMBEDDINGS in output_caps
+    }