mirascope 2.1.0__py3-none-any.whl → 2.2.0__py3-none-any.whl

mirascope/llm/prompts/prompts.py

@@ -1,7 +1,6 @@
 """Concrete Prompt classes for generating messages with tools and formatting."""
 
 from collections.abc import Callable, Sequence
-from dataclasses import dataclass, field
 from typing import Any, Generic, TypeVar, overload
 
 from ..._utils import copy_function_metadata
@@ -32,22 +31,20 @@ from .protocols import (
 FunctionT = TypeVar("FunctionT", bound=Callable[..., Any])
 
 
-@dataclass(kw_only=True)
 class BasePrompt(Generic[FunctionT]):
     """Base class for all Prompt types with shared metadata functionality."""
 
     fn: FunctionT
     """The underlying prompt function that generates message content."""
 
-    __name__: str = field(init=False, repr=False, default="")
+    __name__: str = ""
     """The name of the underlying function (preserved for decorator stacking)."""
 
-    def __post_init__(self) -> None:
-        """Preserve standard function attributes for decorator stacking."""
+    def __init__(self, *, fn: FunctionT) -> None:
+        self.fn = fn
         copy_function_metadata(self, self.fn)
 
 
-@dataclass
 class Prompt(BasePrompt[MessageTemplate[P]], Generic[P, FormattableT]):
     """A prompt that can be called with a model to generate a response.
 
@@ -64,6 +61,17 @@ class Prompt(BasePrompt[MessageTemplate[P]], Generic[P, FormattableT]):
     format: FormatSpec[FormattableT] | None
     """The response format for the generated response."""
 
+    def __init__(
+        self,
+        *,
+        fn: MessageTemplate[P],
+        toolkit: Toolkit,
+        format: FormatSpec[FormattableT] | None,
+    ) -> None:
+        self.toolkit = toolkit
+        self.format = format
+        super().__init__(fn=fn)
+
     def messages(self, *args: P.args, **kwargs: P.kwargs) -> Sequence[Message]:
         """Return the `Messages` from invoking this prompt."""
         return promote_to_messages(self.fn(*args, **kwargs))
@@ -141,7 +149,6 @@ class Prompt(BasePrompt[MessageTemplate[P]], Generic[P, FormattableT]):
         return model.stream(messages, tools=self.toolkit, format=self.format)
 
 
-@dataclass
 class AsyncPrompt(BasePrompt[AsyncMessageTemplate[P]], Generic[P, FormattableT]):
     """An async prompt that can be called with a model to generate a response.
 
@@ -158,6 +165,17 @@ class AsyncPrompt(BasePrompt[AsyncMessageTemplate[P]], Generic[P, FormattableT])
     format: FormatSpec[FormattableT] | None
     """The response format for the generated response."""
 
+    def __init__(
+        self,
+        *,
+        fn: AsyncMessageTemplate[P],
+        toolkit: AsyncToolkit,
+        format: FormatSpec[FormattableT] | None,
+    ) -> None:
+        self.toolkit = toolkit
+        self.format = format
+        super().__init__(fn=fn)
+
     async def messages(self, *args: P.args, **kwargs: P.kwargs) -> Sequence[Message]:
         """Return the `Messages` from invoking this prompt."""
         return promote_to_messages(await self.fn(*args, **kwargs))
@@ -237,7 +255,6 @@ class AsyncPrompt(BasePrompt[AsyncMessageTemplate[P]], Generic[P, FormattableT])
         )
 
 
-@dataclass
 class ContextPrompt(
     BasePrompt[ContextMessageTemplate[P, DepsT]], Generic[P, DepsT, FormattableT]
 ):
