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

mirascope/llm/calls/calls.py

@@ -1,11 +1,10 @@
 """The Call module for generating responses using LLMs."""
 
 from dataclasses import dataclass
-from typing import Generic, TypeVar, overload
+from typing import Generic, overload
 
 from ..context import Context, DepsT
 from ..formatting import FormattableT
-from ..models import Model, use_model
 from ..prompts import (
     AsyncContextPrompt,
     AsyncPrompt,
@@ -22,39 +21,19 @@ from ..responses import (
     Response,
     StreamResponse,
 )
+from ..tools import (
+    AsyncContextToolkit,
+    AsyncToolkit,
+    ContextToolkit,
+    Toolkit,
+)
 from ..types import P
-
-CallT = TypeVar("CallT", bound="BaseCall")
-
-
-@dataclass
-class BaseCall:
-    """Base class for all Call types with shared model functionality."""
-
-    default_model: Model
-    """The default model that will be used if no model is set in context."""
-
-    @property
-    def model(self) -> Model:
-        """The model used for generating responses. May be overwritten via `with llm.model(...)`."""
-        return use_model(self.default_model)
+from .base_call import BaseCall
 
 
 @dataclass
-class Call(BaseCall, Generic[P, FormattableT]):
-    """A call that directly generates LLM responses without requiring a model argument.
-
-    Created by decorating a `MessageTemplate` with `llm.call`. The decorated function
-    becomes directly callable to generate responses, with the `Model` bundled in.
-
-    A `Call` is essentially: `MessageTemplate` + tools + format + `Model`.
-    It can be invoked directly: `call(*args, **kwargs)` (no model argument needed).
-
-    The model can be overridden at runtime using `with llm.model(...)` context manager.
-    """
-
-    prompt: Prompt[P, FormattableT]
-    """The underlying Prompt instance that generates messages with tools and format."""
+class Call(BaseCall[P, Prompt, Toolkit, FormattableT], Generic[P, FormattableT]):
+    """A class for generating responses using LLMs."""
 
     @overload
     def __call__(
@@ -84,7 +63,10 @@ class Call(BaseCall, Generic[P, FormattableT]):
         self, *args: P.args, **kwargs: P.kwargs
     ) -> Response | Response[FormattableT]:
         """Generates a response using the LLM."""
-        return self.prompt.call(self.model, *args, **kwargs)
+        messages = self.fn(*args, **kwargs)
+        return self.model.call(
+            messages=messages, tools=self.toolkit, format=self.format
+        )
 
     @overload
     def stream(
@@ -100,24 +82,18 @@ class Call(BaseCall, Generic[P, FormattableT]):
         self, *args: P.args, **kwargs: P.kwargs
     ) -> StreamResponse | StreamResponse[FormattableT]:
         """Generates a streaming response using the LLM."""
-        return self.prompt.stream(self.model, *args, **kwargs)
+        messages = self.fn(*args, **kwargs)
+        return self.model.stream(
+            messages=messages, tools=self.toolkit, format=self.format
+        )
 
 
 @dataclass
-class AsyncCall(BaseCall, Generic[P, FormattableT]):
-    """An async call that directly generates LLM responses without requiring a model argument.
-
-    Created by decorating an async `MessageTemplate` with `llm.call`. The decorated async
-    function becomes directly callable to generate responses asynchronously, with the `Model` bundled in.
-
-    An `AsyncCall` is essentially: async `MessageTemplate` + tools + format + `Model`.
-    It can be invoked directly: `await call(*args, **kwargs)` (no model argument needed).
-
-    The model can be overridden at runtime using `with llm.model(...)` context manager.
-    """
-
-    prompt: AsyncPrompt[P, FormattableT]
-    """The underlying AsyncPrompt instance that generates messages with tools and format."""
+class AsyncCall(
+    BaseCall[P, AsyncPrompt, AsyncToolkit, FormattableT],
+    Generic[P, FormattableT],
+):
+    """A class for generating responses using LLMs asynchronously."""
 
     @overload
     async def __call__(
@@ -132,7 +108,7 @@ class AsyncCall(BaseCall, Generic[P, FormattableT]):
     async def __call__(
         self, *args: P.args, **kwargs: P.kwargs
     ) -> AsyncResponse | AsyncResponse[FormattableT]:
-        """Generates a response using the LLM asynchronously."""
+        """Generates a Asyncresponse using the LLM asynchronously."""
         return await self.call(*args, **kwargs)
 
     @overload
@@ -149,7 +125,10 @@ class AsyncCall(BaseCall, Generic[P, FormattableT]):
         self, *args: P.args, **kwargs: P.kwargs
     ) -> AsyncResponse | AsyncResponse[FormattableT]:
         """Generates a response using the LLM asynchronously."""
-        return await self.prompt.call(self.model, *args, **kwargs)
+        messages = await self.fn(*args, **kwargs)
+        return await self.model.call_async(
+            messages=messages, tools=self.toolkit, format=self.format
+        )
 
     @overload
     async def stream(
@@ -165,25 +144,18 @@ class AsyncCall(BaseCall, Generic[P, FormattableT]):
         self, *args: P.args, **kwargs: P.kwargs
     ) -> AsyncStreamResponse[FormattableT] | AsyncStreamResponse:
         """Generates a streaming response using the LLM asynchronously."""
-        return await self.prompt.stream(self.model, *args, **kwargs)
+        messages = await self.fn(*args, **kwargs)
+        return await self.model.stream_async(
+            messages=messages, tools=self.toolkit, format=self.format
+        )
 
 
 @dataclass
-class ContextCall(BaseCall, Generic[P, DepsT, FormattableT]):
-    """A context-aware call that directly generates LLM responses without requiring a model argument.
-
-    Created by decorating a `ContextMessageTemplate` with `llm.call`. The decorated function
-    (with first parameter `'ctx'` of type `Context[DepsT]`) becomes directly callable to generate
-    responses with context dependencies, with the `Model` bundled in.
-
-    A `ContextCall` is essentially: `ContextMessageTemplate` + tools + format + `Model`.
-    It can be invoked directly: `call(ctx, *args, **kwargs)` (no model argument needed).
-
-    The model can be overridden at runtime using `with llm.model(...)` context manager.
-    """
-
-    prompt: ContextPrompt[P, DepsT, FormattableT]
-    """The underlying ContextPrompt instance that generates messages with tools and format."""
+class ContextCall(
+    BaseCall[P, ContextPrompt, ContextToolkit[DepsT], FormattableT],
+    Generic[P, DepsT, FormattableT],
+):
+    """A class for generating responses using LLMs."""
 
     @overload
     def __call__(
@@ -227,7 +199,10 @@ class ContextCall(BaseCall, Generic[P, DepsT, FormattableT]):
         self, ctx: Context[DepsT], *args: P.args, **kwargs: P.kwargs
     ) -> ContextResponse[DepsT, None] | ContextResponse[DepsT, FormattableT]:
         """Generates a response using the LLM."""
-        return self.prompt.call(self.model, ctx, *args, **kwargs)
+        messages = self.fn(ctx, *args, **kwargs)
+        return self.model.context_call(
+            ctx=ctx, messages=messages, tools=self.toolkit, format=self.format
+        )
 
     @overload
     def stream(
@@ -251,25 +226,18 @@ class ContextCall(BaseCall, Generic[P, DepsT, FormattableT]):
         ContextStreamResponse[DepsT, None] | ContextStreamResponse[DepsT, FormattableT]
     ):
         """Generates a streaming response using the LLM."""
-        return self.prompt.stream(self.model, ctx, *args, **kwargs)
+        messages = self.fn(ctx, *args, **kwargs)
+        return self.model.context_stream(
+            ctx=ctx, messages=messages, tools=self.toolkit, format=self.format
+        )
 
 
 @dataclass
-class AsyncContextCall(BaseCall, Generic[P, DepsT, FormattableT]):
-    """An async context-aware call that directly generates LLM responses without requiring a model argument.
-
-    Created by decorating an async `ContextMessageTemplate` with `llm.call`. The decorated async
-    function (with first parameter `'ctx'` of type `Context[DepsT]`) becomes directly callable to generate
-    responses asynchronously with context dependencies, with the `Model` bundled in.
-
-    An `AsyncContextCall` is essentially: async `ContextMessageTemplate` + tools + format + `Model`.
-    It can be invoked directly: `await call(ctx, *args, **kwargs)` (no model argument needed).
-
-    The model can be overridden at runtime using `with llm.model(...)` context manager.
-    """
-
-    prompt: AsyncContextPrompt[P, DepsT, FormattableT]
-    """The underlying AsyncContextPrompt instance that generates messages with tools and format."""
+class AsyncContextCall(
+    BaseCall[P, AsyncContextPrompt, AsyncContextToolkit[DepsT], FormattableT],
+    Generic[P, DepsT, FormattableT],
+):
+    """A class for generating responses using LLMs asynchronously."""
 
     @overload
     async def __call__(
@@ -313,7 +281,10 @@ class AsyncContextCall(BaseCall, Generic[P, DepsT, FormattableT]):
         self, ctx: Context[DepsT], *args: P.args, **kwargs: P.kwargs
     ) -> AsyncContextResponse[DepsT, None] | AsyncContextResponse[DepsT, FormattableT]:
         """Generates a response using the LLM asynchronously."""
-        return await self.prompt.call(self.model, ctx, *args, **kwargs)
+        messages = await self.fn(ctx, *args, **kwargs)
+        return await self.model.context_call_async(
+            ctx=ctx, messages=messages, tools=self.toolkit, format=self.format
+        )
 
     @overload
     async def stream(
@@ -338,4 +309,7 @@ class AsyncContextCall(BaseCall, Generic[P, DepsT, FormattableT]):
         | AsyncContextStreamResponse[DepsT, FormattableT]
     ):
         """Generates a streaming response using the LLM asynchronously."""
-        return await self.prompt.stream(self.model, ctx, *args, **kwargs)
+        messages = await self.fn(ctx, *args, **kwargs)
+        return await self.model.context_stream_async(
+            ctx=ctx, messages=messages, tools=self.toolkit, format=self.format
+        )

mirascope/llm/calls/decorator.py

@@ -4,24 +4,29 @@ from __future__ import annotations
 
 from collections.abc import Sequence
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Generic, cast, overload
+from typing import Generic, Literal, 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, OutputParser
+from ..formatting import Format, FormattableT
 from ..models import Model
 from ..prompts import (
-    AsyncContextMessageTemplate,
-    AsyncContextPrompt,
-    AsyncMessageTemplate,
-    AsyncPrompt,
-    ContextMessageTemplate,
-    ContextPrompt,
-    MessageTemplate,
-    Prompt,
-    _utils,
+    AsyncContextPromptable,
+    AsyncPromptable,
+    ContextPromptable,
+    Promptable,
+    _utils as _prompt_utils,
+    prompt,
 )
-from ..providers import ModelId
 from ..tools import (
     AsyncContextTool,
     AsyncContextToolkit,
@@ -36,40 +41,19 @@ from ..tools import (
 from ..types import P
 from .calls import AsyncCall, AsyncContextCall, Call, ContextCall
 
-if TYPE_CHECKING:
-    from ..models import Params
-
 
 @dataclass(kw_only=True)
 class CallDecorator(Generic[ToolT, FormattableT]):
-    """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`
-    """
+    """A decorator for converting prompts to calls."""
 
     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] | OutputParser[FormattableT] | None
-    )
-    """The structured output format off the prompt, if any."""
+    format: type[FormattableT] | Format[FormattableT] | None
 
     @overload
     def __call__(
         self: CallDecorator[AsyncTool | AsyncContextTool[DepsT], FormattableT],
-        fn: AsyncContextMessageTemplate[P, DepsT],
+        fn: AsyncContextPromptable[P, DepsT],
     ) -> AsyncContextCall[P, DepsT, FormattableT]:
         """Decorate an async context prompt into an AsyncContextCall."""
         ...
@@ -77,31 +61,31 @@ class CallDecorator(Generic[ToolT, FormattableT]):
     @overload
     def __call__(
         self: CallDecorator[Tool | ContextTool[DepsT], FormattableT],
-        fn: ContextMessageTemplate[P, DepsT],
+        fn: ContextPromptable[P, DepsT],
     ) -> ContextCall[P, DepsT, FormattableT]:
         """Decorate a context prompt into a ContextCall."""
         ...
 
     @overload
     def __call__(
-        self: CallDecorator[AsyncTool, FormattableT], fn: AsyncMessageTemplate[P]
+        self: CallDecorator[AsyncTool, FormattableT], fn: AsyncPromptable[P]
     ) -> AsyncCall[P, FormattableT]:
         """Decorate an async prompt into an AsyncCall."""
         ...
 
     @overload
     def __call__(
-        self: CallDecorator[Tool, FormattableT], fn: MessageTemplate[P]
+        self: CallDecorator[Tool, FormattableT], fn: Promptable[P]
     ) -> Call[P, FormattableT]:
         """Decorate a prompt into a Call."""
         ...
 
     def __call__(
         self,
-        fn: ContextMessageTemplate[P, DepsT]
-        | AsyncContextMessageTemplate[P, DepsT]
-        | MessageTemplate[P]
-        | AsyncMessageTemplate[P],
+        fn: ContextPromptable[P, DepsT]
+        | AsyncContextPromptable[P, DepsT]
+        | Promptable[P]
+        | AsyncPromptable[P],
     ) -> (
         ContextCall[P, DepsT, FormattableT]
         | AsyncContextCall[P, DepsT, FormattableT]
@@ -109,131 +93,123 @@ class CallDecorator(Generic[ToolT, FormattableT]):
         | AsyncCall[P, FormattableT]
     ):
         """Decorates a prompt into a Call or ContextCall."""
-        is_context = _utils.is_context_promptable(fn)
-        is_async = _utils.is_async_promptable(fn)
+        is_context = _prompt_utils.is_context_promptable(fn)
+        is_async = _prompt_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(
-                prompt=prompt,
+                fn=prompt(fn),
                 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(
-                prompt=prompt,
+                fn=prompt(fn),
                 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(
-                prompt=prompt,
+                fn=prompt(fn),
                 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(
-                prompt=prompt,
+                fn=prompt(fn),
                 default_model=self.model,
+                format=self.format,
+                toolkit=Toolkit(tools=tools),
             )
 
 
 @overload
 def call(
-    model: ModelId,
     *,
-    tools: Sequence[ToolT] | None = None,
-    format: type[FormattableT]
-    | Format[FormattableT]
-    | OutputParser[FormattableT]
-    | None = None,
+    provider: Literal["anthropic"],
+    model_id: AnthropicModelId,
+    tools: list[ToolT] | None = None,
+    format: type[FormattableT] | Format[FormattableT] | None = None,
     **params: Unpack[Params],
 ) -> CallDecorator[ToolT, FormattableT]:
-    """Decorator for converting prompt functions into LLM calls.
+    """Decorate a prompt into a Call using Anthropic models."""
+    ...
 
-    This overload accepts a model ID string and allows additional params.
-    """
+
+@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."""
     ...
 
 
 @overload
 def call(
-    model: Model,
     *,
-    tools: Sequence[ToolT] | None = None,
-    format: type[FormattableT]
-    | Format[FormattableT]
-    | OutputParser[FormattableT]
-    | None = None,
+    provider: Literal["openai:completions"],
+    model_id: OpenAICompletionsModelId,
+    tools: list[ToolT] | None = None,
+    format: type[FormattableT] | Format[FormattableT] | None = None,
+    **params: Unpack[Params],
 ) -> CallDecorator[ToolT, FormattableT]:
-    """Decorator for converting prompt functions into LLM calls.
+    """Decorate a prompt into a Call using OpenAI models."""
+    ...
 
-    This overload accepts a Model instance and does not allow additional params.
-    """
+
+@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."""
     ...
 
 
 def call(
-    model: ModelId | Model,
     *,
-    tools: Sequence[ToolT] | None = None,
-    format: type[FormattableT]
-    | Format[FormattableT]
-    | OutputParser[FormattableT]
-    | None = None,
+    provider: Provider,
+    model_id: ModelId,
+    tools: list[ToolT] | None = None,
+    format: type[FormattableT] | Format[FormattableT] | None = None,
     **params: Unpack[Params],
 ) -> CallDecorator[ToolT, FormattableT]:
-    """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`)
+    """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.
 
     Example:
 
@@ -241,12 +217,15 @@ def call(
         ```python
         from mirascope import llm
 
-        @llm.call("openai/gpt-4")
-        def recommend_book(genre: str):
-            return f"Please recommend a book in {genre}."
+        @llm.call(
+            provider="openai:completions",
+            model_id="gpt-4o-mini",
+        )
+        def answer_question(question: str) -> str:
+            return f"Answer this question: {question}"
 
-        response: llm.Response = recommend_book("fantasy")
-        print(response.pretty())
+        response: llm.Response = answer_question("What is the capital of France?")
+        print(response)
         ```
 
     Example:
@@ -257,19 +236,20 @@ def call(
         from mirascope import llm
 
         @dataclass
-        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())
+        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)
         ```
     """
-    if isinstance(model, str):
-        model = Model(model, **params)
+    model = Model(provider=provider, model_id=model_id, **params)
     return CallDecorator(model=model, tools=tools, format=format)

mirascope/llm/clients/__init__.py

@@ -0,0 +1,34 @@
+"""Client interfaces for LLM providers."""
+
+from .anthropic import (
+    AnthropicClient,
+    AnthropicModelId,
+)
+from .base import BaseClient, ClientT, Params
+from .google import GoogleClient, GoogleModelId
+from .openai import (
+    OpenAICompletionsClient,
+    OpenAICompletionsModelId,
+    OpenAIResponsesClient,
+    OpenAIResponsesModelId,
+)
+from .providers import PROVIDERS, ModelId, Provider, client, get_client
+
+__all__ = [
+    "PROVIDERS",
+    "AnthropicClient",
+    "AnthropicModelId",
+    "BaseClient",
+    "ClientT",
+    "GoogleClient",
+    "GoogleModelId",
+    "ModelId",
+    "OpenAICompletionsClient",
+    "OpenAICompletionsModelId",
+    "OpenAIResponsesClient",
+    "OpenAIResponsesModelId",
+    "Params",
+    "Provider",
+    "client",
+    "get_client",
+]