feat: enhance GoogleClient to include grounding and URL context metadata

[rasphlat]

Add grounding_metadata and url_context_metadata to Google Client Response

Summary

This PR exposes grounding_metadata and url_context_metadata from Google's API response as dynamic attributes on ClientResponse when using invoke() or a_invoke(). These metadata objects are only added when present and non-empty.

Motivation

When using Google's grounding tools (Google Search, Google Maps, URL Context), the API returns rich metadata that enables building citation experiences, verifying sources, and understanding how the model grounded its response. Previously, this metadata was discarded.

Supported Tools

🔍 Google Search Grounding

When using google_search, the grounding_metadata provides:

• web_search_queries: The search queries the model executed
• grounding_chunks: Web sources with URIs and titles
• grounding_supports: Maps text segments to source citations (enables inline citations)
• search_entry_point: HTML/CSS for rendering search suggestions

Documentation

🗺️ Google Maps Grounding

When using google_maps, the grounding_metadata contains location-based grounding information from Google Maps data, enabling place-aware responses with verifiable sources.

Documentation

🔗 URL Context Tool

When using url_context, the url_context_metadata provides:

• url_metadata: Array of retrieved URLs with their retrieval status (URL_RETRIEVAL_STATUS_SUCCESS, etc.)

This helps verify which URLs were successfully fetched and used to ground the response.

Documentation

Usage

from google.genai import types

# Example with Google Search
response = client.invoke(
    "Who won Euro 2024?",
    tools=[{"google_search": types.GoogleSearch()}]
)

# Access grounding metadata if present
if hasattr(response, "grounding_metadata"):
    metadata = response.grounding_metadata
    print("Search queries:", metadata.web_search_queries)
    print("Sources:", metadata.grounding_chunks)
    
    # Build inline citations
    for support in metadata.grounding_supports:
        print(f"Text: {support.segment.text}")
        print(f"Source indices: {support.grounding_chunk_indices}")

# Example with URL Context
if hasattr(response, "url_context_metadata"):
    for url_info in response.url_context_metadata.url_metadata:
        print(f"URL: {url_info.retrieved_url}")
        print(f"Status: {url_info.url_retrieval_status}")

Notes

• Metadata objects are native Google types (types.GroundingMetadata, types.UrlContextMetadata)
• Use hasattr() to check for presence before accessing
• Only affects invoke() and a_invoke() methods