[Firebase AI] Add starter types for Live API

Author: andrewheard

FirebaseAI/Sources/Types/Internal/Live/ActivityHandling.swift

@@ -0,0 +1,35 @@
+// 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
+
+/// The different ways of handling user activity.
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+public struct ActivityHandling: EncodableProtoEnum, Hashable, Sendable {
+  enum Kind: String {
+    case interrupts = "START_OF_ACTIVITY_INTERRUPTS"
+    case noInterrupt = "NO_INTERRUPTION"
+  }
+
+  /// If true, start of activity will interrupt the model's response (also
+  /// called "barge in"). The model's current response will be cut-off in the
+  /// moment of the interruption. This is the default behavior.
+  public static let interrupts = ActivityHandling(kind: .interrupts)
+
+  /// The model's response will not be interrupted.
+  public static let noInterrupt = ActivityHandling(kind: .noInterrupt)
+
+  /// Returns the raw string representation of the `ActivityHandling` value.
+  public let rawValue: String
+}

FirebaseAI/Sources/Types/Internal/Live/BidiGenerateContentClientContent.swift

@@ -0,0 +1,34 @@
+// 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
+
+/// Incremental update of the current conversation delivered from the client.
+/// All the content here is unconditionally appended to the conversation
+/// history and used as part of the prompt to the model to generate content.
+///
+/// A message here will interrupt any current model generation.
+struct BidiGenerateContentClientContent: Encodable {
+  /// The content appended to the current conversation with the model.
+  ///
+  /// For single-turn queries, this is a single instance. For multi-turn
+  /// queries, this is a repeated field that contains conversation history and
+  /// latest request.
+  let turns: [ModelContent]?
+
+  /// If true, indicates that the server content generation should start with
+  /// the currently accumulated prompt. Otherwise, the server will await
+  /// additional messages before starting generation.
+  let turnComplete: Bool?
+}

FirebaseAI/Sources/Types/Internal/Live/BidiGenerateContentClientMessage.swift

@@ -0,0 +1,30 @@
+// 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
+
+/// Messages sent by the client in the BidiGenerateContent RPC call.
+enum BidiGenerateContentClientMessage: Encodable {
+  /// Message to be sent in the first and only first client message.
+  case setup(BidiGenerateContentSetup)
+
+  /// Incremental update of the current conversation delivered from the client.
+  case clientContent(BidiGenerateContentClientContent)
+
+  /// User input that is sent in real time.
+  case realtimeInput(BidiGenerateContentRealtimeInput)
+
+  /// Response to a `ToolCallMessage` received from the server.
+  case toolResponse(BidiGenerateContentToolResponse)
+}

FirebaseAI/Sources/Types/Internal/Live/BidiGenerateContentRealtimeInput.swift

@@ -0,0 +1,63 @@
+// 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
+
+/// User input that is sent in real time.
+///
+/// This is different from `ClientContentUpdate` in a few ways:
+///
+/// - Can be sent continuously without interruption to model generation.
+/// - If there is a need to mix data interleaved across the
+///   `ClientContentUpdate` and the `RealtimeUpdate`, server attempts to
+///   optimize for best response, but there are no guarantees.
+/// - End of turn is not explicitly specified, but is rather derived from user
+///   activity (for example, end of speech).
+/// - Even before the end of turn, the data is processed incrementally
+///   to optimize for a fast start of the response from the model.
+/// - Is always assumed to be the user's input (cannot be used to populate
+///   conversation history).
+struct BidiGenerateContentRealtimeInput: Encodable {
+  /// These form the realtime audio input stream.
+  let audio: Data?
+
+  /// Indicates that the audio stream has ended, e.g. because the microphone was
+  /// turned off.
+  ///
+  /// This should only be sent when automatic activity detection is enabled
+  /// (which is the default).
+  ///
+  /// The client can reopen the stream by sending an audio message.
+  let audioStreamEnd: Bool?
+
+  /// These form the realtime video input stream.
+  let video: Data?
+
+  /// These form the realtime text input stream.
+  let text: String?
+
+  /// Marks the start of user activity.
+  struct ActivityStart: Encodable {}
+
+  /// Marks the start of user activity. This can only be sent if automatic
+  /// (i.e. server-side) activity detection is disabled.
+  let activityStart: ActivityStart?
+
+  /// Marks the end of user activity.
+  struct ActivityEnd: Encodable {}
+
+  /// Marks the end of user activity. This can only be sent if automatic (i.e.
+  // server-side) activity detection is disabled.
+  let activityEnd: ActivityEnd?
+}

FirebaseAI/Sources/Types/Internal/Live/BidiGenerateContentServerContent.swift

