maeser.chat.chat_logs module

maeser.chat.chat_logs module#

Module for managing chat logs, including logging and retrieving chat history, feedback, and training data.

class maeser.chat.chat_logs.BaseChatLogsManager(chat_log_path: str, user_manager: UserManager | None = None)[source]#

Bases: ABC

Abstract base class for chat logs managers.

Parameters:

  • chat_log_path (str) – Path to the chat log directory.

  • user_manager (UserManager | None) – Optional user manager instance.

abstract get_chat_history(branch_name: str, session_id: str) → dict[source]#

Abstract method to get chat history for a session.

Parameters:

  • branch_name (str) – The name of the branch.

  • session_id (str) – The session ID for the conversation.

Returns:

The chat history for the session.

Return type:

dict

abstract get_chat_history_overview(user: User | None) → list[dict][source]#

Abstract method to get an overview of chat history. This is used to display a list of overviews of previous chat conversations.

Parameters:

user (User | None) – The user to get chat history for.

Returns:

A list of dictionaries containing information about previous chat conversations. Each should have the following keys:

  • ’branch’: The name of the branch.

  • ’session’: The session ID for the conversation.

  • ’modified’: The timestamp of when the chat conversation was last modified.

  • ’header’: The text that will be used as the link text. Usually the first message in the conversation. Could also be a conversation title.

Return type:

list[dict]

abstract get_chat_logs_overview(sort_by: str, order: str, branch_filter: str, user_filter: str, feedback_filter: str) → tuple[list[dict], int, float, set[str]][source]#

Abstract method to get an overview of chat logs.

Parameters:

  • sort_by (str) – The field to sort by.

  • order (str) – The order to sort by. Either ‘asc’ or ‘desc’.

  • branch_filter (str) – The branch to filter by.

  • feedback_filter (str) – The feedback to filter by.

Returns:

A tuple containing:

  • list[dict]: A list of dictionaries containing information about chat logs.

  • int: The total number of tokens used.

  • float: The total cost of the chat logs.

Return type:

tuple

abstract get_log_file_template(filename: str, branch: str, app_name: str) → str[source]#

Abstract method to get the jinja template for a log file.

Parameters:

  • filename (str) – The name of the log file.

  • branch (str) – The branch the log file is in.

  • app_name (str) – The display name of the Maeser application.

Returns:

The rendered template for the log file.

Return type:

str

abstract log(branch_name: str, session_id: str, log_data: dict) → None[source]#

Abstract method to log chat data.

Parameters:

  • branch_name (str) – The name of the branch.

  • session_id (str) – The session ID for the conversation.

  • log_data (dict) – The data to be logged.

Returns:

None

abstract log_feedback(branch_name: str, session_id: str, message_index: int, feedback: str) → None[source]#

Abstract method to log feedback for a message.

Parameters:

  • branch_name (str) – The name of the branch.

  • session_id (str) – The session ID for the conversation.

  • message_index (int) – The index of the message to add feedback to.

  • feedback (str) – The feedback to add to the message.

Returns:

None

abstract save_feedback(feedback: dict) → None[source]#

Abstract method to save feedback input to a file.

Parameters:

feedback (dict) – The feedback to save.

Returns:

None

abstract save_training_data(training_data: dict) → None[source]#

Abstract method to save training data to a file.

Parameters:

training_data (dict) – The training data to save.

Returns:

None

class maeser.chat.chat_logs.ChatLogsManager(chat_log_path: str)[source]#

Bases: BaseChatLogsManager

The Chat Logs Manager used by Maeser.

Parameters:

chat_log_path (str) – Path to the chat log directory.

get_chat_history(branch_name: str, session_id: str) → dict[source]#

Retrieves chat history for a specific session.

This loads the entire chat log file (in YAML format) as a dictionary, consisting of the following fields:

  • “branch”: The chat branch of the session.

  • “real_name”: The real name of the user.

  • “session_id”: The chat session ID.

  • “time”: The creation time of the session/chat log.

  • “total_cost”: The aggregate cost of all messages in the chat.

  • “total_tokens”: The aggregate number of tokens of all messages in the chat.

  • “user”: The full ID of the user, formatted like authenticator.user_id.

  • “messages”:

    A list containing the chat message history, including the messages from both the user and the chatbot.

    • The “content” field contains the actual text content of the message.

    • The “role” field indicates whether the message came from the user (‘user’) or the chatbot (‘system’).

    • Messages from the chatbot (“role: system”) also contain the context retrieved from vector stores (”context”), the total cost and tokens (”cost” and “tokens_used”), and the execution time (”execution_time”).

