abstractcore 2.4.9__py3-none-any.whl → 2.5.2__py3-none-any.whl

abstractcore/providers/anthropic_provider.py

@@ -32,6 +32,7 @@ class AnthropicProvider(BaseProvider):
 
     def __init__(self, model: str = "claude-3-haiku-20240307", api_key: Optional[str] = None, **kwargs):
         super().__init__(model, **kwargs)
+        self.provider = "anthropic"
 
         if not ANTHROPIC_AVAILABLE:
             raise ImportError("Anthropic package not installed. Install with: pip install anthropic")

abstractcore/providers/base.py

@@ -38,6 +38,7 @@ class BaseProvider(AbstractCoreInterface, ABC):
 
     def __init__(self, model: str, **kwargs):
         AbstractCoreInterface.__init__(self, model, **kwargs)
+        self.provider = None
 
         # Setup structured logging
         self.logger = get_logger(self.__class__.__name__)

abstractcore/providers/huggingface_provider.py

@@ -35,6 +35,13 @@ try:
 except ImportError:
     LLAMACPP_AVAILABLE = False
 
+# Try to import Outlines (native structured output for transformers models)
+try:
+    import outlines
+    OUTLINES_AVAILABLE = True
+except ImportError:
+    OUTLINES_AVAILABLE = False
+
 # We no longer download models - cache-only approach
 # huggingface_hub not required for basic operation
 
@@ -42,9 +49,10 @@ except ImportError:
 class HuggingFaceProvider(BaseProvider):
     """HuggingFace provider with dual support for transformers and GGUF models"""
 
