lionagi 0.0.206__py3-none-any.whl → 0.0.208__py3-none-any.whl

lionagi/core/branch/conversation.py

@@ -2,483 +2,786 @@ import json
 import pandas as pd
 from datetime import datetime
 from typing import Any, Optional, Dict, Union
-from lionagi.schema import DataLogger
-from lionagi.utils import lcall, as_dict
-from ..messages.messages import Message, System, Instruction, Response
-from ..core_util import sign_message, validate_messages
 
+from lionagi.utils.sys_util import as_dict, create_copy, strip_lower, to_df
+from lionagi.utils.call_util import lcall
+from ..messages.messages import Message, System, Instruction, Response
 
 class Conversation:
     """
-    Represents a conversation with messages, tools, and instructions.
-
-    A `Conversation` is a container for messages exchanged in a conversation, as well as tools and instructions
-    for interacting with external services or tools.
-
+    A class to represent a conversation, encapsulating messages within a pandas DataFrame.
+    
     Attributes:
-        messages (pd.DataFrame): A DataFrame containing conversation messages.
-        _logger (DataLogger): An instance of DataLogger for logging.
+        messages (pd.DataFrame): A DataFrame holding conversation messages with columns specified in _cols.
     """
+    
+    _cols = ["node_id", "role", "sender", "timestamp", "content"]
 
-    def __init__(self, dir: Optional[str] = None) -> None:
+    def __init__(self) -> None:
         """
-        Initializes a Conversation object with an empty DataFrame for messages and a DataLogger.
-
-        Args:
-            dir (Optional[str]): The directory path for storing logs. Defaults to None.
-
-        Examples:
-            >>> conversation = Conversation(dir='logs/')
+        Initializes a Conversation instance with an empty DataFrame structured to hold messages.
         """
-        self.messages = pd.DataFrame(columns=["node_id", "role", "sender", "timestamp", "content"])
-        self.logger = DataLogger(dir=dir)
+        self.messages = pd.DataFrame(columns=Conversation._cols)
 
-    def _create_message(
-        self,
-        system: Optional[Union[dict, list, System]] = None,
-        instruction: Optional[Union[dict, list, Instruction]] = None,
-        context: Optional[Union[str, Dict[str, Any]]] = None,
-        response: Optional[Union[dict, list, Response]] = None,
-        sender: Optional[str] = None
-    ) -> Message:
+    @classmethod
+    def from_csv(cls, filepath: str, **kwargs) -> 'Conversation':
         """
-        Creates a Message object based on the given parameters.
-
-        Only one of `system`, `instruction`, or `response` can be provided to create a message.
+        Create a Conversation instance from a CSV file containing messages.
 
         Args:
-            system (Optional[Union[dict, list, System]]): The system message content.
-            instruction (Optional[Union[dict, list, Instruction]]): The instruction content.
-            context (Optional[Union[str, Dict[str, Any]]]): The context associated with the instruction.
-            response (Optional[Union[dict, list, Response]]): The response content.
-            sender (Optional[str]): The sender of the message.
+            filepath (str): The path to the CSV file to be loaded.
+            **kwargs: Additional keyword arguments passed to pandas.read_csv function.
 
         Returns:
-            Message: A message object created from the provided parameters.
-
-        Raises:
-            ValueError: If more than one or none of the parameters (system, instruction, response) are provided.
-
-        Examples:
-            >>> conversation = Conversation()
-            >>> msg = conversation._create_message(system="System message", sender="system")
+            Conversation: An instance of Conversation with messages loaded from the specified CSV file.
         """
-        
-        if sum(lcall([system, instruction, response], bool)) != 1:
-            raise ValueError("Error: Message must have one and only one role.")
-        else:
-            if isinstance(any([system, instruction, response]), Message):
-                if system:
-                    return system
-                elif instruction:
-                    return instruction
-                elif response:
-                    return response
-
-            msg = 0
-            if response:
-                msg = Response(response=response, sender=sender)
-            elif instruction:
-                msg = Instruction(instruction=instruction, 
-                                  context=context, sender=sender)
-            elif system:
-                msg = System(system=system, sender=sender)
-            return msg
-        
-    def add_message(
-        self,
-        system: Optional[Union[dict, list, System]] = None,
-        instruction: Optional[Union[dict, list, Instruction]] = None,
-        context: Optional[Union[str, Dict[str, Any]]] = None,
-        response: Optional[Union[dict, list, Response]] = None,
-        sender: Optional[str] = None
-    ) -> None:
+        messages = pd.read_csv(filepath)
+        messages = to_df(messages)
+        self = cls(messages=messages, **kwargs)
+        return self
+    
+    @classmethod
+    def from_json(cls, filepath: str, **kwargs) -> 'Conversation':
         """
-        Creates and adds a new message to the conversation's messages DataFrame.
+        Create a Conversation instance from a JSON file containing messages.
+
         Args:
-            system (Optional[System]): Content for a system message.
-            instruction (Optional[Instruction]): Content for an instruction message.
-            context (Optional[Union[str, Dict[str, Any]]]): Context for the instruction message.
-            response (Optional[Response]): Content for a response message.
-            sender (Optional[str]): The sender of the message.
+            filepath (str): The path to the JSON file to be loaded.
+            **kwargs: Additional keyword arguments passed to pandas.read_json function.
 
-        Examples:
-            >>> conversation = Conversation()
-            >>> conversation.add_message(instruction="What's the weather?", sender="user")
+        Returns:
+            Conversation: An instance of Conversation with messages loaded from the specified JSON file.
         """
