[Firebase AI] Add CodeExecution tool support

FirebaseAI/CHANGELOG.md

@@ -1,3 +1,8 @@
+# 12.3.0
+- [feature] Added support for the Code Execution tool, which enables the model
+  to generate and run code to perform complex tasks like solving mathematical
+  equations or visualizing data. (#15280)
+
 # 12.2.0
 - [feature] Added support for returning thought summaries, which are synthesized
   versions of a model's internal reasoning process. (#15096)

FirebaseAI/Sources/AILog.swift

@@ -62,6 +62,8 @@ enum AILog {
     case decodedInvalidCitationPublicationDate = 3011
     case generateContentResponseUnrecognizedContentModality = 3012
     case decodedUnsupportedImagenPredictionType = 3013
+    case codeExecutionResultUnrecognizedOutcome = 3014
+    case executableCodeUnrecognizedLanguage = 3015
 
     // SDK State Errors
     case generateContentResponseNoCandidates = 4000

FirebaseAI/Sources/ModelContent.swift

@@ -39,6 +39,8 @@ struct InternalPart: Equatable, Sendable {
     case fileData(FileData)
     case functionCall(FunctionCall)
     case functionResponse(FunctionResponse)
+    case executableCode(ExecutableCode)
+    case codeExecutionResult(CodeExecutionResult)
   }
 
   let data: OneOfData
@@ -85,6 +87,16 @@ public struct ModelContent: Equatable, Sendable {
         return FunctionResponsePart(
           functionResponse, isThought: part.isThought, thoughtSignature: part.thoughtSignature
         )
+      case let .executableCode(executableCode):
+        return ExecutableCodePart(
+          executableCode, isThought: part.isThought, thoughtSignature: part.thoughtSignature
+        )
+      case let .codeExecutionResult(codeExecutionResult):
+        return CodeExecutionResultPart(
+          codeExecutionResult: codeExecutionResult,
+          _isThought: part.isThought,
+          thoughtSignature: part.thoughtSignature
+        )
       }
     }
   }
@@ -194,6 +206,8 @@ extension InternalPart.OneOfData: Codable {
     case fileData
     case functionCall
     case functionResponse
+    case executableCode
+    case codeExecutionResult
   }
 
   public func encode(to encoder: Encoder) throws {
@@ -209,6 +223,10 @@ extension InternalPart.OneOfData: Codable {
       try container.encode(functionCall, forKey: .functionCall)
     case let .functionResponse(functionResponse):
       try container.encode(functionResponse, forKey: .functionResponse)
+    case let .executableCode(executableCode):
+      try container.encode(executableCode, forKey: .executableCode)
+    case let .codeExecutionResult(codeExecutionResult):
+      try container.encode(codeExecutionResult, forKey: .codeExecutionResult)
     }
   }
 