-    def __init__(self, model: str = "Qwen/Qwen3-4B",
+    def __init__(self, model: str = "unsloth/Qwen3-4B-Instruct-2507-GGUF",
                  device: Optional[str] = None,
                  n_gpu_layers: Optional[int] = None,
+                 structured_output_method: str = "auto",
                  **kwargs):
 
         # Handle legacy context_size parameter with deprecation warning
@@ -61,10 +69,18 @@ class HuggingFaceProvider(BaseProvider):
                 kwargs["max_tokens"] = context_size
 
         super().__init__(model, **kwargs)
+        self.provider = "huggingface"
 
         # Handle timeout parameter for local models
         self._handle_timeout_parameter(kwargs)
 
+        # Structured output method: "auto", "native_outlines", "prompted"
+        # auto: Use Outlines if available (for transformers), otherwise prompted (default)
+        # native_outlines: Force Outlines (error if unavailable)
+        # prompted: Always use prompted fallback (fastest for transformers, still 100% success)
+        # Note: GGUF models always use llama-cpp-python native support regardless of this setting
+        self.structured_output_method = structured_output_method
+
         # Initialize tool handler
         self.tool_handler = UniversalToolHandler(model)
 
@@ -481,9 +497,9 @@ class HuggingFaceProvider(BaseProvider):
         """Generate response using appropriate backend"""
 
         if self.model_type == "gguf":
-            return self._generate_gguf(prompt, messages, system_prompt, tools, media, stream, **kwargs)
+            return self._generate_gguf(prompt, messages, system_prompt, tools, media, stream, response_model, **kwargs)
         else:
-            return self._generate_transformers(prompt, messages, system_prompt, tools, media, stream, **kwargs)
+            return self._generate_transformers(prompt, messages, system_prompt, tools, media, stream, response_model, **kwargs)
 
     def _generate_transformers(self,
                                prompt: str,
@@ -492,8 +508,9 @@ class HuggingFaceProvider(BaseProvider):
                                tools: Optional[List[Dict[str, Any]]] = None,
                                media: Optional[List['MediaContent']] = None,
                                stream: bool = False,
+                               response_model: Optional[Type[BaseModel]] = None,
                                **kwargs) -> Union[GenerateResponse, Iterator[GenerateResponse]]:
-        """Generate using transformers backend (original implementation)"""
+        """Generate using transformers backend with optional Outlines native structured output"""
 
         if not self.pipeline:
             return GenerateResponse(
@@ -502,6 +519,66 @@ class HuggingFaceProvider(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[huggingface]",
+                    model=self.model,
+                    finish_reason="error"
+                )
+
+            # Try Outlines if available (auto or native_outlines mode)
+            if OUTLINES_AVAILABLE:
+                try:
+                    # Cache Outlines model wrapper to avoid re-initialization
+                    if not hasattr(self, '_outlines_model') or self._outlines_model is None:
+                        self.logger.debug("Creating Outlines model wrapper for native structured output")
+                        self._outlines_model = outlines.from_transformers(
+                            self.model_instance,
+                            self.tokenizer
+                        )
+
+                    # Build input text (same as normal generation)
+                    input_text = self._build_input_text_transformers(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(
+                        input_text,
+                        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
+
         # Build input text with tool and media support
         # Handle media content first if present
         if media:
@@ -568,6 +645,7 @@ class HuggingFaceProvider(BaseProvider):
                        tools: Optional[List[Dict[str, Any]]] = None,
                        media: Optional[List['MediaContent']] = None,
                        stream: bool = False,
+                       response_model: Optional[Type[BaseModel]] = None,
                        **kwargs) -> Union[GenerateResponse, Iterator[GenerateResponse]]:
         """Generate using GGUF backend with llama-cpp-python"""
 
@@ -663,6 +741,19 @@ class HuggingFaceProvider(BaseProvider):
         if seed_value is not None:
             generation_kwargs["seed"] = seed_value
 
+        # Add native structured output support (llama-cpp-python format)
+        # llama-cpp-python 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()
+            generation_kwargs["response_format"] = {
+                "type": "json_schema",
+                "json_schema": {
+                    "name": response_model.__name__,
+                    "schema": json_schema
+                }
+            }
+
         # Handle tools - both native and prompted support
         has_native_tools = False
         if tools:

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)
@@ -207,6 +208,19 @@ class LMStudioProvider(BaseProvider):
         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)

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:

abstractcore/providers/ollama_provider.py

@@ -23,8 +23,10 @@ from ..events import EventType
 class OllamaProvider(BaseProvider):
     """Ollama provider for local models with full integration"""
 
-    def __init__(self, model: str = "llama2", base_url: str = "http://localhost:11434", **kwargs):
+    def __init__(self, model: str = "qwen3:4b-instruct-2507-q4_K_M", base_url: str = "http://localhost:11434", **kwargs):
         super().__init__(model, **kwargs)
+        self.provider = "ollama"
+
         self.base_url = base_url.rstrip('/')
         self.client = httpx.Client(timeout=self._timeout)
 
@@ -143,9 +145,11 @@ class OllamaProvider(BaseProvider):
             payload["options"]["seed"] = seed_value
 
         # Add structured output support (Ollama native JSON schema)
+        # Ollama accepts the full JSON schema in the "format" parameter
+        # This provides server-side guaranteed schema compliance
         if response_model and PYDANTIC_AVAILABLE:
             json_schema = response_model.model_json_schema()
-            payload["format"] = json_schema
+            payload["format"] = json_schema  # Pass the full schema, not just "json"
 
         # Use chat format by default (recommended by Ollama docs), especially when tools are present
         # Only use generate format for very simple cases without tools or messages

abstractcore/providers/openai_provider.py

@@ -32,6 +32,7 @@ class OpenAIProvider(BaseProvider):
 
     def __init__(self, model: str = "gpt-3.5-turbo", api_key: Optional[str] = None, **kwargs):
         super().__init__(model, **kwargs)
+        self.provider = "openai"
 
         if not OPENAI_AVAILABLE:
             raise ImportError("OpenAI package not installed. Install with: pip install openai")

abstractcore/providers/registry.py

@@ -86,8 +86,8 @@ class ProviderRegistry:
             display_name="Ollama",
             provider_class=None,
             description="Local LLM server for running open-source models",
-            default_model="qwen3-coder:30b",
-            supported_features=["chat", "completion", "embeddings", "prompted_tools", "streaming"],
+            default_model="qwen3:4b-instruct-2507-q4_K_M",
+            supported_features=["chat", "completion", "embeddings", "prompted_tools", "streaming", "structured_output"],
             authentication_required=False,
             local_provider=True,
             installation_extras="ollama",
@@ -101,7 +101,7 @@ class ProviderRegistry:
             provider_class=None,
             description="Local model development and testing platform",
             default_model="qwen/qwen3-4b-2507",
-            supported_features=["chat", "completion", "embeddings", "prompted_tools", "streaming"],
+            supported_features=["chat", "completion", "embeddings", "prompted_tools", "streaming", "structured_output"],
             authentication_required=False,
             local_provider=True,
             installation_extras=None,
@@ -115,7 +115,7 @@ class ProviderRegistry:
             provider_class=None,
             description="Apple Silicon optimized local inference",
             default_model="mlx-community/Qwen3-4B",
-            supported_features=["chat", "completion", "prompted_tools", "streaming", "apple_silicon"],
+            supported_features=["chat", "completion", "prompted_tools", "streaming", "structured_output", "apple_silicon"],
             authentication_required=False,
             local_provider=True,
             installation_extras="mlx",
@@ -128,8 +128,8 @@ class ProviderRegistry:
             display_name="HuggingFace",
             provider_class=None,
             description="Access to HuggingFace models (transformers and embeddings)",
-            default_model="Qwen/Qwen3-4B/",
-            supported_features=["chat", "completion", "embeddings", "prompted_tools", "local_models"],
+            default_model="unsloth/Qwen3-4B-Instruct-2507-GGUF",
+            supported_features=["chat", "completion", "embeddings", "prompted_tools", "local_models", "structured_output"],
             authentication_required=False,  # Optional for public models
             local_provider=True,
             installation_extras="huggingface",

abstractcore/structured/handler.py

@@ -6,6 +6,7 @@ import json
 import re
 import time
 from typing import Type, Dict, Any, Optional
+from enum import Enum
 from pydantic import BaseModel, ValidationError
 
 from .retry import FeedbackRetry
@@ -69,6 +70,9 @@ class StructuredOutputHandler:
                         max_retries=self.retry_strategy.max_attempts)
 
         try:
