mirascope 1.22.0__tar.gz → 1.22.2__tar.gz

{mirascope-1.22.0 → mirascope-1.22.2}/.github/workflows/docs.yml

@@ -13,7 +13,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Set up uv
-        run: curl -LsSf https://astral.sh/uv/0.3.0/install.sh | sh
+        run: curl -LsSf https://astral.sh/uv/0.6.10/install.sh | sh
 
       - name: Set up Python
         run: uv python install 3.10

{mirascope-1.22.0 → mirascope-1.22.2}/.github/workflows/lint.yml

@@ -21,11 +21,15 @@ jobs:
       - 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.5.6/install.sh | sh
+        run: curl -LsSf https://astral.sh/uv/0.6.10/install.sh | sh
+
+      - name: Check uv lock file is up-to-date
+        run: uv lock --check
 
       - name: Set Up Python Environment
-        run: uv python install 3.11
+        run: uv python install 3.10
 
       - name: Restore uv cache
         uses: actions/cache@v4

{mirascope-1.22.0 → mirascope-1.22.2}/.github/workflows/release.yml

@@ -19,7 +19,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Set up uv
-        run: curl -LsSf https://astral.sh/uv/0.5.6/install.sh | sh
+        run: curl -LsSf https://astral.sh/uv/0.6.10/install.sh | sh
 
       - name: Set up Python
         run: uv python install 3.10

{mirascope-1.22.0 → mirascope-1.22.2}/.github/workflows/tests.yml

@@ -24,7 +24,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Set up uv
-        run: curl -LsSf https://astral.sh/uv/0.5.6/install.sh | sh
+        run: curl -LsSf https://astral.sh/uv/0.6.10/install.sh | sh
 
       - name: Set up Python ${{ matrix.python-version }}
         run: |

{mirascope-1.22.0 → mirascope-1.22.2}/.gitignore

@@ -150,6 +150,7 @@ venv.bak/
 docs/**/*.html.md
 docs/llms.txt
 build/snippets/
+mkdocs.dev.yml
 
 # mypy
 .mypy_cache/

