mirascope 2.0.0a4__py3-none-any.whl → 2.0.0a6__py3-none-any.whl

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

@@ -3,9 +3,10 @@
 from collections.abc import Sequence
 from typing_extensions import Unpack
 
-from openai import AsyncOpenAI, OpenAI
+from openai import AsyncOpenAI, BadRequestError as OpenAIBadRequestError, OpenAI
 
 from ....context import Context, DepsT
+from ....exceptions import BadRequestError, NotFoundError
 from ....formatting import Format, FormattableT
 from ....messages import Message
 from ....responses import (
@@ -29,6 +30,7 @@ from ....tools import (
     Toolkit,
 )
 from ...base import BaseProvider, Params
+from .. import _utils as _shared_utils
 from ..model_id import OpenAIModelId, model_name
 from . import _utils
 
@@ -38,6 +40,12 @@ class OpenAIResponsesProvider(BaseProvider[OpenAI]):
 
     id = "openai:responses"
     default_scope = "openai/"
+    error_map = {
+        **_shared_utils.OPENAI_ERROR_MAP,
+        OpenAIBadRequestError: lambda e: NotFoundError
+        if hasattr(e, "code") and e.code == "model_not_found"  # pyright: ignore[reportAttributeAccessIssue,reportUnknownMemberType]
+        else BadRequestError,
+    }
 
     def __init__(
         self,
@@ -49,6 +57,10 @@ class OpenAIResponsesProvider(BaseProvider[OpenAI]):
         self.client = OpenAI(api_key=api_key, base_url=base_url)
         self.async_client = AsyncOpenAI(api_key=api_key, base_url=base_url)
 
+    def get_error_status(self, e: Exception) -> int | None:
+        """Extract HTTP status code from OpenAI exception."""
+        return getattr(e, "status_code", None)
+
     def _call(
         self,
         *,
@@ -77,7 +89,6 @@ class OpenAIResponsesProvider(BaseProvider[OpenAI]):
             format=format,
             params=params,
         )
-
         openai_response = self.client.responses.create(**kwargs)
 
         assistant_message, finish_reason, usage = _utils.decode_response(
@@ -127,7 +138,6 @@ class OpenAIResponsesProvider(BaseProvider[OpenAI]):
             format=format,
             params=params,
         )
-
         openai_response = await self.async_client.responses.create(**kwargs)
 
         assistant_message, finish_reason, usage = _utils.decode_response(
@@ -177,7 +187,6 @@ class OpenAIResponsesProvider(BaseProvider[OpenAI]):
             format=format,
             params=params,
         )
-
         openai_stream = self.client.responses.create(
             **kwargs,
             stream=True,
@@ -227,7 +236,6 @@ class OpenAIResponsesProvider(BaseProvider[OpenAI]):
             format=format,
             params=params,
         )
-
         openai_stream = await self.async_client.responses.create(
             **kwargs,
             stream=True,
@@ -281,7 +289,6 @@ class OpenAIResponsesProvider(BaseProvider[OpenAI]):
             format=format,
             params=params,
         )
-
         openai_response = self.client.responses.create(**kwargs)
 
         assistant_message, finish_reason, usage = _utils.decode_response(
@@ -335,7 +342,6 @@ class OpenAIResponsesProvider(BaseProvider[OpenAI]):
             format=format,
             params=params,
         )
-
         openai_response = await self.async_client.responses.create(**kwargs)
 
         assistant_message, finish_reason, usage = _utils.decode_response(

mirascope/llm/providers/provider_id.py

@@ -6,6 +6,7 @@ KnownProviderId: TypeAlias = Literal[
     "anthropic",  # Anthropic provider via AnthropicProvider
     "anthropic-beta",  # Anthropic beta provider via AnthropicBetaProvider
     "google",  # Google provider via GoogleProvider
+    "mirascope",  # Mirascope Router provider via MirascopeProvider
     "mlx",  # Local inference powered by `mlx-lm`, via MLXProvider
     "ollama",  # Ollama provider via OllamaProvider
     "openai",  # OpenAI provider via OpenAIProvider (prefers Responses routing when available)

mirascope/llm/providers/provider_registry.py

@@ -1,16 +1,32 @@
 """Provider registry for managing provider instances and scopes."""
 
+from functools import lru_cache
 from typing import overload
 
 from ..exceptions import NoRegisteredProviderError
+from .anthropic import AnthropicProvider
 from .base import Provider
-from .load_provider import load_provider
+from .google import GoogleProvider
+from .mirascope import MirascopeProvider
+from .mlx import MLXProvider
+from .ollama import OllamaProvider
+from .openai import OpenAIProvider
+from .openai.completions.provider import OpenAICompletionsProvider
+from .openai.responses.provider import OpenAIResponsesProvider
 from .provider_id import ProviderId
+from .together import TogetherProvider
 
 # Global registry mapping scopes to providers
 # Scopes are matched by prefix (longest match wins)
 PROVIDER_REGISTRY: dict[str, Provider] = {}
 
+
+def reset_provider_registry() -> None:
+    """Resets the provider registry, clearing all registered providers."""
+    PROVIDER_REGISTRY.clear()
+    provider_singleton.cache_clear()
+
+
 # Default auto-registration mapping for built-in providers
 # These providers will be automatically registered on first use
 DEFAULT_AUTO_REGISTER_SCOPES: dict[str, ProviderId] = {
@@ -23,6 +39,46 @@ DEFAULT_AUTO_REGISTER_SCOPES: dict[str, ProviderId] = {
 }
 
 
+@lru_cache(maxsize=256)
+def provider_singleton(
+    provider_id: ProviderId, *, api_key: str | None = None, base_url: str | None = None
+) -> Provider:
+    """Create a cached provider instance for the specified provider id.
+
+    Args:
+        provider_id: The provider name ("openai", "anthropic", or "google").
+        api_key: API key for authentication. If None, uses provider-specific env var.
+        base_url: Base URL for the API. If None, uses provider-specific env var.
+
+    Returns:
+        A cached provider instance for the specified provider with the given parameters.
+
+    Raises:
+        ValueError: If the provider_id is not supported.
+    """
+    match provider_id:
+        case "anthropic":
+            return AnthropicProvider(api_key=api_key, base_url=base_url)
+        case "google":
+            return GoogleProvider(api_key=api_key, base_url=base_url)
+        case "mirascope":
+            return MirascopeProvider(api_key=api_key, base_url=base_url)
+        case "mlx":  # pragma: no cover (MLX is only available on macOS)
+            return MLXProvider()
+        case "ollama":
+            return OllamaProvider(api_key=api_key, base_url=base_url)
+        case "openai":
+            return OpenAIProvider(api_key=api_key, base_url=base_url)
+        case "openai:completions":
+            return OpenAICompletionsProvider(api_key=api_key, base_url=base_url)
+        case "openai:responses":
+            return OpenAIResponsesProvider(api_key=api_key, base_url=base_url)
+        case "together":
+            return TogetherProvider(api_key=api_key, base_url=base_url)
+        case _:  # pragma: no cover
+            raise ValueError(f"Unknown provider: '{provider_id}'")
+
+
 @overload
 def register_provider(
     provider: Provider,
@@ -100,7 +156,7 @@ def register_provider(
     """
 
     if isinstance(provider, str):
-        provider = load_provider(provider, api_key=api_key, base_url=base_url)
+        provider = provider_singleton(provider, api_key=api_key, base_url=base_url)
 
     if scope is None:
         scope = provider.default_scope
@@ -160,7 +216,7 @@ def get_provider_for_model(model_id: str) -> Provider:
     if matching_defaults:
         best_scope = max(matching_defaults, key=len)
         provider_id = DEFAULT_AUTO_REGISTER_SCOPES[best_scope]
-        provider = load_provider(provider_id)
+        provider = provider_singleton(provider_id)
         # Auto-register for future calls
         PROVIDER_REGISTRY[best_scope] = provider
         return provider

mirascope/llm/providers/together/__init__.py

@@ -1,18 +1,6 @@
 """Together AI provider implementation."""
 
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from .provider import TogetherProvider
-else:
-    try:
-        from .provider import TogetherProvider
-    except ImportError:  # pragma: no cover
-        from .._missing_import_stubs import (
-            create_provider_stub,
-        )
-
-        TogetherProvider = create_provider_stub("openai", "TogetherProvider")
+from .provider import TogetherProvider
 
 __all__ = [
     "TogetherProvider",

mirascope/llm/responses/base_stream_response.py

@@ -227,7 +227,8 @@ class BaseStreamResponse(
         self.messages = list(input_messages) + [self._assistant_message]
 
         self._chunk_iterator = chunk_iterator
-        self._current_content: Text | Thought | ToolCall | None = None
+        self._current_content: Text | Thought | None = None
+        self._current_tool_calls: dict[str, ToolCall] = {}
 
         self._processing_format_tool: bool = False
 
@@ -269,7 +270,7 @@ class BaseStreamResponse(
         self, chunk: TextStartChunk | TextChunk | TextEndChunk
     ) -> None:
         if chunk.type == "text_start_chunk":
-            if self._current_content:
+            if self._current_content or self._current_tool_calls:
                 raise RuntimeError(
                     "Received text_start_chunk while processing another chunk"
                 )
@@ -292,7 +293,7 @@ class BaseStreamResponse(
         self, chunk: ThoughtStartChunk | ThoughtChunk | ThoughtEndChunk
     ) -> None:
         if chunk.type == "thought_start_chunk":
-            if self._current_content:
+            if self._current_content or self._current_tool_calls:
                 raise RuntimeError(
                     "Received thought_start_chunk while processing another chunk"
                 )
@@ -323,35 +324,38 @@ class BaseStreamResponse(
                 raise RuntimeError(
                     "Received tool_call_start_chunk while processing another chunk"
                 )
-            self._current_content = ToolCall(
+            if chunk.id in self._current_tool_calls:
+                raise RuntimeError("Got tool_call_start_chunk with conflicting id")
+            # Create a new tool call and track it by ID
+            # Multiple tool calls can be in progress simultaneously (interleaved)
+            tool_call = ToolCall(
                 id=chunk.id,
                 name=chunk.name,
                 args="",
             )
+            self._current_tool_calls[chunk.id] = tool_call
 
         elif chunk.type == "tool_call_chunk":
-            if (
-                self._current_content is None
-                or self._current_content.type != "tool_call"
-            ):
+            # Look up the tool call by ID
+            tool_call = self._current_tool_calls.get(chunk.id)
+            if tool_call is None:
                 raise RuntimeError(
-                    "Received tool_call_chunk while not processing tool call."
+                    f"Received tool_call_chunk for unknown tool call ID: {chunk.id}"
                 )
-            self._current_content.args += chunk.delta
+            tool_call.args += chunk.delta
 
         elif chunk.type == "tool_call_end_chunk":
-            if (
-                self._current_content is None
-                or self._current_content.type != "tool_call"
-            ):
+            # Finalize the tool call
+            tool_call = self._current_tool_calls.get(chunk.id)
+            if tool_call is None:
                 raise RuntimeError(
-                    "Received tool_call_end_chunk while not processing tool call."
+                    f"Received tool_call_end_chunk for unknown tool call ID: {chunk.id}"
                 )
-            if not self._current_content.args:
-                self._current_content.args = "{}"
-            self._content.append(self._current_content)
-            self._tool_calls.append(self._current_content)
-            self._current_content = None
+            if not tool_call.args:
+                tool_call.args = "{}"
+            self._content.append(tool_call)
+            self._tool_calls.append(tool_call)
+            del self._current_tool_calls[chunk.id]
 
     def _pretty_chunk(self, chunk: AssistantContentChunk, spacer: str) -> str:
         match chunk.type:

mirascope/llm/tools/decorator.py

@@ -62,15 +62,19 @@ class ToolDecorator:
         is_async = _tool_utils.is_async_tool_fn(fn)
 
         if is_context and is_async:
-            return AsyncContextTool[DepsT, JsonableCovariantT, P](
+            return AsyncContextTool[DepsT, JsonableCovariantT, P].from_function(
                 fn, strict=self.strict
             )
         elif is_context:
-            return ContextTool[DepsT, JsonableCovariantT, P](fn, strict=self.strict)
+            return ContextTool[DepsT, JsonableCovariantT, P].from_function(
+                fn, strict=self.strict
+            )
         elif is_async:
-            return AsyncTool[P, JsonableCovariantT](fn, strict=self.strict)
+            return AsyncTool[P, JsonableCovariantT].from_function(
+                fn, strict=self.strict
+            )
         else:
-            return Tool[P, JsonableCovariantT](fn, strict=self.strict)
+            return Tool[P, JsonableCovariantT].from_function(fn, strict=self.strict)
 
 
 @overload

mirascope/llm/tools/tool_schema.py

@@ -175,10 +175,35 @@ class ToolSchema(Generic[ToolFnT]):
     def __init__(
         self,
         fn: ToolFnT,
+        name: str,
+        description: str,
+        parameters: ToolParameterSchema,
         *,
         strict: bool = False,
-        is_context_tool: bool = False,
     ) -> None:
+        """Create a `ToolSchema` with the provided values.
+
+        Args:
+            fn: The function that implements the tool's functionality
+            name: The name of the tool
+            description: Description of what the tool does
+            parameters: JSON Schema describing the parameters accepted by the tool
+            strict: Whether the tool should use strict mode when supported
+        """
+        self.fn = fn
+        self.name = name
+        self.description = description
+        self.parameters = parameters
+        self.strict = strict
+
+    @classmethod
+    def from_function(
+        cls,
+        fn: AnyToolFn,
+        *,
+        strict: bool = False,
+        is_context_tool: bool = False,
+    ) -> ToolSchema[AnyToolFn]:
         """Create a `ToolSchema` by inspecting a function and its docstring.
 
         Uses Pydantic's create_model to dynamically build a model from the function
@@ -264,11 +289,13 @@ class ToolSchema(Generic[ToolFnT]):
         if "$defs" in schema:
             parameters.defs = schema["$defs"]
 
-        self.fn = fn
-        self.name = name
-        self.description = description
-        self.parameters = parameters
-        self.strict = strict
+        return cls(
+            fn=cast(ToolFnT, fn),
+            name=name,
+            description=description,
+            parameters=parameters,
+            strict=strict,
+        )
 
     def can_execute(self, tool_call: ToolCall) -> bool:
         """Check if a `ToolCall` can be executed by tools with this `ToolSchema`.

mirascope/llm/tools/tools.py

@@ -40,10 +40,27 @@ class Tool(
     This class is not instantiated directly but created by the `@tool()` decorator.
     """
 
-    def __init__(
-        self, fn: ToolFn[AnyP, JsonableCovariantT], *, strict: bool = False
-    ) -> None:
-        super().__init__(fn, strict=strict, is_context_tool=False)
+    @classmethod
+    def from_function(  # pyright: ignore[reportIncompatibleMethodOverride]
+        cls, fn: ToolFn[AnyP, JsonableCovariantT], *, strict: bool = False
+    ) -> Tool[AnyP, JsonableCovariantT]:
+        """Create a `Tool` by inspecting a function and its docstring.
+
+        Args:
+            fn: The function to extract schema from
+            strict: Whether the tool should use strict mode when supported
+
+        Returns:
+            a `Tool` representing the function
+        """
+        schema = ToolSchema.from_function(fn, strict=strict, is_context_tool=False)
+        return cls(
+            fn=cast(ToolFn[AnyP, JsonableCovariantT], schema.fn),
+            name=schema.name,
+            description=schema.description,
+            parameters=schema.parameters,
+            strict=schema.strict,
+        )
 
     def __call__(self, *args: AnyP.args, **kwargs: AnyP.kwargs) -> JsonableCovariantT:
         """Call the underlying function directly."""
@@ -69,10 +86,27 @@ class AsyncTool(
     This class is not instantiated directly but created by the `@tool()` decorator.
     """
 
-    def __init__(
-        self, fn: AsyncToolFn[AnyP, JsonableCovariantT], *, strict: bool = False
-    ) -> None:
-        super().__init__(fn, strict=strict, is_context_tool=False)
+    @classmethod
+    def from_function(  # pyright: ignore[reportIncompatibleMethodOverride]
+        cls, fn: AsyncToolFn[AnyP, JsonableCovariantT], *, strict: bool = False
+    ) -> AsyncTool[AnyP, JsonableCovariantT]:
+        """Create an `AsyncTool` by inspecting a function and its docstring.
+
+        Args:
+            fn: The function to extract schema from
+            strict: Whether the tool should use strict mode when supported
+
+        Returns:
+            an `AsyncTool` representing the function
+        """
+        schema = ToolSchema.from_function(fn, strict=strict, is_context_tool=False)
+        return cls(
+            fn=cast(AsyncToolFn[AnyP, JsonableCovariantT], schema.fn),
+            name=schema.name,
+            description=schema.description,
+            parameters=schema.parameters,
+            strict=schema.strict,
+        )
 
     def __call__(
         self, *args: AnyP.args, **kwargs: AnyP.kwargs
@@ -100,13 +134,30 @@ class ContextTool(
     This class is not instantiated directly but created by the `@tool()` decorator.
     """
 
-    def __init__(
-        self,
+    @classmethod
+    def from_function(  # pyright: ignore[reportIncompatibleMethodOverride]
+        cls,
         fn: ContextToolFn[DepsT, AnyP, JsonableCovariantT],
         *,
         strict: bool = False,
-    ) -> None:
-        super().__init__(fn, strict=strict, is_context_tool=True)
+    ) -> ContextTool[DepsT, JsonableCovariantT, AnyP]:
+        """Create a `ContextTool` by inspecting a function and its docstring.
+
+        Args:
+            fn: The function to extract schema from
+            strict: Whether the tool should use strict mode when supported
+
+        Returns:
+            a `ContextTool` representing the function
+        """
+        schema = ToolSchema.from_function(fn, strict=strict, is_context_tool=True)
+        return cls(
+            fn=cast(ContextToolFn[DepsT, AnyP, JsonableCovariantT], schema.fn),
+            name=schema.name,
+            description=schema.description,
+            parameters=schema.parameters,
+            strict=schema.strict,
+        )
 
     def __call__(
         self,
@@ -141,13 +192,30 @@ class AsyncContextTool(
     This class is not instantiated directly but created by the `@tool()` decorator.
     """
 
-    def __init__(
-        self,
+    @classmethod
+    def from_function(  # pyright: ignore[reportIncompatibleMethodOverride]
+        cls,
         fn: AsyncContextToolFn[DepsT, AnyP, JsonableCovariantT],
         *,
         strict: bool = False,
-    ) -> None:
-        super().__init__(fn, strict=strict, is_context_tool=True)
+    ) -> AsyncContextTool[DepsT, JsonableCovariantT, AnyP]:
+        """Create an `AsyncContextTool` by inspecting a function and its docstring.
+
+        Args:
+            fn: The function to extract schema from
+            strict: Whether the tool should use strict mode when supported
+
+        Returns:
+            an `AsyncContextTool` representing the function
+        """
+        schema = ToolSchema.from_function(fn, strict=strict, is_context_tool=True)
+        return cls(
+            fn=cast(AsyncContextToolFn[DepsT, AnyP, JsonableCovariantT], schema.fn),
+            name=schema.name,
+            description=schema.description,
+            parameters=schema.parameters,
+            strict=schema.strict,
+        )
 
     def __call__(
         self,