Runtime gRPC API

The Runtime gRPC API contains methods for requesting interpretation of the meaning of text.

NLU as a Service provides these protocol buffer (.proto) files to define the Runtime NLU service for gRPC. These files contain the building blocks for the runtime of your NLU applications:

runtime.proto defines the main services and messages to request interpretation.
result.proto defines the result.
multi-intent-interpretation.proto defines multi-intent interpretations.
single-intent-interpretation.proto defines single-intent interpretations.
interpretation-common.proto defines additional items.

Once you have transformed the proto files into functions and classes in your programming language using gRPC tools, you can call these functions from your client application to start interpreting plain text or results from ASR as a Service.

See Runtime app development for a sample using Python. For other languages, consult the consult the gRPC and protocol buffer documentation.

Tip:

Try out this API using a Sample NLU runtime client that you can download and run.

Proto file structure

The proto files define an RPC service with an Interpret method containing an InterpretRequest and InterpretResponse. Details about each component are referenced by name within the proto file.

InterpretRequest structure

InterpretResponse structure

Runtime service

Runtime interpretation service. Use the Interpret method to request an interpretation.

Runtime service method
Name	Request Type	Response Type	Description
Interpret	InterpretRequest	InterpretResponse	Starts an interpretation request and returns a response.

InterpretRequest

The input to interpret, with parameters, model, extra resources, and client tags to customize the interpretation. Included in Runtime service.

InterpretRequest fields
Field	Type	Description
parameters	InterpretationParameters	Parameters for the interpretation.
model	ResourceReference	Mandatory. Semantic model to perform the interpretation.
resources	InterpretationResource	Repeated. Resources to customize the interpretation.
client_data	string,string	Key, value pairs to log.
user_id	string	Identifies a particular user within an application.
input	InterpretationInput	Mandatory. Input to interpret.

This message includes:

InterpretRequest
    parameters InterpretationParameters
        interpretation_result_type (EnumInterpretationResultType)
        interpretation_input_logging_mode (EnumInterpretationInputLoggingMode)
        post_processing_script_parameters
        max_interpretations
    model (ResourceReference)
    resources (InterpretationResource)
    client_data
    user_id
    input (InterpretationInput)

InterpretRequest example:

interpret_req = InterpretRequest(
    parameters=params,
    model=model,
    input=input)

InterpretationParameters

Optional parameters controlling the interpretation. Included in InterpretRequest.

InterpretationParameters fields
Field	Type	Description
interpretation_result_type	EnumInterpretation ResultType	Format of interpretation result. Default is SINGLE_INTENT.
interpretation_input_logging_mode	EnumInterpretation InputLoggingMode	Format for input in the call logs. Default is PLAINTEXT.
max_interpretations	uint32	Maximum interpretations for the result. Default is 0 for the NLU server’s configured setting.

This message includes:

InterpretRequest
  InterpretationParameters
    interpretation_result_type (EnumInterpretationResultType)
    interpretation_input_logging_mode (EnumInterpretationInputLoggingMode)
    max_interpretations

InterpretationParameters example:

params = InterpretationParameters(
    interpretation_result_type=EnumInterpretationResultType.SINGLE_INTENT,
    interpretation_input_logging_mode=EnumInterpretationInputLoggingMode.PLAINTEXT)

EnumInterpretationResultType

Format of interpretations result. Included in InterpretationParameters.

EnumInterpretationResultType options
Name	Number	Description
UNKNOWN	0	Default. Same as SINGLE_INTENT.
SINGLE_INTENT	1	Always return a single-intent interpretation.
MULTI_INTENT	2	Always return multi-intent interpretation.

EnumInterpretationInputLoggingMode

Format for input in the diagnostic logs. Included in InterpretationParameters.

EnumInterpretationInputLoggingMode options
Name	Number	Description
PLAINTEXT	0	Default. Log the literal text of the input.
SUPPRESSED	9	Input is replaced with “value suppressed.”

