bot#

class besser.bot.core.bot.Bot(name)[source]#

Bases: object

The bot class.

Parameters:: name (str) – The bot’s name

_name#

The bot name

Type:: str

_platforms#

The bot platforms

Type:: list[Platform]

_platforms_threads#

The threads where the platforms are run

Type:: list[threading.Thread]

_nlp_engine#

The bot NLP engine

Type:: NLPEngine

_config#

The bot configuration parameters

Type:: ConfigParser

_default_ic_config#

the intent classifier configuration used by default for the bot states

Type:: IntentClassifierConfiguration

_sessions#

The bot sessions

Type:: dict[str, Session]

_trained#

Whether the bot has been trained or not. It must be trained before it starts its execution.

Type:: bool

_monitoring_db#

The monitoring component of the bot that communicates with a database to store usage information for later visualization or analysis

Type:: MonitoringDB

states#

The bot states

Type:: list[State]

intents#

The bot intents

Type:: list[Intent]

entities#

The bot entities

Type:: list[Entity]

global_initial_states#

List of tuples of initial global states and their triggering intent

Type:: list[State, Intent]

global_state_component#

Dictionary of global state components, where key is initial global state and values is set of states in corresponding global component

Type:: dict[State, list[State]]

_get_session(session_id)[source]#

Get a bot session.

Parameters:: session_id (str) – the session id
Returns:: the session, if exists, or None
Return type:: Session or None

_init_global_states()[source]#

Initialise the global states and add the necessary transitions.

Go through all the global states and add transitions to every state to jump to the global states. Also add the transition to jump back to the previous state once the global state component has been completed.

_monitoring_db_insert_intent_prediction(session)[source]#

Insert an intent prediction record into the monitoring database.

Parameters:: session (Session) – the session of the current user

_monitoring_db_insert_session(session)[source]#

Insert a session record into the monitoring database.

Parameters:: session (Session) – the session of the current user

_monitoring_db_insert_transition(session, transition)[source]#

Insert a transition record into the monitoring database.

Parameters:: session (Session) – the session of the current user

_new_session(session_id, platform)[source]#

Create a new session for the bot.

Parameters:

session_id (str) – the session id
platform (Platform) – the platform where the session is to be created and used

Returns:

the session

Return type:

Session

_run_platforms()[source]#: Stop the execution of the bot platforms

_stop_platforms()[source]#

add_entity(entity)[source]#

Add an entity to the bot.

Parameters:: entity (Entity) – the entity to add
Returns:: the added entity
Return type:: Entity

add_intent(intent)[source]#

Add an intent to the bot.

Parameters:: intent (Intent) – the intent to add
Returns:: the added intent
Return type:: Intent

property config#

The bot configuration parameters.

Type:: ConfigParser

delete_session(session_id)[source]#

Delete an existing bot session.

Parameters:: session_id (str) – the session id

get_or_create_session(session_id, platform)[source]#

get_property(prop)[source]#

Get a bot property’s value

Parameters:: prop (Property) – the property to get its value
Returns:: the property value, or None
Return type:: Any

initial_state()[source]#

Get the bot’s initial state. It can be None if it has not been set.

Returns:: the initial state of the bot, if exists
Return type:: State or None

load_properties(path)[source]#

Read a properties file and store its properties in the bot configuration.

An example properties file, config.ini:

[websocket_platform]
websocket.host = localhost
websocket.port = 8765
streamlit.host = localhost
streamlit.port = 5000

[telegram_platform]
telegram.token = YOUR-BOT-TOKEN

[nlp]
nlp.language = en
nlp.region = US
nlp.timezone = Europe/Madrid
nlp.pre_processing = True
nlp.intent_threshold = 0.4

nlp.openai.api_key = YOUR-API-KEY
nlp.intent.openai.model_name = gpt-4-turbo-preview

nlp.hf.api_key = YOUR-API-KEY
nlp.intent.hf.model_name = mistralai/Mixtral-8x7B-Instruct-v0.1

nlp.replicate.api_key = YOUR-API-KEY
nlp.intent.replicate.model_name = mistralai/mixtral-8x7b-instruct-v0.1

[db]
db.monitoring = False
db.monitoring.dialect = postgresql
db.monitoring.host = localhost
db.monitoring.port = 5432
db.monitoring.database = DB-NAME
db.monitoring.username = DB-USERNAME
db.monitoring.password = DB-PASSWORD

Parameters:: path (str) – the path to the properties file

property name#

The bot name.

Type:: str

new_entity(name, base_entity=False, entries=None, description=None)[source]#

Create a new entity in the bot.

Parameters:

name (str) – the entity name. It must be unique in the bot
base_entity (bool) – whether the entity is a base entity or not (i.e. a custom entity)
entries (dict[str, list[str]] or None) – the entity entries
description (str or None) – a description of the entity, optional

Returns:

the entity

Return type:

Entity

new_intent(name, training_sentences=None, parameters=None, description=None)[source]#

Create a new intent in the bot.

Parameters:

name (str) – the intent name. It must be unique in the bot
training_sentences (list[str] or None) – the intent’s training sentences
parameters (list[IntentParameter] or None) – the intent parameters, optional
description (str or None) – a description of the intent, optional

Returns:

the intent

Return type:

Intent

new_state(name, initial=False, ic_config=None)[source]#

Create a new state in the bot.

Parameters:

name (str) – the state name. It must be unique in the bot.
initial (bool) – whether the state is initial or not. A bot must have 1 initial state.
ic_config (IntentClassifierConfiguration or None) – the intent classifier configuration for the state. If None is provided, the bot’s default one will be assigned to the state.

Returns:

the state

Return type:

State

property nlp_engine#

The bot NLP engine.

Type:: NLPEngine

receive_file(session_id, file)[source]#

Receive a file from a specific session.

Parameters:

session_id (str) – the session that sends the message to the bot
file (File) – the file sent to the bot

receive_message(session_id, message)[source]#

Receive a message from a specific session.

Receiving a message starts the process of inferring the message’s intent and acting properly (e.g. transition to another state, store something in memory, etc.)

Parameters:

session_id (str) – the session that sends the message to the bot
message (str) – the message sent to the bot

reset(session_id)[source]#

Reset the bot current state and memory for the specified session. Then, restart the bot again for this session.

Parameters:: session_id (str) – the session to reset
Returns:: the reset session, or None if the provided session_id does not exist
Return type:: Session or None

run(train=True, sleep=True)[source]#

Start the execution of the bot.

Parameters:

train (bool) – whether to train the bot or not
sleep (bool) – whether to sleep after running the bot or not, which means that this function will not return

set_default_ic_config(ic_config)[source]#

Set the default intent classifier configuration.

Parameters:: ic_config (IntentClassifierConfiguration) – the intent classifier configuration

set_global_fallback_body(body)[source]#

Set the fallback body for all bot states.

The fallback body is a state’s callable function that will be run whenever necessary to handle unexpected scenarios (e.g. when no intent is matched, the current state’s fallback is run). This method simply sets the same fallback body to all bot states.