agent#

class besser.agent.core.agent.Agent(name)[source]#

Bases: object

The agent class.

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

_name#

The agent name

Type:: str

_platforms#

The agent platforms

Type:: list[Platform]

_platforms_threads#

The threads where the platforms are run

Type:: list[threading.Thread]

_event_loop#

The event loop managing external events

Type:: asyncio.AbstractEventLoop

_event_thread#

The thread where the event loop is run

Type:: threading.Thread

_nlp_engine#

The agent NLP engine

Type:: NLPEngine

_config#

The agent configuration parameters

Type:: ConfigParser

_default_ic_config#

the intent classifier configuration used by default for the agent states

Type:: IntentClassifierConfiguration

_sessions#

The agent sessions

Type:: dict[str, Session]

_trained#

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

Type:: bool

_monitoring_db#

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

Type:: MonitoringDB

states#

The agent states

Type:: list[State]

intents#

The agent intents

Type:: list[Intent]

entities#

The agent 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]]

processors#

List of processors used by the agent

Type:: list[Processors]

_get_session(session_id)[source]#

Get an agent 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_chat(session, message)[source]#

Insert a message record into the monitoring database.

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

_monitoring_db_insert_event(event)[source]#

Insert an event record into the monitoring database.

Parameters:: event (Event) – the event to insert into the database

_monitoring_db_insert_intent_prediction(session, predicted_intent)[source]#

Insert an intent prediction record into the monitoring database.

Parameters:

session (Session) – the session of the current user
predicted_intent (IntentClassifierPrediction) – the intent prediction

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

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]#: Start the execution of the agent platforms

_stop_platforms()[source]#: Stop the execution of the agent platforms

add_entity(entity)[source]#

Add an entity to the agent.

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

add_intent(intent)[source]#

Add an intent to the agent.

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

property config#

The agent configuration parameters.

Type:: ConfigParser

delete_session(session_id)[source]#

Delete an existing agent session.

Parameters:: session_id (str) – the session id

get_or_create_session(session_id, platform)[source]#

get_property(prop)[source]#

Get an agent 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 agent’s initial state. It can be None if it has not been set.

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

load_properties(path)[source]#

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

An example properties file, config.ini:

[agent]
agent.check_transitions.delay = 2

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

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

[github_platform]
github.personal_token = GITHUB-PERSONAL-TOKEN
github.webhook_token = WEBHOOK-TOKEN
github.webhook_port = 8901

[gitlab_platform]
gitlab.personal_token = GITLAB-PERSONAL-TOKEN
gitlab.webhook_token = WEBHOOK-TOKEN
gitlab.webhook_port = 8901

[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.hf.api_key = YOUR-API-KEY
nlp.replicate.api_key = YOUR-API-KEY

[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 agent name.

Type:: str

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

Create a new entity in the agent.

Parameters:

name (str) – the entity name. It must be unique in the agent
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 agent.

Parameters:

name (str) – the intent name. It must be unique in the agent
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 agent.

Parameters:

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

Returns:

the state

Return type:

State

property nlp_engine#

The agent NLP engine.

Type:: NLPEngine

process(session, message, is_user_message)[source]#

Runs the agent processors in a message.

Only processors that process messages of the same type as the given message will be run. If the message to process is a user message, only processors that process user messages will be run. If the message to process is an agent message, only processors that process agent messages will be run.

Parameters:

session (Session) – the current session
message (Any) – the message to be processed
is_user_message (bool) – indicates whether the message is a user message (True) or an agent message (False)

Returns:

the processed message

Return type:

Any

receive_event(event)[source]#

Receive an external event from a platform.

Receiving an event and send it to all the applicable sessions of the agent

Parameters:: event (Event) – the received event

reset(session_id)[source]#

Reset the agent current state and memory for the specified session. Then, restart the agent 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 agent.

Parameters:

train (bool) – whether to train the agent or not
sleep (bool) – whether to sleep after running the agent 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 agent 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 agent states.