[Firebase AI] Add Generable macro for schema generation

.github/workflows/common.yml

@@ -105,6 +105,12 @@ jobs:
       with:
         path: .build
         key: ${{needs.spm-package-resolved.outputs.cache_key}}
+    - name: Disable SwiftPM prebuilts in Xcode
+      run: |
+        defaults write com.apple.dt.Xcode IDEPackageEnablePrebuilts -bool NO
+        defaults read com.apple.dt.Xcode IDEPackageEnablePrebuilts
+    - name: Clear SwiftPM caches
+      run: rm -rf ~/.swiftpm/artifacts ~/.swiftpm/cache
     - name: Xcode
       run: sudo xcode-select -s /Applications/${{ matrix.xcode }}.app/Contents/Developer
     - name: Run setup command, if needed.

FirebaseAI/Sources/Macros/FirebaseAILogicPlugin.swift

@@ -0,0 +1,23 @@
+// 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 SwiftCompilerPlugin
+import SwiftSyntaxMacros
+
+@main
+struct FirebaseAILogicPlugin: CompilerPlugin {
+  let providingMacros: [Macro.Type] = [
+    StringifyMacro.self,
+  ]
+}

FirebaseAI/Sources/Macros/StringifyMacro.swift

@@ -0,0 +1,37 @@
+// 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 SwiftSyntax
+import SwiftSyntaxBuilder
+import SwiftSyntaxMacros
+
+/// Implementation of the `stringify` macro, which takes an expression
+/// of any type and produces a tuple containing the value of that expression
+/// and the source code that produced the value. For example
+///
+///     #stringify(x + y)
+///
+///  will expand to
+///
+///     (x + y, "x + y")
+public struct StringifyMacro: ExpressionMacro {
+  public static func expansion(of node: some FreestandingMacroExpansionSyntax,
+                               in context: some MacroExpansionContext) -> ExprSyntax {
+    guard let argument = node.arguments.first?.expression else {
+      fatalError("compiler bug: the macro does not have any arguments")
+    }
+
+    return "(\(argument), \(literal: argument.description))"
+  }
+}

FirebaseAI/Sources/Types/Public/Generable/ConvertibleFromModelOutput.swift

@@ -0,0 +1,44 @@
+// 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
+
+/// A type that can be initialized from model output.
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+public protocol ConvertibleFromModelOutput: SendableMetatype {
+  /// Creates an instance from content generated by a model.
+  ///
+  /// Conformance to this protocol is provided by the `@Generable` macro. A manual implementation
+  /// may be used to map values onto properties using different names. To manually initialize your
+  /// type from model output, decode the values as shown below:
+  ///
+  /// ```swift
+  /// struct Person: ConvertibleFromModelOutput {
+  ///     var name: String
+  ///     var age: Int
+  ///
+  ///     init(_ content: ModelOutput) {
+  ///         self.name = try content.value(forProperty: "firstName")
+  ///         self.age = try content.value(forProperty: "ageInYears")
+  ///     }
+  /// }
+  /// ```
+  ///
+  /// - Important: If your type also conforms to ``ConvertibleToModelOutput``, it is critical
+  /// that this implementation be symmetrical with
+  /// ``ConvertibleToModelOutput/modelOutput``.
+  ///
+  /// - SeeAlso: `@Generable` macro ``Generable(description:)``
+  init(_ content: ModelOutput) throws
+}

FirebaseAI/Sources/Types/Public/Generable/ConvertibleToModelOutput.swift

@@ -0,0 +1,43 @@
+// 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 type that can be converted to model output.
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+public protocol ConvertibleToModelOutput {
+  /// This instance represented as model output.
+  ///
+  /// Conformance to this protocol is provided by the `@Generable` macro. A manual implementation
+  /// may be used to map values onto properties using different names. Use the `modelOutput`
+  /// property as shown below, to manually return a new ``ModelOutput`` with the properties
+  /// you specify.
+  ///
+  /// ```swift
+  /// struct Person: ConvertibleToModelOutput {
+  ///    var name: String
+  ///    var age: Int
+  ///
+  ///    var modelOutput: ModelOutput {
+  ///        ModelOutput(properties: [
+  ///            "firstName": name,
+  ///            "ageInYears": age
+  ///        ])
+  ///    }
+  /// }
+  /// ```
+  ///
+  /// - Important: If your type also conforms to ``ConvertibleFromModelOutput``, it is
+  /// critical that this implementation be symmetrical with
+  /// ``ConvertibleFromModelOutput/init(_:)``.
+  var modelOutput: ModelOutput { get }
+}

FirebaseAI/Sources/Types/Public/Generable/Generable.swift

