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

mirascope/llm/exceptions.py

@@ -1,25 +1,25 @@
-"""Mirascope exception hierarchy for unified error handling across providers."""
+"""Mirascope llm exception hierarchy for unified error handling across providers."""
 
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from .clients import ModelId, Provider
     from .formatting import FormattingMode
+    from .providers import ModelId, ProviderId
 
 
-class MirascopeError(Exception):
-    """Base exception for all Mirascope errors."""
+class MirascopeLLMError(Exception):
+    """Base exception for all Mirascope LLM errors."""
 
     original_exception: Exception | None
 
 
-class APIError(MirascopeError):
+class APIError(MirascopeLLMError):
     """Base class for API-related errors."""
 
     status_code: int | None
 
 
-class ConnectionError(MirascopeError):
+class ConnectionError(MirascopeLLMError):
     """Raised when unable to connect to the API (network issues, timeouts)."""
 
 
@@ -39,33 +39,33 @@ class NotFoundError(APIError):
     """Raised when requested resource is not found (404)."""
 
 
-class ToolNotFoundError(MirascopeError):
+class ToolNotFoundError(MirascopeLLMError):
     """Raised if a tool_call cannot be converted to any corresponding tool."""
 
 
-class FeatureNotSupportedError(MirascopeError):
+class FeatureNotSupportedError(MirascopeLLMError):
     """Raised if a Mirascope feature is unsupported by chosen provider.
 
     If compatibility is model-specific, then `model_id` should be specified.
     If the feature is not supported by the provider at all, then it may be `None`."""
 
-    provider: "Provider"
+    provider_id: "ProviderId"
     model_id: "ModelId | None"
     feature: str
 
     def __init__(
         self,
         feature: str,
-        provider: "Provider",
+        provider_id: "ProviderId",
         model_id: "ModelId | None" = None,
         message: str | None = None,
     ) -> None:
         if message is None:
             model_msg = f" for model '{model_id}'" if model_id is not None else ""
-            message = f"Feature '{feature}' is not supported by provider '{provider}'{model_msg}"
+            message = f"Feature '{feature}' is not supported by provider '{provider_id}'{model_msg}"
         super().__init__(message)
         self.feature = feature
-        self.provider = provider
+        self.provider_id = provider_id
         self.model_id = model_id
 
 
@@ -77,16 +77,16 @@ class FormattingModeNotSupportedError(FeatureNotSupportedError):
     def __init__(
         self,
         formatting_mode: "FormattingMode",
-        provider: "Provider",
+        provider_id: "ProviderId",
         model_id: "ModelId | None" = None,
         message: str | None = None,
     ) -> None:
         if message is None:
             model_msg = f" for model '{model_id}'" if model_id is not None else ""
-            message = f"Formatting mode '{formatting_mode}' is not supported by provider '{provider}'{model_msg}"
+            message = f"Formatting mode '{formatting_mode}' is not supported by provider '{provider_id}'{model_msg}"
         super().__init__(
             feature=f"formatting_mode:{formatting_mode}",
-            provider=provider,
+            provider_id=provider_id,
             model_id=model_id,
             message=message,
         )
@@ -101,5 +101,19 @@ class ServerError(APIError):
     """Raised for server-side errors (500+)."""
 
 
-class TimeoutError(MirascopeError):
+class TimeoutError(MirascopeLLMError):
     """Raised when requests timeout or deadline exceeded."""
+
+
+class NoRegisteredProviderError(MirascopeLLMError):
+    """Raised when no provider is registered for a given model_id."""
+
+    model_id: str
+
+    def __init__(self, model_id: str) -> None:
+        message = (
+            f"No provider registered for model '{model_id}'. "
+            f"Use llm.register_provider() to register a provider for this model."
+        )
+        super().__init__(message)
+        self.model_id = model_id

mirascope/llm/formatting/_utils.py

@@ -2,8 +2,9 @@
 
 import inspect
 import json
+from typing import Any, cast
 
-from ..tools import FORMAT_TOOL_NAME, ToolParameterSchema, ToolSchema
+from ..tools import FORMAT_TOOL_NAME, ToolFn, ToolParameterSchema, ToolSchema
 from .types import Format, FormattableT, FormattingMode
 
 TOOL_MODE_INSTRUCTIONS = f"""Always respond to the user's query using the {FORMAT_TOOL_NAME} tool for structured output."""
