Add URLContextMetadata to Candidate

Author: andrewheard

FirebaseAI/Sources/AILog.swift

@@ -66,6 +66,7 @@ enum AILog {
     case codeExecutionResultUnrecognizedOutcome = 3015
     case executableCodeUnrecognizedLanguage = 3016
     case fallbackValueUsed = 3017
+    case urlMetadataUnrecognizedURLRetrievalStatus = 3018
 
     // SDK State Errors
     case generateContentResponseNoCandidates = 4000

FirebaseAI/Sources/GenerateContentResponse.swift

@@ -154,14 +154,19 @@ public struct Candidate: Sendable {
 
   public let groundingMetadata: GroundingMetadata?
 
+  /// Metadata related to the ``URLContext`` tool.
+  public let urlContextMetadata: URLContextMetadata?
+
   /// Initializer for SwiftUI previews or tests.
   public init(content: ModelContent, safetyRatings: [SafetyRating], finishReason: FinishReason?,
-              citationMetadata: CitationMetadata?, groundingMetadata: GroundingMetadata? = nil) {
+              citationMetadata: CitationMetadata?, groundingMetadata: GroundingMetadata? = nil,
+              urlContextMetadata: URLContextMetadata? = nil) {
     self.content = content
     self.safetyRatings = safetyRatings
     self.finishReason = finishReason
     self.citationMetadata = citationMetadata
     self.groundingMetadata = groundingMetadata
+    self.urlContextMetadata = urlContextMetadata
   }
 
   // Returns `true` if the candidate contains no information that a developer could use.
@@ -499,6 +504,7 @@ extension Candidate: Decodable {
     case finishReason
     case citationMetadata
     case groundingMetadata
+    case urlContextMetadata
   }
 
   /// Initializes a response from a decoder. Used for decoding server responses; not for public
@@ -540,6 +546,14 @@ extension Candidate: Decodable {
       GroundingMetadata.self,
       forKey: .groundingMetadata
     )
+
+    if let urlContextMetadata =
+      try container.decodeIfPresent(URLContextMetadata.self, forKey: .urlContextMetadata),
+      !urlContextMetadata.urlMetadata.isEmpty {
+      self.urlContextMetadata = urlContextMetadata
+    } else {
+      urlContextMetadata = nil
+    }
   }
 }
 

FirebaseAI/Sources/Tool.swift

@@ -63,11 +63,6 @@ public struct GoogleSearch: Sendable {
   public init() {}
 }
 
-@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
-public struct URLContext: Sendable {
-  public init() {}
-}
-
 /// A helper tool that the model may use when generating responses.
 ///
 /// A `Tool` is a piece of code that enables the system to interact with external systems to perform
@@ -235,8 +230,5 @@ extension FunctionCallingConfig.Mode: Encodable {}
 @available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
 extension GoogleSearch: Encodable {}
 
-@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
-extension URLContext: Encodable {}
-
 @available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
 extension ToolConfig: Encodable {}

FirebaseAI/Sources/Types/Public/Tools/URLContext.swift

@@ -0,0 +1,18 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+public struct URLContext: Sendable, Encodable {
+  init() {}
+}

FirebaseAI/Sources/Types/Public/URLContextMetadata.swift

@@ -0,0 +1,33 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/// Metadata related to the ``URLContext`` tool.
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+public struct URLContextMetadata: Sendable, Hashable {
+  /// List of URL context.
+  public let urlMetadata: [URLMetadata]
+}
+
+// MARK: - Codable Conformances
+
+extension URLContextMetadata: Decodable {
+  enum CodingKeys: CodingKey {
+    case urlMetadata
+  }
+
+  public init(from decoder: any Decoder) throws {
+    let container = try decoder.container(keyedBy: CodingKeys.self)
+    urlMetadata = try container.decodeIfPresent([URLMetadata].self, forKey: .urlMetadata) ?? []
+  }
+}

FirebaseAI/Sources/Types/Public/URLMetadata.swift

@@ -0,0 +1,84 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import Foundation
+
+/// Context of a single URL retrieval.
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+public struct URLMetadata: Sendable, Hashable {
+  /// Status of the URL retrieval.
+  public struct URLRetrievalStatus: DecodableProtoEnum, Hashable {
+    enum Kind: String {
+      case unspecified = "URL_RETRIEVAL_STATUS_UNSPECIFIED"
+      case success = "URL_RETRIEVAL_STATUS_SUCCESS"
+      case error = "URL_RETRIEVAL_STATUS_ERROR"
+      case paywall = "URL_RETRIEVAL_STATUS_PAYWALL"
+      case unsafe = "URL_RETRIEVAL_STATUS_UNSAFE"
+    }
+
+    /// Internal only - default value.
+    static let unspecified = URLRetrievalStatus(kind: .unspecified)
+
+    /// URL retrieval succeeded.
+    public static let success = URLRetrievalStatus(kind: .success)
+
+    /// URL retrieval failed due to an error.
+    public static let error = URLRetrievalStatus(kind: .error)
+
+    // URL retrieval failed failed because the content is behind paywall.
+    public static let paywall = URLRetrievalStatus(kind: .paywall)
+
+    // URL retrieval failed because the content is unsafe.
+    public static let unsafe = URLRetrievalStatus(kind: .unsafe)
+
+    /// Returns the raw string representation of the `URLRetrievalStatus` value.
+    public let rawValue: String
+
+    static let unrecognizedValueMessageCode =
+      AILog.MessageCode.urlMetadataUnrecognizedURLRetrievalStatus
+  }
+
+  /// The URL retrieved by the ``URLContext`` tool.
+  public let retrievedURL: URL?
+
+  /// The status of the URL retrieval.
+  public let retrievalStatus: URLRetrievalStatus
+}
+
+// MARK: - Codable Conformances
+
+extension URLMetadata: Decodable {
+  enum CodingKeys: String, CodingKey {
+    case retrievedURL = "retrievedUrl"
+    case retrievalStatus = "urlRetrievalStatus"
+  }
+
+  public init(from decoder: any Decoder) throws {
+    let container = try decoder.container(keyedBy: CodingKeys.self)
+
+    if let retrievedURLString = try container.decodeIfPresent(String.self, forKey: .retrievedURL),
+       let retrievedURL = URL(string: retrievedURLString) {
+      self.retrievedURL = retrievedURL
+    } else {
+      retrievedURL = nil
+    }
+    let retrievalStatus = try container.decodeIfPresent(
+      URLMetadata.URLRetrievalStatus.self, forKey: .retrievalStatus
+    )
+
+    self.retrievalStatus = AILog.safeUnwrap(
+      retrievalStatus, fallback: URLMetadata.URLRetrievalStatus(kind: .unspecified)
+    )
+  }
+}