Remove implementation detail from catalog core widget schema descriptions

Author: victoreronmosele

.gemini/GEMINI.md

@@ -12,8 +12,10 @@ The project is structured as a monorepo containing several Dart and Flutter pack
 
 | Package                              | Description                                                             |
 | ------------------------------------ | ----------------------------------------------------------------------- |
-| `packages/genui`             | The core framework for employing Generative UI.                         |
-| `packages/genui_firebase_ai` | Firebase AI integration for `genui`.                            |
+| `packages/genui`                     | The core framework for employing Generative UI.                         |
+| `packages/genui_a2ui`                | Integration with the A2UI Streaming UI Protocol.                        |
+| `packages/genui_firebase_ai`         | Firebase AI integration for `genui`.                                    |
+| `packages/genui_google_generative_ai`| Integration with Google Cloud Generative Language API.                  |
 | `packages/json_schema_builder`       | A Dart JSON Schema package with validation, used by the core framework. |
 
 ### Example Applications
@@ -25,15 +27,16 @@ The `examples` directory contains sample applications demonstrating the usage of
 | `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.                                                                                          |
+| `verdure`         | A full-stack example (Flutter client + Python server) of a landscape design agent using the A2A protocol.                                                                                                                                                         |
+| `custom_backend`  | Demonstrates how a custom backend can interact with `genui`.                                                                                                                                                                                                      |
 
 The `simple_chat` and `travel_app` examples are good starting points for understanding the library's capabilities.
 
 ## Implementation Details
 
 For a deeper understanding of the project's architecture and data flow, refer to the following documents:
 
-- **`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.
+- **`packages/genui/DESIGN.md`**: Provides a comprehensive overview of the core `genui` package's architecture, purpose, and implementation.
 
 ## Building and Running
 
@@ -47,7 +50,7 @@ The project uses standard `flutter` and `dart` commands. A comprehensive script
   ./tool/run_all_tests_and_fixes.sh
   ```
 
-  This is a script used by CI for ensuring code quality. It runs `dart fix`, `dart format`, `flutter test`, and `flutter analyze` for all packages and examples in the repository.
+  This script wraps the `test_and_fix` Dart tool (`tool/test_and_fix`) to run `dart fix`, `dart format`, `fix_copyright` (in `tool/fix_copyright`), `flutter test`, and `flutter analyze` for all packages and examples in the repository. It is used by developers before comitting code. It takes a while to run, and is not idempotent: it will reformat code and add copyright notices if necessary.
 
 ## Development Conventions
 
@@ -71,14 +74,18 @@ The project uses standard `flutter` and `dart` commands. A comprehensive script
 ### Firebase Integration
 
 - 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`.