{mirascope-1.22.0 → mirascope-1.22.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mirascope
-Version: 1.22.0
+Version: 1.22.2
 Summary: LLM abstractions that aren't obstructions
 Project-URL: Homepage, https://mirascope.com
 Project-URL: Documentation, https://mirascope.com/WELCOME
@@ -68,6 +68,7 @@ Requires-Dist: pillow<11,>=10.4.0; extra == 'gemini'
 Provides-Extra: google
 Requires-Dist: google-genai<2,>=1.2.0; extra == 'google'
 Requires-Dist: pillow<11,>=10.4.0; extra == 'google'
+Requires-Dist: proto-plus>=1.24.0; extra == 'google'
 Provides-Extra: groq
 Requires-Dist: groq<1,>=0.9.0; extra == 'groq'
 Provides-Extra: hyperdx

{mirascope-1.22.0 → mirascope-1.22.2}/docs/CONTRIBUTING.md

@@ -149,11 +149,22 @@ We care deeply about maintaining high-quality, up-to-date documentation. This me
 
 The documentation lives in the [docs/](https://github.com/Mirascope/mirascope/tree/main/docs) directory, which can be built by running `uv run mkdocs serve`.
 
-A few key things to note:
+### Fast Docs Development
+
+For faster local documentation development, we provide a script that automatically creates a modified configuration without slow plugins. It can be invoked via: 
+
+```shell
+# Run the fast docs development server
+uv run python scripts/serve_docs_dev.py
+```
+
+Under the hood, this script disables the `social` and `mkdocs-jupyter` plugins, and sets `strict: false`, which significantly speeds up rebuild times during development.
+
+### Documentation Notes
 
 1. We have code examples in the `examples` folder for all code snippets in the documentation, and we maintain snippets for every option (e.g. prompt writing methods, providers, etc.). While this seems unnecessarily cumbersome, these examples operate as tests for type hints because we run `pyright` on all of the examples. When writing documentation that changes existing examples or requires new examples, make sure to properly update the actual code in the `examples/` directory to match the existing structure.
 2. The API reference is generated automatically, but things like new modules still need to be included in the `docs/api` structure for generation to work.
-3. The `docs/tutorials` are written as Jupyter notebooks that get converted into markdown. This conversion will happen on every save when running the server locally, which can make writing docs slow. We recommend setting `strict: false` and commenting out the `mkdocs-jupyter` plugin in `mkdocs.yml` to skip the conversion.
+3. The `docs/tutorials` are written as Jupyter notebooks that get converted into markdown. This conversion will happen on every save when running the server locally, which can make writing docs slow. We recommend using the fast docs development script to address this.
 
 !!! tip "MacOS Users Will Need `cairo`
 

{mirascope-1.22.0 → mirascope-1.22.2}/mirascope/core/google/_utils/_convert_common_call_params.py

@@ -1,8 +1,6 @@
 from typing import cast
 
-from google.genai.types import (
-    GenerationConfigDict,
-)
+from google.genai.types import GenerateContentConfig
 
 from ...base.call_params import CommonCallParams
 from ..call_params import GoogleCallParams
@@ -17,23 +15,24 @@ GOOGLE_PARAM_MAPPING = {
 
 def convert_common_call_params(common_params: CommonCallParams) -> GoogleCallParams:
     """Convert CommonCallParams to Google parameters."""
-    generation_config = {}
+    config = GenerateContentConfig()
 
     for key, value in common_params.items():
         if key not in GOOGLE_PARAM_MAPPING or value is None:
             continue
 
         if key == "stop":
-            generation_config["stop_sequences"] = (
-                [value] if isinstance(value, str) else value
-            )
+            # Google API expects a list of strings for stop sequences
+            if isinstance(value, str):
+                config.stop_sequences = [value]
+            elif isinstance(value, list):
+                config.stop_sequences = value
         else:
-            generation_config[GOOGLE_PARAM_MAPPING[key]] = value
+            target_attr = GOOGLE_PARAM_MAPPING[key]
+            setattr(config, target_attr, value)
 
-    if not generation_config:
+    default_config = GenerateContentConfig()
+    if config == default_config:
         return cast(GoogleCallParams, {})
 
-    return cast(
-        GoogleCallParams,
-        {"generation_config": cast(GenerationConfigDict, generation_config)},
-    )
+    return cast(GoogleCallParams, {"config": config})

{mirascope-1.22.0 → mirascope-1.22.2}/mirascope/core/google/_utils/_setup_call.py

@@ -138,10 +138,12 @@ def setup_call(
 
     if messages[0] and messages[0].get("role") == "system":
         with _generate_content_config_context(call_kwargs) as config:
-            config.system_instruction = [
-                Part.model_validate(part)
-                for part in (messages.pop(0).get("parts") or [])
-            ]
+            system_message = messages.pop(0)
+            message_parts = system_message.get("parts", [])
+            if message_parts:
+                config.system_instruction = [
+                    Part.model_validate(part) for part in message_parts
+                ]
 
     if json_mode:
         with _generate_content_config_context(call_kwargs) as config:

{mirascope-1.22.0 → mirascope-1.22.2}/mkdocs.yml

@@ -316,7 +316,6 @@ nav:
           - Middleware: "learn/extensions/middleware.md"
           - Custom LLM Provider: "learn/extensions/custom_provider.md"
       - MCP - Model Context Protocol:
-          - Server: "learn/mcp/server.md"
           - Client: "learn/mcp/client.md"
   - Integrations:
       - OpenTelemetry: "integrations/otel.md"

{mirascope-1.22.0 → mirascope-1.22.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mirascope"
-version = "1.22.0"
+version = "1.22.2"
 description = "LLM abstractions that aren't obstructions"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -67,7 +67,7 @@ bedrock = [
 ]
 cohere = ["cohere>=5.5.8,<6"]
 gemini = ["google-generativeai>=0.4.0,<1", "pillow>=10.4.0,<11"]
-google = ["google-genai>=1.2.0,<2", "pillow>=10.4.0,<11"]
+google = ["google-genai>=1.2.0,<2", "pillow>=10.4.0,<11", "proto-plus>=1.24.0"]
 groq = ["groq>=0.9.0,<1"]
 tenacity = ["tenacity>=8.4.2,<9"]
 hyperdx = ["hyperdx-opentelemetry>=0.1.0,<1"]

mirascope-1.22.2/scripts/serve_docs_dev.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python
+"""
+Script to run a faster version of mkdocs serve for local documentation development.
+This creates a temporary modified mkdocs config that disables slow plugins.
+"""
+
+import os
+import re
+import subprocess
+from pathlib import Path
+
+# Define paths
+root_dir = Path(__file__).parent.parent
+original_file = root_dir / "mkdocs.yml"
+dev_config_file = root_dir / "mkdocs.dev.yml"
+
+
+def comment_out_plugin(lines: list[str], plugin_name: str) -> list[str]:
+    """Comment out a plugin and its configuration block in the mkdocs.yml file."""
+    # We process the mkdocs.yml file line-by-line rather than trying to parse the YAML
+    # because mkdocs.yml is difficult to parse correctly.
+    in_plugin_block = False
+    modified_lines = lines.copy()
+
+    for i, line in enumerate(modified_lines):
+        stripped_line = line.strip()
+        if stripped_line.startswith("-") and plugin_name in stripped_line:
+            in_plugin_block = True
+            modified_lines[i] = f"# {line}"
+        elif in_plugin_block:
+            if stripped_line.startswith("-") or not stripped_line:
+                in_plugin_block = False
+            else:
+                modified_lines[i] = f"# {line}"
+
+    return modified_lines
+
+
+def main() -> None:
+    print("📚 Setting up fast documentation development server...")  # noqa: T201
+
+    # Read the original mkdocs.yml
+    with open(original_file) as f:
+        lines = f.readlines()
+
+    # Comment out slow plugins
+    lines = comment_out_plugin(lines, "social")
+    lines = comment_out_plugin(lines, "mkdocs-jupyter")
+
+    # Set strict to false for faster builds
+    content = "".join(lines)
+    if "strict:" in content:
+        content = re.sub(r"strict:\s*true", "strict: false", content)
+    else:
+        # If strict isn't found, raise a helpful error
+        raise ValueError(
+            "Could not find 'strict:' setting in mkdocs.yml. "
+            "Please ensure mkdocs.yml contains this setting."
+        )
+
+    # Write the modified configuration to mkdocs.dev.yml
+    with open(dev_config_file, "w") as f:
+        f.write(content)
+
+    print("📝 Created development config at mkdocs.dev.yml")  # noqa: T201
+    print("🚀 Starting mkdocs development server with fast configuration...")  # noqa: T201
+
+    # Run mkdocs serve with the development config
+    try:
+        subprocess.run(["mkdocs", "serve", "-f", str(dev_config_file)])
+    except KeyboardInterrupt:
+        print("\n🛑 Development server stopped")  # noqa: T201
+    finally:
+        # Clean up the temporary file
+        if dev_config_file.exists():
+            os.remove(dev_config_file)
+            print("🧹 Removed temporary config file")  # noqa: T201
+
+
+if __name__ == "__main__":
+    main()

{mirascope-1.22.0 → mirascope-1.22.2}/tests/core/google/_utils/test_convert_common_call_params.py

@@ -1,3 +1,5 @@
+from google.genai.types import GenerateContentConfig
+
 from mirascope.core.base.call_params import CommonCallParams
 from mirascope.core.google._utils._convert_common_call_params import (
     convert_common_call_params,
@@ -13,14 +15,13 @@ def test_google_conversion_full():
         "stop": ["STOP", "END"],
     }
     result = convert_common_call_params(params)
-    assert result == {
-        "generation_config": {
-            "temperature": 0.7,
-            "max_output_tokens": 100,
-            "top_p": 0.9,
-            "stop_sequences": ["STOP", "END"],
-        }
-    }
+
+    config = result.get("config")
+    assert isinstance(config, GenerateContentConfig)
+    assert config.temperature == 0.7
+    assert config.max_output_tokens == 100
+    assert config.top_p == 0.9
+    assert config.stop_sequences == ["STOP", "END"]
 
 
 def test_google_conversion_single_stop():
@@ -30,12 +31,11 @@ def test_google_conversion_single_stop():
         "stop": "STOP",
     }
     result = convert_common_call_params(params)
-    assert result == {
-        "generation_config": {
-            "temperature": 0.7,
-            "stop_sequences": ["STOP"],
-        }
-    }
+
+    config = result.get("config")
+    assert isinstance(config, GenerateContentConfig)
+    assert config.temperature == 0.7
+    assert config.stop_sequences == ["STOP"]
 
 
 def test_google_conversion_empty():
@@ -54,11 +54,10 @@ def test_google_conversion_full_with_invalid_key():
         "invalid": "invalid",  # pyright: ignore [reportAssignmentType]
     }
     result = convert_common_call_params(params)
-    assert result == {
-        "generation_config": {
-            "temperature": 0.7,
-            "max_output_tokens": 100,
-            "top_p": 0.9,
-            "stop_sequences": ["STOP", "END"],
-        }
-    }
+
+    config = result.get("config")
+    assert isinstance(config, GenerateContentConfig)
+    assert config.temperature == 0.7
+    assert config.max_output_tokens == 100
+    assert config.top_p == 0.9
+    assert config.stop_sequences == ["STOP", "END"]

{mirascope-1.22.0 → mirascope-1.22.2}/tests/core/google/_utils/test_setup_call.py

@@ -1,6 +1,7 @@
 """Tests the `google._utils.setup_call` module."""
 
 from collections.abc import Callable
+from typing import cast
 from unittest.mock import MagicMock, patch
 
 import pytest
@@ -17,6 +18,7 @@ from mirascope.core.google._utils._convert_common_call_params import (
     convert_common_call_params,
 )
 from mirascope.core.google._utils._setup_call import setup_call
+from mirascope.core.google.call_params import GoogleCallParams
 from mirascope.core.google.tool import GoogleTool
 
 
@@ -309,3 +311,76 @@ def test_setup_call_vertexai_dynamic_config_non_dict(
     metadata = fn._metadata
     assert "tags" in metadata
     assert "use_vertex_ai" in metadata["tags"]
+
+
+@patch(
+    "mirascope.core.google._utils._setup_call.convert_message_params",
+    new_callable=MagicMock,
+)
+@patch("mirascope.core.google._utils._setup_call._utils", new_callable=MagicMock)
+@patch("mirascope.core.google._utils._setup_call.Client", new_callable=MagicMock)
+def test_setup_call_with_call_params(
+    mock_client_class: MagicMock,
+    mock_utils: MagicMock,
+    mock_convert_message_params: MagicMock,
+    mock_base_setup_call: MagicMock,
+) -> None:
+    """Tests the `setup_call` function with direct parameters in call_params."""
+    mock_client = MagicMock()
+    mock_client_class.return_value = mock_client
+    mock_utils.setup_call = mock_base_setup_call
+    fn = MagicMock()
+
+    call_params = cast(GoogleCallParams, {"temperature": 0.8, "top_p": 0.7})
+
+    create, prompt_template, messages, tool_types, call_kwargs = setup_call(
+        model="google-1.5-flash",
+        client=None,
+        fn=fn,
+        fn_args={},
+        dynamic_config=None,
+        tools=None,
+        json_mode=False,
+        call_params=call_params,
+        response_model=None,
+        stream=False,
+    )
+
+    # These parameters should be passed to the base setup_call
+    mock_base_setup_call.assert_called_with(
+        fn,
+        {},
+        None,
+        None,
+        GoogleTool,
+        call_params,  # Call params should be passed directly
+        convert_common_call_params,
+    )
+
+    # Now test with a GenerateContentConfig parameter
+    mock_base_setup_call.reset_mock()
+    call_params = cast(GoogleCallParams, {"temperature": 0.9, "top_k": 10})
+
+    create, prompt_template, messages, tool_types, call_kwargs = setup_call(
+        model="google-1.5-flash",
+        client=None,
+        fn=fn,
+        fn_args={},
+        dynamic_config=None,
+        tools=None,
+        json_mode=False,
+        call_params=call_params,
+        response_model=None,
+        stream=False,
+    )
+
+    # These parameters should be passed to the base setup_call
+    mock_base_setup_call.assert_called_with(
+        fn,
+        {},
+        None,
+        None,
+        GoogleTool,
+        call_params,  # Call params should be passed directly
+        convert_common_call_params,
+    )

{mirascope-1.22.0 → mirascope-1.22.2}/uv.lock

@@ -1,5 +1,4 @@
 version = 1
-revision = 1
 requires-python = ">=3.10"
 resolution-markers = [
     "python_full_version < '3.11' and sys_platform == 'linux'",
@@ -3170,7 +3169,7 @@ wheels = [
 
 [[package]]
 name = "mirascope"
-version = "1.21.6"
+version = "1.22.1"
 source = { editable = "." }
 dependencies = [
     { name = "docstring-parser" },
@@ -3203,6 +3202,7 @@ gemini = [
 google = [
     { name = "google-genai" },
     { name = "pillow" },
+    { name = "proto-plus" },
 ]
 groq = [
     { name = "groq" },
@@ -3314,6 +3314,7 @@ requires-dist = [
     { name = "opentelemetry-sdk", marker = "extra == 'opentelemetry'", specifier = ">=1.22.0,<2" },
     { name = "pillow", marker = "extra == 'gemini'", specifier = ">=10.4.0,<11" },
     { name = "pillow", marker = "extra == 'google'", specifier = ">=10.4.0,<11" },
+    { name = "proto-plus", marker = "extra == 'google'", specifier = ">=1.24.0" },
     { name = "pydantic", specifier = ">=2.7.4,<3.0" },
     { name = "pydub", marker = "extra == 'realtime'", specifier = ">=0.25.1,<1" },
     { name = "sounddevice", marker = "extra == 'realtime'", specifier = ">=0.5.1,<1" },
@@ -3322,7 +3323,6 @@ requires-dist = [
     { name = "typing-extensions", specifier = ">=4.10.0" },
     { name = "websockets", marker = "extra == 'realtime'", specifier = ">=13.1,<14" },
 ]
-provides-extras = ["anthropic", "azure", "bedrock", "cohere", "gemini", "google", "groq", "tenacity", "hyperdx", "langfuse", "litellm", "logfire", "mistral", "openai", "opentelemetry", "vertex", "realtime", "mcp", "xai"]
 
 [package.metadata.requires-dev]
 dev = [

mirascope-1.22.0/docs/learn/mcp/server.md

@@ -1,98 +0,0 @@
-# MCP Server
-
-!!! warning "This interface is deprecated!"
-
-    We have updated the Mirascope MCP Client module such that the `sse_client` and `stdio_client` properly handle connecting to any MCP server.
-
-    Given the introduction of `FastMCP` into the official MCP SDK, there's no reason to use this interface.
-
-    Instead, we recommend using the official SDK to build your servers (to which you can easily connect your Mirascope code now).
-
-MCP (Model Context Protocol) Server in Mirascope enables you to expose resources, tools, and prompts to LLM clients through a standardized protocol. This allows for secure and controlled interactions between host applications (like Claude Desktop) and local services.
-
-## Basic Usage and Syntax
-
-Let's build a simple book recommendation server using MCP:
-
-```python  hl_lines="7 10 27-32 40"
---8<-- "examples/learn/mcp/server_decorators.py:3"
-```
-
-This example demonstrates:
-
-1. Creating an MCP server with the `MCPServer` class
-2. Registering a tool to get book recommendations by genre
-3. Exposing a books database as a resource
-4. Creating a prompt template for book recommendations
-5. Running the server asynchronously
-
-## Server Components
-
-### Tools
-
-Tools in MCP Server expose callable functions to clients. Tools can be registered using the `@app.tool()` decorator, which follows the same patterns as described in the [Tools](../tools.md) documentation:
-
-```python
---8<-- "examples/learn/mcp/server_decorators.py:12:26"
-```
-
-The `@app.tool()` decorator supports all the same functionality as the standard Mirascope tool decorators, including:
-
-- Function-based tools
-- Class-based tools inheriting from `BaseTool`
-- Tool configurations and validation
-- Computed fields and dynamic configuration
-
-See the [Tools documentation](../tools.md) for more details on defining and using tools.
-
-### Resources
-
-Resources provide access to data through URIs. They can be registered using the `@app.resource()` decorator with configuration options:
-
-```python
---8<-- "examples/learn/mcp/server_decorators.py:29:39"
-```
-
-Resources support both synchronous and asynchronous functions, making them flexible for different types of data access.
-
-### Prompts
-
-Prompts define reusable message templates. They can be registered using the `@app.prompt()` decorator, which provides the same functionality as the standard Mirascope `@prompt_template` decorator described in the [Prompts](../prompts.md) documentation:
-
-```python
---8<-- "examples/learn/mcp/server_decorators.py:42:49"
-```
-
-The `@app.prompt()` decorator supports all the features of standard Mirascope prompts, including:
-
-- String templates
-- Multi-line prompts
-- Chat history
-- Object attribute access
-- Format specifiers
-- Computed fields and dynamic configuration
-
-See the [Prompts documentation](../prompts.md) for more details on creating and using prompts.
-
-## Alternative Definition Style
-
-In addition to using decorators, you can also define your functions first and then register them when creating the MCP server. This style enables better function reusability and separation of concerns:
-
-```python hl_lines="46-59"
---8<-- "examples/learn/mcp/server.py:3:69"
-```
-
-This alternative style offers several advantages:
-
-1. **Function Reusability**: Functions can be used both independently and as part of the MCP server
-2. **Cleaner Separation**: Clear separation between function definitions and server configuration
-3. **Easier Testing**: Functions can be tested in isolation before being registered with the server
-4. **Code Organization**: Related functions can be grouped together in separate modules
-
-The same applies for prompts defined with `@prompt_template` - see the [Prompts](../prompts.md) documentation for more details about prompt reusability.
-
-Both the decorator style and this alternative style are fully supported - choose the one that better fits your application's needs.
-
-## Next Steps
-
-By leveraging MCP Server in Mirascope, you can create secure and standardized integrations between LLM clients and local services. This enables powerful capabilities while maintaining control over how LLMs interact with your systems.