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

mirascope/llm/content/image.py

@@ -0,0 +1,206 @@
+"""The `Image` content class."""
+
+import base64
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, get_args
+
+import httpx
+
+ImageMimeType = Literal[
+    "image/png",
+    "image/jpeg",
+    "image/webp",
+    "image/gif",
+    "image/heic",
+    "image/heif",
+]  # TODO: add e2e tests for every supported type
+
+MIME_TYPES = get_args(ImageMimeType)
+
+# Maximum image size in bytes (20MB)
+MAX_IMAGE_SIZE = 20 * 1024 * 1024
+
+
+def infer_image_type(image_data: bytes) -> ImageMimeType:
+    """Get the MIME type of an image from its raw bytes.
+
+    Raises:
+        ValueError: If the image type cannot be determined or data is too small
+    """
+    if len(image_data) < 12:
+        raise ValueError("Image data too small to determine type (minimum 12 bytes)")
+
+    if image_data.startswith(b"\xff\xd8\xff"):
+        return "image/jpeg"
+    elif image_data.startswith(b"\x89PNG\r\n\x1a\n"):
+        return "image/png"
+    elif image_data.startswith(b"GIF87a") or image_data.startswith(b"GIF89a"):
+        return "image/gif"
+    elif image_data.startswith(b"RIFF") and image_data[8:12] == b"WEBP":
+        return "image/webp"
+    elif image_data[4:12] in (
+        b"ftypmif1",
+        b"ftypmsf1",
+        b"ftypheic",
+        b"ftypheix",
+        b"ftyphevc",
+        b"ftyphevx",
+    ):
+        subtype = image_data[8:12]
+        if subtype in (b"heic", b"heix"):
+            return "image/heic"
+        elif subtype in (b"mif1", b"msf1", b"hevc", b"hevx"):
+            return "image/heif"
+    raise ValueError("Unsupported image type")
+
+
+@dataclass(kw_only=True)
+class Base64ImageSource:
+    """Image data represented as a base64 encoded string."""
+
+    type: Literal["base64_image_source"]
+
+    data: str
+    """The image data, as a base64 encoded string."""
+
+    mime_type: ImageMimeType
+    """The mime type of the image (e.g. image/png)."""
+
+
+def _process_image_bytes(data: bytes, max_size: int) -> Base64ImageSource:
+    """Validate and process image bytes into a Base64ImageSource.
+
+    Args:
+        data: Raw image bytes
+        max_size: Maximum allowed size in bytes
+
+    Returns:
+        A Base64ImageSource with validated and encoded data
+
+    Raises:
+        ValueError: If data size exceeds max_size
+    """
+    size = len(data)
+    if size > max_size:
+        raise ValueError(
+            f"Image size ({size} bytes) exceeds maximum allowed size ({max_size} bytes)"
+        )
+
+    mime_type = infer_image_type(data)
+    encoded_data = base64.b64encode(data).decode("utf-8")
+    return Base64ImageSource(
+        type="base64_image_source",
+        data=encoded_data,
+        mime_type=mime_type,
+    )
+
+
+@dataclass(kw_only=True)
+class URLImageSource:
+    """Image data referenced via external URL."""
+
+    type: Literal["url_image_source"]
+
+    url: str
+    """The url of the image (e.g. https://example.com/sazed.png)."""
+
+
+@dataclass(kw_only=True)
+class Image:
+    """Image content for a message.
+
+    Images can be included in messages to provide visual context. This can be
+    used for both input (e.g., user uploading an image) and output (e.g., model
+    generating an image).
+    """
+
+    type: Literal["image"] = "image"
+
+    source: Base64ImageSource | URLImageSource
+
+    @classmethod
+    def from_url(cls, url: str) -> "Image":
+        """Create an `Image` reference from a URL, without downloading it.
+
+        Args:
+            url: The URL of the image
+
+        Returns:
+            An `Image` with a `URLImageSource`
+        """
+        return cls(source=URLImageSource(type="url_image_source", url=url))
+
+    @classmethod
+    def download(cls, url: str, *, max_size: int = MAX_IMAGE_SIZE) -> "Image":
+        """Download and encode an image from a URL.
+
+        Args:
+            url: The URL of the image to download
+            max_size: Maximum allowed image size in bytes (default: 20MB)
+
+        Returns:
+            An `Image` with a `Base64ImageSource`
+
+        Raises:
+            ValueError: If the downloaded image exceeds max_size
+        """
+        response = httpx.get(url, follow_redirects=True)
+        response.raise_for_status()
+        return cls(source=_process_image_bytes(response.content, max_size))
+
+    @classmethod
+    async def download_async(
+        cls, url: str, *, max_size: int = MAX_IMAGE_SIZE
+    ) -> "Image":
+        """Asynchronously download and encode an image from a URL.
+
+        Args:
+            url: The URL of the image to download
+            max_size: Maximum allowed image size in bytes (default: 20MB)
+
+        Returns:
+            An `Image` with a `Base64ImageSource`
+
+        Raises:
+            ValueError: If the downloaded image 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_image_bytes(response.content, max_size))
+
+    @classmethod
+    def from_file(cls, file_path: str, *, max_size: int = MAX_IMAGE_SIZE) -> "Image":
+        """Create an `Image` from a file path.
+
+        Args:
+            file_path: Path to the image file
+            max_size: Maximum allowed image size in bytes (default: 20MB)
+
+        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"Image file size ({file_size} bytes) exceeds maximum allowed size ({max_size} bytes)"
+            )
+        with open(path, "rb") as f:
+            image_bytes = f.read()
+        return cls(source=_process_image_bytes(image_bytes, max_size))
+
+    @classmethod
+    def from_bytes(cls, data: bytes, *, max_size: int = MAX_IMAGE_SIZE) -> "Image":
+        """Create an `Image` from raw bytes.
+
+        Args:
+            data: Raw image bytes
+            max_size: Maximum allowed image size in bytes (default: 20MB)
+
+        Raises:
+            ValueError: If the data size exceeds max_size
+        """
+        return cls(source=_process_image_bytes(data, max_size))

