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

mirascope/llm/exceptions.py

@@ -0,0 +1,360 @@
+"""Mirascope llm exception hierarchy for unified error handling across providers."""
+
+import json
+from typing import TYPE_CHECKING
+
+from pydantic import ValidationError
+
+if TYPE_CHECKING:
+    from .providers import ModelId, ProviderId
+
+
+class Error(Exception):
+    """Base exception for all Mirascope LLM errors."""
+
+
+class ProviderError(Error):
+    """Base class for errors that originate from a provider SDK.
+
+    This wraps exceptions from provider libraries (OpenAI, Anthropic, etc.)
+    and provides a unified interface for error handling.
+    """
+
+    provider: "ProviderId"
+    """The provider that raised this error."""
+
+    original_exception: Exception | None
+    """The original exception from the provider SDK, if available."""
+
+    def __init__(
+        self,
+        message: str,
+        provider: "ProviderId",
+        original_exception: Exception | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.provider = provider
+        self.original_exception = original_exception
+        if original_exception is not None:
+            self.__cause__ = original_exception
+
+
+class APIError(ProviderError):
+    """Base class for HTTP-level API errors."""
+
+    status_code: int | None
+    """The HTTP status code, if available."""
+
+    def __init__(
+        self,
+        message: str,
+        provider: "ProviderId",
+        status_code: int | None = None,
+        original_exception: Exception | None = None,
+    ) -> None:
+        super().__init__(message, provider, original_exception)
+        self.status_code = status_code
+
+
+class AuthenticationError(APIError):
+    """Raised for authentication failures (401, invalid API keys)."""
+
+    def __init__(
+        self,
+        message: str,
+        provider: "ProviderId",
+        status_code: int | None = None,
+        original_exception: Exception | None = None,
+    ) -> None:
+        super().__init__(
+            message,
+            provider,
+            status_code=status_code or 401,
+            original_exception=original_exception,
+        )
+
+
+class PermissionError(APIError):
+    """Raised for permission/authorization failures (403)."""
+
+    def __init__(
+        self,
+        message: str,
+        provider: "ProviderId",
+        status_code: int | None = None,
+        original_exception: Exception | None = None,
+    ) -> None:
+        super().__init__(
+            message,
+            provider,
+            status_code=status_code or 403,
+            original_exception=original_exception,
+        )
+
+
+class BadRequestError(APIError):
+    """Raised for malformed requests (400, 422)."""
+
+    def __init__(
+        self,
+        message: str,
+        provider: "ProviderId",
+        status_code: int | None = None,
+        original_exception: Exception | None = None,
+    ) -> None:
+        super().__init__(
+            message,
+            provider,
+            status_code=status_code or 400,
+            original_exception=original_exception,
+        )
+
+
+class NotFoundError(APIError):
+    """Raised when requested resource is not found (404)."""
+
+    def __init__(
+        self,
+        message: str,
+        provider: "ProviderId",
+        status_code: int | None = None,
+        original_exception: Exception | None = None,
+    ) -> None:
+        super().__init__(
+            message,
+            provider,
+            status_code=status_code or 404,
+            original_exception=original_exception,
+        )
+
+
+class RateLimitError(APIError):
+    """Raised when rate limits are exceeded (429)."""
+
+    def __init__(
+        self,
+        message: str,
+        provider: "ProviderId",
+        status_code: int | None = None,
+        original_exception: Exception | None = None,
+    ) -> None:
+        super().__init__(
+            message,
+            provider,
+            status_code=status_code or 429,
+            original_exception=original_exception,
+        )
+
+
+class ServerError(APIError):
+    """Raised for server-side errors (500+)."""
+
+    def __init__(
+        self,
+        message: str,
+        provider: "ProviderId",
+        status_code: int | None = None,
+        original_exception: Exception | None = None,
+    ) -> None:
+        super().__init__(
+            message,
+            provider,
+            status_code=status_code or 500,
+            original_exception=original_exception,
+        )
+
+
+class ConnectionError(ProviderError):
+    """Raised when unable to connect to the API (network issues, timeouts)."""
+
+
+class TimeoutError(ProviderError):
+    """Raised when requests timeout or deadline exceeded."""
+
+
+class ResponseValidationError(ProviderError):
+    """Raised when API response fails validation.
+
+    This wraps the APIResponseValidationErrors that OpenAI and Anthropic both return.
+    """
+
+
+class ToolError(Error):
+    """Base class for errors that occur during tool execution."""
+
+
+class ToolExecutionError(ToolError):
+    """Raised if an uncaught exception is thrown while executing a tool."""
+
+    tool_exception: Exception
+    """The exception that was thrown while executing the tool."""
+
+    def __init__(self, tool_exception: Exception | str) -> None:
+        if isinstance(tool_exception, str):
+            # Support string for snapshot reconstruction
+            message = tool_exception
+            tool_exception = ValueError(message)
+        else:
+            message = str(tool_exception)
+        super().__init__(message)
+        self.tool_exception = tool_exception
+        self.__cause__ = tool_exception
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, ToolExecutionError):
+            return False
+        # Needed for snapshot tests.
+        return str(self) == str(other)
+
+
+class ToolNotFoundError(ToolError):
+    """Raised if a tool call does not match any registered tool."""
+
+    tool_name: str
+    """The name of the tool that was not found."""
+
+    def __init__(self, tool_name: str) -> None:
+        super().__init__(f"Tool '{tool_name}' not found in registered tools")
+        self.tool_name = tool_name
+
+    def __repr__(self) -> str:
+        return f"ToolNotFoundError({self.tool_name!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, ToolNotFoundError):
+            return NotImplemented
+        return self.tool_name == other.tool_name
+
+    def __hash__(self) -> int:
+        return hash((type(self), self.tool_name))
+
+
+class ParseError(Error):
+    """Raised when response.parse() fails to parse the response content.
+
+    This wraps errors from JSON extraction, JSON parsing, Pydantic validation,
+    or custom OutputParser functions.
+    """
+
+    original_exception: Exception
+    """The original exception that caused the parse failure."""
+
+    def __init__(
+        self,
+        message: str,
+        original_exception: Exception,
+    ) -> None:
+        super().__init__(message)
+        self.original_exception = original_exception
+        self.__cause__ = original_exception
+
+    def retry_message(self) -> str:
+        """Generate a message suitable for retrying with the LLM.
+
+        Returns a user-friendly message describing what went wrong,
+        suitable for including in a retry prompt.
+        """
+
+        if isinstance(self.original_exception, ValidationError):
+            return (
+                f"Your response failed schema validation:\n"
+                f"{self.original_exception}\n\n"
+                "Please correct these issues and respond again."
+            )
+        elif isinstance(self.original_exception, json.JSONDecodeError):
+            # JSON syntax error
+            return (
+                "Your response could not be parsed because no valid JSON object "
+                "was found. Please ensure your response contains a JSON object "
+                "with opening '{' and closing '}' braces."
+            )
+        else:
+            # ValueError from JSON extraction, or OutputParser error
+            return (
+                f"Your response could not be parsed: {self.original_exception}\n\n"
+                "Please ensure your response matches the expected format."
+            )
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, ParseError):
+            return False
+        return str(self) == str(other)
+
+
+class FeatureNotSupportedError(Error):
+    """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_id: "ProviderId"
+    model_id: "ModelId | None"
+    feature: str
+
+    def __init__(
+        self,
+        feature: str,
+        provider_id: "ProviderId",
+        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_id}'{model_msg}"
+        super().__init__(message)
+        self.feature = feature
+        self.provider_id = provider_id
+        self.model_id = model_id
+
+
+class NoRegisteredProviderError(Error):
+    """Raised when no provider is registered for a given model_id."""
+
+    model_id: str
+
+    def __init__(self, model_id: str) -> None:
+        message = (
+            f"No provider registered for model '{model_id}'. "
+            f"Use llm.register_provider() to register a provider for this model."
+        )
+        super().__init__(message)
+        self.model_id = model_id
+
+
+class MissingAPIKeyError(Error):
+    """Raised when no API key is available for a provider.
+
+    This error is raised during auto-registration when the required API key
+    environment variable is not set. If a Mirascope fallback is available,
+    the error message will suggest using MIRASCOPE_API_KEY as an alternative.
+    """
+
+    provider_id: str
+    """The provider that requires an API key."""
+
+    env_var: str
+    """The environment variable that should contain the API key."""
+
+    def __init__(
+        self,
+        provider_id: str,
+        env_var: str,
+        has_mirascope_fallback: bool = False,
+    ) -> None:
+        if has_mirascope_fallback:
+            message = (
+                f"No API key found for {provider_id}. Either:\n"
+                f"  1. Set {env_var} environment variable, or\n"
+                f"  2. Set MIRASCOPE_API_KEY for cross-provider support "
+                f"via Mirascope Router\n"
+                f"     (Learn more: https://mirascope.com/docs/router)"
+            )
+        else:
+            message = (
+                f"No API key found for {provider_id}. "
+                f"Set the {env_var} environment variable."
+            )
+        super().__init__(message)
+        self.provider_id = provider_id
+        self.env_var = env_var

mirascope/llm/formatting/__init__.py

@@ -0,0 +1,39 @@
+"""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.
+
+The `@output_parser` decorator can be used to create custom parsers for non-JSON
+formats like XML, YAML, CSV, or any custom text structure.
+"""
+
+from .format import Format, format, resolve_format
+from .from_call_args import FromCallArgs
+from .output_parser import OutputParser, is_output_parser, output_parser
+from .partial import Partial
+from .primitives import (
+    PrimitiveType,
+    PrimitiveWrapperModel,
+    create_wrapper_model,
+    is_primitive_type,
+)
+from .types import FormatSpec, FormattableT, FormattingMode
+
+__all__ = [
+    "Format",
+    "FormatSpec",
+    "FormattableT",
+    "FormattingMode",
+    "FromCallArgs",
+    "OutputParser",
+    "Partial",
+    "PrimitiveType",
+    "PrimitiveWrapperModel",
+    "create_wrapper_model",
+    "format",
+    "is_output_parser",
+    "is_primitive_type",
+    "output_parser",
+    "resolve_format",
+]

mirascope/llm/formatting/format.py

@@ -0,0 +1,291 @@
+"""The `llm.format` decorator for defining response formats as classes."""
+
+from __future__ import annotations
+
+import inspect
+import json
+from dataclasses import dataclass
+from typing import Any, Generic, cast
+
+from ..tools import FORMAT_TOOL_NAME, ToolFn, ToolParameterSchema, ToolSchema
+from ..types import NoneType
+from .output_parser import OutputParser, is_output_parser
+from .primitives import create_wrapper_model, is_primitive_type
+from .types import FormatSpec, FormattableT, FormattingMode, HasFormattingInstructions
+
+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}"
+)
+
+
+@dataclass(kw_only=True)
+class Format(Generic[FormattableT]):
+    """Class representing a structured output format for LLM responses.
+
+    A `Format` contains metadata needed to describe a structured output type
+    to the LLM, including the expected schema. This class is not instantiated directly,
+    but is created by calling `llm.format`, or is automatically generated by LLM
+    providers when a `Formattable` is passed to a call method.
+
+    Example:
+
+      ```python
+      from mirascope import llm
+
+      class Book:
+          title: str
+          author: str
+
+      print(llm.format(Book, mode="tool"))
+      ```
+    """
+
+    name: str
+    """The name of the response format."""
+
+    description: str | None
+    """A description of the response format, if available."""
+
+    schema: dict[str, object]
+    """JSON schema representation of the structured output format."""
+
+    mode: FormattingMode
+    """The decorator-provided mode of the response format.
+
+    Determines how the LLM call may be modified in order to extract the expected format.
+    """
+
+    formattable: type[FormattableT] | OutputParser[FormattableT]
+    """The formattable type or custom output parser.
+
+    Can be one of:
+    - type[BaseModel]: A Pydantic model class for structured output
+    - PrimitiveType: A primitive type (str, int, list, etc.) for simple output
+    - OutputParser[FormattableT]: A custom parser created with @llm.output_parser
+
+    The type determines how the response will be parsed in response.parse().
+    OutputParser uses Any for the response type since it works with any response.
+    """
+
+    @property
+    def formatting_instructions(self) -> str | None:
+        """The formatting instructions that will be added to the LLM system prompt.
+
+        If the format has a custom `OutputParser`, its formatting instructions will be used.
+        Otherwise, if the format type has a `formatting_instructions` class method,
+        the output of that call will be used. Otherwise, instructions may be
+        auto-generated based on the formatting mode.
+        """
+        if is_output_parser(self.formattable) or isinstance(
+            self.formattable, HasFormattingInstructions
+        ):
+            return self.formattable.formatting_instructions()
+
+        if self.mode == "tool":
+            return TOOL_MODE_INSTRUCTIONS
+        elif self.mode == "json":
+            json_schema = json.dumps(self.schema, indent=2)
+            instructions = JSON_MODE_INSTRUCTIONS.format(json_schema=json_schema)
+            return inspect.cleandoc(instructions)
+        elif self.mode == "parser":
+            return None  # pragma: no cover
+
+    def create_tool_schema(
+        self,
+    ) -> ToolSchema[ToolFn[..., None]]:
+        """Generate a `ToolSchema` for parsing this format.
+
+        Returns:
+            `ToolSchema` for the format tool
+        """
+
+        schema_dict: dict[str, Any] = self.schema.copy()
+        schema_dict["type"] = "object"
+
+        properties = schema_dict.get("properties")
+        if not properties or not isinstance(properties, dict):
+            properties = {}  # pragma: no cover
+        properties = cast(dict[str, Any], properties)
+        required: list[str] = list(properties.keys())
+
+        description = (
+            f"Use this tool to extract data in {self.name} format for a final response."
+        )
+        if self.description:
+            description += "\n" + self.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
+
+        return ToolSchema(
+            fn=cast(ToolFn[..., None], _unused_format_fn),
+            name=FORMAT_TOOL_NAME,
+            description=description,
+            parameters=parameters,
+            strict=None,  # Provider determines whether to use strict mode.
+        )
+
+
+def format(
+    formattable: type[FormattableT] | OutputParser[FormattableT] | None,
+    *,
+    mode: FormattingMode,
+) -> Format[FormattableT] | None:
+    """Returns a `Format` that describes structured output or custom parsing.
+
+    This function converts a Formattable type (e.g. Pydantic `BaseModel` or primitive type)
+    or an `OutputParser` into a `Format` object that describes how the output should be
+    formatted and parsed. Calling `llm.format` is optional, as all the APIs that expect
+    a `Format` can also take the Formattable type or `OutputParser` directly. However,
+    calling `llm.format` is necessary in order to specify the formatting mode for
+    `BaseModel`/primitive types.
+
+    Primitive types are automatically wrapped in a `BaseModel` with an "output" field
+    for schema generation, then unwrapped during parsing.
+
+    Args:
+        formattable: The type or parser to format:
+            - BaseModel type: Uses structured output with JSON schema
+            - Primitive type: Wrapped in schema for structured output
+            - OutputParser: Uses custom parsing with instructions
+        mode: The format mode to use (required):
+            - "strict": Use model strict structured outputs, or fail if unavailable.
+            - "tool": Use forced tool calling with a special tool that represents a
+              formatted response.
+            - "json": Use provider json mode if available, or modify prompt to request
+              json if not.
+            - "parser": Must be used for OutputParser types.
+
+    The Formattable type may provide custom formatting instructions via a
+    `formatting_instructions(cls)` classmethod. If that method is present, it will be called,
+    and the resulting instructions will automatically be appended to the system prompt.
+
+    If no formatting instructions are present, then Mirascope may auto-generate instructions
+    based on the active format mode. To disable this behavior and all prompt modification,
+    you can add the `formatting_instructions` classmethod and have it return `None`.
+
+    Returns:
+      A `Format` object describing the format type or parser.
+
+    Example:
+      Using with a BaseModel:
+
+      ```python
+      from pydantic import BaseModel
+      from mirascope import llm
+
+      class Book(BaseModel):
+          title: str
+          author: str
+
+      format = llm.format(Book, mode="strict")
+
+      @llm.call("openai/gpt-5-mini", format=format)
+      def recommend_book(genre: str):
+          return f"Recommend a {genre} book."
+
+      response = recommend_book("fantasy")
+      book: Book = response.parse()
+      ```
+
+    Example:
+
+      Using with an `OutputParser`:
+
+      ```python
+      @llm.output_parser(
+          formatting_instructions="Return XML: <book><title>...</title></book>"
+      )
+      def parse_book_xml(response: llm.AnyResponse) -> Book:
+          # ... parsing logic ...
+          return Book(...)
+
+      @llm.call("openai/gpt-5-mini", format=parse_book_xml)
+      def recommend_book(genre: str):
+          return f"Recommend a {genre} book."
+      ```
+    """
+    # TODO: Add caching or memoization to this function (e.g. functools.lru_cache)
+
+    if formattable is None or formattable is NoneType:
+        return None
+
+    if is_output_parser(formattable):
+        if mode != "parser":
+            raise ValueError(f"mode must be 'parser' for OutputParser, got '{mode}'")
+        return Format[Any](
+            name=formattable.__name__,
+            description=formattable.__doc__,
+            schema={},
+            mode="parser",
+            formattable=formattable,
+        )
+
+    if is_primitive_type(formattable):
+        wrapper_model = create_wrapper_model(formattable)
+        schema = wrapper_model.model_json_schema()
+        name = (
+            formattable.__name__
+            if hasattr(formattable, "__name__")
+            else str(formattable)
+        )
+
+        return Format[FormattableT](
+            name=name,
+            description=None,
+            schema=schema,
+            mode=mode,
+            formattable=formattable,
+        )
+
+    description = None
+    if formattable.__doc__:
+        description = inspect.cleandoc(formattable.__doc__)
+
+    schema = formattable.model_json_schema()
+
+    return Format[FormattableT](
+        name=formattable.__name__,
+        description=description,
+        schema=schema,
+        mode=mode,
+        formattable=formattable,
+    )
+
+
+def resolve_format(
+    formattable: FormatSpec[FormattableT] | None,
+    default_mode: FormattingMode,
+) -> Format[FormattableT] | None:
+    """Resolve a `Format` (or None) from a possible `Format`, Formattable, or `OutputParser`.
+
+    Args:
+        formattable: The format specification:
+            - Format: Returned as-is
+            - BaseModel/primitive type: Converted to Format with default_mode
+            - OutputParser: Converted to Format with mode='parser'
+        default_mode: The mode to use for BaseModel/primitive types.
+
+    Returns:
+        A Format object or None.
+    """
+    if isinstance(formattable, Format):
+        return formattable
+
+    if is_output_parser(formattable):
+        return format(formattable, mode="parser")
+
+    return format(formattable, mode=default_mode)