ResourceReference

Parameters to fetch an external resource. Included in InterpretRequest and InterpretationResource.

ResourceReference fields
Field	Type	Description
type	EnumResourceType	Resource type.
uri	string	URN for the resource.
request_timeout_ms	uint32	Time, in milliseconds, to wait for a response from the hosting server. Default is 0 for the NLU server’s configured setting.
headers	string,string	Map of headers to transmit to the server hosting the resource. May include max_age, max_stale, max_fresh, cookies.

This message includes:

InterpretRequest | InterpretationResource
  ResourceReference
    type (EnumResourceType)
    uri
    request_timeout_ms
    headers

ResourceReference example:

options.add_argument('--modelUrn', nargs="?",
                     help="NLU Model URN")
. . .
# Reference the model via the app config
model = ResourceReference(
    type=EnumResourceType.SEMANTIC_MODEL,
    uri=args.modelUrn)

EnumResourceType

Specifies a semantic model or wordset. Included in ResourceReference. Use the default, UNDEFINED_RESOURCE_TYPE, to determine the type from the content-type header returned by the resource’s server.

EnumResourceType options
Name	Number	Description
UNDEFINED_RESOURCE_TYPE	0	Default. Use the content-type header from the resource’s server to determine the type.
SEMANTIC_MODEL	1	A semantic model from Mix.nlu.
WORDSET	2	Currently unsupported. Use InterpretationResource–inline_wordset.
COMPILED_WORDSET	3	A compiled wordset associated to a specific semantic model.

InterpretationResource

A resource to customize the interpretation. Included in InterpretRequest.

InterpretationResource fields
Field	Type	Description
One of
external_reference	ResourceReference	External resource.
inline_wordset	string	Inline wordset, in JSON. See Wordsets.

This message includes:

InterpretRequest
  InterpretationResource
    external_reference (ResourceReference)
    inline_wordset

InterpretationInput

Input to interpret. Included in InterpretRequest. Use either text or the result from ASR as a Service.

InterpretationInput fields
Field	Type	Description
One of
text	string	Text input.
asr_result	nuance.asr.v1.RecognitionResponse	RecognitionResponse from ASR as a Service.

This message includes:

InterpretRequest
  InterpretationInput
    text
    or
    asr_result

InterpretationInput example:

def parse_args():
    options.add_argument("--textInput", metavar="file", nargs="?",
        help="Text to perform interpretation on")
. . .
input = InterpretationInput(
    text=args.textInput)

InterpretResponse

The interpretation result. Included in Runtime service.

InterpretationResponse fields
Field	Type	Description
status	Status	Whether the request was successful. A 200 code means success, while other values indicate an error.
result	InterpretResult	The result of the interpretation.

This message includes:

InterpretResponse
  status (Status)
  result (InterpretResult)
    literal
    interpretations (Interpretation)

Status

A Status message indicates either that the request was successful or reports errors that occurred during the request. Included in InterpretResponse.

Status fields
Field	Type	Description
code	uint32	HTTP status code . A 200 code means success, with or without warnings while other values indicate an error.
message	string	Brief text meaning of the status code.
details	string	In the case of an error or warning, includes a longer description of the nature of the issue.

InterpretResult

Result of interpretation. Contains the input literal and one or more interpretations. Included in InterpretResponse.

For examples, see Interpretation results: Intents and Interpretation results: Entities.

InterpretResult fields
Field	Type	Description
literal	string	Input used for interpretation. For text input, this is always the raw input text. For input coming from ASR as a Service results, this gives a concatenation of the audio tokens, separated by spaces, in minimally formatted text format. For example, “Pay five hundred dollars.”
formatted_literal	string	The formatted input literal. For input coming from ASR as a Service results, this is the text representation of the ASR result, but with formatted text. For example, “Pay $500.” When the input for interpretation is text, this is the same as literal.
interpretations	Interpretation	Repeated. Candidate interpretations of the input.
sensitive	bool	Indicates whether the literal contains entities flagged as sensitive. Sensitive entities are masked in call logs.

