kai-karren / nlg-server

A simple example for a simple Rasa-compatible NLG Server that exposes static responses loaded from a JSON file through a REST API.

NLG Server

NLG Server is an example for a simple, Rasa-compatible NLG Server that exposes static responses loaded from a JSON file through a REST API.

Because it does not perform Natural Language Generation itself, its purpose is currently limited to separating the responses from your Rasa model to allow changes of the responses without having to retrain and upload a new model.

The exposed API follows the format defined by Rasa. See Rasa NLG Servers

Usage

The NLG server loads the responses from a given JSON file or from a directory consisting of multiple response JSON files. Using further nested directories is also supported.

Features

• Load static response JSON files (single files or from a directory)
• Use templates in your responses in the form {slotName} or $slotName (see examples section)
• Randomly chose a response from a set of given response variations
• Can be used with Rasa (Last tested with Rasa 3.2.1)

Environment Variable

reponses=<path to our json response file or to a directory of multiple response files>

Response File

The responses have to be defined as JSON in the following format

{
  "response_name": "This is an example response.",
  "example_response": "Test 1 2 3.",
  "response_with_variations": [
    "first_variation", 
    "second_variation"
  ]
}

Endpoint

address:port/nlg

The default port is 8080

Request Format

{
  "response":"example2",
  "arguments":{
    
  },
  "tracker":{
  }
} 

Response Format

{
    "text": "Some text",
}

Examples

Slot Template Filling Example

Response JSON file

{
  "example": "This is an example response.",
  "test": "Test 1 2 3.",
  "utter_template": "Your number is {number}."
}

Request

{
    "response": "utter_template",
    "tracker": {
        "sender_id": "user_42",
        "slots": {
            "number": "80"
        }
    }
}

Response

{
    "text": "Your number is 80."
}

Docker

Build an Image

To build the NLG server as a docker container you can use the provided dockerfile as an example

Replace the responses folder with your folder name

docker build -t nlg-server .

Run the container

Your build container can be run (exposed over port 8082) with the following command or your add it to a docker-compose file.

docker run -p 8082:8080 nlg-server

Resources

The POJOs for the Rasa Request and Responses have been generated with https://www.jsonschema2pojo.org/

nlg-server's Issues

Evaluate if creating a library/package for the NLG Server makes sense

Evaluate if creating a library/package for the NLG Server makes sense so that it can be used as a maven dependency.

Increase the unit test coverage

I have been lazy with unit tests for this project. There should be unit tests for all non-autogenerated classes that contain logic.

Create a Wiki and better documentation

A Wiki with documentation and examples on how to use the nlg-server project should be created.

Support for loading responses from multiple JSON files in a directory

To simplify the management of projects with lots of responses, to be able to load multiple JSON files from a given directory to load the responses would be beneficial.

Implement slot template filling

The current implementation of NLG does not yet support slot template filling in the responses. I kind of forgot that.
To enable this, the NLG Server has to receive slots from the Dialogue Engine as part of the request.

Example

"I understood that you said $number"  with slot number = 42 => "I understood that you said 42"
"I understood that you are {name}" with slot name = "Kai Karren" => "I understood that you are Kai Karren"

Requirements

• ✔️ Slot template filling of the responses has been implemented and tested

Expected Behavior

When no slots are given in the request but the response contains a template, the template should be filled with an empty String.

Add more examples

Having more examples could be helpful.

Enable CI pipeline with Github Actions

Each commit to the master branch should be build with Github Actions.

Slot Template Configuration for number slots

To have more control over how numbers are formatted when slot templates are filled, a configuration should be possible.
E.g
22 22 45 56 instead of 22224556
2 2 2 2 instead of 2222 and so on.

Evaluate support for other file formats aside from JSON

Currently, the responses can only be provided as JSON key-value pairs. To extend this also to other formats like YAML or a custom format could be a good addition. This should be evaluated and how this could look like.

Random selection when multiple responses for the same utterance name exist

At the moment, the NLG server can not handle duplicate responses for the same utterance name. The one that has been loaded last will be used.

To randomly select a response variation at runtime would be the nicer solution.