firebase-ios-sdk/FirebaseAI/Sources/Protocols/Public/LanguageModelProvider.swift

// Copyright 2026 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.

#if compiler(>=6.2.3)
  /// A type that represents a large language model (LLM).
  public protocol LanguageModelProvider: Sendable {
    /// Returns an instance of the ``FirebaseAI/LanguageModel`` corresponding to this provider.
    ///
    /// > Important: This method is for **internal use only** and may change at any time.
    ///
    /// - Parameter firebaseAI: A ``FirebaseAI`` instance that provides necessary context for
    ///   instantiating the model, such as the API configuration.
    func _languageModel(firebaseAI: FirebaseAI) -> any FirebaseAI.LanguageModel
  }

  public extension LanguageModelProvider where Self == GeminiModelProvider {
    /// **[Public Preview]** Creates a ``GeminiModelProvider`` for the specified model name.
    ///
    /// > Warning: This API is a public preview and may be subject to change.
    ///
    /// - Parameters:
    ///   - name: The name of the model to use; see [available model names
    ///     ](https://firebase.google.com/docs/ai-logic/models#available-model-names)
    ///     for a list of supported model names.
    ///   - safetySettings: Settings to adjust the safety filters for potentially harmful content
    ///     generated by the model.
    ///   - requestOptions: Configuration parameters for sending requests to the backend.
    static func geminiModel(name: String, safetySettings: [SafetySetting]? = nil,
                            requestOptions: RequestOptions = RequestOptions())
      -> GeminiModelProvider {
      return GeminiModelProvider(
        modelName: name,
        safetySettings: safetySettings,
        requestOptions: requestOptions
      )
    }
  }

  public extension LanguageModelProvider where Self == FirebaseAI.SystemLanguageModel {
    /// **[Public Preview]** Creates a model provider for the on-device `SystemLanguageModel`
    /// provided by Apple's Foundation Models framework.
    ///
    /// > Warning: This API is a public preview and may be subject to change.
    ///
    /// For more details about the configuration options, see the Apple
    /// [documentation](https://developer.apple.com/documentation/foundationmodels/systemlanguagemodel/init(usecase:guardrails:)).
    ///
    /// - Parameters:
    ///   - useCase: The ``FirebaseAI/SystemLanguageModel/UseCase`` that the model is tuned for;
    ///     defaults to ``FirebaseAI/SystemLanguageModel/UseCase/general``.
    ///   - guardrails: The ``FirebaseAI/SystemLanguageModel/Guardrails`` that configure how the
    ///     model handles potentially harmful content; defaults to
    ///     ``FirebaseAI/SystemLanguageModel/Guardrails/default``.
    static func systemModel(useCase: FirebaseAI.SystemLanguageModel.UseCase = .general,
                            guardrails: FirebaseAI.SystemLanguageModel.Guardrails = .default)
      -> FirebaseAI.SystemLanguageModel {
      return FirebaseAI.SystemLanguageModel(useCase: useCase, guardrails: guardrails)
    }
  }

  public extension LanguageModelProvider where Self == HybridModelProvider {
    /// **[Public Preview]** Creates a ``HybridModelProvider`` for the specified models.
    ///
    /// > Warning: This API is a public preview and may be subject to change.
    ///
    /// - Parameters:
    ///   - primary: The main, or default, model to use.
    ///   - secondary: The backup model to fallback to if the `primary` model is unavailable.
    static func hybridModel(primary: any LanguageModelProvider,
                            secondary: any LanguageModelProvider) -> HybridModelProvider {
      return HybridModelProvider(primary: primary, secondary: secondary)
    }
  }

  // Provides backwards compatibility for the
  // `FirebaseAI.generativeModelSession(model:tools:instructions:)` method where `model` was a
  // simple `String` containing a Gemini model name.
  extension String: LanguageModelProvider {
    public func _languageModel(firebaseAI: FirebaseAI) -> any FirebaseAI.LanguageModel {
      return firebaseAI.geminiModel(name: self)
    }
  }
#endif // compiler(>=6.2.3)