mirascope 2.0.0__py3-none-any.whl → 2.0.0a0__py3-none-any.whl

mirascope/llm/responses/__init__.py

@@ -1,18 +1,16 @@
 """The Responses module for LLM responses."""
 
 from . import _utils
-from .base_response import ResponseT
 from .base_stream_response import (
     AsyncChunkIterator,
     ChunkIterator,
     RawMessageChunk,
     RawStreamEventChunk,
     StreamResponseChunk,
-    StreamResponseT,
 )
 from .finish_reason import FinishReason, FinishReasonChunk
 from .response import AsyncContextResponse, AsyncResponse, ContextResponse, Response
-from .root_response import AnyResponse, RootResponse
+from .root_response import RootResponse
 from .stream_response import (
     AsyncContextStreamResponse,
     AsyncStreamResponse,
@@ -29,10 +27,8 @@ from .streams import (
     ThoughtStream,
     ToolCallStream,
 )
-from .usage import Usage, UsageDeltaChunk
 
 __all__ = [
-    "AnyResponse",
     "AsyncChunkIterator",
     "AsyncContextResponse",
     "AsyncContextStreamResponse",
@@ -50,16 +46,12 @@ __all__ = [
     "RawMessageChunk",
     "RawStreamEventChunk",
     "Response",
-    "ResponseT",
     "RootResponse",
     "Stream",
     "StreamResponse",
     "StreamResponseChunk",
-    "StreamResponseT",
     "TextStream",
     "ThoughtStream",
     "ToolCallStream",
-    "Usage",
-    "UsageDeltaChunk",
     "_utils",
 ]

mirascope/llm/responses/_utils.py

@@ -1,34 +1,20 @@
-"""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.
+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{..."
+    "Sure thing! Here's the JSON:\n{...}"
 
     Or cases where the model wraps the JSON in code blocks like:
-    "```json\n{..."
+    "```json\n{...}\n```"
 
     Args:
         text: The raw text that may contain a JSON object
 
+    Raises:
+        ValueError: If no serialized json object string was found.
+
     Returns:
-        Text starting from the opening `{`, or None if no `{` found.
+        The extracted serialized JSON string
     """
     code_block_start_marker = "```json"
     code_block_start = text.find(code_block_start_marker)
@@ -39,39 +25,14 @@ def _strip_json_preamble(text: str) -> str | None:
 
     json_start = text.find("{")
     if json_start == -1:
-        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)
+        raise ValueError("Could not extract json: no opening `{`")
 
     # Find the matching closing brace
     brace_count = 0
     in_string = False
     escaped = False
 
-    for i, char in enumerate(stripped):
+    for i, char in enumerate(text[json_start:], json_start):
         if escaped:
             escaped = False
             continue
@@ -90,57 +51,6 @@ def extract_serialized_json(text: str) -> str:
             elif char == "}":
                 brace_count -= 1
                 if brace_count == 0:
-                    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
+                    return text[json_start : i + 1]
 
-    return cast(Partial[FormattableT], instance)
+    raise ValueError("Could not extract json: no closing `}`")

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, TypeVar
+from typing import TYPE_CHECKING, Any
 
 from ..content import Text, Thought, ToolCall
 from ..formatting import Format, FormattableT
@@ -9,13 +9,9 @@ from ..messages import AssistantMessage, Message
 from ..tools import FORMAT_TOOL_NAME, ToolkitT
 from .finish_reason import FinishReason
 from .root_response import RootResponse
-from .usage import Usage
 
 if TYPE_CHECKING:
-    from ..models import Params
-    from ..providers import ModelId, ProviderId
-
-ResponseT = TypeVar("ResponseT", bound="BaseResponse[Any, Any]")
+    from ..clients import ModelId, Params, Provider
 
 
 class BaseResponse(RootResponse[ToolkitT, FormattableT]):
@@ -25,41 +21,34 @@ class BaseResponse(RootResponse[ToolkitT, FormattableT]):
         self,
         *,
         raw: Any,  # noqa: ANN401
-        provider_id: "ProviderId",
+        provider: "Provider",
         model_id: "ModelId",
-        provider_model_name: str,
         params: "Params",
         toolkit: ToolkitT,
         format: Format[FormattableT] | None = None,
         input_messages: Sequence[Message],
         assistant_message: AssistantMessage,
         finish_reason: FinishReason | None,
-        usage: Usage | None,
     ) -> None:
         """Initialize a Response.
 
         Args:
             raw: The raw response from the LLM.
-            provider: The provider name (e.g. "anthropic", "openai").
+            provider: The provider name (e.g. "anthropic", "openai:completions").
             model_id: The model identifier that generated the response.
-            provider_model_name: Optional provider-specific model name. May include
-                provider-specific additional info (like api mode in "gpt-5:responses").
             params: The params used to generate the response (or None).
             toolkit: Toolkit containing all the tools used to generate the response.
             format: The `Format` for the expected structured output format (or None).
             input_messages: The message history before the final assistant message.
             assistant_message: The final assistant message containing the response content.
             finish_reason: The reason why the LLM finished generating a response.
-            usage: Token usage statistics for the response.
         """
         self.raw = raw