-        msg = self._create_message(
-            system=system, instruction=instruction, 
-            context=context, response=response, sender=sender
-        )
-        message_dict = msg.to_dict()
-        if isinstance(as_dict(message_dict['content']), dict):
-            message_dict['content'] = json.dumps(message_dict['content'])
-        message_dict['timestamp'] = datetime.now()
-        self.messages.loc[len(self.messages)] = message_dict
-    
+        messages = pd.read_json(filepath, orient="records", lines=True)
+        messages = to_df(messages)
+        self = cls(messages=messages, **kwargs)
+        return self
+        
     @property
     def last_row(self) -> pd.Series:
         """
-        Retrieves the last row from the messages DataFrame.
+        Retrieve the last row from the conversation messages as a pandas Series.
 
         Returns:
-            pd.Series: A Series object representing the last message.
+            pd.Series: The last message in the conversation.
         """
-        return self.messages.iloc[-1]
+        return get_rows(self.messages, n=1, from_='last')
     
     @property
     def first_system(self) -> pd.Series:
         """
-        Retrieves the first system message from the messages DataFrame.
+        Retrieve the first system message from the conversation.
 
         Returns:
-            pd.Series: A Series object representing the first system message.
+            pd.Series: The first message in the conversation where the role is 'system'.
         """
-        return self.messages[self.messages.role == 'system'].iloc[0]
+        return get_rows(self.messages, role='system', n=1, from_='front')
         
     @property
     def last_response(self) -> pd.Series:
         """
-        Retrieves the last response message from the messages DataFrame.
+        Retrieve the last response message from the conversation.
 
         Returns:
-            pd.Series: A Series object representing the last response message.
+            pd.Series: The last message in the conversation where the role is 'assistant'.
         """
-        return self.get_last_rows(role='assistant')
-    
+        return get_rows(self.messages, role='assistant', n=1, from_='last')
+
     @property
-    def last_instruction(self) -> pd.Series:
+    def last_response_content(self) -> Dict:
         """
-        Retrieves the last instruction message from the messages DataFrame.
+        Retrieve the last response message content from the conversation.
 
         Returns:
-            pd.Series: A Series object representing the last instruction message.
+            pd.Series: The last message in the conversation where the role is 'assistant'.
         """
-        return self.get_last_rows(role='user')
-    
-    def get_last_rows(
-        self, 
-        sender: Optional[str] = None, 
-        role: Optional[str] = None, 
-        n: int = 1, 
-        sign_ = False
-    ) -> Union[pd.DataFrame, pd.Series]:
-        """
-        Retrieves the last n rows from the messages DataFrame filtered by sender or role.
+        return as_dict(self.last_response.content.iloc[-1])
 
-        Args:
-            sender (Optional[str]): The sender filter for the messages.
-            role (Optional[str]): The role filter for the messages.
-            n (int): The number of rows to retrieve.
-            sign_: If sign messages with a sender identifier.
+    @property
+    def last_instruction(self) -> pd.Series:
+        """
+        Retrieve the last instruction message from the conversation.
 
         Returns:
-            Union[pd.DataFrame, pd.Series]: The last n messages as a DataFrame or a single message as a Series.
-
-        Raises:
-            ValueError: If both sender and role are provided or if none is provided.
+            pd.Series: The last message in the conversation where the role is 'user'.
         """
+        return get_rows(self.messages, role='user', n=1, from_='last')
 
-        if sender is None and role is None:
-            outs = self.messages.iloc[-n:]
-        elif sender and role:
-            outs = self.messages[(self.messages['sender'] == sender) & (self.messages['role'] == role)].iloc[-n:]
-        elif sender:
-            outs = self.messages[self.messages['sender'] == sender].iloc[-n:]
-        else:
-            outs = self.messages[self.messages['role'] == role].iloc[-n:]
-
-        return sign_message(outs, sender) if sign_ else outs
-
-    def filter_messages_by(
-        self,
-        role: Optional[str] = None, 
-        sender: Optional[str] = None,
-        start_time: Optional[datetime] = None,
-        end_time: Optional[datetime] = None,
-        content_keywords: Optional[Union[str, list]] = None,
-        case_sensitive: bool = False
-    ) -> pd.DataFrame:
+    @property
+    def last_action_request(self):
         """
-        Retrieves messages filtered by a specific criterion.
-
-        Args:
-            role (Optional[str]): The role to filter the messages.
-            sender (Optional[str]): The sender to filter the messages.
-            start_time (Optional[datetime]): The start time to filter the messages.
-            end_time (Optional[datetime]): The end time to filter the messages.
-            content_keywords (Optional[Union[str, list]]): The content to filter the messages.
-            case_sensitive (bool): Flag to indicate if the search should be case sensitive. Defaults to False.
+        Retrieve the last action request message from the conversation.
 
         Returns:
-            pd.DataFrame: A DataFrame containing filtered messages.
-
-        Raises:
-            ValueError: If more than one or none of the filtering criteria are provided.
+            pd.Series: The last message in the conversation with sender 'action_request'.
         """
-        outs = self.messages.copy()
-        
-        if content_keywords:
-            outs = self.search_keywords(content_keywords, case_sensitive)
-        
-        outs = outs[outs['role'] == role] if role else outs
-        outs = outs[outs['sender'] == sender] if sender else outs
-        outs = outs[outs['timestamp'] > start_time] if start_time else outs
-        outs = outs[outs['timestamp'] < end_time] if end_time else outs
-        return outs
-
-    def replace_keyword(
-        self, 
-        keyword: str, 
-        replacement: str, 
-        case_sensitive: bool = False
-    ) -> None:
+        return get_rows(self.messages, sender='action_request', n=1, from_='last')
+    
+    @property
+    def last_action_response(self):
         """
-        Replaces a keyword in the content of all messages with a replacement string.
+        Retrieve the last action response message from the conversation.
 
-        Args:
-            keyword (str): The keyword to replace.
-            replacement (str): The string to replace the keyword with.
-            case_sensitive (bool, optional): Flag to indicate if the replacement should be case sensitive. Defaults to False.
+        Returns:
+            pd.Series: The last message in the conversation with sender 'action_response'.
         """
-        if not case_sensitive:
-            self.messages["content"] = self.messages["content"].str.replace(
-                keyword, replacement, case=False
-            )
-        else:
-            self.messages["content"] = self.messages["content"].str.replace(
-                keyword, replacement
-            )
+        return get_rows(self.messages, sender='action_response', n=1, from_='last')
 
-    def search_keywords(
-        self, 
-        keywords: Union[str, list],
-        case_sensitive: bool = False
-    ) -> pd.DataFrame:
+    @property
+    def len_messages(self):
         """
-        Searches for a keyword in the content of all messages and returns the messages containing it.
-
-        Args:
-            keywords (str): The keywords to search for.
-            case_sensitive (bool, optional): Flag to indicate if the search should be case sensitive. Defaults to False.
+        Get the total number of messages in the conversation.
 
         Returns:
-            pd.DataFrame: A DataFrame containing messages with the specified keyword.
+            int: The total number of messages.
         """
-        if isinstance(keywords, list):
-            keywords = '|'.join(keywords)
-        if not case_sensitive:
-            return self.messages[
-                self.messages["content"].str.contains(keywords, case=False)
-            ]
-        return self.messages[self.messages["content"].str.contains(keywords)]
-
-    def remove_from_messages(self, message_id: str) -> bool:
+        return len(self.messages)
+    
+    @property
+    def len_instructions(self):
         """
-        Removes a message from the conversation based on its message ID.
-
-        Args:
-            message_id (str): The ID of the message to be removed.
+        Get the total number of instruction messages (messages with role 'user') in the conversation.
 
         Returns:
-            bool: True if the message was successfully removed, False otherwise.
+            int: The total number of instruction messages.
         """
-        initial_length = len(self.messages)
-        self.messages = self.messages[self.messages["node_id"] != message_id]
-        return len(self.messages) < initial_length
+        return len(self.messages[self.messages.role == 'user'])
+    
+    @property
+    def len_responses(self):
+        """
+        Get the total number of response messages (messages with role 'assistant') in the conversation.
 
-    def update_messages_content(
-        self, 
-        message_id: str, 
-        col: str, 
-        value: Any
-    ) -> bool:
+        Returns:
+            int: The total number of response messages.
         """
-        Updates the content of a specific message in the conversation.
 
-        Args:
-            message_id (str): The ID of the message to be updated.
-            col (str): The column of the message that needs to be updated.
-            value (Any): The new value to be set for the specified column.
+        return len(self.messages[self.messages.role == 'assistant'])
+    
+    @property
+    def len_systems(self):
+        """
+        Get the total number of system messages (messages with role 'system') in the conversation.
 
         Returns:
-            bool: True if the update was successful, False otherwise.
+            int: The total number of system messages.
+        """
+        return len(self.messages[self.messages.role == 'system'])
 
-        Examples:
-            >>> conversation = Conversation()
-            >>> conversation.add_message(system="Initial message", sender="system")
-            >>> success = conversation.update_messages_content(
-            ...     message_id="1", col="content", value="Updated message")
+    @property
+    def info(self):
         """
-        index = self.messages.index[self.messages["id_"] == message_id].tolist()
-        if index:
-            self.messages.at[index[0], col] = value
-            return True
-        return False
+        Get a summary of the conversation messages categorized by role.
 
-    def info(self, use_sender: bool = False) -> Dict[str, int]:
+        Returns:
+            Dict[str, int]: A dictionary with keys as message roles and values as counts.
         """
-        Provides a summary of the conversation messages.
 
-        Args:
-            use_sender (bool, optional): Determines whether to summarize by sender or by role. Defaults to False.
+        return self._info()
+    
+    @property
+    def sender_info(self):
+        """
+        Provides a descriptive summary of the conversation, including the total number of messages,
+        a summary by role, and the first five messages.
 
         Returns:
-            Dict[str, int]: A dictionary containing counts of messages either by role or sender.
+            Dict[str, Any]: A dictionary containing the total number of messages, summary by role,
+            and a list of the first five message dictionaries.
         """
-        messages = self.messages['sender'] if use_sender else self.messages['role']
-        result = messages.value_counts().to_dict()
-        result['total'] = len(self.messages)
-        return result
-
+        return self._info(use_sender=True)
+    
     @property
     def describe(self) -> Dict[str, Any]:
         """
