gRPC setup

The basic steps in using the gRPC protocol for NLU as a Service gRPC API are:

  1. Install gRPC for the programming language of your choice, including C++, Java, Python, Go, Ruby, C#, Node.js, and others. See the gRPC Documentation  for a complete list and instructions on using gRPC with each language.

    For example, to install gRPC for Python:

    python3 -m venv env
source env/bin/activate
pip install grpcio
pip install grpcio-tools
mkdir -p google/api
curl https://raw.githubusercontent.com/googleapis/googleapis/master/google/api/annotations.proto \
google/api/annotations.proto
curl https://raw.githubusercontent.com/googleapis/googleapis/master/google/api/http.proto \
google/api/http.proto

  2. Download the zip files containing the gRPC proto files:

    Together, these zip files contain several sets of proto files:

    • nuance/nlu/v1/ contains protos related to runtime NLU interpretation: runtime.proto, result.proto, interpretation-common.proto, single-intent-interpretation.proto, and multi-intent-interpretation.proto

    • nuance/nlu/wordset/v1beta1/ contains wordset.proto with RPCs and messages related to working with compiled wordsets

    • nuance/nlu/common/v1beta1/ contains generic classes for referencing external resources and for job status updates: job.proto and resource.proto

    • nuance/rpc/ contains generic classes for status and error codes: status.proto, status_code.proto, and error_details.proto

  3. Unzip the files in a location that your applications can access, for example in a directory containing your client apps.

    If you have proto files and applications from an earlier version of NLUaaS, create a new directory to hold the new files. This will make it easier to identify the Runtime and Wordset files in their new path structure.

    The zip files contain common messaging files, error_details.proto, status_code.proto, and status.proto. If you already have these files (for example, if you have already done this for ASRaaS or DLGaaS, which also use these protos), you are prompted to keep or overwrite them: choose [n]o or [N]one.

    replace  nuance/rpc/error_details.proto? [y]es, [n]o, [A]ll, [N]one, [r]ename: N

    These are the files after unzipping:

    unzip nuance_nlu_runtime_protos_v1.zip
unzip nuance_nlu_wordset_protos_v1.zip

├── Your client apps here
├── nuance_nlu_runtime_protos_v1.zip
├── nuance_nlu_wordset_protos_v1.zip
└── nuance
    ├── nlu
    │   ├── v1
    │   │   ├── runtime.proto
    │   │   ├── result.proto
    │   │   ├── interpretation-common.proto
    │   │   ├── single-intent-interpretation.proto
    │   │   └── multi-intent-interpretation.proto
    │   │
    │   ├── wordset
    │   │   └── v1beta1
    │   │       └── wordset.proto
    │   └── common
    │      └── v1beta1
    │           ├── job.proto
    │           └── resource.proto
    │
    └── rpc
        ├── error_details.proto
        ├── status_code.proto
        └── status.proto

  4. Generate client stub files in your programming language from the proto files using gRPC protoc.

    For example, for Python:

    python -m grpc_tools.protoc --proto_path=./ --python_out=./ \
--grpc_python_out=./ nuance/nlu/v1/runtime.proto
python -m grpc_tools.protoc --proto_path=./ --python_out=./ \
nuance/nlu/v1/result.proto
python -m grpc_tools.protoc --proto_path=./ --python_out=./ \
nuance/nlu/v1/interpretation-common.proto
python -m grpc_tools.protoc --proto_path=./ --python_out=./ \
nuance/nlu/v1/single-intent-interpretation.proto
python -m grpc_tools.protoc --proto_path=./ --python_out=./ \
nuance/nlu/v1/multi-intent-interpretation.proto
python -m grpc_tools.protoc --proto_path=./ --python_out=./ \
--grpc_python_out=./ nuance/nlu/wordset/v1beta1/wordset.proto
python -m grpc_tools.protoc --proto_path=./ --python_out=./ \
nuance/nlu/common/v1beta1/job.proto
python -m grpc_tools.protoc --proto_path=./ --python_out=./ \
nuance/nlu/common/v1beta1/resource.proto
python -m grpc_tools.protoc --proto_path=./ --python_out=./ \
nuance/rpc/status.proto
python -m grpc_tools.protoc --proto_path=./ --python_out=./ \
nuance/rpc/status_code.proto
python -m grpc_tools.protoc --proto_path=./ --python_out=./ \
nuance/rpc/error_details.proto

    Depending on your programming language, the stubs may consist of one file or multiple files per proto file. These stub files contain the methods and fields from the proto files as implemented in your programming language. You will consult the stubs with the proto files.

  5. Write your client application, referencing the functions or classes in the client stub files. See Runtime app development for details.

  6. Run your client app to request text interpretation, optionally passing in NLU models and wordsets.

Final structure

The resulting files contain the information in the proto files in your programming language (in this example, Python):

├── Your client apps here
├── nuance
    ├── nlu
    │   ├── v1
    │   │   ├── runtime_pb2.py
    │   │   ├── runtime_pb2_grpc.py
    │   │   ├── runtime.proto
    │   │   ├── result_pb2.py
    │   │   ├── result.proto
    │   │   ├── interpretation-common_pb2.py
    │   │   ├── interpretation-common.proto
    │   │   ├── single-intent-interpretation_pb2.py
    │   │   ├── single-intent-interpretation.proto
    │   │   ├── multi-intent-interpretation_pb2.py
    │   │   └── multi-intent-interpretation.proto
    │   ├── wordset
    │   │   └── v1beta1
    │   │       ├── wordset_pb2.py
    │   │       ├── wordset_grpc_pb2.py
    │   │       └── wordset.proto
    │   └── common
    │       └── v1beta1
    │           ├── job_pb2.py
    │           ├── job.proto
    │           ├── resource_pb2.py
    │           └── resource.proto
    └── rpc
        ├── error_details_pb2.py
        ├── error_details.proto
        ├── status_code_pb2.py
        ├── status_code.proto
        ├── status_pb2.py
        └── status.proto

What’s next?

Once you have the proto files and optionally the client stubs, you are ready to develop and run client applications with the help of sample clients: