mirascope 1.23.4__tar.gz → 1.24.1__tar.gz

{mirascope-1.23.4 → mirascope-1.24.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mirascope
-Version: 1.23.4
+Version: 1.24.1
 Summary: LLM abstractions that aren't obstructions
 Project-URL: Homepage, https://mirascope.com
 Project-URL: Documentation, https://mirascope.com/WELCOME
@@ -154,7 +154,7 @@ print(book)
 
 ## Tutorials
 
-Check out our [quickstart tutorial](https://mirascope.com/tutorials/getting_started/quickstart) and many other tutorials for an interactive way to getting started with Mirascope.
+Check out our [quickstart tutorial](https://mirascope.com/docs/mirascope/getting-started/quickstart) and many other tutorials for an interactive way to getting started with Mirascope.
 
 ## Usage
 
@@ -166,4 +166,4 @@ Mirascope uses [Semantic Versioning](https://semver.org/).
 
 ## Licence
 
-This project is licensed under the terms of the [MIT License](https://github.com/Mirascope/mirascope/blob/dev/LICENSE).
+This project is licensed under the terms of the [MIT License](https://github.com/Mirascope/mirascope/tree/main/LICENSE).

{mirascope-1.23.4 → mirascope-1.24.1}/README.md

@@ -51,7 +51,7 @@ print(book)
 
 ## Tutorials
 
-Check out our [quickstart tutorial](https://mirascope.com/tutorials/getting_started/quickstart) and many other tutorials for an interactive way to getting started with Mirascope.
+Check out our [quickstart tutorial](https://mirascope.com/docs/mirascope/getting-started/quickstart) and many other tutorials for an interactive way to getting started with Mirascope.
 
 ## Usage
 
@@ -63,4 +63,4 @@ Mirascope uses [Semantic Versioning](https://semver.org/).
 
 ## Licence
 
-This project is licensed under the terms of the [MIT License](https://github.com/Mirascope/mirascope/blob/dev/LICENSE).
+This project is licensed under the terms of the [MIT License](https://github.com/Mirascope/mirascope/tree/main/LICENSE).

mirascope-1.24.1/api_ref/llm/call_response.md

@@ -0,0 +1,3 @@
+# mirascope.llm.call_response
+
+::: mirascope.llm.call_response

mirascope-1.24.1/api_ref/llm/call_response_chunk.md

@@ -0,0 +1,3 @@
+# mirascope.llm.call_response_chunk
+
+::: mirascope.llm.call_response_chunk

{mirascope-1.23.4 → mirascope-1.24.1}/mirascope/__init__.py

@@ -15,6 +15,7 @@ from .core import (
     BaseToolKit,
     CacheControlPart,
     DocumentPart,
+    DocumentURLPart,
     ImagePart,
     ImageURLPart,
     LocalProvider,
@@ -43,6 +44,7 @@ __all__ = [
     "BaseToolKit",
     "CacheControlPart",
     "DocumentPart",
+    "DocumentURLPart",
     "ImagePart",
     "ImageURLPart",
     "LocalProvider",

{mirascope-1.23.4 → mirascope-1.24.1}/mirascope/core/__init__.py

@@ -16,6 +16,7 @@ from .base import (
     CacheControlPart,
     CostMetadata,
     DocumentPart,
+    DocumentURLPart,
     FromCallArgs,
     ImagePart,
     ImageURLPart,
@@ -77,6 +78,7 @@ __all__ = [
     "CacheControlPart",
     "CostMetadata",
     "DocumentPart",
+    "DocumentURLPart",
     "FromCallArgs",
     "ImagePart",
     "ImageURLPart",

{mirascope-1.23.4 → mirascope-1.24.1}/mirascope/core/azure/call_response_chunk.py

@@ -75,14 +75,14 @@ class AzureCallResponseChunk(
         return self.chunk.id
 
     @property
-    def usage(self) -> CompletionsUsage:
+    def usage(self) -> CompletionsUsage | None:
         """Returns the usage of the chat completion."""
         return self.chunk.usage
 
     @property
-    def input_tokens(self) -> int:
+    def input_tokens(self) -> int | None:
         """Returns the number of input tokens."""
-        return self.usage.prompt_tokens
+        return self.usage.prompt_tokens if self.usage else None
 
     @property
     def cached_tokens(self) -> int:
@@ -90,9 +90,9 @@ class AzureCallResponseChunk(
         return 0
 
     @property
-    def output_tokens(self) -> int:
+    def output_tokens(self) -> int | None:
         """Returns the number of output tokens."""
-        return self.usage.completion_tokens
+        return self.usage.completion_tokens if self.usage else None
 
     @property
     def cost_metadata(self) -> CostMetadata:

{mirascope-1.23.4 → mirascope-1.24.1}/mirascope/core/base/__init__.py

@@ -16,6 +16,7 @@ from .message_param import (
     BaseMessageParam,
     CacheControlPart,
     DocumentPart,
+    DocumentURLPart,
     ImagePart,
     ImageURLPart,
     TextPart,
@@ -59,6 +60,7 @@ __all__ = [
     "CommonCallParams",
     "CostMetadata",
     "DocumentPart",
+    "DocumentURLPart",
     "FromCallArgs",
     "GenerateJsonSchemaNoTitles",
     "ImagePart",

{mirascope-1.23.4 → mirascope-1.24.1}/mirascope/core/base/_utils/_convert_messages_to_message_params.py

@@ -14,6 +14,7 @@ from ..message_param import (
     BaseMessageParam,
     CacheControlPart,
     DocumentPart,
+    DocumentURLPart,
     ImagePart,
     ImageURLPart,
     TextPart,
@@ -37,7 +38,8 @@ def _convert_message_sequence_part_to_content_part(
     | AudioURLPart
     | AudioSegment
     | Wave_read
-    | DocumentPart,
+    | DocumentPart
+    | DocumentURLPart,
 ) -> (
     TextPart
     | ImagePart
@@ -45,6 +47,7 @@ def _convert_message_sequence_part_to_content_part(
     | AudioPart
     | AudioURLPart
     | CacheControlPart
+    | DocumentURLPart
     | DocumentPart
 ):
     if isinstance(message_sequence_part, str):
@@ -57,7 +60,8 @@ def _convert_message_sequence_part_to_content_part(
         | AudioPart
         | AudioURLPart
         | CacheControlPart
-        | DocumentPart,
+        | DocumentPart
+        | DocumentURLPart,
     ):
         return message_sequence_part
     elif has_pil_module and isinstance(message_sequence_part, Image.Image):
@@ -107,6 +111,7 @@ def convert_message_content_to_message_param_content(
         | AudioSegment
         | Wave_read
         | DocumentPart
+        | DocumentURLPart,
     ],
 ) -> (
     list[
@@ -117,6 +122,7 @@ def convert_message_content_to_message_param_content(
         | AudioURLPart
         | CacheControlPart
         | DocumentPart
+        | DocumentURLPart,
     ]
     | str
 ):
@@ -151,6 +157,7 @@ def convert_messages_to_message_params(
         | AudioSegment
         | Wave_read
         | DocumentPart
+        | DocumentURLPart,
     ]
     | list[BaseMessageParam]
     | BaseMessageParam,

{mirascope-1.23.4 → mirascope-1.24.1}/mirascope/core/base/call_response.py

@@ -60,10 +60,8 @@ def transform_tool_outputs(
         tools_and_outputs: Sequence[tuple[_BaseToolT, JsonableType]],
     ) -> list[_ToolMessageParamT]:
         def recursive_serializer(value: JsonableType) -> BaseType:
-            if isinstance(value, str):
+            if isinstance(value, str | int | float | bool | None):
                 return value
-            if isinstance(value, int | float | bool):
-                return value  # Don't serialize primitives yet
             if isinstance(value, bytes):
                 return base64.b64encode(value).decode("utf-8")
             if isinstance(value, BaseModel):

{mirascope-1.23.4 → mirascope-1.24.1}/mirascope/core/base/message_param.py

@@ -103,6 +103,18 @@ class DocumentPart(BaseModel):
     document: bytes
 
 
+class DocumentURLPart(BaseModel):
+    """A content part for documents with a URL.
+
+    Attributes:
+        type: Always "document_url"
+        url: The URL to the document
+    """
+
+    type: Literal["document_url"]
+    url: str
+
+
 class ToolCallPart(BaseModel):
     """A content part for tool.
 
@@ -156,6 +168,7 @@ class BaseMessageParam(BaseModel):
             | AudioURLPart
             | CacheControlPart
             | DocumentPart
+            | DocumentURLPart
             | ToolCallPart
             | ToolResultPart
         ]

{mirascope-1.23.4 → mirascope-1.24.1}/mirascope/core/base/messages.py

@@ -14,6 +14,7 @@ from .message_param import (
     BaseMessageParam,
     CacheControlPart,
     DocumentPart,
+    DocumentURLPart,
     ImagePart,
     ImageURLPart,
     TextPart,
@@ -36,6 +37,7 @@ class Messages:
             | AudioSegment
             | Wave_read
             | DocumentPart
+            | DocumentURLPart
         ]
         | list[BaseMessageParam | Any]
         | BaseMessageParam
@@ -57,6 +59,7 @@ class Messages:
             | AudioSegment
             | Wave_read
             | DocumentPart
+            | DocumentURLPart
         ],
     ) -> BaseMessageParam:
         return BaseMessageParam(
@@ -80,6 +83,7 @@ class Messages:
             | AudioSegment
             | Wave_read
             | DocumentPart
+            | DocumentURLPart
         ],
     ) -> BaseMessageParam:
         return BaseMessageParam(
@@ -103,6 +107,7 @@ class Messages:
             | AudioSegment
             | Wave_read
             | DocumentPart
+            | DocumentURLPart
         ],
     ) -> BaseMessageParam:
         return BaseMessageParam(

{mirascope-1.23.4 → mirascope-1.24.1}/mirascope/core/base/tool.py

@@ -122,6 +122,15 @@ class BaseTool(BaseModel, ABC):
             if field not in {"tool_call", "delta"}
         }
 
+    @property
+    def id(self) -> str | None:
+        """The id of the tool."""
+        if tool_call := getattr(self, "tool_call", None):
+            # Expect tool_call has an id attribute.
+            # If not, we should override this method on the provider tool
+            return getattr(tool_call, "id", None)
+        return None
+
     @abstractmethod
     def call(self, *args: Any, **kwargs: Any) -> Any:  # noqa: ANN401
         """The method to call the tool."""

{mirascope-1.23.4 → mirascope-1.24.1}/mirascope/core/bedrock/_utils/_message_param_converter.py

@@ -100,25 +100,27 @@ class BedrockMessageParamConverter(BaseMessageParamConverter):
                     )
                 elif "toolUse" in block:
                     tool_use = block["toolUse"]
+
+                    tool_use_part = ToolCallPart(
+                        type="tool_call",
+                        name=tool_use["name"],
+                        id=tool_use["toolUseId"],
+                        args=tool_use["input"],
+                    )
                     if converted_content:
+                        converted_content.append(tool_use_part)
                         converted.append(
                             BaseMessageParam(
                                 role=message_param["role"], content=converted_content
                             )
                         )
                         converted_content = []
+                        continue
 
                     converted.append(
                         BaseMessageParam(
                             role="assistant",
-                            content=[
-                                ToolCallPart(
-                                    type="tool_call",
-                                    name=tool_use["name"],
-                                    id=tool_use["toolUseId"],
-                                    args=tool_use["input"],
-                                )
-                            ],
+                            content=[tool_use_part],
                         )
                     )
                 elif "toolResult" in block:
@@ -137,7 +139,6 @@ class BedrockMessageParamConverter(BaseMessageParamConverter):
                                 ToolResultPart(
                                     type="tool_result",
                                     id=tool_result["toolUseId"],
-                                    name=tool_result["name"],  # pyright: ignore [reportGeneralTypeIssues]
                                     content=tool_result["content"]
                                     if isinstance(tool_result["content"], str)
                                     else tool_result["content"][0]["text"],  # pyright: ignore [reportTypedDictNotRequiredAccess]

{mirascope-1.23.4 → mirascope-1.24.1}/mirascope/core/bedrock/call_response.py

@@ -219,7 +219,6 @@ class BedrockCallResponse(
                             "toolResult": {
                                 "content": [{"text": output}],
                                 "toolUseId": tool.tool_call["toolUse"]["toolUseId"],  # pyright: ignore [reportOptionalSubscript]
-                                "name": tool._name(),
                             }
                         },
                     )

{mirascope-1.23.4 → mirascope-1.24.1}/mirascope/core/bedrock/tool.py

@@ -56,6 +56,10 @@ class BedrockTool(BaseTool):
 
     tool_call: SkipJsonSchema[ToolUseBlockContentTypeDef]
 
+    @property
+    def id(self) -> str | None:
+        return self.tool_call["toolUse"]["toolUseId"]
+
     @classmethod
     def tool_schema(cls) -> ToolTypeDef:
         """Constructs a JSON Schema tool schema from the `BaseModel` schema defined.

{mirascope-1.23.4 → mirascope-1.24.1}/mirascope/core/google/_utils/_convert_message_params.py

@@ -16,9 +16,13 @@ from google.genai.types import (
 )
 
 from ...base import BaseMessageParam
-from ...base._utils import get_audio_type, get_image_type
+from ...base._utils import get_audio_type, get_document_type, get_image_type
 from ...base._utils._parse_content_template import _load_media
-from ._validate_media_type import _check_audio_media_type, _check_image_media_type
+from ._validate_media_type import (
+    _check_audio_media_type,
+    _check_document_media_type,
+    _check_image_media_type,
+)
 
 
 def _over_file_size_limit(size: int) -> bool:
@@ -154,9 +158,78 @@ async def _convert_message_params_async(
                         if _over_file_size_limit(total_payload_size):
                             must_upload[index] = blob_dict
                             total_payload_size -= audio_size
+                elif part.type == "document":
+                    _check_document_media_type(part.media_type)
+                    blob_dict = BlobDict(data=part.document, mime_type=part.media_type)
+                    converted_content.append(PartDict(inline_data=blob_dict))
+                    document_size = len(part.document)
+                    total_payload_size += document_size
+                    if _over_file_size_limit(total_payload_size):
+                        must_upload[index] = blob_dict
+                        total_payload_size -= document_size
+                elif part.type == "document_url":
+                    if (
+                        client.vertexai
+                        or not part.url.startswith(("https://", "http://"))
+                        or "generativelanguage.googleapis.com" in part.url
+                    ):
+                        converted_content.append(
+                            PartDict(
+                                file_data=FileDataDict(
+                                    file_uri=part.url, mime_type=None
+                                )
+                            )
+                        )
+                    else:
+                        media_type = None
+                        try:
+                            downloaded_document = _load_media(part.url)
+                            document_types = {
+                                "pdf": "application/pdf",
+                                "html": "text/html",
+                                "xml": "text/xml",
+                                "rtf": "text/rtf",
+                            }
+
+                            try:
+                                document_type_ext = get_document_type(
+                                    downloaded_document
+                                )
+                                media_type = document_types.get(document_type_ext)
+                            except ValueError:
+                                try:
+                                    downloaded_document.decode("utf-8")
+                                    media_type = "text/plain"
+                                except UnicodeDecodeError:
+                                    pass
+
+                            if media_type is None:
+                                raise ValueError(
+                                    f"Unsupported document format detected for URL: {part.url}. "
+                                    "Google API only supports the following document formats: "
+                                    "PDF, JavaScript, Python, TXT, HTML, CSS, Markdown, CSV, XML and RTF. "
+                                    "Please provide a document in one of these supported formats."
+                                )
+
+                            _check_document_media_type(media_type)
+                            blob_dict = BlobDict(
+                                data=downloaded_document, mime_type=media_type
+                            )
+                            converted_content.append(PartDict(inline_data=blob_dict))
+                            document_size = len(downloaded_document)
+                            total_payload_size += document_size
+                            if _over_file_size_limit(total_payload_size):
+                                must_upload[index] = blob_dict
+                                total_payload_size -= document_size
+                        except ValueError as e:
+                            raise ValueError(
+                                f"Failed to process document from URL: {part.url}. "
+                                f"Error details: {str(e)}. "
+                                "Please ensure the URL is accessible and points to a supported document format."
+                            )
                 else:
                     raise ValueError(
-                        "Google currently only supports text, tool_call, tool_result, image, and audio parts. "
+                        "Google currently only supports text, tool_call, tool_result, image, audio, and document parts. "
                         f"Part provided: {part.type}"
                     )
 

{mirascope-1.23.4 → mirascope-1.24.1}/mirascope/core/google/_utils/_message_param_converter.py

@@ -8,7 +8,7 @@ from google.genai.types import (
 )
 
 from mirascope.core import BaseMessageParam
-from mirascope.core.base import DocumentPart, ImagePart, TextPart
+from mirascope.core.base import DocumentPart, DocumentURLPart, ImagePart, TextPart
 from mirascope.core.base._utils._base_message_param_converter import (
     BaseMessageParamConverter,
 )
@@ -21,7 +21,11 @@ from mirascope.core.base.message_param import (
 )
 from mirascope.core.google._utils import convert_message_params
 
-from ._validate_media_type import _check_audio_media_type, _check_image_media_type
+from ._validate_media_type import (
+    _check_audio_media_type,
+    _check_document_media_type,
+    _check_image_media_type,
+)
 
 
 class GoogleMessageParamConverter(BaseMessageParamConverter):
@@ -78,7 +82,21 @@ class GoogleMessageParamConverter(BaseMessageParamConverter):
                                 audio=data,
                             )
                         )
-                    elif mime_type == "application/pdf":
+                    elif mime_type in [
+                        "application/pdf",
+                        "application/x-javascript",
+                        "text/javascript",
+                        "application/x-python",
+                        "text/x-python",
+                        "text/plain",
+                        "text/html",
+                        "text/css",
+                        "text/csv",
+                        "text/xml",
+                        "text/rtf",
+                        "text/md",
+                    ]:
+                        _check_document_media_type(mime_type)
                         content_list.append(
                             DocumentPart(
                                 type="document", media_type=mime_type, document=data
@@ -106,6 +124,26 @@ class GoogleMessageParamConverter(BaseMessageParamConverter):
                                 url=cast(str, part.file_data.file_uri),
                             )
                         )
+                    elif mime_type in [
+                        "application/pdf",
+                        "application/x-javascript",
+                        "text/javascript",
+                        "application/x-python",
+                        "text/x-python",
+                        "text/plain",
+                        "text/html",
+                        "text/css",
+                        "text/csv",
+                        "text/xml",
+                        "text/rtf",
+                        "text/md",
+                    ]:
+                        content_list.append(
+                            DocumentURLPart(
+                                type="document_url",
+                                url=cast(str, part.file_data.file_uri),
+                            )
+                        )
                     else:
                         # Since `FileDataDict` handles any file data, we use
                         # `ImageURLPart` for unknown mime types
@@ -148,7 +186,7 @@ class GoogleMessageParamConverter(BaseMessageParamConverter):
                     )
                 else:
                     raise ValueError(
-                        "Part does not contain any supported content (text, image, or document)."
+                        "Part does not contain any supported content (text, image, audio, or document)."
                     )
 
             if len(content_list) == 1 and isinstance(content_list[0], TextPart):

{mirascope-1.23.4 → mirascope-1.24.1}/mirascope/core/google/_utils/_validate_media_type.py

@@ -32,3 +32,27 @@ def _check_audio_media_type(media_type: str) -> None:
             "Google currently only supports WAV, MP3, AIFF, AAC, OGG, "
             "and FLAC audio file types."
         )
+
+
+def _check_document_media_type(media_type: str) -> None:
+    """Raises a `ValueError` if the document media type is not supported."""
+
+    if media_type not in [
+        "application/pdf",
+        "application/x-javascript",
+        "text/javascript",
+        "application/x-python",
+        "text/x-python",
+        "text/plain",
+        "text/html",
+        "text/css",
+        "text/csv",
+        "text/xml",
+        "text/rtf",
+        "text/md",
+    ]:
+        raise ValueError(
+            f"Unsupported document media type: {media_type}. "
+            "Google currently only supports PDF, JavaScript, Python, TXT, HTML, CSS, "
+            "CSV, XML, RTF, and Markdown document types."
+        )

{mirascope-1.23.4 → mirascope-1.24.1}/mirascope/llm/call_response.py

@@ -142,15 +142,6 @@ class CallResponse(
             tools_and_outputs: The sequence of tools and their outputs from which the tool
                 message parameters should be constructed.
         """
-
-        def _get_tool_call_id(_tool: BaseTool) -> str | None:
-            """Get the tool call ID."""
-            if tool_call := getattr(_tool, "tool_call", None):
-                # Expect tool_call has an id attribute.
-                # If not, we should implement a method to get the id on the provider tool
-                return getattr(tool_call, "id", None)
-            return None
-
         return [
             BaseMessageParam(
                 role="tool",
@@ -159,7 +150,7 @@ class CallResponse(
                         type="tool_result",
                         name=tool._name(),
                         content=output,
-                        id=_get_tool_call_id(tool),
+                        id=tool.id,
                     )
                 ],
             )

{mirascope-1.23.4 → mirascope-1.24.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mirascope"
-version = "1.23.4"
+version = "1.24.1"
 description = "LLM abstractions that aren't obstructions"
 readme = "README.md"
 license = { file = "LICENSE" }

{mirascope-1.23.4 → mirascope-1.24.1}/tests/core/bedrock/_utils/test_message_param_converter.py

@@ -163,7 +163,6 @@ def test_tool_result():
                 "toolResult": {
                     "toolUseId": "tool_123",
                     "content": [{"text": "result"}],
-                    "name": "tool_123",
                 }
             }
         ],
@@ -175,7 +174,6 @@ def test_tool_result():
             content=[
                 ToolResultPart(
                     type="tool_result",
-                    name="tool_123",
                     content="result",
                     id="tool_123",
                     is_error=False,
@@ -187,7 +185,7 @@ def test_tool_result():
 
 def test_tool_use_with_text():
     message_param = {
-        "role": "user",
+        "role": "assistant",
         "content": [
             {"text": "Hello"},
             {
@@ -201,16 +199,16 @@ def test_tool_use_with_text():
     }
     results = BedrockMessageParamConverter.from_provider([message_param])  # pyright: ignore [reportArgumentType]
     assert results == [
-        BaseMessageParam(role="user", content=[TextPart(type="text", text="Hello")]),
         BaseMessageParam(
             role="assistant",
             content=[
+                TextPart(type="text", text="Hello"),
                 ToolCallPart(
                     type="tool_call",
                     name="tool_name",
                     args={"arg": "val"},
                     id="tool_id",
-                )
+                ),
             ],
         ),
     ]
@@ -225,7 +223,6 @@ def test_tool_result_with_text():
                 "toolResult": {
                     "toolUseId": "tool_id",
                     "content": [{"text": "result"}],
-                    "name": "tool_name",
                 }
             },
         ],
@@ -238,7 +235,6 @@ def test_tool_result_with_text():
             content=[
                 ToolResultPart(
                     type="tool_result",
-                    name="tool_name",
                     content="result",
                     id="tool_id",
                     is_error=False,

{mirascope-1.23.4 → mirascope-1.24.1}/tests/core/bedrock/test_call_response.py

@@ -183,7 +183,6 @@ def test_bedrock_call_response_with_tools() -> None:
                             {"text": "The Name of the Wind by Patrick Rothfuss"}
                         ],
                         "toolUseId": "id",
-                        "name": "FormatBook",
                     }
                 }
             ],

{mirascope-1.23.4 → mirascope-1.24.1}/tests/core/bedrock/test_tool.py

@@ -40,6 +40,7 @@ def test_bedrock_tool() -> None:
     assert tool.title == "The Name of the Wind"
     assert tool.author == "Patrick Rothfuss"
     assert tool.call() == "The Name of the Wind by Patrick Rothfuss"
+    assert tool.id == "id"
 
     expected_schema = ToolTypeDef(
         toolSpec=ToolSpecificationTypeDef(