+            # Store provider for schema generation
+            self.current_provider = provider
+            
             # Strategy 1: Use native support if available
             if self._has_native_support(provider):
                 self.logger.debug("Using native structured output support",
@@ -125,12 +129,44 @@ class StructuredOutputHandler:
         """
         Check if provider has native structured output support.
 
+        Checks both provider type (Ollama, LMStudio, HuggingFace, MLX with Outlines)
+        and model capabilities configuration as fallback.
+
         Args:
             provider: The LLM provider instance
 
         Returns:
             True if provider supports native structured outputs
         """
+        # Ollama and LMStudio always support native structured outputs
+        # via the format and response_format parameters respectively
+        provider_name = provider.__class__.__name__
+        if provider_name in ['OllamaProvider', 'LMStudioProvider']:
+            return True
+
+        # HuggingFaceProvider supports native via GGUF or Transformers+Outlines
+        if provider_name == 'HuggingFaceProvider':
+            # Check if it's a GGUF model - these use llama-cpp-python which supports native structured outputs
+            if hasattr(provider, 'model_type') and provider.model_type == 'gguf':
+                return True
+
+            # Check if it's a Transformers model with Outlines available
+            if hasattr(provider, 'model_type') and provider.model_type == 'transformers':
+                try:
+                    import outlines
+                    return True
+                except ImportError:
+                    return False
+
+        # MLXProvider supports native via Outlines
+        if provider_name == 'MLXProvider':
+            try:
+                import outlines
+                return True
+            except ImportError:
+                return False
+
+        # For other providers, check model capabilities
         capabilities = getattr(provider, 'model_capabilities', {})
         return capabilities.get("structured_output") == "native"
 
@@ -242,6 +278,9 @@ class StructuredOutputHandler:
                 # Try parsing the extracted JSON
                 try:
                     data = json.loads(json_content)
+                    # Preprocess enum responses if we have mappings
+                    if hasattr(self, '_enum_mappings') and self._enum_mappings:
+                        data = self._preprocess_enum_response(data, self._enum_mappings)
                     result = response_model.model_validate(data)
                 except (json.JSONDecodeError, ValidationError) as parse_error:
                     # Try to fix the JSON
@@ -254,6 +293,9 @@ class StructuredOutputHandler:
                     if fixed_json:
                         try:
                             data = json.loads(fixed_json)
+                            # Preprocess enum responses if we have mappings
+                            if hasattr(self, '_enum_mappings') and self._enum_mappings:
+                                data = self._preprocess_enum_response(data, self._enum_mappings)
                             result = response_model.model_validate(data)
                             self.logger.info("JSON self-fix successful", attempt=attempt + 1)
                         except (json.JSONDecodeError, ValidationError) as fix_error:
@@ -350,6 +392,14 @@ class StructuredOutputHandler:
             Enhanced prompt with schema information
         """
         schema = response_model.model_json_schema()
+        
+        # For prompted providers, simplify enum schemas to avoid LLM confusion
+        # Store original enum mappings for response preprocessing
+        if hasattr(self, 'current_provider') and not self._has_native_support(self.current_provider):
+            schema, self._enum_mappings = self._simplify_enum_schemas(schema)
+        else:
+            self._enum_mappings = {}
+        
         model_name = response_model.__name__
 
         # Create example from schema
@@ -432,4 +482,114 @@ Important: Return ONLY the JSON object, no additional text or formatting."""
             return match.group(0)
 
         # If nothing found, try the original content
-        return content
+        return content
+
+    def _simplify_enum_schemas(self, schema: Dict[str, Any]) -> tuple[Dict[str, Any], Dict[str, Dict[str, str]]]:
+        """
+        Simplify enum schemas for prompted providers while preserving enum mappings.
+        
+        Args:
+            schema: Original JSON schema
+            
+        Returns:
+            Tuple of (simplified_schema, enum_mappings)
+            enum_mappings maps field_paths to {enum_notation: enum_value}
+        """
+        if '$defs' not in schema:
+            return schema, {}
+        
+        # Find enum definitions and build mappings
+        enum_mappings = {}
+        enum_refs_to_simplify = {}
+        
+        for def_name, def_schema in schema['$defs'].items():
+            if def_schema.get('type') == 'string' and 'enum' in def_schema:
+                ref_key = f"#/$defs/{def_name}"
+                enum_values = def_schema['enum']
+                
+                # Build mapping from Python enum notation to actual values
+                enum_class_name = def_name
+                field_mappings = {}
+                for value in enum_values:
+                    # Map both "EnumClass.VALUE_NAME" and "<EnumClass.VALUE_NAME: 'value'>" patterns
+                    enum_notation = f"{enum_class_name}.{value.upper().replace(' ', '_')}"
+                    field_mappings[enum_notation] = value
+                    # Also handle the repr format
+                    repr_notation = f"<{enum_class_name}.{value.upper().replace(' ', '_')}: '{value}'>"
+                    field_mappings[repr_notation] = value
+                
+                enum_refs_to_simplify[ref_key] = {
+                    'type': 'string',
+                    'description': f"Use one of: {', '.join(enum_values)}. IMPORTANT: Use the exact string values, not Python enum notation.",
+                    'enum': enum_values
+                }
+                
+                # Store mappings by reference for later use
+                enum_mappings[ref_key] = field_mappings
+        
+        # Create simplified schema by replacing enum references
+        def replace_enum_refs(obj, path=""):
+            if isinstance(obj, dict):
+                if '$ref' in obj and obj['$ref'] in enum_refs_to_simplify:
+                    # Store the field path for this enum reference
+                    if path:
+                        enum_mappings[path] = enum_mappings[obj['$ref']]
+                    return enum_refs_to_simplify[obj['$ref']]
+                return {k: replace_enum_refs(v, f"{path}.{k}" if path else k) for k, v in obj.items()}
+            elif isinstance(obj, list):
+                return [replace_enum_refs(item, path) for item in obj]
+            return obj
+        
+        simplified_schema = replace_enum_refs(schema)
+        
+        # Remove the $defs section since we've inlined the enum definitions
+        if '$defs' in simplified_schema:
+            # Only remove enum definitions, keep other definitions
+            remaining_defs = {k: v for k, v in simplified_schema['$defs'].items() 
+                            if not (v.get('type') == 'string' and 'enum' in v)}
+            if remaining_defs:
+                simplified_schema['$defs'] = remaining_defs
+            else:
+                del simplified_schema['$defs']
+        
+        return simplified_schema, enum_mappings
+
+    def _preprocess_enum_response(self, data: Dict[str, Any], enum_mappings: Dict[str, Dict[str, str]]) -> Dict[str, Any]:
+        """
+        Preprocess LLM response to convert Python enum notation back to valid enum values.
+        
+        Args:
+            data: Parsed JSON data from LLM
+            enum_mappings: Mappings from field paths to enum notation conversions
+            
+        Returns:
+            Preprocessed data with enum notations converted to valid values
+        """
+        if not enum_mappings:
+            return data
+        
+        def convert_enum_values(obj, path=""):
+            if isinstance(obj, dict):
+                result = {}
+                for key, value in obj.items():
+                    field_path = f"{path}.{key}" if path else key
+                    
+                    # Check if this field has enum mappings
+                    field_mappings = None
+                    for enum_path, mappings in enum_mappings.items():
+                        if field_path in enum_path or enum_path in field_path:
+                            field_mappings = mappings
+                            break
+                    
+                    if field_mappings and isinstance(value, str):
+                        # Try to convert enum notation to actual value
+                        converted_value = field_mappings.get(value, value)
+                        result[key] = converted_value
+                    else:
+                        result[key] = convert_enum_values(value, field_path)
+                return result
+            elif isinstance(obj, list):
+                return [convert_enum_values(item, path) for item in obj]
+            return obj
+        
+        return convert_enum_values(data)