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 {Keyword1 Keyword2} syntax without specifying an entity type. In such a case, Oscova will internally create a Sys.Keyword-<UniqueID> entity type and add the keywords as entry values.

[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-<UniqueID> 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.