@@ -27,7 +28,9 @@ def default_formatting_instructions(
         return inspect.cleandoc(instructions)
 
 
-def create_tool_schema(format: Format[FormattableT]) -> ToolSchema:
+def create_tool_schema(
+    format: Format[FormattableT],
+) -> ToolSchema[ToolFn[..., None]]:
     """Convert a `Format` to a `ToolSchema` for format parsing.
 
     Args:
@@ -37,13 +40,14 @@ def create_tool_schema(format: Format[FormattableT]) -> ToolSchema:
         `ToolSchema` for the format tool
     """
 
-    schema_dict = format.schema.copy()
+    schema_dict: dict[str, Any] = format.schema.copy()
     schema_dict["type"] = "object"
 
     properties = schema_dict.get("properties")
     if not properties or not isinstance(properties, dict):
         properties = {}  # pragma: no cover
-    required = list(properties.keys())
+    properties = cast(dict[str, Any], properties)
+    required: list[str] = list(properties.keys())
 
     description = (
         f"Use this tool to extract data in {format.name} format for a final response."
@@ -64,7 +68,7 @@ def create_tool_schema(format: Format[FormattableT]) -> ToolSchema:
             "Format tool function should not be called."
         )  # pragma: no cover
 
-    tool_schema = ToolSchema.__new__(ToolSchema)
+    tool_schema = cast(ToolSchema[ToolFn[..., None]], ToolSchema.__new__(ToolSchema))
     tool_schema.fn = _unused_format_fn
     tool_schema.name = FORMAT_TOOL_NAME
     tool_schema.description = description

mirascope/llm/formatting/format.py

@@ -55,8 +55,8 @@ def format(
       format = llm.format(Book, mode="strict")
 
       @llm.call(
-          provider="openai:completions",
-          model_id="gpt-4o-mini",
+          provider_id="openai",
+          model_id="openai/gpt-5-mini",
           format=format,
       )
       def recommend_book(genre: str):

mirascope/llm/formatting/from_call_args.py

@@ -20,8 +20,8 @@ class FromCallArgs:
 
 
     @llm.call(
-        provider="openai:completions",
-        model_id="gpt-4o-mini",
+        provider_id="openai",
+        model_id="openai/gpt-5-mini",
         format=Book,
     )
     def summarize_book(title: str, author: str):

mirascope/llm/messages/message.py

@@ -10,7 +10,7 @@ from ..content import AssistantContentPart, Text, UserContentPart
 from ..types import Jsonable
 
 if TYPE_CHECKING:
-    from ..clients import ModelId, Provider
+    from ..providers import ModelId, ProviderId
 
 
 @dataclass(kw_only=True)
@@ -51,12 +51,15 @@ class AssistantMessage:
     name: str | None = None
     """A name identifying the creator of this message."""
 
-    provider: Provider | None
+    provider_id: ProviderId | None
     """The LLM provider that generated this assistant message, if available."""
 
     model_id: ModelId | None
     """The model identifier of the LLM that generated this assistant message, if available."""
 
+    provider_model_name: str | None
+    """The provider-specific model identifier (e.g. "gpt-5:responses"), if available."""
+
     raw_message: Jsonable | None
     """The provider-specific raw representation of this assistant message, if available.
 
@@ -149,8 +152,9 @@ def user(
 def assistant(
     content: AssistantContent,
     *,
-    provider: Provider | None,
     model_id: ModelId | None,
+    provider_id: ProviderId | None,
+    provider_model_name: str | None = None,
     raw_message: Jsonable | None = None,
     name: str | None = None,
 ) -> AssistantMessage:
@@ -159,8 +163,10 @@ def assistant(
     Args:
         content: The content of the message, which can be `str` or any `AssistantContent`,
             or a sequence of assistant content pieces.
-        provider: Optional identifier of the provider that produced this message.
         model_id: Optional id of the model that produced this message.
+        provider_id: Optional identifier of the provider that produced this message.
+        provider_model_name: Optional provider-specific model name. May include
+            provider-specific additional info (like api mode in "gpt-5:responses").
         raw_message: Optional Jsonable object that contains the provider-specific
             "raw" data representation of the content for this assistant message.
         name: Optional name to identify a specific assistant in multi-party conversations.
@@ -168,6 +174,7 @@ def assistant(
     Returns:
         An `AssistantMessage`.
     """
+
     if isinstance(content, str) or not isinstance(content, Sequence):
         content = [content]
     promoted_content = [
@@ -175,8 +182,9 @@ def assistant(
     ]
     return AssistantMessage(
         content=promoted_content,
-        provider=provider,
+        provider_id=provider_id,
         model_id=model_id,
+        provider_model_name=provider_model_name,
         raw_message=raw_message,
         name=name,
     )

mirascope/llm/models/__init__.py

@@ -6,11 +6,11 @@ the model at runtime, and `llm.use_model()` retrieves the model from context or
 creates a default one.
 """
 
-from .models import Model, get_model_from_context, model, use_model
+from .models import Model, model, model_from_context, use_model
 
 __all__ = [
     "Model",
-    "get_model_from_context",
     "model",
+    "model_from_context",
     "use_model",
 ]