mirascope 2.1.0__py3-none-any.whl → 2.2.0__py3-none-any.whl

mirascope/llm/responses/response.py

@@ -6,6 +6,7 @@ from typing import TYPE_CHECKING, Any, Generic, overload
 
 from ..content import ToolOutput
 from ..context import Context, DepsT
+from ..exceptions import ParseError
 from ..formatting import Format, FormattableT
 from ..messages import AssistantMessage, Message, UserContent
 from ..tools import (
@@ -100,6 +101,56 @@ class Response(BaseResponse[Toolkit, FormattableT]):
             content=content,
         )
 
+    @overload
+    def validate(
+        self: "Response[None]", max_retries: int = 1
+    ) -> tuple[None, "Response[None]"]: ...
+
+    @overload
+    def validate(
+        self: "Response[FormattableT]", max_retries: int = 1
+    ) -> tuple[FormattableT, "Response[FormattableT]"]: ...
+
+    def validate(
+        self, max_retries: int = 1
+    ) -> tuple[FormattableT | None, "Response[FormattableT] | Response[None]"]:
+        """Parse and validate the response, retrying on parse errors.
+
+        Attempts to parse the response. On `ParseError`, asks the LLM to fix its
+        output by resuming with the error message. Returns both the parsed value
+        and the (potentially updated) response.
+
+        Args:
+            max_retries: Maximum number of retry attempts on parse failure.
+                Defaults to 1 (2 total attempts). Must be non-negative.
+
+        Returns:
+            A tuple of (parsed_value, response). If parsing succeeded on the first
+            attempt, returns (value, self). If retries were needed, returns
+            (value, new_response) where new_response is the final successful response.
+
+        Raises:
+            ValueError: If max_retries is negative.
+            ParseError: If parsing fails after exhausting all retry attempts.
+            Error: If the LLM call fails while generating a retry response.
+        """
+        if max_retries < 0:
+            raise ValueError("max_retries must be non-negative")
+
+        if self.format is None:
+            return None, self
+
+        current_response: Response[FormattableT] = self
+        for attempt in range(max_retries + 1):
+            try:
+                return current_response.parse(), current_response
+            except ParseError as e:
+                if attempt == max_retries:
+                    raise
+                current_response = current_response.resume(e.retry_message())
+
+        raise AssertionError("Unreachable")  # pragma: no cover
+
 
 class AsyncResponse(BaseResponse[AsyncToolkit, FormattableT]):
     """The response generated by an LLM in async mode."""
@@ -180,6 +231,58 @@ class AsyncResponse(BaseResponse[AsyncToolkit, FormattableT]):
             content=content,
         )
 
