mirascope 2.0.0a1__py3-none-any.whl → 2.0.0a3__py3-none-any.whl

mirascope/llm/providers/provider_registry.py

@@ -0,0 +1,167 @@
+"""Provider registry for managing provider instances and scopes."""
+
+from typing import overload
+
+from ..exceptions import NoRegisteredProviderError
+from .base import Provider
+from .load_provider import load_provider
+from .provider_id import ProviderId
+
+# Global registry mapping scopes to providers
+# Scopes are matched by prefix (longest match wins)
+PROVIDER_REGISTRY: dict[str, Provider] = {}
+
+# Default auto-registration mapping for built-in providers
+# These providers will be automatically registered on first use
+DEFAULT_AUTO_REGISTER_SCOPES: dict[str, ProviderId] = {
+    "anthropic/": "anthropic",
+    "google/": "google",
+    "openai/": "openai",
+    "mlx-community/": "mlx",
+}
+
+
+@overload
+def register_provider(
+    provider: Provider,
+    scope: str | list[str] | None = None,
+) -> Provider:
+    """Register a provider instance with scope(s).
+
+    Args:
+        provider: Provider instance to register.
+        scope: Scope string or list of scopes (e.g., "anthropic/", ["anthropic/", "openai/"]).
+            If None, uses the provider's default_scope.
+    """
+    ...
+
+
+@overload
+def register_provider(
+    provider: ProviderId,
+    scope: str | list[str] | None = None,
+    *,
+    api_key: str | None = None,
+    base_url: str | None = None,
+) -> Provider:
+    """Register a provider by ID with scope(s).
+
+    Args:
+        provider: Provider ID string (e.g., "anthropic", "openai").
+        scope: Scope string or list of scopes (e.g., "anthropic/", ["anthropic/", "openai/"]).
+            If None, uses the provider's default_scope.
+        api_key: API key for authentication.
+        base_url: Base URL for the API.
+    """
+    ...
+
+
+def register_provider(
+    provider: ProviderId | Provider,
+    scope: str | list[str] | None = None,
+    *,
+    api_key: str | None = None,
+    base_url: str | None = None,
+) -> Provider:
+    """Register a provider with scope(s) in the global registry.
+
+    Scopes use prefix matching on model IDs:
+    - "anthropic/" matches "anthropic/*"
+    - "anthropic/claude-4-5" matches "anthropic/claude-4-5*"
+    - "anthropic/claude-4-5-sonnet" matches exactly "anthropic/claude-4-5-sonnet"
+
+    When multiple scopes match a model_id, the longest match wins.
+
+    Args:
+        provider: Either a provider ID string or a provider instance.
+        scope: Scope string or list of scopes for prefix matching on model IDs.
+            If None, uses the provider's default_scope attribute.
+            Can be a single string or a list of strings.
+        api_key: API key for authentication (only used if provider is a string).
+        base_url: Base URL for the API (only used if provider is a string).
+
+    Example:
+        ```python
+        # Register with default scope
+        llm.register_provider("anthropic", api_key="key")
+
+        # Register for specific models
+        llm.register_provider("openai", scope="openai/gpt-4")
+
+        # Register for multiple scopes
+        llm.register_provider("aws-bedrock", scope=["anthropic/", "openai/"])
+
+        # Register a custom instance
+        custom = llm.providers.AnthropicProvider(api_key="team-key")
+        llm.register_provider(custom, scope="anthropic/claude-4-5-sonnet")
+        ```
+    """
+
+    if isinstance(provider, str):
+        provider = load_provider(provider, api_key=api_key, base_url=base_url)
+
+    if scope is None:
+        scope = provider.default_scope
+
+    scopes = [scope] if isinstance(scope, str) else scope
+    for s in scopes:
+        PROVIDER_REGISTRY[s] = provider
+
+    return provider
+
+
+def get_provider_for_model(model_id: str) -> Provider:
+    """Get the provider for a model_id based on the registry.
+
+    Uses longest prefix matching to find the most specific provider for the model.
+    If no explicit registration is found, checks for auto-registration defaults
+    and automatically registers the provider on first use.
+
+    Args:
+        model_id: The full model ID (e.g., "anthropic/claude-4-5-sonnet").
+
+    Returns:
+        The provider instance registered for this model.
+
+    Raises:
+        ValueError: If no provider is registered or available for this model.
+
+    Example:
+        ```python
+        # Assuming providers are registered:
+        # - "anthropic/" -> AnthropicProvider()
+        # - "anthropic/claude-4-5-sonnet" -> CustomProvider()
+
+        provider = get_provider_for_model("anthropic/claude-4-5-sonnet")
+        # Returns CustomProvider (longest match)
+
+        provider = get_provider_for_model("anthropic/claude-3-opus")
+        # Returns AnthropicProvider (matches "anthropic/" prefix)
+
+        # Auto-registration on first use:
+        provider = get_provider_for_model("openai/gpt-4")
+        # Automatically loads and registers OpenAIProvider() for "openai/"
+        ```
+    """
+    # Try explicit registry first (longest match wins)
+    matching_scopes = [
+        scope for scope in PROVIDER_REGISTRY if model_id.startswith(scope)
+    ]
+    if matching_scopes:
+        best_scope = max(matching_scopes, key=len)
+        return PROVIDER_REGISTRY[best_scope]
+
+    # Fall back to auto-registration
+    matching_defaults = [
+        scope for scope in DEFAULT_AUTO_REGISTER_SCOPES if model_id.startswith(scope)
+    ]
+    if matching_defaults:
+        best_scope = max(matching_defaults, key=len)
+        provider_id = DEFAULT_AUTO_REGISTER_SCOPES[best_scope]
+        provider = load_provider(provider_id)
+        # Auto-register for future calls
+        PROVIDER_REGISTRY[best_scope] = provider
+        return provider
+
+    # No provider found
+    raise NoRegisteredProviderError(model_id)

