mirascope 1.23.3__tar.gz → 1.24.0__tar.gz

{mirascope-1.23.3 → mirascope-1.24.0}/.github/CODEOWNERS

@@ -4,8 +4,5 @@
 # Python Owner
 *.py        @willbakst
 
-# Documentation Owner
-/docs/      @willbakst
-
 # Examples Owner
 /examples/  @willbakst

{mirascope-1.23.3 → mirascope-1.24.0}/.github/workflows/lint.yml

@@ -19,8 +19,6 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - uses: codespell-project/actions-codespell@v2
-        with:
-          exclude_file: "docs/tutorials/evals/evaluating_web_search_agent.ipynb,docs/tutorials/agents/web_search_agent.ipynb,docs/tutorials/more_advanced/knowledge_graph.ipynb"
 
       - name: Set up uv
         run: curl -LsSf https://astral.sh/uv/0.6.10/install.sh | sh

{mirascope-1.23.3 → mirascope-1.24.0}/.pre-commit-config.yaml

@@ -5,7 +5,6 @@ repos:
       - id: codespell
         additional_dependencies:
           - tomli
-        exclude: "docs/tutorials/more_advanced/knowledge_graph.ipynb|docs/tutorials/evals/evaluating_web_search_agent.ipynb|docs/tutorials/agents/web_search_agent.ipynb|docs/blog/posts/llm-prompt.md"
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: "v0.9.7"
     hooks:

{mirascope-1.23.3 → mirascope-1.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mirascope
-Version: 1.23.3
+Version: 1.24.0
 Summary: LLM abstractions that aren't obstructions
 Project-URL: Homepage, https://mirascope.com
 Project-URL: Documentation, https://mirascope.com/WELCOME
@@ -101,19 +101,19 @@ Provides-Extra: xai
 Requires-Dist: openai<2,>=1.6.0; extra == 'xai'
 Description-Content-Type: text/markdown
 
-<div align="center" justiry="start">
-    <a href="https://mirascope.com">
-        <img align="bottom" src="https://github.com/Mirascope/mirascope/assets/99370834/e403d7ee-f8bc-4df1-b2d0-33763f021c89" alt="Frog Logo" width="84"/><br><img align="bottom" src="https://uploads-ssl.webflow.com/65a6fd6a1c3b2704d6217d3d/65b5674e9ceef563dc57eb11_Medium%20length%20hero%20headline%20goes%20here.svg" width="400" alt="Mirascope"/>
+<p align="center">
+    <a href="https://mirascope.com/#mirascope">
+        <img src="https://github.com/user-attachments/assets/58b04850-8f30-40a6-be68-96ed2aa9b6d8" />
     </a>
-</div>
+</p>
 
 <p align="center">
     <a href="https://github.com/Mirascope/mirascope/actions/workflows/tests.yml" target="_blank"><img src="https://github.com/Mirascope/mirascope/actions/workflows/tests.yml/badge.svg?branch=main" alt="Tests"/></a>
     <a href="https://codecov.io/github/Mirascope/mirascope" target="_blank"><img src="https://codecov.io/github/Mirascope/mirascope/graph/badge.svg?token=HAEAWT3KC9" alt="Coverage"/></a>
-    <a href="https://mirascope.com/WELCOME" target="_blank"><img src="https://img.shields.io/badge/docs-available-brightgreen" alt="Docs"/></a>
+    <a href="https://mirascope.com/docs/mirascope" target="_blank"><img src="https://img.shields.io/badge/docs-available-brightgreen" alt="Docs"/></a>
     <a href="https://pypi.python.org/pypi/mirascope" target="_blank"><img src="https://img.shields.io/pypi/v/mirascope.svg" alt="PyPI Version"/></a>
     <a href="https://pypi.python.org/pypi/mirascope" target="_blank"><img src="https://img.shields.io/pypi/pyversions/mirascope.svg" alt="Stars"/></a>
-    <a href="https://github.com/Mirascope/mirascope/blog/dev/LICENSE"><img src="https://img.shields.io/github/license/Mirascope/mirascope.svg" alt="License"/></a>
+    <a href="https://github.com/Mirascope/mirascope/tree/main/LICENSE"><img src="https://img.shields.io/github/license/Mirascope/mirascope.svg" alt="License"/></a>
     <a href="https://github.com/Mirascope/mirascope/stargazers" target="_blank"><img src="https://img.shields.io/github/stars/Mirascope/mirascope.svg" alt="Stars"/></a>
 </p>
 
@@ -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.3 → mirascope-1.24.0}/README.md

