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 to False.

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:

1. 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