mirascope/llm/responses/base_response.py

@@ -11,7 +11,7 @@ from .finish_reason import FinishReason
 from .root_response import RootResponse
 
 if TYPE_CHECKING:
-    from ..clients import ModelId, Params, Provider
+    from ..providers import ModelId, Params, ProviderId
 
 
 class BaseResponse(RootResponse[ToolkitT, FormattableT]):
@@ -21,8 +21,9 @@ class BaseResponse(RootResponse[ToolkitT, FormattableT]):
         self,
         *,
         raw: Any,  # noqa: ANN401
-        provider: "Provider",
+        provider_id: "ProviderId",
         model_id: "ModelId",
+        provider_model_name: str,
         params: "Params",
         toolkit: ToolkitT,
         format: Format[FormattableT] | None = None,
@@ -34,8 +35,10 @@ class BaseResponse(RootResponse[ToolkitT, FormattableT]):
 
         Args:
             raw: The raw response from the LLM.
-            provider: The provider name (e.g. "anthropic", "openai:completions").
+            provider: The provider name (e.g. "anthropic", "openai").
             model_id: The model identifier that generated the response.
+            provider_model_name: Optional provider-specific model name. May include
+                provider-specific additional info (like api mode in "gpt-5:responses").
             params: The params used to generate the response (or None).
             toolkit: Toolkit containing all the tools used to generate the response.
             format: The `Format` for the expected structured output format (or None).
@@ -44,8 +47,9 @@ class BaseResponse(RootResponse[ToolkitT, FormattableT]):
             finish_reason: The reason why the LLM finished generating a response.
         """
         self.raw = raw
-        self.provider = provider
+        self.provider_id = provider_id
         self.model_id = model_id
+        self.provider_model_name = provider_model_name
         self.params = params
         self.toolkit = toolkit
         self.finish_reason = finish_reason
@@ -84,8 +88,9 @@ class BaseResponse(RootResponse[ToolkitT, FormattableT]):
             assistant_message = AssistantMessage(
                 content=self.content,
                 name=assistant_message.name,
-                provider=assistant_message.provider,
+                provider_id=assistant_message.provider_id,
                 model_id=assistant_message.model_id,
+                provider_model_name=assistant_message.provider_model_name,
                 raw_message=assistant_message.raw_message,
             )
         self.messages = list(input_messages) + [assistant_message]

mirascope/llm/responses/base_stream_response.py

@@ -38,7 +38,7 @@ from .streams import (
 )
 
 if TYPE_CHECKING:
-    from ..clients import ModelId, Params, Provider
+    from ..providers import ModelId, Params, ProviderId
 
 
 @dataclass(kw_only=True)
@@ -157,8 +157,9 @@ class BaseStreamResponse(
     def __init__(
         self,
         *,
-        provider: "Provider",
+        provider_id: "ProviderId",
         model_id: "ModelId",
+        provider_model_name: str,
         params: "Params",
         toolkit: ToolkitT,
         format: Format[FormattableT] | None = None,
@@ -168,8 +169,10 @@ class BaseStreamResponse(
         """Initialize the BaseStreamResponse.
 
         Args:
