state

class besser.agent.core.state.State(agent, name, initial=False, ic_config=None)

Bases: object

The State core component of an agent.

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

Parameters:

• agent (Agent) – the agent 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

_agent

The agent the state belongs to

Type:

Agent

_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 agent 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 agent 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)

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

_t_name()

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 agent

The state’s agent.

Type:

Agent

check_transitions(session)

Check the state transitions and triggers the one that is satisfied.

When checking transition, the priority is based on transition order.

For a given transition expecting an event to happen, the first event matching will be used (and removed from the session queue of events).

If a user message event is received but does not match the transition, run the fallback body (and the event is removed from the session queue of events)

Parameters:

session (Session) – the current session

go_to(dest)

Create a new auto transition on this state.

This transition needs no event nor condition to be triggered, which means that when the agent moves to a state that has an auto transition, the agent will move to the transition’s destination state. 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

run(session)

Run the state body.

Parameters:

session (Session) – the user session

set_body(body)

Set the state body.

Parameters:

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

set_fallback_body(body)

Set the state fallback body.

Parameters:

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

set_global(intent)

Set state as globally accessible state.

Parameters:

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

when_condition(function, params=None)

Start the definition of a “condition matching” transition on this state.

Parameters:

• function (Union[Callable[[Session], bool], Callable[[Session, dict], bool]]) – the condition function to add to the transition. Allowed function arguments are (Session) or (Session, dict) to add parameters within the dict argument. The function must return a boolean value

• params (dict, optional) – the parameters for the condition function, necessary if the function has (Session, dict) arguments

Returns:

the transition builder

Return type:

TransitionBuilder

when_event(event=None)

Start the definition of an “event matching” transition on this state.

Parameters:

event (Event) – the target event for the transition to be triggered. If none, any event can trigger this transition.

Returns:

the transition builder

Return type:

TransitionBuilder

when_file_received(allowed_types=None)

Start the definition of a “file received” transition on this state.

Parameters:

allowed_types (list[str] or str) – the file types to consider for this transition. List of strings or just 1 string are valid values

Returns:

the transition builder

Return type:

TransitionBuilder

when_intent_matched(intent)

Start the definition of an “intent matching” transition on this state.

Parameters:

intent (Intent) – the target intent for the transition to be triggered

Returns:

the transition builder

Return type:

TransitionBuilder

when_no_intent_matched()

when_variable_matches_operation(var_name, operation, target)

Start the definition of a “variable matching operator” transition on this state.

This transition evaluates if (variable operator target_value) is satisfied. For instance, “age > 18”.

Parameters:

• var_name (str) – the name of the variable to evaluate. The variable must exist in the user session

• operation (Callable[[Any, Any], bool]) – the operation to apply to the variable and the target value. It gets as arguments the variable and the target value, and returns a boolean value

• target (Any) – the target value to compare with the variable

Returns:

the transition builder

Return type:

TransitionBuilder