-        Describes the conversation with various statistics and information.
+        Provides a descriptive summary of the conversation, including the total number of messages,
+        a summary by role, and the first five messages.
 
         Returns:
-            Dict[str, Any]: A dictionary containing information such as total number of messages, summary by role,
-                            and individual messages.
+            Dict[str, Any]: A dictionary containing the total number of messages, summary by role, and a list of the first maximum five message dictionaries.
         """
         return {
             "total_messages": len(self.messages),
-            "summary_by_role": self.info(),
+            "summary_by_role": self._info(),
             "messages": [
                 msg.to_dict() for _, msg in self.messages.iterrows()
-            ],
+            ][: self.len_messages -1 if self.len_messages < 5 else 5],
         }
 
-    def history(
-        self, begin_: Optional[datetime] = None, end_: Optional[datetime] = None
-    ) -> pd.DataFrame:
+    def clone(self, num: Optional[int] = None) -> 'Conversation':
         """
-        Retrieves a history of messages within a specified date range.
+        Creates a copy or multiple copies of the current Conversation instance.
 
         Args:
-            begin_ (Optional[datetime], optional): The start date of the message history. Defaults to None.
-            end_ (Optional[datetime], optional): The end date of the message history. Defaults to None.
+            num (Optional[int], optional): The number of copies to create. If None, a single copy is created.
+                                           Defaults to None.
 
         Returns:
-            pd.DataFrame: A DataFrame containing messages within the specified date range.
-        """
-        
-        if isinstance(begin_, str):
-            begin_ = datetime.strptime(begin_, '%Y-%m-%d')
-        if isinstance(end_, str):
-            end_ = datetime.strptime(end_, '%Y-%m-%d')
-        if begin_ and end_:
-            return self.messages[
-                (self.messages["timestamp"].dt.date >= begin_.date())
-                & (self.messages["timestamp"].dt.date <= end_.date())
-            ]
-        elif begin_:
-            return self.messages[(self.messages["timestamp"].dt.date >= begin_.date())]
-        elif end_:
-            return self.messages[(self.messages["timestamp"].dt.date <= end_.date())]
-        return self.messages
-
-    def clone(self) -> 'Conversation':
-        """
-        Creates a clone of the current conversation.
-
-        Returns:
-            Conversation: A new Conversation object that is a clone of the current conversation.
+            Conversation: A new Conversation instance or a list of Conversation instances if num is specified.
         """
         cloned = Conversation()
         cloned.logger.set_dir(self.logger.dir)
         cloned.messages = self.messages.copy()
+        if num:
+            return create_copy(cloned, num=num)
         return cloned
 
-    # def merge_conversation(self, other: 'Conversation', update: bool = False,) -> None:
-    #     """
-    #     Merges another conversation into the current one.
-    #
-    #     Args:
-    #         other (Conversation): The other conversation to merge with the current one.
-    #         update (bool, optional): If True, updates the first system message before merging. Defaults to False.
-    #     """
-    #     if update:
-    #         self.first_system = other.first_system.copy()
-    #     df = pd.concat([self.messages.copy(), other.messages.copy()], ignore_index=True)
-    #     self.messages = df.drop_duplicates().reset_index(drop=True, inplace=True)
-
-    def rollback(self, steps: int) -> None:
+    def add_message(
+        self,
+        system: Optional[Union[dict, list, System]] = None,
+        instruction: Optional[Union[dict, list, Instruction]] = None,
+        context: Optional[Union[str, Dict[str, Any]]] = None,
+        response: Optional[Union[dict, list, Response]] = None,
+        sender: Optional[str] = None
+    ) -> None:
         """
-        Rollbacks the conversation by a specified number of steps (messages).
+        Adds a message to the conversation.
 
         Args:
-            steps (int): The number of steps to rollback.
+            system (Optional[Union[dict, list, System]], optional): System message content or object.
+            instruction (Optional[Union[dict, list, Instruction]], optional): Instruction message content or object.
+            context (Optional[Union[str, Dict[str, Any]]], optional): Context for the message.
+            response (Optional[Union[dict, list, Response]], optional): Response message content or object.
+            sender (Optional[str], optional): The sender of the message.
 
         Raises:
-            ValueError: If steps are not a non-negative integer or greater than the number of messages.
+            ValueError: If the content cannot be converted to a JSON string.
         """
-        if steps < 0 or steps > len(self.messages):
-            raise ValueError("Steps must be a non-negative integer less than or equal to the number of messages.")
-        self.messages = self.messages[:-steps].reset_index(drop=True)
+        msg = self._create_message(
+            system=system, instruction=instruction, 
+            context=context, response=response, sender=sender
+        )
+        message_dict = msg.to_dict()
+        if isinstance(as_dict(message_dict['content']), dict):
+            message_dict['content'] = json.dumps(message_dict['content'])
+        message_dict['timestamp'] = datetime.now().isoformat()
+        self.messages.loc[len(self.messages)] = message_dict
+    
+    def remove_message(self, node_id: str) -> None:
+        """
+        Removes a message from the conversation based on its node_id.
 
-    def reset(self) -> None:
+        Args:
+            node_id (str): The node_id of the message to be removed.
         """
