co-nlu

warning

This documentation page is still being written.

define user hello
  "hi"
  "hello"
  "hey there!"

Introduction

Every message from the user needs to be interpreted by the bot in order to determine what the user meant and what to do next. The result of the interpretation is represented by the intent of the message and, optionally, by one or more entities. The intent is simply a category of user messages which is defined at design time. The entities represent specific bits of information that are included in the message e.g. names, locations, numbers, dates, etc.

define user INTENT_NAME
  entity ENTITY_NAME as ENTITY_TYPE

  "example simple utterance"
  "example utterance with $ENTITY_NAME"
  ...    

define user affirm
  "yes"
  "no"
  "sure" 
  "of course"

Entity types

The co-nlu module defines the following set of commonly used entity types:

Type	Description	Examples
number	An integer or float number expressed both using digits and letters	e.g. 2, 15, 250.2, thirty two
date	Represents a date	e.g. today, tomorrow, 12 June
boolean	Represents a boolean value	e.g. True, False

Regular Expressions

Entities that should match a regular expression can be defined as follows:

define user inform ping
  entity pin as regex:"\d\d\d\d"
  
  "$pin"
  "it is $pin"
  "PIN: $pin"

Lookup types

define lookup refund_option
  "account value"
  "gift card, gift"
  "card, credit card, debit card"
  "check, paper check"      

define user inform
  entity $refund_option as lookup:refund_option
  
  "$refund_option"
  "I want a $refund_option"

Inform

A special intent defined by this module is called inform and it should be used to model user messages where only the mentioned entities are important rather than the intent. For example, when the user is asked to choose between three options, we're interested just in the choice they make.

define user inform
  entity account_id as number

  "my account id is $account_id"

Entity values

define user inform $order_status="unknown"
  context "order_status" in $expected

  "i don't know"  
  "i dont think it has shipped"
  "I haven't received it yet, but my account doesn't show a shipping status."
  "It looks like it hasn't been shipped, but I don't see anything written anywhere"

Sub-intents

...

Contextual Examples

Certain expressions can mean different things when said in different contexts. To model this, you can specify the context for examples as shown below:

define user inform order_status out_for_delivery
  context "order_status" in $expected

  "out for delivery"
  "it's out for delivery"

In the example above, the expressions "out for delivery" and "it's out for delivery" are interpreted as inform order_status out_for_delivery when the context expression "order_status" in $expected is true. You can use any valid expression to define the context.

note

As an implementation detail, each expression will be translated into a separate feature that will be used by the machine learning model.

The general syntax for contextual examples is the following:

define user some_intent
  "non contextual example 1"
  "non contextula example 2"
  ...
  
  context CONTEXT_EXPRESSION_1
    "contextual expression 1.1"
    "contextual expression 1.2"
    ...
    
  context CONTEXT_EXPRESSION_2
    "contextual expression 2.1"
    "contextula expression 2.2"
    ...
  
  ...

Expected Intents

A frequent use for defining the context of an example is using the intents that are expected at that point in the conversation. For this, the contextual expression can be the user intents themselves as shown below:

define user inform pin_number
  entity pin_number as number

  "my PIN is $nhs_number"

  in the context of user inform pin_number
    "$pin_number"

In the example above, if we're in the context of expecting the user to provide a PIN i.e. there is a flow at a user inform pin_number location, then any number provided at that point will be interpreted as a PIN. In a different context, a number can be interpreted as an account ID, for example.

note

The in the context of syntax is just a more verbose and readable variant for simply saying context. Both can be used interchangeably.