abstractcore 2.9.1__py3-none-any.whl → 2.11.2__py3-none-any.whl

abstractcore/providers/openai_provider.py

@@ -5,6 +5,7 @@ OpenAI provider implementation.
 import os
 import json
 import time
+import warnings
 from typing import List, Dict, Any, Optional, Union, Iterator, AsyncIterator, Type
 
 try:
@@ -15,7 +16,6 @@ except ImportError:
     BaseModel = None
 from .base import BaseProvider
 from ..core.types import GenerateResponse
-from ..media import MediaHandler
 from ..exceptions import AuthenticationError, ProviderAPIError, ModelNotFoundError, format_model_error, format_auth_error
 from ..tools import UniversalToolHandler, execute_tools
 from ..events import EventType
@@ -106,25 +106,64 @@ class OpenAIProvider(BaseProvider):
                         "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})
+        media_enrichment = None
+
+        # Handle media content regardless of prompt (media can be used with messages too)
+        if media:
+            # Get the last user message content to combine with media
+            user_message_text = prompt.strip() if prompt else ""
+            if not user_message_text and api_messages:
+                # If no prompt, try to get text from the last user message
+                for msg in reversed(api_messages):
+                    if msg.get("role") == "user" and msg.get("content"):
+                        user_message_text = msg["content"]
+                        break
+
+            replace_last_user = False
+            if api_messages and api_messages[-1].get("role") == "user":
+                last_content = api_messages[-1].get("content")
+                # Only replace the last user message when prompt is empty (prompt already in messages)
+                # or when the prompt is the same as the last user content (avoid duplication).
+                if (not prompt.strip()) or (last_content == user_message_text):
+                    replace_last_user = True
+
+            try:
+                # Process media files into MediaContent objects first
+                processed_media = self._process_media_content(media)
+
+                # Use capability-based media handler selection (vision vs fallback)
+                media_handler = self._get_media_handler_for_model(self.model)
+
+                # Create multimodal message combining text and processed media
+                multimodal_message = media_handler.create_multimodal_message(user_message_text, processed_media)
+                media_enrichment = getattr(media_handler, "media_enrichment", None)
+
+                if isinstance(multimodal_message, str):
+                    if replace_last_user:
+                        api_messages[-1]["content"] = multimodal_message
+                    else:
+                        api_messages.append({"role": "user", "content": multimodal_message})
+                else:
+                    if replace_last_user:
+                        api_messages[-1] = multimodal_message
+                    else:
+                        api_messages.append(multimodal_message)
+            except ImportError:
+                self.logger.warning("Media processing not available. Install with: pip install \"abstractcore[media]\"")
+                if user_message_text and not replace_last_user:
+                    api_messages.append({"role": "user", "content": user_message_text})
+            except Exception as e:
+                # Do not silently drop user-supplied media. Fail loudly so callers can
+                # choose an explicit fallback policy (e.g. audio_policy='speech_to_text').
+                from ..exceptions import UnsupportedFeatureError
+
+                raise UnsupportedFeatureError(
+                    f"OpenAI provider could not format attached media for model '{self.model}': {e}"
+                ) from e
+
+        # Add prompt as separate message if provided (for backward compatibility)
+        elif prompt and prompt not in [msg.get("content") for msg in (messages or [])]:
+            api_messages.append({"role": "user", "content": prompt})
 
         # Prepare API call parameters using unified system
         generation_kwargs = self._prepare_generation_kwargs(**kwargs)
@@ -136,18 +175,38 @@ class OpenAIProvider(BaseProvider):
             "stream": stream
         }
 
+        # Prompt caching (OpenAI): best-effort pass-through via `prompt_cache_key`.
+        prompt_cache_key = kwargs.get("prompt_cache_key")
+        if isinstance(prompt_cache_key, str) and prompt_cache_key.strip():
+            call_params["prompt_cache_key"] = prompt_cache_key.strip()
+
         # 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["temperature"] = generation_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)
+            seed_value = generation_kwargs.get("seed")
             if seed_value is not None:
                 call_params["seed"] = seed_value
+        else:
+            # Best-effort: expose a warning when a caller requests params that are ignored.
+            seed_value = generation_kwargs.get("seed")
+            if seed_value is not None:
+                warnings.warn(
+                    f"Seed parameter ({seed_value}) requested but not supported by OpenAI reasoning models ({self.model}).",
+                    RuntimeWarning,
+                    stacklevel=2,
+                )
+            if ("temperature" in kwargs) or (getattr(self, "temperature", 0.7) != 0.7):
+                warnings.warn(
+                    f"Temperature parameter requested but not supported by OpenAI reasoning models ({self.model}).",
+                    RuntimeWarning,
+                    stacklevel=2,
+                )
 
         # Handle different token parameter names for different model families
         if self._uses_max_completion_tokens():