-            provider: The provider name (e.g. "anthropic", "openai:completions").
+            provider: The provider name (e.g. "anthropic", "openai").
             model_id: The model identifier that generated the response.
+            provider_model_name: Optional provider-specific model name. May include
+                provider-specific additional info (like api mode in "gpt-5:responses").
             params: The params used to generate the response (or None).
             toolkit: Toolkit containing all the tools used to generate the response.
             format: The `Format` for the expected structured output format (or None).
@@ -179,8 +182,9 @@ class BaseStreamResponse(
         as the stream is consumed.
         """
 
-        self.provider = provider
+        self.provider_id = provider_id
         self.model_id = model_id
+        self.provider_model_name = provider_model_name
         self.params = params
         self.toolkit = toolkit
         self.format = format
@@ -206,8 +210,9 @@ class BaseStreamResponse(
 
         self._assistant_message = AssistantMessage(
             content=self._content,
-            provider=provider,
+            provider_id=provider_id,
             model_id=model_id,
+            provider_model_name=provider_model_name,
             raw_message=None,
         )
 

mirascope/llm/responses/response.py

@@ -18,11 +18,12 @@ from ..tools import (
     Tool,
     Toolkit,
 )
+from ..types import Jsonable
 from .base_response import BaseResponse
 from .finish_reason import FinishReason
 
 if TYPE_CHECKING:
-    from ..clients import ModelId, Params, Provider
+    from ..providers import ModelId, Params, ProviderId
 
 
 class Response(BaseResponse[Toolkit, FormattableT]):
@@ -32,8 +33,9 @@ class Response(BaseResponse[Toolkit, FormattableT]):
         self,
         *,
         raw: Any,  # noqa: ANN401
-        provider: "Provider",
+        provider_id: "ProviderId",
         model_id: "ModelId",
+        provider_model_name: str,
         params: "Params",
         tools: Sequence[Tool] | Toolkit | None = None,
         format: Format[FormattableT] | None = None,
@@ -45,8 +47,9 @@ class Response(BaseResponse[Toolkit, FormattableT]):
         toolkit = tools if isinstance(tools, Toolkit) else Toolkit(tools=tools)
         super().__init__(
             raw=raw,
-            provider=provider,
+            provider_id=provider_id,
             model_id=model_id,
+            provider_model_name=provider_model_name,
             params=params,
             toolkit=toolkit,
             format=format,
@@ -55,7 +58,7 @@ class Response(BaseResponse[Toolkit, FormattableT]):
             finish_reason=finish_reason,
         )
 
-    def execute_tools(self) -> Sequence[ToolOutput]:
+    def execute_tools(self) -> Sequence[ToolOutput[Jsonable]]:
         """Execute and return all of the tool calls in the response.
 
         Returns:
@@ -101,8 +104,9 @@ class AsyncResponse(BaseResponse[AsyncToolkit, FormattableT]):
         self,
         *,
         raw: Any,  # noqa: ANN401
-        provider: "Provider",
+        provider_id: "ProviderId",
         model_id: "ModelId",
+        provider_model_name: str,
         params: "Params",
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
         format: Format[FormattableT] | None = None,
@@ -116,8 +120,9 @@ class AsyncResponse(BaseResponse[AsyncToolkit, FormattableT]):
         )
         super().__init__(
             raw=raw,
-            provider=provider,
+            provider_id=provider_id,
             model_id=model_id,
+            provider_model_name=provider_model_name,
             params=params,
             toolkit=toolkit,
             format=format,
@@ -126,7 +131,7 @@ class AsyncResponse(BaseResponse[AsyncToolkit, FormattableT]):
             finish_reason=finish_reason,
         )
 