@@ -257,6 +274,17 @@ class ContextPrompt(
     format: FormatSpec[FormattableT] | None
     """The response format for the generated response."""
 
+    def __init__(
+        self,
+        *,
+        fn: ContextMessageTemplate[P, DepsT],
+        toolkit: ContextToolkit[DepsT],
+        format: FormatSpec[FormattableT] | None,
+    ) -> None:
+        self.toolkit = toolkit
+        self.format = format
+        super().__init__(fn=fn)
+
     def messages(
         self, ctx: Context[DepsT], *args: P.args, **kwargs: P.kwargs
     ) -> Sequence[Message]:
@@ -360,7 +388,6 @@ class ContextPrompt(
         )
 
 
-@dataclass
 class AsyncContextPrompt(
     BasePrompt[AsyncContextMessageTemplate[P, DepsT]], Generic[P, DepsT, FormattableT]
 ):
@@ -380,6 +407,17 @@ class AsyncContextPrompt(
     format: FormatSpec[FormattableT] | None
     """The response format for the generated response."""
 
+    def __init__(
+        self,
+        *,
+        fn: AsyncContextMessageTemplate[P, DepsT],
+        toolkit: AsyncContextToolkit[DepsT],
+        format: FormatSpec[FormattableT] | None,
+    ) -> None:
+        self.toolkit = toolkit
+        self.format = format
+        super().__init__(fn=fn)
+
     async def messages(
         self, ctx: Context[DepsT], *args: P.args, **kwargs: P.kwargs
     ) -> Sequence[Message]:

mirascope/llm/providers/__init__.py

@@ -10,6 +10,7 @@ stub_module_if_missing("mirascope.llm.providers.anthropic", "anthropic")
 stub_module_if_missing("mirascope.llm.providers.google", "google")
 stub_module_if_missing("mirascope.llm.providers.mlx", "mlx")
 stub_module_if_missing("mirascope.llm.providers.openai", "openai")
+stub_module_if_missing("mirascope.llm.providers.openrouter", "openai")
 stub_module_if_missing("mirascope.llm.providers.together", "openai")
 stub_module_if_missing("mirascope.llm.providers.ollama", "openai")
 
@@ -30,6 +31,7 @@ from .openai import (
     OpenAIProvider,
 )
 from .openai.completions import BaseOpenAICompletionsProvider
+from .openrouter import OpenRouterProvider
 from .provider_id import KNOWN_PROVIDER_IDS, ProviderId
 from .provider_registry import (
     get_provider_for_model,
@@ -53,6 +55,7 @@ __all__ = [
     "OllamaProvider",
     "OpenAIModelId",
     "OpenAIProvider",
+    "OpenRouterProvider",
     "Provider",
     "ProviderId",
     "TogetherProvider",

mirascope/llm/providers/openai/completions/_utils/__init__.py

@@ -5,11 +5,14 @@ from .decode import (
     model_name,
 )
 from .encode import encode_request
+from .feature_info import CompletionsModelFeatureInfo, feature_info_for_openai_model
 
 __all__ = [
+    "CompletionsModelFeatureInfo",
     "decode_async_stream",
     "decode_response",
     "decode_stream",
     "encode_request",
+    "feature_info_for_openai_model",
     "model_name",
 ]

mirascope/llm/providers/openai/completions/_utils/encode.py

@@ -22,12 +22,7 @@ from .....tools import (
 )
 from ....base import _utils as _base_utils
 from ...model_id import OpenAIModelId, model_name
-from ...model_info import (
-    MODELS_WITHOUT_AUDIO_SUPPORT,
-    MODELS_WITHOUT_JSON_OBJECT_SUPPORT,
-    MODELS_WITHOUT_JSON_SCHEMA_SUPPORT,
-    NON_REASONING_MODELS,
-)
+from .feature_info import CompletionsModelFeatureInfo
 
 if TYPE_CHECKING:
     from .....models import Params
@@ -58,6 +53,8 @@ class ChatCompletionCreateKwargs(TypedDict, total=False):
 def _encode_user_message(
     message: UserMessage,
     model_id: OpenAIModelId,
+    feature_info: CompletionsModelFeatureInfo,
+    provider_id: str,
 ) -> list[openai_types.ChatCompletionMessageParam]:
     """Convert Mirascope `UserMessage` to a list of OpenAI `ChatCompletionMessageParam`.
 
@@ -106,11 +103,10 @@ def _encode_user_message(
             )
             current_content.append(content)
         elif part.type == "audio":
-            base_model_name = model_name(model_id, None)
-            if base_model_name in MODELS_WITHOUT_AUDIO_SUPPORT:
+            if feature_info.audio_support is False:
                 raise FeatureNotSupportedError(
                     feature="Audio inputs",
-                    provider_id="openai",
+                    provider_id=provider_id,
                     message=f"Model '{model_id}' does not support audio inputs.",
                 )
 
@@ -208,18 +204,13 @@ def _encode_assistant_message(
 
 
 def _encode_message(
-    message: Message, model_id: OpenAIModelId, encode_thoughts_as_text: bool
+    message: Message,
+    model_id: OpenAIModelId,
+    encode_thoughts_as_text: bool,
+    feature_info: CompletionsModelFeatureInfo,
+    provider_id: str,
 ) -> list[openai_types.ChatCompletionMessageParam]:
-    """Convert a Mirascope `Message` to OpenAI `ChatCompletionMessageParam` format.
-
-    Args:
-        message: A Mirascope message (system, user, or assistant)
-        model_id: The model ID being used
-        encode_thoughts: Whether to encode thoughts as text
-
-    Returns:
-        A list of OpenAI `ChatCompletionMessageParam` (may be multiple for tool outputs)
-    """
+    """Convert a Mirascope `Message` to OpenAI `ChatCompletionMessageParam` format."""
     if message.role == "system":
         return [
             openai_types.ChatCompletionSystemMessageParam(
@@ -227,7 +218,7 @@ def _encode_message(
             )
         ]
     elif message.role == "user":
-        return _encode_user_message(message, model_id)
+        return _encode_user_message(message, model_id, feature_info, provider_id)
     elif message.role == "assistant":
         return [_encode_assistant_message(message, model_id, encode_thoughts_as_text)]
     else:
@@ -302,6 +293,8 @@ def encode_request(
     tools: BaseToolkit[AnyToolSchema],
     format: FormatSpec[FormattableT] | None,
     params: Params,
+    feature_info: CompletionsModelFeatureInfo,
+    provider_id: str,
 ) -> tuple[Sequence[Message], Format[FormattableT] | None, ChatCompletionCreateKwargs]:
     """Prepares a request for the `OpenAI.chat.completions.create` method."""
     if model_id.endswith(":responses"):
@@ -313,7 +306,11 @@ def encode_request(
         )
     base_model_name = model_name(model_id, None)
 
-    is_reasoning_model = base_model_name not in NON_REASONING_MODELS
+    is_reasoning_model = feature_info.is_reasoning_model is True
+    strict_supported = feature_info.strict_support is True
+    strict_allowed = feature_info.strict_support is not False
+    supports_json_object = feature_info.json_object_support is True
+
     kwargs: ChatCompletionCreateKwargs = ChatCompletionCreateKwargs(
         {"model": base_model_name}
     )
@@ -321,7 +318,7 @@ def encode_request(
 
     with _base_utils.ensure_all_params_accessed(
         params=params,
-        provider_id="openai",
+        provider_id=provider_id,
         unsupported_params=[
             "top_k",
             *(["temperature", "top_p", "stop_sequences"] if is_reasoning_model else []),
@@ -348,15 +345,14 @@ def encode_request(
 
     openai_tools = [_convert_tool_to_tool_param(tool) for tool in tools.tools]
 
-    model_supports_strict = base_model_name not in MODELS_WITHOUT_JSON_SCHEMA_SUPPORT
-    default_mode = "strict" if model_supports_strict else "tool"
+    default_mode = "strict" if strict_supported else "tool"
     format = resolve_format(format, default_mode=default_mode)
     if format is not None:
         if format.mode == "strict":
-            if not model_supports_strict:
+            if not strict_allowed:
                 raise FeatureNotSupportedError(
                     feature="formatting_mode:strict",
-                    provider_id="openai",
+                    provider_id=provider_id,
                     model_id=model_id,
                 )
             kwargs["response_format"] = _create_strict_response_format(format)
@@ -371,10 +367,7 @@ def encode_request(
                 kwargs["parallel_tool_calls"] = False
             format_tool_schema = format.create_tool_schema()
             openai_tools.append(_convert_tool_to_tool_param(format_tool_schema))
-        elif (
-            format.mode == "json"
-            and base_model_name not in MODELS_WITHOUT_JSON_OBJECT_SUPPORT
-        ):
+        elif format.mode == "json" and supports_json_object:
             kwargs["response_format"] = {"type": "json_object"}
 
         if format.formatting_instructions:
@@ -388,7 +381,9 @@ def encode_request(
     encoded_messages: list[openai_types.ChatCompletionMessageParam] = []
     for message in messages:
         encoded_messages.extend(
-            _encode_message(message, model_id, encode_thoughts_as_text)
+            _encode_message(
+                message, model_id, encode_thoughts_as_text, feature_info, provider_id
+            )
         )
     kwargs["messages"] = encoded_messages
 

mirascope/llm/providers/openai/completions/_utils/feature_info.py

@@ -0,0 +1,50 @@
+"""Model feature information for OpenAI completions encoding."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ...model_info import (
+    MODELS_WITHOUT_AUDIO_SUPPORT,
+    MODELS_WITHOUT_JSON_OBJECT_SUPPORT,
+    MODELS_WITHOUT_JSON_SCHEMA_SUPPORT,
+    NON_REASONING_MODELS,
+)
+
+
+@dataclass(frozen=True)
+class CompletionsModelFeatureInfo:
+    """Model feature information for OpenAI completions encoding.
+
+    This dataclass encapsulates feature detection for OpenAI-compatible models,
+    allowing providers to pass pre-computed feature information rather than
+    relying on model name matching in encode_request.
+
+    None values mean "unknown":
+        - audio_support: None → allow audio (permissive)
+        - strict_support: None → default to tool mode, but allow explicit strict
+        - json_object_support: None → disable (use prompt instructions instead)
+        - is_reasoning_model: None → treat as False (allow temperature)
+    """
+
+    audio_support: bool | None = None
+    """Whether the model supports audio inputs. None means skip check (allow)."""
+
+    strict_support: bool | None = None
+    """Whether the model supports strict JSON schema. None allows explicit strict."""
+
+    json_object_support: bool | None = None
+    """Whether the model supports JSON object response format. None disables."""
+
+    is_reasoning_model: bool | None = None
+    """Whether the model is a reasoning model. None means False (allow temperature)."""
+
+
+def feature_info_for_openai_model(model_name: str) -> CompletionsModelFeatureInfo:
+    """Get feature info for a base OpenAI model name."""
+    return CompletionsModelFeatureInfo(
+        audio_support=model_name not in MODELS_WITHOUT_AUDIO_SUPPORT,
+        strict_support=model_name not in MODELS_WITHOUT_JSON_SCHEMA_SUPPORT,
+        json_object_support=model_name not in MODELS_WITHOUT_JSON_OBJECT_SUPPORT,
+        is_reasoning_model=model_name not in NON_REASONING_MODELS,
+    )

mirascope/llm/providers/openai/completions/base_provider.py

@@ -27,6 +27,7 @@ from ...base import BaseProvider
 from .. import _utils as _shared_utils
 from ..model_id import model_name as openai_model_name
 from . import _utils
+from ._utils import CompletionsModelFeatureInfo
 
 if TYPE_CHECKING:
     from ....models import Params
@@ -83,6 +84,10 @@ class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
         """Extract the model name to send to the API."""
         return openai_model_name(model_id, None)
 
+    def _model_feature_info(self, model_id: str) -> CompletionsModelFeatureInfo:
+        """Get feature info for the model. Override for provider-specific features."""
+        return CompletionsModelFeatureInfo()
+
     def _provider_model_name(self, model_id: str) -> str:
         """Get the model name for tracking in Response."""
         return self._model_name(model_id)
@@ -114,6 +119,8 @@ class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
             tools=toolkit,
             format=format,
             params=params,
+            feature_info=self._model_feature_info(model_id),
+            provider_id=self.id,
         )
         kwargs["model"] = self._model_name(model_id)
         openai_response = self.client.chat.completions.create(**kwargs)
@@ -168,6 +175,8 @@ class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
             tools=toolkit,
             format=format,
             params=params,
+            feature_info=self._model_feature_info(model_id),
+            provider_id=self.id,
         )
         kwargs["model"] = self._model_name(model_id)
         openai_response = self.client.chat.completions.create(**kwargs)
@@ -220,6 +229,8 @@ class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
             messages=messages,
             tools=toolkit,
             format=format,
+            feature_info=self._model_feature_info(model_id),
+            provider_id=self.id,
         )
         kwargs["model"] = self._model_name(model_id)
         openai_response = await self.async_client.chat.completions.create(**kwargs)
