abstractcore 2.4.0__tar.gz → 2.4.2__tar.gz

{abstractcore-2.4.0 → abstractcore-2.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: abstractcore
-Version: 2.4.0
+Version: 2.4.2
 Summary: Unified interface to all LLM providers with essential infrastructure for tool calling, streaming, and model management
 Author-email: Laurent-Philippe Albou <contact@abstractcore.ai>
 Maintainer-email: Laurent-Philippe Albou <contact@abstractcore.ai>

abstractcore-2.4.2/abstractcore/core/factory.py

@@ -0,0 +1,73 @@
+"""
+Factory for creating LLM providers.
+"""
+
+from typing import Optional
+from .interface import AbstractCoreInterface
+from ..exceptions import ModelNotFoundError, AuthenticationError, ProviderAPIError
+
+
+def create_llm(provider: str, model: Optional[str] = None, **kwargs) -> AbstractCoreInterface:
+    """
+    Create an LLM provider instance with unified token parameter support.
+
+    Args:
+        provider: Provider name (openai, anthropic, ollama, huggingface, mlx, lmstudio, mock)
+        model: Model name (optional, will use provider default)
+        **kwargs: Additional configuration including token parameters
+
+    Token Parameters (AbstractCore Unified Standard):
+        max_tokens: Total context window budget (input + output combined)
+        max_output_tokens: Maximum tokens reserved for generation (default: 2048)
+        max_input_tokens: Maximum tokens for input (auto-calculated if not specified)
+
+    Examples:
+        # Strategy 1: Budget + Output Reserve (Recommended)
+        llm = create_llm(
+            provider="openai",
+            model="gpt-4o",
+            max_tokens=8000,        # Total budget
+            max_output_tokens=2000  # Reserve for output
+        )
+
+        # Strategy 2: Explicit Input + Output (Advanced)
+        llm = create_llm(
+            provider="anthropic",
+            model="claude-3.5-sonnet",
+            max_input_tokens=6000,   # Explicit input limit
+            max_output_tokens=2000   # Explicit output limit
+        )
+
+        # Quick setup with defaults
+        llm = create_llm("ollama", "qwen3-coder:30b")
+
+        # Get configuration help
+        print(llm.get_token_configuration_summary())
+        warnings = llm.validate_token_constraints()
+
+    Returns:
+        Configured LLM provider instance with unified token management
+
+    Raises:
+        ImportError: If provider dependencies are not installed
+        ValueError: If provider is not supported
+        ModelNotFoundError: If specified model is not available
+        AuthenticationError: If API credentials are invalid
+    """
+
+    # Auto-detect provider from model name if needed
+    if model:
+        # MLX models should use MLX provider
+        if "mlx-community" in model.lower() and provider.lower() == "huggingface":
+            provider = "mlx"
+        # GGUF models should use HuggingFace GGUF backend
+        elif (".gguf" in model.lower() or "-gguf" in model.lower()) and provider.lower() == "mlx":
+            provider = "huggingface"
+
+    # Use centralized provider registry for all provider creation
+    try:
+        from ..providers.registry import create_provider
+        return create_provider(provider, model, **kwargs)
+    except (ModelNotFoundError, AuthenticationError, ProviderAPIError) as e:
+        # Re-raise provider exceptions cleanly
+        raise e

abstractcore-2.4.2/abstractcore/exceptions/__init__.py

@@ -0,0 +1,125 @@
+"""
+Custom exceptions for AbstractCore.
+"""
+
+
+class AbstractCoreError(Exception):
+    """Base exception for AbstractCore"""
+    pass
+
+
+class ProviderError(AbstractCoreError):
+    """Base exception for provider-related errors"""
+    pass
+
+
+class ProviderAPIError(ProviderError):
+    """API call to provider failed"""
+    pass
+
+
+class AuthenticationError(ProviderError):
+    """Authentication with provider failed"""
+    pass
+
+
+# Alias for backward compatibility with old AbstractCore
+Authentication = AuthenticationError
+
+
+class RateLimitError(ProviderError):
+    """Rate limit exceeded"""
+    pass
+
+
+class InvalidRequestError(ProviderError):
+    """Invalid request to provider"""
+    pass
+
+
+class UnsupportedFeatureError(AbstractCoreError):
+    """Feature not supported by provider"""
+    pass
+
+
+class FileProcessingError(AbstractCoreError):
+    """Error processing file or media"""
+    pass
+
+
+class ToolExecutionError(AbstractCoreError):
+    """Error executing tool"""
+    pass
+
+
+class SessionError(AbstractCoreError):
+    """Error with session management"""
+    pass
+
+
+class ConfigurationError(AbstractCoreError):
+    """Invalid configuration"""
+    pass
+
+
+class ModelNotFoundError(ProviderError):
+    """Model not found or invalid model name"""
+    pass
+
+
+def format_model_error(provider: str, invalid_model: str, available_models: list) -> str:
+    """
+    Format a helpful error message for model not found errors.
+
+    Args:
+        provider: Provider name (e.g., "OpenAI", "Anthropic")
+        invalid_model: The model name that was not found
+        available_models: List of available model names
+
+    Returns:
+        Formatted error message string
+    """
+    message = f"❌ Model '{invalid_model}' not found for {provider} provider.\n"
+
+    if available_models:
+        message += f"\n✅ Available models ({len(available_models)}):\n"
+        for model in available_models[:30]:  # Show max 30
+            message += f"  • {model}\n"
+        if len(available_models) > 30:
+            message += f"  ... and {len(available_models) - 30} more\n"
+    else:
+        # Show provider documentation when we can't fetch models
+        doc_links = {
+            "anthropic": "https://docs.anthropic.com/en/docs/about-claude/models",
+            "openai": "https://platform.openai.com/docs/models",
+            "ollama": "https://ollama.com/library",
+            "huggingface": "https://huggingface.co/models",
+            "mlx": "https://huggingface.co/mlx-community"
+        }
+
+        provider_lower = provider.lower()
+        if provider_lower in doc_links:
+            message += f"\n📚 See available models: {doc_links[provider_lower]}\n"
+        else:
+            message += f"\n⚠️  Could not fetch available models for {provider}.\n"
+
+    return message.rstrip()
+
+
+# Export all exceptions for easy importing
+__all__ = [
+    'AbstractCoreError',
+    'ProviderError', 
+    'ProviderAPIError',
+    'AuthenticationError',
+    'Authentication',  # Backward compatibility alias
+    'RateLimitError',
+    'InvalidRequestError',
+    'UnsupportedFeatureError',
+    'FileProcessingError',
+    'ToolExecutionError',
+    'SessionError',
+    'ConfigurationError',
+    'ModelNotFoundError',
+    'format_model_error'
+]

abstractcore-2.4.2/abstractcore/media/__init__.py

@@ -0,0 +1,151 @@
+"""
+Media handling for different providers.
+"""
+
+import base64
+from pathlib import Path
+from typing import Union, Dict, Any, Optional
+from enum import Enum
+
+
+class MediaType(Enum):
+    """Supported media types"""
+    IMAGE = "image"
+    AUDIO = "audio"
+    VIDEO = "video"
+    DOCUMENT = "document"
+
+
+class MediaHandler:
+    """Base class for media handling"""
+
+    @staticmethod
+    def encode_image(image_path: Union[str, Path]) -> str:
+        """
+        Encode an image file to base64.
+
+        Args:
+            image_path: Path to the image file
+
+        Returns:
+            Base64 encoded string
+        """
+        with open(image_path, "rb") as image_file:
+            return base64.b64encode(image_file.read()).decode('utf-8')
+
+    @staticmethod
+    def format_for_openai(image_path: Union[str, Path]) -> Dict[str, Any]:
+        """
+        Format image for OpenAI API.
+
+        Args:
+            image_path: Path to the image
+
+        Returns:
+            Formatted content for OpenAI
+        """
+        base64_image = MediaHandler.encode_image(image_path)
+        return {
+            "type": "image_url",
+            "image_url": {
+                "url": f"data:image/jpeg;base64,{base64_image}"
+            }
+        }
+
+    @staticmethod
+    def format_for_anthropic(image_path: Union[str, Path]) -> Dict[str, Any]:
+        """
+        Format image for Anthropic API.
+
+        Args:
+            image_path: Path to the image
+
+        Returns:
+            Formatted content for Anthropic
+        """
+        base64_image = MediaHandler.encode_image(image_path)
+
+        # Detect image type
+        path = Path(image_path)
+        media_type = "image/jpeg"
+        if path.suffix.lower() == ".png":
+            media_type = "image/png"
+        elif path.suffix.lower() == ".gif":
+            media_type = "image/gif"
+        elif path.suffix.lower() == ".webp":
+            media_type = "image/webp"
+
+        return {
+            "type": "image",
+            "source": {
+                "type": "base64",
+                "media_type": media_type,
+                "data": base64_image
+            }
+        }
+
+    @staticmethod
+    def format_for_provider(image_path: Union[str, Path], provider: str) -> Optional[Dict[str, Any]]:
+        """
+        Format media for a specific provider.
+
+        Args:
+            image_path: Path to the media file
+            provider: Provider name
+
+        Returns:
+            Formatted content or None if not supported
+        """
+        provider_lower = provider.lower()
+
+        if provider_lower == "openai":
+            return MediaHandler.format_for_openai(image_path)
+        elif provider_lower == "anthropic":
+            return MediaHandler.format_for_anthropic(image_path)
+        else:
+            # Local providers typically don't support images directly
+            return None
+
+    @staticmethod
+    def is_image_file(path: Union[str, Path]) -> bool:
+        """
+        Check if a file is an image.
+
+        Args:
+            path: Path to check
+
+        Returns:
+            True if the file is an image
+        """
+        image_extensions = {'.jpg', '.jpeg', '.png', '.gif', '.bmp', '.webp', '.ico', '.tiff'}
+        return Path(path).suffix.lower() in image_extensions
+
+    @staticmethod
+    def get_media_type(path: Union[str, Path]) -> MediaType:
+        """
+        Determine the media type of a file.
+
+        Args:
+            path: Path to the file
+
+        Returns:
+            MediaType enum value
+        """
+        path = Path(path)
+        extension = path.suffix.lower()
+
+        image_extensions = {'.jpg', '.jpeg', '.png', '.gif', '.bmp', '.webp'}
+        audio_extensions = {'.mp3', '.wav', '.m4a', '.ogg', '.flac'}
+        video_extensions = {'.mp4', '.avi', '.mov', '.mkv', '.webm'}
+        document_extensions = {'.pdf', '.doc', '.docx', '.txt', '.md'}
+
+        if extension in image_extensions:
+            return MediaType.IMAGE
+        elif extension in audio_extensions:
+            return MediaType.AUDIO
+        elif extension in video_extensions:
+            return MediaType.VIDEO
+        elif extension in document_extensions:
+            return MediaType.DOCUMENT
+        else:
+            return MediaType.DOCUMENT  # Default to document

abstractcore-2.4.2/abstractcore/providers/__init__.py

@@ -0,0 +1,48 @@
+# LLM provider implementations
+
+from .base import BaseProvider
+from .openai_provider import OpenAIProvider
+from .anthropic_provider import AnthropicProvider
+from .ollama_provider import OllamaProvider
+from .lmstudio_provider import LMStudioProvider
+from .huggingface_provider import HuggingFaceProvider
+from .mlx_provider import MLXProvider
+from .mock_provider import MockProvider
+
+# Provider registry for centralized provider discovery and management
+from .registry import (
+    ProviderRegistry,
+    ProviderInfo,
+    get_provider_registry,
+    list_available_providers,
+    get_provider_info,
+    is_provider_available,
+    get_all_providers_with_models,
+    get_all_providers_status,
+    create_provider,
+    get_available_models_for_provider
+)
+
+__all__ = [
+    # Provider classes
+    'BaseProvider',
+    'OpenAIProvider',
+    'AnthropicProvider',
+    'OllamaProvider',
+    'LMStudioProvider',
+    'HuggingFaceProvider',
+    'MLXProvider',
+    'MockProvider',
+
+    # Provider registry
+    'ProviderRegistry',
+    'ProviderInfo',
+    'get_provider_registry',
+    'list_available_providers',
+    'get_provider_info',
+    'is_provider_available',
+    'get_all_providers_with_models',
+    'get_all_providers_status',
+    'create_provider',
+    'get_available_models_for_provider',
+]