-        Resets the conversation, clearing all messages.
+        _remove_message(self.messages, node_id)
+    
+    def update_message(
+        self, value: Any, node_id: Optional[str] = None, col: str = 'node_id'
+    ) -> None:
         """
-        self.messages = pd.DataFrame(columns=self.messages.columns)
+        Updates a message in the conversation based on its node_id.
 
-    def to_csv(self, filepath: str, **kwargs) -> None:
+        Args:
+            value (Any): The new value to update the message with.
+            node_id (Optional[str], optional): The node_id of the message to be updated. Defaults to None.
+            col (str, optional): The column to be updated. Defaults to 'node_id'.
+
+        Returns:
+            bool: True if the update was successful, False otherwise.
         """
-        Exports the conversation messages to a CSV file.
+        return _update_row(self.messages, node_id=node_id, col=col, value=value)
+    
+    def change_first_system_message(
+        self, system: Union[str, Dict[str, Any], System], sender: Optional[str] = None
+    ):
+        """
+        Updates the first system message in the conversation.
 
         Args:
-            filepath (str): The file path where the CSV will be saved.
-            **kwargs: Additional keyword arguments for `pandas.DataFrame.to_csv` method.
+            system (Union[str, Dict[str, Any], System]): The new system message content, which can be a string,
+                                                         a dictionary of message content, or a System object.
+            sender (Optional[str], optional): The sender of the system message. Defaults to None.
+
+        Raises:
+            ValueError: If there are no system messages in the conversation or if the input cannot be
+                        converted into a system message.
         """
-        self.messages.to_csv(filepath, **kwargs)
+        if self.len_systems == 0:
+            raise ValueError("There is no system message in the messages.")
+        
+        if not isinstance(system, (str, Dict, System)):
+            raise ValueError("Input cannot be converted into a system message.")
+            
+        elif isinstance(system, (str, Dict)):
+            system = System(system, sender=sender)
+            
+        elif isinstance(system, System):
+            message_dict = system.to_dict()
+            if sender:
+                message_dict['sender'] = sender
+            message_dict['timestamp'] = datetime.now().isoformat()
+            sys_index = self.messages[self.messages.role == 'system'].index
+            self.messages.loc[sys_index[0]] = message_dict
 
-    def from_csv(self, filepath: str, **kwargs) -> None:
+    def rollback(self, steps: int) -> None:
+        """
+        Removes the last 'n' messages from the conversation.
+
+        Args:
+            steps (int): The number of messages to remove from the end of the conversation.
+
+        Raises:
+            ValueError: If 'steps' is not a positive integer or exceeds the number of messages.
+        """
+        return _remove_last_n_rows(self.messages, steps)
+
+    def clear_messages(self) -> None:
+        """
+        Clears all messages from the conversation, resetting it to an empty state.
+        """
+        self.messages = pd.DataFrame(columns=Conversation._cols)
+
+    def to_csv(self, filepath: str, **kwargs) -> None:
         """
-        Imports conversation messages from a CSV file.
+        Exports the conversation messages to a CSV file.
 
         Args:
-            filepath (str): The file path of the CSV to be read.
-            **kwargs: Additional keyword arguments for `pandas.read_csv` method.
+            filepath (str): The path to the file where the CSV will be saved.
+            **kwargs: Additional keyword arguments passed to pandas.DataFrame.to_csv() method.
         """
-        self.messages = pd.read_csv(filepath, **kwargs)
+        self.messages.to_csv(filepath, **kwargs)
 
     def to_json(self, filepath: str) -> None:
         """
         Exports the conversation messages to a JSON file.
 
         Args:
-            filepath (str): The file path where the JSON will be saved.
+            filepath (str): The path to the file where the JSON will be saved.
+            **kwargs: Additional keyword arguments passed to pandas.DataFrame.to_json() method, such as
+                      'orient', 'lines', and 'date_format'.
+
+        Note:
+            The recommended kwargs for compatibility with the from_json class method are
+            orient='records', lines=True, and date_format='iso'.
         """
         self.messages.to_json(
             filepath, orient="records", lines=True, date_format="iso")
 
-    def from_json(self, filepath: str) -> None:
+    def replace_keyword(
+        self,
+        keyword: str, 
+        replacement: str, 
+        col: str = 'content',
+        case_sensitive: bool = False
+    ) -> None:
         """
-        Imports conversation messages from a JSON file.
+        Replaces all occurrences of a keyword in a specified column of the conversation's messages with a given replacement.
 
         Args:
-            filepath (str): The file path of the JSON to be read.
+            keyword (str): The keyword to be replaced.
+            replacement (str): The string to replace the keyword with.
+            col (str, optional): The column where the replacement should occur. Defaults to 'content'.
+            case_sensitive (bool, optional): If True, the replacement is case sensitive. Defaults to False.
         """