@@ -274,6 +285,8 @@ class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
             messages=messages,
             tools=toolkit,
             format=format,
+            feature_info=self._model_feature_info(model_id),
+            provider_id=self.id,
         )
         kwargs["model"] = self._model_name(model_id)
         openai_response = await self.async_client.chat.completions.create(**kwargs)
@@ -326,6 +339,8 @@ class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
             tools=toolkit,
             format=format,
             params=params,
+            feature_info=self._model_feature_info(model_id),
+            provider_id=self.id,
         )
         kwargs["model"] = self._model_name(model_id)
         openai_stream = self.client.chat.completions.create(
@@ -376,6 +391,8 @@ class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
             tools=toolkit,
             format=format,
             params=params,
+            feature_info=self._model_feature_info(model_id),
+            provider_id=self.id,
         )
         kwargs["model"] = self._model_name(model_id)
 
@@ -425,6 +442,8 @@ class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
             tools=toolkit,
             format=format,
             params=params,
+            feature_info=self._model_feature_info(model_id),
+            provider_id=self.id,
         )
         kwargs["model"] = self._model_name(model_id)
         openai_stream = await self.async_client.chat.completions.create(
@@ -478,6 +497,8 @@ class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
             tools=toolkit,
             format=format,
             params=params,
+            feature_info=self._model_feature_info(model_id),
+            provider_id=self.id,
         )
         kwargs["model"] = self._model_name(model_id)
 

