NB:
La version française de la documentation Athena n’est pas encore disponible
Si vous le souhaitez, vous pouvez consulter la version en anglais disponible si dessous :
Definition
A pattern defines what user input is expected to trigger a scenario or sub scenario.
Two kind of these patterns exists, the difference relies on their election system :
Special patterns also exists and will be explained later :
Keyword Matching
This pattern has the following syntax :
? HELLO
It always starts with a simple question mark and followed by a space.
The matching system is quite simple but you need to read the rules to understand it.
Keyword rules
- A keyword is composed of letters
- No special chars allowed
- No numbers allowed
- A keyword must be at least two characters long.
Preprocessing
The matching system before comparing user input and keywords preprocess the words:
- All numbers and special chars are removed
- All accentuated letters are rewritten with non accentuated characters
- One letter word are remove.
- Input is upper cased
Keyword matching
The matching system compare keywords with their string equality, phonex equality and metaphone equality. This can correct some typos in user messages, or match two different words but close enough by their pronunciation.
Keyword order
Order is primordial in patterns :
? HELLO JOHN cannot match with ‘john hello’
Election system
Given those scenarios :
? HELLO
- Hello you
? HELLO JOHN
- Hello, my name is John
? BYE
- goodbye
Here are some examples of rules applied :
- ‘hello’ -> first scenario
- ‘hello john’ -> second scenario
- ‘hello mark’ -> first scenario
- ‘bye’ -> goodbye
- ‘hello bye’ -> default (this is pattern conflict)
Pattern expansion
Because it can be a consuming task to define all possible patterns for a scenario, Athena includes pattern expansion.
This works only for keywords system.
Inline expansion
? (HELLO|HI) JOHN
- Hello
Equivalent :
? HELLO JOHN
? HI JOHN
- Hello
Optional expansion
If no words is defined after the last pipe, pattern without the expansion will be generated. As well for unique word in curly brackets
? (HELLO|HI) (JOHN)
- Hello
? (GOODBYE|BYE|) JOHN
- Hello
Equivalent :
? HELLO JOHN
? HI JOHN
? HELLO
? HI
- Hello
? GOODBYE JOHN
? BYE JOHN
? JOHN
- Hello
Expansion factor
+ HELLO(HELLO|HI)
? __HELLO JOHN
- Hi, i'm john
? __HELLO MARY
- HI, i'm mary
Equivalent :
? HELLO JOHN
? HI JOHN
- Hi, i'm john
? HELLO MARY
? HI MARY
- Hi, i'm mary
An expansion factor is defined by a plus symbol followed by a space and an identifier, and an inline expansion.
To call the expansion factor, precede the identifier by two underscores.
Classifier
This pattern has the following syntax :
?! hello
It always starts with a simple question mark, followed by a interrogation point and a space.
The matching system is based on a classification system which is not part of Athena.
Election system
The classification system process a sentence and returns to athena the list of intent score pair (for each intent defined in the application, a score is attributed to it)
Given those scenarios :
?! hello
- Hello you
?! bye
- goodbye
Athena will elect the scenario with the highest score. The minimum threshold of an elected score is 0.5 (the system is 50% sure that it is this intent)
Notes : you can override the minimum threshold, refer to the classification configuration.
Combined
You can use both Keywords Matching and Classification system in the same script and scenario :
?! hello
? HELLO
- Hello you
? HELLO JOHN
- Hello, my name is John
?! bye
? BYE
- goodbye
If 100% words of user input match a keyword matching pattern, the classification system is not solicited since it’s a perfect match. What’s not a perfect match regarding the scenario :
- hello mark (mark is an extra word)
- Hello mister john (john is an extra word)
If not 100% percent, classification system takes the lead :
- Process the sentence to get scores over minimum threshold
- If valid scores (over minimum threshold), find a scenario with the intent name
If no valid scores, or no scenario with intent name, the keyword matching system takes the lead.
Special Patterns
Pattern condition
A scenario or sub scenario can be conditionally activated.
The syntax is :
?: @Time.BeforeNoon()
? HELLO
- Good morning
?: @Time.AfterNoon()
? HELLO
- Good afternoon
It always starts with a simple question mark, followed by colon and a space.
The condition is expressed using an addin, or with code style syntax.
This allows in this example to elect a different scenario based on time of day.
Patterns fallbacks
Default
A sub scenario can defines a default behavior if there is no match between user input and sub scenarios and root scenarios
? HELLO
- How are you ?
? FINE
- I'm glad
? BAD
- Do you want a hug ?
??
- I hope you're fine
? BYE
- goodbye
Syntax is two interrogation mark
In this case, here is the behavior expected :
- hello -> How are you ? -> Fine -> I’m glad
- hello -> How are you ? -> Morose -> I hope you’re fine
- hello -> How are you ? -> Sorry i need to go, bye -> goodbye
Default forced
A sub scenario can defines a default forced behavior if there is no match between user input and sub scenarios.
? HELLO
- How are you ?
? FINE
- I'm glad
? BAD
- Do you want a hug ?
???
- I hope you're fine
? BYE
- goodbye
Syntax is three interrogation mark
In this case, here is the behavior expected :
- hello -> How are you ? -> Fine -> I’m glad
- hello -> How are you ? -> Morose -> I hope you’re fine
- hello -> How are you ? -> Sorry i need to go, bye -> I hope you’re fine
Notes on defaults
You can’t combine both default and default forced patterns.
Pattern parameter
A scenario can have pattern parameters, which will be extracted by extraction systems.
? HELLO
- Hello
? HELLO
?% firstname
- Hello %firstname
The syntax is a question mark followed by a percent and a space. The last particle is the identifier of entity that needs to be extracted.
In this case, we assume that the firstname extractor extract common first names. Here is the behavior expected :
- Hello -> Hello
- Hello John -> Hello John
- Hello there -> Hello
The syntax also keeps in memory the extracted values during whole scenario. Wich means that it will only be cleared when user reach a root scenario :
? HELLO
- Hello
? HELLO
?% firstname
- Hello %firstname, how are you ?
? (FINE|GOOD)
- Glad to hear that %firstname
? BAD
- What's wrong %firstname
See in that exemple we can use %firsname in the sub scenario, we can do it with calllabel as well :
? HELLO
- Hello
? HELLO
?% firstname
- Hello %firstname, how are you ?
? (FINE|GOOD)
- {GOOD}
? BAD
- {BAD}
[GOOD]
- Glad to hear that %firstname
[BAD]
- What's wrong %firstname
This notation allows you to omit calllabel parameters, but you must take care about callers ! The question ou should ask yourself is : “Have they already extracted %firstname ?”
Technical Information
Extracted parameters use AthenaContext data as storage. Which means you can add extracted parameters using an addin.
Given the following addin :
[AthenaAddin(Name = "extract")]
public class ExtractAddin : AthenaAddin
{
public string extract(string parameterName)
{
AthenaContext.Current.AddData(parameterName, "mathias");
return NOTHING;
}
}
You can use it like this in Athena :
? HELLO
-: @extract.extract("firstname")
- Hello %firstname, how are you ?
Existing parameter extractors
Currently you must request xBrain to implement a new one.
How to create your own parameter extractor
Currently you must request xBrain to implement a new one.
Pattern triggers
Those patterns are used to trigger a specific sub scenario using a specific command:
? BUTTON CHOICE
- Choose one option :[list][*] [button title="yes"]yes[/button][*] [button title="no"]no[/button][/list]
?! yes
?# yes
- You choose yes
?! no
?# no
- You choose no
In this case, the sub scenario accepts text responses, and click on yes/no buttons.
Click on button send a custom message, that triggers the specific pattern.