-        self.reset()
-        self.messages = pd.read_json(filepath, orient="records", lines=True)
+        _replace_keyword(
+            self.messages, keyword, replacement, col=col, 
+            case_sensitive=case_sensitive
+        )
+        
+    def search_keywords(
+        self, 
+        keywords: Union[str, list],
+        case_sensitive: bool = False, reset_index: bool = False, dropna: bool = False
+    ) -> pd.DataFrame:
+        """
+        Searches for messages containing specified keywords within the conversation.
 
+        Args:
+            keywords (Union[str, list]): The keyword(s) to search for within the conversation's messages.
+            case_sensitive (bool, optional): If True, the search is case sensitive. Defaults to False.
+            reset_index (bool, optional): If True, resets the index of the resulting DataFrame. Defaults to False.
+            dropna (bool, optional): If True, drops messages with NA values before searching. Defaults to False.
+
+        Returns:
+            pd.DataFrame: A DataFrame containing messages that match the search criteria.
+        """
+        return _search_keywords(
+            self.messages, keywords, case_sensitive, reset_index, dropna
+        )
+        
     def extend(self, messages: pd.DataFrame, **kwargs) -> None:
         """
-        Extends the current conversation messages with additional messages from a DataFrame.
+        Extends the conversation by appending new messages, optionally avoiding duplicates based on specified criteria.
 
         Args:
-            messages (pd.DataFrame): The DataFrame containing messages to be added to the conversation.
-            kwargs: for pd.df.drop_duplicates
+            messages (pd.DataFrame): A DataFrame containing new messages to append to the conversation.
+            **kwargs: Additional keyword arguments for handling duplicates (passed to pandas' drop_duplicates method).
         """
+        self.messages = _extend(self.messages, messages, **kwargs)
         
-        validate_messages(messages)
+    def filter_by(
+        self,
+        role: Optional[str] = None, 
+        sender: Optional[str] = None,
+        start_time: Optional[datetime] = None,
+        end_time: Optional[datetime] = None,
+        content_keywords: Optional[Union[str, list]] = None,
+        case_sensitive: bool = False
+    ) -> pd.DataFrame:
+        """
+        Filters the conversation's messages based on specified criteria such as role, sender, time range, and keywords.
+
+        Args:
+            role (Optional[str]): Filter messages by role (e.g., 'user', 'assistant', 'system').
+            sender (Optional[str]): Filter messages by sender.
+            start_time (Optional[datetime]): Filter messages sent after this time.
+            end_time (Optional[datetime]): Filter messages sent before this time.
+            content_keywords (Optional[Union[str, list]]): Filter messages containing these keywords.
+            case_sensitive (bool, optional): If True, keyword search is case sensitive. Defaults to False.
+
+        Returns:
+            pd.DataFrame: A DataFrame containing messages that match the filter criteria.
+        """
+        return _filter_messages_by(
+            self.messages, role=role, sender=sender, 
+            start_time=start_time, end_time=end_time, 
+            content_keywords=content_keywords, case_sensitive=case_sensitive
+        )
+        
+    def _create_message(
+        self,
+        system: Optional[Union[dict, list, System]] = None,
+        instruction: Optional[Union[dict, list, Instruction]] = None,
+        context: Optional[Union[str, Dict[str, Any]]] = None,
+        response: Optional[Union[dict, list, Response]] = None,
+        sender: Optional[str] = None
+    ) -> Message:
+        """
+        Creates a message object based on the given parameters, ensuring only one message type is specified.
+
+        Args:
+            system (Optional[Union[dict, list, System]]): System message to be added.
+            instruction (Optional[Union[dict, list, Instruction]]): Instruction message to be added.
+            context (Optional[Union[str, Dict[str, Any]]]): Context for the instruction message.
+            response (Optional[Union[dict, list, Response]]): Response message to be added.
+            sender (Optional[str]): The sender of the message.
+
+        Returns:
+            Message: A Message object created from the provided parameters.
+
+        Raises:
+            ValueError: If more than one message type is specified or if the parameters do not form a valid message.
+        """
+        if sum(lcall([system, instruction, response], bool)) != 1:
+            raise ValueError("Error: Message must have one and only one role.")
+        
+        else:
+            if isinstance(any([system, instruction, response]), Message):
+                if system:
+                    return system
+                elif instruction:
+                    return instruction
+                elif response:
+                    return response
+
+            msg = 0
+            if response:
+                msg = Response(response=response, sender=sender)
+            elif instruction:
+                msg = Instruction(instruction=instruction, 
+                                  context=context, sender=sender)
+            elif system:
+                msg = System(system=system, sender=sender)
+            return msg
+
+    def _info(self, use_sender: bool = False) -> Dict[str, int]:
+        """
+        Generates a summary of the conversation's messages, either by role or sender.
+
+        Args:
+            use_sender (bool, optional): If True, generates the summary based on sender. If False, uses role. Defaults to False.
+
+        Returns:
+            Dict[str, int]: A dictionary with counts of messages, categorized either by role or sender.
+        """
+        messages = self.messages['sender'] if use_sender else self.messages['role']
+        result = messages.value_counts().to_dict()
+        result['total'] = len(self.len_messages)
+        return result
+
+def validate_messages(messages):
+    """
+    Validates the structure and content of a DataFrame containing conversation messages.
+
+    Args:
+        messages (pd.DataFrame): The DataFrame containing conversation messages to validate.
+
+    Returns:
+        bool: True if the DataFrame is valid, raises a ValueError otherwise.
+
+    Raises:
+        ValueError: If the DataFrame has unmatched columns, contains null values, has an unsupported role, or
+                    if the content cannot be parsed as a JSON string.
+    """
+    if list(messages.columns) != ['node_id', 'role', 'sender', 'timestamp', 'content']:
+        raise ValueError('Invalid messages dataframe. Unmatched columns.')
+    if messages.isnull().values.any():
+        raise ValueError('Invalid messages dataframe. Cannot have null.')
+    if not all(role in ['system', 'user', 'assistant'] for role in messages['role'].unique()):
+        raise ValueError('Invalid messages dataframe. Cannot have role other than ["system", "user", "assistant"].')
+    for cont in messages['content']:
+        if cont.startswith('Sender'):
+            cont = cont.split(':', 1)[1]
         try:
