Merge pull request #9880 from liamsommer-mx/how-to-fixes

Small fixes to align with current modules

Author: Karuna-Mendix

content/en/docs/marketplace/genai/how-to/create-single-agent.md

@@ -106,7 +106,6 @@ Mendix ticket data needs to be ingested into the knowledge base. You can find a
     * Edit the first retrieve action to retrieve objects from your new entity `Ticket`.
     * In the loop, delete the second action that adds metadata to the `MetadataCollection`.
     * In the last action of the loop `Chunks: Add KnowledgeBaseChunk to ChunkCollection` keep the **Human readable ID** field empty.
-    * Near the end of the microflow, edit the `DeployedKnowledgeBase` retrieve action to change the XPath constraint for name from *example* to `HistoricalTickets`.
 
 7. Finally, create a microflow `ACT_CreateDemoData_IngestIntoKnowledgeBase` that first calls the `Tickets_CreateDataset` microflow, followed by the `ACT_TicketList_LoadAllIntoKnowledgeBase` microflow. Add this `ACT_CreateDemoData_IngestIntoKnowledgeBase` new microflow to your navigation or homepage and ensure that it is accessible to admins (add the admin role under **Allowed Roles** in the microflow properties).
 

content/en/docs/marketplace/genai/how-to/ground_your_llm_in_data.md

@@ -62,7 +62,7 @@ To start, create a microflow that allows you to upload data into your knowledge
 
 1. Create a new microflow, for example, `ACT_TicketList_LoadAllIntoKnowledgeBase`.
 
-    {{< figure src="/attachments/appstore/platform-supported-content/modules/genai/genai-howto-goundllm/loaddataintokb_example.png" >}}
+    {{< figure src="/attachments/appstore/platform-supported-content/modules/genai/genai-howto-goundllm/loaddataintokb-example-replace.png" >}}
 
 2. Add the `Retrieve Objects` action. You can configure it as follows:
 
@@ -91,25 +91,14 @@ To start, create a microflow that allows you to upload data into your knowledge
 
 6. Next, add the `DeployedKnowledgeBase: Get` action from the `Mendix Cloud Knowledge Base` category:
 
-    To edit the parameter value for `MxCloudKnowledgeBaseResource`, double-click its type, select `Variable`, and assign it the value `MxCloudKnowledgeBaseResource`. Similarly, for `CollectionName`, double-click its type, select `Expression`, and assign it the value `TicketSolutions`.
+    * **MxCloudKnowledgeBaseResource**: `MxCloudKnowledgeBaseResource` (as retrieved in the step above)
+    * **CollectionName**: `HistoricalTickets`
+    * Use return value: Yes, `DeployedKnowledgeBase`
 
-    You can keep the **Use return variable** as *Yes* and the object name `DeployedKnowledgeBase`.
+7. Add the `Embed & Replace` action to insert your knowledge into the knowledge base:
 