-    async def execute_tools(self) -> Sequence[ToolOutput]:
+    async def execute_tools(self) -> Sequence[ToolOutput[Jsonable]]:
         """Execute and return all of the tool calls in the response.
 
         Returns:
@@ -179,8 +184,9 @@ class ContextResponse(
         self,
         *,
         raw: Any,  # noqa: ANN401
-        provider: "Provider",
+        provider_id: "ProviderId",
         model_id: "ModelId",
+        provider_model_name: str,
         params: "Params",
         tools: Sequence[Tool | ContextTool[DepsT]]
         | ContextToolkit[DepsT]
@@ -196,8 +202,9 @@ class ContextResponse(
         )
         super().__init__(
             raw=raw,
-            provider=provider,
+            provider_id=provider_id,
             model_id=model_id,
+            provider_model_name=provider_model_name,
             params=params,
             toolkit=toolkit,
             format=format,
@@ -206,7 +213,7 @@ class ContextResponse(
             finish_reason=finish_reason,
         )
 
-    def execute_tools(self, ctx: Context[DepsT]) -> Sequence[ToolOutput]:
+    def execute_tools(self, ctx: Context[DepsT]) -> Sequence[ToolOutput[Jsonable]]:
         """Execute and return all of the tool calls in the response.
 
         Args:
