fix(gemini): add additionalContent with grounding metadata to Structured handler

[angus-mcritchie]

Summary

Add additionalContent with grounding metadata (citations, search queries, URL metadata) to the Gemini Structured handler, matching the behavior of the Text handler.

Problem

When using Gemini with provider tools like google_search for structured responses, the grounding metadata (citations, web search queries, search entry point, URL metadata) is returned by the API but not captured in the response.

The Text handler correctly captures this data in additionalContent (lines 201-207), but the Structured handler does not (line 227+).

This means:

• Prism::structured() with google_search tool → No citations available
• Prism::text() with google_search tool → Citations available ✓

Solution

Add the same additionalContent population to Structured.php that exists in Text.php:

additionalContent: Arr::whereNotNull([
    'citations' => CitationMapper::mapFromGemini(data_get($data, 'candidates.0', [])) ?: null,
    'searchEntryPoint' => data_get($data, 'candidates.0.groundingMetadata.searchEntryPoint'),
    'searchQueries' => data_get($data, 'candidates.0.groundingMetadata.webSearchQueries'),
    'urlMetadata' => data_get($data, 'candidates.0.urlContextMetadata.urlMetadata'),
]),

Changes

• src/Providers/Gemini/Handlers/Structured.php:
  • Added use Prism\Prism\Providers\Gemini\Maps\CitationMapper;
  • Added additionalContent parameter to Step constructor in addStep() method

Testing

Verified fix works by:

1. Making a structured Gemini request with google_search provider tool
2. Confirming additionalContent['citations'] is now populated with 6 citations
3. Before fix: additionalContent was empty

Related

This brings Structured.php in line with Text.php behavior for Gemini grounding metadata.

[Copilot]

Pull request overview

This PR adds support for capturing grounding metadata (citations, search queries, URL metadata) in Gemini's Structured handler responses, bringing it into parity with the Text handler. When using provider tools like google_search with structured outputs, this metadata is now properly captured in the additionalContent field.

Changes:

• Added CitationMapper import to Structured handler
• Populated additionalContent with grounding metadata in the Step constructor

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.