This message includes:

InterpretResponse
  InterpretResult
    literal
    formatted_literal
    interpretations (Interpretation)
    sensitive

Interpretation

Candidate interpretation of the input. Included in InterpretResult.

The interpret request specifies the type of interpretation: either single-intent or multi-intent (see interpretation_result_type in InterpretationParameters). Multi-intent interpretation requires a semantic model that is enabled for multi-intent (not currently supported in Mix.nlu).

See Interpretation results: Intents for details and more examples.

Interpretation fields
Field	Type	Description
One of
single_intent_interpretation	SingleIntentInterpretation	The result contains one intent.
multi_intent_interpretation	MultiIntentInterpretation	The result contains multiple intents. This choice requires a multi-intent semantic model, which is not currently supported in Nuance-hosted NLUaaS.

This message includes:

InterpretResult
  Interpretation
    single_intent_interpretation (SingleIntentInterpretation)
    or
    multi_intent_interpretation (MultiIntentInterpretation)

SingleIntentInterpretation

Single-intent interpretation results. Included in Interpretation. Theses results include one or more alternative intents, complete with entities if they occur in the text. Each intent is shown with a confidence score and indicates whether the match was done from a grammar file or an SSM (statistical) file.

SingleIntentInterpretation fields
Field	Type	Description
intent	string	Intent name as specified in the semantic model.
confidence	float	Confidence score (between 0.0 and 1.0 inclusive). The higher the score, the likelier the detected intent is correct.
origin	EnumOrigin	How the intent was detected.
entities	string,SingleIntentEntityList	Map of entity names to lists of entities: key, entity list.

This message includes:

InterpretResponse
  InterpretResult
    SingleIntentInterpretation
      intent
      confidence
      origin (EnumOrigin)
      entities (key,SingleIntentEntityList)
        entity (SingleIntentEntity)

In this example, single intent interpretation returns the most likely intent, PLACE_ORDER, and an alternative, PAY_BILL, with a much lower confidence level:

  "result": {
    "literal": "I'd like to place an order",
    "formatted_literal": "I'd like to place an order",
    "interpretations": [
      {
        "single_intent_interpretation": {
          "intent": "PLACE_ORDER",
          "confidence": 0.9941431283950806,
          "origin": "STATISTICAL"
        }
      },
      {
        "single_intent_interpretation": {
          "intent": "PAY_BILL",
          "confidence": 0.0019808802753686905,
          "origin": "STATISTICAL"
        }
      }
    ]
  }
}

EnumOrigin

Origin of an intent or entity. Included in SingleIntentInterpretation, SingleIntentEntity, IntentNode, and EntityNode.

EnumOrigin
Name	Number	Description
UNKNOWN	0
GRAMMAR	1	Determined from an exact match with a grammar file in the model.
STATISTICAL	2	Determined statistically from the SSM file in the model.

SingleIntentEntityList

List of entities. Included in SingleIntentInterpretation.

SingleIntentEntityList fields
Field	Type	Description
entities	SingleIntentEntity	Repeated. An entity match in the intent, for single-intent interpretation.

SingleIntentEntity

Entity in the intent. Included in SingleIntentEntityList.