+- 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/README.md`](packages/genui/README.md#configure-firebase-ai-logic).
 
-## 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
 

.gemini/README.md

@@ -10,6 +10,7 @@ The files in this directory are used to customize the behavior of these tools fo
 - **`GEMINI.md`**: Provides project-specific context, instructions, and guidelines that are included in the context when using Gemini CLI and Code Assist. This helps the AI understand the project's conventions and requirements.
 - **`config.yaml`**: Configuration for the Gemini for GitHub tools, such as settings for code review.
 - **`styleguide.md`**: Contains the project's style guide, which is used by the Gemini for Github tools to ensure that generated reviews adhere to the project's conventions.
+- **`commands/`**: A directory containing custom command definitions (e.g., `fix_code.toml`) for the Gemini CLI.
 
 ## Documentation
 

.github/workflows/flutter_packages.yaml

@@ -121,8 +121,6 @@ jobs:
       - name: Update submodules
         working-directory: ${{ matrix.package.path }}
         run: git submodule update --init --recursive
-      - name: Stub firebase_options.dart
-        run: sh tool/stub_firebase_options.sh
       - name: Install dependencies
         working-directory: ${{ matrix.package.path }}
         run: dart pub get

.gitignore

@@ -1,7 +1,38 @@
-# These files are regularly auto-updated, but they should not be ignored:
-# **/project.pbxproj
-# **/settings.gradle.kts
-# **/build.gradle.kts
+# Diagrams, produced by https://pub.dev/packages/layerlens.
+DEPS.md
+
+# Firebase
+google-services.json
+**/lib/firebase_options.dart
+firebase.json
+GoogleService-Info.plist
+.firebase
+.firebaserc
+
+# This package's specific logs.
+*.log.*
+*.log
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv
+venv/
+ENV/
+.env
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# ==============================================================================
+#
+# STANDARD FLUTTER GITIGNORE
+#
+# ==============================================================================
 
 # Miscellaneous
 *.class
@@ -15,35 +46,27 @@
 .svn/
 .swiftpm/
 migrate_working_dir/
-firepit-log.txt
-pglite-debug.log
-
-# Diagrams, produced by https://pub.dev/packages/layerlens.
-DEPS.md
 
 # IntelliJ related
 *.iml
 *.ipr
 *.iws
 .idea/
 
+# The .vscode folder contains launch configuration and tasks you configure in
+# VS Code which you may wish to be included in version control, so this line
+# is commented out by default.
+#.vscode/
+
 # 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
+/build/
+/coverage/
 
 # Symbolication related
 app.*.symbols
@@ -52,33 +75,6 @@ app.*.symbols
 app.*.map.json
 
 # Android Studio will place build artifacts here
-**/android/app/debug
-**/android/app/profile
-**/android/app/release
-
-# Firebase
-google-services.json
-**/lib/firebase_options.dart
-firebase.json
-GoogleService-Info.plist
-.firebase
-.firebaserc
-
-# This package's specific logs.
-*.log.*
-*.log
-
-# Python
-__pycache__/
-*.py[cod]
-*$py.class
-.venv
-venv/
-ENV/
-.env
-build/
-dist/
-*.egg-info/
-.pytest_cache/
-.coverage
-htmlcov/
+/android/app/debug
+/android/app/profile
+/android/app/release

CONTRIBUTING.md

@@ -8,7 +8,7 @@ Please follow [Flutter contributor guidelines][flutter_guidelines].
 
 To run examples:
 
-1. Configure Firebase as described in [USAGE.md][usage_md].
+1. Configure Firebase as described in [README.md][readme_md].
 2. Run `flutter run`.
 
 NOTE: For Google-internal projects see go/flutter-genui-internal.
@@ -104,7 +104,7 @@ releasing a new version.
 [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/genui/USAGE.md#configure-firebase
+[readme_md]: packages/genui/README.md#configure-firebase-ai-logic
 [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

@@ -3,6 +3,10 @@
 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).
@@ -37,58 +41,6 @@ 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/)
@@ -120,31 +72,44 @@ 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                                                                   |
-| ---------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| [genui](packages/genui/)                         | A framework to employ Generative UI.                       |
-| [genui_firebase_ai](packages/genui_firebase_ai/) | Firebase AI integration for genui.                 |
-| [json_schema_builder](packages/json_schema_builder/)             | 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
+## Getting Started
 
-See [packages/genui/USAGE.md](packages/genui/USAGE.md).
+See the [genui getting started guide](packages/genui/README.md#getting-started-with-genui).
 
 ## Constraints
 
 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
 
 See [CONTRIBUTING.md](CONTRIBUTING.md)

docs/assets/genui_intro_video_still.png

@@ -21,6 +21,6 @@
   <key>CFBundleVersion</key>
   <string>1.0</string>
   <key>MinimumOSVersion</key>
-  <string>13.0</string>
+  <string>15.0</string>
 </dict>
 </plist>

examples/catalog_gallery/ios/Flutter/AppFrameworkInfo.plist

@@ -346,7 +346,7 @@
 				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
-				IPHONEOS_DEPLOYMENT_TARGET = 13.0;
+				IPHONEOS_DEPLOYMENT_TARGET = 15.0;
 				MTL_ENABLE_DEBUG_INFO = NO;
 				SDKROOT = iphoneos;
 				SUPPORTED_PLATFORMS = iphoneos;
@@ -472,7 +472,7 @@
 				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
-				IPHONEOS_DEPLOYMENT_TARGET = 13.0;
+				IPHONEOS_DEPLOYMENT_TARGET = 15.0;
 				MTL_ENABLE_DEBUG_INFO = YES;
 				ONLY_ACTIVE_ARCH = YES;
 				SDKROOT = iphoneos;
@@ -523,7 +523,7 @@
 				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
-				IPHONEOS_DEPLOYMENT_TARGET = 13.0;
+				IPHONEOS_DEPLOYMENT_TARGET = 15.0;
 				MTL_ENABLE_DEBUG_INFO = NO;
 				SDKROOT = iphoneos;
 				SUPPORTED_PLATFORMS = iphoneos;