docs: address ai insights recommendations (#1810)

* docs: address ai insights recommendations

* docs: further refinements

* chore: delete outdated images

* Update AI-powered-insights.md

---------

Co-authored-by: Dimitar Nikolov <[email protected]>

Author: petar-i-todorov

embedding-reports/display-reports-in-applications/web-application/ai-interactivity.md

@@ -1,5 +1,5 @@
 ---
-title: AI-Powered Insights in Report Preview
+title: AI-Powered Insights
 page_title: AI-Powered Insights in Report Preview
 description: "Learn how to implement an AI-powered prompt UI as part of any web-based report viewer."
 slug: telerikreporting/designing-reports/adding-interactivity-to-reports/ai-powered-insights
@@ -12,14 +12,15 @@ position: 1
 
 **AI Insights** is an AI-powered feature available during the report preview. It enables users to execute predefined or custom prompts on the core data of the previewed report, uncovering valuable insights, generating summaries, or answering specific questions. The feature also supports fine-tuning of the embedded Retrieval-Augmented Generation (RAG) algorithms, optimizing them to deliver accurate responses while minimizing token consumption.
 
+>tip For a working example of this functionality, check the [AI Insights Report Demo](https://demos.telerik.com/reporting/ai-insights).
+
 ![The UI of the AI system after configuration.](images/angular-report-viewer-with-ai-insights.png)
 
 ## Feature Concept
 
-To bring the power of Generative AI (GenAI) into reporting workflows, we are introducing a **AI Prompt** dialog that integrates seamlessly in the report viewers. The dialog provides a convenient UI for sending predefined or custom prompts to an AI model, configured in the Reporting REST Service. The prompts and responses returned from the AI model are displayed in the Output panel of the dialog, allowing for easier tracking of the conversation.
-
+To bring the power of Generative AI (GenAI) into reporting workflows, we are introducing an **AI Prompt** dialog that integrates seamlessly in the report viewers. The dialog provides a convenient UI for sending predefined or custom prompts to an AI model, configured in the Reporting REST Service. The prompts and responses returned from the AI model are displayed in the Output panel of the dialog, allowing for easier tracking of the conversation.
 
-**TODO**: explain about the context that is kept within one report and is cleared when changing the report parameters or navigating to another report.
+The AI conversation maintains context throughout user's interaction with a specific report. All previous questions and responses are preserved and sent to the AI model as context, enabling more coherent and contextually relevant conversations. However, this context is automatically cleared when report parameters are changed or when navigating to a different report, ensuring that each report session starts with a fresh conversation thread.
 
 The feature is supported by all [web report viewers]({%slug telerikreporting/using-reports-in-applications/display-reports-in-applications/web-application/html5-report-viewer/overview%}) and by the [WPF Report Viewer]({%slug telerikreporting/using-reports-in-applications/display-reports-in-applications/wpf-application/overview%}) connected to a remote Reporting REST Service.
 
@@ -33,30 +34,25 @@ The feature is supported by all [web report viewers]({%slug telerikreporting/usi
   Alternatively, you may disable the feature by setting the _AIClient allowRAG_ attribute to _false_.
 
 - **Predefined Summary Prompts**  
-  Users can choose from a set of **predefined prompts** tailored for common tasks like summarization, explanation, and data insights—boosting efficiency with minimal effort.
+  Users can choose from a set of predefined prompts tailored for common tasks like summarization, explanation, and data insights—boosting efficiency with minimal effort.
 
-- **Custom AI Prompts**
-  Besides the predefined prompts, you can choose to allow custom prompts to be made by the end-users of the application.
+- **Custom AI Prompts**  
+  Besides the predefined prompts, users can create and use custom prompts through the UI.
 
 - **End-User Consent for Data Sharing**  
-  To ensure transparency and compliance, the **AI Prompt** will **request explicit consent** from users before sharing any data with GenAI services.
+  To ensure transparency and compliance, the AI Prompt requests explicit consent from users before sharing any data with GenAI services.
 
-- **Flexible Context Selection**  
-  Users can define the scope of the prompt by selecting:
-  
-  * The **entire document**
-  * A **specific page**
-  * A **range of pages**
+<img src="images/predefined-prompts.png" style="border: 1px solid lightgray; width: 500px" alt="Image of the Prompt UI" />
 
-<img src="images/AskAIPrompt-updated.png" style="border: 1px solid lightgray" alt="Image of the Prompt UI" />
+## User Consent
 
-## User Consent for AI Summaries
+Before using the AI Prompt dialog, users must give consent for the AI to process their provided text. This ensures transparency and user control over their data.
 
-Before using the AI Prompt Dialog, users must give consent for the AI to process their provided text. This ensures transparency and user control over their data.
+<img src="images/user-consent.png" style="border: 1px solid lightgray; width: 500px" alt="User Consent for AI Summaries" />
 
-<img src="images/UserConsentForAI-updated.png" style="border: 1px solid lightgray" alt="User Consent for AI Summaries" />
+## Configuration
 
-## Configure the AI
+To enable the AI-powered insights functionality, you must provide a valid configuration that defines the AI client, model, and other essential details such as authentication credentials. This configuration also allows you to customize various aspects of the AI functionality, including user consent requirements, custom prompt permissions, and Retrieval-Augmented Generation (RAG) settings. The AI configuration is managed through the [report engine configuration]({%slug telerikreporting/using-reports-in-applications/export-and-configure/configure-the-report-engine/overview%}). For a complete list of available settings, check the table below. For an example configuration, check the [Example](#example) section.
 
 | Setting | Description |
 | ------ | ------ |
@@ -67,8 +63,8 @@ Before using the AI Prompt Dialog, users must give consent for the AI to process
 |requireConsent|A boolean configuration option that determines whether users must explicitly consent to the use of AI models before the AI report insights features can be utilized within the application.|
 |allowCustomPrompts|This setting is set to true by default. If you set it to `false`, users will only be able to use the predefined prompts and will not be allowed to ask custom prompts.|
 |predefinedPrompts|This setting specifies a list of predefined prompts that the AI client can use. Each prompt is defined by a text attribute, which contains the prompt's content.|
-|allowRAG|This setting specifies whether the [Retrieval-Augmented Generation (RAG)](https://en.wikipedia.org/wiki/Retrieval-augmented_generation) is allowed. The default value is _true_. Available only on projects targeting .NET and .NET Standard.|
-|ragSettings|These settings specify the configuration of the [Retrieval-Augmented Generation (RAG)](https://en.wikipedia.org/wiki/Retrieval-augmented_generation) when allowed by the _allowRAG_ setting. Available only on projects targeting .NET and .NET Standard.|
+|allowRAG|This setting specifies whether the [Retrieval-Augmented Generation (RAG)](https://en.wikipedia.org/wiki/Retrieval-augmented_generation) is allowed. The default value is _true_. Available only on projects targeting .NET8 or higher.|
+|ragSettings|These settings specify the configuration of the [Retrieval-Augmented Generation (RAG)](https://en.wikipedia.org/wiki/Retrieval-augmented_generation) when allowed by the _allowRAG_ setting. Available only on projects targeting .NET8 or higher.|
 
 __AI clients__
 
@@ -88,6 +84,8 @@ Depending on which option will be used, a corresponding `Telerik.Reporting.Teler
 - `Telerik.Reporting.AI.Microsoft.Extensions.Ollama`
 - `Telerik.Reporting.AI.Microsoft.Extensions.OpenAI`
 
+### Example
+
 Below is an example of how to configure the project for the `AzureOpenAI` option.
 
 ````JSON
@@ -102,8 +100,8 @@ Below is an example of how to configure the project for the `AzureOpenAI` option
 			"allowCustomPrompts": false,
 			"allowRAG": true,
 			"predefinedPrompts": [
-				{ "text": "Prompt 1" },
-				{ "text": "Prompt 2" }
+				{ "text": "Generate a summary of the report." },
+				{ "text": "Translate the report into German." }
 			],
 			"ragSettings": {
 				"tokenizationEncoding": "Set Encoding Name Here",
@@ -126,22 +124,21 @@ Below is an example of how to configure the project for the `AzureOpenAI` option
          requireConsent="false"
          allowCustomPrompts="false">
          <predefinedPrompts>
-             <add text="Prompt 1" />
-             <add text="Prompt 2" />
+             <add text="Generate a summary of the report." />
+             <add text="Translate the report into German." />
          </predefinedPrompts>
      </AIClient>
  </Telerik.Reporting>
 ````
 
-
 ## Customization
 The workflow of instantiating the AI Client and passing a request to it can be customized by overriding the following methods of the [ReportsController](/api/telerik.reporting.services.webapi.reportscontrollerbase) class:
-* [CreateAIThread(string, string, ClientReportSource)](/api/telerik.reporting.services.webapi.reportscontrollerbase#Telerik_Reporting_Services_WebApi_ReportsControllerBase_CreateAIThread_System_String_System_String_Telerik_Reporting_Services_WebApi_ClientReportSource_) - called when the AI Prompt dialog is to be displayed. In this method the AI Client is instantiated either using the settings provided in the application configuration file, or by using the AIClientFactory instance provided with the Reporting REST Service Configuration (see [Extensibility]({%slug telerikreporting/designing-reports/adding-interactivity-to-reports/ai-powered-insights%}#extensibility) below. Providing custom logic in the method allows to control the UI properties of the AI Prompt dialog: changing or disabling the consent message, enabling/disabling custom prompts, etc. This logic can be based on the currently previewed report, represented by the property **ClientReportSource**.
+* [CreateAIThread(string, string, ClientReportSource)](/api/telerik.reporting.services.webapi.reportscontrollerbase#Telerik_Reporting_Services_WebApi_ReportsControllerBase_CreateAIThread_System_String_System_String_Telerik_Reporting_Services_WebApi_ClientReportSource_) - called when the AI Prompt dialog is to be displayed. In this method, the AI Client is instantiated either using the settings provided in the application configuration file, or by using the AIClientFactory instance provided with the Reporting REST Service Configuration (see [Extensibility]({%slug telerikreporting/designing-reports/adding-interactivity-to-reports/ai-powered-insights%}#extensibility) below. Providing custom logic in the method allows to control the UI properties of the AI Prompt dialog: changing or disabling the consent message, enabling/disabling custom prompts, etc. This logic can be based on the currently previewed report, represented by the property **ClientReportSource**.
 
 {{source=CodeSnippets\MvcCS\Controllers\ReportsController.cs region=ReportsController_CreateAIThread_CheckReportSource}}
 
 
-* [UpdateAIPrompts(ClientReportSource, AIThreadInfo)](/api/telerik.reporting.services.webapi.reportscontrollerbase#collapsible-Telerik_Reporting_Services_WebApi_ReportsControllerBase_UpdateAIPrompts_Telerik_Reporting_Services_WebApi_ClientReportSource_Telerik_Reporting_Services_Engine_AIThreadInfo_) - called internally during the execution of **CreateAIThread()** method. Provides easier access to the predefined prompts, allowing to alter or disable them based on a custom logic like the role of the currently logged user, or on the currently previewed report, represented by the property **ClientReportSource**.
+* [UpdateAIPrompts(ClientReportSource, AIThreadInfo)](/api/telerik.reporting.services.webapi.reportscontrollerbase#collapsible-Telerik_Reporting_Services_WebApi_ReportsControllerBase_UpdateAIPrompts_Telerik_Reporting_Services_WebApi_ClientReportSource_Telerik_Reporting_Services_Engine_AIThreadInfo_) - called internally during the execution of the **CreateAIThread()** method. Provides easier access to the predefined prompts, allowing to alter or disable them based on custom logic like the role of the currently logged user, or on the currently previewed report, represented by the property **ClientReportSource**.
 
 {{source=CodeSnippets\MvcCS\Controllers\ReportsController.cs region=ReportsController_CreateAIThread_UpdateAIPrompts}}
 
@@ -172,9 +169,8 @@ static Telerik.Reporting.AI.IClient GetCustomAIClient()
 }
 ````
 
-
 ## See Also
 
-* [Overview of the AI Interactivity]({%slug telerikreporting/using-reports-in-applications/display-reports-in-applications/web-application/ai-interactivity%})
+* [AI Insights Report Demo](https://demos.telerik.com/reporting/ai-insights)
 * [AIClient Element Overview]({%slug telerikreporting/aiclient-element%})
 * [Interface IClient](https://docs.telerik.com/reporting/api/telerik.reporting.ai.iclient)