mirascope 1.25.7__py3-none-any.whl → 2.0.0a0__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,63 @@
+"""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."""
+
+    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."""

mirascope/llm/content/tool_output.py

@@ -0,0 +1,26 @@
+"""The `ToolOutput` content class."""
+
+from dataclasses import dataclass
+from typing import Generic, Literal
+
+from ..types import JsonableT
+
+
+@dataclass(kw_only=True)
+class ToolOutput(Generic[JsonableT]):
+    """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."""
+
+    value: JsonableT
+    """The output value from the tool call."""

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,28 @@
+import inspect
+from collections.abc import Callable
+from typing import get_origin
+
+from .context import Context
+
+
+def first_param_is_context(fn: Callable) -> 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]
+
+    type_is_context = get_origin(first_param.annotation) is Context
+    subclass_of_context = isinstance(first_param.annotation, type) and issubclass(
+        first_param.annotation, Context
+    )
+    return first_param.name == "ctx" and (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."""

mirascope/llm/exceptions.py

@@ -0,0 +1,105 @@
+"""Mirascope exception hierarchy for unified error handling across providers."""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .clients import ModelId, Provider
+    from .formatting import FormattingMode
+
+
+class MirascopeError(Exception):
+    """Base exception for all Mirascope errors."""
+
+    original_exception: Exception | None
+
+
+class APIError(MirascopeError):
+    """Base class for API-related errors."""
+
+    status_code: int | None
+
+
+class ConnectionError(MirascopeError):
+    """Raised when unable to connect to the API (network issues, timeouts)."""
+
+
+class AuthenticationError(APIError):
+    """Raised for authentication failures (401, invalid API keys)."""
+
+
+class PermissionError(APIError):
+    """Raised for permission/authorization failures (403)."""
+
+
+class BadRequestError(APIError):
+    """Raised for malformed requests (400, 422)."""
+
+
+class NotFoundError(APIError):
+    """Raised when requested resource is not found (404)."""
+
+
+class ToolNotFoundError(MirascopeError):
+    """Raised if a tool_call cannot be converted to any corresponding tool."""
+
+
+class FeatureNotSupportedError(MirascopeError):
+    """Raised if a Mirascope feature is unsupported by chosen provider.
+
+    If compatibility is model-specific, then `model_id` should be specified.
+    If the feature is not supported by the provider at all, then it may be `None`."""
+
+    provider: "Provider"
+    model_id: "ModelId | None"
+    feature: str
+
+    def __init__(
+        self,
+        feature: str,
+        provider: "Provider",
+        model_id: "ModelId | None" = None,
+        message: str | None = None,
+    ) -> None:
+        if message is None:
+            model_msg = f" for model '{model_id}'" if model_id is not None else ""
+            message = f"Feature '{feature}' is not supported by provider '{provider}'{model_msg}"
+        super().__init__(message)
+        self.feature = feature
+        self.provider = provider
+        self.model_id = model_id
+
+
+class FormattingModeNotSupportedError(FeatureNotSupportedError):
+    """Raised when trying to use a formatting mode that is not supported by the chosen model."""
+
+    formatting_mode: "FormattingMode"
+
+    def __init__(
+        self,
+        formatting_mode: "FormattingMode",
+        provider: "Provider",
+        model_id: "ModelId | None" = None,
+        message: str | None = None,
+    ) -> None:
+        if message is None:
+            model_msg = f" for model '{model_id}'" if model_id is not None else ""
+            message = f"Formatting mode '{formatting_mode}' is not supported by provider '{provider}'{model_msg}"
+        super().__init__(
+            feature=f"formatting_mode:{formatting_mode}",
+            provider=provider,
+            model_id=model_id,
+            message=message,
+        )
+        self.formatting_mode = formatting_mode
+
+
+class RateLimitError(APIError):
+    """Raised when rate limits are exceeded (429)."""
+
+
+class ServerError(APIError):
+    """Raised for server-side errors (500+)."""
+
+
+class TimeoutError(MirascopeError):
+    """Raised when requests timeout or deadline exceeded."""

mirascope/llm/formatting/__init__.py

@@ -0,0 +1,22 @@
+"""Response formatting interfaces for structuring LLM outputs.
+
+This module provides a way to define structured output formats for LLM responses.
+The `@format` decorator can be applied to classes to specify how LLM
+outputs should be structured and parsed.
+"""
+
+from .format import format, resolve_format
+from .from_call_args import FromCallArgs
+from .partial import Partial
+from .types import Format, FormattableT, FormattingMode
+
+__all__ = [
+    "Format",
+    "FormattableT",
+    "FormattableT",
+    "FormattingMode",
+    "FromCallArgs",
+    "Partial",
+    "format",
+    "resolve_format",
+]

mirascope/llm/formatting/_utils.py

@@ -0,0 +1,74 @@
+"""Utilities for the formatting module."""
+
+import inspect
+import json
+
+from ..tools import FORMAT_TOOL_NAME, ToolParameterSchema, ToolSchema
+from .types import Format, FormattableT, FormattingMode
+
+TOOL_MODE_INSTRUCTIONS = f"""Always respond to the user's query using the {FORMAT_TOOL_NAME} tool for structured output."""
+
+
+JSON_MODE_INSTRUCTIONS = (
+    "Respond only with valid JSON that matches this exact schema:\n{json_schema}"
+)
+
+
+def default_formatting_instructions(
+    schema: dict[str, object], mode: FormattingMode
+) -> str | None:
+    """Generate formatting instructions for the given mode and format info."""
+
+    if mode == "tool":
+        return TOOL_MODE_INSTRUCTIONS
+    elif mode == "json":
+        json_schema = json.dumps(schema, indent=2)
+        instructions = JSON_MODE_INSTRUCTIONS.format(json_schema=json_schema)
+        return inspect.cleandoc(instructions)
+
+
+def create_tool_schema(format: Format[FormattableT]) -> ToolSchema:
+    """Convert a `Format` to a `ToolSchema` for format parsing.
+
+    Args:
+        format: The `Format` instance containing schema and metadata
+
+    Returns:
+        `ToolSchema` for the format tool
+    """
+
+    schema_dict = format.schema.copy()
+    schema_dict["type"] = "object"
+
+    properties = schema_dict.get("properties")
+    if not properties or not isinstance(properties, dict):
+        properties = {}  # pragma: no cover
+    required = list(properties.keys())
+
+    description = (
+        f"Use this tool to extract data in {format.name} format for a final response."
+    )
+    if format.description:
+        description += "\n" + format.description
+
+    parameters = ToolParameterSchema(
+        properties=properties,
+        required=required,
+        additionalProperties=False,
+    )
+    if "$defs" in schema_dict and isinstance(schema_dict["$defs"], dict):
+        parameters.defs = schema_dict["$defs"]
+
+    def _unused_format_fn() -> None:
+        raise TypeError(
+            "Format tool function should not be called."
+        )  # pragma: no cover
+
+    tool_schema = ToolSchema.__new__(ToolSchema)
+    tool_schema.fn = _unused_format_fn
+    tool_schema.name = FORMAT_TOOL_NAME
+    tool_schema.description = description
+    tool_schema.parameters = parameters
+    tool_schema.strict = True
+
+    return tool_schema