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

abstractcore/events/__init__.py

@@ -20,15 +20,17 @@ from enum import Enum
 from dataclasses import dataclass, field
 from datetime import datetime
 import uuid
+import asyncio
 
 
 class EventType(Enum):
     """Minimal event system - clean, simple, efficient"""
 
-    # Core events (4) - matches LangChain pattern
+    # Core events (5) - matches LangChain pattern + async progress
     GENERATION_STARTED = "generation_started"      # Unified for streaming and non-streaming
     GENERATION_COMPLETED = "generation_completed"  # Includes all metrics
     TOOL_STARTED = "tool_started"                  # Before tool execution
+    TOOL_PROGRESS = "tool_progress"                # Real-time progress during tool execution
     TOOL_COMPLETED = "tool_completed"              # After tool execution
 
     # Error handling (1)
@@ -60,6 +62,7 @@ class EventEmitter:
 
     def __init__(self):
         self._listeners: Dict[EventType, List[Callable]] = {}
+        self._async_listeners: Dict[EventType, List[Callable]] = {}
 
     def on(self, event_type: EventType, handler: Callable):
         """
@@ -141,6 +144,67 @@ class EventEmitter:
             }
         )
 
+    def on_async(self, event_type: EventType, handler: Callable):
+        """
+        Register an async event handler.
+
+        Args:
+            event_type: Type of event to listen for
+            handler: Async function to call when event occurs
+        """
+        if event_type not in self._async_listeners:
+            self._async_listeners[event_type] = []
+        self._async_listeners[event_type].append(handler)
+
+    async def emit_async(self, event_type: EventType, data: Dict[str, Any], source: Optional[str] = None, **kwargs) -> Event:
+        """
+        Emit an event asynchronously to all registered handlers.
+
+        Runs async handlers concurrently with asyncio.gather().
+        Also triggers sync handlers for backward compatibility.
+
+        Args:
+            event_type: Type of event
+            data: Event data
+            source: Source of the event
+            **kwargs: Additional event attributes (model_name, tokens, etc.)
+
+        Returns:
+            The event object
+        """
+        # Filter kwargs to only include valid Event fields
+        try:
+            valid_fields = set(Event.__dataclass_fields__.keys())
+        except AttributeError:
+            # Fallback for older Python versions
+            valid_fields = {'trace_id', 'span_id', 'request_id', 'duration_ms', 'model_name',
+                          'provider_name', 'tokens_input', 'tokens_output', 'cost_usd', 'metadata'}
+        filtered_kwargs = {k: v for k, v in kwargs.items() if k in valid_fields}
+
+        event = Event(
+            type=event_type,
+            timestamp=datetime.now(),
+            data=data,
+            source=source or self.__class__.__name__,
+            **filtered_kwargs
+        )
+
+        # Run async handlers concurrently
+        if event_type in self._async_listeners:
+            tasks = [handler(event) for handler in self._async_listeners[event_type]]
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+        # Also run sync handlers (backward compatible)
+        if event_type in self._listeners:
+            for handler in self._listeners[event_type]:
+                try:
+                    handler(event)
+                except Exception as e:
+                    # Log error but don't stop event propagation
+                    print(f"Error in event handler: {e}")
+
+        return event
+
 
 class GlobalEventBus:
     """
