Wordset app development

The previous topic gives high-level guidance on how to develop a basic NLU client application that can interpret intents and entities from text inputs. Accuracy on interpretation of values for some types of entities can often be greatly improved by providing wordsets that define values to expect.

With the gRPC Wordset API for NLU, you can create a client application to perform requested wordset operations:

  • Compile wordsets
  • Retrieve wordset metadata
  • Delete wordsets

This topic describes how to implement the basic wordsets functionality in the context of a Python application. For the complete application, see Sample Python wordsets client.

Step 1: Generate token

This step is similar to the step documented for the client runtime app. As with the runtime client, there are both Linux bash scripts and Windows batch scripts for each of the token generation scenarios.

Step 2: Import functions

In your client application, import all functions from the wordset client stubs that you generated in gRPC setup.

from nuance.nlu.wordset.v1beta1.wordset_pb2 import *
from nuance.nlu.wordset.v1beta1.wordset_pb2_grpc import *
from nuance.nlu.common.v1beta1.resource_pb2 import *

Do not edit these stub files.

Step 3: Authorize and connect

See Step 3 as documented for the client runtime app.

Step 4: Call Wordset client stub

With a communication channel established, the app calls a client stub function or class, which makes use of the channel. This stub is based on the main service name and is defined in the generated client files. In Python it is named WordsetStub.

with create_channel(args) as channel:
    stub = WordsetStub(channel)

Step 5: Configure wordset request

With authorization complete, you can configure your request to:

  • Compile a wordset: Provide a URN reference for the companion DLM, a URN reference to use for the compiled wordset, and a JSON wordset.

    def create_compile_wordset_request(args):
      target_artifact_reference = ResourceReference(uri=args.artifactUrn)
      companion_artifact_reference = ResourceReference(uri=args.modelUrn)
      wordset = json.dumps(json.load(args.wordsetFile))
      return CompileWordsetRequest(
  • Get metadata for a compiled wordset: Provide the URN reference for the wordset.

    def create_get_wordset_metadata_request(artifactUrn):
      artifact_reference = ResourceReference(uri=artifactUrn)
      return GetWordsetMetadataRequest(artifact_reference=artifact_reference)
  • Delete a compiled wordset: Provide the URN reference for the wordset.

    def create_delete_wordset_request(artifactUrn):
      artifact_reference = ResourceReference(uri=artifactUrn)
      return DeleteWordsetRequest(artifact_reference=artifact_reference)

Step 6: Perform wordset operation

After calling the client stub and configuring the wordset request, you can access the appropriate Wordset API method through the client stub, sending the request.

To compile a wordset:

def compile_wordset(args):
  with create_channel(args) as channel:
    stub = WordsetStub(channel)
    compiled_wordset_request = create_compile_wordset_request(args)
    for message in stub.CompileWordsetAndWatch(compiled_wordset_request):

To retrieve wordset metadata:

def get_wordset_metadata(args):
  with create_channel(args) as channel:
    stub = WordsetStub(channel)
    response = stub.GetWordsetMetadata(create_get_wordset_metadata_request(args.artifactUrn))

To delete a wordset:

def delete_wordset(args):
  with create_channel(args) as channel:
    stub = WordsetStub(channel)
    response = stub.DeleteWordset(create_delete_wordset_request(args.artifactUrn))