Parameters:

  • branch_name (str) – The name of the branch.

  • session_id (str) – The session ID for the conversation.

Returns:

The chat history for the session.

Return type:

dict

get_chat_history_overview(user: User | None) → list[dict][source]#

Gets an overview of chat history for a specific user.

This overview consists of statistics for all chat logs that belongs to the user.

The statistics for each chat log in the list include the following:

  • “branch” (str): The chat branch of the session.

  • “session” (str): The chat session ID.

  • “modified” (int): The time and date the log file was last modified.

  • “header” (str): The first message of the chat. This is used as the chat title in the web view.

Parameters:

user (User | None) – The user to get chat history for.

Returns:

A list of dictionaries containing information about previous chat conversations.

Return type:

list[dict]

get_chat_logs_overview(sort_by: str, order: str, branch_filter: str, user_filter: str, feedback_filter: str) → tuple[list[dict], int, float, set[str]][source]#

Gets an overview of chat logs.

Retrieves information about individual chat logs that match the specified filters as well as the total tokens and cost aggregated from these logs.

Details for individual chat logs include the following:

  • “name” (str): The name of the log file.

  • “created” (int): The creation time and date of the log file.

  • “modified” (int): The time and date the log file was last modified.

  • “branch” (str): The chat branch of the conversation.

Parameters:

  • sort_by (str) – The field to sort by. Either ‘created’ or ‘modified’.

  • order (str) –

    The order to sort by:

    • ’asc’ for ascending order.

    • ’desc’ for descending order.

  • branch_filter (str) – The branch to filter by.

  • feedback_filter (str) –

    The feedback to filter by:

    • ’true’ for logs with feedback.

    • ’false’ for logs without feedback.

Returns:

A tuple containing:

  • list[dict]: A list of dictionaries containing information about chat logs.

  • int: The total number of tokens used.

  • float: The total cost of the chat logs.

Return type:

tuple

get_log_file_template(filename: str, branch: str, app_name: str) → str[source]#

Gets the Jinja template for a log file.

Parameters:

  • filename (str) – The name of the log file.

  • branch (str) – The branch the log file is in.

  • app_name (str) – The display name of the Maeser application. This name and the name of the branch will be populated into the page’s title element.

Returns:

The rendered template for the log file.

Return type:

str

log(branch_name: str, session_id: str, log_data: dict) → None[source]#

Logs a user’s message and chatbot’s response with corresponding statistics to the session’s chat log (in YAML format).

This function should be called every time the user submits a new message and receives a response from the chatbot.

The log_data dictionary should contain the following key-value pairs:

  • “messages” (tuple[str]): A tuple of two strings: The user’s message and the chatbot’s response, in that order.

  • “user” (User): The user the chat belongs to.

  • “cost” (float): The total cost of the last message.

  • “tokens” (int): The total tokens of the last message.

Parameters:

  • branch_name (str) – The name of the branch.

  • session_id (str) – The session ID for the conversation.

  • log_data (dict) – The data to be logged. Should contain the following keys: ‘user’, ‘cost’, ‘tokens’, and ‘message’.

Returns:

None

log_feedback(branch_name: str, session_id: str, message_index: int, feedback: str) → None[source]#

Adds feedback to the log for a specific response in a specific session.

Parameters:

  • branch_name (str) – The name of the branch.

  • session_id (str) – The session ID for the conversation.

  • message_index (int) – The index of the message to add feedback to.

  • feedback (str) – The feedback to add to the message.

Returns:

None

save_feedback(feedback: dict) → None[source]#

Saves feedback input to a YAML file.

Parameters:

feedback (dict) – The feedback to save.

Returns:

None

save_training_data(training_data: dict) → None[source]#

Saves training data to a YAML file.

Parameters:

training_data (dict) – The training data to save.

Contents