feat(NGUI-446): added list of all available fields for table and set-of-cards into agent output (#232)

Author: velias

docs/guide/architecture.md

@@ -1,13 +1,24 @@
 # Architecture
 
-This guide shows how to use *NextGen UI Agent* in your application.
+This guide shows how to use *NextGen UI Agent* in your AI application, how it plays with other building blocks of it.
+
+## What is *UI Agent*
 
 In short, *UI Agent* takes `User Prompt` and [`Structured Data`](input_data/index.md) relevant to this prompt as an input, 
 and generates UI component to visualize that piece of data to the user. We call it [`Data UI Block`](data_ui_blocks/index.md).
-[AI (LLM) is used](llm.md) in this step to understand the `User Prompt` and [input data structure](./input_data/structure.md), 
-and select the best dynamic UI component and displayed data values.
 
-Stricter configuration can be used when tighter control of UI components applied to the input data is necessary, for 
+UI Agent uses [AI (LLM)](llm.md) in this step to understand the `User Prompt` and [input data structure](./input_data/structure.md),
+and select the best dynamic UI component and displayed data values. 
+As UI component generation is an AI narrow task, small LLMs (3B, 8B, Mini/Flash/Flash-Lite series) are typically able to provide 
+good results for this task, which saves LLM price. They also provide better processing time, which is important for good user experience.
+We provide [LLM evaluation tool](https://github.com/RedHat-UX/next-gen-ui-agent/tree/main/tests/ai_eval_components) as part of this project, 
+results from some [eval runs are available](https://github.com/RedHat-UX/next-gen-ui-agent/tree/main/tests/ai_eval_components/results).
+We expect to provide small LLMs finetuned for UI generation task in the future.
+
+*UI Agent* can process structured Input Data in different formats. Extensible [input data transformation framework](./input_data/transformation.md) 
+is used, with OOTB transformers provided for the most common formats like `JSON`, `YAML`, `CSV` and `fixed width columns table`.
+
+Stricter configuration can be defined when tighter control of the UI components applied to the input data is necessary, for
 details see [Component Selection and Configuration docs](./data_ui_blocks/index.md#selection-and-configuration-process).
 
 In the future, this agent will also maintain `UI state` and view layouts to keep UI and flows consistent, handle personalized 
@@ -16,11 +27,12 @@ values formating, and many other features. Stay tuned ;-)
 Example of the generated `Data UI Block`:
 ![Example of the Data UI Block](../img/data_ui_block_card.png "Example of the Data UI Block")
 
-*UI Agent* also suports [*Hand Build Components*](data_ui_blocks/hand_build_components.md) for pieces of data where UI component exists already, or where 
-it is needed to provide special visualization or use features on top of AI generated UI components.
+*UI Agent* also suports [*Hand Build Components*](data_ui_blocks/hand_build_components.md) for pieces of data where UI component exists 
+already, or where it is needed to provide special visualization or use features on top of AI generated UI components.
 
+## How to use *UI Agent*
 
-Your application, called *Controlling assistant*, has to provide other building blocks and their orchestration to implement complete solution.
+Your AI application, called *Controlling assistant*, has to provide other building blocks and their orchestration to implement complete solution.
 
 Example of the *Controlling assistant* architecture:
 ![Example of the Controlling assistant architecture](../img/architecture_assistant_flow.jpg "Example of the Controlling assistant architecture")
@@ -29,7 +41,7 @@ Example of the *Controlling assistant* architecture:
 It can do it directly, for example using `LLM Tools Calling`/`MCP`, or it can call *Data providing agent* in case 
 of Multi-Agent architecture. It can even generate that data itself in process of Reasoning or user's intent detection and processing.
 *Controlling assistant* can load more pieces of data for one conversation turn, and send them all to the *UI Agent* to generate 
-more `AI UI Blocks` to be shown to the user in the assistant's GUI.
+more `Data UI Blocks` to be shown to the user in the assistant's GUI.
 
 *Controlling assistant* can also generate *Natural language response* based on this data and deliver it to the user through GUI or Voice user interface.
 To follow vision of the *NextGen UI*, this natural language response should not repeat visualized data, but rather provide 
@@ -43,6 +55,20 @@ Example mockup of the *Controlling assistant* GUI:
 They can be rendered using pluggable GUI component system renderers, and integrated into the GUI of the *Controlling assistant*. 
 We provide renderers for several UI component systems, either Server-Side or Client-Side, see [Binding into UI](renderer/index.md).
 
-*UI Agent* can be integrated into *Controlling Assistant* developed using multiple AI frameworks or AI protocols, see [Binding into AI application](ai_apps_binding/index.md).
+Output of the *UI Agent* does not contain the `Data UI Block` rendering only, but also [structured UI component configuration](../spec/output.md). 
+It can be used to implement advanced UI features, like live data updates from backend, manual selection of visualized table columns etc.
+
+## How to integrate *UI Agent*
+
+*UI Agent* can be integrated into *Controlling Assistant* developed using multiple AI frameworks or AI protocols,
+see [Binding into AI application](ai_apps_binding/index.md). You can also refer ["Choose your framework"](../installation.md) guide.
+
+The first approach how to integrate *UI Agent* into the *Controlling assistant* is to use assistant's LLM to choose and execute the 
+UI Agent. This approach makes sense if you want your assistant to act like `Orchestrator` - to decide about the UI component generation.
+For example to select which backend data loaded during the processing needs to be visualized in UI, or whether UI has to be generated at all.
+This approach cost you more in terms of the main LLM processing price (tokens) and time, but gives you more flexibility.
 
-You can also refer ["Choose your framework"](../installation.md).
+Alternative approach is to invoke *UI Agent* directly as part of your assistant logic, at the specific moment of the processing flow, 
+after gathering structured backend data for the response.
+This approach is a bit more reliable, helps to reduce main LLM processing price (tokens) and time (you can even generate UI in 
+parallel with *Natural language response* generation), but is a bit less flexible.

docs/guide/configuration.md

@@ -10,6 +10,7 @@ The Next Gen UI Agent can be configured in two ways: `programmatically` using Py
 
 [UI Component system](renderer/index.md) for rendering (default: `"json"`)
 
+
 ### `data_transformer` [`str`, optional] 
 
 Optional name of the [Input Data Transformer](input_data/transformation.md) used by the UI Agent. 
@@ -20,17 +21,27 @@ Can be overriden [per data type](#data_transformer-str-optional_1). Defaults to
 
 Whether to allow unsupported/Tech Preview [Dynamic UI components](data_ui_blocks/dynamic_components.md) to be selected by LLM (default: `False`)
 
+
 ### `component_selection_strategy` [`str`, optional]
 
 Strategy for LLM powered component selection and configuration step:
 
 - `one_llm_call`: Uses single LLM call for component selection and configuration - default
 - `two_llm_calls`: Uses two LLM calls - first selects component type, second configures it - *experimental feature!*
 
+
 ### `input_data_json_wrapping` [`bool`, optional]
 
 Whether to perform [automatic `InputData` JSON wrapping](input_data/structure.md#automatic-json-wrapping) if JSON structure is not good for LLM processing (default: `True`)
 
+
+### `generate_all_fields` [`bool`, optional]
+
+If `True`, the agent will generate all possible view Fields for the UI component into its output configuration `UIBlockComponentMetadata.fields_all`. 
+It can be used in UI component to give user a chance to manually select/update which fields are shown.
+If `False` then all fields aren't generated. Can be overriden for individual `data_types`. (default: `False`)
+
+
 ### `data_types` [`dict[str, AgentConfigDataType]`, optional]
 
 Configurations for [`InputData.type`s](input_data/index.md#inputdata-object-fields), like:
@@ -44,6 +55,13 @@ Key is `InputData.type` to configure, value is configuration object for that dat
 
 Optional name of the [Input Data Transformer](input_data/transformation.md) to be used for this data type instead of [Agent's default one](#data_transformer-str-optional).
 
+#### `generate_all_fields` [`bool`, optional]
+
+If `True`, the agent will generate all possible view Fields for the UI component into its output configuration `UIBlockComponentMetadata.fields_all`. 
+It can be used in UI component to give user a chance to manually select/update which fields are shown.
+If `False` then all fields aren't generated, if not defined then [agent's default setting](#generate_all_fields-bool-optional) is used.
+All fields are supported only for `table` and `set-of-cards` components.
+
 
 #### `components` [`list[AgentConfigComponent]`, optional]
 

docs/guide/data_ui_blocks/dynamic_components.md

@@ -73,6 +73,9 @@ Value can be simple text or number etc. List (array) of values is supported as w
 
 Layout for this set of cards has to be provided by frontend application.
 
+If enabled in the *UI Agent* configuration, [agent's output can contain list of all fields available in the input data](../../spec/output.md), so you can 
+provide user with the ability to manually select what is shown after this UI component is generated.
+
 ### Table
 
 [![Status](https://img.shields.io/badge/Status-Tech%20Preview-orange)](https://github.com/RedHat-UX/next-gen-ui-agent)
@@ -85,3 +88,6 @@ Table is UI block that displays:
   * Table with AI selected Columns with AI generated names, and rows of values gathered from agent's input data.
 
 Individual cell value can be simple text or number etc. List (array) of values is supported as well.
+
+If enabled in the *UI Agent* configuration, [agent's output can contain list of all fields available in the input data](../../spec/output.md), so you can 
+provide user with the ability to manually select which columns are shown after this UI component is generated.

docs/guide/renderer/index.md

@@ -18,3 +18,6 @@ We provide renderers for several UI component systems:
 * Client-Side
     * [PatternFly NPM](patternfly_npm.md) - produces [PatternFly](https://www.patternfly.org/) React components
 
+
+Besides rendering itself, output of the *UI Agent* also contain [structured UI component configuration](../../spec/output.md). It can be
+used for advanced UI features, like live data updates from backend, manual selection of visualized fields etc.

docs/spec/output.md

@@ -0,0 +1,3 @@
+{%
+    include-markdown "../../spec/output/README.md"
+%}

libs/next_gen_ui_agent/agent.py

@@ -3,6 +3,7 @@
 from typing import Optional
 
 from next_gen_ui_agent.agent_config import parse_config_yaml
+from next_gen_ui_agent.all_fields_collector import generate_all_fields
 from next_gen_ui_agent.component_selection_llm_onestep import (
     OnestepLLMCallComponentSelectionStrategy,
 )
@@ -39,6 +40,7 @@
     AgentConfig,
     InputData,
     InputDataInternal,
+    UIBlockComponentMetadata,
     UIBlockConfiguration,
     UIBlockRendering,
     UIComponentMetadata,
@@ -227,14 +229,32 @@ def construct_UIBlockConfiguration(
         It should be returned from AI framework/protocol binding so *Controlling Assistant* can send it back later when it needs to refresh component for the new data.
         """
 
+        block_component_metadata = UIBlockComponentMetadata(
+            **component_metadata.model_dump(),
+        )
+
         # put sanitized data paths to the UIBlockConfiguration
-        if component_metadata.fields:
-            for field in component_metadata.fields:
+        if block_component_metadata.fields:
+            for field in block_component_metadata.fields:
                 field.data_path = sanitize_data_path(field.data_path)  # type: ignore
                 field.id = generate_field_id(field.data_path)
 
+        data_type = input_data.get("type")
+        generate_for_data_type = (
+            data_type
+            and self.config.data_types
+            and self.config.data_types.get(data_type)
+            and self.config.data_types.get(data_type).generate_all_fields  # type: ignore
+        )
+        if (
+            self.config.generate_all_fields and generate_for_data_type is not False
+        ) or generate_for_data_type is True:
+            block_component_metadata.fields_all = generate_all_fields(
+                component_metadata
+            )
+
         return UIBlockConfiguration(
-            component_metadata=component_metadata,
+            component_metadata=block_component_metadata,
             data_type=input_data.get("type"),
             input_data_transformer_name=component_metadata.input_data_transformer_name,
             json_wrapping_field_name=component_metadata.json_wrapping_field_name,