state#

class besser.bot.core.state.State(bot, name, initial=False, ic_config=None)[source]#

Bases: object

The State core component of a bot.

The bot relies on a state machine to define its execution logic. Each state can run a set of actions, and the bot can navigate to other states through transitions that are triggered when events occur (e.g. an intent is matched).

Parameters:

bot (Bot) – the bot the state belongs to
name (str) – the state’s name
initial (bool) – whether the state is initial or not
ic_config (IntentClassifierConfiguration) – the intent classifier configuration of the state

_bot#

The bot the state belongs to

Type:: Bot

_name#

The state name

Type:: str

_initial#

Whether the state is initial or not

Type:: bool

_body#

The state body. It is a callable that takes as argument a Session. It will be run whenever the bot moves to this state.

Type:: Callable[[Session], None]

_fallback_body#

The state fallback body. It is a callable that takes as argument a Session. It will be run whenever the bot tries to move to another state, but it can’t (e.g. an intent is matched but none of the current state’s transitions are triggered on that intent)

Type:: Callable[[Session], None]

_ic_config#

the intent classifier configuration of the state

Type:: IntentClassifierConfiguration

_transition_counter#

Count the number of transitions of this state. Used to name the transitions.

Type:: int

intents#

The state intents, i.e. those that can be matched from a specific state

Type:: list[Intent]

transitions#

The state’s transitions to other states

Type:: list[Transition]

_check_global_state(dest)[source]#

Add state to global state component if condition is met.

If the previous state is a global state, add this state to the component’s list of the global state.

Parameters:: dest (State) – the destination state

_check_next_transition(session)[source]#

Check whether the first defined transition of the state is an auto transition, and if so, move to its destination state.

This method is intended to be called after running the body of a state.

Parameters:: session (Session) – the user session

_t_name()[source]#

Name generator for transitions. Transition names are generic and enumerated. On each call, a new name is generated and the transition counter is incremented for the next name.

Returns:: a name for the next transition
Return type:: str

property bot#

The state’s bot.

Type:: Bot

go_to(dest)[source]#

Create a new auto transition on this state.

This transition needs no event to be triggered, which means that when the bot moves to a state that has an auto transition, the bot will move to the transition’s destination state unconditionally without waiting for user input. This transition cannot be combined with other transitions.

Parameters:: dest (State) – the destination state

property ic_config#

the intent classifier configuration of the state.

Type:: IntentClassifierConfiguration

property initial#

The initial status of the state (initial or non-initial).

Type:: bool

property name#

The state name

Type:: str

receive_file(session)[source]#

Receive a file from a user session.

When receiving a file it looks for the state’s transition whose trigger event is to receive a file. The fallback body is when no file transition was defined.

Parameters:: session (Session) – the user session that sent the message

receive_intent(session)[source]#

Receive an intent from a user session (which is predicted from the user message).

When receiving an intent it looks for the state’s transition whose trigger event is to match that intent. The fallback body is run when the received intent does not match any transition intent (i.e. fallback intent).

Parameters:: session (Session) – the user session that sent the message

run(session)[source]#

Run the state (i.e. its body). After running the body, check if the first defined transition of the state is an auto transition, and if so, move to its destination state.

Parameters:: session (Session) – the user session

set_body(body)[source]#

Set the state body.

Parameters:: body (Callable[[Session], None]) – the body

set_fallback_body(body)[source]#

Set the state fallback body.

Parameters:: body (Callable[[Session], None]) – the fallback body

set_global(intent)[source]#

Set state as globally accessible state.

Parameters:: intent (Intent) – the intent that should trigger the jump to the global state

when_event_go_to(event, dest, event_params)[source]#

Create a new transition on this state.

When the bot is in a state and a state’s transition event occurs, the bot will move to the destination state of the transition.

Parameters:

event (Callable[[Session, dict], bool]) – the transition event
dest (State) – the destination state
event_params (dict) – the parameters associated to the event

when_file_received_go_to(dest, allowed_types=None)[source]#

Create a new file received transition on this state.

When the bot is in a state and a file is received the bot will move to the transition’s destination state. If no other transition is specified, trigger the fallback state.

Parameters:

dest (State) – the destination state
allowed_types (list[str] or str, optional) – the allowed file types, non-conforming types will cause a
message (fallback) –

when_intent_matched_go_to(intent, dest)[source]#

Create a new intent matching transition on this state.

When the bot is in a state and an intent is received (the intent is predicted from a user message), if the transition event is to receive this particular intent, the bot will move to the transition’s destination state.

Parameters:

intent (Intent) – the transition intent
dest (State) – the destination state

when_no_intent_matched_go_to(dest)[source]#

Create a new no intent matching transition on this state.

When the bot is in a state and no fitting intent is received (the intent is predicted from a user message), the bot will move to the transition’s destination state. If no other transition is specified, the bot will wait for a user message regardless.

Parameters:: dest (State) – the destination state

when_variable_matches_operation_go_to(var_name, operation, target, dest)[source]#

Create a new variable_matches_operation transition on this state.

When the bot is in a state and the operation on the specified session variable and target value returns true, then the bot moves to the specified destination state.

Parameters:

var_name (str) – the name of the stored variable in the session storage
operation (Callable[[Any, Any], bool]) – the comparison operation to be done on the stored and target value
target (Any) – the target value to which will be used in the operation with the stored value
dest (State) – the destination state