@ -7,24 +7,36 @@ The `Conversation` class is a powerful tool for managing and structuring convers
## Table of Contents
1. **Class Definition**
- Overview
- Attributes
2. **Methods**
- `__init__(self, time_enabled: bool = False, *args, **kwargs)`
- `add(self, role: str, content: str, *args, **kwargs)`
- `delete(self, index: str)`
- `update(self, index: str, role, content)`
- `query(self, index: str)`
- `search(self, keyword: str)`
- `display_conversation(self, detailed: bool = False)`
- `export_conversation(self, filename: str)`
- `import_conversation(self, filename: str)`
- `count_messages_by_role(self)`
- `return_history_as_string(self)`
- `save_as_json(self, filename: str)`
- `load_from_json(self, filename: str)`
- `search_keyword_in_conversation(self, keyword: str)`
- Initialization Parameters
2. **Core Methods**
- Message Management
- History Operations
- Export/Import
- Search and Query
- Cache Management
- Memory Management
3. **Advanced Features**
- Token Counting
- Memory Providers
- Caching System
- Batch Operations
---
@ -36,217 +48,303 @@ The `Conversation` class is designed to manage conversations by keeping track of
#### Attributes
- `time_enabled (bool)` : A flag indicating whether to enable timestamp recording for messages.
- `conversation_history (list)` : A list that stores messages in the conversation.
- `id (str)` : Unique identifier for the conversation
- `name (str)` : Name of the conversation
### 2. Methods
- `system_prompt (Optional[str])` : System prompt for the conversation
#### `__init__(self, time_enabled: bool = False, *args, **kwargs)`
- `time_enabled (bool)` : Flag to enable time tracking for messages
- **Description** : Initializes a new Conversation object.
- **Parameters** :
- `time_enabled (bool)` : If `True` , timestamps will be recorded for each message. Default is `False` .
- `autosave (bool)` : Flag to enable automatic saving
#### `add(self, role: str, content: str, *args, **kwargs)`
- `save_filepath (str)` : File path for saving conversation history
- **Description** : Adds a message to the conversation history.
- **Parameters** :
- `role (str)` : The role of the speaker (e.g., "user," "assistant").
- `content (str)` : The content of the message.
- `conversation_history (list)` : List storing conversation messages
#### `delete(self, index: str)`
- `tokenizer (Any)` : Tokenizer for counting tokens
- **Description** : Deletes a message from the conversation history.
- **Parameters** :
- `index (str)` : The index of the message to delete.
- `context_length (int)` : Maximum number of tokens allowed
- `rules (str)` : Rules for the conversation
- `custom_rules_prompt (str)` : Custom prompt for rules
- `user (str)` : User identifier for messages
- `auto_save (bool)` : Flag for auto-saving
- `save_as_yaml (bool)` : Flag to save as YAML
- `save_as_json_bool (bool)` : Flag to save as JSON
- `token_count (bool)` : Flag to enable token counting
- `cache_enabled (bool)` : Flag to enable prompt caching
- `cache_stats (dict)` : Statistics about cache usage
- `provider (Literal["mem0", "in-memory"])` : Memory provider type
#### Initialization Parameters
```python
conversation = Conversation(
id="unique_id", # Optional: Unique identifier
name="conversation_name", # Optional: Name of conversation
system_prompt="System message", # Optional: Initial system prompt
time_enabled=True, # Optional: Enable timestamps
autosave=True, # Optional: Enable auto-saving
save_filepath="path/to/save.json", # Optional: Save location
tokenizer=your_tokenizer, # Optional: Token counter
context_length=8192, # Optional: Max tokens
rules="conversation rules", # Optional: Rules
custom_rules_prompt="custom", # Optional: Custom rules
user="User:", # Optional: User identifier
auto_save=True, # Optional: Auto-save
save_as_yaml=True, # Optional: Save as YAML
save_as_json_bool=False, # Optional: Save as JSON
token_count=True, # Optional: Count tokens
cache_enabled=True, # Optional: Enable caching
conversations_dir="path/to/dir", # Optional: Cache directory
provider="in-memory" # Optional: Memory provider
)
```
#### `update(self, index: str, role, content)`
### 2. Core Methods
- **Description** : Updates a message in the conversation history.
- **Parameters** :
- `index (str)` : The index of the message to update.
- `role (_type_)` : The new role of the speaker.
- `content (_type_)` : The new content of the message.
#### Message Management
#### `query(self, index: str)`
##### `add(role: str, content: Union[str, dict, list], metadata: Optional[dict] = None)`
- **Description** : Retrieves a message from the conversation history.
- **Parameters** :
- `index (str)` : The index of the message to query.
- **Returns** : The message as a string.
Adds a message to the conversation history.
#### `search(self, keyword: str)`
```python
# Add a simple text message
conversation.add("user", "Hello, how are you?")
- **Description** : Searches for messages containing a specific keyword in the conversation history.
- **Parameters** :
- `keyword (str)` : The keyword to search for.
- **Returns** : A list of messages that contain the keyword.
# Add a structured message
conversation.add("assistant", {
"type": "response",
"content": "I'm doing well!"
})
#### `display_conversation(self, detailed: bool = False)`
# Add with metadata
conversation.add("user", "Hello", metadata={"timestamp": "2024-03-20"})
```
- **Description** : Displays the conversation history.
- **Parameters** :
- `detailed (bool, optional)` : If `True` , provides detailed information about each message. Default is `False` .
##### `add_multiple_messages(roles: List[str], contents: List[Union[str, dict, list]])`
#### `export_conversation(self, filename: str)`
Adds multiple messages at once.
- **Description** : Exports the conversation history to a text file.
- **Parameters** :
- `filename (str)` : The name of the file to export to.
```python
conversation.add_multiple_messages(
roles=["user", "assistant"],
contents=["Hello!", "Hi there!"]
)
```
#### `import_conversation(self, filename: str)`
##### `add_tool_output_to_agent(role: str, tool_output: dict )`
- **Description** : Imports a conversation history from a text file.
- **Parameters** :
- `filename (str)` : The name of the file to import from.
Adds a tool output to the conversation.
#### `count_messages_by_role(self)`
```python
conversation.add_tool_output_to_agent(
"tool",
{"name": "calculator", "result": "42"}
)
```
- **Description** : Counts the number of messages by role in the conversation.
- **Returns** : A dictionary containing the count of messages for each role.
#### History Operations
#### `return_history_as_string(self)`
##### `get_last_message_as_string() -> str `
- **Description** : Returns the entire conversation history as a single string.
- **Returns** : The conversation history as a string.
Returns the last message as a string.
#### `save_as_json(self, filename: str)`
```python
last_message = conversation.get_last_message_as_string()
# Returns: "assistant: Hello there!"
```
- **Description** : Saves the conversation history as a JSON file.
- **Parameters** :
- `filename (str)` : The name of the JSON file to save.
##### `get_final_message() -> str`
#### `load_from_json(self, filename: str)`
Returns the final message from the conversation.
- **Description** : Loads a conversation history from a JSON file.
- **Parameters** :
- `filename (str)` : The name of the JSON file to load.
```python
final_message = conversation.get_final_message()
# Returns: "assistant: Goodbye!"
```
#### `search_keyword_in_conversation(self, keyword: str) `
##### `get_final_message_content() -> str `
- **Description** : Searches for a keyword in the conversation history and returns matching messages.
- **Parameters** :
- `keyword (str)` : The keyword to search for.
- **Returns** : A list of messages containing the keyword.
Returns just the content of the final message.
## Examples
```python
final_content = conversation.get_final_message_content()
# Returns: "Goodbye!"
```
Here are some usage examples of the `Conversation` class:
##### `return_all_except_first() -> list`
### Creating a Conversation
Returns all messages except the first one.
```python
from swarms.structs import Conversation
messages = conversation.return_all_except_first()
```
##### `return_all_except_first_string() -> str`
Returns all messages except the first one as a string.
conv = Conversation()
```python
messages_str = conversation.return_all_except_first_string()
```
### Adding Messages
#### Export/Import
##### `to_json() -> str`
Converts conversation to JSON string.
```python
conv.add("user", "Hello, world!")
conv.add("assistant", "Hello, user!")
json_str = conversation.to_json()
```
### Displaying the Conversation
##### `to_dict() -> list`
Converts conversation to dictionary.
```python
conv.display_conversation ()
dict_data = conversation.to_dict ()
```
### Searching for Messages
##### `to_yaml() -> str`
Converts conversation to YAML string.
```python
result = conv.search("Hello" )
yaml_str = conversation.to_yaml( )
```
### Exporting and Importing Conversations
##### `return_json() -> str`
Returns conversation as formatted JSON string.
```python
conv.export_conversation("conversation.txt")
conv.import_conversation("conversation.txt")
json_str = conversation.return_json()
```
### Counting Messages by Role
#### Search and Query
##### `get_visible_messages(agent: "Agent", turn: int) -> List[Dict]`
Gets visible messages for a specific agent and turn.
```python
counts = conv.count_messages_by_role()
visible_msgs = conversation.get_visible_messages(agent, turn=1 )
```
### Loading and Saving as JSON
#### Cache Management
##### `get_cache_stats() -> Dict[str, int]`
Gets statistics about cache usage.
```python
conv.save_as_json("conversation.json")
conv.load_from_json("conversation.json")
stats = conversation.get_cache_stats()
# Returns: {
# "hits": 10,
# "misses": 5,
# "cached_tokens": 1000,
# "total_tokens": 2000,
# "hit_rate": 0.67
# }
```
Certainly! Let's continue with more examples and additional information about the `Conversation` class.
#### Memory Management
### Querying a Specific Message
##### `clear_memory()`
You can retrieve a specific message from the conversation by its index:
Clears the conversation memory.
```python
message = conv.query(0) # Retrieves the first message
conversation.clear_memory()
```
### Updating a Message
##### `clear()`
You can update a message's content or role within the conversation:
Clears the conversation history.
```python
conv.update(0, "user", "Hi there!") # Updates the first message
conversation.clear()
```
### Deleting a Message
### 3. Advanced Features
If you want to remove a message from the conversation, you can use the `delete` method:
#### Token Counting
The class supports automatic token counting when enabled:
```python
conv.delete(0) # Deletes the first message
conversation = Conversation(token_count=True)
conversation.add("user", "Hello world")
# Token count will be automatically calculated and stored
```
### Counting Messages by Role
#### Memory Providers
You can count the number of messages by role in the conversation :
The class supports different memory providers :
```python
counts = conv.count_messages_by_role()
# Example result: {'user': 2, 'assistant': 2}
# In-memory provider (default)
conversation = Conversation(provider="in-memory")
# Mem0 provider
conversation = Conversation(provider="mem0")
```
### Exporting and Importing as Text
#### Caching System
You can export the conversation to a text file and later import it :
The caching system can be enabled to improve performance :
```python
conv.export_conversation("conversation.txt") # Export
conv.import_conversation("conversation.txt") # Import
conversation = Conversation(cache_enabled=True)
# Messages will be cached for faster retrieval
```
### Exporting and Importing as JSON
#### Batch Operations
Conversations can also be saved and loaded as JSON files :
The class supports batch operations for efficiency :
```python
conv.save_as_json("conversation.json") # Save as JSON
conv.load_from_json("conversation.json") # Load from JSON
# Batch add messages
conversation.batch_add([
{"role": "user", "content": "Hello"},
{"role": "assistant", "content": "Hi"}
])
```
### Searching for a Keyword
### Class Methods
You can search for messages containing a specific keyword within the conversation:
#### `load_conversation(name: str, conversations_dir: Optional[str] = None) -> "Conversation"`
Loads a conversation from cache.
```python
results = conv.search_keyword_in_conversation("Hello ")
conversation = Conversation.load_conversation("my_conversation ")
```
#### `list_cached_conversations(conversations_dir: Optional[str] = None) -> List[str]`
Lists all cached conversations.
These examples demonstrate the versatility of the `Conversation` class in managing and interacting with conversation data. Whether you're building a chatbot, conducting analysis, or simply organizing dialogues, this class offers a robust set of tools to help you accomplish your goals.
```python
conversations = Conversation.list_cached_conversations()
```
## Conclusion
The `Conversation` class is a valuable utility for handling conversation data in Python. With its ability to add, update, delete, search, export, and import messages, you have the flexibility to work with conversations in various ways. Feel free to explore its features and adapt them to your specific projects and application s.
The `Conversation` class provides a comprehensive set of tools for managing conversations in Python applications. With support for multiple memory providers, caching, token counting, and various export formats, it's suitable for a wide range of use cases from simple chat applications to complex AI system s.
If you have any further questions or need additional assistance, please don't hesitate to ask!
For more information or specific use cases, please refer to the examples above or consult the source code.
Kye Gomez
3 weeks ago