-        self.provider_id = provider_id
+        self.provider = provider
         self.model_id = model_id
-        self.provider_model_name = provider_model_name
         self.params = params
         self.toolkit = toolkit
         self.finish_reason = finish_reason
-        self.usage = usage
         self.format = format
 
         # Process content in the assistant message, organizing it by type and
@@ -95,9 +84,8 @@ class BaseResponse(RootResponse[ToolkitT, FormattableT]):
             assistant_message = AssistantMessage(
                 content=self.content,
                 name=assistant_message.name,
-                provider_id=assistant_message.provider_id,
+                provider=assistant_message.provider,
                 model_id=assistant_message.model_id,
-                provider_model_name=assistant_message.provider_model_name,
                 raw_message=assistant_message.raw_message,
             )
         self.messages = list(input_messages) + [assistant_message]

mirascope/llm/responses/base_stream_response.py

@@ -20,12 +20,7 @@ from ..content import (
     ToolCallEndChunk,
     ToolCallStartChunk,
 )
-from ..formatting import (
-    Format,
-    FormattableT,
-    Partial,
-    is_output_parser,
-)
+from ..formatting import Format, FormattableT, Partial
 from ..messages import AssistantMessage, Message
 from ..tools import FORMAT_TOOL_NAME, ToolkitT
 from ..types import Jsonable
@@ -41,14 +36,9 @@ from .streams import (
     ThoughtStream,
     ToolCallStream,
 )
-from .usage import Usage, UsageDeltaChunk
 
 if TYPE_CHECKING:
-    from ..models import Params
-    from ..providers import ModelId, ProviderId
-
-
-StreamResponseT = TypeVar("StreamResponseT", bound="BaseStreamResponse[Any, Any, Any]")
+    from ..clients import ModelId, Params, Provider
 
 
 @dataclass(kw_only=True)
@@ -86,11 +76,7 @@ class RawMessageChunk:
 
 
 StreamResponseChunk: TypeAlias = (
-    AssistantContentChunk
-    | FinishReasonChunk
-    | RawStreamEventChunk
-    | RawMessageChunk
-    | UsageDeltaChunk
+    AssistantContentChunk | FinishReasonChunk | RawStreamEventChunk | RawMessageChunk
 )
 
 ChunkIterator: TypeAlias = Iterator[StreamResponseChunk]
