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

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