@@ -199,6 +258,10 @@ class OpenAIProvider(BaseProvider):
                 # Runtime observability: capture the exact client payload we sent.
                 formatted.metadata = dict(formatted.metadata or {})
                 formatted.metadata["_provider_request"] = {"call_params": call_params}
+                if media_enrichment:
+                    from ..media.enrichment import merge_enrichment_metadata
+
+                    formatted.metadata = merge_enrichment_metadata(formatted.metadata, media_enrichment)
 
                 # Handle tool execution for OpenAI native responses
                 if tools and formatted.has_tool_calls():
@@ -237,25 +300,56 @@ class OpenAIProvider(BaseProvider):
                         "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})
+        media_enrichment = None
+
+        # Handle media content regardless of prompt (media can be used with messages too)
+        if media:
+            # Get the last user message content to combine with media
+            user_message_text = prompt.strip() if prompt else ""
+            if not user_message_text and api_messages:
+                # If no prompt, try to get text from the last user message
+                for msg in reversed(api_messages):
+                    if msg.get("role") == "user" and msg.get("content"):
+                        user_message_text = msg["content"]
+                        break
+
+            replace_last_user = False
+            if api_messages and api_messages[-1].get("role") == "user":
+                last_content = api_messages[-1].get("content")
+                if (not prompt.strip()) or (last_content == user_message_text):
+                    replace_last_user = True
+
+            try:
+                processed_media = self._process_media_content(media)
+                media_handler = self._get_media_handler_for_model(self.model)
+                multimodal_message = media_handler.create_multimodal_message(user_message_text, processed_media)
+                media_enrichment = getattr(media_handler, "media_enrichment", None)
+
+                if isinstance(multimodal_message, str):
+                    if replace_last_user:
+                        api_messages[-1]["content"] = multimodal_message
+                    else:
+                        api_messages.append({"role": "user", "content": multimodal_message})
+                else:
+                    if replace_last_user:
+                        api_messages[-1] = multimodal_message
+                    else:
+                        api_messages.append(multimodal_message)
+
+            except ImportError:
+                self.logger.warning("Media processing not available. Install with: pip install \"abstractcore[media]\"")
+                if user_message_text and not replace_last_user:
+                    api_messages.append({"role": "user", "content": user_message_text})
+            except Exception as e:
+                from ..exceptions import UnsupportedFeatureError
+
+                raise UnsupportedFeatureError(
+                    f"OpenAI provider could not format attached media for model '{self.model}': {e}"
+                ) from e
+
+        # Add prompt as separate message if provided (for backward compatibility)
+        elif prompt and prompt not in [msg.get("content") for msg in (messages or [])]:
+            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)
@@ -267,18 +361,37 @@ class OpenAIProvider(BaseProvider):
             "stream": stream
         }
 
+        # Prompt caching (OpenAI): best-effort pass-through via `prompt_cache_key`.
+        prompt_cache_key = kwargs.get("prompt_cache_key")
+        if isinstance(prompt_cache_key, str) and prompt_cache_key.strip():
+            call_params["prompt_cache_key"] = prompt_cache_key.strip()
+
         # 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["temperature"] = generation_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)
+            seed_value = generation_kwargs.get("seed")
             if seed_value is not None:
                 call_params["seed"] = seed_value
+        else:
+            seed_value = generation_kwargs.get("seed")
+            if seed_value is not None:
+                warnings.warn(
+                    f"Seed parameter ({seed_value}) requested but not supported by OpenAI reasoning models ({self.model}).",
+                    RuntimeWarning,
+                    stacklevel=2,
+                )
+            if ("temperature" in kwargs) or (getattr(self, "temperature", 0.7) != 0.7):
+                warnings.warn(
+                    f"Temperature parameter requested but not supported by OpenAI reasoning models ({self.model}).",
+                    RuntimeWarning,
+                    stacklevel=2,
+                )
 
         # Handle different token parameter names for different model families
         if self._uses_max_completion_tokens():
@@ -329,6 +442,10 @@ class OpenAIProvider(BaseProvider):
                 formatted.gen_time = gen_time
                 formatted.metadata = dict(formatted.metadata or {})
                 formatted.metadata["_provider_request"] = {"call_params": call_params}
+                if media_enrichment:
+                    from ..media.enrichment import merge_enrichment_metadata
+
+                    formatted.metadata = merge_enrichment_metadata(formatted.metadata, media_enrichment)
 
                 # Handle tool execution for OpenAI native responses
                 if tools and formatted.has_tool_calls():
@@ -609,6 +726,33 @@ class OpenAIProvider(BaseProvider):
             else:
                 yield chunk_response
 
