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

mirascope/llm/responses/response.py

@@ -18,14 +18,11 @@ from ..tools import (
     Tool,
     Toolkit,
 )
-from ..types import Jsonable
 from .base_response import BaseResponse
 from .finish_reason import FinishReason
-from .usage import Usage
 
 if TYPE_CHECKING:
-    from ..models import Params
-    from ..providers import ModelId, ProviderId
+    from ..clients import ModelId, Params, Provider
 
 
 class Response(BaseResponse[Toolkit, FormattableT]):
@@ -35,34 +32,30 @@ class Response(BaseResponse[Toolkit, FormattableT]):
         self,
         *,
         raw: Any,  # noqa: ANN401
-        provider_id: "ProviderId",
+        provider: "Provider",
         model_id: "ModelId",
-        provider_model_name: str,
         params: "Params",
         tools: Sequence[Tool] | Toolkit | None = None,
         format: Format[FormattableT] | None = None,
         input_messages: Sequence[Message],
         assistant_message: AssistantMessage,
         finish_reason: FinishReason | None,
-        usage: Usage | None,
     ) -> None:
         """Initialize a `Response`."""
         toolkit = tools if isinstance(tools, Toolkit) else Toolkit(tools=tools)
         super().__init__(
             raw=raw,
-            provider_id=provider_id,
+            provider=provider,
             model_id=model_id,
-            provider_model_name=provider_model_name,
             params=params,
             toolkit=toolkit,
             format=format,
             input_messages=input_messages,
             assistant_message=assistant_message,
             finish_reason=finish_reason,
-            usage=usage,
         )
 
-    def execute_tools(self) -> Sequence[ToolOutput[Jsonable]]:
+    def execute_tools(self) -> Sequence[ToolOutput]:
         """Execute and return all of the tool calls in the response.
 
         Returns:
@@ -108,16 +101,14 @@ class AsyncResponse(BaseResponse[AsyncToolkit, FormattableT]):
         self,
         *,
         raw: Any,  # noqa: ANN401
-        provider_id: "ProviderId",
+        provider: "Provider",
         model_id: "ModelId",
-        provider_model_name: str,
         params: "Params",
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
         format: Format[FormattableT] | None = None,
         input_messages: Sequence[Message],
         assistant_message: AssistantMessage,
         finish_reason: FinishReason | None,
-        usage: Usage | None,
     ) -> None:
         """Initialize an `AsyncResponse`."""
         toolkit = (
@@ -125,19 +116,17 @@ class AsyncResponse(BaseResponse[AsyncToolkit, FormattableT]):
         )
         super().__init__(
             raw=raw,
-            provider_id=provider_id,
+            provider=provider,
             model_id=model_id,
-            provider_model_name=provider_model_name,
             params=params,
             toolkit=toolkit,
             format=format,
             input_messages=input_messages,
             assistant_message=assistant_message,
             finish_reason=finish_reason,
-            usage=usage,
         )
 
-    async def execute_tools(self) -> Sequence[ToolOutput[Jsonable]]:
+    async def execute_tools(self) -> Sequence[ToolOutput]:
         """Execute and return all of the tool calls in the response.
 
         Returns:
