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

mirascope/api/_generated/functions/client.py

@@ -66,6 +66,7 @@ class FunctionsClient:
         signature: str,
         signature_hash: str,
         name: str,
+        language: str,
         description: typing.Optional[str] = OMIT,
         tags: typing.Optional[typing.Sequence[str]] = OMIT,
         metadata: typing.Optional[typing.Dict[str, typing.Optional[str]]] = OMIT,
@@ -87,6 +88,8 @@ class FunctionsClient:
 
         name : str
 
+        language : str
+
         description : typing.Optional[str]
 
         tags : typing.Optional[typing.Sequence[str]]
@@ -114,6 +117,7 @@ class FunctionsClient:
             signature="signature",
             signature_hash="signatureHash",
             name="name",
+            language="language",
         )
         """
         _response = self._raw_client.create(
@@ -122,6 +126,7 @@ class FunctionsClient:
             signature=signature,
             signature_hash=signature_hash,
             name=name,
+            language=language,
             description=description,
             tags=tags,
             metadata=metadata,
@@ -359,6 +364,7 @@ class AsyncFunctionsClient:
         signature: str,
         signature_hash: str,
         name: str,
+        language: str,
         description: typing.Optional[str] = OMIT,
         tags: typing.Optional[typing.Sequence[str]] = OMIT,
         metadata: typing.Optional[typing.Dict[str, typing.Optional[str]]] = OMIT,
@@ -380,6 +386,8 @@ class AsyncFunctionsClient:
 
         name : str
 
+        language : str
+
         description : typing.Optional[str]
 
         tags : typing.Optional[typing.Sequence[str]]
@@ -412,6 +420,7 @@ class AsyncFunctionsClient:
                 signature="signature",
                 signature_hash="signatureHash",
                 name="name",
+                language="language",
             )
 
 
@@ -423,6 +432,7 @@ class AsyncFunctionsClient:
             signature=signature,
             signature_hash=signature_hash,
             name=name,
+            language=language,
             description=description,
             tags=tags,
             metadata=metadata,

mirascope/api/_generated/functions/raw_client.py

@@ -167,6 +167,7 @@ class RawFunctionsClient:
         signature: str,
         signature_hash: str,
         name: str,
+        language: str,
         description: typing.Optional[str] = OMIT,
         tags: typing.Optional[typing.Sequence[str]] = OMIT,
         metadata: typing.Optional[typing.Dict[str, typing.Optional[str]]] = OMIT,
@@ -188,6 +189,8 @@ class RawFunctionsClient:
 
         name : str
 
+        language : str
+
         description : typing.Optional[str]
 
         tags : typing.Optional[typing.Sequence[str]]
@@ -213,6 +216,7 @@ class RawFunctionsClient:
                 "signature": signature,
                 "signatureHash": signature_hash,
                 "name": name,
+                "language": language,
                 "description": description,
                 "tags": tags,
                 "metadata": metadata,
@@ -1094,6 +1098,7 @@ class AsyncRawFunctionsClient:
         signature: str,
         signature_hash: str,
         name: str,
+        language: str,
         description: typing.Optional[str] = OMIT,
         tags: typing.Optional[typing.Sequence[str]] = OMIT,
         metadata: typing.Optional[typing.Dict[str, typing.Optional[str]]] = OMIT,
@@ -1115,6 +1120,8 @@ class AsyncRawFunctionsClient:
 
         name : str
 
+        language : str
+
         description : typing.Optional[str]
 
         tags : typing.Optional[typing.Sequence[str]]
@@ -1140,6 +1147,7 @@ class AsyncRawFunctionsClient:
                 "signature": signature,
                 "signatureHash": signature_hash,
                 "name": name,
+                "language": language,
                 "description": description,
                 "tags": tags,
                 "metadata": metadata,

mirascope/api/_generated/functions/types/functions_create_response.py

@@ -6,13 +6,17 @@ import pydantic
 import typing_extensions
 from ...core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
 from ...core.serialization import FieldMetadata
-from .functions_create_response_dependencies_value import FunctionsCreateResponseDependenciesValue
+from .functions_create_response_dependencies_value import (
+    FunctionsCreateResponseDependenciesValue,
+)
 
 
 class FunctionsCreateResponse(UniversalBaseModel):
     id: str
     hash: str
-    signature_hash: typing_extensions.Annotated[str, FieldMetadata(alias="signatureHash")]
+    signature_hash: typing_extensions.Annotated[
+        str, FieldMetadata(alias="signatureHash")
+    ]
     name: str
     description: typing.Optional[str] = None
     version: str
@@ -20,15 +24,28 @@ class FunctionsCreateResponse(UniversalBaseModel):
     metadata: typing.Optional[typing.Dict[str, typing.Optional[str]]] = None
     code: str
     signature: str
-    dependencies: typing.Optional[typing.Dict[str, typing.Optional[FunctionsCreateResponseDependenciesValue]]] = None
-    environment_id: typing_extensions.Annotated[str, FieldMetadata(alias="environmentId")]
+    language: str
+    dependencies: typing.Optional[
+        typing.Dict[str, typing.Optional[FunctionsCreateResponseDependenciesValue]]
+    ] = None
+    environment_id: typing_extensions.Annotated[
+        str, FieldMetadata(alias="environmentId")
+    ]
     project_id: typing_extensions.Annotated[str, FieldMetadata(alias="projectId")]
-    organization_id: typing_extensions.Annotated[str, FieldMetadata(alias="organizationId")]
-    created_at: typing_extensions.Annotated[typing.Optional[str], FieldMetadata(alias="createdAt")] = None
-    updated_at: typing_extensions.Annotated[typing.Optional[str], FieldMetadata(alias="updatedAt")] = None
+    organization_id: typing_extensions.Annotated[
+        str, FieldMetadata(alias="organizationId")
+    ]
+    created_at: typing_extensions.Annotated[
+        typing.Optional[str], FieldMetadata(alias="createdAt")
+    ] = None
+    updated_at: typing_extensions.Annotated[
+        typing.Optional[str], FieldMetadata(alias="updatedAt")
+    ] = None
 
     if IS_PYDANTIC_V2:
-        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(
+            extra="allow", frozen=True
+        )  # type: ignore # Pydantic v2
     else:
 
         class Config:

mirascope/api/_generated/functions/types/functions_find_by_hash_response.py

@@ -6,13 +6,17 @@ import pydantic
 import typing_extensions
 from ...core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
 from ...core.serialization import FieldMetadata
-from .functions_find_by_hash_response_dependencies_value import FunctionsFindByHashResponseDependenciesValue
+from .functions_find_by_hash_response_dependencies_value import (
+    FunctionsFindByHashResponseDependenciesValue,
+)
 
 
 class FunctionsFindByHashResponse(UniversalBaseModel):
     id: str
     hash: str
-    signature_hash: typing_extensions.Annotated[str, FieldMetadata(alias="signatureHash")]
+    signature_hash: typing_extensions.Annotated[
+        str, FieldMetadata(alias="signatureHash")
+    ]
     name: str
     description: typing.Optional[str] = None
     version: str
@@ -20,17 +24,28 @@ class FunctionsFindByHashResponse(UniversalBaseModel):
     metadata: typing.Optional[typing.Dict[str, typing.Optional[str]]] = None
     code: str
     signature: str
-    dependencies: typing.Optional[typing.Dict[str, typing.Optional[FunctionsFindByHashResponseDependenciesValue]]] = (
-        None
-    )
-    environment_id: typing_extensions.Annotated[str, FieldMetadata(alias="environmentId")]
+    language: str
+    dependencies: typing.Optional[
+        typing.Dict[str, typing.Optional[FunctionsFindByHashResponseDependenciesValue]]
+    ] = None
+    environment_id: typing_extensions.Annotated[
+        str, FieldMetadata(alias="environmentId")
+    ]
     project_id: typing_extensions.Annotated[str, FieldMetadata(alias="projectId")]
-    organization_id: typing_extensions.Annotated[str, FieldMetadata(alias="organizationId")]
-    created_at: typing_extensions.Annotated[typing.Optional[str], FieldMetadata(alias="createdAt")] = None
-    updated_at: typing_extensions.Annotated[typing.Optional[str], FieldMetadata(alias="updatedAt")] = None
+    organization_id: typing_extensions.Annotated[
+        str, FieldMetadata(alias="organizationId")
+    ]
+    created_at: typing_extensions.Annotated[
+        typing.Optional[str], FieldMetadata(alias="createdAt")
+    ] = None
+    updated_at: typing_extensions.Annotated[
+        typing.Optional[str], FieldMetadata(alias="updatedAt")
+    ] = None
 
     if IS_PYDANTIC_V2:
-        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(
+            extra="allow", frozen=True
+        )  # type: ignore # Pydantic v2
     else:
 
         class Config:

mirascope/api/_generated/functions/types/functions_get_by_env_response.py

@@ -24,6 +24,7 @@ class FunctionsGetByEnvResponse(UniversalBaseModel):
     metadata: typing.Optional[typing.Dict[str, typing.Optional[str]]] = None
     code: str
     signature: str
+    language: str
     dependencies: typing.Optional[
         typing.Dict[str, typing.Optional[FunctionsGetByEnvResponseDependenciesValue]]
     ] = None

mirascope/api/_generated/functions/types/functions_get_response.py

@@ -6,13 +6,17 @@ import pydantic
 import typing_extensions
 from ...core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
 from ...core.serialization import FieldMetadata
-from .functions_get_response_dependencies_value import FunctionsGetResponseDependenciesValue
+from .functions_get_response_dependencies_value import (
+    FunctionsGetResponseDependenciesValue,
+)
 
 
 class FunctionsGetResponse(UniversalBaseModel):
     id: str
     hash: str
-    signature_hash: typing_extensions.Annotated[str, FieldMetadata(alias="signatureHash")]
+    signature_hash: typing_extensions.Annotated[
+        str, FieldMetadata(alias="signatureHash")
+    ]
     name: str
     description: typing.Optional[str] = None
     version: str
@@ -20,15 +24,28 @@ class FunctionsGetResponse(UniversalBaseModel):
     metadata: typing.Optional[typing.Dict[str, typing.Optional[str]]] = None
     code: str
     signature: str
-    dependencies: typing.Optional[typing.Dict[str, typing.Optional[FunctionsGetResponseDependenciesValue]]] = None
-    environment_id: typing_extensions.Annotated[str, FieldMetadata(alias="environmentId")]
+    language: str
+    dependencies: typing.Optional[
+        typing.Dict[str, typing.Optional[FunctionsGetResponseDependenciesValue]]
+    ] = None
+    environment_id: typing_extensions.Annotated[
+        str, FieldMetadata(alias="environmentId")
+    ]
     project_id: typing_extensions.Annotated[str, FieldMetadata(alias="projectId")]
-    organization_id: typing_extensions.Annotated[str, FieldMetadata(alias="organizationId")]
-    created_at: typing_extensions.Annotated[typing.Optional[str], FieldMetadata(alias="createdAt")] = None
-    updated_at: typing_extensions.Annotated[typing.Optional[str], FieldMetadata(alias="updatedAt")] = None
+    organization_id: typing_extensions.Annotated[
+        str, FieldMetadata(alias="organizationId")
+    ]
+    created_at: typing_extensions.Annotated[
+        typing.Optional[str], FieldMetadata(alias="createdAt")
+    ] = None
+    updated_at: typing_extensions.Annotated[
+        typing.Optional[str], FieldMetadata(alias="updatedAt")
+    ] = None
 
     if IS_PYDANTIC_V2:
-        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(
+            extra="allow", frozen=True
+        )  # type: ignore # Pydantic v2
     else:
 
         class Config:

mirascope/api/_generated/functions/types/functions_list_by_env_response_functions_item.py

@@ -24,6 +24,7 @@ class FunctionsListByEnvResponseFunctionsItem(UniversalBaseModel):
     metadata: typing.Optional[typing.Dict[str, typing.Optional[str]]] = None
     code: str
     signature: str
+    language: str
     dependencies: typing.Optional[
         typing.Dict[
             str,

mirascope/api/_generated/functions/types/functions_list_response_functions_item.py

@@ -14,7 +14,9 @@ from .functions_list_response_functions_item_dependencies_value import (
 class FunctionsListResponseFunctionsItem(UniversalBaseModel):
     id: str
     hash: str
-    signature_hash: typing_extensions.Annotated[str, FieldMetadata(alias="signatureHash")]
+    signature_hash: typing_extensions.Annotated[
+        str, FieldMetadata(alias="signatureHash")
+    ]
     name: str
     description: typing.Optional[str] = None
     version: str
@@ -22,17 +24,30 @@ class FunctionsListResponseFunctionsItem(UniversalBaseModel):
     metadata: typing.Optional[typing.Dict[str, typing.Optional[str]]] = None
     code: str
     signature: str
+    language: str
     dependencies: typing.Optional[
-        typing.Dict[str, typing.Optional[FunctionsListResponseFunctionsItemDependenciesValue]]
+        typing.Dict[
+            str, typing.Optional[FunctionsListResponseFunctionsItemDependenciesValue]
+        ]
     ] = None
-    environment_id: typing_extensions.Annotated[str, FieldMetadata(alias="environmentId")]
+    environment_id: typing_extensions.Annotated[
+        str, FieldMetadata(alias="environmentId")
+    ]
     project_id: typing_extensions.Annotated[str, FieldMetadata(alias="projectId")]
-    organization_id: typing_extensions.Annotated[str, FieldMetadata(alias="organizationId")]
-    created_at: typing_extensions.Annotated[typing.Optional[str], FieldMetadata(alias="createdAt")] = None
-    updated_at: typing_extensions.Annotated[typing.Optional[str], FieldMetadata(alias="updatedAt")] = None
+    organization_id: typing_extensions.Annotated[
+        str, FieldMetadata(alias="organizationId")
+    ]
+    created_at: typing_extensions.Annotated[
+        typing.Optional[str], FieldMetadata(alias="createdAt")
+    ] = None
+    updated_at: typing_extensions.Annotated[
+        typing.Optional[str], FieldMetadata(alias="updatedAt")
+    ] = None
 
     if IS_PYDANTIC_V2:
-        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(
+            extra="allow", frozen=True
+        )  # type: ignore # Pydantic v2
     else:
 
         class Config:

mirascope/api/_generated/reference.md

@@ -3749,6 +3749,7 @@ client.functions.create(
     signature="signature",
     signature_hash="signatureHash",
     name="name",
+    language="language",
 )
 
 ```
@@ -3805,6 +3806,14 @@ client.functions.create(
 <dl>
 <dd>
 
+**language:** `str` 
+    
+</dd>
+</dl>
+
+<dl>
+<dd>
+
 **description:** `typing.Optional[str]` 
     
 </dd>

mirascope/llm/__init__.py

@@ -20,6 +20,7 @@ from . import (
     prompts,
     providers,
     responses,
+    retries,
     tools,
     types,
 )
@@ -67,7 +68,9 @@ from .exceptions import (
     ProviderError,
     RateLimitError,
     ResponseValidationError,
+    RetriesExhausted,
     ServerError,
+    StreamRestarted,
     TimeoutError,
     ToolError,
     ToolExecutionError,
@@ -144,6 +147,25 @@ from .responses import (
     Usage,
     UsageDeltaChunk,
 )
+from .retries import (
+    AsyncContextRetryResponse,
+    AsyncContextRetryStreamResponse,
+    AsyncRetryCall,
+    AsyncRetryPrompt,
+    AsyncRetryResponse,
+    AsyncRetryStreamResponse,
+    ContextRetryResponse,
+    ContextRetryStreamResponse,
+    RetryCall,
+    RetryConfig,
+    RetryModel,
+    RetryModelParams,
+    RetryPrompt,
+    RetryResponse,
+    RetryStreamResponse,
+    retry,
+    retry_model,
+)
 from .tools import (
     AnyToolFn,
     AnyTools,
@@ -184,12 +206,18 @@ __all__ = [
     "AsyncContextCall",
     "AsyncContextPrompt",
     "AsyncContextResponse",
+    "AsyncContextRetryResponse",
+    "AsyncContextRetryStreamResponse",
     "AsyncContextStreamResponse",
     "AsyncContextTool",
     "AsyncContextToolkit",
     "AsyncContextTools",
     "AsyncPrompt",
     "AsyncResponse",
+    "AsyncRetryCall",
+    "AsyncRetryPrompt",
+    "AsyncRetryResponse",
+    "AsyncRetryStreamResponse",
     "AsyncStream",
     "AsyncStreamResponse",
     "AsyncTextStream",
@@ -212,6 +240,8 @@ __all__ = [
     "ContextCall",
     "ContextPrompt",
     "ContextResponse",
+    "ContextRetryResponse",
+    "ContextRetryStreamResponse",
     "ContextStreamResponse",
     "ContextTool",
     "ContextToolkit",
@@ -249,11 +279,20 @@ __all__ = [
     "RawMessageChunk",
     "Response",
     "ResponseValidationError",
+    "RetriesExhausted",
+    "RetryCall",
+    "RetryConfig",
+    "RetryModel",
+    "RetryModelParams",
+    "RetryPrompt",
+    "RetryResponse",
+    "RetryStreamResponse",
     "RootResponse",
     "ServerError",
     "Stream",
     "StreamResponse",
     "StreamResponseChunk",
+    "StreamRestarted",
     "SystemContent",
     "SystemMessage",
     "Text",
@@ -309,6 +348,9 @@ __all__ = [
     "register_provider",
     "reset_provider_registry",
     "responses",
+    "retries",
+    "retry",
+    "retry_model",
     "tool",
     "tools",
     "types",

mirascope/llm/calls/calls.py

@@ -1,7 +1,6 @@
 """The Call module for generating responses using LLMs."""
 
 from collections.abc import Callable
-from dataclasses import dataclass, field
 from typing import Any, Generic, TypeVar, overload
 
 from ..._utils import copy_function_metadata
@@ -31,7 +30,6 @@ PromptT = TypeVar("PromptT", bound=BasePrompt[Callable[..., Any]])
 CallT = TypeVar("CallT", bound="BaseCall[Any]")
 
 
-@dataclass(kw_only=True)
 class BaseCall(Generic[PromptT]):
     """Base class for all Call types with shared model functionality."""
 
@@ -41,20 +39,20 @@ class BaseCall(Generic[PromptT]):
     prompt: PromptT
     """The underlying Prompt instance that generates messages with tools and format."""
 
-    __name__: str = field(init=False, repr=False, default="")
+    __name__: str = ""
     """The name of the underlying function (preserved for decorator stacking)."""
 
+    def __init__(self, *, default_model: Model, prompt: PromptT) -> None:
+        self.default_model = default_model
+        self.prompt = prompt
+        copy_function_metadata(self, self.prompt.fn)
+
     @property
     def model(self) -> Model:
         """The model used for generating responses. May be overwritten via `with llm.model(...)`."""
         return use_model(self.default_model)
 
-    def __post_init__(self) -> None:
-        """Preserve standard function attributes for decorator stacking."""
-        copy_function_metadata(self, self.prompt.fn)
-
 
-@dataclass
 class Call(BaseCall[Prompt[P, FormattableT]], Generic[P, FormattableT]):
     """A call that directly generates LLM responses without requiring a model argument.
 
