Merge pull request #9664 from liamsommer-mx/deployedKnowledgeBase

Deployed knowledge base

Author: Karuna-Mendix

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

@@ -217,7 +217,7 @@ The [ChatCompletions (with history)](/appstore/modules/genai/genai-for-mx/common
 
 Some capabilities of the chat completions operations are currently only available for specific models:
 
-* **Function Calling** - You can use function calling in all chat completions operations using a [supported model](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference-supported-models-features.html) by adding a `ToolCollection` with a `Tool` via the [Tools: Add Function to Request](/appstore/modules/genai/genai-for-mx/commons/#add-function-to-request) operation. For more information about function calling, see the [Function Calling Documentation](/appstore/modules/genai/function-calling/).
+* **Function Calling** - You can use function calling in all chat completions operations. To do this, use a [supported model](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference-supported-models-features.html) by adding a `ToolCollection` with a `Tool` via the [Tools: Add Function to Request](/appstore/modules/genai/genai-for-mx/commons/#add-function-to-request) operation. You can also first retrieve data from a knowledge base and then call `ChatCompletions` with the information required using the connector's function calling properties. In order to use this function, add a knowledge base to your Request using [Tools: Add Knowledge Base](/appstore/modules/genai/genai-for-mx/commons/#add-knowledge-base-to-request). For more information about function calling, see [Function Calling](/appstore/modules/genai/function-calling/).
 
 **Function calling microflows**: A microflow used as a tool for function calling must satisfy the following conditions:
 

content/en/docs/appstore/use-content/platform-supported-content/modules/genai/how-to/create-single-agent.md

@@ -122,7 +122,7 @@ 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 action `Connection: Get` to change the collection name from *example* to `HistoricalTickets`
+    * Near the end of the microflow, edit the action `DeployedKnowledgeBase: Get` to change the collection 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).
 
@@ -289,23 +289,22 @@ Users can now ask for information for a specific ticket by providing a ticket id
 
 Finally, you can add a tool for knowledge base retrieval. This allows the agent to query the knowledge base for similar tickets and thus tailor a response to the user based on private knowledge. Note that the knowledge base retrieval is only supported for [Mendix Cloud GenAI Resource Packs](/appstore/modules/genai/mx-cloud-genai/resource-packs/).
 
-1. In the microflow `ACT_TicketHelper_CallAgent`, add a `Retrieve` action, before the request is created, to retrieve a **Mendix Cloud Knowledge Base** object:
+1. In the microflow `ACT_TicketHelper_CallAgent`, add a `Retrieve` action, before the request is created, to retrieve a **Collection** object:
 
     * Source: `From database`
-    * Entity: `MxGenAIConnector.MxCloudKnowledgeBase` (search for *MxCloudKnowledgeBase*)
+    * Entity: `MxGenAIConnector.Collection` (search for *Collection*)
     * Range: `First`
-    * Object name: `MxCloudKnowledgeBase` (default)
+    * Object name: `Collection` (default)
 
-2. Add the `Tools: Add Mendix Cloud Knowledge Base` action after the **Request** creation microflow:
+2. Add the `Tools: Add Knowledge Base` action after the **Request** creation microflow:
 
     * Request: `Request` (object created in previous action)
-    * MxCloudKnowledgeBase: `MxCloudKnowledgeBase` (object that was retrieved in the previous step)
-    * CollectionName: `HistoricalTickets` (name that was used in the [Ingest Data into Knowledge Base](#ingest-knowledge-base))
     * MaxNumberOfResults: empty (expression; optional)
     * MinimumSimilarity: empty (expression; optional)
     * MetadataCollection: empty (expression; optional)
     * Name: `RetrieveSimilarTickets` (expression)
     * Description: `Similar tickets from the database` (expression)
+    * DeployedKnowledgeBase: `Collection` (object that was retrieved in the previous step)
     * Use return value: `no`
 
 You have successfully integrated a knowledge base into your agent interaction. Now, when a user submits a request like, `My VPN crashes all the time and I need it to work on important documents`, the agent will search the knowledge base for similar tickets and provide a relevant solution.

content/en/docs/appstore/use-content/platform-supported-content/modules/genai/how-to/ground_your_llm_in_data.md

@@ -39,7 +39,9 @@ Before implementing this capability into your app, make sure you meet the follow
 
 Since this document focuses on the [Mendix Cloud GenAI Resource Packs](/appstore/modules/genai/mx-cloud-genai/resource-packs/), ensure that you have the [Mendix Cloud GenAI Connector](https://marketplace.mendix.com/link/component/239449) installed.
 
-Follow the [Navigate through the Mendix Cloud GenAI Portal](/appstore/modules/genai/mx-cloud-genai/Navigate-MxGenAI/) instructions to collect the resources keys.
+Follow the instructions in the [Navigate through the Mendix Cloud GenAI Portal](/appstore/modules/genai/mx-cloud-genai/Navigate-MxGenAI/) guide to collect the resources keys and configure the connector within your application. The keys bridge the gap between your app and the resources, enabling you to access models and add to or retrieve data from a Mendix Cloud GenAI knowledge base.
+
+ While this documentation focuses on adding data to your knowledge base from a Mendix application, you can also fill the knowledge base directly within the portal, for example, by uploading files.
 
 ### Creating Domain Model Entity {#domainmodel}
 
@@ -80,22 +82,22 @@ To start, create a microflow that allows you to upload data into your knowledge
     * Use return value: No
     * Metadata collection: `empty` (optional)
 
-5. After the loop, add a `Retrieve` action to retrieve a `MxCloudKnowledgeBase`. In this example, the first entry found in the database is used.
+5. After the loop, add a `Retrieve` action to retrieve a `MxCloudKnowledgeBaseResource`. In this example, the first entry found in the database is used.
 
     * **Source**: `From database`
-    * **Entity**: `MxGenAIConnector.MxCloudKnowledgeBase`
+    * **Entity**: `MxGenAIConnector.MxCloudKnowledgeBaseResource`
     * **Range**: `First`
-    * **Object name**: `MxCloudKnowledgeBase`
+    * **Object name**: `MxCloudKnowledgeBaseResource`
 
-6. Next, add the `Connection: Get` action from the `Mendix Cloud Knowledge Base` category:
+6. Next, add the `DeployedKnowledgeBase: Get` action from the `Mendix Cloud Knowledge Base` category:
 
-    To edit the parameter value for `MxCloudKnowledgeBase`, double-click its type, select `Variable`, and assign it the value `MxCloudKnowledgeBase`. Similarly, for `CollectionName`, double-click its type, select `Expression`, and assign it the value `TicketSolutions`.
+    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`.
 
-    You can keep the **Use return variable** as *Yes* and the object name `MxKnowledgeBaseConnection`.
+    You can keep the **Use return variable** as *Yes* and the object name `DeployedKnowledgeBase`.
 
 7. Add the `Embed & Repopulate Collection` action to insert your knowledge into the knowledge base:
 
-    To edit the parameter value for `Connection`, double-click its type, select `Variable`, and assign it the value `MxKnowledgeBaseConnection`. Similarly, for `ChunkCollection`, double-click its type, select `Variable`, and assign it the value `GenAICommons.ChunkCollection`.
+    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`.
 
@@ -186,9 +188,9 @@ To use the knowledge in a chat interface, create and adjust certain microflows a
 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.
 
     * **Source**: `From database`
-    * **Entity**: `MxGenAIConnector.MxCloudKnowledgeBase`
+    * **Entity**: `MxGenAIConnector.MxCloudKnowledgeBaseResource`
     * **Range**: `First`
-    * **Object name**: `MxCloudKnowledgeBase`
+    * **Object name**: `MxCloudKnowledgeBaseResource`
 
 6. Add the `Tools: Add Mendix Cloud Knowledge Base` action with the settings shown in the image below:
 

content/en/docs/appstore/use-content/platform-supported-content/modules/genai/mendix-cloud-genai/Mx GenAI Connector.md

@@ -41,6 +41,8 @@ Knowledge bases are often used for:
 1. [Retrieval Augmented Generation (RAG)](https://docs.mendix.com/appstore/modules/genai/rag/) retrieves relevant knowledge from the knowledge base, incorporates it into a prompt, and sends it to the model to generate a response.
 2. Semantic search enables advanced search capabilities by considering the semantic meaning of the text, going beyond exact and approximate matching. It allows the knowledge base to be searched for similar chunks effectively.
 
+If you are looking for a step-by-step guide on how to get your application data into a Mendix Cloud Knowledge Base, refer [Grounding Your Large Language Model in Data – Mendix Cloud GenAI](/appstore/modules/genai/how-to/howto-groundllm/). Note that the Mendix Portal also provides options for importing data into your knowledge base, such as file uploads. For more information, see [Navigate through the Mendix Cloud GenAI Portal](/appstore/modules/genai/mx-cloud-genai/Navigate-MxGenAI/). This documentation focuses solely on adding data from an application using the connector.
+
 #### Embeddings
 
 Convert strings into vector embeddings for various purposes based on the relatedness of texts.
@@ -87,15 +89,17 @@ Follow the steps below to get started:
 * Make sure to configure the [Encryption module](/appstore/modules/encryption/#configuration) before you connect your app to Mendix Cloud GenAI.
 * Add the module role `MxGenAIConnector.Administrator` to your Administrator **User roles** in the **Security** settings of your app. 
 * Add the `Configuration_Overview` page (**USE_ME** > **Configuration**) to your navigation, or add the `Snippet_Configuration` to a page that is already part of your navigation. Alternatively, you can register your key by using the `Configuration_RegisterByString` microflow.
-* Complete the runtime setup of Mendix Cloud GenAI configuration by navigating to the page mentioned above. Import a key generated in the [portal](https://genai.home.mendix.com) or provided to you and click **Test Key** to validate its functionality.
+* Complete the runtime setup of Mendix Cloud GenAI configuration by navigating to the page mentioned above. Import a key generated in the [portal](https://genai.home.mendix.com) or provided to you and click **Test Key** to validate its functionality. Note that this key establishes a connection between the Mendix Cloud resources and your application. It contains all the information required to set up the connection.
 
 ## Operations
 
 {{< 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.
 
-To use the operations, either a `DeployedModel` (text, embeddings) or a `MxKnowledgebaseConnection` must always be passed as input. The DeployedModel will be created automatically when importing keys at runtime and needs to be retrieved from the database. To initialize a knowledge base operation, use the `Connection: Get` toolbox action to create the `MxKnowledgebaseConnection` object. It requires a `CollectionName` (string) for the right collection inside of the knowledge base resource to be used.
+To use the operations, either a `DeployedModel` (text, embeddings) or a `DeployedKnowledgeBase` must always be passed as input. The DeployedModel will be created automatically when importing keys at runtime and needs to be retrieved from the database. To initialize a knowledge base operation, use the `DeployedKnowledgeBase: Get` toolbox action to retrieve the DeployedKnowledgeBase object for a specified collection. It requires the collection's Name (string) as input. 
+
+In Mendix Cloud GenAI, a single knowledge base resource (MxCloudKnowledgeBaseResource) can contain multiple collections (tables). As a result, several DeployedKnowledgeBase objects may belong to the same resource.
 
 ### Chat Completions Operation
 
@@ -119,7 +123,7 @@ 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 Mendix Cloud 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. Additionally, you may apply optional filters, such as `MaxNumberOfResults` or `MinimumSimilarity`, or pass a [MetadataCollection](/appstore/modules/genai/genai-for-mx/commons/#metadatacollection-entity). The optional `Description` can help the model understand the knowledge base content and decide whether it should be called in the current chat context.
+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" >}}
 
@@ -166,7 +170,7 @@ The model uses the file name when analyzing documents, which may introduce a pot
 
 ### Knowledge Base Operations
 
-To implement knowledge base logic into your Mendix application, you can use the actions in the **USE_ME** > **Knowledge Base** folder or under the **GenAI Knowledge Base (Content)** or **Mendix Cloud Knowledge Base** categories in the **Toolbox**. These actions require a specialized [Connection](/appstore/modules/genai/genai-for-mx/commons/#connection) of type `MxKnowledgeBaseConnection` that determines the model and endpoint to use. Additionally, the collection name must be passed when creating the object and it must be associated with a `Configuration` object. Please note that for Mendix Cloud GenAI a knowledge base resource may contain several collections (tables). 
+To implement knowledge base logic into your Mendix application, you can use the actions in the **USE_ME** > **Knowledge Base** folder or under the **GenAI Knowledge Base (Content)** or **Mendix Cloud Knowledge Base** categories in the **Toolbox**. These actions require a specialized [DeployedKnowledgeBase](/appstore/modules/genai/genai-for-mx/commons/#deployed-knowledge-base) of type `Collection` that determines the model and endpoint to use. Additionally, the collection name must be passed when creating the object and it must be associated with a `Configuration` object. Please note that for Mendix Cloud GenAI a knowledge base resource may contain several collections (tables). 
 
 Dealing with knowledge bases involves two main stages:
 
@@ -193,7 +197,7 @@ The chunk collection can then be stored in the knowledge base using one of the f
 
 ##### Add Data Chunks to Your Knowledge Base
 
-Use the following toolbox actions inside the **Mendix Cloud Knowledge Base** toolbox category to populate knowledge data into the knowledge base:
+Use the following toolbox actions inside the **Mendix Cloud Knowledge Base** toolbox category to populate knowledge data into a collection:
 
 1. `Embed & Insert` embeds a list of chunks (passed via a [ChunkCollection](/appstore/modules/genai/genai-for-mx/commons/#chunkcollection)) and inserts them into the knowledge base.
 2. `Embed & repopulate KB` is similar to the `Embed & Insert`, but deletes all existing chunks from the knowledge base before inserting the new chunks.
@@ -206,15 +210,11 @@ Additionally, use the following toolbox actions to delete chunks:
 
 When data in your Mendix app that is relevant to the knowledge base changes, it is usually necessary to keep the knowledge base chunks in sync. Whenever a Mendix Object changes, the affected chunks must be updated. Depending on your use case, the `Embed & Replace` and `Delete for Objects` can be conveniently used in event handler microflows.
 
-The example below shows how to repopulate a knowledge base using a list of Mendix objects:
-
-{{< figure src="/attachments/appstore/platform-supported-content/modules/genai/mxgenAI-connector/PushTicketstoMxKB.png" >}} 
-
 ##### Knowledge Base Retrieval{#knowledge-base-retrieval}
 
-The following toolbox actions can be used to retrieve knowledge data from the knowledge base (and associate it with your Mendix data):
+The following toolbox actions can be used to retrieve knowledge data from a collection (and associate it with your Mendix data):
 
-1. `Retrieve` retrieves knowledge base chunks from the knowledge base. You can use pagination via the `Offset` and `MaxNumberOfResults` parameters or apply filtering via a `MetadataCollection` or `MxObject`. (Scroll down to see all available input parameters of this operation)
+1. `Retrieve` retrieves knowledge base chunks from the knowledge base. You can use pagination via the `Offset` and `MaxNumberOfResults` parameters or apply filtering via a `MetadataCollection` or `MxObject`. 
 2. `Retrieve & Associate` is similar to the `Retrieve` but associates the returned chunks with a Mendix object if they were linked at the insertion stage. 
 
     {{% alert color="info" %}}You must define your entity specialized from `KnowledgeBaseChunk`, which is associated to the entity that was used to pass a MendixObject during the [insertion stage](#knowledge-base-insertion).