@@ -0,0 +1,52 @@
+// 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
+
+/// Incremental server update generated by the model in response to client
+/// messages.
+///
+/// Content is generated as quickly as possible, and not in realtime. Clients
+/// may choose to buffer and play it out in realtime.
+struct BidiGenerateContentServerContent: Decodable {
+  /// The content that the model has generated as part of the current
+  /// conversation with the user.
+  let modelTurn: ModelContent?
+
+  /// If true, indicates that the model is done generating. Generation will only
+  /// start in response to additional client messages. Can be set alongside
+  /// `content`, indicating that the `content` is the last in the turn.
+  let turnComplete: Bool?
+
+  /// If true, indicates that a client message has interrupted current model
+  /// generation. If the client is playing out the content in realtime, this is a
+  /// good signal to stop and empty the current queue. If the client is playing
+  /// out the content in realtime, this is a good signal to stop and empty the
+  /// current playback queue.
+  let interrupted: Bool?
+
+  /// If true, indicates that the model is done generating.
+  ///
+  /// When model is interrupted while generating there will be no
+  /// 'generation_complete' message in interrupted turn, it will go through
+  /// 'interrupted > turn_complete'.
+  ///
+  /// When model assumes realtime playback there will be delay between
+  /// generation_complete and turn_complete that is caused by model waiting for
+  /// playback to finish.
+  let generationComplete: Bool?
+
+  /// Metadata specifies sources used to ground generated content.
+  let groundingMetadata: GroundingMetadata?
+}

FirebaseAI/Sources/Types/Internal/Live/BidiGenerateContentServerMessage.swift

@@ -0,0 +1,45 @@
+// 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
+
+/// Response message for BidiGenerateContent RPC call.
+struct BidiGenerateContentServerMessage: Decodable {
+  /// The type of the message.
+  enum MessageType: Decodable {
+    /// Sent in response to a `BidiGenerateContentSetup` message from the client.
+    case setupComplete(BidiGenerateContentSetupComplete)
+
+    /// Content generated by the model in response to client messages.
+    case serverContent(BidiGenerateContentServerContent)
+
+    /// Request for the client to execute the `function_calls` and return the
+    /// responses with the matching `id`s.
+    case toolCall(BidiGenerateContentToolCall)
+
+    /// Notification for the client that a previously issued
+    /// `ToolCallMessage` with the specified `id`s should have been not executed
+    /// and should be cancelled.
+    case toolCallCancellation(BidiGenerateContentToolCallCancellation)
+
+    /// Server will disconnect soon.
+    case goAway(GoAway)
+  }
+
+  /// The message type.
+  let messageType: MessageType
+
+  /// Usage metadata about the response(s).
+  let usageMetadata: GenerateContentResponse.UsageMetadata?
+}

FirebaseAI/Sources/Types/Internal/Live/BidiGenerateContentSetup.swift

@@ -0,0 +1,57 @@
+// 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
+
+/// Message to be sent in the first and only first
+/// `BidiGenerateContentClientMessage`. Contains configuration that will apply
+/// for the duration of the streaming RPC.
+///
+/// Clients should wait for a `BidiGenerateContentSetupComplete` message before
+/// sending any additional messages.
+struct BidiGenerateContentSetup: Encodable {
+  /// The fully qualified name of the publisher model.
+  ///
+  /// Publisher model format:
+  /// `projects/{project}/locations/{location}/publishers/*/models/*`
+  let model: String
+
+  /// Generation config.
+  ///
+  /// The following fields aren't supported:
+  ///
+  ///  - `response_logprobs`
+  ///  - `response_mime_type`
+  ///  - `logprobs`
+  ///  - `response_schema`
+  ///  - `stop_sequence`
+  ///  - `routing_config`
+  ///  - `audio_timestamp`
+  let generationConfig: GenerationConfig?
+
+  /// The user provided system instructions for the model.
+  /// Note: only text should be used in parts and content in each part will be
+  /// in a separate paragraph.
+  let systemInstruction: ModelContent?
+
+  /// A list of `Tools` the model may use to generate the next response.
+  ///
+  /// A `Tool` is a piece of code that enables the system to interact with
+  /// external systems to perform an action, or set of actions, outside of
+  /// knowledge and scope of the model.
+  let tools: [Tool]?
+
+  /// Configures the handling of realtime input.
+  let realtimeInputConfig: RealtimeInputConfig?
+}

FirebaseAI/Sources/Types/Internal/Live/BidiGenerateContentSetupComplete.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.
+
+import Foundation
+
+/// Sent in response to a `BidiGenerateContentSetup` message from the client.
+struct BidiGenerateContentSetupComplete: Decodable {}

FirebaseAI/Sources/Types/Internal/Live/BidiGenerateContentToolCall.swift

@@ -0,0 +1,22 @@
+// 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
+
+/// Request for the client to execute the `function_calls` and return the
+/// responses with the matching `id`s.
+struct BidiGenerateContentToolCall: Decodable {
+  /// The function call to be executed.
+  let functionCalls: [FunctionCall]?
+}

FirebaseAI/Sources/Types/Internal/Live/BidiGenerateContentToolCallCancellation.swift

@@ -0,0 +1,25 @@
+// 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
+
+/// Notification for the client that a previously issued `ToolCallMessage`
+/// with the specified `id`s should have been not executed and should be
+/// cancelled. If there were side-effects to those tool calls, clients may
+/// attempt to undo the tool calls. This message occurs only in cases where the
+/// clients interrupt server turns.
+struct BidiGenerateContentToolCallCancellation: Decodable {
+  /// The ids of the tool calls to be cancelled.
+  let ids: [String]?
+}