mirascope/llm/content/text.py

@@ -0,0 +1,47 @@
+"""The `Text` content class."""
+
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass(kw_only=True)
+class Text:
+    """Text content for a message."""
+
+    type: Literal["text"] = "text"
+
+    text: str
+    """The text content."""
+
+
+@dataclass(kw_only=True)
+class TextStartChunk:
+    """Represents the start of a text chunk stream."""
+
+    type: Literal["text_start_chunk"] = "text_start_chunk"
+
+    content_type: Literal["text"] = "text"
+    """The type of content reconstructed by this chunk."""
+
+
+@dataclass(kw_only=True)
+class TextChunk:
+    """Represents an incremental text chunk in a stream."""
+
+    type: Literal["text_chunk"] = "text_chunk"
+
+    content_type: Literal["text"] = "text"
+    """The type of content reconstructed by this chunk."""
+
+    delta: str
+    """The incremental text added in this chunk."""
+
+
+@dataclass(kw_only=True)
+class TextEndChunk:
+    """Represents the end of a text chunk stream."""
+
+    type: Literal["text_end_chunk"] = "text_end_chunk"
+
+    content_type: Literal["text"] = "text"
+    """The type of content reconstructed by this chunk."""

mirascope/llm/content/thought.py

@@ -0,0 +1,58 @@
+"""The `Thought` content class and its streaming chunks.
+
+The `Thought` is an interpretable / readable summary of the models' reasoning
+process. This may be a summary generated by a summarizer model that is distinct from
+the reasoning model, or for some models it may be the raw output of the model's thinking
+process.
+"""
+
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass(kw_only=True)
+class Thought:
+    """Thinking content for a message.
+
+    Represents the thinking or thought process of the assistant. These generally are
+    summaries of the model's reasoning process, rather than the direct reasoning tokens,
+    although this behavior is model and provider specific.
+    """
+
+    type: Literal["thought"] = "thought"
+
+    thought: str
+    """The thoughts or reasoning of the assistant."""
+
+
+@dataclass(kw_only=True)
+class ThoughtStartChunk:
+    """Represents the start of a thought chunk stream."""
+
+    type: Literal["thought_start_chunk"] = "thought_start_chunk"
+
+    content_type: Literal["thought"] = "thought"
+    """The type of content reconstructed by this chunk."""
+
+
+@dataclass(kw_only=True)
+class ThoughtChunk:
+    """Represents an incremental thought chunk in a stream."""
+
+    type: Literal["thought_chunk"] = "thought_chunk"
+
+    content_type: Literal["thought"] = "thought"
+    """The type of content reconstructed by this chunk."""
+
+    delta: str
+    """The incremental thoughts added in this chunk."""
+
+
+@dataclass(kw_only=True)
+class ThoughtEndChunk:
+    """Represents the end of a thought chunk stream."""
+
+    type: Literal["thought_end_chunk"] = "thought_end_chunk"
+
+    content_type: Literal["thought"] = "thought"
+    """The type of content reconstructed by this chunk."""

mirascope/llm/content/tool_call.py