SingleIntentEntity fields
Field	Type	Description
text_range	TextRange	Range of literal text for which this entity applies.
formatted_text_range	TextRange	Range of the formatted literal text for which this entity applies. When the input for interpretation comes from an ASR result, this may be absent if there is misalignment.
confidence	float	Confidence score between 0.0 and 1.0 inclusive. The higher the score, the likelier the entity detection is correct.
origin	EnumOrigin	How the entity was detected.
entities	string, SingleIntentEntityList	For hierarchical entities, the child entities of the entity: key, entity list.
One of
string_value	string	The canonical value as a string.
struct_value	google.protobuf. Struct	The entity value as an object. This object may be directly converted to a JSON representation.
literal	string	The input literal associated with this entity. For text input, this is the raw input text. For input coming from ASR results, this is in minimally formatted text format.
formatted_literal	string	The formatted input literal associated with the entity. When the input for interpretation is text, this is the same as literal.
sensitive	bool	Indicates whether the entity has been flagged as sensitive. Sensitive entities are masked in call logs.
audio_range	AudioRange	Range of audio input this operator applies to. Available only when interpreting a recognition result from ASR as a Service.

This message includes:

InterpretResponse
  InterpretResult
    SingleIntentInterpretation
      SingleIntentEntityList
        SingleIntentEntity
          text_range (TextRange)
          formatted_text_range (TextRange)
          confidence
          origin (EnumOrigin)
          entities (key, SingleIntentEntityList)
          string_value
          struct_value
          literal
          formatted_literal
          sensitive
          audio_range (AudioRange)

In this example, single intent interpretation returns the single intent, PLACE_ORDER, with entity FLAVOR: strawberry and PRODUCT: cheesecake

  "result": {
    "literal": "I want to order a strawberry cheesecake",
    "formatted_literal": "I want to order a strawberry cheesecake",
    "interpretations": [
      {
        "single_intent_interpretation": {
          "intent": "PLACE_ORDER",
          "confidence": 0.9987062215805054,
          "origin": "STATISTICAL",
          "entities": {
            "FLAVOR": {
              "entities": [
                {
                  "text_range": {
                    "start_index": 18,
                    "end_index": 28
                  },
                  "formatted_text_range": {
                    "start_index": 18,
                    "end_index": 28
                  },
                  "confidence": 0.9648909568786621,
                  "origin": "STATISTICAL",
                  "string_value": "strawberry",
                  "literal": "strawberry",
                  "formatted_literal": "strawberry"
                }
              ]
            },
            "PRODUCT": {
              "entities": [
                {
                  "text_range": {
                    "start_index": 29,
                    "end_index": 39
                  },
                  "formatted_text_range": {
                    "start_index": 29,
                    "end_index": 39
                  },
                  "confidence": 0.9585300087928772,
                  "origin": "STATISTICAL",
                  "string_value": "cheesecake",
                  "literal": "cheesecake",
                  "formatted_literal": "cheesecake",
                }
              ]
            }
          }
        }
      }
    ]
  }
}

TextRange

Range of text in the input literal. Included in SingleIntentEntity, OperatorNode, IntentNode, and EntityNode.

TextRange fields
Field	Type	Description
start_index	uint32	Inclusive, 0-based character position, in relation to literal text.
end_index	uint32	Exclusive, 0-based character position, in relation to literal text.

AudioRange

Range of time in the input audio. Included in SingleIntentEntity, OperatorNode, IntentNode, and EntityNode. Available only when interpreting a recognition result from ASR as a Service.

AudioRange fields
Field	Type	Description
start_time_ms	uint32	Inclusive start time in milliseconds.
end_time_ms	uint32	Exclusive end time in milliseconds.

MultiIntentInterpretation

Multi-intent interpretation. Contains a tree of nodes representing the detected operators, intents, and entities and their associations. Included in Interpretation.

Multi-intent interpretation may be requested without error, but it is not currently supported as it requires a multi-intent semantic model, not yet available in Mix. When requesting multi-intent interpretation against a single-intent model, the results contain the same information as a single-intent interpretation, but formatted slightly differently: the root of the multi-intent interpretation contains the intent.

MultiIntentInterpretation fields
Field	Type	Description
root	InterpretationNode	Root node of the interpretation tree. Can be either OperatorNode or IntentNode.

This message includes:

InterpretResponse
  InterpretResult
    MultiIntentInterpretation
      root (InterpretationNode)