+    @overload
+    async def validate(
+        self: "AsyncResponse[None]", max_retries: int = 1
+    ) -> tuple[None, "AsyncResponse[None]"]: ...
+
+    @overload
+    async def validate(
+        self: "AsyncResponse[FormattableT]", max_retries: int = 1
+    ) -> tuple[FormattableT, "AsyncResponse[FormattableT]"]: ...
+
+    async def validate(
+        self, max_retries: int = 1
+    ) -> tuple[
+        FormattableT | None, "AsyncResponse[FormattableT] | AsyncResponse[None]"
+    ]:
+        """Parse and validate the response, retrying on parse errors.
+
+        Attempts to parse the response. On `ParseError`, asks the LLM to fix its
+        output by resuming with the error message. Returns both the parsed value
+        and the (potentially updated) response.
+
+        Args:
+            max_retries: Maximum number of retry attempts on parse failure.
+                Defaults to 1 (2 total attempts). Must be non-negative.
+
+        Returns:
+            A tuple of (parsed_value, response). If parsing succeeded on the first
+            attempt, returns (value, self). If retries were needed, returns
+            (value, new_response) where new_response is the final successful response.
+
+        Raises:
+            ValueError: If max_retries is negative.
+            ParseError: If parsing fails after exhausting all retry attempts.
+            Error: If the LLM call fails while generating a retry response.
+        """
+        if max_retries < 0:
+            raise ValueError("max_retries must be non-negative")
+
+        if self.format is None:
+            return None, self
+
+        current_response: AsyncResponse[FormattableT] = self
+        for attempt in range(max_retries + 1):
+            try:
+                return current_response.parse(), current_response
+            except ParseError as e:
+                if attempt == max_retries:
+                    raise
+                current_response = await current_response.resume(e.retry_message())
+
+        raise AssertionError("Unreachable")  # pragma: no cover
+
 
 class ContextResponse(
     BaseResponse[ContextToolkit[DepsT], FormattableT], Generic[DepsT, FormattableT]
@@ -268,6 +371,62 @@ class ContextResponse(
             content=content,
         )
 
+    @overload
+    def validate(
+        self: "ContextResponse[DepsT, None]", ctx: Context[DepsT], max_retries: int = 1
+    ) -> tuple[None, "ContextResponse[DepsT, None]"]: ...
+
+    @overload
+    def validate(
+        self: "ContextResponse[DepsT, FormattableT]",
+        ctx: Context[DepsT],
+        max_retries: int = 1,
+    ) -> tuple[FormattableT, "ContextResponse[DepsT, FormattableT]"]: ...
+
+    def validate(
+        self, ctx: Context[DepsT], max_retries: int = 1
+    ) -> tuple[
+        FormattableT | None,
+        "ContextResponse[DepsT, FormattableT] | ContextResponse[DepsT, None]",
+    ]:
+        """Parse and validate the response, retrying on parse errors.
+
+        Attempts to parse the response. On `ParseError`, asks the LLM to fix its
+        output by resuming with the error message. Returns both the parsed value
+        and the (potentially updated) response.
+
+        Args:
+            ctx: A `Context` with the required deps type.
+            max_retries: Maximum number of retry attempts on parse failure.
+                Defaults to 1 (2 total attempts). Must be non-negative.
+
+        Returns:
+            A tuple of (parsed_value, response). If parsing succeeded on the first
+            attempt, returns (value, self). If retries were needed, returns
+            (value, new_response) where new_response is the final successful response.
+
+        Raises:
+            ValueError: If max_retries is negative.
+            ParseError: If parsing fails after exhausting all retry attempts.
+            Error: If the LLM call fails while generating a retry response.
+        """
+        if max_retries < 0:
+            raise ValueError("max_retries must be non-negative")
+
+        if self.format is None:
+            return None, self
+
+        current_response: ContextResponse[DepsT, FormattableT] = self
+        for attempt in range(max_retries + 1):
+            try:
+                return current_response.parse(), current_response
+            except ParseError as e:
+                if attempt == max_retries:
+                    raise
+                current_response = current_response.resume(ctx, e.retry_message())
+
+        raise AssertionError("Unreachable")  # pragma: no cover
+
 
 class AsyncContextResponse(
     BaseResponse[AsyncContextToolkit[DepsT], FormattableT], Generic[DepsT, FormattableT]
@@ -360,3 +519,61 @@ class AsyncContextResponse(
             response=self,
             content=content,
         )
+
+    @overload
+    async def validate(
+        self: "AsyncContextResponse[DepsT, None]",
+        ctx: Context[DepsT],
+        max_retries: int = 1,
+    ) -> tuple[None, "AsyncContextResponse[DepsT, None]"]: ...
+
+    @overload
+    async def validate(
+        self: "AsyncContextResponse[DepsT, FormattableT]",
+        ctx: Context[DepsT],
+        max_retries: int = 1,
+    ) -> tuple[FormattableT, "AsyncContextResponse[DepsT, FormattableT]"]: ...
+
+    async def validate(
+        self, ctx: Context[DepsT], max_retries: int = 1
+    ) -> tuple[
+        FormattableT | None,
+        "AsyncContextResponse[DepsT, FormattableT] | AsyncContextResponse[DepsT, None]",
+    ]:
+        """Parse and validate the response, retrying on parse errors.
+
+        Attempts to parse the response. On `ParseError`, asks the LLM to fix its
+        output by resuming with the error message. Returns both the parsed value
+        and the (potentially updated) response.
+
+        Args:
+            ctx: A `Context` with the required deps type.
+            max_retries: Maximum number of retry attempts on parse failure.
+                Defaults to 1 (2 total attempts). Must be non-negative.
+
+        Returns:
+            A tuple of (parsed_value, response). If parsing succeeded on the first
+            attempt, returns (value, self). If retries were needed, returns
+            (value, new_response) where new_response is the final successful response.
+
+        Raises:
+            ValueError: If max_retries is negative.
+            ParseError: If parsing fails after exhausting all retry attempts.
+            Error: If the LLM call fails while generating a retry response.
+        """
+        if max_retries < 0:
+            raise ValueError("max_retries must be non-negative")
+
+        if self.format is None:
+            return None, self
+
+        current_response: AsyncContextResponse[DepsT, FormattableT] = self
+        for attempt in range(max_retries + 1):
+            try:
+                return current_response.parse(), current_response
+            except ParseError as e:
+                if attempt == max_retries:
+                    raise
+                current_response = await current_response.resume(ctx, e.retry_message())
+
+        raise AssertionError("Unreachable")  # pragma: no cover

mirascope/llm/responses/stream_response.py

@@ -6,6 +6,7 @@ from typing import TYPE_CHECKING, Generic, overload
 
 from ..content import ToolOutput
 from ..context import Context, DepsT
+from ..exceptions import ParseError
 from ..formatting import Format, FormattableT
 from ..messages import Message, UserContent
 from ..tools import (
@@ -156,6 +157,61 @@ class StreamResponse(BaseSyncStreamResponse[Toolkit, FormattableT]):
             content=content,
         )
 
+    @overload
+    def validate(
+        self: "StreamResponse[None]", max_retries: int = 1
+    ) -> tuple[None, "StreamResponse[None]"]: ...
+
+    @overload
+    def validate(
+        self: "StreamResponse[FormattableT]", max_retries: int = 1
+    ) -> tuple[FormattableT, "StreamResponse[FormattableT]"]: ...
+
+    def validate(
+        self, max_retries: int = 1
+    ) -> tuple[
+        FormattableT | None, "StreamResponse[FormattableT] | StreamResponse[None]"
+    ]:
+        """Parse and validate the response, retrying on parse errors.
+
+        Consumes the stream (calls `finish()`) and then attempts to parse. On
+        `ParseError`, asks the LLM to fix its output by resuming with the error
+        message. Returns both the parsed value and the (potentially updated) response.
+
+        Args:
+            max_retries: Maximum number of retry attempts on parse failure.
+                Defaults to 1 (2 total attempts). Must be non-negative.
+
+        Returns:
+            A tuple of (parsed_value, response). If parsing succeeded on the first
+            attempt, returns (value, self). If retries were needed, returns
+            (value, new_response) where new_response is the final successful response.
+
+        Raises:
+            ValueError: If max_retries is negative.
+            ParseError: If parsing fails after exhausting all retry attempts.
+            Error: If the LLM call fails while generating a retry response.
+        """
+        if max_retries < 0:
+            raise ValueError("max_retries must be non-negative")
+
+        self.finish()
+
+        if self.format is None:
+            return None, self
+
+        current_response: StreamResponse[FormattableT] = self
+        for attempt in range(max_retries + 1):
+            try:
+                return current_response.parse(), current_response
+            except ParseError as e:
+                if attempt == max_retries:
+                    raise
+                current_response = current_response.resume(e.retry_message())
+                current_response.finish()
+
+        raise AssertionError("Unreachable")  # pragma: no cover
+
 
 class AsyncStreamResponse(BaseAsyncStreamResponse[AsyncToolkit, FormattableT]):
     """An `AsyncStreamResponse` wraps response content from the LLM with a streaming interface.
@@ -287,6 +343,62 @@ class AsyncStreamResponse(BaseAsyncStreamResponse[AsyncToolkit, FormattableT]):
             content=content,
         )
 
+    @overload
+    async def validate(
+        self: "AsyncStreamResponse[None]", max_retries: int = 1
+    ) -> tuple[None, "AsyncStreamResponse[None]"]: ...
+
+    @overload
+    async def validate(
+        self: "AsyncStreamResponse[FormattableT]", max_retries: int = 1
+    ) -> tuple[FormattableT, "AsyncStreamResponse[FormattableT]"]: ...
+
+    async def validate(
+        self, max_retries: int = 1
+    ) -> tuple[
+        FormattableT | None,
+        "AsyncStreamResponse[FormattableT] | AsyncStreamResponse[None]",
+    ]:
+        """Parse and validate the response, retrying on parse errors.
+
+        Consumes the stream (calls `finish()`) and then attempts to parse. On
+        `ParseError`, asks the LLM to fix its output by resuming with the error
+        message. Returns both the parsed value and the (potentially updated) response.
+
+        Args:
+            max_retries: Maximum number of retry attempts on parse failure.
+                Defaults to 1 (2 total attempts). Must be non-negative.
+
+        Returns:
+            A tuple of (parsed_value, response). If parsing succeeded on the first
+            attempt, returns (value, self). If retries were needed, returns
+            (value, new_response) where new_response is the final successful response.
+
+        Raises:
+            ValueError: If max_retries is negative.
+            ParseError: If parsing fails after exhausting all retry attempts.
+            Error: If the LLM call fails while generating a retry response.
+        """
+        if max_retries < 0:
+            raise ValueError("max_retries must be non-negative")
+
+        await self.finish()
+
+        if self.format is None:
+            return None, self
+
+        current_response: AsyncStreamResponse[FormattableT] = self
+        for attempt in range(max_retries + 1):
+            try:
+                return current_response.parse(), current_response
+            except ParseError as e:
+                if attempt == max_retries:
+                    raise
+                current_response = await current_response.resume(e.retry_message())
+                await current_response.finish()
+
+        raise AssertionError("Unreachable")  # pragma: no cover
+
 
 class ContextStreamResponse(
     BaseSyncStreamResponse[ContextToolkit[DepsT], FormattableT],
@@ -428,6 +540,67 @@ class ContextStreamResponse(
             content=content,
         )
 
+    @overload
+    def validate(
+        self: "ContextStreamResponse[DepsT, None]",
+        ctx: Context[DepsT],
+        max_retries: int = 1,
+    ) -> tuple[None, "ContextStreamResponse[DepsT, None]"]: ...
+
+    @overload
+    def validate(
+        self: "ContextStreamResponse[DepsT, FormattableT]",
+        ctx: Context[DepsT],
+        max_retries: int = 1,
+    ) -> tuple[FormattableT, "ContextStreamResponse[DepsT, FormattableT]"]: ...
+
+    def validate(
+        self, ctx: Context[DepsT], max_retries: int = 1
+    ) -> tuple[
+        FormattableT | None,
+        "ContextStreamResponse[DepsT, FormattableT] | ContextStreamResponse[DepsT, None]",
+    ]:
+        """Parse and validate the response, retrying on parse errors.
+
+        Consumes the stream (calls `finish()`) and then attempts to parse. On
+        `ParseError`, asks the LLM to fix its output by resuming with the error
+        message. Returns both the parsed value and the (potentially updated) response.
+
+        Args:
+            ctx: A `Context` with the required deps type.
+            max_retries: Maximum number of retry attempts on parse failure.
+                Defaults to 1 (2 total attempts). Must be non-negative.
+
+        Returns:
+            A tuple of (parsed_value, response). If parsing succeeded on the first
+            attempt, returns (value, self). If retries were needed, returns
+            (value, new_response) where new_response is the final successful response.
+
+        Raises:
+            ValueError: If max_retries is negative.
+            ParseError: If parsing fails after exhausting all retry attempts.
+            Error: If the LLM call fails while generating a retry response.
+        """
+        if max_retries < 0:
+            raise ValueError("max_retries must be non-negative")
+
+        self.finish()
+
+        if self.format is None:
+            return None, self
+
+        current_response: ContextStreamResponse[DepsT, FormattableT] = self
+        for attempt in range(max_retries + 1):
+            try:
+                return current_response.parse(), current_response
+            except ParseError as e:
+                if attempt == max_retries:
+                    raise
+                current_response = current_response.resume(ctx, e.retry_message())
+                current_response.finish()
+
+        raise AssertionError("Unreachable")  # pragma: no cover
+
 
 class AsyncContextStreamResponse(
     BaseAsyncStreamResponse[AsyncContextToolkit[DepsT], FormattableT],
@@ -575,3 +748,64 @@ class AsyncContextStreamResponse(
             response=self,
             content=content,
         )
+
+    @overload
+    async def validate(
+        self: "AsyncContextStreamResponse[DepsT, None]",
+        ctx: Context[DepsT],
+        max_retries: int = 1,
+    ) -> tuple[None, "AsyncContextStreamResponse[DepsT, None]"]: ...
+
+    @overload
+    async def validate(
+        self: "AsyncContextStreamResponse[DepsT, FormattableT]",
+        ctx: Context[DepsT],
+        max_retries: int = 1,
+    ) -> tuple[FormattableT, "AsyncContextStreamResponse[DepsT, FormattableT]"]: ...
+
+    async def validate(
+        self, ctx: Context[DepsT], max_retries: int = 1
+    ) -> tuple[
+        FormattableT | None,
+        "AsyncContextStreamResponse[DepsT, FormattableT] | AsyncContextStreamResponse[DepsT, None]",
+    ]:
+        """Parse and validate the response, retrying on parse errors.
+
+        Consumes the stream (calls `finish()`) and then attempts to parse. On
+        `ParseError`, asks the LLM to fix its output by resuming with the error
+        message. Returns both the parsed value and the (potentially updated) response.
+
+        Args:
+            ctx: A `Context` with the required deps type.
+            max_retries: Maximum number of retry attempts on parse failure.
+                Defaults to 1 (2 total attempts). Must be non-negative.
+
+        Returns:
+            A tuple of (parsed_value, response). If parsing succeeded on the first
+            attempt, returns (value, self). If retries were needed, returns
+            (value, new_response) where new_response is the final successful response.
+
+        Raises:
+            ValueError: If max_retries is negative.
+            ParseError: If parsing fails after exhausting all retry attempts.
+            Error: If the LLM call fails while generating a retry response.
+        """
+        if max_retries < 0:
+            raise ValueError("max_retries must be non-negative")
+
+        await self.finish()
+
+        if self.format is None:
+            return None, self
+
+        current_response: AsyncContextStreamResponse[DepsT, FormattableT] = self
+        for attempt in range(max_retries + 1):
+            try:
+                return current_response.parse(), current_response
+            except ParseError as e:
+                if attempt == max_retries:
+                    raise
+                current_response = await current_response.resume(ctx, e.retry_message())
+                await current_response.finish()
+
+        raise AssertionError("Unreachable")  # pragma: no cover

mirascope/llm/retries/__init__.py

@@ -0,0 +1,51 @@
+"""Retry functionality for reliable LLM interactions.
+
+This module provides retry capabilities for LLM calls, including:
+- Automatic retry on failures (connection errors, rate limits, etc.)
+- Configurable retry strategies and backoff
+- Fallback models
+- Retry metadata tracking
+"""
+
+from .retry_calls import AsyncRetryCall, BaseRetryCall, RetryCall
+from .retry_config import RetryArgs, RetryConfig
+from .retry_decorator import retry
+from .retry_models import RetryModel, RetryModelParams, retry_model
+from .retry_prompts import AsyncRetryPrompt, BaseRetryPrompt, RetryPrompt
+from .retry_responses import (
+    AsyncContextRetryResponse,
+    AsyncRetryResponse,
+    ContextRetryResponse,
+    RetryResponse,
+)
+from .retry_stream_responses import (
+    AsyncContextRetryStreamResponse,
+    AsyncRetryStreamResponse,
+    ContextRetryStreamResponse,
+    RetryStreamResponse,
+)
+from .utils import RetryFailure
+
+__all__ = [
+    "AsyncContextRetryResponse",
+    "AsyncContextRetryStreamResponse",
+    "AsyncRetryCall",
+    "AsyncRetryPrompt",
+    "AsyncRetryResponse",
+    "AsyncRetryStreamResponse",
+    "BaseRetryCall",
+    "BaseRetryPrompt",
+    "ContextRetryResponse",
+    "ContextRetryStreamResponse",
+    "RetryArgs",
+    "RetryCall",
+    "RetryConfig",
+    "RetryFailure",
+    "RetryModel",
+    "RetryModelParams",
+    "RetryPrompt",
+    "RetryResponse",
+    "RetryStreamResponse",
+    "retry",
+    "retry_model",
+]