co-flows
warning
This documentation page is still being written.
Introduction
A flow is a description of a sequence of events coupled with flow logic elements (logical conditions, branching, etc. )
define flow hello
# EVENT_1
# EVENT_2
# EVENT_3
...
Events
The general description of an event has the following format:
# General format
event <EVENT_NAME>
<ATTRIBUTE_1>: <VALUE_1>
...
# Example
event user_online
authenticated: False
After every event match, a context variable $event
{: .language-colang .highlight} is set.
User intents
The most important event in a flow is the user intent event and it has the following syntax:
# Intent specified by name
user hello
# Example utterance, which is matched to the corresponding intent
user "yes"
# Intent with a specific entity
user inform with $username
# Intent with a specific value for an entity
user i_want_to_eat with $food_type="italian"
Event object
Bot responses
The second most important event in a flow is the bot response event, and it has the following syntax:
# Raw response
bot "How are you?"
# Pre-defined response
bot how_are_you
define bot how_are_you
"How are you?"
# Raw response with context variables
bot "How are you, $user.name?"
# Pre-defined response with context variables
bot how_are_you(name=$user.name)
bot how_are_you with $name=$user.name
define bot how_are_you
"How are you, $name?"
For more details on pre-defined bot responses, go to the co-nlg
section.
Advanced Topics
Variables
The syntax for declaring variables:
# A local variable
local $x
var $x
local var $x
# The syntax for a global variable
global $x
global var $x
Interruption events
The actions a flow can perform are:
- advancing
- interrupting
- resuming
- aborting
Each action can be modeled at the flow level:
# When the flow is being resumed
flow resuming
# When the flow is being interrupted (we can reject the interruption, and keep it active)
flow interrupting
# When the flow is being aborted (we can reject the aborting)
flow aborting
We can also write interruption flows that match interruption events for other flows:
define interruption flow x:
...
flow resuming | interrupting | aborting
Resuming logic
TODO: explain
Sub-flows
Sub-flows are flows that can only be started by calling them directly from other flows. We can use them to model behaviour that is needed in multiple places, to avoid repetition. For example, in a customer support bot, an account validation flow could be needed both from a refund flow and a password reset flow:
define subflow validate_account
bot "Can I have your name or account ID, please?"
...
order_refund:
user "I need a refund"
bot "Sure, I can help with your refund"
do validate_account
...
password_reset:
user "I forgot my password"
bot "Sure, let's reset your password. I first need to validate your account."
do validate_account
...
Custom meta information
some_flow:
meta
allow_multiple: False
Meta flags can change the behaviour of a flow. The comprehensive list of flags is the following:
allow_multiple
: Whether multiple instances of the same flow are allowed to start in parallel. Defaults toFalse
.
Force interrupt labels
Force interrupt labels can be used to force the interruption of a flow at a specified point, on the next event. For example, this feature can be used to repeat a question that the user was asked, when resuming a flow:
define flow repeat_question
bot says something
# we're only interested in questions
if $utterance.text[-1] != "?"
done
$question_text = $utterance.text[0].lower() + $utterance.text[1:]
label force_interrupt
bot "So, $question_text"
# Below is currently a hack to make this flow aware of "user_intent" events
done
user says something
We can have multiple force_interrupt labels e.g. "force_interrupt_1", "force_interrupt_2", etc.
Auto-resume labels
TODO:
Parent-children relationship
The parent-child relationship is kept as "local" as possible by following the following rules:
- When a flow starts, the parents are the flows that advanced during the same iteration; if no flow advanced, then the flows that have been interrupted are considered the parents;
Flow specificity
TODO
Flow priority
When making the final decision, there are two elements that are taken into account: the priority of a flow and the specificity of a flow.
All flows have a default priority of 1. The priority of a flow can be set explicitly to another value either as part of the meta
block, or using the priority
shorthand:
some_flow:
meta
...
priority: 2
some_other_flow:
priority 2
Left to cover
- defining flows
define flow X
- basic branching
- ifs
- context variables
- calling other flows with
do
- inferences
- loops
- custom events matching with
event
- matching using
*
when resuming
when interrupted
when aborting
- flows specificity and priority