@@ -1,16 +1,16 @@
-<div align="center" justiry="start">
-    <a href="https://mirascope.com">
-        <img align="bottom" src="https://github.com/Mirascope/mirascope/assets/99370834/e403d7ee-f8bc-4df1-b2d0-33763f021c89" alt="Frog Logo" width="84"/><br><img align="bottom" src="https://uploads-ssl.webflow.com/65a6fd6a1c3b2704d6217d3d/65b5674e9ceef563dc57eb11_Medium%20length%20hero%20headline%20goes%20here.svg" width="400" alt="Mirascope"/>
+<p align="center">
+    <a href="https://mirascope.com/#mirascope">
+        <img src="https://github.com/user-attachments/assets/58b04850-8f30-40a6-be68-96ed2aa9b6d8" />
     </a>
-</div>
+</p>
 
 <p align="center">
     <a href="https://github.com/Mirascope/mirascope/actions/workflows/tests.yml" target="_blank"><img src="https://github.com/Mirascope/mirascope/actions/workflows/tests.yml/badge.svg?branch=main" alt="Tests"/></a>
     <a href="https://codecov.io/github/Mirascope/mirascope" target="_blank"><img src="https://codecov.io/github/Mirascope/mirascope/graph/badge.svg?token=HAEAWT3KC9" alt="Coverage"/></a>
-    <a href="https://mirascope.com/WELCOME" target="_blank"><img src="https://img.shields.io/badge/docs-available-brightgreen" alt="Docs"/></a>
+    <a href="https://mirascope.com/docs/mirascope" target="_blank"><img src="https://img.shields.io/badge/docs-available-brightgreen" alt="Docs"/></a>
     <a href="https://pypi.python.org/pypi/mirascope" target="_blank"><img src="https://img.shields.io/pypi/v/mirascope.svg" alt="PyPI Version"/></a>
     <a href="https://pypi.python.org/pypi/mirascope" target="_blank"><img src="https://img.shields.io/pypi/pyversions/mirascope.svg" alt="Stars"/></a>
-    <a href="https://github.com/Mirascope/mirascope/blog/dev/LICENSE"><img src="https://img.shields.io/github/license/Mirascope/mirascope.svg" alt="License"/></a>
+    <a href="https://github.com/Mirascope/mirascope/tree/main/LICENSE"><img src="https://img.shields.io/github/license/Mirascope/mirascope.svg" alt="License"/></a>
     <a href="https://github.com/Mirascope/mirascope/stargazers" target="_blank"><img src="https://img.shields.io/github/stars/Mirascope/mirascope.svg" alt="Stars"/></a>
 </p>
 
@@ -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.0/api_ref/llm/call_response.md

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

mirascope-1.24.0/api_ref/llm/call_response_chunk.md

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

mirascope-1.24.0/api_ref/llm/context.md

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

mirascope-1.24.0/api_ref/llm/override.md

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

mirascope-1.24.0/api_ref/llm/stream.md

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

mirascope-1.24.0/api_ref/llm/tool.md

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

mirascope-1.24.0/api_ref/mcp/client.md

@@ -0,0 +1,3 @@
+# mirascope.mcp.client
+
+::: mirascope.mcp.client

mirascope-1.24.0/api_ref/retries/fallback.md

@@ -0,0 +1,3 @@
+# mirascope.retries.fallback
+
+::: mirascope.retries.fallback

mirascope-1.24.0/api_ref/retries/tenacity.md

@@ -0,0 +1,3 @@
+# mirascope.retries.tenacity
+
+::: mirascope.retries.tenacity

{mirascope-1.23.3 → mirascope-1.24.0}/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.3 → mirascope-1.24.0}/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.3 → mirascope-1.24.0}/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.3 → mirascope-1.24.0}/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.3 → mirascope-1.24.0}/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.3 → mirascope-1.24.0}/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.3 → mirascope-1.24.0}/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.3 → mirascope-1.24.0}/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.3 → mirascope-1.24.0}/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.3 → mirascope-1.24.0}/mirascope/llm/__init__.py

@@ -3,11 +3,13 @@ from ._call import call
 from ._context import context
 from ._override import override
 from .call_response import CallResponse
+from .call_response_chunk import CallResponseChunk
 from .stream import Stream
 from .tool import Tool
 
 __all__ = [
     "CallResponse",
+    "CallResponseChunk",
     "CostMetadata",
     "LocalProvider",
     "Provider",

{mirascope-1.23.3 → mirascope-1.24.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mirascope"
-version = "1.23.3"
+version = "1.24.0"
 description = "LLM abstractions that aren't obstructions"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -209,7 +209,7 @@ venvPath = "."
 venv = ".venv"
 
 [tool.codespell]
-skip = [".git", "*.lock", "./docs/blog/posts/llm-prompt.md"]
+skip = [".git", "*.lock"]
 ignore-words-list = 'EHR,reworkd,ROUGE,rouge,Rouge'
 ignore-regex = 'and buyed some milk'