Bixby Developer Center

Vocabulary

Training in Bixby can be extended and enhanced by adding vocabulary. Vocabulary helps Bixby with the following:

• Associate words and phrases with primitive concepts
• Understand references to enumeration symbols
• Link words and phrases to sorting orders

Vocabulary for Primitives

Imagine a user who is looking to watch a movie tonight. Instead of simply saying, "What movies are playing tonight?", the user might ask, "What comedies are playing tonight?" Your capsule can handle this case by supplying vocabulary.

To do this, create a new file of type Vocabulary within your capsule (File > New File) in the language-specific resource folder the vocabulary belongs to (in this case, en). This will create a new *.vocab.bxb file under that folder.

You can then add a word/phrase list for the corresponding concept:

vocab (MovieGenre) {
  "comedies"
  "cartoons"
  "animation"
  "mysteries"
  "romances"
  "documentaries"
}

This list doesn't specify the only possible values for the MovieGenre concept. It provides hints that help Bixby's natural language understanding when the user's utterance lacks clear context.

Vocabulary for Enumerations

Vocabulary also allows you to add natural language words or phrases for symbols in enumerated primitive concepts (with some exceptions mentioned).

Suppose a weather capsule has symbols for weather that match a weather condition API:

enum (WeatherCondition) {
  symbol (wcClear)
  symbol (wcRain)
  symbol (wcSnow)
  symbol (wcHail)
  symbol (wcSleet)
  symbol (wcFog)
}

We might want to allow users to ask Bixby questions that directly refer to enumerated values:

"Is it going to rain tonight?"

Or:

"Is it going to be foggy tomorrow morning?"

To handle this, you must include a vocabulary file that specifies the symbols and their matching vocabulary terms:

vocab (WeatherCondition) {
  "wcClear" { "clear" "sunny" }
  "wcRain" { "rain" "raining" }
  "wcSnow" { "snow" "snowing" }
  "wcHail" { "hail" "hailing" }
  "wcSleet" { "sleet" }
  "wcFog" { "fog" "foggy" }
}

With this vocabulary in place, utterances related to the weather conditions can be trained, and Bixby can understand related terms such as "fog" and "foggy".

You can create vocabulary terms in this fashion for any closed type: enum, boolean, integer, and decimal.

Vocabulary for Sorting

If your capsule allows for changing the sort order of results, you can link vocabulary entries to sort keys. For example, if you are working on a hotel booking capsule, you could sort search results by price.

This example lists various ways a user could refer to expensive hotels (example.hotel.HighRate):

vocab (example.hotel.HighRate) {
  $sort-desc {
    "expensive"
    "extravagant"
    "fancier"
    "fancy"
    "high priced"
    "higher priced"
    "lavish"
    "luxurious"
    "luxury"
    "more costly"
    "more expensive"
    "most costly"
    "most expensive"
    "opulent"
    "pricey"
    ...
  }
}

Imported Vocabulary

When your capsule imports another capsule, it imports that capsule's vocabulary. For example, the viv.self library has a Field concept which is simply an enum of field names:

enum (Field) {
  symbol (firstName)
  symbol (lastName)
  symbol (structuredName)
  symbol (firstAndLastName)
  symbol (phoneInfo)
  symbol (emailInfo)
  symbol (addressInfo)
}

This is used internally by viv.self to allow users to refer to individual fields in the Profile model by using vocabulary associated with the symbols:

vocab (Field) {
  "FirstName" { "first name" "given name" }
  "LastName" { "last name" "family name" }
  "EmailInfo" { "email" "email address" }
  "PhoneInfo" { "phone number" "number" "phone" }
  "AddressInfo" { "address" }
}

This list doesn't define vocabulary for StructuredName or FirstAndLastName; this is to allow capsules that import viv.self to add their own vocabulary to cover those cases, as those might be domain-specific. The Space Resort capsule adds "name" as vocabulary for FirstAndLastName:

vocab (self.Field) {
  "FirstAndLastName" { "name" }
}

Vocabulary Classification

Vocabulary is considered closed if all the vocabulary belongs to a closed set of specified terms, and open otherwise.

For open matching, if you tag a word or phrase in a training example as a specific concept and it is not explicitly listed in the vocab, this matching is considered "out-of-vocabulary" (OOV).

Closed Types

The following types are considered "closed":

• Enum: Vocabulary is required and any tagging must match one of the values specified in the vocab.
• Boolean: Vocabulary is required and inherently set to true and false.
• Qualified: Vocabulary is not allowed, but qualified types must follow the specific Regex pattern.
• Numbers (Integer and Decimal): Vocabulary is required, but the platform provides these automatically for convenience.

Open Types

The following types are considered "open":

• Name: Vocabulary is allowed, but any word can be matched to this type regardless. (OOV matching is acceptable.)
• Text: Vocabulary is not allowed, so all matching is open. (OOV only.)

Limitations and Restrictions

This section discusses some of the limitations and restrictions for vocabulary.

Number of Entries Limitations

A capsule can have a maximum of 75,000 vocabulary entries total (across all concepts). Each concept can have up to 50,000 vocabulary entries.

Name Limitations

Bixby does not support pattern recognition in vocabulary. For example, let's assume you have a vocabulary list of MovieTitles and a vocabulary list of ActorNames. If your user has an utterance like "Show me Tom Cruise movies", unless you have "Tom Cruise" explicitly in your ActorNames vocab, Bixby won't be able to distinguish "Tom Cruise" as an actor or a movie title. You should keep adding more and better training examples. If that doesn't work, then it is probably not reasonable to have Bixby separate all those types for you. Instead, you should have a single type like SearchQuery and have your backend server handle doing the sorting and structured querying itself.

Boolean Case

The appropriate casing for boolean symbols in vocab is true and false.

Do use all lower case.

Don't do any of the following:

• True, tRuE, or any form of mixed case
• TRUE

Automatic Speech Recognition and Text-to-Speech

Automatic Speech Recognition (ASR) and Text-to-Speech (TTS) are useful Bixby capabilities for communicating with users. However, the natural language utterances you train and the vocabulary you add are only used in their specific capsule (although they might be used over time to help improve ASR and TTS performance).