|
| 1 | +--- |
| 2 | +title: Main components and concepts |
| 3 | +description: >- |
| 4 | + Familiarize yourself with the main components and concepts of the |
| 5 | + Flutter for GenUI SDK. |
| 6 | +--- |
| 7 | + |
| 8 | +:::experimental |
| 9 | +The `genui` package is in |
| 10 | +alpha and is likely to change. |
| 11 | +::: |
| 12 | + |
| 13 | +## Main components |
| 14 | + |
| 15 | +The package is built around the following main components: |
| 16 | + |
| 17 | +* `GenUiConversation`: The primary facade and entry point for the package. |
| 18 | + It includes the `GenUiManager` and `ContentGenerator` classes, |
| 19 | + manages the conversation history, |
| 20 | + and orchestrates the entire generative UI process. |
| 21 | + |
| 22 | +* `Catalog`: A collection of `CatalogItem` objects that defines |
| 23 | + the set of widgets that the AI is allowed to use. |
| 24 | + Each `CatalogItem` specifies a widget's name (for the AI |
| 25 | + to reference), a data schema for its properties, and a |
| 26 | + builder function to render the Flutter widget. |
| 27 | + |
| 28 | +* `DataModel`: A centralized, observable store for all dynamic UI state. |
| 29 | + Widgets are _bound_ to data in this model. When data changes, |
| 30 | + only the widgets that depend on that specific piece of data are rebuilt. |
| 31 | + |
| 32 | +* `ContentGenerator`: An interface for communicating with a generative AI model. |
| 33 | + This interface uses streams to send `A2uiMessage` commands, |
| 34 | + text responses, and errors back to the `GenUiConversation`. |
| 35 | + |
| 36 | +* `A2uiMessage`: A message sent from the AI |
| 37 | + (through the `ContentGenerator`) to the UI, |
| 38 | + instructing it to perform actions like `beginRendering`, |
| 39 | + `surfaceUpdate`, `dataModelUpdate`, or `deleteSurface`. |
| 40 | + |
| 41 | +## How it works |
| 42 | + |
| 43 | +The `GenUiConversation` manages the interaction cycle: |
| 44 | + |
| 45 | +1. **User input**: The user provides a prompt (for example, through a text field). |
| 46 | + The app calls `genUiConversation.sendRequest()`. |
| 47 | +2. **AI invocation**: The `GenUiConversation` adds the user's message to its |
| 48 | + internal conversation history and calls `contentGenerator.sendRequest()`. |
| 49 | +3. **AI response**: The `ContentGenerator` interacts with the AI model. |
| 50 | + The AI, guided by the widget schemas, sends back responses. |
| 51 | +4. **Stream handling**: The `ContentGenerator` emits A2uiMessages, |
| 52 | + text responses, or errors on its streams. |
| 53 | +5. **UI state update**: `GenUiConversation` listens to these streams. |
| 54 | + `A2uiMessages` are passed to `GenUiManager.handleMessage()`, |
| 55 | + which updates the UI state and `DataModel`. |
| 56 | +6. **UI rendering**: The `GenUiManager` broadcasts an update, |
| 57 | + and any `GenUiSurface` widgets listening for that surface ID will rebuild. |
| 58 | + Widgets are bound to the `DataModel`, so they update automatically |
| 59 | + when their data changes. |
| 60 | +7. **Callbacks**: Text responses and errors trigger the `onTextResponse` |
| 61 | + and `onError` callbacks on `GenUiConversation`. |
| 62 | +8. **User interaction**: The user interacts with the newly generated UI |
| 63 | + (for example, by typing in a text field). This interaction directly |
| 64 | + updates the `DataModel`. If the interaction is an action (like a button click), |
| 65 | + the `GenUiSurface` captures the event and forwards it to the |
| 66 | + `GenUiConversation`'s `GenUiManager`, which automatically creates |
| 67 | + a new `UserMessage` containing the current state of the data model |
| 68 | + and restarts the cycle. |
| 69 | + |
| 70 | +For more detailed information on the implementation of GenUI SDK for Flutter, |
| 71 | +check out the [design doc][]. |
| 72 | + |
| 73 | +The next section walks you through adding `genui` to your app. |
| 74 | + |
| 75 | +[design doc]: {{site.repo.organization}}/genui/blob/main/packages/genui/DESIGN.md |
| 76 | +[`genui`]: {{site.pub-pkg}}/genui |
0 commit comments