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

mirascope/llm/calls/calls.py

@@ -5,6 +5,7 @@ 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,
@@ -21,19 +22,37 @@ from ..responses import (
     Response,
     StreamResponse,
 )
-from ..tools import (
-    AsyncContextToolkit,
-    AsyncToolkit,
-    ContextToolkit,
-    Toolkit,
-)
 from ..types import P
-from .base_call import BaseCall
 
 
 @dataclass
-class Call(BaseCall[P, Prompt, Toolkit, FormattableT], Generic[P, FormattableT]):
-    """A class for generating responses using LLMs."""
+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)
+
+
+@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."""
 
     @overload
     def __call__(
@@ -63,10 +82,7 @@ class Call(BaseCall[P, Prompt, Toolkit, FormattableT], Generic[P, FormattableT])
         self, *args: P.args, **kwargs: P.kwargs
     ) -> Response | Response[FormattableT]:
         """Generates a response using the LLM."""
-        messages = self.fn(*args, **kwargs)
-        return self.model.call(
-            messages=messages, tools=self.toolkit, format=self.format
-        )
+        return self.prompt.call(self.model, *args, **kwargs)
 
     @overload
     def stream(
@@ -82,18 +98,24 @@ class Call(BaseCall[P, Prompt, Toolkit, FormattableT], Generic[P, FormattableT])
         self, *args: P.args, **kwargs: P.kwargs
     ) -> StreamResponse | StreamResponse[FormattableT]:
         """Generates a streaming response using the LLM."""
-        messages = self.fn(*args, **kwargs)
-        return self.model.stream(
-            messages=messages, tools=self.toolkit, format=self.format
-        )
+        return self.prompt.stream(self.model, *args, **kwargs)
 
 
 @dataclass
-class AsyncCall(
-    BaseCall[P, AsyncPrompt, AsyncToolkit, FormattableT],
-    Generic[P, FormattableT],
-):
-    """A class for generating responses using LLMs asynchronously."""
+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."""
 
     @overload
     async def __call__(
@@ -108,7 +130,7 @@ class AsyncCall(
     async def __call__(
         self, *args: P.args, **kwargs: P.kwargs
     ) -> AsyncResponse | AsyncResponse[FormattableT]:
-        """Generates a Asyncresponse using the LLM asynchronously."""
+        """Generates a response using the LLM asynchronously."""
         return await self.call(*args, **kwargs)
 
     @overload
@@ -125,10 +147,7 @@ class AsyncCall(
         self, *args: P.args, **kwargs: P.kwargs
     ) -> AsyncResponse | AsyncResponse[FormattableT]:
         """Generates a response using the LLM asynchronously."""
-        messages = await self.fn(*args, **kwargs)
-        return await self.model.call_async(
-            messages=messages, tools=self.toolkit, format=self.format
-        )
+        return await self.prompt.call(self.model, *args, **kwargs)
 
     @overload
     async def stream(
@@ -144,18 +163,25 @@ class AsyncCall(
         self, *args: P.args, **kwargs: P.kwargs
     ) -> AsyncStreamResponse[FormattableT] | AsyncStreamResponse:
         """Generates a streaming response using the LLM asynchronously."""
-        messages = await self.fn(*args, **kwargs)
-        return await self.model.stream_async(
-            messages=messages, tools=self.toolkit, format=self.format
-        )
+        return await self.prompt.stream(self.model, *args, **kwargs)
 
 
 @dataclass
-class ContextCall(
-    BaseCall[P, ContextPrompt, ContextToolkit[DepsT], FormattableT],
-    Generic[P, DepsT, FormattableT],
-):
-    """A class for generating responses using LLMs."""
+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."""
 
     @overload
     def __call__(
@@ -199,10 +225,7 @@ class ContextCall(
         self, ctx: Context[DepsT], *args: P.args, **kwargs: P.kwargs
     ) -> ContextResponse[DepsT, None] | ContextResponse[DepsT, FormattableT]:
         """Generates a response using the LLM."""
-        messages = self.fn(ctx, *args, **kwargs)
-        return self.model.context_call(
-            ctx=ctx, messages=messages, tools=self.toolkit, format=self.format
-        )
+        return self.prompt.call(self.model, ctx, *args, **kwargs)
 
     @overload
     def stream(
@@ -226,18 +249,25 @@ class ContextCall(
         ContextStreamResponse[DepsT, None] | ContextStreamResponse[DepsT, FormattableT]
     ):
         """Generates a streaming response using the LLM."""
-        messages = self.fn(ctx, *args, **kwargs)
-        return self.model.context_stream(
-            ctx=ctx, messages=messages, tools=self.toolkit, format=self.format
-        )
+        return self.prompt.stream(self.model, ctx, *args, **kwargs)
 
 
 @dataclass
-class AsyncContextCall(
-    BaseCall[P, AsyncContextPrompt, AsyncContextToolkit[DepsT], FormattableT],
-    Generic[P, DepsT, FormattableT],
-):
-    """A class for generating responses using LLMs asynchronously."""
+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."""
 
     @overload
     async def __call__(
@@ -281,10 +311,7 @@ class AsyncContextCall(
         self, ctx: Context[DepsT], *args: P.args, **kwargs: P.kwargs
     ) -> AsyncContextResponse[DepsT, None] | AsyncContextResponse[DepsT, FormattableT]:
         """Generates a response using the LLM asynchronously."""
-        messages = await self.fn(ctx, *args, **kwargs)
-        return await self.model.context_call_async(
-            ctx=ctx, messages=messages, tools=self.toolkit, format=self.format
-        )
+        return await self.prompt.call(self.model, ctx, *args, **kwargs)
 
     @overload
     async def stream(
@@ -309,7 +336,4 @@ class AsyncContextCall(
         | AsyncContextStreamResponse[DepsT, FormattableT]
     ):
         """Generates a streaming response using the LLM asynchronously."""
-        messages = await self.fn(ctx, *args, **kwargs)
-        return await self.model.context_stream_async(
-            ctx=ctx, messages=messages, tools=self.toolkit, format=self.format
-        )
+        return await self.prompt.stream(self.model, ctx, *args, **kwargs)

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