mirascope 2.0.0a5__py3-none-any.whl → 2.0.1__py3-none-any.whl

mirascope/llm/responses/_utils.py

@@ -1,20 +1,34 @@
-def extract_serialized_json(text: str) -> str:
-    """Extract the serialized JSON string from text that may contain extra content.
+"""Utilities for response classes."""
+
+import json
+from typing import cast
+
+import jiter
+from pydantic import BaseModel
+
+from ..formatting import (
+    FormattableT,
+    Partial,
+    PrimitiveWrapperModel,
+    create_wrapper_model,
+    is_primitive_type,
+)
+
+
+def _strip_json_preamble(text: str) -> str | None:
+    """Strip preamble text before JSON content.
 
     Handles cases where models output text before JSON like:
-    "Sure thing! Here's the JSON:\n{...}"
+    "Sure thing! Here's the JSON:\n{..."
 
     Or cases where the model wraps the JSON in code blocks like:
-    "```json\n{...}\n```"
+    "```json\n{..."
 
     Args:
         text: The raw text that may contain a JSON object
 
-    Raises:
-        ValueError: If no serialized json object string was found.
-
     Returns:
-        The extracted serialized JSON string
+        Text starting from the opening `{`, or None if no `{` found.
     """
     code_block_start_marker = "```json"
     code_block_start = text.find(code_block_start_marker)
@@ -25,14 +39,39 @@ def extract_serialized_json(text: str) -> str:
 
     json_start = text.find("{")
     if json_start == -1:
-        raise ValueError("Could not extract json: no opening `{`")
+        return None
+
+    return text[json_start:]
+
+
+def extract_serialized_json(text: str) -> str:
+    """Extract the serialized JSON string from text that may contain extra content.
+
+    Handles cases where models output text before JSON like:
+    "Sure thing! Here's the JSON:\n{...}"
+
+    Or cases where the model wraps the JSON in code blocks like:
+    "```json\n{...}\n```"
+
+    Args:
+        text: The raw text that may contain a JSON object
+
+    Raises:
+        json.JSONDecodeError: If no valid JSON object could be extracted.
+
+    Returns:
+        The extracted serialized JSON string
+    """
+    stripped = _strip_json_preamble(text)
+    if stripped is None:
+        raise json.JSONDecodeError("No JSON object found: missing '{'", text, 0)
 
     # Find the matching closing brace
     brace_count = 0
     in_string = False
     escaped = False
 
-    for i, char in enumerate(text[json_start:], json_start):
+    for i, char in enumerate(stripped):
         if escaped:
             escaped = False
             continue
@@ -51,6 +90,57 @@ def extract_serialized_json(text: str) -> str:
             elif char == "}":
                 brace_count -= 1
                 if brace_count == 0:
-                    return text[json_start : i + 1]
+                    return stripped[: i + 1]
+
+    raise json.JSONDecodeError("No JSON object found: missing '}'", text, len(text))
+
+
+def parse_partial_json(
+    json_text: str, formattable: type[FormattableT]
+) -> FormattableT | Partial[FormattableT] | None:
+    """Parse incomplete JSON into a Partial model for structured streaming.
+
+    Uses jiter's partial mode to handle incomplete JSON gracefully.
+    Returns None if JSON cannot be parsed yet.
+
+    Handles cases where models output text before JSON like:
+    "Sure thing! Here's the JSON:\n{..."
+
+    Args:
+        json_text: The incomplete JSON string to parse
+        formattable: The target format type (BaseModel or PrimitiveType)
+
+    Returns:
+        Parsed partial object, or None if unparsable
+
+    Example:
+        >>> from pydantic import BaseModel
+        >>> class Book(BaseModel):
+        ...     title: str
+        ...     author: str
+        >>> parse_partial_json('{"title": "The Name"', Book)
+        PartialBook(title='The Name', author=None)
+    """
+    # Strip preamble text before JSON
+    stripped = _strip_json_preamble(json_text)
+    if stripped is None:
+        return None
+
+    try:
+        parsed = jiter.from_json(stripped.encode(), partial_mode="trailing-strings")
+    except Exception:
+        return None
+
+    target_model = formattable
+    if is_primitive_type(target_model):
+        target_model = cast(BaseModel, create_wrapper_model(target_model))
+
+    try:
+        instance = cast(BaseModel, Partial[target_model]).model_validate(parsed)
+    except Exception:
+        return None
+
+    if is_primitive_type(formattable):
+        return cast(PrimitiveWrapperModel, instance).output
 
-    raise ValueError("Could not extract json: no closing `}`")
+    return cast(Partial[FormattableT], instance)

mirascope/llm/responses/base_response.py

@@ -1,7 +1,7 @@
 """Shared base of Response and AsyncResponse."""
 
 from collections.abc import Sequence
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, TypeVar
 
 from ..content import Text, Thought, ToolCall
 from ..formatting import Format, FormattableT
@@ -12,7 +12,10 @@ from .root_response import RootResponse
 from .usage import Usage
 
 if TYPE_CHECKING:
-    from ..providers import ModelId, Params, ProviderId
+    from ..models import Params
+    from ..providers import ModelId, ProviderId
+
+ResponseT = TypeVar("ResponseT", bound="BaseResponse[Any, Any]")
 
 
 class BaseResponse(RootResponse[ToolkitT, FormattableT]):

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)
@@ -227,7 +236,8 @@ class BaseStreamResponse(
         self.messages = list(input_messages) + [self._assistant_message]
 
         self._chunk_iterator = chunk_iterator
-        self._current_content: Text | Thought | ToolCall | None = None
+        self._current_content: Text | Thought | None = None
+        self._current_tool_calls: dict[str, ToolCall] = {}
 
         self._processing_format_tool: bool = False
 
@@ -269,7 +279,7 @@ class BaseStreamResponse(
         self, chunk: TextStartChunk | TextChunk | TextEndChunk
     ) -> None:
         if chunk.type == "text_start_chunk":
-            if self._current_content:
+            if self._current_content or self._current_tool_calls:
                 raise RuntimeError(
                     "Received text_start_chunk while processing another chunk"
                 )
@@ -292,7 +302,7 @@ class BaseStreamResponse(
         self, chunk: ThoughtStartChunk | ThoughtChunk | ThoughtEndChunk
     ) -> None:
         if chunk.type == "thought_start_chunk":
-            if self._current_content:
+            if self._current_content or self._current_tool_calls:
                 raise RuntimeError(
                     "Received thought_start_chunk while processing another chunk"
                 )
@@ -323,35 +333,38 @@ class BaseStreamResponse(
                 raise RuntimeError(
                     "Received tool_call_start_chunk while processing another chunk"
                 )
-            self._current_content = ToolCall(
+            if chunk.id in self._current_tool_calls:
+                raise RuntimeError("Got tool_call_start_chunk with conflicting id")
+            # Create a new tool call and track it by ID
+            # Multiple tool calls can be in progress simultaneously (interleaved)
+            tool_call = ToolCall(
                 id=chunk.id,
                 name=chunk.name,
                 args="",
             )
+            self._current_tool_calls[chunk.id] = tool_call
 
         elif chunk.type == "tool_call_chunk":
-            if (
-                self._current_content is None
-                or self._current_content.type != "tool_call"
-            ):
+            # Look up the tool call by ID
+            tool_call = self._current_tool_calls.get(chunk.id)
+            if tool_call is None:
                 raise RuntimeError(
-                    "Received tool_call_chunk while not processing tool call."
+                    f"Received tool_call_chunk for unknown tool call ID: {chunk.id}"
                 )
-            self._current_content.args += chunk.delta
+            tool_call.args += chunk.delta
 
         elif chunk.type == "tool_call_end_chunk":
-            if (
-                self._current_content is None
-                or self._current_content.type != "tool_call"
-            ):
+            # Finalize the tool call
+            tool_call = self._current_tool_calls.get(chunk.id)
+            if tool_call is None:
                 raise RuntimeError(
-                    "Received tool_call_end_chunk while not processing tool call."
+                    f"Received tool_call_end_chunk for unknown tool call ID: {chunk.id}"
                 )
-            if not self._current_content.args:
-                self._current_content.args = "{}"
-            self._content.append(self._current_content)
-            self._tool_calls.append(self._current_content)
-            self._current_content = None
+            if not tool_call.args:
+                tool_call.args = "{}"
+            self._content.append(tool_call)
+            self._tool_calls.append(tool_call)
+            del self._current_tool_calls[chunk.id]
 
     def _pretty_chunk(self, chunk: AssistantContentChunk, spacer: str) -> str:
         match chunk.type:
@@ -501,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.
 
@@ -523,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(
@@ -682,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.
 
@@ -704,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()
         ```
     """