mirascope/llm/providers/openai/completions/provider.py

@@ -1,6 +1,7 @@
 """OpenAI Completions API provider implementation."""
 
-from ..model_id import model_name
+from ..model_id import model_name as openai_model_name
+from ._utils import CompletionsModelFeatureInfo, feature_info_for_openai_model
 from .base_provider import BaseOpenAICompletionsProvider
 
 
@@ -14,9 +15,14 @@ class OpenAICompletionsProvider(BaseOpenAICompletionsProvider):
     api_key_required = False
     provider_name = "OpenAI"
 
+    def _model_feature_info(self, model_id: str) -> CompletionsModelFeatureInfo:
+        """Get feature info for actual OpenAI models."""
+        base_name = openai_model_name(model_id, None)
+        return feature_info_for_openai_model(base_name)
+
     def _provider_model_name(self, model_id: str) -> str:
         """Get the model name for tracking in Response.
 
         Returns the model name with :completions suffix for tracking which API was used.
         """
-        return model_name(model_id, "completions")
+        return openai_model_name(model_id, "completions")

mirascope/llm/providers/openrouter/__init__.py

@@ -0,0 +1,5 @@
+"""OpenRouter provider for accessing multiple LLM providers via OpenRouter's API."""
+
+from .provider import OpenRouterProvider
+
+__all__ = ["OpenRouterProvider"]