@@ -0,0 +1,205 @@
+// 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
+
+/// A type that the model uses when responding to prompts.
+///
+/// Annotate your Swift structure or enumeration with the `@Generable` macro to allow the model to
+/// respond to prompts by generating an instance of your type. Use the `@Guide` macro to provide
+/// natural language descriptions of your properties, and programmatically control the values that
+/// the model can generate.
+///
+/// ```swift
+/// @Generable
+/// struct SearchSuggestions {
+///     @Guide(description: "A list of suggested search terms", .count(4))
+///     var searchTerms: [SearchTerm]
+///
+///     @Generable
+///     struct SearchTerm {
+///         // Use a generation identifier for data structures the framework generates.
+///         var id: GenerationID
+///
+///         @Guide(description: "A 2 or 3 word search term, like 'Beautiful sunsets'")
+///         var searchTerm: String
+///     }
+/// }
+/// ```
+/// - SeeAlso: `@Generable` macro ``Generable(description:)`` and  `@Guide` macro
+/// ``Guide(description:)``.
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+public protocol Generable: ConvertibleFromModelOutput, ConvertibleToModelOutput {
+  /// An instance of the JSON schema.
+  static var jsonSchema: JSONSchema { get }
+}
+
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+extension Optional where Wrapped: Generable {}
+
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+extension Optional: ConvertibleToModelOutput where Wrapped: ConvertibleToModelOutput {
+  public var modelOutput: ModelOutput {
+    guard let self else { return ModelOutput(kind: .null) }
+
+    return ModelOutput(self)
+  }
+}
+
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+extension Bool: Generable {
+  public static var jsonSchema: JSONSchema {
+    JSONSchema(kind: .boolean, source: "Bool")
+  }
+
+  public init(_ content: ModelOutput) throws {
+    guard case let .bool(value) = content.kind else {
+      throw Self.decodingFailure(content)
+    }
+    self = value
+  }
+
+  public var modelOutput: ModelOutput {
+    return ModelOutput(kind: .bool(self))
+  }
+}
+
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+extension String: Generable {
+  public static var jsonSchema: JSONSchema {
+    JSONSchema(kind: .string, source: "String")
+  }
+
+  public init(_ content: ModelOutput) throws {
+    guard case let .string(value) = content.kind else {
+      throw Self.decodingFailure(content)
+    }
+    self = value
+  }
+
+  public var modelOutput: ModelOutput {
+    return ModelOutput(kind: .string(self))
+  }
+}
+
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+extension Int: Generable {
+  public static var jsonSchema: JSONSchema {
+    JSONSchema(kind: .integer, source: "Int")
+  }
+
+  public init(_ content: ModelOutput) throws {
+    guard case let .number(value) = content.kind, let integer = Int(exactly: value) else {
+      throw Self.decodingFailure(content)
+    }
+    self = integer
+  }
+
+  public var modelOutput: ModelOutput {
+    return ModelOutput(kind: .number(Double(self)))
+  }
+}
+
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+extension Float: Generable {
+  public static var jsonSchema: JSONSchema {
+    JSONSchema(kind: .double, source: "Number")
+  }
+
+  public init(_ content: ModelOutput) throws {
+    guard case let .number(value) = content.kind else {
+      throw Self.decodingFailure(content)
+    }
+    self = Float(value)
+  }
+
+  public var modelOutput: ModelOutput {
+    return ModelOutput(kind: .number(Double(self)))
+  }
+}
+
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+extension Double: Generable {
+  public static var jsonSchema: JSONSchema {
+    JSONSchema(kind: .double, source: "Number")
+  }
+
+  public init(_ content: ModelOutput) throws {
+    guard case let .number(value) = content.kind else {
+      throw Self.decodingFailure(content)
+    }
+    self = value
+  }
+
+  public var modelOutput: ModelOutput {
+    return ModelOutput(kind: .number(self))
+  }
+}
+
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+extension Decimal: Generable {
+  public static var jsonSchema: JSONSchema {
+    JSONSchema(kind: .double, source: "Number")
+  }
+
+  public init(_ content: ModelOutput) throws {
+    guard case let .number(value) = content.kind else {
+      throw Self.decodingFailure(content)
+    }
+    self = Decimal(value)
+  }
+
+  public var modelOutput: ModelOutput {
+    let doubleValue = (self as NSDecimalNumber).doubleValue
+    return ModelOutput(kind: .number(doubleValue))
+  }
+}
+
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+extension Array: Generable where Element: Generable {
+  public static var jsonSchema: JSONSchema {
+    JSONSchema(kind: .array(item: Element.self), source: String(describing: self))
+  }
+}
+
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+extension Array: ConvertibleToModelOutput where Element: ConvertibleToModelOutput {
+  public var modelOutput: ModelOutput {
+    let values = map { $0.modelOutput }
+    return ModelOutput(kind: .array(values))
+  }
+}
+
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+extension Array: ConvertibleFromModelOutput where Element: ConvertibleFromModelOutput {
+  public init(_ content: ModelOutput) throws {
+    guard case let .array(values) = content.kind else {
+      throw Self.decodingFailure(content)
+    }
+    self = try values.map { try Element($0) }
+  }
+}
+
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+private extension ConvertibleFromModelOutput {
+  /// Helper method to create ``GenerativeModel/GenerationError/decodingFailure(_:)`` instances.
+  static func decodingFailure(_ content: ModelOutput) -> GenerativeModel.GenerationError {
+    return GenerativeModel.GenerationError.decodingFailure(
+      GenerativeModel.GenerationError.Context(debugDescription: """
+      \(content.self) does not contain \(Self.self).
+      Content: \(content)
+      """)
+    )
+  }
+}

FirebaseAI/Sources/Types/Public/Generable/GenerationGuide.swift

@@ -0,0 +1,17 @@
+// 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.
+
+/// Guides that control how values are generated.
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+public struct GenerationGuide<Value> {}