Move Firebase AI logic to a separate package (#290)

Author: jacobsimionato

README.md

@@ -48,13 +48,20 @@ final catalog = CoreCatalogItems.asCatalog().copyWith([
 ]);
 
 /// Initializing the library.
-late final _uiAgent = UiAgent(
-  '''
+final genUiManager = GenUiManager(catalog: catalog);
+final aiClient = FirebaseAiClient(
+  systemInstruction: '''
   You are a bicycle maintenance assistant who is an expert in diagnosing issues and
   giving step-by-step instructions.
   ''',
-  catalog: catalog,
+  tools: genUiManager.getTools(),
+);
+late final _uiAgent = UiAgent(
+  genUiManager: genUiManager,
+  aiClient: aiClient,
   onSurfaceAdded: _onSurfaceAdded,
+  onSurfaceDeleted: (_) {},
+  onTextResponse: (_) {},
   // ignore: avoid_print
   onWarning: (value) => print('Warning from UiAgent: $value'),
 );
@@ -107,10 +114,11 @@ Widget build(BuildContext context) {
 
 ## Packages
 
-| Package                                              | Description                                                                   | Version                                                                                                              |
-| ---------------------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| [flutter_genui](packages/flutter_genui/)             | (work in progress) A framework to employ Generative UI.                       | [![pub package](https://img.shields.io/pub/v/flutter_genui.svg)](https://pub.dev/packages/flutter_genui)             |
-| [dart_schema_builder](packages/dart_schema_builder/) | (work in progress) A fully featured Dart JSON Schema package with validation. | [![pub package](https://img.shields.io/pub/v/dart_schema_builder.svg)](https://pub.dev/packages/dart_schema_builder) |
+| Package                                              | Description                                                                   |
+| ---------------------------------------------------- | ----------------------------------------------------------------------------- |
+| [flutter_genui](packages/flutter_genui/)             | (work in progress) A framework to employ Generative UI.                       |
+| [flutter_genui_firebase_ai](packages/flutter_genui_firebase_ai/) | (work in progress) Firebase AI integration for flutter_genui.     |
+| [dart_schema_builder](packages/dart_schema_builder/) | (work in progress) A fully featured Dart JSON Schema package with validation. |
 
 ## Usage
 

examples/simple_chat/lib/main.dart

@@ -5,6 +5,7 @@
 import 'package:flutter/material.dart';
 import 'package:firebase_core/firebase_core.dart';
 import 'package:flutter_genui/flutter_genui.dart';
+import 'package:flutter_genui_firebase_ai/flutter_genui_firebase_ai.dart';
 import 'package:simple_chat/message.dart';
 import 'firebase_options.dart';
 import 'package:logging/logging.dart';
@@ -40,22 +41,34 @@ class ChatScreen extends StatefulWidget {
 class _ChatScreenState extends State<ChatScreen> {
   final TextEditingController _textController = TextEditingController();
   final List<MessageController> _messages = [];
-  // TODO: Demonstrate how to create a GenerativeModel via
-  // FirebaseAI.googleAI().generativeModel and pass it as a dependency here.
-  late final UiAgent _uiAgent = UiAgent(
-    '''
+  late final GenUiManager _genUiManager;
+  late final UiAgent _uiAgent;
+  final ScrollController _scrollController = ScrollController();
+
+  @override
+  void initState() {
+    super.initState();
+    const instruction = '''
     You are a helpful assistant who chats with user,
     giving exactly one response for each user message.
     Your responses should contain acknowledgment
     of the user message.
-    ''',
-    catalog: CoreCatalogItems.asCatalog(),
-    onSurfaceAdded: _handleSurfaceAdded,
-    onTextResponse: _onTextResponse,
-    // ignore: avoid_print
-    onWarning: (value) => print('Warning from UiAgent: $value'),
-  );
-  final ScrollController _scrollController = ScrollController();
+    ''';
+    final catalog = CoreCatalogItems.asCatalog();
+    _genUiManager = GenUiManager(catalog: catalog);
+    final aiClient = FirebaseAiClient(
+      systemInstruction: '$instruction\n\n${GenUiPromptFragments.basicChat}',
+      tools: _genUiManager.getTools(),
+    );
+    _uiAgent = UiAgent(
+      genUiManager: _genUiManager,
+      aiClient: aiClient,
+      onSurfaceAdded: _handleSurfaceAdded,
+      onTextResponse: _onTextResponse,
+      // ignore: avoid_print
+      onWarning: (value) => print('Warning from UiAgent: $value'),
+    );
+  }
 
   void _handleSurfaceAdded(SurfaceAdded surface) {
     if (!mounted) return;

examples/simple_chat/pubspec.yaml

@@ -14,10 +14,11 @@ dependencies:
     sdk: flutter
 
   cupertino_icons: ^1.0.8
-  firebase_ai: ^3.0.0
   firebase_core: ^4.0.0
   flutter_genui:
     path: ../../packages/flutter_genui
+  flutter_genui_firebase_ai:
+    path: ../../packages/flutter_genui_firebase_ai
   logging: ^1.3.0
 
 dev_dependencies:

examples/travel_app/lib/main.dart

@@ -9,6 +9,7 @@ import 'package:firebase_app_check/firebase_app_check.dart';
 import 'package:firebase_core/firebase_core.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_genui/flutter_genui.dart';
+import 'package:flutter_genui_firebase_ai/flutter_genui_firebase_ai.dart';
 import 'package:logging/logging.dart';
 
 import 'firebase_options.dart';

examples/travel_app/pubspec.yaml

@@ -15,15 +15,15 @@ dependencies:
   dart_schema_builder:
     path: ../../packages/dart_schema_builder
   file: ^7.0.1
-  firebase_ai: ^3.0.0
   firebase_app_check: ^0.4.0
-  firebase_auth: ^6.0.0
   firebase_core: ^4.0.0
   firebase_core_platform_interface: ^6.0.0
   flutter:
     sdk: flutter
   flutter_genui:
     path: ../../packages/flutter_genui
+  flutter_genui_firebase_ai:
+    path: ../../packages/flutter_genui_firebase_ai
   flutter_markdown: ^0.7.1
   json_rpc_2: ^4.0.0
   logging: ^1.3.0

packages/flutter_genui/README.md

@@ -4,12 +4,14 @@ A Flutter package for building dynamic, conversational user interfaces powered b
 
 `flutter_genui` allows you to create applications where the UI is not static or predefined, but is instead constructed by an AI in real-time based on a conversation with the user. This enables highly flexible, context-aware, and interactive user experiences.
 
+This package provides the core functionality for GenUI. For a concrete implementation that uses Firebase AI, see the `flutter_genui_firebase_ai` package.
+
 ## Features
 
 - **Dynamic UI Generation**: Render Flutter UIs from structured data returned by a generative AI.
 - **Simplified Conversation Flow**: A high-level `UiAgent` facade manages the interaction loop with the AI.
 - **Customizable Widget Catalog**: Define a "vocabulary" of Flutter widgets that the AI can use to build the interface.
-- **Extensible AI Client**: Abstract interface for connecting to different AI model backends. A ready-to-use `GeminiAiClient` for Firebase is included.
+- **Extensible AI Client**: Abstract interface for connecting to different AI model backends.
 - **Event Handling**: Capture user interactions (button clicks, text input) and send them back to the AI as context for the next turn in the conversation.
 
 ## Core Concepts
@@ -20,7 +22,7 @@ The package is built around three main components:
 
 2. **`Catalog`**: A collection of `CatalogItem`s that defines the set of widgets the AI is allowed to use. Each `CatalogItem` specifies a widget's name (for the AI to reference), a data schema for its properties, and a builder function to render the Flutter widget.
 
-3. **`AiClient`**: An interface for communicating with a generative AI model. The package includes `GeminiAiClient` for interacting with Gemini models via the [Firebase AI Logic SDK](https://pub.dev/packages/firebase_ai).
+3. **`AiClient`**: An interface for communicating with a generative AI model. For a concrete implementation, see `FirebaseAiClient` in the `flutter_genui_firebase_ai` package.
 
 ## Getting Started
 
@@ -29,6 +31,7 @@ To use `flutter_genui`, you need to initialize a `UiAgent`, provide it with a sy
 ```dart
 import 'package:flutter/material.dart';
 import 'package:flutter_genui/flutter_genui.dart';
+import 'package:flutter_genui_firebase_ai/flutter_genui_firebase_ai.dart';
 
 void main() {
   // Initialize Firebase, etc.
@@ -51,9 +54,14 @@ class _MyAppState extends State<MyApp> {
     super.initState();
 
     // 1. Create a UiAgent with a system instruction
+    final genUiManager = GenUiManager(catalog: CoreCatalogItems.asCatalog());
+    final aiClient = FirebaseAiClient(
+      systemInstruction: 'You are a helpful AI assistant that builds UIs.',
+      tools: genUiManager.getTools(),
+    );
     _uiAgent = UiAgent(
-      'You are a helpful AI assistant that builds UIs.',
-      catalog: CoreCatalogItems.asCatalog(),
+      genUiManager: genUiManager,
+      aiClient: aiClient,
       onSurfaceAdded: _onSurfaceAdded,
     );
   }

packages/flutter_genui/USAGE.md

@@ -42,17 +42,21 @@ If `flutterfire configure` fails, try one or all of these:
 
 ### Employ `flutter_genui`
 
-For a complete example, refer to [main.dart in the minimal_genui example](../../examples/minimal_genui/lib/main.dart). The following steps outline the details of setting up your project to use `flutter_genui`:
+For a complete example, refer to [main.dart in the simple_chat example](../../examples/simple_chat/lib/main.dart). The following steps outline the details of setting up your project to use `flutter_genui`:
 
-1. In your `pubspec.yaml` file, add `flutter_genui` to the `dependencies` section with one of the following options:
+1. In your `pubspec.yaml` file, add `flutter_genui` and `flutter_genui_firebase_ai` to the `dependencies` section with one of the following options:
 
    - Reference the github project directly:
 
    ```yaml
    flutter_genui:
-   git:
-     url: https://github.com/flutter/genui.git
-     path: packages/flutter_genui
+     git:
+       url: https://github.com/flutter/genui.git
+       path: packages/flutter_genui
+   flutter_genui_firebase_ai:
+     git:
+       url: https://github.com/flutter/genui.git
+       path: packages/flutter_genui_firebase_ai
    ```
 
    - In the future: download from [pub.dev](https://pub.dev)! (We're not ready to publish this as a package until the API is more stable.)
@@ -72,8 +76,14 @@ For a complete example, refer to [main.dart in the minimal_genui example](../../
    @override
    void initState() {
      super.initState();
+     final genUiManager = GenUiManager(catalog: CoreCatalogItems.asCatalog());
+     final aiClient = FirebaseAiClient(
+       systemInstruction: 'You are a helpful AI assistant.',
+       tools: genUiManager.getTools(),
+     );
      uiAgent = UiAgent(
-       'You are a helpful AI assistant.',
+       genUiManager: genUiManager,
+       aiClient: aiClient,
        onSurfaceAdded: _onSurfaceAdded,
      );
    }

packages/flutter_genui/lib/flutter_genui.dart

@@ -3,7 +3,6 @@
 // found in the LICENSE file.
 
 export 'src/ai_client/ai_client.dart';
-export 'src/ai_client/firebase_ai_client.dart';
 export 'src/catalog/core_widgets/checkbox_group.dart';
 export 'src/catalog/core_widgets/column.dart';
 export 'src/catalog/core_widgets/elevated_button.dart';
@@ -15,10 +14,13 @@ export 'src/core/core_catalog.dart';
 export 'src/core/genui_configuration.dart';
 export 'src/core/genui_manager.dart';
 export 'src/core/genui_surface.dart';
+export 'src/core/prompt_fragments.dart';
 export 'src/core/widgets/chat_primitives.dart';
 export 'src/facade/ui_agent.dart';
 export 'src/model/catalog.dart';
 export 'src/model/catalog_item.dart';
 export 'src/model/chat_message.dart';
+export 'src/model/tools.dart';
 export 'src/model/ui_models.dart';
 export 'src/primitives/logging.dart';
+export 'src/primitives/simple_items.dart';

packages/flutter_genui/lib/src/core/prompt_fragments.dart

@@ -0,0 +1,21 @@
+// Copyright 2025 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+/// A collection of prompt fragments for use with GenUI.
+class GenUiPromptFragments {
+  /// A basic chat prompt fragment.
+  static const String basicChat = '''
+
+# Outputting UI information
+
+Use the provided tools to respond to the user using rich UI elements.
+
+Important considerations:
+- When you are asking for information from the user, you should always include
+  at least one submit button of some kind or another submitting element so that
+  the user can indicate that they are done providing information.
+- After you have modified the UI, be sure to use the provideFinalOutput to give
+  control back to the user so they can respond.
+''';
+}

packages/flutter_genui/lib/src/facade/ui_agent.dart

@@ -8,29 +8,12 @@ import 'package:dart_schema_builder/dart_schema_builder.dart';
 import 'package:flutter/foundation.dart';
 
 import '../ai_client/ai_client.dart';
-import '../ai_client/firebase_ai_client.dart';
-import '../core/genui_configuration.dart';
 import '../core/genui_manager.dart';
-import '../model/catalog.dart';
 import '../model/chat_message.dart';
 import '../model/ui_models.dart';
 
 const _maxConversationLength = 1000;
 
-const _genuiSystemPromptFragment = '''
-
-# Outputting UI information
-
-Use the provided tools to respond to the user using rich UI elements.
-
-Important considerations:
-- When you are asking for information from the user, you should always include
-  at least one submit button of some kind or another submitting element so that
-  the user can indicate that they are done providing information.
-- After you have modified the UI, be sure to use the provideFinalOutput to give
-  control back to the user so they can respond.
-''';
-
 /// A high-level facade for the GenUI package.
 ///
 /// This class simplifies the process of creating a generative UI by managing
@@ -40,32 +23,17 @@ Important considerations:
 class UiAgent {
   /// Creates a new [UiAgent].
   ///
-  /// The [instruction] is a system prompt that guides the AI's behavior.
-  ///
-  /// The [catalog] defines the set of widgets available to the AI. If not
-  /// provided, a default catalog of core widgets is used.
-  ///
   /// Callbacks like [onSurfaceAdded] and [onSurfaceDeleted] can be provided to
   /// react to UI changes initiated by the AI.
-  UiAgent(
-    String instruction, {
-    required Catalog catalog,
+  UiAgent({
     this.onSurfaceAdded,
     this.onSurfaceDeleted,
     this.onTextResponse,
     this.onWarning,
-    GenUiConfiguration configuration = const GenUiConfiguration(),
-    AiClient? aiClient,
-  }) : _genUiManager = GenUiManager(
-         catalog: catalog,
-         configuration: configuration,
-       ) {
-    _aiClient =
-        aiClient ??
-        FirebaseAiClient(
-          systemInstruction: '$instruction\n\n$_genuiSystemPromptFragment',
-          tools: _genUiManager.getTools(),
-        );
+    required GenUiManager genUiManager,
+    required AiClient aiClient,
+  }) : _genUiManager = genUiManager,
+       _aiClient = aiClient {
     _aiClient.activeRequests.addListener(_handleActivityUpdates);
     _aiMessageSubscription = _genUiManager.surfaceUpdates.listen(
       _handleAiMessage,