mirascope/llm/providers/openrouter/provider.py

@@ -0,0 +1,67 @@
+"""OpenRouter provider implementation."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from ..openai.completions._utils import (
+    CompletionsModelFeatureInfo,
+    feature_info_for_openai_model,
+)
+from ..openai.completions.base_provider import BaseOpenAICompletionsProvider
+from ..openai.model_id import model_name as openai_model_name
+
+
+class OpenRouterProvider(BaseOpenAICompletionsProvider):
+    """Provider for OpenRouter's OpenAI-compatible API.
+
+    Inherits from BaseOpenAICompletionsProvider with OpenRouter-specific configuration:
+    - Uses OpenRouter's API endpoint
+    - Requires OPENROUTER_API_KEY
+
+    Usage:
+        Option 1: Use "openrouter/" prefix for explicit OpenRouter models:
+
+        ```python
+        from mirascope import llm
+
+        llm.register_provider("openrouter", scope="openrouter/")
+
+        @llm.call("openrouter/openai/gpt-4o")
+        def my_prompt():
+            return [llm.messages.user("Hello!")]
+        ```
+
+        Option 2: Route existing model IDs through OpenRouter:
+
+        ```python
+        from mirascope import llm
+
+        # Register for openai and anthropic models via OpenRouter
+        llm.register_provider("openrouter", scope=["openai/", "anthropic/"])
+
+        # Now openai/ models go through OpenRouter
+        @llm.call("openai/gpt-4")
+        def my_prompt():
+            return [llm.messages.user("Hello!")]
+        ```
+    """
+
+    id: ClassVar[str] = "openrouter"
+    default_scope: ClassVar[str | list[str]] = []
+    default_base_url: ClassVar[str | None] = "https://openrouter.ai/api/v1"
+    api_key_env_var: ClassVar[str] = "OPENROUTER_API_KEY"
+    api_key_required: ClassVar[bool] = True
+    provider_name: ClassVar[str | None] = "OpenRouter"
+
+    def _model_name(self, model_id: str) -> str:
+        """Strip 'openrouter/' prefix from model ID for OpenRouter API."""
+        return model_id.removeprefix("openrouter/")
+
+    def _model_feature_info(self, model_id: str) -> CompletionsModelFeatureInfo:
+        """Return OpenAI feature info for openai/* models, empty info otherwise."""
+        base_model_id = model_id.removeprefix("openrouter/")
+        if base_model_id.startswith("openai/"):
+            openai_name = openai_model_name(base_model_id, None)
+            return feature_info_for_openai_model(openai_name)
+        return CompletionsModelFeatureInfo()

mirascope/llm/providers/provider_id.py

@@ -10,6 +10,7 @@ KnownProviderId: TypeAlias = Literal[
     "mlx",  # Local inference powered by `mlx-lm`, via MLXProvider
     "ollama",  # Ollama provider via OllamaProvider
     "openai",  # OpenAI provider via OpenAIProvider (prefers Responses routing when available)
+    "openrouter",  # OpenRouter provider via OpenRouterProvider
     "together",  # Together AI provider via TogetherProvider
 ]
 KNOWN_PROVIDER_IDS = get_args(KnownProviderId)
@@ -20,5 +21,6 @@ OpenAICompletionsCompatibleProviderId: TypeAlias = Literal[
     "ollama",  # Ollama (OpenAI-compatible)
     "openai",  # OpenAI via OpenAIProvider (routes to completions)
     "openai:completions",  # OpenAI Completions API directly
+    "openrouter",  # OpenRouter (OpenAI-compatible)
     "together",  # Together AI (OpenAI-compatible)
 ]

mirascope/llm/providers/provider_registry.py

@@ -16,6 +16,7 @@ from .ollama import OllamaProvider
 from .openai import OpenAIProvider
 from .openai.completions.provider import OpenAICompletionsProvider
 from .openai.responses.provider import OpenAIResponsesProvider
+from .openrouter import OpenRouterProvider
 from .provider_id import ProviderId
 from .together import TogetherProvider
 
@@ -71,6 +72,9 @@ DEFAULT_AUTO_REGISTER_SCOPES: dict[str, Sequence[ProviderDefault]] = {
     "mlx-community/": [
         ProviderDefault("mlx", None),  # No API key required
     ],
+    "openrouter/": [
+        ProviderDefault("openrouter", "OPENROUTER_API_KEY"),
+    ],
 }
 
 
@@ -122,6 +126,8 @@ def provider_singleton(
             return OpenAICompletionsProvider(api_key=api_key, base_url=base_url)
         case "openai:responses":
             return OpenAIResponsesProvider(api_key=api_key, base_url=base_url)
+        case "openrouter":
+            return OpenRouterProvider(api_key=api_key, base_url=base_url)
         case "together":
             return TogetherProvider(api_key=api_key, base_url=base_url)
         case _:  # pragma: no cover