Expressions and Entities
An Expression is a pattern that defines user input. The Expression
Attribute is used to decorate an intent method with triggering user input expressions. Multiple Expressions on single intent method is supported. By default all expressions are case-insensitive.
Declaring an Expression
The following symbols are allowed in an expression. Any other symbol found in an expression gets truncated after normalization.
Type | Description |
---|---|
Alphanumeric | Combination of alphabetic and numeric characters. |
Hyphen(-) | The hyphen character is valid as it may be part of entity names. |
Dot(.) | The dot symbol is valid as it is part of system entity names. |
Ampersand(@) | Strictly used as prefix for entity names in template mode. |
Curly Braces ({}) | Strictly used for annotating entity values. |
Entities
Entities are pieces of information within a user message that a developer would want to extract. To learn how to create custom entity recognizers visit the Entity Recognizers section.
In Oscova expressions entity types (category to which an entity value belongs to) are specified using the format @EntityTypeName
.
In the code below the developer is explicitly specifying the sys.date
entity in the expression.
[Expression("Add a reminder for @sys.date")]
public void ReminderStart(Context context, Result result)
{
//Do something
}
Types of Expressions
There are 2 types of Expressions in Oscova.
1. Example
In example mode an expression is created by annotating entity values with curly braces. Annotation links words or phrases to specific entity types.
[Expression("{open} the garage door")]
[Expression("{close} the garage door")]
[Entity("command")]
Immediately after an example expression the developer must use the Entity
attribute to specify the entity type of the annotated value. If the entity type is not a system entity an internal entity recognizer gets created that recognizes the annotated value.
The order of the following Entity
attributes is used to determine the type of the annotated value. Wrong ordering will lead to ambiguity.
2. Template
This is the recommended mode of writing expressions. In template mode an expression is created by using entity type names instead of annotation of entity values. Entity type name must be prefixed with an ampersand @ symbol.
[Expression("@command the garage door")]
As @command
denotes a new entity type we'll need to add a recognizer for this type.
bot.CreateRecognizer("command", new[] {"open", "close"});
The above expression captures:
Open the garage door.
Close the garage door.
Entity types name must contain only alphanumeric characters separated by dot(.) or Hypen(-). Any other character type is invalid.
Note
The @
symbol is only used in Expressions, anywhere else you will only be specifying the entity type. For example, in EntityCollection
to get an entity of type sys.currency
, you'll use Entities.OfType("sys.currency");
Using System Entities
As Oscova comes with dozens of pre-built system entities. It is convenient to use them in Expressions instead of creating one from scratch. All system entity type names are available as constant members of the Sys
class.
For example you can specify the Sys.Date
type as shown below.
[Expression("Book an appointment for {tomorrow}")]
[Entity(Sys.Date)]
public void Appointment(Context context, Result result)
{
//Do Something.
}
Keywords
From version v4.5.1 OSCOVA supports declaration of keywords in expressions. Keywords are words or phrases that must exist in user input for matching just like values of entity types.
To create keywords simply use example {SomeWord}
syntax without specifying an entity type. In such a case, Oscova will internally create a Sys.Keyword.SomeWord
entity type and add the keywords as entry values. If keyword entity is being generated for a phrase with multiple words, then all space characters are replaced with an underscore (_
) symbol. For example, if a phrase like {chicken drumsticks}
is specified, then Oscova will create a Keyword entity type with the name Sys.Keyword.Chicken_Drumsticks
.
[Expression("{Start Engine}")]
public void StartEngine(Context context, Result result)
{
//Do Something.
}
In the above example, the expression {Start Engine} does not specify an entity type and hence is internally going to treated as a Sys.keyword.Start_Engine
entity type.
Note
Internally, keywords are treated exactly as any other required entity types.
If an expression uses keywords, then the expression MUST explicitly specify other required entity types by name instead of using example values. In short, expressions using keywords must be written in Template Mode.
For example:
INCORRECT
[Expression("{Start} at {500}")] // INCORRECT
[Entity("@sys.number")]
public void StartEngine(Context context, Result result)
{
//Do Something.
}
CORRECT
[Expression("{Start} at @sys.number")] // CORRECT
public void StartEngine(Context context, Result result)
{
//Do Something.
}
Adding a name to an Expression
OSCOVA provides a special Name
property on ExpressionAttribute
that enables developers to assign a contextually unique names to Expressions. Expression names have been introduced to remove code redundancy in situations where developers would manually check the recognized entities to differentiate between multiple expressions.
Example
[Expression("open @app", Name = "single-app")]
[Expression("open @app and @app", Name = "multi-app")]
public void OpenApp(Context context, Result result)
{
if (result.CurrentIntent.ExpressionName == "single-app")
{
//Do something here.
}
else if (result.CurrentIntent.ExpressionName == "multi-app")
{
//Do something here.
}
}
By convention Expression names must be unique for a given intent. Expressions on different intents may have similar names as they will be contextually unique to their respective intents.
To separate words in Expression names use the hyphen (-) character.
AutoEntity
Attribute
The AutoEntity
attribute tells Oscova to automatically extract entity types and create all possible combinations of expressions from the specified expression value.
[Expression("Add 1 and 2")]
[AutoEntity]
public void AddNum(Result result)
{
var numbers = result.Entities.AllOfType<NumberEntity>();
var num1 = numbers[0].Number;
var num2 = numbers[1].Number;
result.SendResponse($"Sum is {num1+num2}");
}
In the example code aboe the intent makes use of the AutoEntity
attribute and during training Oscova automatically tags the entity types for the value 1
and 2
with @sys.number
making the final expression as [Expression("Add @sys.number and @sys.number")]
Important
As it is not possible to know which entity the developer may use within the intent body, Oscova adds all possible combinations of expressions to the Intent. Hence it is recommended that this feature is used only when absolutely necessary.