@@ -149,6 +213,7 @@ class GlobalEventBus:
     """
     _instance = None
     _listeners: Dict[EventType, List[Callable]] = {}
+    _async_listeners: Dict[EventType, List[Callable]] = {}
 
     def __new__(cls):
         if cls._instance is None:
@@ -199,6 +264,52 @@ class GlobalEventBus:
     def clear(cls):
         """Clear all global event handlers"""
         cls._listeners.clear()
+        cls._async_listeners.clear()
+
+    @classmethod
+    def on_async(cls, event_type: EventType, handler: Callable):
+        """Register a global async event handler"""
+        if event_type not in cls._async_listeners:
+            cls._async_listeners[event_type] = []
+        cls._async_listeners[event_type].append(handler)
+
+    @classmethod
+    async def emit_async(cls, event_type: EventType, data: Dict[str, Any], source: Optional[str] = None, **kwargs):
+        """
+        Emit a global event asynchronously.
+
+        Runs async handlers concurrently with asyncio.gather().
+        Also triggers sync handlers for backward compatibility.
+        """
+        # Filter kwargs to only include valid Event fields
+        try:
+            valid_fields = set(Event.__dataclass_fields__.keys())
+        except AttributeError:
+            # Fallback for older Python versions
+            valid_fields = {'trace_id', 'span_id', 'request_id', 'duration_ms', 'model_name',
+                          'provider_name', 'tokens_input', 'tokens_output', 'cost_usd', 'metadata'}
+        filtered_kwargs = {k: v for k, v in kwargs.items() if k in valid_fields}
+
+        event = Event(
+            type=event_type,
+            timestamp=datetime.now(),
+            data=data,
+            source=source or "GlobalEventBus",
+            **filtered_kwargs
+        )
+
+        # Run async handlers concurrently
+        if event_type in cls._async_listeners:
+            tasks = [handler(event) for handler in cls._async_listeners[event_type]]
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+        # Also run sync handlers (backward compatible)
+        if event_type in cls._listeners:
+            for handler in cls._listeners[event_type]:
+                try:
+                    handler(event)
+                except Exception as e:
+                    print(f"Error in global event handler: {e}")
 
 
 # Convenience functions

abstractcore/exceptions/__init__.py

@@ -106,10 +106,55 @@ def format_model_error(provider: str, invalid_model: str, available_models: list
     return message.rstrip()
 
 
+def format_auth_error(provider: str, reason: str = None) -> str:
+    """
+    Format actionable authentication error with setup instructions.
+
+    Args:
+        provider: Provider name (e.g., "openai", "anthropic")
+        reason: Optional reason for auth failure
+
+    Returns:
+        Formatted error message with fix instructions
+    """
+    urls = {
+        "openai": "https://platform.openai.com/api-keys",
+        "anthropic": "https://console.anthropic.com/settings/keys",
+    }
+    msg = f"{provider.upper()} authentication failed"
+    if reason:
+        msg += f": {reason}"
+    msg += f"\nFix: abstractcore --set-api-key {provider} YOUR_KEY"
+    if provider.lower() in urls:
+        msg += f"\nGet key: {urls[provider.lower()]}"
+    return msg
+
+
+def format_provider_error(provider: str, reason: str) -> str:
+    """
+    Format actionable provider unavailability error with setup instructions.
+
+    Args:
+        provider: Provider name (e.g., "ollama", "lmstudio")
+        reason: Reason for unavailability (e.g., "Connection refused")
+
+    Returns:
+        Formatted error message with setup instructions
+    """
+    instructions = {
+        "ollama": "Install: https://ollama.com/download\nStart: ollama serve",
+        "lmstudio": "Install: https://lmstudio.ai/\nEnable API in settings",
+    }
+    msg = f"Provider '{provider}' unavailable: {reason}"
+    if provider.lower() in instructions:
+        msg += f"\n{instructions[provider.lower()]}"
+    return msg
+
+
 # Export all exceptions for easy importing
 __all__ = [
     'AbstractCoreError',
-    'ProviderError', 
+    'ProviderError',
     'ProviderAPIError',
     'AuthenticationError',
     'Authentication',  # Backward compatibility alias
@@ -121,5 +166,7 @@ __all__ = [
     'SessionError',
     'ConfigurationError',
     'ModelNotFoundError',
-    'format_model_error'
+    'format_model_error',
+    'format_auth_error',
+    'format_provider_error'
 ]

abstractcore/media/processors/office_processor.py

@@ -6,13 +6,13 @@ This module provides comprehensive processing capabilities for Microsoft Office
 document processing in 2025.
 """
 
-import logging
 from pathlib import Path
 from typing import Optional, Dict, Any, List, Union, Tuple
 import json
 
 from ..base import BaseMediaHandler, MediaProcessingError
 from ..types import MediaContent, MediaType, ContentFormat, MediaProcessingResult
