feat(translator): OpenAI web search annotations passthrough

[cjangrist]

Summary

• Pass through OpenAI url_citation annotations from Chat Completions responses to all downstream formats (Claude citations, Gemini groundingMetadata, Responses annotations)
• Enable built-in tool passthrough (web_search_preview) from Responses→Chat Completions requests
• Streaming: accumulate annotations across chunks, attach on finish events
• Non-streaming: read from message.annotations, attach directly

Test plan

• 9 unit tests (7 new + 2 updated) covering all translation paths
• Multi-chunk annotation accumulation tested (streaming)
• content_part.done and output_item.done both asserted (Responses)
• Built-in tool field preservation verified (search_context_size)
• go test ./... — zero failures
• E2E: 21/21 across 7 distinct native Codex models

🤖 Generated with Claude Code

[gemini-code-assist]

Summary of Changes

Hello @cjangrist, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the translator's capabilities by enabling the seamless propagation of OpenAI's web search annotations and built-in tools across various API formats. The changes ensure that rich contextual information from web searches is preserved and correctly formatted when translating between OpenAI, Claude, Gemini, and Responses APIs, improving the fidelity and utility of translated responses.

Highlights

• OpenAI Web Search Annotations Passthrough: Implemented the passthrough of OpenAI url_citation annotations from Chat Completions responses to all downstream formats, including Claude citations, Gemini groundingMetadata, and Responses annotations.
• Built-in Tool Passthrough: Enabled the direct passthrough of built-in tools, specifically web_search_preview, from Responses to Chat Completions requests.
• Streaming Annotation Accumulation: Introduced logic to accumulate annotations across multiple chunks for streaming responses and attach them correctly upon completion events.
• Non-Streaming Annotation Handling: Ensured that for non-streaming responses, annotations are directly read from message.annotations and attached to the respective output formats.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• internal/translator/openai/claude/openai_claude_response.go
  • Added AnnotationsRaw field to ConvertOpenAIResponseToAnthropicParams to store accumulated annotations.
  • Implemented logic to extract and accumulate url_citation annotations from OpenAI streaming chunks.
  • Modified streaming and non-streaming conversion functions to attach accumulated annotations as citations in the Claude response.
• internal/translator/openai/gemini/openai_gemini_response.go
  • Added AnnotationsRaw field to ConvertOpenAIResponseToGeminiParams for annotation accumulation.
  • Integrated logic to process and accumulate url_citation annotations from OpenAI streaming responses.
  • Updated streaming and non-streaming conversion to map accumulated annotations to groundingMetadata in Gemini responses.
• internal/translator/openai/openai/responses/openai_openai-responses_request.go
  • Modified the request translation logic to explicitly pass through built-in tools (e.g., web_search_preview) from OpenAI Responses format to OpenAI Chat Completions requests, rather than ignoring them.
• internal/translator/openai/openai/responses/openai_openai-responses_response.go
  • Added AnnotationsRaw field to oaiToResponsesState to manage accumulated annotations.
  • Implemented accumulation of url_citation annotations from OpenAI streaming chunks.
  • Ensured that accumulated annotations are attached to response.content_part.done and response.output_item.done events for streaming, and directly to the message content for non-streaming responses.
• test/builtin_tools_translation_test.go
  • Renamed TestOpenAIResponsesToOpenAI_IgnoresBuiltinTools to TestOpenAIResponsesToOpenAI_PassesBuiltinTools.
  • Updated assertions to verify that built-in tools are now correctly passed through, including their type and specific fields like search_context_size.
• test/openai_websearch_translation_test.go
  • Added a new test file containing multiple test cases to validate the correct translation and passthrough of OpenAI web search annotations and built-in tools across streaming and non-streaming scenarios for Claude, Gemini, and OpenAI Responses formats.

Activity

• 9 unit tests were added or updated, covering all translation paths for the new features.
• Multi-chunk annotation accumulation was specifically tested for streaming scenarios.
• Assertions were made for content_part.done and output_item.done in Responses.
• Built-in tool field preservation, such as search_context_size, was verified.
• All go test ./... commands passed without failures.
• End-to-end tests across 7 distinct native Codex models passed 21/21.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request successfully implements the passthrough of OpenAI web search annotations to various downstream formats like Claude, Gemini, and Responses, for both streaming and non-streaming scenarios. The changes also enable the passthrough of built-in tools from Responses to Chat Completions, and the new unit tests provide good coverage for these features. My review focuses on improving code maintainability by addressing several instances of duplicated logic. I've suggested creating helper functions to handle JSON compaction and annotation attachment, which would reduce redundancy and make the code cleaner. Additionally, I've pointed out an opportunity to improve readability by reducing repetitive type assertions.

[cjangrist]

@tianyicui @soffchen @neavo @luispater @hkfires @masrurimz can I please have your thoughts? these pass through search engine tool call grounding references, critical for building trustable answer engines.