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

mirascope/llm/responses/finish_reason.py

@@ -0,0 +1,27 @@
+"""The reason the LLM finished generating a response."""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Literal
+
+
+class FinishReason(str, Enum):
+    """The reason why the LLM finished generating a response.
+
+    `FinishReason` is only set when the response did not have a normal finish (e.g. it
+    ran out of tokens). When a response finishes generating normally, no finish reason
+    is set.
+    """
+
+    MAX_TOKENS = "max_tokens"
+    REFUSAL = "refusal"
+
+
+@dataclass(kw_only=True)
+class FinishReasonChunk:
+    """Represents the finish reason for a completed stream."""
+
+    type: Literal["finish_reason_chunk"] = "finish_reason_chunk"
+
+    finish_reason: FinishReason
+    """The reason the stream finished."""

mirascope/llm/responses/response.py

@@ -0,0 +1,345 @@
+"""Implements Response and AsyncResponse."""
+
+import asyncio
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any, Generic, overload
+
+from ..content import ToolOutput
+from ..context import Context, DepsT
+from ..formatting import Format, FormattableT
+from ..messages import AssistantMessage, Message, UserContent
+from ..tools import (
+    AsyncContextTool,
+    AsyncContextToolkit,
+    AsyncTool,
+    AsyncToolkit,
+    ContextTool,
+    ContextToolkit,
+    Tool,
+    Toolkit,
+)
+from .base_response import BaseResponse
+from .finish_reason import FinishReason
+
+if TYPE_CHECKING:
+    from ..clients import ModelId, Params, Provider
+
+
+class Response(BaseResponse[Toolkit, FormattableT]):
+    """The response generated by an LLM."""
+
+    def __init__(
+        self,
+        *,
+        raw: Any,  # noqa: ANN401
+        provider: "Provider",
+        model_id: "ModelId",
+        params: "Params",
+        tools: Sequence[Tool] | Toolkit | None = None,
+        format: Format[FormattableT] | None = None,
+        input_messages: Sequence[Message],
+        assistant_message: AssistantMessage,
+        finish_reason: FinishReason | None,
+    ) -> None:
+        """Initialize a `Response`."""
+        toolkit = tools if isinstance(tools, Toolkit) else Toolkit(tools=tools)
+        super().__init__(
+            raw=raw,
+            provider=provider,
+            model_id=model_id,
+            params=params,
+            toolkit=toolkit,
+            format=format,
+            input_messages=input_messages,
+            assistant_message=assistant_message,
+            finish_reason=finish_reason,
+        )
+
+    def execute_tools(self) -> Sequence[ToolOutput]:
+        """Execute and return all of the tool calls in the response.
+
+        Returns:
+            A sequence containing a `ToolOutput` for every tool call in the order they appeared.
+
+        Raises:
+            ToolNotFoundError: If one of the response's tool calls has no matching tool.
+            Exception: If one of the tools throws an exception.
+        """
+        return [self.toolkit.execute(tool_call) for tool_call in self.tool_calls]
+
+    @overload
+    def resume(self: "Response", content: UserContent) -> "Response": ...
+
+    @overload
+    def resume(
+        self: "Response[FormattableT]", content: UserContent
+    ) -> "Response[FormattableT]": ...
+
+    def resume(self, content: UserContent) -> "Response | Response[FormattableT]":
+        """Generate a new `Response` using this response's messages with additional user content.
+
+        Uses this response's tools and format type. Also uses this response's provider,
+        model, client, and params, unless the model context manager is being used to
+        provide a new LLM as an override.
+
+        Args:
+            content: The new user message content to append to the message history.
+
+        Returns:
+            A new `Response` instance generated from the extended message history.
+        """
+        return self.model.resume(
+            response=self,
+            content=content,
+        )
+
+
+class AsyncResponse(BaseResponse[AsyncToolkit, FormattableT]):
+    """The response generated by an LLM in async mode."""
+
+    def __init__(
+        self,
+        *,
+        raw: Any,  # noqa: ANN401
+        provider: "Provider",
+        model_id: "ModelId",
+        params: "Params",
+        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
+        format: Format[FormattableT] | None = None,
+        input_messages: Sequence[Message],
+        assistant_message: AssistantMessage,
+        finish_reason: FinishReason | None,
+    ) -> None:
+        """Initialize an `AsyncResponse`."""
+        toolkit = (
+            tools if isinstance(tools, AsyncToolkit) else AsyncToolkit(tools=tools)
+        )
+        super().__init__(
+            raw=raw,
+            provider=provider,
+            model_id=model_id,
+            params=params,
+            toolkit=toolkit,
+            format=format,
+            input_messages=input_messages,
+            assistant_message=assistant_message,
+            finish_reason=finish_reason,
+        )
+
+    async def execute_tools(self) -> Sequence[ToolOutput]:
+        """Execute and return all of the tool calls in the response.
+
+        Returns:
+            A sequence containing a `ToolOutput` for every tool call in the order they appeared.
+
+        Raises:
+            ToolNotFoundError: If one of the response's tool calls has no matching tool.
+            Exception: If one of the tools throws an exception.
+        """
+        tasks = [self.toolkit.execute(tool_call) for tool_call in self.tool_calls]
+        return await asyncio.gather(*tasks)
+
+    @overload
+    async def resume(
+        self: "AsyncResponse", content: UserContent
+    ) -> "AsyncResponse": ...
+
+    @overload
+    async def resume(
+        self: "AsyncResponse[FormattableT]", content: UserContent
+    ) -> "AsyncResponse[FormattableT]": ...
+
+    async def resume(
+        self, content: UserContent
+    ) -> "AsyncResponse | AsyncResponse[FormattableT]":
+        """Generate a new `AsyncResponse` using this response's messages with additional user content.
+
+        Uses this response's tools and format type. Also uses this response's provider,
+        model, client, and params, unless the model context manager is being used to
+        provide a new LLM as an override.
+
+        Args:
+            content: The new user message content to append to the message history.
+
+        Returns:
+            A new `AsyncResponse` instance generated from the extended message history.
+        """
+        return await self.model.resume_async(
+            response=self,
+            content=content,
+        )
+
+
+class ContextResponse(
+    BaseResponse[ContextToolkit[DepsT], FormattableT], Generic[DepsT, FormattableT]
+):
+    """The response generated by an LLM from a context call."""
+
+    def __init__(
+        self,
+        *,
+        raw: Any,  # noqa: ANN401
+        provider: "Provider",
+        model_id: "ModelId",
+        params: "Params",
+        tools: Sequence[Tool | ContextTool[DepsT]]
+        | ContextToolkit[DepsT]
+        | None = None,
+        format: Format[FormattableT] | None = None,
+        input_messages: Sequence[Message],
+        assistant_message: AssistantMessage,
+        finish_reason: FinishReason | None,
+    ) -> None:
+        """Initialize a `ContextResponse`."""
+        toolkit = (
+            tools if isinstance(tools, ContextToolkit) else ContextToolkit(tools=tools)
+        )
+        super().__init__(
+            raw=raw,
+            provider=provider,
+            model_id=model_id,
+            params=params,
+            toolkit=toolkit,
+            format=format,
+            input_messages=input_messages,
+            assistant_message=assistant_message,
+            finish_reason=finish_reason,
+        )
+
+    def execute_tools(self, ctx: Context[DepsT]) -> Sequence[ToolOutput]:
+        """Execute and return all of the tool calls in the response.
+
+        Args:
+            ctx: A `Context` with the required deps type.
+
+        Returns:
+            A sequence containing a `ToolOutput` for every tool call.
+
+        Raises:
+            ToolNotFoundError: If one of the response's tool calls has no matching tool.
+            Exception: If one of the tools throws an exception.
+        """
+        return [self.toolkit.execute(ctx, tool_call) for tool_call in self.tool_calls]
+
+    @overload
+    def resume(
+        self: "ContextResponse[DepsT]", ctx: Context[DepsT], content: UserContent
+    ) -> "ContextResponse[DepsT]": ...
+
+    @overload
+    def resume(
+        self: "ContextResponse[DepsT, FormattableT]",
+        ctx: Context[DepsT],
+        content: UserContent,
+    ) -> "ContextResponse[DepsT, FormattableT]": ...
+
+    def resume(
+        self, ctx: Context[DepsT], content: UserContent
+    ) -> "ContextResponse[DepsT] | ContextResponse[DepsT, FormattableT]":
+        """Generate a new `ContextResponse` using this response's messages with additional user content.
+
+        Uses this response's tools and format type. Also uses this response's provider,
+        model, client, and params, unless the model context manager is being used to
+        provide a new LLM as an override.
+
+        Args:
+            ctx: A `Context` with the required deps type.
+            content: The new user message content to append to the message history.
+
+        Returns:
+            A new `ContextResponse` instance generated from the extended message history.
+        """
+        return self.model.context_resume(
+            ctx=ctx,
+            response=self,
+            content=content,
+        )
+
+
+class AsyncContextResponse(
+    BaseResponse[AsyncContextToolkit[DepsT], FormattableT], Generic[DepsT, FormattableT]
+):
+    """The response generated by an LLM from an async context call."""
+
+    def __init__(
+        self,
+        *,
+        raw: Any,  # noqa: ANN401
+        provider: "Provider",
+        model_id: "ModelId",
+        params: "Params",
+        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
+        | AsyncContextToolkit[DepsT]
+        | None = None,
+        format: Format[FormattableT] | None = None,
+        input_messages: Sequence[Message],
+        assistant_message: AssistantMessage,
+        finish_reason: FinishReason | None,
+    ) -> None:
+        """Initialize an `AsyncContextResponse`."""
+        toolkit = (
+            tools
+            if isinstance(tools, AsyncContextToolkit)
+            else AsyncContextToolkit(tools=tools)
+        )
+        super().__init__(
+            raw=raw,
+            provider=provider,
+            model_id=model_id,
+            params=params,
+            toolkit=toolkit,
+            format=format,
+            input_messages=input_messages,
+            assistant_message=assistant_message,
+            finish_reason=finish_reason,
+        )
+
+    async def execute_tools(self, ctx: Context[DepsT]) -> Sequence[ToolOutput]:
+        """Execute and return all of the tool calls in the response.
+
+        Args:
+            ctx: A `Context` with the required deps type.
+
+        Returns:
+            A sequence containing a `ToolOutput` for every tool call in the order they appeared.
+
+        Raises:
+            ToolNotFoundError: If one of the response's tool calls has no matching tool.
+            Exception: If one of the tools throws an exception.
+        """
+        tasks = [self.toolkit.execute(ctx, tool_call) for tool_call in self.tool_calls]
+        return await asyncio.gather(*tasks)
+
+    @overload
+    async def resume(
+        self: "AsyncContextResponse[DepsT]", ctx: Context[DepsT], content: UserContent
+    ) -> "AsyncContextResponse[DepsT]": ...
+
+    @overload
+    async def resume(
+        self: "AsyncContextResponse[DepsT, FormattableT]",
+        ctx: Context[DepsT],
+        content: UserContent,
+    ) -> "AsyncContextResponse[DepsT, FormattableT]": ...
+
+    async def resume(
+        self, ctx: Context[DepsT], content: UserContent
+    ) -> "AsyncContextResponse[DepsT] | AsyncContextResponse[DepsT, FormattableT]":
+        """Generate a new `AsyncContextResponse` using this response's messages with additional user content.
+
+        Uses this response's tools and format type. Also uses this response's provider,
+        model, client, and params, unless the model context manager is being used to
+        provide a new LLM as an override.
+
+        Args:
+            ctx: A Context with the required deps type.
+            content: The new user message content to append to the message history.
+
+        Returns:
+            A new `AsyncContextResponse` instance generated from the extended message history.
+        """
+        return await self.model.context_resume_async(
+            ctx=ctx,
+            response=self,
+            content=content,
+        )