+from ...utils.structured_logging import get_logger
 
 
 class OfficeProcessor(BaseMediaHandler):
@@ -36,7 +36,7 @@ class OfficeProcessor(BaseMediaHandler):
             **kwargs: Additional configuration options
         """
         super().__init__(**kwargs)
-        self.logger = logging.getLogger(__name__)
+        self.logger = get_logger(__name__)
 
         # Configuration options
         self.extract_tables = kwargs.get('extract_tables', True)

abstractcore/media/utils/image_scaler.py

@@ -8,7 +8,6 @@ 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
@@ -17,6 +16,7 @@ except ImportError:
     PIL_AVAILABLE = False
 
 from ..base import MediaProcessingError
+from ...utils.structured_logging import get_logger
 
 
 class ScalingMode(Enum):
@@ -36,7 +36,7 @@ class ModelOptimizedScaler:
     """
 
     def __init__(self):
-        self.logger = logging.getLogger(__name__)
+        self.logger = get_logger(__name__)
 
         if not PIL_AVAILABLE:
             raise MediaProcessingError("PIL (Pillow) is required for image scaling")

abstractcore/media/vision_fallback.py

@@ -5,11 +5,11 @@ Implements two-stage pipeline: vision model → description → text-only model
 Uses unified AbstractCore configuration system.
 """
 
-import logging
 from pathlib import Path
 from typing import Optional, Dict, Any
+from ..utils.structured_logging import get_logger
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 class VisionNotConfiguredError(Exception):

abstractcore/providers/anthropic_provider.py

@@ -5,7 +5,7 @@ Anthropic provider implementation.
 import os
 import json
 import time
-from typing import List, Dict, Any, Optional, Union, Iterator, Type
+from typing import List, Dict, Any, Optional, Union, Iterator, AsyncIterator, Type
 
 try:
     from pydantic import BaseModel
@@ -16,7 +16,7 @@ except ImportError:
 from .base import BaseProvider
 from ..core.types import GenerateResponse
 from ..media import MediaHandler
-from ..exceptions import AuthenticationError, ProviderAPIError, ModelNotFoundError, format_model_error
+from ..exceptions import AuthenticationError, ProviderAPIError, ModelNotFoundError, format_model_error, format_auth_error
 from ..tools import UniversalToolHandler, execute_tools
 from ..events import EventType
 
@@ -30,7 +30,8 @@ except ImportError:
 class AnthropicProvider(BaseProvider):
     """Anthropic Claude API provider with full integration"""
 
-    def __init__(self, model: str = "claude-3-haiku-20240307", api_key: Optional[str] = None, **kwargs):
+    def __init__(self, model: str = "claude-3-haiku-20240307", api_key: Optional[str] = None,
+                 base_url: Optional[str] = None, **kwargs):
         super().__init__(model, **kwargs)
         self.provider = "anthropic"
 
@@ -42,8 +43,15 @@ class AnthropicProvider(BaseProvider):
         if not self.api_key:
             raise ValueError("Anthropic API key required. Set ANTHROPIC_API_KEY environment variable.")
 
-        # Initialize client with timeout
-        self.client = anthropic.Anthropic(api_key=self.api_key, timeout=self._timeout)
+        # Get base URL from param or environment
+        self.base_url = base_url or os.getenv("ANTHROPIC_BASE_URL")
+
+        # Initialize client with timeout and optional base_url
+        client_kwargs = {"api_key": self.api_key, "timeout": self._timeout}
+        if self.base_url:
+            client_kwargs["base_url"] = self.base_url
+        self.client = anthropic.Anthropic(**client_kwargs)
+        self._async_client = None  # Lazy-loaded async client
 
         # Initialize tool handler
         self.tool_handler = UniversalToolHandler(model)
@@ -56,6 +64,16 @@ class AnthropicProvider(BaseProvider):
         """Public generate method that includes telemetry"""
         return self.generate_with_telemetry(*args, **kwargs)
 
+    @property
+    def async_client(self):
+        """Lazy-load AsyncAnthropic client for native async operations."""
+        if self._async_client is None:
+            client_kwargs = {"api_key": self.api_key, "timeout": self._timeout}
+            if self.base_url:
+                client_kwargs["base_url"] = self.base_url
+            self._async_client = anthropic.AsyncAnthropic(**client_kwargs)
+        return self._async_client
+
     def _generate_internal(self,
                           prompt: str,
                           messages: Optional[List[Dict[str, str]]] = None,
@@ -207,7 +225,7 @@ class AnthropicProvider(BaseProvider):
             error_str = str(e).lower()
 
             if 'api_key' in error_str or 'authentication' in error_str:
-                raise AuthenticationError(f"Anthropic authentication failed: {str(e)}")
+                raise AuthenticationError(format_auth_error("anthropic", str(e)))
             elif ('not_found_error' in error_str and 'model:' in error_str) or '404' in error_str:
                 # Model not found - show available models
                 available_models = self.list_available_models(api_key=self.api_key)
@@ -216,6 +234,182 @@ class AnthropicProvider(BaseProvider):
             else:
                 raise ProviderAPIError(f"Anthropic API error: {str(e)}")
 
+    async def _agenerate_internal(self,
+                                   prompt: str,
+                                   messages: Optional[List[Dict[str, str]]] = None,
+                                   system_prompt: Optional[str] = None,
+                                   tools: Optional[List[Dict[str, Any]]] = None,
+                                   media: Optional[List['MediaContent']] = None,
+                                   stream: bool = False,
+                                   response_model: Optional[Type[BaseModel]] = None,
+                                   **kwargs) -> Union[GenerateResponse, AsyncIterator[GenerateResponse]]:
+        """Native async implementation using AsyncAnthropic - 3-10x faster for batch operations."""
+
+        # Build messages array (same logic as sync)
+        api_messages = []
+
+        # Add conversation history
+        if messages:
+            for msg in messages:
+                # Skip system messages as they're handled separately
+                if msg.get("role") != "system":
+                    # Convert assistant role if needed
+                    role = msg["role"]
+                    if role == "assistant":
+                        api_messages.append({
+                            "role": "assistant",
+                            "content": msg["content"]
+                        })
+                    else:
+                        api_messages.append({
+                            "role": "user",
+                            "content": msg["content"]
+                        })
+
+        # Add current prompt as user message
+        if prompt and prompt not in [msg.get("content") for msg in (messages or [])]:
+            # Handle multimodal message with media content
+            if media:
+                try:
+                    from ..media.handlers import AnthropicMediaHandler
+                    media_handler = AnthropicMediaHandler(self.model_capabilities)
+
+                    # Create multimodal message combining text and media
+                    multimodal_message = media_handler.create_multimodal_message(prompt, media)
+                    api_messages.append(multimodal_message)
+                except ImportError:
+                    self.logger.warning("Media processing not available. Install with: pip install abstractcore[media]")
+                    api_messages.append({"role": "user", "content": prompt})
+                except Exception as e:
+                    self.logger.warning(f"Failed to process media content: {e}")
+                    api_messages.append({"role": "user", "content": prompt})
+            else:
+                api_messages.append({"role": "user", "content": prompt})
+
+        # Prepare API call parameters (same logic as sync)
+        generation_kwargs = self._prepare_generation_kwargs(**kwargs)
+        max_output_tokens = self._get_provider_max_tokens_param(generation_kwargs)
+
+        call_params = {
+            "model": self.model,
+            "messages": api_messages,
+            "max_tokens": max_output_tokens,
+            "temperature": kwargs.get("temperature", self.temperature),
+            "stream": stream
+        }
+
+        # Add system prompt if provided (Anthropic-specific: separate parameter)
+        if system_prompt:
+            call_params["system"] = system_prompt
+
+        # Add top_p if specified
+        if kwargs.get("top_p") or self.top_p < 1.0:
+            call_params["top_p"] = kwargs.get("top_p", self.top_p)
+
+        # Add top_k if specified
+        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:
+            structured_tool = self._create_structured_output_tool(response_model)
+
+            if tools:
+                tools = list(tools) + [structured_tool]
+            else:
+                tools = [structured_tool]
+
+            structured_tool_name = structured_tool["name"]
+
+            if api_messages and api_messages[-1]["role"] == "user":
+                api_messages[-1]["content"] += f"\n\nPlease use the {structured_tool_name} tool to provide your response."
+
+        # Add tools if provided
+        if tools:
+            if self.tool_handler.supports_native:
+                call_params["tools"] = self._format_tools_for_anthropic(tools)
+
+                if structured_tool_name:
+                    call_params["tool_choice"] = {"type": "tool", "name": structured_tool_name}
+                elif kwargs.get("tool_choice"):
+                    call_params["tool_choice"] = {"type": kwargs.get("tool_choice", "auto")}
+            else:
+                tool_prompt = self.tool_handler.format_tools_prompt(tools)
+                if call_params.get("system"):
+                    call_params["system"] += f"\n\n{tool_prompt}"
+                else:
+                    call_params["system"] = tool_prompt
+
+        # Make async API call
+        try:
+            if stream:
+                return self._async_stream_response(call_params, tools)
+            else:
+                start_time = time.time()
+                response = await self.async_client.messages.create(**call_params)
+                gen_time = round((time.time() - start_time) * 1000, 1)
+
+                formatted = self._format_response(response)
+                formatted.gen_time = gen_time
+
+                if tools and (formatted.has_tool_calls() or
+                             (self.tool_handler.supports_prompted and formatted.content)):
+                    formatted = self._handle_tool_execution(formatted, tools)
+
+                return formatted
+        except Exception as e:
+            error_str = str(e).lower()
+
+            if 'api_key' in error_str or 'authentication' in error_str:
+                raise AuthenticationError(format_auth_error("anthropic", str(e)))
+            elif ('not_found_error' in error_str and 'model:' in error_str) or '404' in error_str:
+                available_models = self.list_available_models(api_key=self.api_key)
+                error_message = format_model_error("Anthropic", self.model, available_models)
+                raise ModelNotFoundError(error_message)
+            else:
+                raise ProviderAPIError(f"Anthropic API error: {str(e)}")
+
+    async def _async_stream_response(self, call_params: Dict[str, Any], tools: Optional[List[Dict[str, Any]]] = None) -> AsyncIterator[GenerateResponse]:
+        """Native async streaming with Anthropic's context manager pattern."""
+        stream_params = {k: v for k, v in call_params.items() if k != 'stream'}
+
+        try:
+            async with self.async_client.messages.stream(**stream_params) as stream:
+                async for chunk in stream:
+                    yield GenerateResponse(
+                        content=getattr(chunk, 'content', ''),
+                        model=self.model,
+                        finish_reason=getattr(chunk, 'finish_reason', None),
+                        raw_response=chunk
+                    )
+        except Exception as e:
+            raise ProviderAPIError(f"Anthropic streaming error: {str(e)}")
+
+    def unload(self) -> None:
+        """Close async client if it was created."""
+        if self._async_client is not None:
+            import asyncio
+            try:
+                loop = asyncio.get_running_loop()
+                loop.create_task(self._async_client.close())
+            except RuntimeError:
+                import asyncio
+                asyncio.run(self._async_client.close())
+
     def _format_tools_for_anthropic(self, tools: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
         """Format tools for Anthropic API format"""
         formatted_tools = []

abstractcore/providers/base.py

@@ -4,8 +4,9 @@ Base provider with integrated telemetry, events, and exception handling.
 
 import time
 import uuid
+import asyncio
 from collections import deque
-from typing import List, Dict, Any, Optional, Union, Iterator, Type
+from typing import List, Dict, Any, Optional, Union, Iterator, AsyncIterator, Type
 from abc import ABC, abstractmethod
 
 try:
@@ -1440,9 +1441,9 @@ Please provide a structured response."""
                 **kwargs) -> Union[GenerateResponse, Iterator[GenerateResponse], BaseModel]:
         """
         Generate response from the LLM.
-        
+
         This method implements the AbstractCoreInterface and delegates to generate_with_telemetry.
-        
+
         Args:
             prompt: The input prompt
             messages: Optional conversation history
@@ -1450,7 +1451,7 @@ Please provide a structured response."""
             tools: Optional list of available tools
             stream: Whether to stream the response
             **kwargs: Additional provider-specific parameters (including response_model)
-            
+
         Returns:
             GenerateResponse, iterator of GenerateResponse for streaming, or BaseModel for structured output
         """
@@ -1461,4 +1462,98 @@ Please provide a structured response."""
             tools=tools,
             stream=stream,
             **kwargs
-        )
+        )
+
+    async def agenerate(self,
+                       prompt: str = "",
+                       messages: Optional[List[Dict]] = None,
+                       system_prompt: Optional[str] = None,
+                       tools: Optional[List] = None,
+                       media: Optional[List] = None,
+                       stream: bool = False,
+                       **kwargs) -> Union[GenerateResponse, AsyncIterator[GenerateResponse], BaseModel]:
+        """
+        Async generation - works with all providers.
+
+        Calls _agenerate_internal() which can be overridden for native async.
+        Default implementation uses asyncio.to_thread() fallback.
+
+        Args:
+            prompt: Text prompt
+            messages: Conversation history
+            system_prompt: System instructions
+            tools: Available tools
+            media: Media attachments
+            stream: Enable streaming
+            **kwargs: Additional generation parameters (including response_model)
+
+        Returns:
+            GenerateResponse, AsyncIterator[GenerateResponse] for streaming, or BaseModel for structured output
+        """
+        return await self._agenerate_internal(
+            prompt, messages, system_prompt, tools, media, stream, **kwargs
+        )
+
+    async def _agenerate_internal(self,
+                                   prompt: str,
+                                   messages: Optional[List[Dict]],
+                                   system_prompt: Optional[str],
+                                   tools: Optional[List],
+                                   media: Optional[List],
+                                   stream: bool,
+                                   **kwargs) -> Union[GenerateResponse, AsyncIterator[GenerateResponse], BaseModel]:
+        """
+        Internal async generation method.
+
+        Default implementation: Uses asyncio.to_thread() to run sync generate().
+        Providers override this for native async (3-10x faster for batch operations).
+
+        Args:
+            prompt: Text prompt
+            messages: Conversation history
+            system_prompt: System instructions
+            tools: Available tools
+            media: Media attachments
+            stream: Enable streaming
+            **kwargs: Additional generation parameters
+
+        Returns:
+            GenerateResponse, AsyncIterator[GenerateResponse] for streaming, or BaseModel for structured output
+        """
+        if stream:
+            # Return async iterator for streaming
+            return self._async_stream_generate(
+                prompt, messages, system_prompt, tools, media, **kwargs
+            )
+        else:
+            # Run sync generate in thread pool (fallback)
+            return await asyncio.to_thread(
+                self.generate,
+                prompt, messages, system_prompt, tools, stream, **kwargs
+            )
+
+    async def _async_stream_generate(self,
+                                     prompt: str,
+                                     messages: Optional[List[Dict]],
+                                     system_prompt: Optional[str],
+                                     tools: Optional[List],
+                                     media: Optional[List],
+                                     **kwargs) -> AsyncIterator[GenerateResponse]:
+        """
+        Async streaming generator.
+
+        Wraps sync streaming in async iterator, yielding control to event loop.
+        """
+        # Get sync generator in thread pool
+        def get_sync_stream():
+            return self.generate(
+                prompt, messages, system_prompt, tools,
+                stream=True, **kwargs
+            )
+
+        sync_gen = await asyncio.to_thread(get_sync_stream)
+
+        # Yield chunks asynchronously
+        for chunk in sync_gen:
+            yield chunk
+            await asyncio.sleep(0)  # Yield control to event loop