+    def _get_media_handler_for_model(self, model_name: str):
+        """Get appropriate media handler based on model vision capabilities."""
+        from ..media.handlers import OpenAIMediaHandler, LocalMediaHandler
+
+        # Determine if model supports vision
+        try:
+            from ..architectures.detection import supports_vision
+
+            use_vision_handler = supports_vision(model_name)
+        except Exception as e:
+            self.logger.debug(f"Vision detection failed: {e}, defaulting to LocalMediaHandler")
+            use_vision_handler = False
+
+        # Create appropriate handler
+        if use_vision_handler:
+            handler = OpenAIMediaHandler(self.model_capabilities, model_name=model_name)
+            self.logger.debug(f"Using OpenAIMediaHandler for vision model: {model_name}")
+        else:
+            handler = LocalMediaHandler(self.provider, self.model_capabilities, model_name=model_name)
+            self.logger.debug(f"Using LocalMediaHandler for model: {model_name}")
+
+        return handler
+
+    def supports_prompt_cache(self) -> bool:
+        """OpenAI supports prompt caching via `prompt_cache_key` (server-managed)."""
+        return True
+
     def get_capabilities(self) -> List[str]:
         """Get list of capabilities supported by this provider"""
         capabilities = [
@@ -634,7 +778,7 @@ class OpenAIProvider(BaseProvider):
             return False
         return True
 
-    def unload(self) -> None:
+    def unload_model(self, model_name: str) -> None:
         """Close async client if it was created."""
         if self._async_client is not None:
             import asyncio

abstractcore/providers/openrouter_provider.py

@@ -0,0 +1,76 @@
+"""
+OpenRouter provider (OpenAI-compatible API).
+
+OpenRouter exposes an OpenAI-compatible API at `https://openrouter.ai/api/v1`.
+This provider subclasses `OpenAICompatibleProvider` and adds:
+- API key support via `OPENROUTER_API_KEY` (or AbstractCore config fallback)
+- Optional OpenRouter metadata headers (`HTTP-Referer`, `X-Title`)
+"""
+
+import os
+from typing import Optional, Dict
+
+from .openai_compatible_provider import OpenAICompatibleProvider
+
+
+class OpenRouterProvider(OpenAICompatibleProvider):
+    """OpenRouter provider using OpenAI-compatible API."""
+
+    PROVIDER_ID = "openrouter"
+    PROVIDER_DISPLAY_NAME = "OpenRouter"
+    BASE_URL_ENV_VAR = "OPENROUTER_BASE_URL"
+    API_KEY_ENV_VAR = "OPENROUTER_API_KEY"
+    DEFAULT_BASE_URL = "https://openrouter.ai/api/v1"
+
+    def __init__(
+        self,
+        model: str = "openai/gpt-4o-mini",
+        base_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        **kwargs,
+    ):
+        super().__init__(model=model, base_url=base_url, api_key=api_key, **kwargs)
+
+        if not self._has_api_key():
+            raise ValueError(
+                "OpenRouter API key required. Set OPENROUTER_API_KEY or configure via "
+                "`abstractcore --set-api-key openrouter <key>`."
+            )
+
+    def _has_api_key(self) -> bool:
+        if self.api_key is None:
+            return False
+        key = str(self.api_key).strip()
+        if not key:
+            return False
+        return key.upper() != "EMPTY"
+
+    def _get_api_key_from_config(self) -> Optional[str]:
+        try:
+            from ..config.manager import get_config_manager
+
+            cfg = get_config_manager()
+            return getattr(cfg.config.api_keys, "openrouter", None)
+        except Exception:
+            return None
+
+    def _validate_model(self):
+        # Avoid unauthenticated network calls on init; OpenRouter generally requires a key.
+        if not self._has_api_key():
+            return
+        return super()._validate_model()
+
+    def _get_headers(self) -> Dict[str, str]:
+        headers = super()._get_headers()
+
+        # OpenRouter recommends sending these for better analytics / abuse prevention.
+        site_url = os.getenv("OPENROUTER_SITE_URL")
+        if isinstance(site_url, str) and site_url.strip():
+            headers["HTTP-Referer"] = site_url.strip()
+
+        app_name = os.getenv("OPENROUTER_APP_NAME")
+        if isinstance(app_name, str) and app_name.strip():
+            headers["X-Title"] = app_name.strip()
+
+        return headers
+

abstractcore/providers/registry.py

@@ -6,6 +6,7 @@ eliminating the need for manual synchronization across factory.py, server/app.py
 and __init__.py files.
 """
 
+import os
 from typing import List, Dict, Any, Optional, Type, Callable
 from dataclasses import dataclass, field
 from abc import ABC
@@ -49,6 +50,30 @@ class ProviderRegistry:
         self._logger = get_logger("ProviderRegistry")
         self._register_all_providers()
 
+    def _has_configured_base_url(self, provider_name: str, *, env_var: str) -> bool:
+        """Return True if a provider has an explicit base_url configured.
+
+        We intentionally treat providers like `openai-compatible` / `vllm` as *opt-in* for
+        model probing: their defaults (8080/8000) are not universally valid and can cause
+        noisy timeouts in multi-service dev environments.
+        """
+        if isinstance(env_var, str) and env_var.strip():
+            env_val = os.getenv(env_var)
+            if isinstance(env_val, str) and env_val.strip():
+                return True
+
+        try:
+            from ..config import get_provider_config
+
+            cfg = get_provider_config(provider_name)
+            base_url = cfg.get("base_url")
+            if isinstance(base_url, str) and base_url.strip():
+                return True
+        except Exception:
+            pass
+
+        return False
+
     def _register_all_providers(self):
         """Register all available providers with their metadata."""
 
@@ -71,8 +96,8 @@ class ProviderRegistry:
             name="anthropic",
             display_name="Anthropic",
             provider_class=None,
-            description="Commercial API with Claude 3 family models",
-            default_model="claude-3-5-haiku-latest",
+            description="Commercial API with Claude models",
+            default_model="claude-haiku-4-5",
             supported_features=["chat", "completion", "native_tools", "streaming", "structured_output"],
             authentication_required=True,
             local_provider=False,
@@ -166,6 +191,20 @@ class ProviderRegistry:
             import_path="..providers.openai_compatible_provider"
         ))
 
+        # OpenRouter Provider
+        self.register_provider(ProviderInfo(
+            name="openrouter",
+            display_name="OpenRouter",
+            provider_class=None,
+            description="OpenAI-compatible aggregator API (multi-provider routing and unified billing)",
+            default_model="openai/gpt-4o-mini",
+            supported_features=["chat", "completion", "embeddings", "native_tools", "streaming", "structured_output"],
+            authentication_required=True,
+            local_provider=False,
+            installation_extras=None,
+            import_path="..providers.openrouter_provider"
+        ))
+
 
     def register_provider(self, provider_info: ProviderInfo):
         """Register a provider in the registry."""
@@ -223,13 +262,16 @@ class ProviderRegistry:
             elif provider_info.name == "openai-compatible":
                 from ..providers.openai_compatible_provider import OpenAICompatibleProvider
                 return OpenAICompatibleProvider
+            elif provider_info.name == "openrouter":
+                from ..providers.openrouter_provider import OpenRouterProvider
+                return OpenRouterProvider
             else:
                 raise ImportError(f"No import logic for provider: {provider_info.name}")
         except ImportError as e:
             self._logger.warning(f"Failed to load provider {provider_info.name}: {e}")
             raise ImportError(
                 f"{provider_info.display_name} dependencies not installed. "
-                f"Install with: pip install abstractcore[{provider_info.installation_extras}]"
+                f"Install with: pip install \"abstractcore[{provider_info.installation_extras}]\""
             ) from e
 
     def get_available_models(self, provider_name: str, **kwargs) -> List[str]:
@@ -248,6 +290,20 @@ class ProviderRegistry:
             List of available model names, optionally filtered by capabilities
         """
         try:
+            provider_name_norm = str(provider_name or "").strip().lower()
+            base_url_override = kwargs.get("base_url")
+
+            # Avoid probing generic OpenAI-compatible endpoints unless explicitly configured.
+            # (Default ports like :8080/:8000 are often wrong in real setups.)
+            if provider_name_norm == "openai-compatible" and not (
+                isinstance(base_url_override, str) and base_url_override.strip()
+            ):
+                if not self._has_configured_base_url(provider_name_norm, env_var="OPENAI_COMPATIBLE_BASE_URL"):
+                    return []
+            if provider_name_norm == "vllm" and not (isinstance(base_url_override, str) and base_url_override.strip()):
+                if not self._has_configured_base_url(provider_name_norm, env_var="VLLM_BASE_URL"):
+                    return []
+
             provider_class = self.get_provider_class(provider_name)
 
             # Handle providers that need instance for model listing
@@ -413,7 +469,7 @@ class ProviderRegistry:
             if provider_info.installation_extras:
                 raise ImportError(
                     f"{provider_info.display_name} dependencies not installed. "
-                    f"Install with: pip install abstractcore[{provider_info.installation_extras}]"
+                    f"Install with: pip install \"abstractcore[{provider_info.installation_extras}]\""
                 ) from e
             else:
                 raise ImportError(f"{provider_info.display_name} provider not available") from e
@@ -503,4 +559,4 @@ def get_available_models_for_provider(provider_name: str, **kwargs) -> List[str]
     Returns:
         List of available model names, optionally filtered by capabilities
     """
-    return get_provider_registry().get_available_models(provider_name, **kwargs)
+    return get_provider_registry().get_available_models(provider_name, **kwargs)