In this example, multi-intent interpretation against a standard semantic model returns just one intent for each candidate in the “root” object:

  "result": {
    "literal": "Price list and place order",
    "formatted_literal": "Price list and place order",
    "interpretations": [
      {
        "multi_intent_intepretation": {
          "root": {
            "intent": {
              "name": "GET_INFO",
              "text_range": {
                "end_index": 26
              },
              "formatted_text_range": {
                "end_index": 26
              },
              "confidence": 0.8738054037094116,
              "origin": "STATISTICAL"
            }
          }
        }
      },
      {
        "multi_intent_intepretation": {
          "root": {
            "intent": {
              "name": "PLACE_ORDER",
              "text_range": {
                "end_index": 26
              },
              "formatted_text_range": {
                "end_index": 26
              },
              "confidence": 0.08993412554264069,
              "origin": "STATISTICAL"
            }
          }
        }
      }
    ]
  }

InterpretationNode

Node in the interpretation tree. Included in MultiIntentInterpretation.

InterpretationNode fields
Field	Type	Description
One of
operator	OperatorNode	The relationship of the intents or entities.
intent	IntentNode	The intents detected in the user input.
entity	EntityNode	The entities in the intent.

This message includes:

InterpretResponse
  InterpretResult
    MultiIntentInterpretation
      InterpretationNode
        operator (OperatorNode)
        intent (IntentNode)
        entity (EntityNode)

OperatorNode

Logical operator node. Included in InterpretationNode.

OperatorNode fields
Field	Type	Description
operator	EnumOperator	Type of operator.
text_range	TextRange	Range of the literal text this operator applies to.
formatted_text_range	TextRange	Range of the formatted literal text this operator applies to. When the input for interpretation is an ASR result, this may be absent if there is misalignment.
children	InterpretationNode	Repeated. Child nodes for this operator. An operator node always has children.
literal	string	The input literal associated with this operator. For text input, this is the raw input text. For input coming from ASR as a Service results, this is in minimally formatted text format.
formatted_literal	string	The formatted input literal associated with this operator. When the input for interpretation is text, this is the same as literal.
sensitive	bool	Indicates whether a child entity of this operator node has been flagged as sensitive. Sensitive entities are masked in call logs.
audio_range	AudioRange	Range of audio input this operator applies to. Available only when interpreting a recognition result from ASR as a Service.

This message includes:

InterpretResponse
  InterpretResult
    MultiIntentInterpretation
      InterpretationNode
        OperatorNode
          operator (EnumOperator)
          text_range (TextRange)
          formatted_text_range (TextRange)
          children (InterpretationNode)
          literal
          formatted_literal
          sensitive
          audio_range (AudioRange)

EnumOperator

Logical operator type, AND, OR, or NOT. Included in OperatorNode.

EnumOperator options
Name	Number	Description
AND	0	The following item is an additional intent or entity.
OR	1	The following item is an alternative intent or entity.
NOT	2	The following item is not detected.

IntentNode

Node representing an intent. Included in InterpretationNode.

IntentNode fields
Field	Type	Description
name	string	Intent name as specified in the semantic model.
text_range	TextRange	Range of literal text this intent applies to.
formatted_text_range	TextRange	Range of the formatted literal text this operator applies to. When the input for interpretation is an ASR result, this may be absent if there is misalignment.
confidence	float	Confidence score between 0.0 and 1.0 inclusive. The higher the score, the likelier the detected intent is correct.
origin	EnumOrigin	How the intent was detected.
children	InterpretationNode	Repeated. Child nodes for this intent. An intent node has zero or more child nodes.
literal	string	The input literal associated with this intent. For text input, this is the raw input text. For input coming from ASR as a Service results, this is in minimally formatted text format.
formatted_literal	string	The formatted input literal associated with this intent. When the input for interpretation is text, this is the same as literal.
sensitive	bool	Indicates whether a child entity of this intent node has been flagged as sensitive. Sensitive entities are masked in call logs.
audio_range	AudioRange	Range of audio input this operator applies to. Available only when interpreting a recognition result from ASR as a Service.

