Initial implementation of prompt builder. (#777)

Author: polina-c

examples/simple_chat/lib/chat_session.dart

@@ -19,7 +19,16 @@ class ChatSession extends ChangeNotifier {
     _transport = AiClientTransport(aiClient: aiClient);
 
     // 2. Initialize Catalog & Controller
-    final Catalog catalog = BasicCatalogItems.asCatalog();
+    final Catalog catalog = BasicCatalogItems.asCatalog(
+      systemPromptFragments: [
+        '''
+When you need additional information from the user, try to use the component '${BasicCatalogItems.choicePicker.name}' to ask for it.
+''',
+        '''
+If there is no way to itemize all the options, either use the component '${BasicCatalogItems.textField.name}' or add option 'Other' to the '${BasicCatalogItems.choicePicker.name}'.
+''',
+      ],
+    );
     _surfaceController = SurfaceController(catalogs: [catalog]);
 
     // 3. Initialize Conversation
@@ -68,11 +77,18 @@ class ChatSession extends ChangeNotifier {
 
     final promptBuilder = PromptBuilder.chat(
       catalog: catalog,
-      instructions:
-          'You are a helpful assistant who chats with a user. '
-          'Your responses should contain acknowledgment of the user message.',
+      systemPromptFragments: [
+        'You are a helpful assistant who chats with a user.',
+        PromptFragments.acknowledgeUser(),
+        PromptFragments.requireAtLeastOneSubmitElement(
+          prefix: PromptBuilder.defaultImportancePrefix,
+        ),
+        PromptFragments.uiGenerationRestriction(
+          prefix: PromptBuilder.defaultImportancePrefix,
+        ),
+      ],
     );
-    _transport.addSystemMessage(promptBuilder.systemPrompt);
+    _transport.addSystemMessage(promptBuilder.systemPromptJoined());
   }
 
   void _addSurfaceMessage(String surfaceId) {

examples/travel_app/lib/src/ai_client/google_generative_ai_client.dart

@@ -53,7 +53,7 @@ class GoogleGenerativeAiClient implements AiClient {
   /// [apiKey] is the API key to use for authentication.
   GoogleGenerativeAiClient({
     required this.catalog,
-    this.systemInstruction,
+    this.systemInstruction = const [],
     this.outputToolName = 'provideFinalOutput',
     this.serviceFactory = defaultGenerativeServiceFactory,
     this.additionalTools = const [],
@@ -65,7 +65,7 @@ class GoogleGenerativeAiClient implements AiClient {
   final Catalog catalog;
 
   /// The system instruction to use for the AI model.
-  final String? systemInstruction;
+  final List<String> systemInstruction;
 
   /// The name of an internal pseudo-tool used to retrieve the final structured
   /// output from the AI.
@@ -472,35 +472,19 @@ class GoogleGenerativeAiClient implements AiClient {
       var toolUsageCycle = 0;
       const maxToolUsageCycles = 40; // Safety break for tool loops
 
-      // Build system instruction if provided
-      final parts = <google_ai.Part>[];
-      if (systemInstruction != null) {
-        parts.add(google_ai.Part(text: systemInstruction));
-      }
-      parts.add(
-        google_ai.Part(
-          text:
-              'Current Date: '
-              '${DateTime.now().toIso8601String().split('T').first}\n'
-              'You do not have the ability to execute code. If you need to '
-              'perform calculations, do them yourself.',
-        ),
+      final promptBuilder = PromptBuilder.custom(
+        catalog: catalog,
+        systemPromptFragments: systemInstruction,
+        allowedOperations: SurfaceOperations.createAndUpdate(dataModel: true),
+        clientDataModel: clientDataModel,
       );
-      parts.add(google_ai.Part(text: BasicCatalogEmbed.basicCatalogRules));
-      final String catalogJson = A2uiMessage.a2uiMessageSchema(
-        catalog,
-      ).toJson(indent: '  ');
-      if (clientDataModel != null) {
-        final String dataString = const JsonEncoder.withIndent(
-          '  ',
-        ).convert(clientDataModel);
-        parts.add(google_ai.Part(text: 'Client Data Model:\n$dataString'));
-      }
-      parts.add(google_ai.Part(text: 'A2UI Message Schema:\n$catalogJson'));
 
-      final systemInstructionContent = parts.isNotEmpty
-          ? [google_ai.Content(role: 'user', parts: parts)]
-          : <google_ai.Content>[];
+      final systemInstructionContent = [
+        google_ai.Content(
+          role: 'user',
+          parts: [google_ai.Part(text: promptBuilder.systemPromptJoined())],
+        ),
+      ];
 
       while (toolUsageCycle < maxToolUsageCycles) {
         if (cancellationSignal?.isCancelled ?? false) {

examples/travel_app/lib/src/travel_planner_page.dart

@@ -301,10 +301,10 @@ class _ChatInput extends StatelessWidget {
 
 String? _imagesJson;
 
-final prompt =
-    '''
-Today is ${DateTime.timestamp()}
-
+// TODO(polina-c): construct examples automatically after improving catalog API.
+final prompt = <String>[
+  PromptFragments.currentDate(),
+  '''
 # Instructions
 
 You are a helpful travel agent assistant that communicates by creating and
@@ -403,25 +403,9 @@ user helpful information in InformationCard and TravelCarousel. Always add new
 surfaces when doing this and do not update or delete existing ones. That way,
 the user can return to the main booking flow once they have done some research.
 
-## Controlling the UI
-
-You can control the UI by outputting valid A2UI JSON messages wrapped in markdown code blocks.
-Supported messages are: `createSurface` and `updateComponents`.
-
-To show a new UI:
-1. Output a `createSurface` message to define the surface ID and catalog.
-2. Output an `updateComponents` message to populate the surface with components.
-
-To update an existing UI (e.g. adding items to an itinerary):
-1. Output an `updateComponents` message with the existing `surfaceId` and the new component definitions.
-
-Properties:
-- `createSurface`: requires `surfaceId`, `catalogId` (use the catalog ID provided in system instructions), and `sendDataModel: true`.
-- `updateComponents`: requires `surfaceId` and a list of `components`. One component MUST have `id: "root"`.
+## Updating UI
 
-IMPORTANT:
-- Do not use tools or function calls for UI generation. Use JSON text blocks.
-- Ensure all JSON is valid and fenced with ```json ... ```.
+Update surfaces to modify existing UI, for example to add items to an itinerary.
 
 ## Images
 
@@ -515,4 +499,8 @@ Here is an example of creating a trip planner UI.
 ```
 
 When updating or showing UIs, **ALWAYS** use the JSON messages as described above. Prefer to collect and show information by creating a UI for it.
-''';
+''',
+  PromptFragments.uiGenerationRestriction(
+    prefix: PromptBuilder.defaultImportancePrefix,
+  ),
+];

packages/genui/lib/genui.dart

@@ -23,7 +23,6 @@ export 'src/interfaces/transport.dart';
 export 'src/model/a2ui_client_capabilities.dart';
 export 'src/model/a2ui_message.dart';
 export 'src/model/a2ui_schemas.dart';
-export 'src/model/basic_catalog_embed.dart';
 export 'src/model/catalog.dart';
 export 'src/model/catalog_item.dart';
 export 'src/model/chat_message.dart';

packages/genui/lib/src/catalog/basic_catalog.dart

@@ -103,8 +103,10 @@ abstract final class BasicCatalogItems {
   /// This typically includes controls like play/pause, seek, and volume.
   static final CatalogItem video = video_item.video;
 
+  static final String basicCatalogRules = _basicCatalogRules;
+
   /// Creates a catalog containing all core catalog items.
-  static Catalog asCatalog() {
+  static Catalog asCatalog({List<String> systemPromptFragments = const []}) {
     return Catalog(
       [
         audioPlayer,
@@ -128,6 +130,58 @@ abstract final class BasicCatalogItems {
       ],
       functions: BasicFunctions.all,
       catalogId: basicCatalogId,
+      systemPromptFragments: [basicCatalogRules, ...systemPromptFragments],
     );
   }
 }
+
+/// The text content of basic_catalog_rules.txt.
+const String _basicCatalogRules = r'''
+**REQUIRED PROPERTIES:** You MUST include ALL required properties for every component, even if they are inside a template or will be bound to data.
+- For 'Text', you MUST provide 'text'. If dynamic, use { "path": "..." }.
+- For 'Image', you MUST provide 'url'. If dynamic, use { "path": "..." }.
+- For 'Button', you MUST provide 'action'.
+- For 'TextField', 'CheckBox', etc., you MUST provide 'label'.
+
+**EXAMPLES:**
+
+1. Create a surface:
+```json
+{
+  "version": "v0.9",
+  "createSurface": {
+    "surfaceId": "main",
+    "catalogId": "https://a2ui.org/specification/v0_9/standard_catalog.json",
+    "sendDataModel": true
+  }
+}
+```
+
+2. Update components:
+```json
+{
+  "version": "v0.9",
+  "updateComponents": {
+    "surfaceId": "main",
+    "components": [
+      {
+        // The root component MUST have id "root"
+        "id": "root",
+        "component": "Column",
+        "justify": "start",
+        "children": [
+          "headerText",
+          "content"
+        ]
+      }
+    ]
+  }
+}
+```
+
+**IMPORTANT:**
+- One of the components sent in one of the `updateComponents` MUST have id "root", or nothing will be displayed.
+- Do NOT nest `components` inside `createSurface`. Use `updateComponents` to add components to a surface.
+- `createSurface` ONLY sets up the surface (ID and catalog). It does NOT take content.
+- To show a UI, you typically send a `createSurface` message (if the surface doesn't exist), followed by an `updateComponents` message.
+''';