Merge branch 'main' into a2a_dart

Author: gspencergoog

.gemini/GEMINI.md

@@ -4,25 +4,25 @@ This document provides context for the Gemini Code Assistant to understand the `
 
 ## Project Overview
 
-This is a monorepo for a Generative UI SDK (`flutter_genui`). The SDK allows developers to add interactive, dynamic, and graphical UI to their applications, generated by a Large Language Model (LLM). Instead of rendering static text responses from an LLM, this SDK allows the LLM to compose UIs from a developer-provided widget catalog.
+This is a monorepo for a Generative UI SDK (`genui`). The SDK allows developers to add interactive, dynamic, and graphical UI to their applications, generated by a Large Language Model (LLM). Instead of rendering static text responses from an LLM, this SDK allows the LLM to compose UIs from a developer-provided widget catalog.
 
 The project is structured as a monorepo containing several Dart and Flutter packages, along with example applications.
 
 ### Key Packages
 
 | Package                              | Description                                                             |
 | ------------------------------------ | ----------------------------------------------------------------------- |
-| `packages/flutter_genui`             | The core framework for employing Generative UI.                         |
-| `packages/flutter_genui_firebase_ai` | Firebase AI integration for `flutter_genui`.                            |
+| `packages/genui`             | The core framework for employing Generative UI.                         |
+| `packages/genui_firebase_ai` | Firebase AI integration for `genui`.                            |
 | `packages/json_schema_builder`       | A Dart JSON Schema package with validation, used by the core framework. |
 
 ### Example Applications
 
-The `examples` directory contains sample applications demonstrating the usage of the `flutter_genui` SDK.
+The `examples` directory contains sample applications demonstrating the usage of the `genui` SDK.
 
 | Example           | Description                                                                                                                                                                                                                                                       |
 | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `simple_chat`     | A minimal example of a conversational chat application. It demonstrates the fundamental concepts of `flutter_genui`, such as initializing the `GenUiConversation`, sending user messages, and rendering the AI-generated UI surfaces using the default core widget catalog. |
+| `simple_chat`     | A minimal example of a conversational chat application. It demonstrates the fundamental concepts of `genui`, such as initializing the `GenUiConversation`, sending user messages, and rendering the AI-generated UI surfaces using the default core widget catalog. |
 | `travel_app`      | A more advanced example of a travel planning assistant. It showcases dynamic UI generation, the use of a custom, domain-specific widget catalog, and how user interactions with the UI can be fed back to the AI to refine the conversation.                      |
 | `catalog_gallery` | A simple application that displays the widgets available in the catalog. It's a useful tool for developers to visualize the components that the AI can use to build UIs.                                                                                          |
 
@@ -32,8 +32,8 @@ The `simple_chat` and `travel_app` examples are good starting points for underst
 
 For a deeper understanding of the project's architecture and data flow, refer to the following documents:
 
-- **`packages/flutter_genui/IMPLEMENTATION.md`**: Provides a comprehensive overview of the core `flutter_genui` package's architecture, purpose, and implementation.
-- **`examples/travel_app/IMPLEMENTATION.md`**: Describes the architecture and implementation of the `travel_app` example, showcasing how the `flutter_genui` package is used to build a dynamic, conversational UI.
+- **`packages/genui/IMPLEMENTATION.md`**: Provides a comprehensive overview of the core `genui` package's architecture, purpose, and implementation.
+- **`examples/travel_app/IMPLEMENTATION.md`**: Describes the architecture and implementation of the `travel_app` example, showcasing how the `genui` package is used to build a dynamic, conversational UI.
 
 ## Building and Running
 
@@ -53,9 +53,9 @@ The project uses standard `flutter` and `dart` commands. A comprehensive script
 
 ### Code Style and Formatting
 
-- The project follows the `dart_flutter_team_lints` linting rules, which is the combination of this [analysis_options.yaml](https://raw.githubusercontent.com/dart-lang/ecosystem/refs/heads/main/pkgs/dart_flutter_team_lints/lib/analysis_options.yaml) file and the [recommended](https://raw.githubusercontent.com/dart-lang/core/refs/heads/main/pkgs/lints/lib/recommended.yaml) and [core](https://raw.githubusercontent.com/dart-lang/core/refs/heads/main/pkgs/lints/lib/core.yaml) lints.
+- The project follows the linting rules in the `analysis_options.yaml` file at the top of the repo.
 - Code formatting is enforced using the `dart_format` tool.
-- The `tool/run_all_tests_and_fixes.sh` script should be run before committing to ensure all files are correctly formatted and analyzed.
+- The `tool/run_all_tests_and_fixes.sh` script should be run before committing to ensure all files are correctly formatted and analyzed.  Don't run it every time you want to test something, just before you commit, since it does more than just test things, and takes a while.
 
 ### Testing
 
@@ -70,15 +70,19 @@ The project uses standard `flutter` and `dart` commands. A comprehensive script
 
 ### Firebase Integration
 
-- The examples and the `flutter_genui_firebase_ai` package use Firebase.
-- A script at `tool/stub_firebase_options.sh` is used in CI to create a stub `firebase_options.dart` file. For local development, developers need to configure their own Firebase project by following the instructions in `packages/flutter_genui/USAGE.md`.
+- The examples and the `genui_firebase_ai` package use Firebase.
+- A script at `tool/stub_firebase_options.sh` is used in CI to create a stub `firebase_options.dart` file. For local development, developers need to configure their own Firebase project by following the instructions in `packages/genui/USAGE.md`.
 
-## Folder `spikes`
+## Updating the Guides (`packages/genui/.guides`)
 
-The folder `spikes` contains experiments and proof of concepts,
-that does not have to be of good quality.
+When asked to update the developer guides located in `packages/genui/.guides`, it is critical to ensure the documentation accurately reflects the current state of the codebase. Before making any changes to the guides, you must read *all* the Dart code in the following packages:
 
-Skip this folder when reviewing code.
+-   `packages/genui`
+-   `packages/genui_firebase_ai`
+-   `packages/genui_google_generative_ai`
+-   `packages/genui_a2ui`
+
+This ensures that any code examples, API references, and architectural explanations in the guides are up-to-date and consistent with the actual implementation.
 
 ## Draft pull requests
 

.gitignore

@@ -15,8 +15,8 @@
 .svn/
 .swiftpm/
 migrate_working_dir/
-**/firepit-log.txt
-**/pglite-debug.log
+firepit-log.txt
+pglite-debug.log
 
 # Diagrams, produced by https://pub.dev/packages/layerlens.
 DEPS.md
@@ -30,20 +30,20 @@ DEPS.md
 # Flutter/Dart/Pub related
 **/doc/api/
 **/ios/Flutter/.last_build_id
-**/.dart_tool/
-**/.flutter-plugins-dependencies
-**/.pub-cache/
-**/.pub/
-**/build/
-**/coverage/
-**/pubspec.lock
-**/generated_plugins.cmake
-**/GeneratedPluginRegistrant.*
-**/generated_plugin_registrant.*
-**/Podfile
-**/Podfile.lock
-**/Runner-Bridging-Header.h
-**/contents.xcworkspacedata
+.dart_tool/
+.flutter-plugins-dependencies
+.pub-cache/
+.pub/
+build/
+coverage/
+pubspec.lock
+generated_plugins.cmake
+GeneratedPluginRegistrant.*
+generated_plugin_registrant.*
+Podfile
+Podfile.lock
+Runner-Bridging-Header.h
+contents.xcworkspacedata
 
 # Symbolication related
 app.*.symbols
@@ -57,13 +57,28 @@ app.*.map.json
 **/android/app/release
 
 # Firebase
-**/google-services.json
+google-services.json
 **/lib/firebase_options.dart
-**/firebase.json
-**/GoogleService-Info.plist
-**/.firebase
-**/.firebaserc
+firebase.json
+GoogleService-Info.plist
+.firebase
+.firebaserc
 
 # This package's specific logs.
-**/*.log.*
-**/*.log
+*.log.*
+*.log
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv
+venv/
+ENV/
+.env
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.coverage
+htmlcov/

CONTRIBUTING.md

@@ -78,9 +78,33 @@ Triage issues ready for second-line review:
 At the end of a triage session, the untriaged issue list should be as close to
 empty as possible.
 
+## Versioning
+
+We use [Semver] for package versioning, although before 1.0.0, we will be
+incrementing only the minor number for breaking changes and the patch number for
+non-breaking changes. After 1.0.0, we will be using standard Semver, bumping the
+major number for breaking changes.
+
+We release `genui`, `genui_firebase_ai`,
+`genui_google_generative_ui`, and `genui_a2ui` in lock step,
+with the same version number, so when one is released, they are all released.
+
+`json_schema_builder` is released independently on its own schedule, with its
+own version number.
+
+"Releasing" consititutes manually publishing them all to [pub.dev] after the
+pull request containing the version bump has passed CI. The packages must be
+published by someone with permission to publish under the labs.flutter.org
+owner.
+
+Use the [release tool](tool/release/README.md) to help automate the process of
+releasing a new version.
+
+[pub.dev]: https://pub.dev
+[Semver]: https://semver.org/
 [for-front-line]: https://github.com/flutter/genui/issues?q=is%3Aissue%20state%3Aopen%20-label%3AP0%20%20-label%3AP1%20-label%3AP2%20%20-label%3AP3%20-label%3Afront-line-handled
 [flutter_guidelines]: https://github.com/flutter/flutter/blob/master/CONTRIBUTING.md
-[usage_md]: packages/flutter_genui/USAGE.md#configure-firebase
+[usage_md]: packages/genui/USAGE.md#configure-firebase
 [assigned_p2_p3_issues]: https://github.com/flutter/genui/issues?q=is%3Aopen%20is%3Aissue%20label%3AP2%2CP3%20assignee%3A*
 [p0_p1_issues_without_milestone]: https://github.com/flutter/genui/issues?q=is%3Aopen%20is%3Aissue%20label%3AP1%2CP0%20no%3Amilestone
 [projectless_open_issues]: https://github.com/flutter/genui/issues?q=is%3Aopen%20is%3Aissue%20no%3Aproject

README.md

@@ -1,14 +1,18 @@
-# Generative UI SDK for Flutter (flutter_genui)
+# Generative UI SDK for Flutter (genui)
 
 A Flutter library to enable developers to easily add interactive
 generative UI to their applications.
 
+See the [Getting started with GenUI](https://www.youtube.com/watch?v=nWr6eZKM6no) video for an overview of the package.
+
+[<img src="docs/assets/genui_intro_video_still.png" alt="GenUI Intro video still" height="500">](https://www.youtube.com/watch?v=nWr6eZKM6no)
+
 ## Status: Highly Experimental
 
 This is a highly experimental package, which means the API will change (sometimes drastically).
 [Feedback is very welcome](https://github.com/flutter/genui/issues/new/choose).
 
-## TL;DR
+## Summary
 
 Our goal for the GenUI SDK for Flutter is to help you replace static "walls of text" from your LLM with
 dynamic, interactive, graphical UI.
@@ -37,63 +41,11 @@ chatbots and next-generation agent-based user experiences.
 - Create dynamically composed UIs: an agent can generate a complete form with sliders, date pickers,
   and text fields on the fly based on a user's request to "book a flight."
 
-## Example
-
-### Using the GenUI SDK with Firebase AI Logic
-
-```dart
-// Adding your widgets into the catalog.
-// Start with the built-in catalog and add your own custom widgets.
-final catalog = CoreCatalogItems.asCatalog().copyWith([
-  myCustomNewWidget,
-]);
-
-/// Initializing the library.
-final genUiManager = GenUiManager(catalog: catalog);
-final contentGenerator = FirebaseAiContentGenerator(
-  catalog: catalog,
-  systemInstruction: '''
-  You are a bicycle maintenance assistant who is an expert in diagnosing issues and
-  giving step-by-step instructions.
-  ''',
-);
-late final _genUiConversation = GenUiConversation(
-  genUiManager: genUiManager,
-  contentGenerator: contentGenerator,
-  onSurfaceAdded: _onSurfaceAdded,
-  onSurfaceDeleted: (_) {},
-  onTextResponse: (_) {},
-  // ignore: avoid_print
-  onWarning: (value) => print('Warning from GenUiConversation: $value'),
-);
-
-// Put the surface, added by AI, to the list of messages that should be rendered,
-// trigger re-render, and scroll to bottom.
-void _onSurfaceAdded(SurfaceAdded surface) {
-  if (!mounted) return;
-  setState(() {
-    _messages.add(MessageController(surfaceId: surface.surfaceId));
-  });
-  _scrollToBottom();
-}
-
-// Render that UI.
-Widget build(BuildContext context) {
-   if (type == MessageType.genUi) {
-     return GenUiSurface(
-       host: _genUiConversation.genUiManager.host,
-       surfaceId: _surfaceId,
-       onEvent: _handleEvent,
-     );
-   }
-}
-```
-
 ## Look & Feel
 
 ### Interactive [Travel App Example](examples/travel_app/)
 
-<img src="misc/travel_app_genui_example.gif" alt="GenUI Travel App Demo" height="500">
+<img src="docs/assets/travel_app_genui_example.gif" alt="GenUI Travel App Demo" height="500">
 
 _The GIF above shows how GenUI enables dynamic, interactive UI generation,_
 _instead of text descriptions or code from a traditional AI coding agent._
@@ -103,7 +55,7 @@ _instead of text descriptions or code from a traditional AI coding agent._
 This UI is not generated in the form of code; rather, it's generated at runtime
 based on a widget catalog from the developers' project.
 
-<img src="misc/travel_app_genui_example.png" alt="GenUI Features Breakdown" height="600">
+<img src="docs/assets/travel_app_genui_example.png" alt="GenUI Features Breakdown" height="600">
 
 ## Implementation goals
 
@@ -120,30 +72,43 @@ based on a widget catalog from the developers' project.
 - **Basic Layout:** LLM-driven basic layout generation.
 - **Any Model:** Integrate with any LLM that can generate structured JSON output.
 
-## Some things we're thinking about
+## Connecting to an AI Agent
 
-- **Genkit Integration:** Integration with Genkit.
-- **Expanded LLM Framework Support:** Official support for additional LLM frameworks.
-- **Streaming UI:** Support for progressively rendering UI components as they stream from the LLM.
-- **Full-Screen Composition:** Enable LLM-driven composition and navigation of entire app screens.
-- **A2A Agent Support:** Support for A2A agent interactions.
-- **Dart Bytecode:** Future support for Dart Bytecode for even greater dynamism and flexibility.
+The `genui` framework uses a `ContentGenerator` to communicate with a generative AI model,
+allowing `genui` to be backend agnostic. You can choose the implementation that best fits
+your needs, whether it's `FirebaseAiContentGenerator` for production apps,
+`GoogleGenerativeAiContentGenerator` for rapid prototyping, or `A2uiContentGenerator` for
+custom agent servers.
+
+See the package table below for more details on each.
 
 ## Packages
 
-| 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.                 |
-| [json_schema_builder](packages/json_schema_builder/)             | (work in progress) A fully featured Dart JSON Schema package with validation. |
+| Package                                                            | Description                                                                                                                                                                  |
+| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [genui](packages/genui/)                                           | The core framework to employ Generative UI.                                                                                                                                  |
+| [genui_firebase_ai](packages/genui_firebase_ai/)                   | Provides **`FirebaseAiContentGenerator`** to connect to Gemini via Firebase AI Logic. This is the recommended approach for production apps based on client-side agents.      |
+| [genui_google_generative_ai](packages/genui_google_generative_ai/) | Provides **`GoogleGenerativeAiContentGenerator`** for connecting to the Google Generative AI API with only an API key. Ideal for getting started quickly.                    |
+| [genui_a2ui](packages/genui_a2ui/)                                 | Provides **`A2uiContentGenerator`** for connecting to any server that implements the [A2UI protocol](https://a2ui.org). Use this for integrating with custom agent backends. |
+| [json_schema_builder](packages/json_schema_builder/)               | A fully featured Dart JSON Schema package with validation, used by the core framework to define widget data structures.                                                      |
 
 ## Usage
 
-See [packages/flutter_genui/USAGE.md](packages/flutter_genui/USAGE.md).
+See [packages/genui/USAGE.md](packages/genui/USAGE.md).
 
 ## Constraints
 
-This repo requires Flutter >=3.35.7.
+This repo requires Flutter version >=3.35.7.
+
+## Some things we're thinking about
+
+- **Genkit Integration:** Integration with Genkit.
+- **ADK Plugin:** turnkey integration with ADK.
+- **Expanded LLM Framework Support:** Official support for additional LLM frameworks.
+- **Streaming UI:** Support for progressively rendering UI components as they stream from the LLM.
+- **Full-Screen Composition:** Enable LLM-driven composition and navigation of entire app screens.
+- **A2A Agent Support:** Support for A2A agent interactions.
+- **Dart Bytecode:** Future support for Dart Bytecode for even greater dynamism and flexibility.
 
 ## Contribute
 

analysis_options.yaml

@@ -0,0 +1,44 @@
+# Copyright 2025 The Flutter Authors.
+# Use of this source code is governed by a BSD-style license that can be
+# found in the LICENSE file.
+
+include: package:lints/recommended.yaml
+
+analyzer:
+  language:
+    strict-casts: true
+    strict-inference: true
+
+linter:
+  rules:
+    # consistency
+    - combinators_ordering
+    - directives_ordering
+    - lines_longer_than_80_chars
+    - prefer_asserts_in_initializer_lists
+    - prefer_const_constructors
+    - prefer_relative_imports
+    - prefer_single_quotes
+    - sort_pub_dependencies
+    - unnecessary_lambdas
+    - unnecessary_library_directive
+    - unnecessary_parenthesis
+    - unnecessary_statements
+    - use_is_even_rather_than_modulo
+
+    # correctness
+    - always_declare_return_types
+    - avoid_catching_errors
+    - avoid_dynamic_calls
+    - comment_references
+    - conditional_uri_does_not_exist
+    - only_throw_errors
+    - test_types_in_equals
+    - throw_in_finally
+    - type_annotate_public_apis
+    - unawaited_futures
+    - unreachable_from_main
+
+    - omit_obvious_local_variable_types
+    - specify_nonobvious_local_variable_types
+    - specify_nonobvious_property_types