@@ -0,0 +1,69 @@
+"""The `ToolCall` content class."""
+
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass(kw_only=True)
+class ToolCall:
+    """Tool call content for a message.
+
+    Represents a request from the assistant to call a tool. This is part of
+    an assistant message's content.
+    """
+
+    type: Literal["tool_call"] = "tool_call"
+
+    id: str
+    """A unique identifier for this tool call."""
+
+    name: str
+    """The name of the tool to call."""
+
+    args: str
+    """The arguments to pass to the tool, stored as stringified json."""
+
+
+@dataclass(kw_only=True)
+class ToolCallStartChunk:
+    """Represents the start of a tool call chunk stream."""
+
+    type: Literal["tool_call_start_chunk"] = "tool_call_start_chunk"
+
+    content_type: Literal["tool_call"] = "tool_call"
+    """The type of content reconstructed by this chunk."""
+
+    id: str
+    """A unique identifier for this tool call."""
+
+    name: str
+    """The name of the tool to call."""
+
+
+@dataclass(kw_only=True)
+class ToolCallChunk:
+    """Represents an incremental tool call chunk in a stream."""
+
+    type: Literal["tool_call_chunk"] = "tool_call_chunk"
+
+    content_type: Literal["tool_call"] = "tool_call"
+    """The type of content reconstructed by this chunk."""
+
+    id: str
+    """A unique identifier for this tool call."""
+
+    delta: str
+    """The incremental json args added in this chunk."""
+
+
+@dataclass(kw_only=True)
+class ToolCallEndChunk:
+    """Represents the end of a tool call chunk stream."""
+
+    type: Literal["tool_call_end_chunk"] = "tool_call_end_chunk"
+
+    content_type: Literal["tool_call"] = "tool_call"
+    """The type of content reconstructed by this chunk."""
+
+    id: str
+    """A unique identifier for this tool call."""

mirascope/llm/content/tool_output.py

@@ -0,0 +1,43 @@
+"""The `ToolOutput` content class."""
+
+from dataclasses import dataclass
+from typing import Generic, Literal, cast
+
+from ..exceptions import ToolError
+from ..types import JsonableCovariantT
+
+
+@dataclass(kw_only=True)
+class ToolOutput(Generic[JsonableCovariantT]):
+    """Tool output content for a message.
+
+    Represents the output from a tool call. This is part of a user message's
+    content, typically following a tool call from the assistant.
+    """
+
+    type: Literal["tool_output"] = "tool_output"
+
+    id: str
+    """The ID of the tool call that this output is for."""
+
+    name: str
+    """The name of the tool that created this output."""
+
+    result: JsonableCovariantT | str
+    """The result of calling the tool.
+    
+    If the tool executed successfully, this will be the tool output.
+    If the tool errored, this will be the error message, as a string.
+    
+    In either case, the result should be passed back to the LLM (so it can
+    either process the output, or re-try with awareness of the error.)
+    """
+
+    error: ToolError | None = None
+    """The error from calling the tool, if any."""
+
+    @property
+    def output(self) -> JsonableCovariantT:
+        if self.error is not None:
+            raise self.error
+        return cast(JsonableCovariantT, self.result)

mirascope/llm/context/__init__.py

@@ -0,0 +1,6 @@
+"""The Context module for providing context to LLM calls during generation."""
+
+from . import _utils
+from .context import Context, DepsT
+
+__all__ = ["Context", "DepsT", "_utils"]

mirascope/llm/context/_utils.py

@@ -0,0 +1,41 @@
+import inspect
+import typing
+from collections.abc import Callable
+from typing import Any, get_origin
+
+from .context import Context
+
+
+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`.
+    Skips the first argument if it is `self` or `cls`.
+    """
+    sig = inspect.signature(fn)
+    params = list(sig.parameters.values())
+    if not params:
+        return False
+
+    if params[0].name in ("self", "cls") and len(params) > 1:
+        first_param = params[1]
+    else:
+        first_param = params[0]
+
+    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 type_is_context or subclass_of_context

mirascope/llm/context/context.py

@@ -0,0 +1,24 @@
+"""Context for LLM calls."""
+
+from dataclasses import dataclass
+from typing import Generic
+from typing_extensions import TypeVar
+
+DepsT = TypeVar("DepsT")
+"""Type variable for dependency injection in `llm.Context`.
+
+This TypeVar is used throughout the LLM module to represent the type of
+dependencies that are present in `llm.Context`. 
+"""
+
+
+@dataclass(kw_only=True)
+class Context(Generic[DepsT]):
+    """Context for LLM calls.
+
+    This class provides a context for LLM calls, including the model,
+    parameters, and any dependencies needed for the call.
+    """
+
+    deps: DepsT
+    """The dependencies needed for a call."""