-7. Add the `Embed & Repopulate Collection` action to insert your knowledge into the knowledge base:
-
-    To edit the parameter value for `DeployedKnowledgeBase`, double-click its type, select `Variable`, and assign it the value `DeployedKnowledgeBase`. Similarly, for `ChunkCollection`, double-click its type, select `Variable`, and assign it the value `GenAICommons.ChunkCollection`.
-
-    You can keep the **Use return variable** as *Yes* and the variable name `IsSuccess`.
-
-8. Next (optional), include a decision:
-
-    * **Caption**: for example, `Replace Success`
-    * **Decision Type**: `Expression`
-    * **Expression**: `$IsSuccess`
-
-    If the decision is `true`, an `End event` action can be added where a microflow return value to `true`. You may add a message to inform the end user that the insertion was successful.
-
-    If the decision is `false`, an `End event` action can be added where a microflow return value to `false`. You may add a message to inform the end user that the insertion failed.
+    * **ChunkCollection**: `ChunkCollection` (as created earlier)
+    * **DeployedKnowledgeBase**: `DeployedKnowledgeBase`
 
 You have successfully implemented the knowledge base insertion microflow! If you do not have any data available in your app yet, you need to create a microflow to generate the dataset, as described in the [Data Set Microflow](#dataset) section below.
 
@@ -119,7 +108,7 @@ This microflow first checks whether a list of tickets already exists in the data
 
 1. Create a new microflow, for example, `Tickets_CreateDataset`.
 
-    {{< figure src="/attachments/appstore/platform-supported-content/modules/genai/genai-howto-goundllm/loaddataintokb_example2.png" >}}
+    {{< figure src="/attachments/appstore/platform-supported-content/modules/genai/genai-howto-goundllm/loaddataintokb-example-demodata.png" >}}
 
 2. Add a `Retrieve` action:
 
@@ -155,7 +144,7 @@ With both microflows created, they must be combined and added to the homepage to
 
 1. Create a new microflow `ACT_TicketList_CreateData_InsertIntoKnowledgeBase`.
 
-    {{< figure src="/attachments/appstore/platform-supported-content/modules/genai/genai-howto-goundllm/loaddataintokb_example3.png" >}}
+    {{< figure src="/attachments/appstore/platform-supported-content/modules/genai/genai-howto-goundllm/loaddataintokb-example-combine.png" >}}
 
 2. Add a `Call Microflow` action where you call the `MyFirstModule.Tickets_CreateDataset` microflow created above. 
 
@@ -181,20 +170,21 @@ To use the knowledge in a chat interface, create and adjust certain microflows a
 
     With the `MyFirstBot.ACT_FullScreenChat_Open microflow` configured, the `MyFirstBot.ChatContext_ChatWithHistory_ActionMicroflow` can now be adjusted to handle user-submitted messages in the chat interface.
 
-    {{< figure src="/attachments/appstore/platform-supported-content/modules/genai/genai-howto-goundllm/chatcontext_microflow_example.png" >}}
+    {{< figure src="/attachments/appstore/platform-supported-content/modules/genai/genai-howto-goundllm/chatcontext-microflow-example.png" >}}
 
 4. Open your `MyFirstBot.ChatContext_ChatWithHistory_ActionMicroflow` microflow in your **MyFirstBot** module.
 
-5. After the `Request found` decision, add a `Retrieve` action. In this example, the first entry found in the database is used, just as in the insertion microflow.
+5. After the `Request found` decision, add a `Retrieve` action. In this example, we retrieve the same as in the insertion microflow.
 
     * **Source**: `From database`
-    * **Entity**: `MxGenAIConnector.MxCloudKnowledgeBaseResource`
+    * **Entity**: `GenAICommons.DeployedKnowledgeBase`
+    * **XPath constraint**: `[Name = 'HistoricalTickets']`
     * **Range**: `First`
-    * **Object name**: `MxCloudKnowledgeBaseResource`
+    * **Object name**: `DeployedKnowledgeBase_SimilarTickets`
 
-6. Add the `Tools: Add Mendix Cloud Knowledge Base` action with the settings shown in the image below:
+6. Add the `Tools: Add Knowledge Base` action with the settings shown in the image below:
 
-    {{< figure src="/attachments/appstore/platform-supported-content/modules/genai/genai-howto-goundllm/tool_mendixcloudgenai_example_action.png" >}}
+    {{< figure src="/attachments/appstore/platform-supported-content/modules/genai/genai-howto-goundllm/tool-addknowledgebase-example.png" >}}
 
 The rest of the actions can remain as they are currently set. Now that everything is implemented, you can test the chat with enriched knowledge.
 

content/en/docs/marketplace/genai/mendix-cloud-genai/Mx GenAI Connector.md

@@ -93,7 +93,7 @@ Follow the steps below to get started:
 
 ## Operations
 
-{{< figure src="/attachments/appstore/platform-supported-content/modules/genai/mxgenAI-connector/MxGenAIConnector_Configuration.png" >}}
+{{< figure src="/attachments/appstore/platform-supported-content/modules/genai/mxgenAI-connector/mxgenaiconnector-configuration.png" >}}
 
 Configuration keys are stored persistently after they are imported (either via the UI or the exposed microflow). There are three different types of configurations that reflect the use cases this service supports. The specific operations are described below.
 
@@ -123,13 +123,17 @@ The microflow activity [Chat completions (with history)](/appstore/modules/genai
 
 #### Retrieve & Generate {#retrieve-and-generate}
 
-To use retrieval and generation in a single operation, an internally predefined tool can be added to the [Request](/appstore/modules/genai/genai-for-mx/commons/#request) via the `Tools: Add Knowledge Base` action . The model can then decide whether to use the [knowledge base retrieval](/appstore/modules/genai/genai-for-mx/commons/#knowledge-base-retrieval) tool when handling the request. This functionality is supported in both with-history and without-history operations. The (optional) `Description` helps the model to understand the knowledge base content and decide whether it should be called in the current chat context. Additionally, you may apply optional filters, such as `MaxNumberOfResults` or `MinimumSimilarity`, or pass a [MetadataCollection](/appstore/modules/genai/genai-for-mx/commons/#metadatacollection-entity). 
+To use retrieval and generation in a single operation, an internally predefined tool can be added to the [Request](/appstore/modules/genai/genai-for-mx/commons/#request) via the `Tools: Add Knowledge Base` action. The model can then decide whether to use the [knowledge base retrieval](/appstore/modules/genai/genai-for-mx/commons/#knowledge-base-retrieval) tool when handling the request. This functionality is supported in both with-history and without-history operations. The (optional) `Description` helps the model to understand the knowledge base content and decide whether it should be called in the current chat context. Additionally, you may apply optional filters, such as `MaxNumberOfResults` or `MinimumSimilarity`, or pass a [MetadataCollection](/appstore/modules/genai/genai-for-mx/commons/#metadatacollection-entity). 
 
-{{< figure src="/attachments/appstore/platform-supported-content/modules/genai/mxgenAI-connector/MxGenAIConnector_ConfigureRAG.png" >}}
+{{< figure src="/attachments/appstore/platform-supported-content/modules/genai/mxgenAI-connector/mxgenaiconnector-rag.png" >}}
 
-The returned `Response` includes [References](/appstore/modules/genai/genai-for-mx/commons/#reference) if the model used them to generate its response. In some cases, a knowledge chunk consists of two texts: one for the semantic search step (retrieval) and another for the generation step. For example, when solving a problem based on historical solutions, the semantic search identifies similar problems using their descriptions, while the generation step produces a solution based on the corresponding historical solutions. In those cases, you can add [MetaData](/appstore/modules/genai/genai-for-mx/commons/#chunkcollection-add-knowledgebasechunk) with the key `knowledge` to the chunks during the insertion stage, allowing the model to base its response on the specified metadata rather than the input text (only the knowledge is passed to the model).
+The returned `Response` includes [References](/appstore/modules/genai/genai-for-mx/commons/#reference) for each retreived chunk from the knowledge base. 
 
-Additionally, to utilize the `Source` attribute of the references, you can include `MetaData` with the key `sourceUrl`. Finally, the `HumanReadableId` of a chunk is used to display the reference's title in the response.
+Optionally, you can control both reference creation and the output returned for the model during the insertion step:
+
+* The `HumanReadableId` of a chunk is used for the reference title in the response, which is shown to the end user in the [ConversationalUI](/appstore/modules/genai/genai-for-mx/conversational-ui/).
+* To utilize the `Source` attribute of the references, include `MetaData` with the key `sourceUrl`. In [ConversationalUI](/appstore/modules/genai/genai-for-mx/conversational-ui/), this will appear as a clickable link for the end user.
+* In some cases, a knowledge chunk consists of two texts: one for the semantic search (retrieval) step, and another for the generation step. For example, when solving a problem based on historical solutions, semantic search identifies similar problems using their descriptions, while the generation step produces a solution based on the corresponding historical solutions. In such cases, you can add [MetaData](/appstore/modules/genai/genai-for-mx/commons/#chunkcollection-add-knowledgebasechunk) with the key `knowledge` to each chunk during insertion. This allows the model to generate its response using the specified metadata instead of the input text (only the value of `knowledge` is passed to the model).
 
 #### Function Calling{#function-calling}
 

content/en/docs/marketplace/platform-supported-content/modules/aws/amazon-bedrock.md

@@ -51,25 +51,62 @@ Follow the instructions in [How to Use Marketplace Content](/appstore/use-conten
 
 After you install the connector, you can find it in the **App Explorer**, in the **AmazonBedrockConnector** section. The connector provides a [domain model and several activities](#technical-reference) that you can use to connect your app to Amazon Bedrock. Each activity can be implemented by using it in a microflow. To ensure that your app can connect to the AWS service, you must also configure AWS authentication for the connector. 
 
-### Using Amazon Bedrock Models
+### Configuring AWS Authentication {#configure-authentication}
 
-To use Amazon Bedrock models, keep in mind some specific requirements, as listed below.
+To use the Amazon Bedrock service, you must authenticate with AWS. To do so, you must set up a configuration profile in your Mendix app. After you set up the configuration profile, the connector module handles the authentication internally.
 
-#### Model Lifecycle
+As of version 3.0.0 of the [AWS Authentication Connector](https://marketplace.mendix.com/link/component/120333), all the resources and logic required to set up authentication are centralized inside the AWS Authentication Connector module.
 
-Amazon Bedrock models have a lifecycle that consists of the Active, Legacy, and EOL stages. For more information, see [Model lifecycle](https://docs.aws.amazon.com/bedrock/latest/userguide/model-lifecycle.html). Models are no longer available for use after they reach the EOL state. To ensure that your application functions as intended, make sure that you regularly monitor the state of the model that you are using. For example, you may want to use an API call to retrieve the status of the model and alert you once it reaches the Legacy state. To programmatically get information about available models and their lifecycle status, you can use the **ListFoundationModels** operation.
+The AWS Authentication Connector supports both **static credentials** and **temporary credentials**. For more information and detailed instructions please refer to the [AWS Authentication Connector documentation page](/appstore/modules/aws/aws-authentication/).
 
-### Configuring AWS Authentication
+### Syncing Available Models, Knowledge Bases, and Agents
 
-In order to use the Amazon Bedrock service, you must authenticate with AWS. To do so, you must set up a configuration profile in your Mendix app. After you set up the configuration profile, the connector module handles the authentication internally.
+You can use the `SNIP_Settings_Admin_ConfigOverview` snippet under **_USE_ME > SyncBedrockMetadata > ReusableUI** on an administrator page to sync models, knowledge bases and agents for the selected region at runtime. Admins on the page first need to configure the settings of the [AWS Authentication Connector](#configure-authentication) module, by selecting the AWS region and how to authenticate. When saving the settings or when you sync the models for the current region, AWS metadata services are called to create persistent objects in the database which you can view in the tables at the bottom of the snippet. 
 
-As of version 3.0.0 of the [AWS Authentication Connector](https://marketplace.mendix.com/link/component/120333), all the resources and logic required to set up authentication are centralized inside the AWS Authentication Connector module.
+{{% alert color="info" %}}
+All models are shown, even those which you cannot accesss. Access to models must be configured in the AWS console.
+{{% /alert %}}
 
-The AWS Authentication Connector supports both **static credentials** and **temporary credentials**. For more information and detailed instructions please refer to the [AWS Authentication Connector documentation page](/appstore/modules/aws/aws-authentication/).
+#### Syncing Resources Using Microflows
+
+If you do not want to configure the resources in an admin user interface, you can use the following actions in your custom microflows:
+
+* Sync Models & Knowledge Bases & Agents
+* [Sync Models](#sync-models) 
+* [Sync Knowledge Bases](#sync-knowledge-bases)
+* [Sync Agents](#sync-agents)
+
+The following actions only list the available resources as non-persistent objects:
+
+* List Foundation Models
+* List Agents
+* List Data Sources
+
+#### Adding Custom Models to your Bedrock Configuration {#adding-custom-model}
+
+When syncing your Bedrock configuration, only publicly available foundation models can be retrieved using the `List Foundation Models` action from the Bedrock Connector. To use cross-region inference (CRI) or provisioned-throughput models that you have setup in your AWS console, you must manually add these models to your database. To add a custom model, follow the steps below:
+
+1. Click **Add model** above the model's table.
+2. Fill out the form with the relevant information of your custom model.
+
+    The display name is shown in the model dropdowns while choosing a model to use. The model ID is required to use the model with Amazon Bedrock. The other fields must be filled out according to the functionalities the model can use.
+
+3. Save the model.
+
+You can now use the custom model with the actions of your choice.
+
+### Using Amazon Bedrock Models
+
+To use Amazon Bedrock models, keep in mind some specific requirements, as listed below.
+
+#### Model Lifecycle
+
+Amazon Bedrock models have a lifecycle that consists of the Active, Legacy, and EOL stages. For more information, see [Model lifecycle](https://docs.aws.amazon.com/bedrock/latest/userguide/model-lifecycle.html). Models are no longer available for use after they reach the EOL state. To ensure that your application functions as intended, make sure that you regularly monitor the state of the model that you are using. For example, you may want to use an API call to retrieve the status of the model and alert you once it reaches the Legacy state. To programmatically get information about available models and their lifecycle status, you can use the **ListFoundationModels** operation.
 
 ### Configuring a Microflow for an AWS Service
 
-After you configure the authentication profile for Amazon Bedrock, you can implement the functions of the connector by using the provided activities in microflows. The **USE_ME** folder contains several subfolders containing operations that depend on the GenAI Commons module. The following example microflows have been created for each of these inside the **ExampleImplementations** folder:
+After you configure the authentication profile for Amazon Bedrock, you can implement the functions of the connector by using the provided activities in microflows. The most important actions are available in the toolbox or in the [GenAI Commons](/appstore/modules/genai/genai-for-mx/commons/#microflows) module.
+The **USE_ME** folder contains several subfolders containing operations. The following example microflows have been created for each of these inside the **ExampleImplementations** folder:
 
 * EXAMPLE_ChatCompletions_FunctionCalling
 * EXAMPLE_ChatCompletions_Vision
@@ -669,13 +706,7 @@ The Amazon Bedrock Connector offers a range of operations to retrieve and store
 
 This can be useful to e.g. associate a chatbot configuration to an available model by selecting the model via dropdown in runtime. The persistent domain model allows for simple and efficient filtering capabilities on the available metadata. Further, the *SNIP_Settings_Admin_BedrockConfig* Snippet can be used to manage and view the synced data from an administrator perspective.
 
-Currently, there are operations available to sync metadata about:
-
-* Sync Models 
-* Sync Knowledge Bases
-* Sync Agents
-
-The syncing process works the same for all of these operations. 
+The syncing process works the same for all of these operations:
 
 1. Information about models, knowledge bases, and agents is persistent in the Mendix app's database on the initial sync.
 2. For knowledge base and agents, an association to the `AmazonBedrockRegion` object, that represents the AWS region used when syncing, is stored.