Interpretation results: Entities
NLU results may also include individual words and phrases in the user’s input, mapped to entities and values. The results differ depending on the type of entity that is interpreted. Entity creation and annotation is done in Mix.nlu or in Mix.dialog, where the custom entity collection types include: List, Regex and rule-based, Relationship (isA and/or hasA), and Freeform.
Results may also include Nuance predefined entities.
List entity
A list collection type entity is an entity with a finite, enumerable list of named values. For example, FLAVOR is a list collection type entity that might contain values such as caramel, blueberry, strawberry, chocolate, and so on. BILL_TYPE might contain values such as Visa, American Express, Telephone, and Hydro.
Each value has one or more user literals, or ways that users might express this canonical value. Literals capture the reality that people will refer to the same thing in multiple different ways. For example, the FLAVOR entity matches sentences containing phrases such as:
- “I’d like to order a butterscotch cake” (butterscotch is a literal meaning “caramel”)
- “I want a dozen fudge cupcakes” (fudge is a literal meaning “chocolate”)
The BILL_TYPE entity matches sentences such as:
- “I want to pay my phone bill” (phone bill is a literal meaning Telephone)
- “Can I pay down my AMEX for this month” (AMEX is a literal meaning American Express)
List entity example
The FLAVOR and PRODUCT entities identify what the user wants to order:
"result": {
"literal": "I'd like to order a butterscotch cake",
"formatted_literal": "I'd like to order a butterscotch cake",
"interpretations": [{
"single_intent_interpretation": {
"intent": "PLACE_ORDER",
"confidence": 0.9917341470718384,
"origin": "STATISTICAL",
"entities": {
"FLAVOR": {
"entities": [{
"text_range": {
"start_index": 20,
"end_index": 32
},
"formatted_text_range": {
"start_index": 20,
"end_index": 32
},
"confidence": 0.9559149146080017,
"origin": "STATISTICAL",
"string_value": "caramel"
"literal": "caramel",
"formatted_literal": "caramel",
}
]
},
"PRODUCT": {
"entities": [{
"text_range": {
"start_index": 33,
"end_index": 37
},
"formatted_text_range": {
"start_index": 33,
"end_index": 37
},
"confidence": 0.9386003613471985,
"origin": "STATISTICAL",
"string_value": "cake",
"literal": "cake",
"formatted_literal": "cake"
}
]
}
}
}
}
]
}
Regex and rule-based entities
For other entities, the set of possible values might be too large to enumerate as a list, but there is a regular pattern to the possible values that can be captured either with a regex (regular expression) or a GrXML grammar.
A regular expression is good at capturing short alphanumeric patterns like card numbers and identification codes.
A GrXML grammar on the other hand works for multi-word patterns, especially when there are a few possible ways to say the same thing that can be systematically expressed, particularly in speech. For example, someone might say the number 125 in many different ways in different contexts: “one hundred twenty five,” “one hundred and twenty five,” “a hundred twenty five,” “a hundred and twenty five,” “one two five,” or “one twenty five.”
Nuance predefined entities are generally based on rule-based grammars.
Regex entity example
Here is an example of a result identifying an entity LOYALTY_CARD_NUM, representing a loyalty card account number consisting of six lowercase letters and four digits defined by the regular expression [a-z]{6}[0-9]{3}.
{
"result": {
"literal": "What is the balance on my account abcdef1234",
"interpretations": [
{
"singleIntentInterpretation": {
"intent": "CHECK_LOYALTY_ACCT",
"confidence": 1,
"origin": "GRAMMAR",
"entities": {
"LOYALTY_CARD_NUM": {
"entities": [
{
"textRange": {
"startIndex": 34,
"endIndex": 44
},
"confidence": 1,
"origin": "GRAMMAR",
"stringValue": "abcdef1234",
"literal": "foobar1234",
"formattedLiteral": "abcdef1234",
"formattedTextRange": {
"startIndex": 34,
"endIndex": 44
}
}
]
}
}
}
},
{
"singleIntentInterpretation": {
"intent": "ORDER_COFFEE",
"confidence": 1.594e-7,
"origin": "STATISTICAL"
}
}
],
"formattedLiteral": "What is the balance on my account abcdef1234"
}
}
Relationship entity
Relationship entities are isA and/or hasA entities:
-
An isA entity is a simple wrapping of another entity. For example, DATE is a relationship entity with an isA connection to nuance_CALENDARX, a Nuance predefined entity.
-
A hasA entity includes one or more entities. Many of the Nuance predefined entities (nuance_CALENDARX, nuance_AMOUNT, and so on) are hasA entities, meaning they are collections of other entities.
Relationship entity examples
Here are some examples of relationship entities in results.
DATE is an isA entity that wraps nuance_CALENDARX:
"result": {
"literal": "I want to pay my Visa bill on February twenty eight",
"formatted_literal": "I want to pay my Visa bill on February 28",
"interpretations": [{
"single_intent_interpretation": {
"intent": "PAY_BILL",
"confidence": 1.0,
"origin": "GRAMMAR",
"entities": {
"DATE": {
"entities": [{
"text_range": {
"start_index": 30,
"end_index": 51
},
"formatted_text_range": {
"start_index": 30,
"end_index": 41
},
"confidence": 1.0,
"origin": "GRAMMAR",
"entities": {
"nuance_CALENDARX": {
"entities": [{
"text_range": {
"start_index": 30,
"end_index": 51
},
"formatted_text_range": {
"start_index": 30,
"end_index": 41
},
"confidence": 1.0,
"origin": "GRAMMAR",
"struct_value": {
"nuance_CALENDAR": {
"nuance_DATE": {
"nuance_DATE_ABS": {
"nuance_MONTH": 2.0,
"nuance_DAY": 28.0
}
}
}
}
}
]
}
}
}
]
},
"BILL_TYPE": {
"entities": [{
"text_range": {
"start_index": 17,
"end_index": 21
},
"formatted_text_range": {
"start_index": 17,
"end_index": 21
},
"confidence": 1.0,
"origin": "GRAMMAR",
"string_value": "Visa",
"literal": "Visa",
"formatted_literal": "Visa"
}
]
}
}
}
}
]
}
nuance_CALENDARX is a hasA entity containing several date and time entities:
"result": {
"literal": "I want to pay my AMEX bill on February twenty eight",
"formatted_literal": "I want to pay my AMEX bill on February 28",
"interpretations": [{
"single_intent_interpretation": {
"intent": "PAY_BILL",
"confidence": 1.0,
"origin": "GRAMMAR",
"entities": {
"nuance_CALENDARX": {
"entities": [{
"text_range": {
"start_index": 30,
"end_index": 51
},
"formatted_text_range": {
"start_index": 30,
"end_index": 41
},
"confidence": 1.0,
"origin": "GRAMMAR",
"struct_value": {
"nuance_CALENDAR": {
"nuance_DATE": {
"nuance_DATE_ABS": {
"nuance_MONTH": 2.0,
"nuance_DAY": 28.0
}
}
}
}
}
]
},
"BILL_TYPE": {
"entities": [{
"text_range": {
"start_index": 17,
"end_index": 21
},
"formatted_text_range": {
"start_index": 17,
"end_index": 21
},
"confidence": 1.0,
"origin": "GRAMMAR",
"string_value": "American Express",
"literal": "AMEX",
"formatted_literal": "AMEX"
}
]
}
}
}
}
]
}
nuance_AMOUNT is another hasA entity containing multiple entities:
"result": {
"literal": "i'd like to pay six hundred and twenty five dollars on my hydro bill",
"formatted_literal": "i'd like to pay $625 on my hydro bill"
"interpretations": [{
"single_intent_interpretation": {
"intent": "PAY_BILL",
"confidence": 1.0,
"origin": "GRAMMAR",
"entities": {
"BILL_TYPE": {
"entities": [{
"text_range": {
"start_index": 58,
"end_index": 63
},
"formatted_text_range": {
"start_index": 27,
"end_index": 32
},
"confidence": 1.0,
"origin": "GRAMMAR",
"string_value": "Hydro"
"literal": "Hydro",
"formatted_literal": "Hydro"
}
]
},
"nuance_AMOUNT": {
"entities": [{
"text_range": {
"start_index": 16,
"end_index": 51
},
"formatted_text_range": {
"start_index": 16,
"end_index": 20
},
"confidence": 1.0,
"origin": "GRAMMAR",
"struct_value": {
"nuance_UNIT": "USD",
"nuance_NUMBER": 625.0
}
}
]
}
}
}
}
]
}
Freeform entity
A freeform entity has values that are only vaguely defined. Freeform entities can match lengthy user input, but they do not give precise information about the contents of the input.
Freeform entity examples
For example, MESSAGE is a freeform entity that occurs after keywords in user input such as:
- “Call Fred to say…”
- “Ask Jenny…”
- “Send a message to Chris.”
The MESSAGE entity matches anything prefixed with “Call someone” or “Ask someone” or “Send this message to someone.” An additional list entity, NAMES, captures the “someone.”
"result": {
"literal": "Ask Jenny When should we arrive",
"formatted_literal": "Ask Jenny When should we arrive",
"interpretations": [{
"single_intent_interpretation": {
"intent": "ASK_RANDOM",
"confidence": 1.0,
"origin": "GRAMMAR",
"entities": {
"NAMES": {
"entities": [{
"text_range": {
"start_index": 4,
"end_index": 9
},
"formatted_text_range": {
"start_index": 4,
"end_index": 9
},
"confidence": 1.0,
"origin": "GRAMMAR",
"string_value": "Jenny",
"literal": "Jenny",
"formatted_literal": "Jenny"
}
]
},
"MESSAGE": {
"entities": [{
"text_range": {
"start_index": 10,
"end_index": 31
},
"formatted_text_range": {
"start_index": 10,
"end_index": 31
},
"confidence": 1.0,
"origin": "GRAMMAR",
"string_value": "",
"literal": "when should we arrive",
"formatted_literal": "when should we arrive"
}
]
}
}
}
}
]
}
"result": {
"literal": "Send this message to Chris Can you pick me up from the five forty train",
"formatted_literal": "Send this message to Chris Can you pick me up from the 5:40 train",
"interpretations": [{
"single_intent_interpretation": {
"intent": "ASK_RANDOM",
"confidence": 1.0,
"origin": "GRAMMAR",
"entities": {
"MESSAGE": {
"entities": [{
"text_range": {
"start_index": 27,
"end_index": 65
},
"formatted_text_range": {
"start_index": 27,
"end_index": 59
},
"confidence": 1.0,
"origin": "GRAMMAR",
"string_value": "",
"literal": "can you pick me up from the five forty train",
"formatted_literal": "can you pick me up from the 5:40 train"
}
]
},
"NAMES": {
"entities": [{
"text_range": {
"start_index": 21,
"end_index": 26
},
"formatted_text_range": {
"start_index": 21,
"end_index": 26
},
"confidence": 1.0,
"origin": "GRAMMAR",
"string_value": "Chris",
"literal": "Chris",
"formatted_literal": "Chris"
}
]
}
}
}
}
]
}
Predefined entity
Nuance data packs include predefined entities for capturing common types of objects like numbers, amounts, dates, quantities, temperatures, and so on. The predefined entities supported will depend on the language.
Nuance predefined entities may appear in interpretation results if one of the intents defined in the NLU model is linked to a predefined entity or to a custom entity that has a relationship to a predefined entity.
Predefined entity example
Here is an example of a PREORDER intent capturing a target delivery time range using predefined entity nuance_CALENDARX.
{
"result": {
"literal": "I want to order a large coffee to deliver between 2 pm and 3 pm",
"interpretations": [
{
"singleIntentInterpretation": {
"intent": "PREORDER",
"confidence": 1,
"origin": "GRAMMAR",
"entities": {
"nuance_CALENDARX": {
"entities": [
{
"textRange": {
"startIndex": 42,
"endIndex": 63
},
"confidence": 1,
"origin": "GRAMMAR",
"structValue": {
"nuance_CALENDAR_RANGE": {
"nuance_CALENDAR_RANGE_END": {
"nuance_CALENDAR": {
"nuance_TIME": {
"nuance_TIME_ABS": {
"nuance_AMPM": "pm",
"nuance_HOUR": 3
}
}
}
},
"nuance_CALENDAR_RANGE_START": {
"nuance_CALENDAR": {
"nuance_TIME": {
"nuance_TIME_ABS": {
"nuance_AMPM": "pm",
"nuance_HOUR": 2
}
}
}
}
}
},
"literal": "between 2 pm and 3 pm",
"formattedLiteral": "between 2 pm and 3 pm",
"formattedTextRange": {
"startIndex": 42,
"endIndex": 63
}
}
]
}
}
}
},
{
"singleIntentInterpretation": {
"intent": "ORDER_COFFEE",
"confidence": 0.0001405441,
"origin": "STATISTICAL"
}
},
{
"singleIntentInterpretation": {
"intent": "CHECK_LOYALTY_ACCT",
"confidence": 0.0000285421,
"origin": "STATISTICAL"
}
}
],
"formattedLiteral": "I want to order a large coffee to deliver between 2 pm and 3 pm"
}
}
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.