[Firebase AI] Add URLContext tool

[andrewheard]

Added support for the URLContext tool which allows developers to provide additional context to the models in the form of URLs.

TODO: A subsequent PR(or CL) should update the changelog with a link to the docs.

Summary of Changes

This pull request integrates the URLContext tool into the Firebase AI SDK, enabling Gemini models to utilize external web content from provided URLs to enrich their responses. This feature enhances the model's ability to understand and generate content based on real-world information, making it more versatile for various applications. The changes involve adding new data models for URL context, updating response structures to include this metadata, and ensuring robust error handling and logging for URL retrieval processes.

Highlights

• New URLContext Tool: Added support for the URLContext tool, allowing developers to provide public web URLs as additional context to Gemini models for more informed responses.
• New Data Structures: Introduced URLContext, URLContextMetadata, and URLMetadata structs to handle URL-based context information within the API.
• Response Metadata Enhancements: The GenerateContentResponse and Candidate structs now include urlContextMetadata and new token count properties (toolUsePromptTokenCount, toolUsePromptTokensDetails) for better usage tracking.
• Logging and Error Handling: A new AILog.MessageCode (urlMetadataUnrecognizedURLRetrievalStatus) has been added for improved logging related to URL retrieval status.
• Comprehensive Testing: Extensive unit and integration tests have been added to validate the functionality of the new URLContext tool across different scenarios, including successful retrievals, mixed validity, and streaming responses.

Changelog

• FirebaseAI/CHANGELOG.md
  • Added an entry for the new feature: 'Added support for Gemini's URL context tool.'
• FirebaseAI/Sources/AILog.swift
  • Added urlMetadataUnrecognizedURLRetrievalStatus to AILog.MessageCode.
• FirebaseAI/Sources/GenerateContentResponse.swift
  • Added toolUsePromptTokenCount and toolUsePromptTokensDetails to UsageMetadata.
  • Added urlContextMetadata to Candidate and its initializer.
  • Updated Decodable conformance for UsageMetadata and Candidate to handle new fields.
• FirebaseAI/Sources/Tool.swift
  • Added urlContext property to Tool struct.
  • Added a static factory method Tool.urlContext() to create a URLContext tool.
• FirebaseAI/Sources/Types/Internal/Tools/URLContext.swift
  • New file defining the URLContext struct.
• FirebaseAI/Sources/Types/Public/URLContextMetadata.swift
  • New file defining URLContextMetadata struct and its Decodable conformance.
• FirebaseAI/Sources/Types/Public/URLMetadata.swift
  • New file defining URLMetadata struct, URLRetrievalStatus enum, and its Decodable conformance.
• FirebaseAI/Tests/TestApp/Tests/Integration/GenerateContentIntegrationTests.swift
  • Added a new integration test generateContent_withURLContext_succeeds to verify the functionality.
• FirebaseAI/Tests/Unit/GenerativeModelGoogleAITests.swift
  • Added unit tests for generateContent_success_urlContext, generateContent_success_urlContext_mixedValidity, and testGenerateContentStream_success_urlContext.
• FirebaseAI/Tests/Unit/GenerativeModelVertexAITests.swift
  • Added unit tests for generateContent_success_urlContext, generateContent_success_urlContext_mixedValidity, testGenerateContent_success_urlContext_retrievedURLPresentOnErrorStatus, and testGenerateContentStream_success_urlContext.
• FirebaseAI/Tests/Unit/MockURLProtocol.swift
  • Minor refactoring of requestHandler guard statement for clarity.
• FirebaseAI/Tests/Unit/Types/GenerateContentResponseTests.swift
  • Added decoding tests for Candidate with urlContextMetadata.

Activity

• google-oss-bot posted 2 warnings: one regarding a missing changelog entry and another about new public headers not being added to the umbrella header.
• paulb777 issued a /gemini summarize command.

[google-oss-bot]

	1 Warning
⚠️	New public headers were added, did you remember to add them to the umbrella header?

Generated by 🚫 Danger

[paulb777]

/gemini summarize

[paulb777]

Going to merge here and rely on a future PR to update the Changelog with a documentation link.