@@ -224,6 +242,12 @@ extension InternalPart.OneOfData: Codable {
       self = try .functionCall(values.decode(FunctionCall.self, forKey: .functionCall))
     } else if values.contains(.functionResponse) {
       self = try .functionResponse(values.decode(FunctionResponse.self, forKey: .functionResponse))
+    } else if values.contains(.executableCode) {
+      self = try .executableCode(values.decode(ExecutableCode.self, forKey: .executableCode))
+    } else if values.contains(.codeExecutionResult) {
+      self = try .codeExecutionResult(
+        values.decode(CodeExecutionResult.self, forKey: .codeExecutionResult)
+      )
     } else {
       let unexpectedKeys = values.allKeys.map { $0.stringValue }
       throw DecodingError.dataCorrupted(DecodingError.Context(

FirebaseAI/Sources/Tool.swift

@@ -71,17 +71,18 @@ public struct GoogleSearch: Sendable {
 public struct Tool: Sendable {
   /// A list of `FunctionDeclarations` available to the model.
   let functionDeclarations: [FunctionDeclaration]?
+
   /// Specifies the Google Search configuration.
   let googleSearch: GoogleSearch?
 
-  init(functionDeclarations: [FunctionDeclaration]?) {
-    self.functionDeclarations = functionDeclarations
-    googleSearch = nil
-  }
+  let codeExecution: CodeExecution?
 
-  init(googleSearch: GoogleSearch) {
+  init(functionDeclarations: [FunctionDeclaration]? = nil,
+       googleSearch: GoogleSearch? = nil,
+       codeExecution: CodeExecution? = nil) {
+    self.functionDeclarations = functionDeclarations
     self.googleSearch = googleSearch
-    functionDeclarations = nil
+    self.codeExecution = codeExecution
   }
 
   /// Creates a tool that allows the model to perform function calling.
@@ -126,6 +127,13 @@ public struct Tool: Sendable {
   public static func googleSearch(_ googleSearch: GoogleSearch = GoogleSearch()) -> Tool {
     return self.init(googleSearch: googleSearch)
   }
+
+  /// Creates a tool that allows the model to execute code.
+  ///
+  /// For more details, see ``CodeExecution``.
+  public static func codeExecution() -> Tool {
+    return self.init(codeExecution: CodeExecution())
+  }
 }
 
 /// Configuration for specifying function calling behavior.

FirebaseAI/Sources/Types/Internal/InternalPart.swift

@@ -63,6 +63,54 @@ struct FunctionResponse: Codable, Equatable, Sendable {
   }
 }
 
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+struct ExecutableCode: Codable, Equatable, Sendable {
+  struct Language: CodableProtoEnum, Sendable, Equatable {
+    enum Kind: String {
+      case unspecified = "LANGUAGE_UNSPECIFIED"
+      case python = "PYTHON"
+    }
+
+    let rawValue: String
+
+    static let unrecognizedValueMessageCode =
+      AILog.MessageCode.executableCodeUnrecognizedLanguage
+  }
+
+  let language: Language?
+  let code: String?
+
+  init(language: Language, code: String) {
+    self.language = language
+    self.code = code
+  }
+}
+
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+struct CodeExecutionResult: Codable, Equatable, Sendable {
+  struct Outcome: CodableProtoEnum, Sendable, Equatable {
+    enum Kind: String {
+      case unspecified = "OUTCOME_UNSPECIFIED"
+      case ok = "OUTCOME_OK"
+      case failed = "OUTCOME_FAILED"
+      case deadlineExceeded = "OUTCOME_DEADLINE_EXCEEDED"
+    }
+
+    let rawValue: String
+
+    static let unrecognizedValueMessageCode =
+      AILog.MessageCode.codeExecutionResultUnrecognizedOutcome
+  }
+
+  let outcome: Outcome?
+  let output: String?
+
+  init(outcome: Outcome, output: String) {
+    self.outcome = outcome
+    self.output = output
+  }
+}
+
 @available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
 struct ErrorPart: Part, Error {
   let error: Error

FirebaseAI/Sources/Types/Public/Part.swift

@@ -202,3 +202,117 @@ public struct FunctionResponsePart: Part {
     self.thoughtSignature = thoughtSignature
   }
 }
+
+/// A part containing code that was executed by the model.
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+public struct ExecutableCodePart: Part {
+  /// The language of the code in an ``ExecutableCodePart``.
+  public struct Language: Sendable, Equatable, CustomStringConvertible {
+    let internalLanguage: ExecutableCode.Language
+
+    /// The Python programming language.
+    public static let python = ExecutableCodePart.Language(ExecutableCode.Language(kind: .python))
+
+    public var description: String { internalLanguage.rawValue }
+
+    init(_ language: ExecutableCode.Language) {
+      internalLanguage = language
+    }
+  }
+
+  let executableCode: ExecutableCode
+  let _isThought: Bool?
+  let thoughtSignature: String?
+
+  /// The language of the code.
+  public var language: ExecutableCodePart.Language {
+    ExecutableCodePart.Language(
+      // Fallback to "LANGUAGE_UNSPECIFIED" if the value is ever omitted by the backend; this should
+      // never happen.
+      executableCode.language ?? ExecutableCode.Language(kind: .unspecified)
+    )
+  }
+
+  /// The code that was executed.
+  public var code: String {
+    // Fallback to empty string if `code` is ever omitted by the backend; this should never happen.
+    executableCode.code ?? ""
+  }
+
+  public var isThought: Bool { _isThought ?? false }
+
+  public init(language: ExecutableCodePart.Language, code: String) {
+    self.init(
+      ExecutableCode(language: language.internalLanguage, code: code),
+      isThought: nil,
+      thoughtSignature: nil
+    )
+  }
+
+  init(_ executableCode: ExecutableCode, isThought: Bool?, thoughtSignature: String?) {
+    self.executableCode = executableCode
+    _isThought = isThought
+    self.thoughtSignature = thoughtSignature
+  }
+}
+
+/// The result of executing code.
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+public struct CodeExecutionResultPart: Part {
+  /// The outcome of a code execution.
+  public struct Outcome: Sendable, Equatable, CustomStringConvertible {
+    let internalOutcome: CodeExecutionResult.Outcome
+
+    /// The code executed without errors.
+    public static let ok = CodeExecutionResultPart.Outcome(CodeExecutionResult.Outcome(kind: .ok))
+
+    /// The code failed to execute.
+    public static let failed =
+      CodeExecutionResultPart.Outcome(CodeExecutionResult.Outcome(kind: .failed))
+
+    /// The code took too long to execute.
+    public static let deadlineExceeded =
+      CodeExecutionResultPart.Outcome(CodeExecutionResult.Outcome(kind: .deadlineExceeded))
+
+    public var description: String { internalOutcome.rawValue }
+
+    init(_ outcome: CodeExecutionResult.Outcome) {
+      internalOutcome = outcome
+    }
+  }
+
+  let codeExecutionResult: CodeExecutionResult
+  let _isThought: Bool?
+  let thoughtSignature: String?
+
+  /// The outcome of the code execution.
+  public var outcome: CodeExecutionResultPart.Outcome {
+    CodeExecutionResultPart.Outcome(
+      // Fallback to "OUTCOME_UNSPECIFIED" if this value is ever omitted by the backend; this should
+      // never happen.
+      codeExecutionResult.outcome ?? CodeExecutionResult.Outcome(kind: .unspecified)
+    )
+  }
+
+  /// The output of the code execution.
+  public var output: String {
+    // Fallback to empty string if `output` is omitted by the backend; this should never happen.
+    codeExecutionResult.output ?? ""
+  }
+
+  public var isThought: Bool { _isThought ?? false }
+
+  public init(outcome: CodeExecutionResultPart.Outcome, output: String) {
+    self.init(
+      codeExecutionResult: CodeExecutionResult(outcome: outcome.internalOutcome, output: output),
+      _isThought: nil,
+      thoughtSignature: nil
+    )
+  }
+
+  init(codeExecutionResult: CodeExecutionResult, _isThought: Bool?, thoughtSignature: String?) {
+    self.codeExecutionResult = codeExecutionResult
+    self._isThought = _isThought
+    self.thoughtSignature = thoughtSignature
+  }
+}

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

@@ -0,0 +1,21 @@
+// 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.
+
+/// A tool that allows the model to execute code.
+///
+/// This tool can be used to solve complex problems, for example, by generating and executing Python
+/// code to solve a math problem.
+public struct CodeExecution: Sendable, Encodable {
+  init() {}
+}

FirebaseAI/Tests/TestApp/Sources/Constants.swift

@@ -25,6 +25,7 @@ public enum ModelNames {
   public static let gemini2FlashLite = "gemini-2.0-flash-lite-001"
   public static let gemini2FlashPreviewImageGeneration = "gemini-2.0-flash-preview-image-generation"
   public static let gemini2_5_Flash = "gemini-2.5-flash"
+  public static let gemini2_5_FlashLite = "gemini-2.5-flash-lite"
   public static let gemini2_5_Pro = "gemini-2.5-pro"
   public static let gemma3_4B = "gemma-3-4b-it"
 }

FirebaseAI/Tests/TestApp/Tests/Integration/GenerateContentIntegrationTests.swift

@@ -418,6 +418,34 @@ struct GenerateContentIntegrationTests {
     }
   }
 
+  @Test(arguments: InstanceConfig.allConfigs)
+  func generateContent_codeExecution_succeeds(_ config: InstanceConfig) async throws {
+    let model = FirebaseAI.componentInstance(config).generativeModel(
+      modelName: ModelNames.gemini2_5_FlashLite,
+      generationConfig: generationConfig,
+      tools: [.codeExecution()]
+    )
+    let prompt = """
+    What is the sum of the first 5 prime numbers? Generate and run code for the calculation.
+    """
+
+    let response = try await model.generateContent(prompt)
+
+    let candidate = try #require(response.candidates.first)
+    let executableCodeParts = candidate.content.parts.compactMap { $0 as? ExecutableCodePart }
+    #expect(executableCodeParts.count == 1)
+    let executableCodePart = try #require(executableCodeParts.first)
+    #expect(executableCodePart.language == .python)
+    #expect(executableCodePart.code.contains("sum"))
+    let codeExecutionResults = candidate.content.parts.compactMap { $0 as? CodeExecutionResultPart }
+    #expect(codeExecutionResults.count == 1)
+    let codeExecutionResultPart = try #require(codeExecutionResults.first)
+    #expect(codeExecutionResultPart.outcome == .ok)
+    #expect(codeExecutionResultPart.output.contains("28")) // 2 + 3 + 5 + 7 + 11 = 28
+    let text = try #require(response.text)
+    #expect(text.contains("28"))
+  }
+
   // MARK: Streaming Tests
 
   @Test(arguments: [