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

abstractcore/providers/openai_provider.py

@@ -5,7 +5,7 @@ OpenAI 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 OpenAIProvider(BaseProvider):
     """OpenAI API provider with full integration"""
 
-    def __init__(self, model: str = "gpt-3.5-turbo", api_key: Optional[str] = None, **kwargs):
+    def __init__(self, model: str = "gpt-3.5-turbo", api_key: Optional[str] = None,
+                 base_url: Optional[str] = None, **kwargs):
         super().__init__(model, **kwargs)
         self.provider = "openai"
 
@@ -42,8 +43,15 @@ class OpenAIProvider(BaseProvider):
         if not self.api_key:
             raise ValueError("OpenAI API key required. Set OPENAI_API_KEY environment variable.")
 
-        # Initialize client with timeout
-        self.client = openai.OpenAI(api_key=self.api_key, timeout=self._timeout)
+        # Get base URL from param or environment
+        self.base_url = base_url or os.getenv("OPENAI_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 = openai.OpenAI(**client_kwargs)
+        self._async_client = None  # Lazy-loaded async client
 
         # Initialize tool handler
         self.tool_handler = UniversalToolHandler(model)
@@ -60,6 +68,16 @@ class OpenAIProvider(BaseProvider):
         """Public generate method that includes telemetry"""
         return self.generate_with_telemetry(*args, **kwargs)
 
+    @property
+    def async_client(self):
+        """Lazy-load AsyncOpenAI 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 = openai.AsyncOpenAI(**client_kwargs)
+        return self._async_client
+
     def _generate_internal(self,
                           prompt: str,
                           messages: Optional[List[Dict[str, str]]] = None,
@@ -188,6 +206,228 @@ class OpenAIProvider(BaseProvider):
             # Model validation is done at initialization, so this is likely an API error
             raise ProviderAPIError(f"OpenAI 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 AsyncOpenAI - 3-10x faster for batch operations."""
+
+        # Build messages array (same logic as sync)
+        api_messages = []
+
+        # Add system message if provided
+        if system_prompt:
+            api_messages.append({"role": "system", "content": system_prompt})
+
+        # Add conversation history
+        if messages:
+            for msg in messages:
+                # Skip system messages as they're handled separately
+                if msg.get("role") != "system":
+                    api_messages.append({
+                        "role": msg["role"],
+                        "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 OpenAIMediaHandler
+                    media_handler = OpenAIMediaHandler(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 using unified system (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,
+            "stream": stream
+        }
+
+        # Add parameters that are supported by this model
+        if not self._is_reasoning_model():
+            # Reasoning models (o1, gpt-5) don't support many parameters
+            call_params["temperature"] = kwargs.get("temperature", self.temperature)
+            call_params["top_p"] = kwargs.get("top_p", self.top_p)
+            call_params["frequency_penalty"] = kwargs.get("frequency_penalty", self.frequency_penalty)
+            call_params["presence_penalty"] = kwargs.get("presence_penalty", self.presence_penalty)
+
+            # Add seed if provided (OpenAI supports seed for deterministic outputs)
+            seed_value = kwargs.get("seed", self.seed)
+            if seed_value is not None:
+                call_params["seed"] = seed_value
+
+        # Handle different token parameter names for different model families
+        if self._uses_max_completion_tokens():
+            call_params["max_completion_tokens"] = max_output_tokens
+        else:
+            call_params["max_tokens"] = max_output_tokens
+
+        # Add tools if provided (convert to native format)
+        if tools:
+            # Convert tools to native format for OpenAI API
+            if self.tool_handler.supports_native:
+                call_params["tools"] = self.tool_handler.prepare_tools_for_native(tools)
+                call_params["tool_choice"] = kwargs.get("tool_choice", "auto")
+            else:
+                # Fallback to manual formatting
+                call_params["tools"] = self._format_tools_for_openai(tools)
+                call_params["tool_choice"] = kwargs.get("tool_choice", "auto")
+
+        # Add structured output support (OpenAI native)
+        if response_model and PYDANTIC_AVAILABLE:
+            if self._supports_structured_output():
+                json_schema = response_model.model_json_schema()
+
+                # OpenAI requires additionalProperties: false for strict mode
+                self._ensure_strict_schema(json_schema)
+
+                call_params["response_format"] = {
+                    "type": "json_schema",
+                    "json_schema": {
+                        "name": response_model.__name__,
+                        "strict": True,
+                        "schema": json_schema
+                    }
+                }
+
+        # Make async API call with proper exception handling
+        try:
+            if stream:
+                return self._async_stream_response(call_params, tools)
+            else:
+                # Track generation time
+                start_time = time.time()
+                response = await self.async_client.chat.completions.create(**call_params)
+                gen_time = round((time.time() - start_time) * 1000, 1)
+
+                formatted = self._format_response(response)
+                # Add generation time to response
+                formatted.gen_time = gen_time
+
+                # Handle tool execution for OpenAI native responses
+                if tools and formatted.has_tool_calls():
+                    formatted = self._handle_tool_execution(formatted, tools)
+
+                return formatted
+        except Exception as e:
+            # Model validation is done at initialization, so this is likely an API error
+            raise ProviderAPIError(f"OpenAI 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 responses from OpenAI."""
+        try:
+            stream = await self.async_client.chat.completions.create(**call_params)
+        except Exception as e:
+            # Model validation is done at initialization, so this is likely an API error
+            raise ProviderAPIError(f"OpenAI API error: {str(e)}")
+
+        # For streaming with tools, we need to collect the complete response
+        collected_content = ""
+        collected_tool_calls = {}  # Use dict to merge streaming chunks by tool call ID
+        final_response = None
+
+        async for chunk in stream:
+            choice = chunk.choices[0] if chunk.choices else None
+            if not choice:
+                continue
+
+            delta = choice.delta
+            content = getattr(delta, 'content', None) or ""
+            collected_content += content
+
+            # Handle tool calls in streaming - merge incomplete chunks
+            if hasattr(delta, 'tool_calls') and delta.tool_calls:
+                for tc in delta.tool_calls:
+                    tc_id = getattr(tc, 'id', None) or getattr(tc, 'index', 0)
+
+                    # Initialize or get existing tool call
+                    if tc_id not in collected_tool_calls:
+                        collected_tool_calls[tc_id] = {
+                            "id": getattr(tc, 'id', None),
+                            "type": getattr(tc, 'type', 'function'),
+                            "name": None,
+                            "arguments": ""
+                        }
+
+                    # Update with new data from this chunk
+                    if hasattr(tc, 'function'):
+                        if hasattr(tc.function, 'name') and tc.function.name:
+                            collected_tool_calls[tc_id]["name"] = tc.function.name
+                        if hasattr(tc.function, 'arguments') and tc.function.arguments:
+                            collected_tool_calls[tc_id]["arguments"] += tc.function.arguments
+
+            # Create chunk response
+            chunk_response = GenerateResponse(
+                content=content,
+                raw_response=chunk,
+                model=chunk.model,
+                finish_reason=choice.finish_reason,
+                tool_calls=None  # Don't include incomplete tool calls in chunks
+            )
+
+            # If this is the final chunk and we have tools, handle tool execution
+            if choice.finish_reason and tools and collected_tool_calls:
+                # Convert dict to list and filter out incomplete tool calls
+                complete_tool_calls = []
+                for tc in collected_tool_calls.values():
+                    if tc["name"] and tc["arguments"] is not None:  # Include tool calls with empty args
+                        complete_tool_calls.append(tc)
+
+                # Create complete response for tool processing
+                complete_response = GenerateResponse(
+                    content=collected_content,
+                    raw_response=chunk,
+                    model=chunk.model,
+                    finish_reason=choice.finish_reason,
+                    tool_calls=complete_tool_calls if complete_tool_calls else None
+                )
+
+                # Handle tool execution
+                final_response = self._handle_tool_execution(complete_response, tools)
+
+                # If tools were executed, yield the tool results as final chunk
+                if final_response.content != collected_content:
+                    tool_results_content = final_response.content[len(collected_content):]
+                    yield GenerateResponse(
+                        content=tool_results_content,
+                        raw_response=chunk,
+                        model=chunk.model,
+                        finish_reason=choice.finish_reason,
+                        tool_calls=None
+                    )
+                else:
+                    # No tools executed but response was processed - yield final response content
+                    yield GenerateResponse(
+                        content=final_response.content,
+                        raw_response=chunk,
+                        model=chunk.model,
+                        finish_reason=choice.finish_reason,
+                        tool_calls=complete_tool_calls if complete_tool_calls else None
+                    )
+            else:
+                yield chunk_response
+
     def _format_tools_for_openai(self, tools: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
         """Format tools for OpenAI API format"""
         formatted_tools = []
@@ -391,6 +631,18 @@ class OpenAIProvider(BaseProvider):
             return False
         return True
 
+    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:
+                # No running loop, close synchronously
+                import asyncio
+                asyncio.run(self._async_client.close())
+
     def _validate_model_exists(self):
         """Preflight check to validate model exists before any generation"""
         try:
@@ -410,7 +662,7 @@ class OpenAIProvider(BaseProvider):
             # For other errors (like API failures), handle gracefully
             error_str = str(e).lower()
             if 'api_key' in error_str or 'authentication' in error_str:
-                raise AuthenticationError(f"OpenAI authentication failed: {str(e)}")
+                raise AuthenticationError(format_auth_error("openai", str(e)))
             # For other API errors during preflight, continue (model might work)
             # This allows for cases where models.list() fails but generation works
 
@@ -511,9 +763,21 @@ class OpenAIProvider(BaseProvider):
 
     @classmethod
     def list_available_models(cls, **kwargs) -> List[str]:
-        """List available models from OpenAI API."""
+        """
+        List available models from OpenAI API.
+
+        Args:
+            **kwargs: Optional parameters including:
+                - api_key: OpenAI API key
+                - 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:
             import openai
+            from .model_capabilities import filter_models_by_capabilities
 
             # Get API key from kwargs or environment
             api_key = kwargs.get('api_key') or os.getenv("OPENAI_API_KEY")
@@ -542,7 +806,21 @@ class OpenAIProvider(BaseProvider):
                     ]):
                         chat_models.append(model_id)
 
-            return sorted(chat_models, reverse=True)  # Latest models first
+            chat_models = sorted(chat_models, reverse=True)  # Latest models first
+
+            # Apply new capability filtering if provided
+            input_capabilities = kwargs.get('input_capabilities')
+            output_capabilities = kwargs.get('output_capabilities')
+            
+            if input_capabilities or output_capabilities:
+                chat_models = filter_models_by_capabilities(
+                    chat_models, 
+                    input_capabilities=input_capabilities,
+                    output_capabilities=output_capabilities
+                )
+
+
+            return chat_models
 
         except Exception:
             return []

abstractcore/providers/registry.py

@@ -202,10 +202,14 @@ class ProviderRegistry:
 
         Args:
             provider_name: Name of the provider
-            **kwargs: Provider-specific parameters (e.g., api_key, base_url)
+            **kwargs: Provider-specific parameters including:
+                - api_key: API key for authentication (if required)
+                - base_url: Base URL for API endpoint (if applicable)
+                - 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 available model names
+            List of available model names, optionally filtered by capabilities
         """
         try:
             provider_class = self.get_provider_class(provider_name)
@@ -285,13 +289,64 @@ class ProviderRegistry:
             for provider_name in self.list_provider_names()
         ]
 
-    def get_providers_with_models(self) -> List[Dict[str, Any]]:
-        """Get only providers that have available models."""
-        all_providers = self.get_all_providers_status()
-        return [
-            provider for provider in all_providers
-            if provider.get("status") == "available" and provider.get("model_count", 0) > 0
-        ]
+    def get_providers_with_models(self, include_models: bool = True) -> List[Dict[str, Any]]:
+        """
+        Get only providers that have available models.
+        
+        Args:
+            include_models: If True, include actual model lists (slower).
+                           If False, return metadata only (much faster). Default: True.
+        """
+        if include_models:
+            # Original behavior - get full status including model lists
+            all_providers = self.get_all_providers_status()
+            return [
+                provider for provider in all_providers
+                if provider.get("status") == "available" and provider.get("model_count", 0) > 0
+            ]
+        else:
+            # Fast path - get all provider metadata without model enumeration
+            # Note: We return all providers since we can't quickly determine which have models
+            return self.get_providers_metadata_only()
+
+    def get_providers_metadata_only(self) -> List[Dict[str, Any]]:
+        """
+        Get provider metadata without enumerating models (fast path).
+        
+        This method returns provider information without making API calls
+        or scanning for models, making it extremely fast for UI discovery.
+        """
+        providers_metadata = []
+        
+        for provider_name in self.list_provider_names():
+            provider_info = self.get_provider_info(provider_name)
+            if not provider_info:
+                continue
+                
+            # Basic availability check without model enumeration
+            try:
+                provider_class = self.get_provider_class(provider_name)
+                status = "available"  # Assume available if class can be imported
+            except Exception:
+                status = "error"
+            
+            metadata = {
+                "name": provider_info.name,
+                "display_name": provider_info.display_name,
+                "type": provider_info.provider_type,
+                "model_count": "unknown",  # Don't enumerate models
+                "status": status,
+                "description": provider_info.description,
+                "local_provider": provider_info.local_provider,
+                "authentication_required": provider_info.authentication_required,
+                "supported_features": provider_info.supported_features,
+                "installation_extras": provider_info.installation_extras,
+                "models": []  # Empty list for fast response
+            }
+            
+            providers_metadata.append(metadata)
+        
+        return providers_metadata
 
     def create_provider_instance(self, provider_name: str, model: Optional[str] = None, **kwargs):
         """
@@ -348,7 +403,7 @@ def is_provider_available(provider_name: str) -> bool:
     return get_provider_registry().is_provider_available(provider_name)
 
 
-def get_all_providers_with_models() -> List[Dict[str, Any]]:
+def get_all_providers_with_models(include_models: bool = True) -> List[Dict[str, Any]]:
     """
     Get comprehensive information about all providers with available models.
 
@@ -356,14 +411,18 @@ def get_all_providers_with_models() -> List[Dict[str, Any]]:
     for provider discovery and information. It replaces the manual provider
     lists in factory.py and server/app.py.
 
+    Args:
+        include_models: If True, include actual model lists (slower). 
+                       If False, return metadata only (much faster). Default: True.
+
     Returns:
         List of provider dictionaries with comprehensive metadata including:
         - name, display_name, type, description
         - model_count, status, supported_features
         - local_provider, authentication_required
-        - installation_extras, sample models
+        - installation_extras, sample models (if include_models=True)
     """
-    return get_provider_registry().get_providers_with_models()
+    return get_provider_registry().get_providers_with_models(include_models=include_models)
 
 
 def get_all_providers_status() -> List[Dict[str, Any]]:
@@ -386,5 +445,18 @@ def create_provider(provider_name: str, model: Optional[str] = None, **kwargs):
 
 
 def get_available_models_for_provider(provider_name: str, **kwargs) -> List[str]:
-    """Get available models for a specific provider."""
+    """
+    Get available models for a specific provider.
+    
+    Args:
+        provider_name: Name of the provider
+        **kwargs: Provider-specific parameters including:
+            - api_key: API key for authentication (if required)
+            - base_url: Base URL for API endpoint (if applicable)
+            - 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 available model names, optionally filtered by capabilities
+    """
     return get_provider_registry().get_available_models(provider_name, **kwargs)

abstractcore/providers/streaming.py

@@ -7,15 +7,15 @@ while maintaining real-time streaming performance, with proper tag rewriting sup
 
 import json
 import re
-import logging
 import uuid
 from typing import List, Dict, Any, Optional, Iterator, Tuple
 from enum import Enum
 
 from ..core.types import GenerateResponse
 from ..tools.core import ToolCall
+from ..utils.structured_logging import get_logger
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 class ToolDetectionState(Enum):