@@ -171,39 +157,32 @@ class BaseStreamResponse(
     def __init__(
         self,
         *,
-        provider_id: "ProviderId",
+        provider: "Provider",
         model_id: "ModelId",
-        provider_model_name: str,
         params: "Params",
         toolkit: ToolkitT,
         format: Format[FormattableT] | None = None,
         input_messages: Sequence[Message],
         chunk_iterator: ChunkIteratorT,
-        usage: Usage | None = None,
     ) -> None:
         """Initialize the BaseStreamResponse.
 
         Args:
-            provider: The provider name (e.g. "anthropic", "openai").
+            provider: The provider name (e.g. "anthropic", "openai:completions").
             model_id: The model identifier that generated the response.
-            provider_model_name: Optional provider-specific model name. May include
-                provider-specific additional info (like api mode in "gpt-5:responses").
             params: The params used to generate the response (or None).
             toolkit: Toolkit containing all the tools used to generate the response.
             format: The `Format` for the expected structured output format (or None).
             input_messages: The input messages that were sent to the LLM
-            usage: Token usage statistics for the response.
 
         The BaseStreamResponse will process the tuples to build the chunks and raw lists
         as the stream is consumed.
         """
 
-        self.provider_id = provider_id
+        self.provider = provider
         self.model_id = model_id
-        self.provider_model_name = provider_model_name
         self.params = params
         self.toolkit = toolkit
-        self.usage = usage
         self.format = format
 
         # Internal-only lists which we mutate (append) during chunk processing
@@ -227,17 +206,15 @@ class BaseStreamResponse(
 
         self._assistant_message = AssistantMessage(
             content=self._content,
-            provider_id=provider_id,
+            provider=provider,
             model_id=model_id,
-            provider_model_name=provider_model_name,
             raw_message=None,
         )
 
         self.messages = list(input_messages) + [self._assistant_message]
 
         self._chunk_iterator = chunk_iterator
-        self._current_content: Text | Thought | None = None
-        self._current_tool_calls: dict[str, ToolCall] = {}
+        self._current_content: Text | Thought | ToolCall | None = None
 
         self._processing_format_tool: bool = False
 
@@ -279,7 +256,7 @@ class BaseStreamResponse(
         self, chunk: TextStartChunk | TextChunk | TextEndChunk
     ) -> None:
         if chunk.type == "text_start_chunk":
-            if self._current_content or self._current_tool_calls:
+            if self._current_content:
                 raise RuntimeError(
                     "Received text_start_chunk while processing another chunk"
                 )
@@ -302,7 +279,7 @@ class BaseStreamResponse(
         self, chunk: ThoughtStartChunk | ThoughtChunk | ThoughtEndChunk
     ) -> None:
         if chunk.type == "thought_start_chunk":
-            if self._current_content or self._current_tool_calls:
+            if self._current_content:
                 raise RuntimeError(
                     "Received thought_start_chunk while processing another chunk"
                 )
@@ -333,38 +310,35 @@ class BaseStreamResponse(
                 raise RuntimeError(
                     "Received tool_call_start_chunk while processing another chunk"
                 )
-            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(
+            self._current_content = ToolCall(
                 id=chunk.id,
                 name=chunk.name,
                 args="",
             )
-            self._current_tool_calls[chunk.id] = tool_call
 
         elif chunk.type == "tool_call_chunk":
-            # Look up the tool call by ID
-            tool_call = self._current_tool_calls.get(chunk.id)
-            if tool_call is None:
+            if (
+                self._current_content is None
+                or self._current_content.type != "tool_call"
+            ):
                 raise RuntimeError(
-                    f"Received tool_call_chunk for unknown tool call ID: {chunk.id}"
+                    "Received tool_call_chunk while not processing tool call."
                 )
-            tool_call.args += chunk.delta
+            self._current_content.args += chunk.delta
 
         elif chunk.type == "tool_call_end_chunk":
-            # Finalize the tool call
-            tool_call = self._current_tool_calls.get(chunk.id)
-            if tool_call is None:
+            if (
+                self._current_content is None
+                or self._current_content.type != "tool_call"
+            ):
                 raise RuntimeError(
-                    f"Received tool_call_end_chunk for unknown tool call ID: {chunk.id}"
+                    "Received tool_call_end_chunk while not processing tool call."
                 )
-            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]
+            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
 
     def _pretty_chunk(self, chunk: AssistantContentChunk, spacer: str) -> str:
         match chunk.type:
@@ -496,14 +470,6 @@ class BaseSyncStreamResponse(BaseStreamResponse[ChunkIterator, ToolkitT, Formatt
                 self._assistant_message.raw_message = chunk.raw_message
             elif chunk.type == "finish_reason_chunk":
                 self.finish_reason = chunk.finish_reason
-            elif chunk.type == "usage_delta_chunk":
-                if self.usage is None:
-                    self.usage = Usage()
-                self.usage.input_tokens += chunk.input_tokens
-                self.usage.output_tokens += chunk.output_tokens
-                self.usage.cache_read_tokens += chunk.cache_read_tokens
-                self.usage.cache_write_tokens += chunk.cache_write_tokens
-                self.usage.reasoning_tokens += chunk.reasoning_tokens
             else:
                 yield self._handle_chunk(chunk)
 
@@ -514,26 +480,6 @@ 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.
 
@@ -556,46 +502,26 @@ class BaseSyncStreamResponse(BaseStreamResponse[ChunkIterator, ToolkitT, Formatt
                 printed = True
             yield pretty
 
+        if not printed:
+            yield "**[No Content]**"
+
     def structured_stream(
         self,
     ) -> Iterator[Partial[FormattableT]]:
-        """Drive the stream forward, yielding partial formatted outputs as they arrive.
+        """Returns an iterator that yields partial structured objects as content streams.
 
-        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.
+        Returns:
+            Iterator[Partial[FormatT]]: Synchronous iterator yielding partial structured objects
 
-        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
+        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.
 
         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).
         """
-        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
+        raise NotImplementedError()
 
 
 class BaseAsyncStreamResponse(
@@ -717,14 +643,6 @@ class BaseAsyncStreamResponse(
                 self._assistant_message.raw_message = chunk.raw_message
             elif chunk.type == "finish_reason_chunk":
                 self.finish_reason = chunk.finish_reason
-            elif chunk.type == "usage_delta_chunk":
-                if self.usage is None:
-                    self.usage = Usage()
-                self.usage.input_tokens += chunk.input_tokens
-                self.usage.output_tokens += chunk.output_tokens
-                self.usage.cache_read_tokens += chunk.cache_read_tokens
-                self.usage.cache_write_tokens += chunk.cache_write_tokens
-                self.usage.reasoning_tokens += chunk.reasoning_tokens
             else:
                 yield self._handle_chunk(chunk)
 
@@ -735,27 +653,6 @@ 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.
 
@@ -778,43 +675,23 @@ class BaseAsyncStreamResponse(
                 printed = True
             yield pretty
 
-    async def structured_stream(
+        if not printed:
+            yield "**[No Content]**"
+
+    def structured_stream(
         self,
     ) -> AsyncIterator[Partial[FormattableT]]:
-        """Drive the stream forward, yielding partial formatted outputs as they arrive.
+        """Returns an async iterator that yields partial structured objects as content streams.
 
-        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.
+        Returns:
+            AsyncIterator[Partial[FormatT]]: Async iterator yielding partial structured objects
 
-        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
+        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.
 
         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).
         """
-        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
+        raise NotImplementedError()

mirascope/llm/responses/finish_reason.py

@@ -15,7 +15,6 @@ class FinishReason(str, Enum):
 
     MAX_TOKENS = "max_tokens"
     REFUSAL = "refusal"
-    CONTEXT_LENGTH_EXCEEDED = "context_length_exceeded"
 
 
 @dataclass(kw_only=True)