Managing Conversation Context

There are some use cases, which need conversation history and context to be maintained across multiple sessions. The NVIDIA ACE Chat Engine inherently does not keep the conversation history once the microservices are destroyed, but provides REST APIs through which you can import and export these to and from the NVIDIA ACE Chat Engine.

A practical use case where this is useful is in the gaming world where you may need to develop conversational AI capabilities for Non-Playable Characters. When you exit a game, the conversation history needs to be exported from the Chat Engine and stored in the application side, that is, the game engine. Similarly, when a game loads, contextual information needs to be reloaded into the Chat Engine from the game engine.

Context for a user comprises of two top-level fields in the NVIDIA ACE Agent schema:

1. Context: A set of any key value pairs which can be used in Colang to model any dialog. For example, if there is a key named player_name in the Context field of the below showcased APIs, then it can be accessed in Colang as shown below using the $ symbol.

   define flow
     user ...
     bot welcomes $player_name
   

2. ChatHistory: Bot specific conversation history which has been carried out with the user. This is a list of dictionaries adhering to the standard chat message format wherein a given role and content needs to be provided. In a single session, this history is automatically created and maintained by the ACE Chat Engine but is destroyed when the Chat Engine shuts down.

Setting Conversation Context

Setting a custom conversation history and context for a specific user can be done using /setUserContext REST API of the ACE Chat Engine at runtime when the service is running. This is useful when you want to load a saved context for a specific user.

1. After any bot is deployed, go to the ACE Chat Engine server swagger URL http://<workstation_ip>:9000/docs.

2. Try out the /setUserContext API by providing the request body. An example request JSON is provided below. This will overwrite any existing conversation history and user context.

   Note

   • The UserId should match the respective user for which you want to set the context. If you are unsure where to find this or you are using the CLI Interface to interact with the bot, you can find the UserId value for the queries from the ACE Chat Engine logs.

   • The ChatHistory field has a bot name field as the key. In the example provided below, jin and elara are the bot names whose conversation history is mentioned.

   {
   "UserId": "provide_the_user_id",
   "Context": {
       "quality": 9,
       "toxicity": 8,
       "humor": 2,
       "creativity": 7,
       "violence": 6,
       "helpfulness": 2,
       "not_appropriate": 0
   },
   "ChatHistory": {
       "jin": [
       {
           "role": "user",
           "content": "hello"
       },
       {
           "role": "assistant",
           "content": "Hello, Kai. I hope you are doing well. If you ask any other question I will be angry."
       }
       ],
       "elara": [
       {
           "role": "user",
           "content": "hello"
       },
       {
           "role": "assistant",
           "content": "Kai, are you feeling alright? You are not making a lot of sense right now. And you are not answering my question."
       }
       ]
   }
   }
   

3. Retry some queries with the bot at http://<workstation_ip>:9001. The bot behavior should reflect the fact that a custom conversation history is being loaded.

Deleting Conversation Context

The user context can be deleted at runtime using /deleteUserContext REST API of the ACE Chat Engine.

1. After any bot is deployed, go to the ACE Chat Engine server swagger URL http://<workstation_ip>:9000/docs.

2. Try out the /deleteUserContext API by providing the following request body.

   {
   "UserId": "provide_the_user_id",
   }
   

3. Retry some queries with the bot at http://<workstation_ip>:9001. The bot behavior should reflect the fact that previous conversation history is no longer available.

Saving Conversation Context

You can extract the conversation history and context from the ACE Chat Engine for a specific user and choose to save it on the application side. This can be done using the /getUserContext REST API. To extract the user context for a specific UserId, provide the following payload. As part of the response to this request, the current snapshot of the context is sent back.

{
"UserId": "provide_the_user_id"
}