This message includes:

InterpretResponse
  InterpretResult
    MultiIntentInterpretation
      InterpretationNode
        IntentNode
          name
          text_range (TextRange)
          formatted_text_range (TextRange)
          confidence
          origin (EnumOrigin)
          children (InterpretationNode)
          literal
          formatted_literal
          sensitive
          audio_range (AudioRange)

EntityNode

Node representing an entity. Included in InterpretationNode.

EntityNode fields
Field	Type	Description
name	string	Entity name as specified in the semantic model.
text_range	TextRange	Range of literal text this intent applies to.
formatted_text_range	TextRange	Range of the formatted literal text this operator applies to. When the input for interpretation is an ASR result, this may be absent if there is misalignment.
confidence	float	Confidence score between 0.0 and 1.0 inclusive. The higher the score, the likelier the detected entity is correct.
origin	EnumOrigin	How the intent was detected.
children	InterpretationNode	Repeated. Child nodes for this entity. A hierarchical entity node can have child entity and operator nodes. Entity nodes currently never have intent nodes as children.
One of
string_value	string	The value of the entity as specified in the semantic model.
struct_value	google. protobuf.Struct	Structured data, ready to convert to a JSON representation.
literal	string	The input literal associated with this entity. For text input, this is the raw input text. For input coming from ASR results, this is in minimally formatted text format.
formatted_literal	string	The formatted input literal associated with this entity. When the input for interpretation is text, this is the same as literal.
sensitive	bool	Indicates whether the entity has been flagged as sensitive. Sensitive entities are masked in call logs.
audio_range	AudioRange	Range of audio input this operator applies to. Available only when interpreting a recognition result from ASR as a Service.

This message includes:

InterpretResponse
  InterpretResult
    MultiIntentInterpretation
      InterpretationNode
        EntityNode
          name
          text_range (TextRange)
          formatted_text_range (TextRange)
          confidence
          origin (EnumOrigin)
          children (InterpretationNode)
          string_value
          struct_value
          literal
          formatted_literal
          sensitive
          audio_range (AudioRange)

Scalar value types

The data types in the proto files are mapped to equivalent types in the generated client stub files.

Scalar data types
Proto	Notes	C++	Java	Python
double		double	double	float
float		float	float	float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers. If your field is likely to have negative values, use sint32 instead.	int32	int	int
int64	Uses variable-length encoding. Inefficient for encoding negative numbers. If your field is likely to have negative values, use sint64 instead.	int64	long	int/long
uint32	Uses variable-length encoding.	uint32	int	int/long
uint64	Uses variable-length encoding.	uint64	long	int/long
sint32	Uses variable-length encoding. Signed int value. These encode negative numbers more efficiently than regular int32s.	int32	int	int
sint64	Uses variable-length encoding. Signed int value. These encode negative numbers more efficiently than regular int64s.	int64	long	int/long
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long
sfixed32	Always four bytes.	int32	int	int
sfixed64	Always eight bytes.	int64	long	int/long
bool		bool	boolean	boolean
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

Runtime gRPC API

Tip:

Proto file structure

Runtime service

InterpretRequest

InterpretationParameters

EnumInterpretationResultType

EnumInterpretationInputLoggingMode

ResourceReference

EnumResourceType

InterpretationResource

InterpretationInput

InterpretResponse

Status

InterpretResult

Interpretation

SingleIntentInterpretation

EnumOrigin

SingleIntentEntityList

SingleIntentEntity

TextRange

AudioRange

MultiIntentInterpretation

InterpretationNode

OperatorNode

EnumOperator

IntentNode

EntityNode

Scalar value types

Related topics

Feedback