monitoring_db#

class baf.db.monitoring_db.MonitoringDB[source]#

Bases: object

This class is an interface to connect to a database where user interactions with the agent are stored to monitor the agent for later analysis.

conn#

The connection to the monitoring database

Type:

sqlalchemy.Connection

connected#

Whether there is an active connection to the monitoring database or not

Type:

bool

close_connection()[source]#

Close the connection to the monitoring database

connect_to_db(agent)[source]#

Connect to the monitoring database.

Parameters:

agent (Agent) – The agent that contains the database-related properties.

delete_session(session)[source]#

Deletes the session information, chat messages, and transitions related to the given session from the monitoring database.

Parameters:

session (Session) – The session to delete.

get_last_state_of_session(agent_name, platform_name, session_id)[source]#

Retrieves the last dest_state for a given session from the transition table.

Parameters:

  • agent_name (str) – The agent name.

  • platform_name (str) – The platform name.

  • session_id (str) – The session ID.

Returns:

The last dest_state value, or None if not found.

Return type:

str | None

get_table(table_name)[source]#

Gets all the content of a database table (i.e., SELECT * FROM table_name).

Parameters:

table_name – the name of the table

Returns:

the table in a dataframe

Return type:

pandas.DataFrame

initialize_db()[source]#

Initialize the monitoring database, creating the tables if necessary.

insert_chat(session, message)[source]#

Insert a new record into the chat table of the monitoring database.

Parameters:

  • session (Session) – the session the transition belongs to

  • message (Message) – the message to insert into the database

insert_event(session, event)[source]#

Insert a new record into the event table of the monitoring database.

Parameters:

  • session (Session or None) – the session the event belongs to, or None if the event is not associated to a session

  • event (Event) – the event to insert into the database

insert_intent_prediction(session, state, predicted_intent)[source]#

Insert a new intent prediction record into the intent predictions table of the monitoring database.

Parameters:

  • session (Session) – the session containing the predicted intent to insert into the database

  • state (State) – the state where the intent prediction took place (the session’s current state may have changed since the intent prediction, so we need it as argument)

  • predicted_intent (IntentClassifierPrediction) – the intent prediction

insert_reasoning_event(session, kind, payload)[source]#

Insert a row into the reasoning_step table.

Parameters:

  • session (Session) – the session that produced the event.

  • kind (str) – one of REASONING_KIND_STEP / REASONING_KIND_TASK_LIST_UPDATE.

  • payload (Any) – for REASONING_KIND_STEP the ReasoningStep dict ({"kind", "step", "summary", "details"}); for REASONING_KIND_TASK_LIST_UPDATE the list of task dicts ([{"id", "description", "status", "result"}, ...]).

Returns:

the inserted row id, or None on failure.

Return type:

int | None

insert_session(session)[source]#

Insert a new session record into the sessions table of the monitoring database.

Parameters:

session (Session) – the session to insert into the database

insert_transition(session, transition)[source]#

Insert a new transition record into the transitions table of the monitoring database.

Parameters:

  • session (Session) – the session the transition belongs to

  • transition (Transition) – the transition to insert into the database

Attach all reasoning events with chat_id IS NULL to the most recent chat row for the session.

Best-effort: if the reasoning_step or chat tables don’t exist yet, or no chat row exists for the session, the method does nothing and returns 0. Called once per reasoning loop after the final session.reply().

Returns:

number of rows linked.

Return type:

int

load_session_variables(session)[source]#

Loads the session variables from the monitoring database, transforms the JSON string into a dictionary, and sets each key-value pair in the session using session.set(key, value).

Parameters:

session (Session) – The session whose variables should be loaded.

run_statement(stmt)[source]#

Executes a SQL statement.

Parameters:

stmt (sqlalchemy.Executable) – the SQL statement

Returns:

the result of the SQL statement

Return type:

sqlalchemy.CursorResult[Any] | None

select_chat(session, n=None, until_timestamp=None)[source]#

Retrieves chat records from the chat table of the database for a given session.

Parameters:

  • session (Session) – the session to get chat records from the database

  • n (Optional[int]) – the number of latest chat records to retrieve. If None, retrieves all records.

  • until_timestamp (Optional[datetime]) – if provided, retrieves only chat records up to this timestamp.

Returns:

the chat records for the given session

Return type:

pandas.DataFrame

select_reasoning_events(session, until_timestamp=None)[source]#

Retrieve all reasoning-state events for a session, in chronological order.

Parameters:

  • session (Session) – the session whose events to fetch.

  • until_timestamp (Optional[datetime]) – if provided, only events at or before this timestamp are returned.

Returns:

rows with columns id, session_id, chat_id, kind, step_kind, step, summary, payload, timestamp. Empty if the table doesn’t exist (e.g. older DB without the migration applied).

Return type:

pandas.DataFrame

select_session(session)[source]#

Retrieves a session record from the sessions table of the database.

Parameters:

session (Session) – the session to get from the database

Returns:

the session record, should be a 1 row DataFrame

Return type:

pandas.DataFrame

session_exists(agent_name, platform_name, session_id)[source]#

Checks whether there is an entry with the given agent_name, platform_name, and session_id in the sessions table.

Parameters:

  • agent_name (str) – The agent name to check.

  • platform_name (str) – The platform name to check.

  • session_id (str) – The session ID to check.

Returns:

True if the session exists, False otherwise.

Return type:

bool

store_session_variables(session)[source]#

Stores the current session variables (dictionary) as a JSON string in the monitoring database, replacing the old value for the given session.

Parameters:

session (Session) – The session whose variables should be stored.

baf.db.monitoring_db.REASONING_KIND_STEP = 'reasoning_step'#

kind value for a reasoning step event (LLM tool call, tool result, push-back, task add/complete/skip, max_steps, reasoning_started/finished).

baf.db.monitoring_db.REASONING_KIND_TASK_LIST_UPDATE = 'task_list_update'#

kind value for a task list snapshot.

baf.db.monitoring_db.TABLE_CHAT = 'chat'#

The name of the database table that contains the chat records

baf.db.monitoring_db.TABLE_EVENT = 'event'#

The name of the database table that contains the event records

baf.db.monitoring_db.TABLE_INTENT_PREDICTION = 'intent_prediction'#

The name of the database table that contains the intent prediction records

baf.db.monitoring_db.TABLE_PARAMETER = 'parameter'#

The name of the database table that contains the parameter records

baf.db.monitoring_db.TABLE_REASONING_STEP = 'reasoning_step'#

The name of the database table that contains reasoning-state step events and task-list snapshots (a single per-session timeline of everything that happens inside the reasoning loop).

baf.db.monitoring_db.TABLE_SESSION = 'session'#

The name of the database table that contains the session records

baf.db.monitoring_db.TABLE_TRANSITION = 'transition'#

The name of the database table that contains the transition records