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

mirascope/llm/calls/decorator.py

@@ -0,0 +1,268 @@
+"""The `llm.call` decorator for turning `Prompt` functions into LLM calls."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Generic, cast, overload
+from typing_extensions import Unpack
+
+from ..context import DepsT
+from ..formatting import FormatSpec, FormattableT
+from ..models import Model
+from ..prompts import (
+    AsyncContextMessageTemplate,
+    AsyncContextPrompt,
+    AsyncMessageTemplate,
+    AsyncPrompt,
+    ContextMessageTemplate,
+    ContextPrompt,
+    MessageTemplate,
+    Prompt,
+    _utils,
+)
+from ..providers import ModelId
+from ..tools import (
+    AsyncContextTool,
+    AsyncContextToolkit,
+    AsyncTool,
+    AsyncToolkit,
+    ContextTool,
+    ContextToolkit,
+    ProviderTool,
+    Tool,
+    Toolkit,
+    ToolT,
+)
+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`
+    """
+
+    model: Model
+    """The default model to use with this call. May be overridden."""
+
+    tools: Sequence[ToolT | ProviderTool] | None
+    """The tools that are included in the prompt, if any."""
+
+    format: FormatSpec[FormattableT] | None
+    """The structured output format off the prompt, if any."""
+
+    @overload
+    def __call__(
+        self: CallDecorator[AsyncTool | AsyncContextTool[DepsT], FormattableT],
+        fn: AsyncContextMessageTemplate[P, DepsT],
+    ) -> AsyncContextCall[P, DepsT, FormattableT]:
+        """Decorate an async context prompt into an AsyncContextCall."""
+        ...
+
+    @overload
+    def __call__(
+        self: CallDecorator[Tool | ContextTool[DepsT], FormattableT],
+        fn: ContextMessageTemplate[P, DepsT],
+    ) -> ContextCall[P, DepsT, FormattableT]:
+        """Decorate a context prompt into a ContextCall."""
+        ...
+
+    @overload
+    def __call__(
+        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: MessageTemplate[P]
+    ) -> Call[P, FormattableT]:
+        """Decorate a prompt into a Call."""
+        ...
+
+    def __call__(
+        self,
+        fn: ContextMessageTemplate[P, DepsT]
+        | AsyncContextMessageTemplate[P, DepsT]
+        | MessageTemplate[P]
+        | AsyncMessageTemplate[P],
+    ) -> (
+        ContextCall[P, DepsT, FormattableT]
+        | AsyncContextCall[P, DepsT, FormattableT]
+        | Call[P, 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)
+
+        if is_context and is_async:
+            tools = cast(
+                Sequence[AsyncTool | AsyncContextTool[DepsT] | ProviderTool] | None,
+                self.tools,
+            )
+            prompt = AsyncContextPrompt(
+                fn=fn,
+                toolkit=AsyncContextToolkit(tools=tools),
+                format=self.format,
+            )
+            return AsyncContextCall(
+                prompt=prompt,
+                default_model=self.model,
+            )
+        elif is_context:
+            tools = cast(
+                Sequence[Tool | ContextTool[DepsT] | ProviderTool] | None, self.tools
+            )
+            prompt = ContextPrompt(
+                fn=fn,
+                toolkit=ContextToolkit(tools=tools),
+                format=self.format,
+            )
+            return ContextCall(
+                prompt=prompt,
+                default_model=self.model,
+            )
+        elif is_async:
+            tools = cast(Sequence[AsyncTool | ProviderTool] | None, self.tools)
+            prompt = AsyncPrompt(
+                fn=fn, toolkit=AsyncToolkit(tools=tools), format=self.format
+            )
+            return AsyncCall(
+                prompt=prompt,
+                default_model=self.model,
+            )
+        else:
+            tools = cast(Sequence[Tool | ProviderTool] | None, self.tools)
+            prompt = Prompt(fn=fn, toolkit=Toolkit(tools=tools), format=self.format)
+            return Call(
+                prompt=prompt,
+                default_model=self.model,
+            )
+
+
+@overload
+def call(
+    model: ModelId,
+    *,
+    tools: Sequence[ToolT | ProviderTool] | None = None,
+    format: FormatSpec[FormattableT] | None = None,
+    **params: Unpack[Params],
+) -> CallDecorator[ToolT, FormattableT]:
+    """Decorator for converting prompt functions into LLM calls.
+
+    This overload accepts a model ID string and allows additional params.
+    """
+    ...
+
+
+@overload
+def call(
+    model: Model,
+    *,
+    tools: Sequence[ToolT | ProviderTool] | None = None,
+    format: FormatSpec[FormattableT] | None = None,
+) -> CallDecorator[ToolT, FormattableT]:
+    """Decorator for converting prompt functions into LLM calls.
+
+    This overload accepts a Model instance and does not allow additional params.
+    """
+    ...
+
+
+def call(
+    model: ModelId | Model,
+    *,
+    tools: Sequence[ToolT | ProviderTool] | None = None,
+    format: FormatSpec[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`)
+
+    Example:
+
+        Regular call:
+        ```python
+        from mirascope import llm
+
+        @llm.call("openai/gpt-4")
+        def recommend_book(genre: str):
+            return f"Please recommend a book in {genre}."
+
+        response: llm.Response = recommend_book("fantasy")
+        print(response.pretty())
+        ```
+
+    Example:
+
+        Context call:
+        ```python
+        from dataclasses import dataclass
+        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())
+        ```
+    """
+    if isinstance(model, str):
+        model = Model(model, **params)
+    return CallDecorator(model=model, tools=tools, format=format)

mirascope/llm/content/__init__.py

@@ -0,0 +1,71 @@
+"""The `llm.messages.content` module."""
+
+from typing import TypeAlias
+
+from ..types import Jsonable
+from .audio import Audio, Base64AudioSource
+from .document import (
+    Base64DocumentSource,
+    Document,
+    TextDocumentSource,
+    URLDocumentSource,
+)
+from .image import Base64ImageSource, Image, ImageMimeType, URLImageSource
+from .text import Text, TextChunk, TextEndChunk, TextStartChunk
+from .thought import Thought, ThoughtChunk, ThoughtEndChunk, ThoughtStartChunk
+from .tool_call import ToolCall, ToolCallChunk, ToolCallEndChunk, ToolCallStartChunk
+from .tool_output import ToolOutput
+
+ContentPart: TypeAlias = (
+    Text | Image | Audio | Document | ToolOutput[Jsonable] | ToolCall | Thought
+)
+"""Content parts that may be included in a Message."""
+
+UserContentPart: TypeAlias = Text | Image | Audio | Document | ToolOutput[Jsonable]
+"""Content parts that can be included in a UserMessage."""
+
+AssistantContentPart: TypeAlias = Text | ToolCall | Thought
+"""Content parts that can be included in an AssistantMessage."""
+
+AssistantContentChunk: TypeAlias = (
+    TextStartChunk
+    | TextChunk
+    | TextEndChunk
+    | ThoughtStartChunk
+    | ThoughtChunk
+    | ThoughtEndChunk
+    | ToolCallStartChunk
+    | ToolCallChunk
+    | ToolCallEndChunk
+)
+"""Chunks of assistant content that may be streamed as generated by the LLM."""
+
+__all__ = [
+    "AssistantContentChunk",
+    "AssistantContentPart",
+    "Audio",
+    "Base64AudioSource",
+    "Base64DocumentSource",
+    "Base64ImageSource",
+    "ContentPart",
+    "Document",
+    "Image",
+    "ImageMimeType",
+    "Text",
+    "TextChunk",
+    "TextDocumentSource",
+    "TextEndChunk",
+    "TextStartChunk",
+    "Thought",
+    "ThoughtChunk",
+    "ThoughtEndChunk",
+    "ThoughtStartChunk",
+    "ToolCall",
+    "ToolCallChunk",
+    "ToolCallEndChunk",
+    "ToolCallStartChunk",
+    "ToolOutput",
+    "URLDocumentSource",
+    "URLImageSource",
+    "UserContentPart",
+]

mirascope/llm/content/audio.py

@@ -0,0 +1,173 @@
+"""The `Audio` content class."""
+
+import base64
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, get_args
+
+import httpx
+
+AudioMimeType = Literal[
+    "audio/wav",
+    "audio/mp3",
+    "audio/aiff",
+    "audio/aac",
+    "audio/ogg",
+    "audio/flac",
+]  # TODO: add e2e tests for every supported type
+
+MIME_TYPES = get_args(AudioMimeType)
+
+# Maximum audio size in bytes (25MB)
+MAX_AUDIO_SIZE = 25 * 1024 * 1024
+
+
+def infer_audio_type(audio_data: bytes) -> AudioMimeType:
+    """Get the MIME type of an audio file from its raw bytes.
+
+    Raises:
+        ValueError: If the audio type cannot be determined or data is too small
+    """
+    if len(audio_data) < 12:
+        raise ValueError("Audio data too small to determine type (minimum 12 bytes)")
+
+    if audio_data.startswith(b"RIFF") and audio_data[8:12] == b"WAVE":
+        return "audio/wav"
+    elif audio_data.startswith(b"ID3") or audio_data.startswith(b"\xff\xfb"):
+        return "audio/mp3"
+    elif audio_data.startswith(b"FORM") and audio_data[8:12] == b"AIFF":
+        return "audio/aiff"
+    elif audio_data.startswith(b"\xff\xf1") or audio_data.startswith(b"\xff\xf9"):
+        return "audio/aac"
+    elif audio_data.startswith(b"OggS"):
+        return "audio/ogg"
+    elif audio_data.startswith(b"fLaC"):
+        return "audio/flac"
+    raise ValueError("Unsupported audio type")
+
+
+@dataclass(kw_only=True)
+class Base64AudioSource:
+    """Audio data represented as a base64 encoded string."""
+
+    type: Literal["base64_audio_source"]
+
+    data: str
+    """The audio data, as a base64 encoded string."""
+
+    mime_type: AudioMimeType
+    """The mime type of the audio (e.g. audio/mp3)."""
+
+
+def _process_audio_bytes(data: bytes, max_size: int) -> Base64AudioSource:
+    """Validate and process audio bytes into a Base64AudioSource.
+
+    Args:
+        data: Raw audio bytes
+        max_size: Maximum allowed size in bytes
+
+    Returns:
+        A Base64AudioSource with validated and encoded data
+
+    Raises:
+        ValueError: If data size exceeds max_size
+    """
+    size = len(data)
+    if size > max_size:
+        raise ValueError(
+            f"Audio size ({size} bytes) exceeds maximum allowed size ({max_size} bytes)"
+        )
+
+    mime_type = infer_audio_type(data)
+    encoded_data = base64.b64encode(data).decode("utf-8")
+    return Base64AudioSource(
+        type="base64_audio_source",
+        data=encoded_data,
+        mime_type=mime_type,
+    )
+
+
+@dataclass(kw_only=True)
+class Audio:
+    """Audio content for a message.
+
+    Audio can be included in messages for voice or sound-based interactions.
+    """
+
+    type: Literal["audio"] = "audio"
+
+    source: Base64AudioSource
+
+    @classmethod
+    def download(cls, url: str, *, max_size: int = MAX_AUDIO_SIZE) -> "Audio":
+        """Download and encode an audio file from a URL.
+
+        Args:
+            url: The URL of the audio file to download
+            max_size: Maximum allowed audio size in bytes (default: 25MB)
+
+        Returns:
+            An `Audio` with a `Base64AudioSource`
+
+        Raises:
+            ValueError: If the downloaded audio exceeds max_size
+        """
+        response = httpx.get(url, follow_redirects=True)
+        response.raise_for_status()
+        return cls(source=_process_audio_bytes(response.content, max_size))
+
+    @classmethod
+    async def download_async(
+        cls, url: str, *, max_size: int = MAX_AUDIO_SIZE
+    ) -> "Audio":
+        """Asynchronously download and encode an audio file from a URL.
+
+        Args:
+            url: The URL of the audio file to download
+            max_size: Maximum allowed audio size in bytes (default: 25MB)
+
+        Returns:
+            An `Audio` with a `Base64AudioSource`
+
+        Raises:
+            ValueError: If the downloaded audio exceeds max_size
+        """
+        async with httpx.AsyncClient() as client:
+            response = await client.get(url, follow_redirects=True)
+            response.raise_for_status()
+            return cls(source=_process_audio_bytes(response.content, max_size))
+
+    @classmethod
+    def from_file(cls, file_path: str, *, max_size: int = MAX_AUDIO_SIZE) -> "Audio":
+        """Create an `Audio` from a file path.
+
+        Args:
+            file_path: Path to the audio file
+            max_size: Maximum allowed audio size in bytes (default: 25MB)
+
+        Raises:
+            FileNotFoundError: If the file does not exist
+            ValueError: If the file size exceeds max_size
+        """
+        path = Path(file_path)
+        file_size = path.stat().st_size
+        if file_size > max_size:
+            raise ValueError(
+                f"Audio file size ({file_size} bytes) exceeds maximum allowed size ({max_size} bytes)"
+            )
+        with open(path, "rb") as f:
+            audio_bytes = f.read()
+        return cls(source=_process_audio_bytes(audio_bytes, max_size))
+
+    @classmethod
+    def from_bytes(cls, data: bytes, *, max_size: int = MAX_AUDIO_SIZE) -> "Audio":
+        """Create an `Audio` from raw bytes.
+
+        Args:
+            data: Raw audio bytes
+            max_size: Maximum allowed audio size in bytes (default: 25MB)
+
+        Raises:
+            ValueError: If the data size exceeds max_size
+        """
+        return cls(source=_process_audio_bytes(data, max_size))

mirascope/llm/content/document.py

@@ -0,0 +1,94 @@
+"""The `Document` content class."""
+
+from dataclasses import dataclass
+from typing import Literal
+
+DocumentTextMimeType = Literal[
+    "application/json",
+    "text/plain",
+    "application/x-javascript",
+    "text/javascript",
+    "application/x-python",
+    "text/x-python",
+    "text/html",
+    "text/css",
+    "text/xml",
+    "text/rtf",
+]
+"""Mime type for documents encoded as plain text."""
+
+DocumentBase64MimeType = Literal["application/pdf"]
+"""Mime type for documents encoded as base64 strings."""
+
+
+@dataclass(kw_only=True)
+class Base64DocumentSource:
+    """Document data represented as a base64 encoded string."""
+
+    type: Literal["base64_document_source"]
+
+    data: str
+    """The document data, as a base64 encoded string."""
+
+    media_type: DocumentBase64MimeType
+    """The media type of the document (e.g. application/pdf)."""
+
+
+@dataclass(kw_only=True)
+class TextDocumentSource:
+    """Plain text document data."""
+
+    type: Literal["text_document_source"]
+
+    data: str
+    """The document data, as plain text."""
+
+    media_type: DocumentTextMimeType
+    """The media type of the document (e.g. text/plain, text/csv)."""
+
+
+@dataclass(kw_only=True)
+class URLDocumentSource:
+    """Document data referenced via external URL."""
+
+    type: Literal["url_document_source"]
+
+    url: str
+    """The url of the document (e.g. https://example.com/paper.pdf)."""
+
+
+@dataclass(kw_only=True)
+class Document:
+    """Document content for a message.
+
+    Documents (like PDFs) can be included for the model to analyze or reference.
+    """
+
+    type: Literal["document"] = "document"
+
+    source: Base64DocumentSource | TextDocumentSource | URLDocumentSource
+
+    @classmethod
+    def from_url(cls, url: str, *, download: bool = False) -> "Document":
+        """Create a `Document` from a URL."""
+        raise NotImplementedError
+
+    @classmethod
+    def from_file(
+        cls,
+        file_path: str,
+        *,
+        mime_type: DocumentTextMimeType | DocumentBase64MimeType | None,
+    ) -> "Document":
+        """Create a `Document` from a file path."""
+        raise NotImplementedError
+
+    @classmethod
+    def from_bytes(
+        cls,
+        data: bytes,
+        *,
+        mime_type: DocumentTextMimeType | DocumentBase64MimeType | None,
+    ) -> "Document":
+        """Create a `Document` from raw bytes."""
+        raise NotImplementedError