@@ -190,9 +179,8 @@ class ContextResponse(
         self,
         *,
         raw: Any,  # noqa: ANN401
-        provider_id: "ProviderId",
+        provider: "Provider",
         model_id: "ModelId",
-        provider_model_name: str,
         params: "Params",
         tools: Sequence[Tool | ContextTool[DepsT]]
         | ContextToolkit[DepsT]
@@ -201,7 +189,6 @@ class ContextResponse(
         input_messages: Sequence[Message],
         assistant_message: AssistantMessage,
         finish_reason: FinishReason | None,
-        usage: Usage | None,
     ) -> None:
         """Initialize a `ContextResponse`."""
         toolkit = (
@@ -209,19 +196,17 @@ class ContextResponse(
         )
         super().__init__(
             raw=raw,
-            provider_id=provider_id,
+            provider=provider,
             model_id=model_id,
-            provider_model_name=provider_model_name,
             params=params,
             toolkit=toolkit,
             format=format,
             input_messages=input_messages,
             assistant_message=assistant_message,
             finish_reason=finish_reason,
-            usage=usage,
         )
 
-    def execute_tools(self, ctx: Context[DepsT]) -> Sequence[ToolOutput[Jsonable]]:
+    def execute_tools(self, ctx: Context[DepsT]) -> Sequence[ToolOutput]:
         """Execute and return all of the tool calls in the response.
 
         Args:
@@ -280,9 +265,8 @@ class AsyncContextResponse(
         self,
         *,
         raw: Any,  # noqa: ANN401
-        provider_id: "ProviderId",
+        provider: "Provider",
         model_id: "ModelId",
-        provider_model_name: str,
         params: "Params",
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
@@ -291,7 +275,6 @@ class AsyncContextResponse(
         input_messages: Sequence[Message],
         assistant_message: AssistantMessage,
         finish_reason: FinishReason | None,
-        usage: Usage | None,
     ) -> None:
         """Initialize an `AsyncContextResponse`."""
         toolkit = (
@@ -301,21 +284,17 @@ class AsyncContextResponse(
         )
         super().__init__(
             raw=raw,
-            provider_id=provider_id,
+            provider=provider,
             model_id=model_id,
-            provider_model_name=provider_model_name,
             params=params,
             toolkit=toolkit,
             format=format,
             input_messages=input_messages,
             assistant_message=assistant_message,
             finish_reason=finish_reason,
-            usage=usage,
         )
 
-    async def execute_tools(
-        self, ctx: Context[DepsT]
-    ) -> Sequence[ToolOutput[Jsonable]]:
+    async def execute_tools(self, ctx: Context[DepsT]) -> Sequence[ToolOutput]:
         """Execute and return all of the tool calls in the response.
 
         Args:

mirascope/llm/responses/root_response.py

@@ -3,29 +3,18 @@
 from abc import ABC
 from collections.abc import Sequence
 from types import NoneType
-from typing import TYPE_CHECKING, Any, Generic, Literal, TypeAlias, overload
+from typing import TYPE_CHECKING, Any, Generic, Literal, overload
 
 from ..content import AssistantContentPart, Text, Thought, ToolCall
-from ..exceptions import ParseError
-from ..formatting import (
-    Format,
-    FormattableT,
-    Partial,
-    create_wrapper_model,
-    is_output_parser,
-    is_primitive_type,
-)
+from ..formatting import Format, FormattableT, Partial
 from ..messages import Message
 from ..tools import ToolkitT
 from . import _utils
 from .finish_reason import FinishReason
-from .usage import Usage
 
 if TYPE_CHECKING:
-    from ..models import Model, Params
-    from ..providers import ModelId, ProviderId
-
-AnyResponse: TypeAlias = "RootResponse[Any, Any]"
+    from ..clients import ModelId, Params, Provider
+    from ..models import Model
 
 
 class RootResponse(Generic[ToolkitT, FormattableT], ABC):
@@ -34,7 +23,7 @@ class RootResponse(Generic[ToolkitT, FormattableT], ABC):
     raw: Any
     """The raw response from the LLM."""
 
-    provider_id: "ProviderId"
+    provider: "Provider"
     """The provider that generated this response."""
 
     model_id: "ModelId"
@@ -66,15 +55,12 @@ class RootResponse(Generic[ToolkitT, FormattableT], ABC):
     """
     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`.
     """
 
-    usage: Usage | None
-    """Token usage statistics for this response, if available."""
-
     format: Format[FormattableT] | None
     """The `Format` describing the structured response format, if available."""
 
@@ -117,96 +103,29 @@ 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. 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.
+            The formatted response object of type FormatT.
 
         Raises:
-            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).
+            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 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.
+        if formattable is None or formattable is NoneType:
             return None  # pragma: no cover
 
-        text = self.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").
+            raise NotImplementedError
 
-        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)
+        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.
@@ -222,6 +141,9 @@ 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):
@@ -243,6 +165,13 @@ class RootResponse(Generic[ToolkitT, FormattableT], ABC):
     @property
     def model(self) -> "Model":
         """A `Model` with parameters matching this response."""