mirascope/llm/responses/root_response.py

@@ -0,0 +1,177 @@
+"""Base interface for all LLM responses."""
+
+from abc import ABC
+from collections.abc import Sequence
+from types import NoneType
+from typing import TYPE_CHECKING, Any, Generic, Literal, overload
+
+from ..content import AssistantContentPart, Text, Thought, ToolCall
+from ..formatting import Format, FormattableT, Partial
+from ..messages import Message
+from ..tools import ToolkitT
+from . import _utils
+from .finish_reason import FinishReason
+
+if TYPE_CHECKING:
+    from ..clients import ModelId, Params, Provider
+    from ..models import Model
+
+
+class RootResponse(Generic[ToolkitT, FormattableT], ABC):
+    """Base class for LLM responses."""
+
+    raw: Any
+    """The raw response from the LLM."""
+
+    provider: "Provider"
+    """The provider that generated this response."""
+
+    model_id: "ModelId"
+    """The model id that generated this response."""
+
+    params: "Params"
+    """The params that were used to generate this response (or None)."""
+
+    toolkit: ToolkitT
+    """The toolkit containing the tools used when generating this response."""
+
+    messages: list[Message]
+    """The message history, including the most recent assistant message."""
+
+    content: Sequence[AssistantContentPart]
+    """The content generated by the LLM."""
+
+    texts: Sequence[Text]
+    """The text content in the generated response, if any."""
+
+    tool_calls: Sequence[ToolCall]
+    """The tools the LLM wants called on its behalf, if any."""
+
+    thoughts: Sequence[Thought]
+    """The readable thoughts from the model's thinking process, if any.
+
+    The thoughts may be direct output from the model thinking process, or may be a
+    generated summary. (This depends on the provider; newer models tend to summarize.)
+    """
+    finish_reason: FinishReason | None
+    """The reason why the LLM finished generating a response, if set.
+    
+    `finish_reason` is only set if the response did not finish generating normally,
+    e.g. `FinishReason.MAX_TOKENS` if the model ran out of tokens before completing.
+    When the response generates normally, `response.finish_reason` will be `None`.
+    """
+
+    format: Format[FormattableT] | None
+    """The `Format` describing the structured response format, if available."""
+
+    @overload
+    def parse(self: "RootResponse[ToolkitT, None]", partial: Literal[True]) -> None:
+        """Format the response into a `Partial[BaseModel]` (with optional fields).
+
+        This is useful for when the stream is only partially consumed, in which case the
+        structured output may only be partially available.
+        """
+        ...
+
+    @overload
+    def parse(
+        self: "RootResponse[ToolkitT, FormattableT]", partial: Literal[True]
+    ) -> Partial[FormattableT]:
+        """Format the response into a `Partial[BaseModel]` (with optional fields).
+
+        This is useful for when the stream is only partially consumed, in which case the
+        structured output may only be partially available.
+        """
+        ...
+
+    @overload
+    def parse(
+        self: "RootResponse[ToolkitT, None]", partial: Literal[False] = False
+    ) -> None:
+        """Overload when the format type is `None`."""
+        ...
+
+    @overload
+    def parse(
+        self: "RootResponse[ToolkitT, FormattableT]", partial: Literal[False] = False
+    ) -> FormattableT:
+        """Overload when the format type is not `None`."""
+        ...
+
+    def parse(
+        self, partial: bool = False
+    ) -> FormattableT | Partial[FormattableT] | None:
+        """Format the response according to the response format parser.
+
+        Returns:
+            The formatted response object of type FormatT.
+
+        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.
+        """
+        if self.format is None:
+            return None
+
+        formattable = self.format.formattable
+        if formattable is None or formattable is NoneType:
+            return None  # pragma: no cover
+
+        if partial:
+            raise NotImplementedError
+
+        text = "".join(text.text for text in self.texts)
+        json_text = _utils.extract_serialized_json(text)
+
+        return formattable.model_validate_json(json_text)
+
+    def pretty(self) -> str:
+        """Return a string representation of all response content.
+
+        The response content will be represented in a way that emphasies clarity and
+        readability, but may not include all metadata (like thinking signatures or tool
+        call ids), and thus cannot be used to reconstruct the response. For example:
+
+        **Thinking:**
+          The user is asking a math problem. I should use the calculator tool.
+
+        **Tool Call (calculator)** {'operation': 'mult', 'a': 1337, 'b': 4242}
+
+        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):
+                pretty_parts.append(part.text)
+            elif isinstance(part, ToolCall):
+                pretty_parts.append(f"**ToolCall ({part.name}):** {part.args}")
+            elif isinstance(part, Thought):
+                indented_thinking = "\n".join(
+                    f"  {line}" for line in part.thought.split("\n")
+                )
+                pretty_parts.append(f"**Thinking:**\n{indented_thinking}")
+            else:
+                pretty_parts.append(
+                    f"[{type(part).__name__}: {str(part)}]"
+                )  # pragma: no cover
+
+        return "\n\n".join(pretty_parts)
+
+    @property
+    def model(self) -> "Model":
+        """A `Model` with parameters matching this response."""
+        from ..models import Model, get_model_from_context
+
+        if context_model := get_model_from_context():
+            return context_model
+
+        return Model(
+            provider=self.provider,
+            model_id=self.model_id,
+            **self.params,
+        )