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

mirascope/llm/responses/base_stream_response.py

@@ -20,7 +20,12 @@ from ..content import (
     ToolCallEndChunk,
     ToolCallStartChunk,
 )
-from ..formatting import Format, FormattableT, Partial
+from ..formatting import (
+    Format,
+    FormattableT,
+    Partial,
+    is_output_parser,
+)
 from ..messages import AssistantMessage, Message
 from ..tools import FORMAT_TOOL_NAME, ToolkitT
 from ..types import Jsonable
@@ -39,7 +44,11 @@ from .streams import (
 from .usage import Usage, UsageDeltaChunk
 
 if TYPE_CHECKING:
-    from ..providers import ModelId, Params, ProviderId
+    from ..models import Params
+    from ..providers import ModelId, ProviderId
+
+
+StreamResponseT = TypeVar("StreamResponseT", bound="BaseStreamResponse[Any, Any, Any]")
 
 
 @dataclass(kw_only=True)
@@ -505,6 +514,26 @@ class BaseSyncStreamResponse(BaseStreamResponse[ChunkIterator, ToolkitT, Formatt
         for _ in self.chunk_stream():
             pass
 
+    def text_stream(self, sep: str = "\n") -> Iterator[str]:
+        """Stream only the text content from the response.
+
+        Args:
+            sep: Separator to yield between text parts. Defaults to newline.
+
+        Returns:
+            Iterator[str]: Iterator yielding text delta strings
+
+        Yields text deltas as they arrive, ignoring thoughts, tool calls, and other
+        content types. Ideal for displaying text to users in real-time.
+
+        If you concatenate the strings from `.text_stream()`, it will be equivalent to
+        calling `.text(sep=sep)` on the fully consumed response.
+        """
+        for stream in self.streams():
+            if stream.content_type == "text":
+                yield from stream
+                yield sep
+
     def pretty_stream(self) -> Iterator[str]:
         """Stream a readable representation of the stream_response as text.
 
@@ -527,26 +556,46 @@ class BaseSyncStreamResponse(BaseStreamResponse[ChunkIterator, ToolkitT, Formatt
                 printed = True
             yield pretty
 
-        if not printed:
-            yield "**[No Content]**"
-
     def structured_stream(
         self,
     ) -> Iterator[Partial[FormattableT]]:
-        """Returns an iterator that yields partial structured objects as content streams.
+        """Drive the stream forward, yielding partial formatted outputs as they arrive.
 
-        Returns:
-            Iterator[Partial[FormatT]]: Synchronous iterator yielding partial structured objects
+        This method consumes the underlying stream chunk by chunk, yielding parsed
+        partial outputs each time new content arrives. Each yielded value is a
+        Partial[FormattableT] with optional fields that may be None until fully received.
 
-        This method yields Partial[FormatT] objects as the response content is streamed,
-        allowing you to access partial structured data before the response is fully complete.
-        Each yielded object represents the current state of the parsed structure with all
-        fields optional.
+        Example:
+            >>> response = recommend_book.stream("fantasy")
+            >>> for partial in response.structured_stream():
+            >>>     print(f"Title so far: {partial.title}")
+            >>> book = response.parse()  # Get final complete result
 
         Fully iterating through this iterator will fully consume the underlying stream,
         updating the Response with all collected content.
+
+        Yields:
+            Partial[FormattableT]: Partial objects with fields populated as they arrive.
+                Fields not yet received will be None.
+
+        Raises:
+            ValueError: If format parameter not set.
+            NotImplementedError: If format uses OutputParser (not supported).
         """
-        raise NotImplementedError()
+        if self.format is None:
+            raise ValueError("structured_stream() requires format parameter")
+
+        if is_output_parser(self.format.formattable):
+            raise NotImplementedError(
+                "structured_stream() not supported for OutputParser. "
+                "Use BaseModel or primitive types."
+            )
+
+        for chunk in self.chunk_stream():
+            if chunk.type == "text_chunk":
+                partial = self.parse(partial=True)
+                if partial:
+                    yield partial
 
 
 class BaseAsyncStreamResponse(
@@ -686,6 +735,27 @@ class BaseAsyncStreamResponse(
         async for _ in self.chunk_stream():
             pass
 
+    async def text_stream(self, sep: str = "\n") -> AsyncIterator[str]:
+        """Stream only the text content from the response.
+
+        Args:
+            sep: Separator to yield between text parts. Defaults to newline.
+
+        Returns:
+            AsyncIterator[str]: Async iterator yielding text delta strings
+
+        Yields text deltas as they arrive, ignoring thoughts, tool calls, and other
+        content types. Ideal for displaying text to users in real-time.
+
+        If you concatenate the strings from `.text_stream()`, it will be equivalent to
+        calling `.text(sep=sep)` on the fully consumed response.
+        """
+        async for stream in self.streams():
+            if stream.content_type == "text":
+                async for delta in stream:
+                    yield delta
+                yield sep
+
     async def pretty_stream(self) -> AsyncIterator[str]:
         """Stream a readable representation of the stream_response as text.
 
@@ -708,23 +778,43 @@ class BaseAsyncStreamResponse(
                 printed = True
             yield pretty
 
-        if not printed:
-            yield "**[No Content]**"
-
-    def structured_stream(
+    async def structured_stream(
         self,
     ) -> AsyncIterator[Partial[FormattableT]]:
-        """Returns an async iterator that yields partial structured objects as content streams.
+        """Drive the stream forward, yielding partial formatted outputs as they arrive.
 
-        Returns:
-            AsyncIterator[Partial[FormatT]]: Async iterator yielding partial structured objects
+        This method consumes the underlying stream chunk by chunk, yielding parsed
+        partial outputs each time new content arrives. Each yielded value is a
+        Partial[FormattableT] with optional fields that may be None until fully received.
 
-        This method yields Partial[FormatT] objects as the response content is streamed,
-        allowing you to access partial structured data before the response is fully complete.
-        Each yielded object represents the current state of the parsed structure with all
-        fields optional.
+        Example:
+            >>> response = await recommend_book.stream("fantasy")
+            >>> async for partial in response.structured_stream():
+            >>>     print(f"Title so far: {partial.title}")
+            >>> book = response.parse()  # Get final complete result
 
         Fully iterating through this iterator will fully consume the underlying stream,
         updating the Response with all collected content.
+
+        Yields:
+            Partial[FormattableT]: Partial objects with fields populated as they arrive.
+                Fields not yet received will be None.
+
+        Raises:
+            ValueError: If format parameter not set.
+            NotImplementedError: If format uses OutputParser (not supported).
         """
-        raise NotImplementedError()
+        if self.format is None:
+            raise ValueError("structured_stream() requires format parameter")
+
+        if is_output_parser(self.format.formattable):
+            raise NotImplementedError(
+                "structured_stream() not supported for OutputParser. "
+                "Use BaseModel or primitive types."
+            )
+
+        async for chunk in self.chunk_stream():
+            if chunk.type == "text_chunk":
+                partial = self.parse(partial=True)
+                if partial:
+                    yield partial

mirascope/llm/responses/response.py

@@ -24,7 +24,8 @@ from .finish_reason import FinishReason
 from .usage import Usage
 
 if TYPE_CHECKING:
-    from ..providers import ModelId, Params, ProviderId
+    from ..models import Params
+    from ..providers import ModelId, ProviderId
 
 
 class Response(BaseResponse[Toolkit, FormattableT]):

mirascope/llm/responses/root_response.py

@@ -3,10 +3,18 @@
 from abc import ABC
 from collections.abc import Sequence
 from types import NoneType
-from typing import TYPE_CHECKING, Any, Generic, Literal, overload
+from typing import TYPE_CHECKING, Any, Generic, Literal, TypeAlias, overload
 
 from ..content import AssistantContentPart, Text, Thought, ToolCall
-from ..formatting import Format, FormattableT, Partial
+from ..exceptions import ParseError
+from ..formatting import (
+    Format,
+    FormattableT,
+    Partial,
+    create_wrapper_model,
+    is_output_parser,
+    is_primitive_type,
+)
 from ..messages import Message
 from ..tools import ToolkitT
 from . import _utils
@@ -14,8 +22,10 @@ from .finish_reason import FinishReason
 from .usage import Usage
 
 if TYPE_CHECKING:
-    from ..models import Model
-    from ..providers import ModelId, Params, ProviderId
+    from ..models import Model, Params
+    from ..providers import ModelId, ProviderId
+
+AnyResponse: TypeAlias = "RootResponse[Any, Any]"
 
 
 class RootResponse(Generic[ToolkitT, FormattableT], ABC):
@@ -107,31 +117,96 @@ class RootResponse(Generic[ToolkitT, FormattableT], ABC):
     ) -> FormattableT | Partial[FormattableT] | None:
         """Format the response according to the response format parser.
 
+        Args:
+            partial: If True, parse incomplete JSON as Partial model. Only works with
+                streaming responses that have accumulated JSON. Returns None if JSON
+                is not yet available or cannot be parsed.
+
+        Supports:
+        - Pydantic BaseModel types (JSON schema validation)
+        - Primitive types (automatically unwrapped from wrapper model)
+        - Custom OutputParsers (custom parsing logic)
+        - Partial parsing during streaming (when partial=True)
+
         Returns:
-            The formatted response object of type FormatT.
+            The formatted response object of type FormatT. For BaseModel types, returns
+            the model instance. For primitive types, returns the unwrapped value (e.g.,
+            a string, list, dict, etc.). For OutputParsers, returns whatever the parser
+            returns. When partial=True, returns None if JSON is incomplete or unparsable.
 
         Raises:
-            json.JSONDecodeError: If the response's textual content can't be parsed as
-                JSON.
-            pydantic.ValidationError: If the response's content fails validation for the
-                format type.
+            NotImplementedError: If partial=True with OutputParser.
+            ParseError: If parsing fails. The `original_exception` attribute contains the
+                underlying error (ValueError for JSON extraction, json.JSONDecodeError
+                for invalid JSON, pydantic.ValidationError for schema validation, or
+                any exception from a custom OutputParser).
         """
         if self.format is None:
             return None
 
         formattable = self.format.formattable
+
+        if is_output_parser(formattable):
+            if partial:
+                raise NotImplementedError(
+                    "parse(partial=True) not supported with OutputParser. "
+                    "Use BaseModel or primitive types."
+                )
+            try:
+                return formattable(self)
+            except Exception as e:
+                raise ParseError(
+                    f"OutputParser failed: {e}",
+                    original_exception=e,
+                ) from e
+
         if formattable is None or formattable is NoneType:  # pyright: ignore[reportUnnecessaryComparison]
             # note: pyright claims the None comparison is unnecessary, but removing it
             # introduces type errors.
             return None  # pragma: no cover
 
-        if partial:
-            raise NotImplementedError
+        text = self.text("")
 
-        text = "".join(text.text for text in self.texts)
-        json_text = _utils.extract_serialized_json(text)
+        if partial:
+            return _utils.parse_partial_json(text, formattable)
+        else:
+            try:
+                json_text = _utils.extract_serialized_json(text)
+                if is_primitive_type(formattable):
+                    wrapper_model = create_wrapper_model(formattable)
+                    wrapper_instance = wrapper_model.model_validate_json(json_text)
+                    return wrapper_instance.output
+
+                return formattable.model_validate_json(json_text)
+            except Exception as e:
+                raise ParseError(
+                    f"Failed to parse response: {e}",
+                    original_exception=e,
+                ) from e
+
+    def text(self, sep: str = "\n") -> str:
+        """Return all text content from this response as a single string.
+
+        Joins the text from all `Text` parts in the response content using the
+        specified separator.
+
+        Args:
+            sep: The separator to use when joining multiple text parts.
+                Defaults to newline ("\\n").
 
-        return formattable.model_validate_json(json_text)
+        Returns:
+            A string containing all text content joined by the separator.
+            Returns an empty string if the response contains no text parts.
+
+        Example:
+            >>> response.text()  # Join with newlines (default)
+            'Hello\\nWorld'
+            >>> response.text(sep=" ")  # Join with spaces
+            'Hello World'
+            >>> response.text(sep="")  # Concatenate directly
+            'HelloWorld'
+        """
+        return sep.join(text.text for text in self.texts)
 
     def pretty(self) -> str:
         """Return a string representation of all response content.
@@ -147,9 +222,6 @@ class RootResponse(Generic[ToolkitT, FormattableT], ABC):
 
         I am going to use the calculator and answer your question for you!
         """
-        if not self.content:
-            return "**[No Content]**"
-
         pretty_parts: list[str] = []
         for part in self.content:
             if isinstance(part, Text):

mirascope/llm/responses/stream_response.py

@@ -27,7 +27,8 @@ from .base_stream_response import (
 )
 
 if TYPE_CHECKING:
-    from ..providers import ModelId, Params, ProviderId
+    from ..models import Params
+    from ..providers import ModelId, ProviderId
 
 
 class StreamResponse(BaseSyncStreamResponse[Toolkit, FormattableT]):
@@ -85,9 +86,8 @@ class StreamResponse(BaseSyncStreamResponse[Toolkit, FormattableT]):
 
         stream_response = answer_question.stream("What is the capital of France?")
 
-        for chunk in stream_response.pretty_stream():
+        for chunk in stream_response.text_stream():
             print(chunk, end="", flush=True)
-        print()
         ```
     """
 
@@ -212,9 +212,8 @@ class AsyncStreamResponse(BaseAsyncStreamResponse[AsyncToolkit, FormattableT]):
 
         stream_response = await answer_question.stream("What is the capital of France?")
 
-        async for chunk in stream_response.pretty_stream():
+        async for chunk in stream_response.text_stream():
             print(chunk, end="", flush=True)
-        print()
         ```
     """
 
@@ -348,9 +347,8 @@ class ContextStreamResponse(
         ctx = llm.Context()
         stream_response = answer_question.stream(ctx, "What is the capital of France?")
 
-        for chunk in stream_response.pretty_stream():
+        for chunk in stream_response.text_stream():
             print(chunk, end="", flush=True)
-        print()
         ```
     """
 
@@ -492,9 +490,8 @@ class AsyncContextStreamResponse(
         ctx = llm.Context()
         stream_response = await answer_question.stream(ctx, "What is the capital of France?")
 
-        async for chunk in stream_response.pretty_stream():
+        async for chunk in stream_response.text_stream():
             print(chunk, end="", flush=True)
-        print()
         ```
     """
 

mirascope/llm/tools/decorator.py

@@ -14,8 +14,12 @@ from .tools import AsyncContextTool, AsyncTool, ContextTool, Tool
 class ToolDecorator:
     """Protocol for the tool decorator."""
 
-    strict: bool
-    """Whether to use strict tool calling, if supported by the provider."""
+    strict: bool | None = None
+    """Whether to use strict tool calling, if supported by the provider.
+    
+    If set to None, then it will use the provider's default setting (usually the 
+    strictest possible).
+    """
 
     @overload
     def __call__(  # pyright:ignore[reportOverlappingOverload]
@@ -106,7 +110,7 @@ def tool(__fn: ToolFn[P, JsonableCovariantT]) -> Tool[P, JsonableCovariantT]:
 
 
 @overload
-def tool(*, strict: bool = False) -> ToolDecorator:
+def tool(*, strict: bool | None = None) -> ToolDecorator:
     """Overload for setting non-default arguments."""
     ...
 
@@ -118,7 +122,7 @@ def tool(
     | AsyncToolFn[P, JsonableCovariantT]
     | None = None,
     *,
-    strict: bool = False,
+    strict: bool | None = None,
 ) -> (
     ContextTool[DepsT, JsonableCovariantT, P]
     | AsyncContextTool[DepsT, JsonableCovariantT, P]
@@ -137,6 +141,7 @@ def tool(
 
     Args:
         strict: Whether the tool should use strict mode when supported by the model.
+            If None, uses provider's default (usually as strict as possible).
 
     Returns:
         A decorator function that converts the function into a Tool or ContextTool.

mirascope/llm/tools/tool_schema.py

@@ -22,6 +22,7 @@ from docstring_parser import parse
 from pydantic import BaseModel, Field, create_model
 from pydantic.fields import FieldInfo
 
+from ..._utils import copy_function_metadata
 from ..content import ToolCall
 from ..types import Jsonable
 from .protocols import AsyncContextToolFn, AsyncToolFn, ContextToolFn, ToolFn
@@ -157,8 +158,15 @@ class ToolSchema(Generic[ToolFnT]):
     it should **not be modified** after the ToolSchema is created.
     """
 
-    strict: bool
-    """Whether the tool should use strict mode when supported by the model."""
+    strict: bool | None
+    """Whether the tool should use strict mode when supported by the model.
+
+    If set to None, will use the provider's default setting (usually as strict as
+    possible).
+    """
+
+    __name__: str
+    """The name of the underlying function (preserved for decorator stacking)."""
 
     def __hash__(self) -> int:
         if not hasattr(self, "_hash"):
@@ -179,7 +187,7 @@ class ToolSchema(Generic[ToolFnT]):
         description: str,
         parameters: ToolParameterSchema,
         *,
-        strict: bool = False,
+        strict: bool | None = None,
     ) -> None:
         """Create a `ToolSchema` with the provided values.
 
@@ -188,20 +196,22 @@ class ToolSchema(Generic[ToolFnT]):
             name: The name of the tool
             description: Description of what the tool does
             parameters: JSON Schema describing the parameters accepted by the tool
-            strict: Whether the tool should use strict mode when supported
+            strict: Whether the tool should use strict mode when supported.
+                If None, uses provider's default (usually as strict as possible).
         """
         self.fn = fn
         self.name = name
         self.description = description
         self.parameters = parameters
         self.strict = strict
+        copy_function_metadata(self, fn)
 
     @classmethod
     def from_function(
         cls,
         fn: AnyToolFn,
         *,
-        strict: bool = False,
+        strict: bool | None = None,
         is_context_tool: bool = False,
     ) -> ToolSchema[AnyToolFn]:
         """Create a `ToolSchema` by inspecting a function and its docstring.
@@ -212,7 +222,8 @@ class ToolSchema(Generic[ToolFnT]):
 
         Args:
             fn: The function to extract schema from
-            strict: Whether the tool should use strict mode when supported
+            strict: Whether the tool should use strict mode when supported.
+                If None, uses provider's default (usually as strict as possible).
             is_context_tool: Whether this is a context tool (skips the context parameter)
 
         Returns:

mirascope/llm/tools/toolkit.py

@@ -60,7 +60,7 @@ class BaseToolkit(Generic[ToolSchemaT]):
         """
         tool = self.tools_dict.get(tool_call.name, None)
         if not tool:
-            raise ToolNotFoundError(f"Tool not found in toolkit: {tool_call.name}")
+            raise ToolNotFoundError(tool_call.name)
         return tool
 
 
@@ -75,12 +75,14 @@ class Toolkit(BaseToolkit[Tool]):
 
         Returns:
             The output from executing the `Tool`.
-
-        Raises:
-            ToolNotFoundError: If the requested tool is not found.
         """
-        tool = self.get(tool_call)
-        return tool.execute(tool_call)
+        try:
+            tool = self.get(tool_call)
+            return tool.execute(tool_call)
+        except ToolNotFoundError as e:
+            return ToolOutput(
+                id=tool_call.id, result=str(e), error=e, name=tool_call.name
+            )
 
 
 class AsyncToolkit(BaseToolkit[AsyncTool]):
@@ -94,12 +96,14 @@ class AsyncToolkit(BaseToolkit[AsyncTool]):
 
         Returns:
             The output from executing the `AsyncTool`.
-
-        Raises:
-            ToolNotFoundError: If the requested tool is not found.
         """
-        tool = self.get(tool_call)
-        return await tool.execute(tool_call)
+        try:
+            tool = self.get(tool_call)
+            return await tool.execute(tool_call)
+        except ToolNotFoundError as e:
+            return ToolOutput(
+                id=tool_call.id, result=str(e), error=e, name=tool_call.name
+            )
 
 
 class ContextToolkit(BaseToolkit[Tool | ContextTool[DepsT]], Generic[DepsT]):
@@ -114,15 +118,17 @@ class ContextToolkit(BaseToolkit[Tool | ContextTool[DepsT]], Generic[DepsT]):
 
         Returns:
             The output from executing the `ContextTool`.
-
-        Raises:
-            ToolNotFoundError: If the requested tool is not found.
         """
-        tool = self.get(tool_call)
-        if isinstance(tool, ContextTool):
-            return tool.execute(ctx, tool_call)
-        else:
-            return tool.execute(tool_call)
+        try:
+            tool = self.get(tool_call)
+            if isinstance(tool, ContextTool):
+                return tool.execute(ctx, tool_call)
+            else:
+                return tool.execute(tool_call)
+        except ToolNotFoundError as e:
+            return ToolOutput(
+                id=tool_call.id, result=str(e), error=e, name=tool_call.name
+            )
 
 
 class AsyncContextToolkit(
@@ -141,12 +147,14 @@ class AsyncContextToolkit(
 
         Returns:
             The output from executing the `AsyncContextTool`.
-
-        Raises:
-            ToolNotFoundError: If the requested tool is not found.
         """
-        tool = self.get(tool_call)
-        if isinstance(tool, AsyncContextTool):
-            return await tool.execute(ctx, tool_call)
-        else:
-            return await tool.execute(tool_call)
+        try:
+            tool = self.get(tool_call)
+            if isinstance(tool, AsyncContextTool):
+                return await tool.execute(ctx, tool_call)
+            else:
+                return await tool.execute(tool_call)
+        except ToolNotFoundError as e:
+            return ToolOutput(
+                id=tool_call.id, result=str(e), error=e, name=tool_call.name
+            )