-        from ..models import use_model  # Dynamic import to avoid circular dependency
+        from ..models import Model, get_model_from_context
+
+        if context_model := get_model_from_context():
+            return context_model
 
-        return use_model(self.model_id, **self.params)
+        return Model(
+            provider=self.provider,
+            model_id=self.model_id,
+            **self.params,
+        )

mirascope/llm/responses/stream_response.py

@@ -18,7 +18,6 @@ from ..tools import (
     Tool,
     Toolkit,
 )
-from ..types import Jsonable
 from .base_stream_response import (
     AsyncChunkIterator,
     BaseAsyncStreamResponse,
@@ -27,8 +26,7 @@ from .base_stream_response import (
 )
 
 if TYPE_CHECKING:
-    from ..models import Params
-    from ..providers import ModelId, ProviderId
+    from ..clients import ModelId, Params, Provider
 
 
 class StreamResponse(BaseSyncStreamResponse[Toolkit, FormattableT]):
@@ -78,25 +76,25 @@ class StreamResponse(BaseSyncStreamResponse[Toolkit, FormattableT]):
         from mirascope import llm
 
         @llm.call(
-            provider_id="openai",
-            model_id="openai/gpt-5-mini",
+            provider="openai:completions",
+            model_id="gpt-4o-mini",
         )
         def answer_question(question: str) -> str:
             return f"Answer this question: {question}"
 
         stream_response = answer_question.stream("What is the capital of France?")
 
-        for chunk in stream_response.text_stream():
+        for chunk in stream_response.pretty_stream():
             print(chunk, end="", flush=True)
+        print()
         ```
     """
 
     def __init__(
         self,
         *,
-        provider_id: "ProviderId",
+        provider: "Provider",
         model_id: "ModelId",
-        provider_model_name: str,
         params: "Params",
         tools: Sequence[Tool] | Toolkit | None = None,
         format: Format[FormattableT] | None = None,
@@ -106,9 +104,8 @@ class StreamResponse(BaseSyncStreamResponse[Toolkit, FormattableT]):
         """Initialize a `StreamResponse`."""
         toolkit = tools if isinstance(tools, Toolkit) else Toolkit(tools=tools)
         super().__init__(
-            provider_id=provider_id,
+            provider=provider,
             model_id=model_id,
-            provider_model_name=provider_model_name,
             params=params,
             toolkit=toolkit,
             format=format,
@@ -116,7 +113,7 @@ class StreamResponse(BaseSyncStreamResponse[Toolkit, FormattableT]):
             chunk_iterator=chunk_iterator,
         )
 
-    def execute_tools(self) -> Sequence[ToolOutput[Jsonable]]:
+    def execute_tools(self) -> Sequence[ToolOutput]:
         """Execute and return all of the tool calls in the response.
 
         Returns:
@@ -204,25 +201,25 @@ class AsyncStreamResponse(BaseAsyncStreamResponse[AsyncToolkit, FormattableT]):
         from mirascope import llm
 
         @llm.call(
-            provider_id="openai",
-            model_id="openai/gpt-5-mini",
+            provider="openai:completions",
+            model_id="gpt-4o-mini",
         )
         async def answer_question(question: str) -> str:
             return f"Answer this question: {question}"
 
         stream_response = await answer_question.stream("What is the capital of France?")
 
-        async for chunk in stream_response.text_stream():
+        async for chunk in stream_response.pretty_stream():
             print(chunk, end="", flush=True)
+        print()
         ```
     """
 
     def __init__(
         self,
         *,
-        provider_id: "ProviderId",
+        provider: "Provider",
         model_id: "ModelId",
-        provider_model_name: str,
         params: "Params",
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
         format: Format[FormattableT] | None = None,
@@ -234,9 +231,8 @@ class AsyncStreamResponse(BaseAsyncStreamResponse[AsyncToolkit, FormattableT]):
             tools if isinstance(tools, AsyncToolkit) else AsyncToolkit(tools=tools)
         )
         super().__init__(
-            provider_id=provider_id,
+            provider=provider,
             model_id=model_id,
-            provider_model_name=provider_model_name,
             params=params,
             toolkit=toolkit,
             format=format,
@@ -244,7 +240,7 @@ class AsyncStreamResponse(BaseAsyncStreamResponse[AsyncToolkit, FormattableT]):
             chunk_iterator=chunk_iterator,
         )
 
-    async def execute_tools(self) -> Sequence[ToolOutput[Jsonable]]:
+    async def execute_tools(self) -> Sequence[ToolOutput]:
         """Execute and return all of the tool calls in the response.
 
         Returns:
@@ -289,8 +285,7 @@ class AsyncStreamResponse(BaseAsyncStreamResponse[AsyncToolkit, FormattableT]):
 
 
 class ContextStreamResponse(
-    BaseSyncStreamResponse[ContextToolkit[DepsT], FormattableT],
-    Generic[DepsT, FormattableT],
+    BaseSyncStreamResponse[ContextToolkit, FormattableT], Generic[DepsT, FormattableT]
 ):
     """A `ContextStreamResponse` wraps response content from the LLM with a streaming interface.
 
@@ -338,8 +333,8 @@ class ContextStreamResponse(
         from mirascope import llm
 
         @llm.call(
-            provider_id="openai",
-            model_id="openai/gpt-5-mini",
+            provider="openai:completions",
+            model_id="gpt-4o-mini",
         )
         def answer_question(ctx: llm.Context, question: str) -> str:
             return f"Answer this question: {question}"
@@ -347,17 +342,17 @@ class ContextStreamResponse(
         ctx = llm.Context()
         stream_response = answer_question.stream(ctx, "What is the capital of France?")
 
-        for chunk in stream_response.text_stream():
+        for chunk in stream_response.pretty_stream():
             print(chunk, end="", flush=True)
+        print()
         ```
     """
 
     def __init__(
         self,
         *,
-        provider_id: "ProviderId",
+        provider: "Provider",
         model_id: "ModelId",
-        provider_model_name: str,
         params: "Params",
         tools: Sequence[Tool | ContextTool[DepsT]]
         | ContextToolkit[DepsT]
@@ -371,9 +366,8 @@ class ContextStreamResponse(
             tools if isinstance(tools, ContextToolkit) else ContextToolkit(tools=tools)
         )
         super().__init__(
-            provider_id=provider_id,
+            provider=provider,
             model_id=model_id,
-            provider_model_name=provider_model_name,
             params=params,
             toolkit=toolkit,
             format=format,
@@ -381,7 +375,7 @@ class ContextStreamResponse(
             chunk_iterator=chunk_iterator,
         )
 
-    def execute_tools(self, ctx: Context[DepsT]) -> Sequence[ToolOutput[Jsonable]]:
+    def execute_tools(self, ctx: Context[DepsT]) -> Sequence[ToolOutput]:
         """Execute and return all of the tool calls in the response.
 
         Args:
@@ -432,7 +426,7 @@ class ContextStreamResponse(
 
 
 class AsyncContextStreamResponse(
-    BaseAsyncStreamResponse[AsyncContextToolkit[DepsT], FormattableT],
+    BaseAsyncStreamResponse[AsyncContextToolkit, FormattableT],
     Generic[DepsT, FormattableT],
 ):
     """An `AsyncContextStreamResponse` wraps response content from the LLM with a streaming interface.
@@ -481,8 +475,8 @@ class AsyncContextStreamResponse(
         from mirascope import llm
 
         @llm.call(
-            provider_id="openai",
-            model_id="openai/gpt-5-mini",
+            provider="openai:completions",
+            model_id="gpt-4o-mini",
         )
         async def answer_question(ctx: llm.Context, question: str) -> str:
             return f"Answer this question: {question}"
@@ -490,17 +484,17 @@ class AsyncContextStreamResponse(
         ctx = llm.Context()
         stream_response = await answer_question.stream(ctx, "What is the capital of France?")
 
-        async for chunk in stream_response.text_stream():
+        async for chunk in stream_response.pretty_stream():
             print(chunk, end="", flush=True)
+        print()
         ```
     """
 
     def __init__(
         self,
         *,
-        provider_id: "ProviderId",
+        provider: "Provider",
         model_id: "ModelId",
-        provider_model_name: str,
         params: "Params",
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
@@ -516,9 +510,8 @@ class AsyncContextStreamResponse(
             else AsyncContextToolkit(tools=tools)
         )
         super().__init__(
-            provider_id=provider_id,
+            provider=provider,
             model_id=model_id,
-            provider_model_name=provider_model_name,
             params=params,
             toolkit=toolkit,
             format=format,
@@ -526,9 +519,7 @@ class AsyncContextStreamResponse(
             chunk_iterator=chunk_iterator,
         )
 
-    async def execute_tools(
-        self, ctx: Context[DepsT]
-    ) -> Sequence[ToolOutput[Jsonable]]:
+    async def execute_tools(self, ctx: Context[DepsT]) -> Sequence[ToolOutput]:
         """Execute and return all of the tool calls in the response.
 
         Args:

mirascope/llm/tools/__init__.py

@@ -1,11 +1,9 @@
 """The Tools module for LLMs."""
 
+from . import protocols
 from .decorator import ToolDecorator, tool
-from .protocols import AsyncContextToolFn, AsyncToolFn, ContextToolFn, ToolFn
 from .tool_schema import (
     FORMAT_TOOL_NAME,
-    AnyToolFn,
-    AnyToolSchema,
     ToolParameterSchema,
     ToolSchema,
     ToolSchemaT,
@@ -22,26 +20,21 @@ from .tools import AsyncContextTool, AsyncTool, ContextTool, Tool, ToolT
 
 __all__ = [
     "FORMAT_TOOL_NAME",
-    "AnyToolFn",
-    "AnyToolSchema",
     "AsyncContextTool",
-    "AsyncContextToolFn",
     "AsyncContextToolkit",
     "AsyncTool",
-    "AsyncToolFn",
     "AsyncToolkit",
     "BaseToolkit",
     "ContextTool",
-    "ContextToolFn",
     "ContextToolkit",
     "Tool",
     "ToolDecorator",
-    "ToolFn",
     "ToolParameterSchema",
     "ToolSchema",
     "ToolSchemaT",
     "ToolT",
     "Toolkit",
     "ToolkitT",
+    "protocols",
     "tool",
 ]

mirascope/llm/tools/_utils.py

@@ -9,10 +9,7 @@ from .protocols import AsyncContextToolFn, AsyncToolFn, ContextToolFn, ToolFn
 
 
 def is_context_tool_fn(
-    fn: ContextToolFn[DepsT, P, JsonableCovariantT]
-    | AsyncContextToolFn[DepsT, P, JsonableCovariantT]
-    | ToolFn[P, JsonableCovariantT]
-    | AsyncToolFn[P, JsonableCovariantT],
+    fn: ToolFn | AsyncToolFn | ContextToolFn | AsyncContextToolFn,
 ) -> TypeIs[
     ContextToolFn[DepsT, P, JsonableCovariantT]
     | AsyncContextToolFn[DepsT, P, JsonableCovariantT]
@@ -22,13 +19,7 @@ def is_context_tool_fn(
 
 
 def is_async_tool_fn(
-    fn: ContextToolFn[DepsT, P, JsonableCovariantT]
-    | AsyncContextToolFn[DepsT, P, JsonableCovariantT]
-    | ToolFn[P, JsonableCovariantT]
-    | AsyncToolFn[P, JsonableCovariantT],
-) -> TypeIs[
-    AsyncContextToolFn[DepsT, P, JsonableCovariantT]
-    | AsyncToolFn[P, JsonableCovariantT]
-]:
+    fn: ToolFn | AsyncToolFn | ContextToolFn | AsyncContextToolFn,
+) -> TypeIs[AsyncToolFn | AsyncContextToolFn]:
     """Type guard to check if a function is an async tool function."""
     return inspect.iscoroutinefunction(fn)