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

mirascope/llm/calls/decorator.py

@@ -4,29 +4,24 @@ from __future__ import annotations
 
 from collections.abc import Sequence
 from dataclasses import dataclass
-from typing import Generic, Literal, cast, overload
+from typing import Generic, cast, overload
 from typing_extensions import Unpack
 
-from ..clients import (
-    AnthropicModelId,
-    GoogleModelId,
-    ModelId,
-    OpenAICompletionsModelId,
-    OpenAIResponsesModelId,
-    Params,
-    Provider,
-)
 from ..context import DepsT
 from ..formatting import Format, FormattableT
 from ..models import Model
 from ..prompts import (
-    AsyncContextPromptable,
-    AsyncPromptable,
-    ContextPromptable,
-    Promptable,
-    _utils as _prompt_utils,
-    prompt,
+    AsyncContextMessageTemplate,
+    AsyncContextPrompt,
+    AsyncMessageTemplate,
+    AsyncPrompt,
+    ContextMessageTemplate,
+    ContextPrompt,
+    MessageTemplate,
+    Prompt,
+    _utils,
 )
+from ..providers import ModelId, Params
 from ..tools import (
     AsyncContextTool,
     AsyncContextToolkit,
@@ -44,16 +39,32 @@ from .calls import AsyncCall, AsyncContextCall, Call, ContextCall
 
 @dataclass(kw_only=True)
 class CallDecorator(Generic[ToolT, FormattableT]):
-    """A decorator for converting prompts to calls."""
+    """Decorator for converting a `MessageTemplate` into a `Call`.
+
+    Takes a raw prompt function that returns message content and wraps it with tools,
+    format, and a model to create a `Call` that can be invoked directly without needing
+    to pass a model argument.
+
+    The decorator automatically detects whether the function is async or context-aware
+    and creates the appropriate `Call` variant (`Call`, `AsyncCall`, `ContextCall`, or `AsyncContextCall`).
+
+    Conceptually: `CallDecorator` = `PromptDecorator` + `Model`
+    Result: `Call` = `MessageTemplate` + tools + format + `Model`
+    """
 
     model: Model
+    """The default model to use with this call. May be overridden."""
+
     tools: Sequence[ToolT] | None
+    """The tools that are included in the prompt, if any."""
+
     format: type[FormattableT] | Format[FormattableT] | None
+    """The structured output format off the prompt, if any."""
 
     @overload
     def __call__(
         self: CallDecorator[AsyncTool | AsyncContextTool[DepsT], FormattableT],
-        fn: AsyncContextPromptable[P, DepsT],
+        fn: AsyncContextMessageTemplate[P, DepsT],
     ) -> AsyncContextCall[P, DepsT, FormattableT]:
         """Decorate an async context prompt into an AsyncContextCall."""
         ...
@@ -61,31 +72,31 @@ class CallDecorator(Generic[ToolT, FormattableT]):
     @overload
     def __call__(
         self: CallDecorator[Tool | ContextTool[DepsT], FormattableT],
-        fn: ContextPromptable[P, DepsT],
+        fn: ContextMessageTemplate[P, DepsT],
     ) -> ContextCall[P, DepsT, FormattableT]:
         """Decorate a context prompt into a ContextCall."""
         ...
 
     @overload
     def __call__(
-        self: CallDecorator[AsyncTool, FormattableT], fn: AsyncPromptable[P]
+        self: CallDecorator[AsyncTool, FormattableT], fn: AsyncMessageTemplate[P]
     ) -> AsyncCall[P, FormattableT]:
         """Decorate an async prompt into an AsyncCall."""
         ...
 
     @overload
     def __call__(
-        self: CallDecorator[Tool, FormattableT], fn: Promptable[P]
+        self: CallDecorator[Tool, FormattableT], fn: MessageTemplate[P]
     ) -> Call[P, FormattableT]:
         """Decorate a prompt into a Call."""
         ...
 
     def __call__(
         self,
-        fn: ContextPromptable[P, DepsT]
-        | AsyncContextPromptable[P, DepsT]
-        | Promptable[P]
-        | AsyncPromptable[P],
+        fn: ContextMessageTemplate[P, DepsT]
+        | AsyncContextMessageTemplate[P, DepsT]
+        | MessageTemplate[P]
+        | AsyncMessageTemplate[P],
     ) -> (
         ContextCall[P, DepsT, FormattableT]
         | AsyncContextCall[P, DepsT, FormattableT]
@@ -93,123 +104,122 @@ class CallDecorator(Generic[ToolT, FormattableT]):
         | AsyncCall[P, FormattableT]
     ):
         """Decorates a prompt into a Call or ContextCall."""
-        is_context = _prompt_utils.is_context_promptable(fn)
-        is_async = _prompt_utils.is_async_promptable(fn)
+        is_context = _utils.is_context_promptable(fn)
+        is_async = _utils.is_async_promptable(fn)
 
         if is_context and is_async:
             tools = cast(
                 Sequence[AsyncTool | AsyncContextTool[DepsT]] | None, self.tools
             )
+            prompt = AsyncContextPrompt(
+                fn=fn,
+                toolkit=AsyncContextToolkit(tools=tools),
+                format=self.format,
+            )
             return AsyncContextCall(
-                fn=prompt(fn),
+                prompt=prompt,
                 default_model=self.model,
-                format=self.format,
-                toolkit=AsyncContextToolkit(tools=tools),
             )
         elif is_context:
             tools = cast(Sequence[Tool | ContextTool[DepsT]] | None, self.tools)
+            prompt = ContextPrompt(
+                fn=fn,
+                toolkit=ContextToolkit(tools=tools),
+                format=self.format,
+            )
             return ContextCall(
-                fn=prompt(fn),
+                prompt=prompt,
                 default_model=self.model,
-                format=self.format,
-                toolkit=ContextToolkit(tools=tools),
             )
         elif is_async:
             tools = cast(Sequence[AsyncTool] | None, self.tools)
+            prompt = AsyncPrompt(
+                fn=fn, toolkit=AsyncToolkit(tools=tools), format=self.format
+            )
             return AsyncCall(
-                fn=prompt(fn),
+                prompt=prompt,
                 default_model=self.model,
-                format=self.format,
-                toolkit=AsyncToolkit(tools=tools),
             )
         else:
             tools = cast(Sequence[Tool] | None, self.tools)
+            prompt = Prompt(fn=fn, toolkit=Toolkit(tools=tools), format=self.format)
             return Call(
-                fn=prompt(fn),
+                prompt=prompt,
                 default_model=self.model,
-                format=self.format,
-                toolkit=Toolkit(tools=tools),
             )
 
 
 @overload
 def call(
+    model: ModelId,
     *,
-    provider: Literal["anthropic"],
-    model_id: AnthropicModelId,
-    tools: list[ToolT] | None = None,
+    tools: Sequence[ToolT] | None = None,
     format: type[FormattableT] | Format[FormattableT] | None = None,
     **params: Unpack[Params],
 ) -> CallDecorator[ToolT, FormattableT]:
-    """Decorate a prompt into a Call using Anthropic models."""
-    ...
-
+    """Decorator for converting prompt functions into LLM calls.
 
-@overload
-def call(
-    *,
-    provider: Literal["google"],
-    model_id: GoogleModelId,
-    tools: list[ToolT] | None = None,
-    format: type[FormattableT] | Format[FormattableT] | None = None,
-    **params: Unpack[Params],
-) -> CallDecorator[ToolT, FormattableT]:
-    """Decorate a prompt into a Call using Google models."""
+    This overload accepts a model ID string and allows additional params.
+    """
     ...
 
 
 @overload
 def call(
+    model: Model,
     *,
-    provider: Literal["openai:completions"],
-    model_id: OpenAICompletionsModelId,
-    tools: list[ToolT] | None = None,
+    tools: Sequence[ToolT] | None = None,
     format: type[FormattableT] | Format[FormattableT] | None = None,
-    **params: Unpack[Params],
 ) -> CallDecorator[ToolT, FormattableT]:
-    """Decorate a prompt into a Call using OpenAI models."""
-    ...
-
+    """Decorator for converting prompt functions into LLM calls.
 
-@overload
-def call(
-    *,
-    provider: Literal["openai:responses", "openai"],
-    model_id: OpenAIResponsesModelId,
-    tools: list[ToolT] | None = None,
-    format: type[FormattableT] | Format[FormattableT] | None = None,
-    **params: Unpack[Params],
-) -> CallDecorator[ToolT, FormattableT]:
-    """Decorate a prompt into a Call using OpenAI models (Responses API)."""
-    ...
-
-
-@overload
-def call(
-    *,
-    provider: Provider,
-    model_id: ModelId,
-    tools: list[ToolT] | None = None,
-    format: type[FormattableT] | Format[FormattableT] | None = None,
-    **params: Unpack[Params],
-) -> CallDecorator[ToolT, FormattableT]:
-    """Decorate a prompt into a Call using a generic provider and model."""
+    This overload accepts a Model instance and does not allow additional params.
+    """
     ...
 
 
 def call(
+    model: ModelId | Model,
     *,
-    provider: Provider,
-    model_id: ModelId,
-    tools: list[ToolT] | None = None,
+    tools: Sequence[ToolT] | None = None,
     format: type[FormattableT] | Format[FormattableT] | None = None,
     **params: Unpack[Params],
 ) -> CallDecorator[ToolT, FormattableT]:
-    """Returns a decorator for turning prompt template functions into generations.
-
-    This decorator creates a `Call` or `ContextCall` that can be used with prompt functions.
-    If the first parameter is typed as `llm.Context[T]`, it creates a ContextCall.
-    Otherwise, it creates a regular Call.
+    """Decorates a `MessageTemplate` to create a `Call` that can be invoked directly.
+
+    The `llm.call` decorator is the most convenient way to use Mirascope. It transforms
+    a raw prompt function (that returns message content) into a `Call` object that bundles
+    the function with tools, format, and a model. The resulting `Call` can be invoked
+    directly to generate LLM responses without needing to pass a model argument.
+
+    The decorator automatically detects the function type:
+    - If the first parameter is named `'ctx'` with type `llm.Context[T]` (or a subclass thereof),
+      creates a `ContextCall`
+    - If the function is async, creates an `AsyncCall` or `AsyncContextCall`
+    - Otherwise, creates a regular `Call`
+
+    The model specified in the decorator can be overridden at runtime using the
+    `llm.model()` context manager. When overridden, the context model completely
+    replaces the decorated model, including all parameters.
+
+    Conceptual flow:
+    - `MessageTemplate`: raw function returning content
+    - `@llm.prompt`: `MessageTemplate` → `Prompt`
+      Includes tools and format, if applicable. Can be called by providing a `Model`.
+    - `@llm.call`: `MessageTemplate` → `Call`. Includes a model, tools, and format. The
+      model may be created on the fly from a model identifier and optional params, or
+      provided outright.
+
+    Args:
+        model: A model ID string (e.g., "openai/gpt-4") or a `Model` instance
+        tools: Optional `Sequence` of tools to make available to the LLM
+        format: Optional response format class (`BaseModel`) or Format instance
+        **params: Additional call parameters (temperature, max_tokens, etc.)
+            Only available when passing a model ID string
+
+    Returns:
+        A `CallDecorator` that converts prompt functions into `Call` variants
+        (`Call`, `AsyncCall`, `ContextCall`, or `AsyncContextCall`)
 
     Example:
 
@@ -217,15 +227,12 @@ def call(
         ```python
         from mirascope import llm
 
-        @llm.call(
-            provider="openai:completions",
-            model_id="gpt-4o-mini",
-        )
-        def answer_question(question: str) -> str:
-            return f"Answer this question: {question}"
+        @llm.call("openai/gpt-4")
+        def recommend_book(genre: str):
+            return f"Please recommend a book in {genre}."
 
-        response: llm.Response = answer_question("What is the capital of France?")
-        print(response)
+        response: llm.Response = recommend_book("fantasy")
+        print(response.pretty())
         ```
 
     Example:
@@ -236,20 +243,19 @@ def call(
         from mirascope import llm
 
         @dataclass
-        class Personality:
-            vibe: str
-
-        @llm.call(
-            provider="openai:completions",
-            model_id="gpt-4o-mini",
-        )
-        def answer_question(ctx: llm.Context[Personality], question: str) -> str:
-            return f"Your vibe is {ctx.deps.vibe}. Answer this question: {question}"
-
-        ctx = llm.Context(deps=Personality(vibe="snarky"))
-        response = answer_question(ctx, "What is the capital of France?")
-        print(response)
+        class User:
+            name: str
+            age: int
+
+        @llm.call("openai/gpt-4")
+        def recommend_book(ctx: llm.Context[User], genre: str):
+            return f"Recommend a {genre} book for {ctx.deps.name}, age {ctx.deps.age}."
+
+        ctx = llm.Context(deps=User(name="Alice", age=15))
+        response = recommend_book(ctx, "fantasy")
+        print(response.pretty())
         ```
     """
-    model = Model(provider=provider, model_id=model_id, **params)
+    if isinstance(model, str):
+        model = Model(model, **params)
     return CallDecorator(model=model, tools=tools, format=format)

mirascope/llm/content/__init__.py

@@ -2,6 +2,7 @@
 
 from typing import TypeAlias
 
+from ..types import Jsonable
 from .audio import Audio, Base64AudioSource
 from .document import (
     Base64DocumentSource,
@@ -16,11 +17,11 @@ from .tool_call import ToolCall, ToolCallChunk, ToolCallEndChunk, ToolCallStartC
 from .tool_output import ToolOutput
 
 ContentPart: TypeAlias = (
-    Text | Image | Audio | Document | ToolOutput | ToolCall | Thought
+    Text | Image | Audio | Document | ToolOutput[Jsonable] | ToolCall | Thought
 )
 """Content parts that may be included in a Message."""
 
-UserContentPart: TypeAlias = Text | Image | Audio | Document | ToolOutput
+UserContentPart: TypeAlias = Text | Image | Audio | Document | ToolOutput[Jsonable]
 """Content parts that can be included in a UserMessage."""
 
 AssistantContentPart: TypeAlias = Text | ToolCall | Thought

mirascope/llm/context/_utils.py

@@ -1,11 +1,12 @@
 import inspect
+import typing
 from collections.abc import Callable
-from typing import get_origin
+from typing import Any, get_origin
 
 from .context import Context
 
 
-def first_param_is_context(fn: Callable) -> bool:
+def first_param_is_context(fn: Callable[..., Any]) -> bool:
     """Returns whether the first argument to a function is `ctx: Context`.
 
     Also returns true if the first argument is a subclass of `Context`.
@@ -21,8 +22,20 @@ def first_param_is_context(fn: Callable) -> bool:
     else:
         first_param = params[0]
 
-    type_is_context = get_origin(first_param.annotation) is Context
-    subclass_of_context = isinstance(first_param.annotation, type) and issubclass(
-        first_param.annotation, Context
+    if first_param.name != "ctx":
+        return False
+
+    try:
+        hints = typing.get_type_hints(fn)
+        annotation = hints.get(first_param.name)
+    except (NameError, AttributeError, TypeError):
+        annotation = first_param.annotation
+
+    if annotation is None or annotation is inspect.Parameter.empty:
+        return False
+
+    type_is_context = get_origin(annotation) is Context
+    subclass_of_context = isinstance(annotation, type) and issubclass(
+        annotation, Context
     )
-    return first_param.name == "ctx" and (type_is_context or subclass_of_context)
+    return type_is_context or subclass_of_context

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,
     )