@@ -265,8 +272,9 @@ class AsyncContextResponse(
         self,
         *,
         raw: Any,  # noqa: ANN401
-        provider: "Provider",
+        provider_id: "ProviderId",
         model_id: "ModelId",
+        provider_model_name: str,
         params: "Params",
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
@@ -284,8 +292,9 @@ class AsyncContextResponse(
         )
         super().__init__(
             raw=raw,
-            provider=provider,
+            provider_id=provider_id,
             model_id=model_id,
+            provider_model_name=provider_model_name,
             params=params,
             toolkit=toolkit,
             format=format,
@@ -294,7 +303,9 @@ class AsyncContextResponse(
             finish_reason=finish_reason,
         )
 
-    async def execute_tools(self, ctx: Context[DepsT]) -> Sequence[ToolOutput]:
+    async def execute_tools(
+        self, ctx: Context[DepsT]
+    ) -> Sequence[ToolOutput[Jsonable]]:
         """Execute and return all of the tool calls in the response.
 
         Args:

mirascope/llm/responses/root_response.py

@@ -13,8 +13,8 @@ from . import _utils
 from .finish_reason import FinishReason
 
 if TYPE_CHECKING:
-    from ..clients import ModelId, Params, Provider
     from ..models import Model
+    from ..providers import ModelId, Params, ProviderId
 
 
 class RootResponse(Generic[ToolkitT, FormattableT], ABC):
@@ -23,7 +23,7 @@ class RootResponse(Generic[ToolkitT, FormattableT], ABC):
     raw: Any
     """The raw response from the LLM."""
 
-    provider: "Provider"
+    provider_id: "ProviderId"
     """The provider that generated this response."""
 
     model_id: "ModelId"
@@ -116,7 +116,9 @@ class RootResponse(Generic[ToolkitT, FormattableT], ABC):
             return None
 
         formattable = self.format.formattable
-        if formattable is None or formattable is NoneType:
+        if formattable is None or formattable is NoneType:  # pyright: ignore[reportUnnecessaryComparison]
+            # note: pyright claims the None comparison is unnecessary, but removing it
+            # introduces type errors.
             return None  # pragma: no cover
 
         if partial:
@@ -165,13 +167,6 @@ class RootResponse(Generic[ToolkitT, FormattableT], ABC):
     @property
     def model(self) -> "Model":
         """A `Model` with parameters matching this response."""
-        from ..models import Model, get_model_from_context
+        from ..models import use_model  # Dynamic import to avoid circular dependency
 
-        if context_model := get_model_from_context():
-            return context_model
-
-        return Model(
-            provider=self.provider,
-            model_id=self.model_id,
-            **self.params,
-        )
+        return use_model(self.model_id, **self.params)

mirascope/llm/responses/stream_response.py

@@ -18,6 +18,7 @@ from ..tools import (
     Tool,
     Toolkit,
 )
+from ..types import Jsonable
 from .base_stream_response import (
     AsyncChunkIterator,
     BaseAsyncStreamResponse,
@@ -26,7 +27,7 @@ from .base_stream_response import (
 )
 
 if TYPE_CHECKING:
-    from ..clients import ModelId, Params, Provider
+    from ..providers import ModelId, Params, ProviderId
 
 
 class StreamResponse(BaseSyncStreamResponse[Toolkit, FormattableT]):
@@ -76,8 +77,8 @@ class StreamResponse(BaseSyncStreamResponse[Toolkit, FormattableT]):
         from mirascope import llm
 
         @llm.call(
-            provider="openai:completions",
-            model_id="gpt-4o-mini",
+            provider_id="openai",
+            model_id="openai/gpt-5-mini",
         )
         def answer_question(question: str) -> str:
             return f"Answer this question: {question}"
@@ -93,8 +94,9 @@ class StreamResponse(BaseSyncStreamResponse[Toolkit, FormattableT]):
     def __init__(
         self,
         *,
-        provider: "Provider",
+        provider_id: "ProviderId",
         model_id: "ModelId",
+        provider_model_name: str,
         params: "Params",
         tools: Sequence[Tool] | Toolkit | None = None,
         format: Format[FormattableT] | None = None,
@@ -104,8 +106,9 @@ class StreamResponse(BaseSyncStreamResponse[Toolkit, FormattableT]):
         """Initialize a `StreamResponse`."""
         toolkit = tools if isinstance(tools, Toolkit) else Toolkit(tools=tools)
         super().__init__(
-            provider=provider,
+            provider_id=provider_id,
             model_id=model_id,
+            provider_model_name=provider_model_name,
             params=params,
             toolkit=toolkit,
             format=format,
@@ -113,7 +116,7 @@ class StreamResponse(BaseSyncStreamResponse[Toolkit, FormattableT]):
             chunk_iterator=chunk_iterator,
         )
 
-    def execute_tools(self) -> Sequence[ToolOutput]:
+    def execute_tools(self) -> Sequence[ToolOutput[Jsonable]]:
         """Execute and return all of the tool calls in the response.
 
         Returns:
@@ -201,8 +204,8 @@ class AsyncStreamResponse(BaseAsyncStreamResponse[AsyncToolkit, FormattableT]):
         from mirascope import llm
 
         @llm.call(
-            provider="openai:completions",
-            model_id="gpt-4o-mini",
+            provider_id="openai",
+            model_id="openai/gpt-5-mini",
         )
         async def answer_question(question: str) -> str:
             return f"Answer this question: {question}"
@@ -218,8 +221,9 @@ class AsyncStreamResponse(BaseAsyncStreamResponse[AsyncToolkit, FormattableT]):
     def __init__(
         self,
         *,
-        provider: "Provider",
+        provider_id: "ProviderId",
         model_id: "ModelId",
+        provider_model_name: str,
         params: "Params",
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
         format: Format[FormattableT] | None = None,
@@ -231,8 +235,9 @@ class AsyncStreamResponse(BaseAsyncStreamResponse[AsyncToolkit, FormattableT]):
             tools if isinstance(tools, AsyncToolkit) else AsyncToolkit(tools=tools)
         )
         super().__init__(
-            provider=provider,
+            provider_id=provider_id,
             model_id=model_id,
+            provider_model_name=provider_model_name,
             params=params,
             toolkit=toolkit,
             format=format,
@@ -240,7 +245,7 @@ class AsyncStreamResponse(BaseAsyncStreamResponse[AsyncToolkit, FormattableT]):
             chunk_iterator=chunk_iterator,
         )
 
-    async def execute_tools(self) -> Sequence[ToolOutput]:
+    async def execute_tools(self) -> Sequence[ToolOutput[Jsonable]]:
         """Execute and return all of the tool calls in the response.
 
         Returns:
@@ -285,7 +290,8 @@ class AsyncStreamResponse(BaseAsyncStreamResponse[AsyncToolkit, FormattableT]):
 
 
 class ContextStreamResponse(
-    BaseSyncStreamResponse[ContextToolkit, FormattableT], Generic[DepsT, FormattableT]
+    BaseSyncStreamResponse[ContextToolkit[DepsT], FormattableT],
+    Generic[DepsT, FormattableT],
 ):
     """A `ContextStreamResponse` wraps response content from the LLM with a streaming interface.
 
@@ -333,8 +339,8 @@ class ContextStreamResponse(
         from mirascope import llm
 
         @llm.call(
-            provider="openai:completions",
-            model_id="gpt-4o-mini",
+            provider_id="openai",
+            model_id="openai/gpt-5-mini",
         )
         def answer_question(ctx: llm.Context, question: str) -> str:
             return f"Answer this question: {question}"
@@ -351,8 +357,9 @@ class ContextStreamResponse(
     def __init__(
         self,
         *,
-        provider: "Provider",
+        provider_id: "ProviderId",
         model_id: "ModelId",
+        provider_model_name: str,
         params: "Params",
         tools: Sequence[Tool | ContextTool[DepsT]]
         | ContextToolkit[DepsT]
@@ -366,8 +373,9 @@ class ContextStreamResponse(
             tools if isinstance(tools, ContextToolkit) else ContextToolkit(tools=tools)
         )
         super().__init__(
-            provider=provider,
+            provider_id=provider_id,
             model_id=model_id,
+            provider_model_name=provider_model_name,
             params=params,
             toolkit=toolkit,
             format=format,
@@ -375,7 +383,7 @@ class ContextStreamResponse(
             chunk_iterator=chunk_iterator,
         )
 
-    def execute_tools(self, ctx: Context[DepsT]) -> Sequence[ToolOutput]:
+    def execute_tools(self, ctx: Context[DepsT]) -> Sequence[ToolOutput[Jsonable]]:
         """Execute and return all of the tool calls in the response.
 
         Args:
@@ -426,7 +434,7 @@ class ContextStreamResponse(
 
 
 class AsyncContextStreamResponse(
-    BaseAsyncStreamResponse[AsyncContextToolkit, FormattableT],
+    BaseAsyncStreamResponse[AsyncContextToolkit[DepsT], FormattableT],
     Generic[DepsT, FormattableT],
 ):
     """An `AsyncContextStreamResponse` wraps response content from the LLM with a streaming interface.
@@ -475,8 +483,8 @@ class AsyncContextStreamResponse(
         from mirascope import llm
 
         @llm.call(
-            provider="openai:completions",
-            model_id="gpt-4o-mini",
+            provider_id="openai",
+            model_id="openai/gpt-5-mini",
         )
         async def answer_question(ctx: llm.Context, question: str) -> str:
             return f"Answer this question: {question}"
@@ -493,8 +501,9 @@ class AsyncContextStreamResponse(
     def __init__(
         self,
         *,
-        provider: "Provider",
+        provider_id: "ProviderId",
         model_id: "ModelId",
+        provider_model_name: str,
         params: "Params",
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
@@ -510,8 +519,9 @@ class AsyncContextStreamResponse(
             else AsyncContextToolkit(tools=tools)
         )
         super().__init__(
-            provider=provider,
+            provider_id=provider_id,
             model_id=model_id,
+            provider_model_name=provider_model_name,
             params=params,
             toolkit=toolkit,
             format=format,
@@ -519,7 +529,9 @@ class AsyncContextStreamResponse(
             chunk_iterator=chunk_iterator,
         )
 
-    async def execute_tools(self, ctx: Context[DepsT]) -> Sequence[ToolOutput]:
+    async def execute_tools(
+        self, ctx: Context[DepsT]
+    ) -> Sequence[ToolOutput[Jsonable]]:
         """Execute and return all of the tool calls in the response.
 
         Args: