mirascope 2.0.0a6__py3-none-any.whl → 2.0.2__py3-none-any.whl

mirascope/llm/exceptions.py

@@ -1,70 +1,292 @@
 """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 .formatting import FormattingMode
     from .providers import ModelId, ProviderId
 
 
-class MirascopeLLMError(Exception):
+class Error(Exception):
     """Base exception for all Mirascope LLM errors."""
 
-    original_exception: Exception | None
-    provider: "ProviderId | None"
 
+class ProviderError(Error):
+    """Base class for errors that originate from a provider SDK.
 
-class APIError(MirascopeLLMError):
-    """Base class for API-related errors."""
+    This wraps exceptions from provider libraries (OpenAI, Anthropic, etc.)
+    and provides a unified interface for error handling.
+    """
 
-    status_code: int | None
+    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, status_code: int | None = None) -> None:
+    def __init__(
+        self,
+        message: str,
+        provider: "ProviderId",
+        original_exception: Exception | None = None,
+    ) -> None:
         super().__init__(message)
-        self.status_code = status_code
+        self.provider = provider
+        self.original_exception = original_exception
+        if original_exception is not None:
+            self.__cause__ = original_exception
 
 
-class ConnectionError(MirascopeLLMError):
-    """Raised when unable to connect to the API (network issues, timeouts)."""
+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, status_code: int | None = None) -> None:
-        super().__init__(message, status_code=status_code or 401)
+    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, status_code: int | None = None) -> None:
-        super().__init__(message, status_code=status_code or 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, status_code: int | None = None) -> None:
-        super().__init__(message, status_code=status_code or 400)
+    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, status_code: int | None = None) -> None:
-        super().__init__(message, status_code=status_code or 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
 
-class ToolNotFoundError(MirascopeLLMError):
-    """Raised if a tool_call cannot be converted to any corresponding tool."""
+    def __hash__(self) -> int:
+        return hash((type(self), self.tool_name))
 
 
-class FeatureNotSupportedError(MirascopeLLMError):
+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`."""
+    If the feature is not supported by the provider at all, then it may be `None`.
+    """
 
     provider_id: "ProviderId"
     model_id: "ModelId | None"
@@ -86,54 +308,7 @@ class FeatureNotSupportedError(MirascopeLLMError):
         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_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"Formatting mode '{formatting_mode}' is not supported by provider '{provider_id}'{model_msg}"
-        super().__init__(
-            feature=f"formatting_mode:{formatting_mode}",
-            provider_id=provider_id,
-            model_id=model_id,
-            message=message,
-        )
-        self.formatting_mode = formatting_mode
-
-
-class RateLimitError(APIError):
-    """Raised when rate limits are exceeded (429)."""
-
-    def __init__(self, message: str, status_code: int | None = None) -> None:
-        super().__init__(message, status_code=status_code or 429)
-
-
-class ServerError(APIError):
-    """Raised for server-side errors (500+)."""
-
-    def __init__(self, message: str, status_code: int | None = None) -> None:
-        super().__init__(message, status_code=status_code or 500)
-
-
-class TimeoutError(MirascopeLLMError):
-    """Raised when requests timeout or deadline exceeded."""
-
-
-# This wraps the APIResponseValidationErrors that OpenAI and Anthropic both return.
-class ResponseValidationError(MirascopeLLMError):
-    """Raised when API response fails validation."""
-
-
-class NoRegisteredProviderError(MirascopeLLMError):
+class NoRegisteredProviderError(Error):
     """Raised when no provider is registered for a given model_id."""
 
     model_id: str
@@ -145,3 +320,41 @@ class NoRegisteredProviderError(MirascopeLLMError):
         )
         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

@@ -3,11 +3,21 @@
 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 FormattableT, FormattingMode
 
 __all__ = [
@@ -16,7 +26,14 @@ __all__ = [
     "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

@@ -1,5 +1,7 @@
 """The `llm.format` decorator for defining response formats as classes."""
 
+from __future__ import annotations
+
 import inspect
 import json
 from dataclasses import dataclass
@@ -7,6 +9,8 @@ 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 FormattableT, FormattingMode, HasFormattingInstructions
 
 TOOL_MODE_INSTRUCTIONS = f"""Always respond to the user's query using the {FORMAT_TOOL_NAME} tool for structured output."""
@@ -49,35 +53,45 @@ class Format(Generic[FormattableT]):
     """JSON schema representation of the structured output format."""
 
     mode: FormattingMode
-    """The decorator-provided mode of the response format. 
-    
+    """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]
-    """The `Formattable` type that this `Format` describes.
-    
-    While the `FormattbleT` typevar allows for `None`, a `Format` will never be
-    constructed when the `FormattableT` is `None`, so you may treat this as 
-    a `RequiredFormattableT` in practice.
+    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 type has a `formatting_instructions` class method, the output of that
-        call will be used for instructions. Otherwise, instructions may be auto-generated
-        based on the formatting mode.
+        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 isinstance(self.formattable, HasFormattingInstructions):
+        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,
@@ -121,30 +135,39 @@ class Format(Generic[FormattableT]):
             name=FORMAT_TOOL_NAME,
             description=description,
             parameters=parameters,
-            strict=True,
+            strict=None,  # Provider determines whether to use strict mode.
         )
 
 
 def format(
-    formattable: type[FormattableT] | None,
+    formattable: type[FormattableT] | OutputParser[FormattableT] | None,
     *,
     mode: FormattingMode,
 ) -> Format[FormattableT] | None:
-    """Returns a `Format` that describes structured output for a Formattable type.
+    """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.
 
-    This function converts a Formattable type (e.g. Pydantic BaseModel) into a `Format`
-    object that describes how the object should be formatted. Calling `llm.format`
-    is optional, as all the APIs that expect a `Format` can also take the Formattable
-    type directly. However, calling `llm.format` is necessary in order to specify the
-    formatting mode that will be used.
+    Primitive types are automatically wrapped in a `BaseModel` with an "output" field
+    for schema generation, then unwrapped during parsing.
 
     Args:
-        mode: The format mode to use, one of the following:
+        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,
@@ -155,34 +178,44 @@ def format(
     you can add the `formatting_instructions` classmethod and have it return `None`.
 
     Returns:
-      A `Format` object describing the Formattable type.
+      A `Format` object describing the format type or parser.
 
     Example:
-      Using with an LLM call:
+      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(
-          provider_id="openai",
-          model_id="openai/gpt-5-mini",
-          format=format,
-      )
+      @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()
-      print(f"{book.title} by {book.author}")
+      ```
+
+    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)
@@ -190,6 +223,34 @@ def format(
     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__)
@@ -206,11 +267,27 @@ def format(
 
 
 def resolve_format(
-    formattable: type[FormattableT] | Format[FormattableT] | None,
+    formattable: (
+        type[FormattableT] | Format[FormattableT] | OutputParser[FormattableT] | None
+    ),
     default_mode: FormattingMode,
 ) -> Format[FormattableT] | None:
-    """Resolve a `Format` (or None) from a possible `Format` or Formattable."""
+    """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
-    else:
-        return format(formattable, mode=default_mode)
+
+    if is_output_parser(formattable):
+        return format(formattable, mode="parser")
+
+    return format(formattable, mode=default_mode)