Flow
A flow consists of following definitions:
intents : Dict<Intent>
- Intent definitionsstates : Dict<State>
- State definitionsactions : Dict<Action>
- Action definitionsmethods : Dict<string>
- Flow-specific method definitions
Additionally a flow can be set as following:
active : boolean
You can enable/disable a flow by setting the active field of a flowvolatile : boolean
Set to true will close the flow whenever it goes outside the flowexpire : number
Will set flow to expire after specified number of miliseconds
Intents
Intent can be defined as following:
intents:
<name>: <Intent>
The intent description contains following fields:
type : "text" | "command" | "data"
Type filter to define type of the message to be associated with this intentcondition : string | string[]
Condition filter to rule out certain intents to be selectedclassifier : Classifier | Classifier[]
Classifier definitionattributes : Dict<Attribute>
Attributes / slotfilling associated with the intentfallback : boolean
Define intent as fallback intent.priority : number
Set priority of an intent for the selection processinitial : boolean
Set whether intent can be triggered only in current flow or from other flow as well
Condition
Condition is every valid javascript expression returning a boolean. Avaliable variables are:
type : string
- Message Typepayload : JsonObject
- Message Payloadcontent : string
- Message Contentcontext : JsonObject
- Flow Contextdata : JsonObject
- Session Dataconfig : JsonObject
- Bot Config
Example:
condition: type == 'text' && content == 'hello' && !context.completed
Classifier
Classifier consists of following fields:
nlu : string
- Name of defined NLU or NLU-typehint : string
- Prepend message with a text fragmentmatch : string
- Match result of the classifier with a specific stringoptions : JsonObject
- Override NLU optionsprocess : method | method[]
- Postprocess intent using methods
Example:
classifier:
nlu: topicClassifier
match: food
options:
lowerCase: true
threshold: 0.8
Example Multiple Classifiers:
classifier:
- nlu: topicClassifier
match: food
- nlu: keywordClassifier
match: food
Example mapping label using dict:
classifier:
nlu: topicClassifier
match: food
dict:
food: [food_a, food_b], # group multiple classes to one
test: testing # change label
Attributes
Attribute consist of following fields:
nlu : string
- Name of defined NLU or NLU-typehint : string
- Prepend message with a text fragmentpath : string
- Result path to be takenoptions : JsonObject
- Override NLU optionsprocess : method | method[]
- Postprocess intent using methods
Example:
attributes:
city:
nlu: genericNER
path: LOCATION
options:
threshold: 0.6
process:
- filterCity
- capitalize
Example normalizing using dict:
attributes:
city:
nlu: genericNER
path: location
options:
threshold: 0.6
dict:
jakarta: [jkt, jekardah, jakarta]
bandung: [bdg, bandung]
default: invalid
States
States can be defined as following:
states:
<name>: <State>
The state description contains following fields:
initial : boolean
Specify initial stateaction : string | StateAction | StateAction[]
Specify action to be executedend : boolean
Specify end statetransitions : Dict<Transition|string>
Specify transitionsfloat : Transition
Specify floating transitionenter : Mapping | method
Specify mapping or method to be executed when state is enteredtransit : Mapping | method
Specify mapping or method to be executed when transition is startedexit : Mapping | method
Specify mapping or method to be executed when state is exited
Mapping
Mapping is a procedure to update context / data. available variables are:
attributes : JsonObject
attributes that is captured by intentintent : string
captured intentcontent : string
message contentpayload : JsonObject
message payloadcontext : JsonObject
Flow contextdata : JsonObject
Session data
Example:
enter:
data.name: attributes.name
context.count: (context.count || 0)++
Example using method:
enter: someMapping
method definition:
methods:
someMapping(ctx): > # {intent, attributes, content, payload, data, context}
ctx.data.name = ctx.attributes.name;
ctx.context.count++;
return ctx;
State Actions
Action can be defined as a single action or multiple actions. The state action definition contains following fields:
name : string
- name of defined action or action typecondition : string
- condition filteroptions : JsonObject
- override action options
Example:
action:
name: reply
options:
text: 'hi!'
Example multiple actions:
action:
- name: reply
condition: context.mood = 'good'
options:
text: 'hi $(data.name)!'
- name: reply
condition: context.mood = 'bad'
options:
text: 'apaan sih kamu!'
You can simplify state actions (if you only have 1 action in some states) :
action: someAction
Transition
Transition define condition that leads to moving from one state to the other state. A transition is defined as following:
transitions:
<destination>: <Transition>
Field definition:
condition : string
- Condition that trigger the transitionpriority : number
- Priority for transition selectionfallback : boolean
- Define fallback when no other transition matchesmapping : Mapping | method
- Define mapping or method that is triggered during this transition
Example:
transitions:
askDob:
condition: "intent == 'yes' && !context.personGender && context.verifyGender"
mapping:
context.personGender: 'context.verifyGender'
context.verifyGender: 'null'
You can simplify transitions definition :
transitions
askDob: "intent == 'yes' && !context.personGender"
Floating State
Normally it is tedious if we have to define a transition to a state that is available in every state. e.g. Cancel state. To mitigate this we can define a floating transition. The system will automatically attach this transition in every state.
float: <Transition>
Events
We can define a mapping or method that is triggered during these events:
enter
- this event is triggered when entering a statetransit
- this event is triggered before transition processexit
- this event is triggered after transition process
Meta Context
Additional meta context accessible in states at context.<meta>
:
$start : boolean
- true if state is initial state$to : string
- describe destination state. Available during exit$from : string
- describe origin state. Available during enter$end : boolean
- true if state is end state
Example:
states:
stateA:
enter:
context.stateACount: (context.stateACount || 0)++
transit:
context.name: attributes.name || null
exit:
context.stateA.to: context.$to
Actions
Actions can be defined as following:
actions:
<name>: <Action>
Following fields are available:
type : string
- action type.method : method
- specify if action type is methodoptions: JsonObject
- action optionscondition : string
- action condition
Example:
actions:
askName:
type: reply
options:
text: 'nama kamu siapa?'
Available action types are described in Action Types.
Flow Switching
Whenever bot reaches a state that is not an end state, the flow will stay open. The following message will trigger a transition to the next state. There is a case where the incoming message cannot be handled by any intents in current flow. In that case it will try to find a flow with a matching intent. When the second flow closes, the system will create internal message reenter.
{
type: "command",
content: "reenter",
payload: null
}
this reenter need to be catched by the previous flow that is open:
intents:
reenter:
type: command
condition: content == "reenter"
Contributing to the Documentation
Is something missing/incorrect? Please let us know by contacting support@kata.ai. If you know how to fix it straight away, don’t hesitate to create a pull request on this documentation’s GitHub repository.