-            if len(messages.dropna(how='all')) > 0 and len(self.messages.dropna(how='all')) > 0:
-                self.messages = pd.concat([self.messages, messages], ignore_index=True)
-                self.messages.drop_duplicates(
-                    inplace=True, subset=['node_id'], keep='first', **kwargs
-                )
-                self.messages.reset_index(drop=True, inplace=True)
-                return
-        except Exception as e:
-            raise ValueError(f"Error in extending messages: {e}")
+            json.loads(cont)
+        except:
+            raise ValueError('Invalid messages dataframe. Content expect json string.')
+    return True
+
+def _sign_message(messages, sender: str):
+    """
+    Prefixes each message in the DataFrame with 'Sender <sender>:' to indicate the message's origin.
+
+    Args:
+        messages (pd.DataFrame): The DataFrame containing conversation messages to sign.
+        sender (str): The name or identifier of the sender to prefix the messages with.
+
+    Returns:
+        pd.DataFrame: The DataFrame with updated messages signed by the specified sender.
+
+    Raises:
+        ValueError: If the sender is None or equivalent to the string 'none'.
+    """
+    if sender is None or strip_lower(sender) == 'none':
+        raise ValueError("sender cannot be None")
+    df = messages.copy()
+
+    for i in df.index:
+        if not df.loc[i, 'content'].startswith('Sender'):
+            df.loc[i, 'content'] = f"Sender {sender}: {df.loc[i, 'content']}"
+        else:
+            content = df.loc[i, 'content'].split(':', 1)[1]
+            df.loc[i, 'content'] = f"Sender {sender}: {content}"
+            
+    return to_df(df)
+
+def _search_keywords(
+    messages, 
+    keywords: Union[str, list],
+    case_sensitive: bool = False, reset_index=False, dropna=False
+):
+    """
+    Searches for keywords in the 'content' column of a DataFrame and returns matching rows.
+
+    Args:
+        messages (pd.DataFrame): The DataFrame to search within.
+        keywords (Union[str, List[str]]): Keyword(s) to search for. If a list, combines keywords with an OR condition.
+        case_sensitive (bool, optional): Whether the search should be case-sensitive. Defaults to False.
+        reset_index (bool, optional): Whether to reset the index of the resulting DataFrame. Defaults to False.
+        dropna (bool, optional): Whether to drop rows with NA values in the 'content' column. Defaults to False.
+
+    Returns:
+        pd.DataFrame: A DataFrame containing rows where the 'content' column matches the search criteria.
+    """
+    out = ''
+    if isinstance(keywords, list):
+        keywords = '|'.join(keywords)
+    if not case_sensitive:
+        out = messages[
+            messages["content"].str.contains(keywords, case=False)
+        ]        
+    out = messages[messages["content"].str.contains(keywords)]
+    if reset_index or dropna:
+        out = to_df(out, reset_index=reset_index)
+    return out
+        
+def _filter_messages_by(
+    messages,
+    role: Optional[str] = None, 
+    sender: Optional[str] = None,
+    start_time: Optional[datetime] = None,
+    end_time: Optional[datetime] = None,
+    content_keywords: Optional[Union[str, list]] = None,
+    case_sensitive: bool = False
+) -> pd.DataFrame:
+    """
+    Filters messages in a DataFrame based on specified criteria such as role, sender, time range, and keywords.
+
+    Args:
+        messages (pd.DataFrame): The DataFrame of messages to filter.
+        role (Optional[str]): The role to filter messages by (e.g., 'user', 'assistant').
+        sender (Optional[str]): The sender to filter messages by.
+        start_time (Optional[datetime]): The start time for filtering messages.
+        end_time (Optional[datetime]): The end time for filtering messages.
+        content_keywords (Optional[Union[str, list]]): Keywords to filter messages by content.
+        case_sensitive (bool): Determines if the keyword search should be case-sensitive.
+
+    Returns:
+        pd.DataFrame: A DataFrame containing messages that match the filter criteria.
+
+    Raises:
+        ValueError: If an error occurs during the filtering process.
+    """
+
+    try:
+        outs = messages.copy()
+        
+        if content_keywords:
+            outs = _search_keywords(content_keywords, case_sensitive)
+        
+        outs = outs[outs['role'] == role] if role else outs
+        outs = outs[outs['sender'] == sender] if sender else outs
+        outs = outs[outs['timestamp'] > start_time] if start_time else outs
+        outs = outs[outs['timestamp'] < end_time] if end_time else outs
+    
+        return to_df(outs)
+    
+    except Exception as e:
+        raise ValueError(f"Error in filtering messages: {e}")
+
+def _replace_keyword(
+    df,
+    keyword: str, 
+    replacement: str, 
+    col='content',
+    case_sensitive: bool = False
+) -> None:
+    """
+    Replaces occurrences of a keyword within a specified column of a DataFrame with a given replacement.
+
+    Args:
+        df (pd.DataFrame): The DataFrame to operate on.
+        keyword (str): The keyword to search for and replace.
+        replacement (str): The string to replace the keyword with.
+        col (str): The column to search for the keyword in.
+        case_sensitive (bool): If True, the search and replacement are case-sensitive.
+
+    Returns:
+        None: This function modifies the DataFrame in place.
+    """
+    if not case_sensitive:
+        df[col] = df[col].str.replace(
+            keyword, replacement, case=False
+        )
+    else:
+        df[col] = df[col].str.replace(
+            keyword, replacement
+        )
+
+def _remove_message(df, node_id: str) -> bool:
+    """
+    Removes a message from the DataFrame based on its node_id.
+
+    Args:
+        df (pd.DataFrame): The DataFrame from which the message should be removed.
+        node_id (str): The node_id of the message to be removed.
+
+    Returns:
+        bool: True if the message was successfully removed, False otherwise.
+    """
+    initial_length = len(df)
+    df = df[df["node_id"] != node_id]
+    
+    return len(df) < initial_length
+
+def _update_row(
+    df, node_id = None, col = "node_id", value = None
+) -> bool:
+    """
+    Updates the value of a specified column for a row identified by node_id in a DataFrame.
+
+    Args:
+        df (pd.DataFrame): The DataFrame to update.
+        node_id (Optional[str]): The node_id of the row to be updated.
+        col (str): The column to update.
+        value (Any): The new value to be assigned to the column.
+
+    Returns:
+        bool: True if the update was successful, False otherwise.
+    """
+    index = df.index[df[col] == node_id].tolist()
+    if index:
+        df.at[index[0], col] = value
+        return True
+    return False
+
+def _remove_last_n_rows(df, steps: int) -> None:
+    """
+    Removes the last 'n' rows from a DataFrame.
+
+    Args:
+        df (pd.DataFrame): The DataFrame from which rows will be removed.
+        steps (int): The number of rows to remove.
+
+    Returns:
+        pd.DataFrame: The DataFrame after the last 'n' rows have been removed.
+
+    Raises:
+        ValueError: If 'steps' is less than 0 or greater than the number of rows in the DataFrame.
+    """
+    if steps < 0 or steps > len(df):
+        raise ValueError("Steps must be a non-negative integer less than or equal to the number of messages.")
+    df = to_df(df[:-steps])
+
+def get_rows(
+    df, 
+    sender: Optional[str] = None, 
+    role: Optional[str] = None, 
+    n: int = 1, 
+    sign_ = False, 
+    from_="front",
+) -> pd.DataFrame:
+    """
+    Retrieves rows from a DataFrame based on specified sender, role, and quantity, optionally signing them.
+
+    Args:
+        df (pd.DataFrame): The DataFrame to retrieve rows from.
+        sender (Optional[str]): The sender based on which to filter rows.
+        role (Optional[str]): The role based on which to filter rows.
+        n (int): The number of rows to retrieve.
+        sign_ (bool): Whether to sign the retrieved rows.
+        from_ (str): Direction to retrieve rows ('front' for the first rows, 'last' for the last rows).
+
+    Returns:
+        pd.DataFrame: A DataFrame containing the retrieved rows.
+    """
+
+    if from_ == "last":
+        if sender is None and role is None:
+            outs = df.iloc[-n:]
+        elif sender and role:
+            outs = df[(df['sender'] == sender) & (df['role'] == role)].iloc[-n:]
+        elif sender:
+            outs = df[df['sender'] == sender].iloc[-n:]
+        else:
+            outs = df[df['role'] == role].iloc[-n:]
+            
+    elif from_ == "front":
+        if sender is None and role is None:
+            outs = df.iloc[:n]
+        elif sender and role:
+            outs = df[(df['sender'] == sender) & (df['role'] == role)].iloc[:n]
+        elif sender:
+            outs = df[df['sender'] == sender].iloc[:n]
+        else:
+            outs = df[df['role'] == role].iloc[:n]
+
+    return _sign_message(outs, sender) if sign_ else outs
+
+def _extend(df1: pd.DataFrame, df2: pd.DataFrame, **kwargs) -> pd.DataFrame:
+    """
+    Extends a DataFrame with another DataFrame, optionally removing duplicates based on specified criteria.
+
+    Args:
+        df1 (pd.DataFrame): The original DataFrame to be extended.
+        df2 (pd.DataFrame): The DataFrame containing new rows to add to df1.
+        **kwargs: Additional keyword arguments for pandas.DataFrame.drop_duplicates().
+
+    Returns:
+        pd.DataFrame: The extended DataFrame after adding rows from df2 and removing duplicates.
+
+    Raises:
+        ValueError: If an error occurs during the extension process.
+    """
+    validate_messages(df2)
+    try:
+        if len(df2.dropna(how='all')) > 0 and len(df1.dropna(how='all')) > 0:
+            df = to_df([df1, df2])
+            df.drop_duplicates(
+                inplace=True, subset=['node_id'], keep='first', **kwargs
+            )
+            return to_df(df)
+    except Exception as e:
+        raise ValueError(f"Error in extending messages: {e}")
+