@@ -67,6 +65,14 @@ class Call(BaseCall[Prompt[P, FormattableT]], Generic[P, FormattableT]):
     The model can be overridden at runtime using `with llm.model(...)` context manager.
     """
 
+    def __init__(
+        self,
+        *,
+        default_model: Model,
+        prompt: Prompt[P, FormattableT],
+    ) -> None:
+        super().__init__(default_model=default_model, prompt=prompt)
+
     @overload
     def __call__(
         self: "Call[P, None]", *args: P.args, **kwargs: P.kwargs
@@ -114,7 +120,6 @@ class Call(BaseCall[Prompt[P, FormattableT]], Generic[P, FormattableT]):
         return self.prompt.stream(self.model, *args, **kwargs)
 
 
-@dataclass
 class AsyncCall(BaseCall[AsyncPrompt[P, FormattableT]], Generic[P, FormattableT]):
     """An async call that directly generates LLM responses without requiring a model argument.
 
@@ -127,6 +132,14 @@ class AsyncCall(BaseCall[AsyncPrompt[P, FormattableT]], Generic[P, FormattableT]
     The model can be overridden at runtime using `with llm.model(...)` context manager.
     """
 
+    def __init__(
+        self,
+        *,
+        default_model: Model,
+        prompt: AsyncPrompt[P, FormattableT],
+    ) -> None:
+        super().__init__(default_model=default_model, prompt=prompt)
+
     @overload
     async def __call__(
         self: "AsyncCall[P, None]", *args: P.args, **kwargs: P.kwargs
@@ -176,7 +189,6 @@ class AsyncCall(BaseCall[AsyncPrompt[P, FormattableT]], Generic[P, FormattableT]
         return await self.prompt.stream(self.model, *args, **kwargs)
 
 
-@dataclass
 class ContextCall(
     BaseCall[ContextPrompt[P, DepsT, FormattableT]], Generic[P, DepsT, FormattableT]
 ):
@@ -192,6 +204,14 @@ class ContextCall(
     The model can be overridden at runtime using `with llm.model(...)` context manager.
     """
 
+    def __init__(
+        self,
+        *,
+        default_model: Model,
+        prompt: ContextPrompt[P, DepsT, FormattableT],
+    ) -> None:
+        super().__init__(default_model=default_model, prompt=prompt)
+
     @overload
     def __call__(
         self: "ContextCall[P, DepsT, None]",
@@ -261,7 +281,6 @@ class ContextCall(
         return self.prompt.stream(self.model, ctx, *args, **kwargs)
 
 
-@dataclass
 class AsyncContextCall(
     BaseCall[AsyncContextPrompt[P, DepsT, FormattableT]],
     Generic[P, DepsT, FormattableT],
@@ -278,6 +297,14 @@ class AsyncContextCall(
     The model can be overridden at runtime using `with llm.model(...)` context manager.
     """
 
+    def __init__(
+        self,
+        *,
+        default_model: Model,
+        prompt: AsyncContextPrompt[P, DepsT, FormattableT],
+    ) -> None:
+        super().__init__(default_model=default_model, prompt=prompt)
+
     @overload
     async def __call__(
         self: "AsyncContextCall[P, DepsT, None]",

mirascope/llm/exceptions.py

@@ -7,6 +7,7 @@ from pydantic import ValidationError
 
 if TYPE_CHECKING:
     from .providers import ModelId, ProviderId
+    from .retries.utils import RetryFailure
 
 
 class Error(Exception):
@@ -358,3 +359,71 @@ class MissingAPIKeyError(Error):
         super().__init__(message)
         self.provider_id = provider_id
         self.env_var = env_var
+
+
+class RetriesExhausted(Error):
+    """Raised when all retry attempts (including fallback models) have been exhausted.
+
+    This exception preserves the full failure history, allowing users to inspect
+    what went wrong at each attempt.
+
+    Example:
+        ```python
+        try:
+            response = retry_model.generate("Tell me a story")
+        except llm.RetriesExhausted as e:
+            print(f"Failed after {len(e.failures)} attempts:")
+            for failure in e.failures:
+                print(f"  - {failure.model.model}: {failure.exception}")
+        ```
+    """
+
+    failures: list["RetryFailure"]
+    """All failed attempts, in order. The last failure triggered exhaustion."""
+
+    def __init__(self, failures: list["RetryFailure"]) -> None:
+        model_names = [f.model.model_id for f in failures]
+        message = (
+            f"All retries exhausted after {len(failures)} attempt(s) "
+            f"across models: {model_names}"
+        )
+        super().__init__(message)
+        self.failures = failures
+        # Chain to the last error for standard traceback behavior
+        if failures:
+            self.__cause__ = failures[-1].exception
+
+
+class StreamRestarted(Error):
+    """Raised when a stream restarts due to a retryable error.
+
+    This exception signals that the stream encountered an error and has been
+    reset for a retry attempt. Users should catch this exception and re-iterate
+    the response to continue streaming from the new attempt.
+
+    Example:
+        ```python
+        response = retry_call.stream("fantasy")
+
+        while True:
+            try:
+                for chunk in response.text_stream():
+                    print(chunk, end="", flush=True)
+                break  # Success
+            except llm.StreamRestarted as e:
+                print(e.message)
+                # Loop continues, re-iterates the response
+        ```
+    """
+
+    failure: "RetryFailure"
+    """The failure that triggered the restart."""
+
+    def __init__(
+        self,
+        failure: "RetryFailure",
+    ) -> None:
+        message = f"Stream restarted due to: {failure.exception}"
+        super().__init__(message)
+        self.failure = failure
+        self.__cause__ = failure.exception