Merge pull request #905 from Mirascope/fix-902

Fix 902 and 903

Author: willbakst

docs/CONTRIBUTING.md

@@ -155,6 +155,15 @@ A few key things to note:
 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.
 
+!!! tip "MacOS Users Will Need `cairo`
+
+    If you're developing using MacOS, you'll need to follow these steps:
+
+    1. `brew install cairo`
+    2. `export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:/opt/homebrew/lib/pkgconfig:$PKG_CONFIG_PATH"`
+    3. `export DYLD_LIBRARY_PATH="/usr/local/lib:/opt/homebrew/lib:$DYLD_LIBRARY_PATH"`
+    4. `source ~/.bash_profile`
+
 ## Testing
 
 All changes to the codebase must be properly unit tested. If a change requires updating an existing unit test, make sure to think through if the change is breaking.

mirascope/core/google/tool.py

@@ -70,48 +70,58 @@ def format_book(title: str, author: str) -> str:
             fn["parameters"] = model_schema
 
         if "parameters" in fn:
-            # Resolve $defs and $ref
+            # Define a function to handle both ref resolution and examples conversion
+            def resolve_refs_and_fix_examples(
+                schema: dict[str, Any], defs: dict[str, Any] | None = None
+            ) -> dict[str, Any]:
+                """Recursively resolve $ref references and fix examples/example fields."""
+                # If this is a reference, resolve it
+                if "$ref" in schema:
+                    ref = schema["$ref"]
+                    if ref.startswith("#/$defs/") and defs:
+                        ref_key = ref.replace("#/$defs/", "")
+                        if ref_key in defs:
+                            # Merge the definition with the current schema (excluding $ref)
+                            resolved = {
+                                **{k: v for k, v in schema.items() if k != "$ref"},
+                                **resolve_refs_and_fix_examples(defs[ref_key], defs),
+                            }
+                            return resolved
+
+                # Handle examples -> example conversion
+                result = {}
+                for key, value in schema.items():
+                    # Convert "examples" to "example" for Google Schema
+                    if key == "examples":
+                        result["example"] = value
+                    elif isinstance(value, dict):
+                        result[key] = resolve_refs_and_fix_examples(value, defs)
+                    elif isinstance(value, list):
+                        result[key] = [
+                            resolve_refs_and_fix_examples(item, defs)
+                            if isinstance(item, dict)
+                            else item
+                            for item in value
+                        ]
+                    else:
+                        result[key] = value
+                return result
+
+            # Extract $defs if they exist
+            defs = {}
             if "$defs" in fn["parameters"]:
                 defs = fn["parameters"].pop("$defs")
 
-                def resolve_refs(schema: dict[str, Any]) -> dict[str, Any]:
-                    """Recursively resolve $ref references using the $defs dictionary."""
-                    # If this is a reference, resolve it
-                    if "$ref" in schema:
-                        ref = schema["$ref"]
-                        if ref.startswith("#/$defs/"):
-                            ref_key = ref.replace("#/$defs/", "")
-                            if ref_key in defs:
-                                # Merge the definition with the current schema (excluding $ref)
-                                resolved = {
-                                    **{k: v for k, v in schema.items() if k != "$ref"},
-                                    **resolve_refs(defs[ref_key]),
-                                }
-                                return resolved
-
-                    # Process all other keys recursively
-                    result = {}
-                    for key, value in schema.items():
-                        if isinstance(value, dict):
-                            result[key] = resolve_refs(value)
-                        elif isinstance(value, list):
-                            result[key] = [
-                                resolve_refs(item) if isinstance(item, dict) else item
-                                for item in value
-                            ]
-                        else:
-                            result[key] = value
-                    return result
-
-                # Resolve all references in the parameters
-                fn["parameters"] = resolve_refs(fn["parameters"])
+            # Resolve all references in the parameters and fix examples
+            fn["parameters"] = resolve_refs_and_fix_examples(fn["parameters"], defs)
 
             def handle_enum_schema(prop_schema: dict[str, Any]) -> dict[str, Any]:
                 if "enum" in prop_schema:
                     prop_schema["format"] = "enum"
                 return prop_schema
 
             # Process properties after resolving references
+            # We're already handling examples -> example conversion recursively above
             fn["parameters"]["properties"] = {
                 prop: {
                     key: value
@@ -120,6 +130,7 @@ def handle_enum_schema(prop_schema: dict[str, Any]) -> dict[str, Any]:
                 }
                 for prop, prop_schema in fn["parameters"]["properties"].items()
             }
+
         return Tool(function_declarations=[FunctionDeclaration(**fn)])
 
     @classmethod

pyproject.toml

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

tests/core/google/test_tool.py

@@ -10,6 +10,7 @@
     Tool,
     Type,
 )
+from pydantic import Field
 
 from mirascope.core.base.tool import BaseTool
 from mirascope.core.google.tool import GoogleTool
@@ -18,10 +19,23 @@
 class FormatBook(GoogleTool):
     """Returns the title and author nicely formatted."""
 
-    title: str
+    title: str = Field(..., examples=["The Name of the Wind"])
     author: str
     genre: Literal["fantasy", "scifi"]
 
+    model_config = {
+        "json_schema_extra": {
+            "examples": [
+                {
+                    "title": "The Way of Kings",
+                    "author": "Brandon Sanderson",
+                    "genre": "fantasy",
+                },
+                {"title": "Dune", "author": "Frank Herbert", "genre": "scifi"},
+            ]
+        }
+    }
+
     def call(self) -> str:
         return f"{self.title} by {self.author}"
 
@@ -54,7 +68,9 @@ def test_google_tool() -> None:
                 parameters=Schema(
                     type=Type.OBJECT,
                     properties={
-                        "title": Schema(type=Type.STRING),
+                        "title": Schema(
+                            type=Type.STRING, example=["The Name of the Wind"]
+                        ),
                         "author": Schema(type=Type.STRING),
                         "genre": Schema(
                             type=Type.STRING,
@@ -63,6 +79,14 @@ def test_google_tool() -> None:
                         ),
                     },
                     required=["title", "author", "genre"],
+                    example=[
+                        {
+                            "title": "The Way of Kings",
+                            "author": "Brandon Sanderson",
+                            "genre": "fantasy",
+                        },
+                        {"title": "Dune", "author": "Frank Herbert", "genre": "scifi"},
+                    ],
                 ),
             )
         ],