mirascope 1.0.5__py3-none-any.whl → 2.1.1__py3-none-any.whl

mirascope/llm/prompts/prompts.py

@@ -0,0 +1,484 @@
+"""Concrete Prompt classes for generating messages with tools and formatting."""
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Generic, TypeVar, overload
+
+from ..._utils import copy_function_metadata
+from ..context import Context, DepsT
+from ..formatting import FormatSpec, FormattableT
+from ..messages import Message, promote_to_messages
+from ..models import Model
+from ..providers import ModelId
+from ..responses import (
+    AsyncContextResponse,
+    AsyncContextStreamResponse,
+    AsyncResponse,
+    AsyncStreamResponse,
+    ContextResponse,
+    ContextStreamResponse,
+    Response,
+    StreamResponse,
+)
+from ..tools import AsyncContextToolkit, AsyncToolkit, ContextToolkit, Toolkit
+from ..types import P
+from .protocols import (
+    AsyncContextMessageTemplate,
+    AsyncMessageTemplate,
+    ContextMessageTemplate,
+    MessageTemplate,
+)
+
+FunctionT = TypeVar("FunctionT", bound=Callable[..., Any])
+
+
+@dataclass(kw_only=True)
+class BasePrompt(Generic[FunctionT]):
+    """Base class for all Prompt types with shared metadata functionality."""
+
+    fn: FunctionT
+    """The underlying prompt function that generates message content."""
+
+    __name__: str = field(init=False, repr=False, default="")
+    """The name of the underlying function (preserved for decorator stacking)."""
+
+    def __post_init__(self) -> None:
+        """Preserve standard function attributes for decorator stacking."""
+        copy_function_metadata(self, self.fn)
+
+
+@dataclass
+class Prompt(BasePrompt[MessageTemplate[P]], Generic[P, FormattableT]):
+    """A prompt that can be called with a model to generate a response.
+
+    Created by decorating a `MessageTemplate` with `llm.prompt`. The decorated
+    function becomes callable with a `Model` to generate LLM responses.
+
+    A `Prompt` is essentially: `MessageTemplate` + tools + format.
+    It can be invoked with a model: `prompt(model, *args, **kwargs)`.
+    """
+
+    toolkit: Toolkit
+    """The toolkit containing this prompt's tools."""
+
+    format: FormatSpec[FormattableT] | None
+    """The response format for the generated response."""
+
+    def messages(self, *args: P.args, **kwargs: P.kwargs) -> Sequence[Message]:
+        """Return the `Messages` from invoking this prompt."""
+        return promote_to_messages(self.fn(*args, **kwargs))
+
+    @overload
+    def __call__(
+        self: "Prompt[P, None]",
+        model: Model | ModelId,
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> Response: ...
+
+    @overload
+    def __call__(
+        self: "Prompt[P, FormattableT]",
+        model: Model | ModelId,
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> Response[FormattableT]: ...
+
+    def __call__(
+        self, model: Model | ModelId, *args: P.args, **kwargs: P.kwargs
+    ) -> Response | Response[FormattableT]:
+        """Generates a response using the provided model."""
+        return self.call(model, *args, **kwargs)
+
+    @overload
+    def call(
+        self: "Prompt[P, None]",
+        model: Model | ModelId,
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> Response: ...
+
+    @overload
+    def call(
+        self: "Prompt[P, FormattableT]",
+        model: Model | ModelId,
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> Response[FormattableT]: ...
+
+    def call(
+        self, model: Model | ModelId, *args: P.args, **kwargs: P.kwargs
+    ) -> Response | Response[FormattableT]:
+        """Generates a response using the provided model."""
+        if isinstance(model, str):
+            model = Model(model)
+        messages = self.messages(*args, **kwargs)
+        return model.call(messages, tools=self.toolkit, format=self.format)
+
+    @overload
+    def stream(
+        self: "Prompt[P, None]",
+        model: Model | ModelId,
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> StreamResponse: ...
+
+    @overload
+    def stream(
+        self: "Prompt[P, FormattableT]",
+        model: Model | ModelId,
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> StreamResponse[FormattableT]: ...
+
+    def stream(
+        self, model: Model | ModelId, *args: P.args, **kwargs: P.kwargs
+    ) -> StreamResponse | StreamResponse[FormattableT]:
+        """Generates a streaming response using the provided model."""
+        if isinstance(model, str):
+            model = Model(model)
+        messages = self.messages(*args, **kwargs)
+        return model.stream(messages, tools=self.toolkit, format=self.format)
+
+
+@dataclass
+class AsyncPrompt(BasePrompt[AsyncMessageTemplate[P]], Generic[P, FormattableT]):
+    """An async prompt that can be called with a model to generate a response.
+
+    Created by decorating an async `MessageTemplate` with `llm.prompt`. The decorated
+    async function becomes callable with a `Model` to generate LLM responses asynchronously.
+
+    An `AsyncPrompt` is essentially: async `MessageTemplate` + tools + format.
+    It can be invoked with a model: `await prompt(model, *args, **kwargs)`.
+    """
+
+    toolkit: AsyncToolkit
+    """The toolkit containing this prompt's async tools."""
+
+    format: FormatSpec[FormattableT] | None
+    """The response format for the generated response."""
+
+    async def messages(self, *args: P.args, **kwargs: P.kwargs) -> Sequence[Message]:
+        """Return the `Messages` from invoking this prompt."""
+        return promote_to_messages(await self.fn(*args, **kwargs))
+
+    @overload
+    async def __call__(
+        self: "AsyncPrompt[P, None]",
+        model: Model | ModelId,
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> AsyncResponse: ...
+
+    @overload
+    async def __call__(
+        self: "AsyncPrompt[P, FormattableT]",
+        model: Model | ModelId,
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> AsyncResponse[FormattableT]: ...
+
+    async def __call__(
+        self, model: Model | ModelId, *args: P.args, **kwargs: P.kwargs
+    ) -> AsyncResponse | AsyncResponse[FormattableT]:
+        """Generates a response using the provided model asynchronously."""
+        return await self.call(model, *args, **kwargs)
+
+    @overload
+    async def call(
+        self: "AsyncPrompt[P, None]",
+        model: Model | ModelId,
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> AsyncResponse: ...
+
+    @overload
+    async def call(
+        self: "AsyncPrompt[P, FormattableT]",
+        model: Model | ModelId,
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> AsyncResponse[FormattableT]: ...
+
+    async def call(
+        self, model: Model | ModelId, *args: P.args, **kwargs: P.kwargs
+    ) -> AsyncResponse | AsyncResponse[FormattableT]:
+        """Generates a response using the provided model asynchronously."""
+        if isinstance(model, str):
+            model = Model(model)
+        messages = await self.messages(*args, **kwargs)
+        return await model.call_async(messages, tools=self.toolkit, format=self.format)
+
+    @overload
+    async def stream(
+        self: "AsyncPrompt[P, None]",
+        model: Model | ModelId,
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> AsyncStreamResponse: ...
+
+    @overload
+    async def stream(
+        self: "AsyncPrompt[P, FormattableT]",
+        model: Model | ModelId,
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> AsyncStreamResponse[FormattableT]: ...
+
+    async def stream(
+        self, model: Model | ModelId, *args: P.args, **kwargs: P.kwargs
+    ) -> AsyncStreamResponse | AsyncStreamResponse[FormattableT]:
+        """Generates a streaming response using the provided model asynchronously."""
+        if isinstance(model, str):
+            model = Model(model)
+        messages = await self.messages(*args, **kwargs)
+        return await model.stream_async(
+            messages, tools=self.toolkit, format=self.format
+        )
+
+
+@dataclass
+class ContextPrompt(
+    BasePrompt[ContextMessageTemplate[P, DepsT]], Generic[P, DepsT, FormattableT]
+):
+    """A context-aware prompt that can be called with a model to generate a response.
+
+    Created by decorating a `ContextMessageTemplate` with `llm.prompt`. The decorated
+    function (with first parameter `'ctx'` of type `Context[DepsT]`) becomes callable
+    with a `Model` to generate LLM responses with context dependencies.
+
+    A `ContextPrompt` is essentially: `ContextMessageTemplate` + tools + format.
+    It can be invoked with a model: `prompt(model, ctx, *args, **kwargs)`.
+    """
+
+    toolkit: ContextToolkit[DepsT]
+    """The toolkit containing this prompt's context-aware tools."""
+
+    format: FormatSpec[FormattableT] | None
+    """The response format for the generated response."""
+
+    def messages(
+        self, ctx: Context[DepsT], *args: P.args, **kwargs: P.kwargs
+    ) -> Sequence[Message]:
+        """Return the `Messages` from invoking this prompt."""
+        return promote_to_messages(self.fn(ctx, *args, **kwargs))
+
+    @overload
+    def __call__(
+        self: "ContextPrompt[P, DepsT, None]",
+        model: Model | ModelId,
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> ContextResponse[DepsT, None]: ...
+
+    @overload
+    def __call__(
+        self: "ContextPrompt[P, DepsT, FormattableT]",
+        model: Model | ModelId,
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> ContextResponse[DepsT, FormattableT]: ...
+
+    def __call__(
+        self,
+        model: Model | ModelId,
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> ContextResponse[DepsT, None] | ContextResponse[DepsT, FormattableT]:
+        """Generates a response using the provided model."""
+        return self.call(model, ctx, *args, **kwargs)
+
+    @overload
+    def call(
+        self: "ContextPrompt[P, DepsT, None]",
+        model: Model | ModelId,
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> ContextResponse[DepsT, None]: ...
+
+    @overload
+    def call(
+        self: "ContextPrompt[P, DepsT, FormattableT]",
+        model: Model | ModelId,
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> ContextResponse[DepsT, FormattableT]: ...
+
+    def call(
+        self,
+        model: Model | ModelId,
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> ContextResponse[DepsT, None] | ContextResponse[DepsT, FormattableT]:
+        """Generates a response using the provided model."""
+        if isinstance(model, str):
+            model = Model(model)
+        messages = self.messages(ctx, *args, **kwargs)
+        return model.context_call(
+            messages, ctx=ctx, tools=self.toolkit, format=self.format
+        )
+
+    @overload
+    def stream(
+        self: "ContextPrompt[P, DepsT, None]",
+        model: Model | ModelId,
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> ContextStreamResponse[DepsT, None]: ...
+
+    @overload
+    def stream(
+        self: "ContextPrompt[P, DepsT, FormattableT]",
+        model: Model | ModelId,
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> ContextStreamResponse[DepsT, FormattableT]: ...
+
+    def stream(
+        self,
+        model: Model | ModelId,
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> (
+        ContextStreamResponse[DepsT, None] | ContextStreamResponse[DepsT, FormattableT]
+    ):
+        """Generates a streaming response using the provided model."""
+        if isinstance(model, str):
+            model = Model(model)
+        messages = self.messages(ctx, *args, **kwargs)
+        return model.context_stream(
+            messages, ctx=ctx, tools=self.toolkit, format=self.format
+        )
+
+
+@dataclass
+class AsyncContextPrompt(
+    BasePrompt[AsyncContextMessageTemplate[P, DepsT]], Generic[P, DepsT, FormattableT]
+):
+    """An async context-aware prompt that can be called with a model to generate a response.
+
+    Created by decorating an async `ContextMessageTemplate` with `llm.prompt`. The decorated
+    async function (with first parameter `'ctx'` of type `Context[DepsT]`) becomes callable
+    with a `Model` to generate LLM responses asynchronously with context dependencies.
+
+    An `AsyncContextPrompt` is essentially: async `ContextMessageTemplate` + tools + format.
+    It can be invoked with a model: `await prompt(model, ctx, *args, **kwargs)`.
+    """
+
+    toolkit: AsyncContextToolkit[DepsT]
+    """The toolkit containing this prompt's async context-aware tools."""
+
+    format: FormatSpec[FormattableT] | None
+    """The response format for the generated response."""
+
+    async def messages(
+        self, ctx: Context[DepsT], *args: P.args, **kwargs: P.kwargs
+    ) -> Sequence[Message]:
+        """Return the `Messages` from invoking this prompt."""
+        return promote_to_messages(await self.fn(ctx, *args, **kwargs))
+
+    @overload
+    async def __call__(
+        self: "AsyncContextPrompt[P, DepsT, None]",
+        model: Model | ModelId,
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> AsyncContextResponse[DepsT, None]: ...
+
+    @overload
+    async def __call__(
+        self: "AsyncContextPrompt[P, DepsT, FormattableT]",
+        model: Model | ModelId,
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> AsyncContextResponse[DepsT, FormattableT]: ...
+
+    async def __call__(
+        self,
+        model: Model | ModelId,
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> AsyncContextResponse[DepsT, None] | AsyncContextResponse[DepsT, FormattableT]:
+        """Generates a response using the provided model asynchronously."""
+        return await self.call(model, ctx, *args, **kwargs)
+
+    @overload
+    async def call(
+        self: "AsyncContextPrompt[P, DepsT, None]",
+        model: Model | ModelId,
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> AsyncContextResponse[DepsT, None]: ...
+
+    @overload
+    async def call(
+        self: "AsyncContextPrompt[P, DepsT, FormattableT]",
+        model: Model | ModelId,
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> AsyncContextResponse[DepsT, FormattableT]: ...
+
+    async def call(
+        self,
+        model: Model | ModelId,
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> AsyncContextResponse[DepsT, None] | AsyncContextResponse[DepsT, FormattableT]:
+        """Generates a response using the provided model asynchronously."""
+        if isinstance(model, str):
+            model = Model(model)
+        messages = await self.messages(ctx, *args, **kwargs)
+        return await model.context_call_async(
+            messages, ctx=ctx, tools=self.toolkit, format=self.format
+        )
+
+    @overload
+    async def stream(
+        self: "AsyncContextPrompt[P, DepsT, None]",
+        model: Model | ModelId,
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> AsyncContextStreamResponse[DepsT, None]: ...
+
+    @overload
+    async def stream(
+        self: "AsyncContextPrompt[P, DepsT, FormattableT]",
+        model: Model | ModelId,
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> AsyncContextStreamResponse[DepsT, FormattableT]: ...
+
+    async def stream(
+        self,
+        model: Model | ModelId,
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> (
+        AsyncContextStreamResponse[DepsT, None]
+        | AsyncContextStreamResponse[DepsT, FormattableT]
+    ):
+        """Generates a streaming response using the provided model asynchronously."""
+        if isinstance(model, str):
+            model = Model(model)
+        messages = await self.messages(ctx, *args, **kwargs)
+        return await model.context_stream_async(
+            messages, ctx=ctx, tools=self.toolkit, format=self.format
+        )

mirascope/llm/prompts/protocols.py

@@ -0,0 +1,65 @@
+"""Types for prompt functions."""
+
+from collections.abc import Sequence
+from typing import Protocol
+
+from ..context import Context, DepsT
+from ..messages import Message, UserContent
+from ..types import P
+
+
+class MessageTemplate(Protocol[P]):
+    """Protocol for a prompt function that returns `UserContent` or `Sequence[Message]`.
+
+    A `MessageTemplate` is a raw function that returns prompt content. It can be
+    converted by the `llm.prompt` decorator into a `Prompt` (callable with a `Model`),
+    or by the `llm.call` decorator into a `Call` (`Prompt` + `Model`).
+    """
+
+    def __call__(
+        self, *args: P.args, **kwargs: P.kwargs
+    ) -> UserContent | Sequence[Message]: ...
+
+
+class AsyncMessageTemplate(Protocol[P]):
+    """Protocol for an async prompt function that returns `UserContent` or `Sequence[Message]`.
+
+    An async `MessageTemplate` that can be converted by the `llm.prompt` decorator
+    into an `AsyncPrompt`, or by the `llm.call` decorator into an `AsyncCall`.
+    """
+
+    async def __call__(
+        self, *args: P.args, **kwargs: P.kwargs
+    ) -> UserContent | Sequence[Message]: ...
+
+
+class ContextMessageTemplate(Protocol[P, DepsT]):
+    """Protocol for a context-aware prompt function that returns `UserContent` or `Sequence[Message]`.
+
+    A `MessageTemplate` with a first parameter named `'ctx'` of type `Context[DepsT]`.
+    Can be converted by the `llm.prompt` decorator into a `ContextPrompt`, or by
+    the `llm.call` decorator into a `ContextCall`.
+    """
+
+    def __call__(
+        self,
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> UserContent | Sequence[Message]: ...
+
+
+class AsyncContextMessageTemplate(Protocol[P, DepsT]):
+    """Protocol for an async context-aware prompt function that returns `UserContent` or `Sequence[Message]`.
+
+    An async `MessageTemplate` with a first parameter named `'ctx'` of type `Context[DepsT]`.
+    Can be converted by the `llm.prompt` decorator into an `AsyncContextPrompt`, or by
+    the `llm.call` decorator into an `AsyncContextCall`.
+    """
+
+    async def __call__(
+        self,
+        ctx: Context[DepsT],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> UserContent | Sequence[Message]: ...

mirascope/llm/providers/__init__.py

@@ -0,0 +1,65 @@
+"""Interfaces for LLM providers."""
+
+from ..._stubs import stub_module_if_missing
+
+# Stub modules for missing optional dependencies BEFORE importing
+# This must happen before any imports from these modules
+# Note: We only stub top-level provider modules, not their submodules.
+# The _StubModule will automatically handle nested attribute access.
+stub_module_if_missing("mirascope.llm.providers.anthropic", "anthropic")
+stub_module_if_missing("mirascope.llm.providers.google", "google")
+stub_module_if_missing("mirascope.llm.providers.mlx", "mlx")
+stub_module_if_missing("mirascope.llm.providers.openai", "openai")
+stub_module_if_missing("mirascope.llm.providers.openrouter", "openai")
+stub_module_if_missing("mirascope.llm.providers.together", "openai")
+stub_module_if_missing("mirascope.llm.providers.ollama", "openai")
+
+# Now imports work regardless of which packages are installed
+# ruff: noqa: E402
+from .anthropic import (
+    AnthropicModelId,
+    AnthropicProvider,
+)
+from .base import BaseProvider, Provider
+from .google import GoogleModelId, GoogleProvider
+from .mirascope import MirascopeProvider
+from .mlx import MLXModelId, MLXProvider
+from .model_id import ModelId
+from .ollama import OllamaProvider
+from .openai import (
+    OpenAIModelId,
+    OpenAIProvider,
+)
+from .openai.completions import BaseOpenAICompletionsProvider
+from .openrouter import OpenRouterProvider
+from .provider_id import KNOWN_PROVIDER_IDS, ProviderId
+from .provider_registry import (
+    get_provider_for_model,
+    register_provider,
+    reset_provider_registry,
+)
+from .together import TogetherProvider
+
+__all__ = [
+    "KNOWN_PROVIDER_IDS",
+    "AnthropicModelId",
+    "AnthropicProvider",
+    "BaseOpenAICompletionsProvider",
+    "BaseProvider",
+    "GoogleModelId",
+    "GoogleProvider",
+    "MLXModelId",
+    "MLXProvider",
+    "MirascopeProvider",
+    "ModelId",
+    "OllamaProvider",
+    "OpenAIModelId",
+    "OpenAIProvider",
+    "OpenRouterProvider",
+    "Provider",
+    "ProviderId",
+    "TogetherProvider",
+    "get_provider_for_model",
+    "register_provider",
+    "reset_provider_registry",
+]

mirascope/llm/providers/anthropic/__init__.py

@@ -0,0 +1,11 @@
+"""Anthropic client implementation."""
+
+from .beta_provider import AnthropicBetaProvider
+from .model_id import AnthropicModelId
+from .provider import AnthropicProvider
+
+__all__ = [
+    "AnthropicBetaProvider",
+    "AnthropicModelId",
+    "AnthropicProvider",
+]

mirascope/llm/providers/anthropic/_utils/__init__.py

@@ -0,0 +1,27 @@
+"""Shared Anthropic utilities."""
+
+from ...base._utils import get_include_thoughts
+from .decode import decode_async_stream, decode_response, decode_stream
+from .encode import (
+    DEFAULT_FORMAT_MODE,
+    DEFAULT_MAX_TOKENS,
+    AnthropicImageMimeType,
+    encode_image_mime_type,
+    encode_request,
+    process_params,
+)
+from .errors import ANTHROPIC_ERROR_MAP
+
+__all__ = [
+    "ANTHROPIC_ERROR_MAP",
+    "DEFAULT_FORMAT_MODE",
+    "DEFAULT_MAX_TOKENS",
+    "AnthropicImageMimeType",
+    "decode_async_stream",
+    "decode_response",
+    "decode_stream",
+    "encode_image_mime_type",
+    "encode_request",
+    "get_include_thoughts",
+    "process_params",
+]