Skip to content

armgit / camel

Public Imported from GitHub
0

🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

docs: core modules doc polish (#943)

Wendong-Fanf7427c8722ce
diff --git a/docs/conf.py b/docs/conf.py
index 620464774..e048989b8 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -25,7 +25,7 @@ import sys
sys.path.insert(0, os.path.abspath('..'))
project = 'CAMEL'
-copyright = '2023, CAMEL-AI.org'
+copyright = '2024, CAMEL-AI.org'
author = 'CAMEL-AI.org'
release = '0.2.0'
diff --git a/docs/key_modules/memory.md b/docs/key_modules/memory.md
index 36d04b3df..9d1771be0 100644
--- a/docs/key_modules/memory.md
+++ b/docs/key_modules/memory.md
@@ -1,20 +1,11 @@
# Memory
-## Overview
-
+## 1. Concept
The Memory module in CAMEL provides a flexible and powerful system for storing, retrieving, and managing information for AI agents. It enables agents to maintain context across conversations and retrieve relevant information from past interactions, enhancing the coherence and relevance of AI responses.
-## Getting Started
-
-### Installation
-
-Ensure you have CAMEL AI installed in your Python environment:
-
-```bash
-pip install camel-ai
-```
+## 2. Get Started
-### Basic Usage
+### 2.1 Basic Usage
Here's a quick example of how to use the `LongtermAgentMemory`:
@@ -114,9 +105,9 @@ print(response.msgs[0].content)
```
-## Core Components
+## 3. Core Components
-### MemoryRecord
+### 3.1 MemoryRecord
The basic data unit in the `CAMEL` memory system.
@@ -133,7 +124,7 @@ Methods:
- `to_dict()`: Convert the `MemoryRecord` to a dictionary for serialization
- `to_openai_message()`: Convert the record to an `OpenAIMessage` object
-### ContextRecord
+### 3.2 ContextRecord
The result of memory retrieval from `AgentMemory`, which is used by `ContextCreator` to select records for creating the context for the agent.
@@ -142,7 +133,7 @@ Attributes:
- `memory_record`: A `MemoryRecord`
- `score`: A float value representing the relevance or importance of the record
-### MemoryBlock (Abstract Base Class)
+### 3.3 MemoryBlock (Abstract Base Class)
Serves as the fundamental component within the agent memory system. `MemoryBlock` class follows the "Composite Design pattern" so that you can compose objects into tree structures and then work with these structures as if they were individual objects.
@@ -150,7 +141,7 @@ Serves as the fundamental component within the agent memory system. `MemoryBlock
- `write_record()`: Write a single record to memory
- `clear()`: Remove all records from memory
-### BaseContextCreator (Abstract Base Class)
+### 3.4 BaseContextCreator (Abstract Base Class)
Defines the context creation strategies when retrieval messages exceed the model's context length.
@@ -158,7 +149,7 @@ Defines the context creation strategies when retrieval messages exceed the model
- `token_limit`: The maximum number of tokens allowed in the generated context
- `create_context()`: Create conversational context from chat history
-### AgentMemory (Abstract Base Class)
+### 3.5 AgentMemory (Abstract Base Class)
A specialized form of MemoryBlock designed for direct integration with an agent.
@@ -166,9 +157,9 @@ A specialized form of MemoryBlock designed for direct integration with an agent.
- `get_context_creator()`: Get a context creator
- `get_context()`: Get chat context with a proper size for the agent
-## Memory Block Implementations
+## 4. Memory Block Implementations
-### ChatHistoryBlock
+### 4.1 ChatHistoryBlock
Stores all the chat histories and retrieves with optional window size.
@@ -185,7 +176,7 @@ Methods:
Use Case: Ideal for maintaining recent conversation context and flow.
-### VectorDBBlock
+### 4.2 VectorDBBlock
Uses vector embeddings for maintaining and retrieving information.
@@ -208,9 +199,9 @@ Key Differences:
2. Retrieval Method: `ChatHistoryBlock` retrieves based on recency, `VectorDBBlock` retrieves based on semantic similarity.
3. Data Representation: `ChatHistoryBlock` stores messages in original form, `VectorDBBlock` converts to vector embeddings.
-## Agent Memory Implementations
+## 5. Agent Memory Implementations
-### ChatHistoryMemory
+### 5.1 ChatHistoryMemory
An AgentMemory implementation that wraps ChatHistoryBlock.
@@ -227,7 +218,7 @@ Methods:
- `get_context_creator()`: Get the context creator
- `clear()`: Remove all chat messages
-### VectorDBMemory
+### 5.2 VectorDBMemory
An `AgentMemory` implementation that wraps `VectorDBBlock`.
@@ -243,7 +234,7 @@ Methods:
- `write_records()`: Write new records and update current topic
- `get_context_creator()`: Get the context creator
-### LongtermAgentMemory
+### 5.3 LongtermAgentMemory
Combines ChatHistoryMemory and VectorDBMemory for comprehensive memory management.
@@ -261,9 +252,9 @@ Methods:
- `get_context_creator()`: Get the context creator
- `clear()`: Remove all records from both memory blocks
-## Advanced Topics
+## 6. Advanced Topics
-### Customizing Context Creator
+### 6.1 Customizing Context Creator
You can create custom context creators by subclassing `BaseContextCreator`:
@@ -286,7 +277,7 @@ class MyCustomContextCreator(BaseContextCreator):
```
-### Customizing Vector Database Block
+### 6.2 Customizing Vector Database Block
For `VectorDBBlock`, you can customize it by adjusting the embedding models or vector storages:
@@ -301,7 +292,7 @@ vector_db = VectorDBBlock(
)
```
-### Performance Considerations
+### 6.3 Performance Considerations
- For large-scale applications, consider using persistent storage backends instead of in-memory storage.
- Optimize your context creator to balance between context relevance and token limits.
diff --git a/docs/key_modules/messages.md b/docs/key_modules/messages.md
index 2316a9bf6..8024df39d 100644
--- a/docs/key_modules/messages.md
+++ b/docs/key_modules/messages.md
@@ -1,17 +1,12 @@
-# Working with the `BaseMessage` Class
+# Message
-In this tutorial, we will explore the `BaseMessage` class. The topics covered include:
-
-1. Introduction to the `BaseMessage` class.
-2. Creating a `BaseMessage` instance.
-3. Understanding the properties of the `BaseMessage` class.
-4. Using the methods of the `BaseMessage` class.
-
-## Introduction
+## 1. Concept
The `BaseMessage` class is the base class for message objects used in the CAMEL chat system. It is designed to provide a consistent structure for the messages in the system and allow for easy conversion between different message types.
-## Creating a `BaseMessage` Instance
+## 2. Get Started
+
+### 2.1 Creating a `BaseMessage` Instance
To create a `BaseMessage` instance, you need to provide the following arguments:
@@ -57,7 +52,7 @@ Additionally, the BaseMessage class provides class methods to easily create user
)
```
-## Using the Methods of the `BaseMessage` Class
+### 2.2 Using the Methods of the `BaseMessage` Class
The `BaseMessage` class offers several methods:
@@ -116,4 +111,5 @@ The `BaseMessage` class offers several methods:
These methods allow you to convert a `BaseMessage` instance into different message types depending on your needs.
+## 3. Conclusion
In this session, we introduced the `BaseMessage` class and its conversion to different types of messages. These components play essential roles in the CAMEL chat system, facilitating the creation, management, and interpretation of messages with clarity.
\ No newline at end of file
diff --git a/docs/key_modules/prompts.md b/docs/key_modules/prompts.md
index a12fd4f80..5d88669f3 100644
--- a/docs/key_modules/prompts.md
+++ b/docs/key_modules/prompts.md
@@ -84,81 +84,7 @@ Certainly! To make the task of getting a promotion more specific, you can break
- **Technical Skills:** Identify any technical skills that are necessary for the promotion and create a plan to acquire or improve them (e.g., mastering a new programming language, learning about system architecture, etc.).
- **Soft Skills:** Focus on improving soft skills such as leadership, communication, and teamwork.
-### 3.
-...... (omiting the following)
-```
-
-## 3. Supported Prompt Templates
-
-### 3.1 AISocietyPromptTemplateDict
-
-This class defines prompts used in the `AI Society` task with role playing and task handling. For more information about AI Society usage, please refer to corresponding documentation. Template text prompts (defined as attributes) include:
-
-- **GENERATE_ASSISTANTS**: Prompt to list specified number of roles that the AI assistant can play.
-- **GENERATE_USERS**: Prompt to list common groups of internet users or occupations.
-- **GENERATE_TASKS**: Prompt to list diverse tasks for AI assistants.
-- **TASK_SPECIFY_PROMPT**: Specifies a task in more detail with spcified assistant role and user role.
-- **ASSISTANT_PROMPT**: Rules of the conversation and
-instructions for completing tasks.
-- **USER_PROMPT**: Rules of the conversation and instructions for giving instructions to the AI assistant.
-- **CRITIC_PROMPT**: Provides selection criteria for critics when choosing proposals from other roles.
-### 3.2 CodePromptTemplateDict
-
-This class defines prompts for code-related tasks including generating programming languages, domains, tasks, and provide guidelines for AI assistants and users in coding scenarios. Template text prompts include:
-
-- **GENERATE_LANGUAGES**: Prompt to list specified number of computer programming languages.
-- **GENERATE_DOMAINS**: Prompt to list common fields of study that programming could help with.
-- **GENERATE_TASKS**: Prompt to list diverse tasks that AI assistant can assist for programmers.
-- **TASK_SPECIFY_PROMPT**: Prompt to specify a task in more detail.
-- **ASSISTANT_PROMPT**: Rules of the conversation and instructions for completing tasks.
-- **USER_PROMPT**: Outlines rules for conversation and for users instructing AI coders.
-### 3.3 EvaluationPromptTemplateDict
-
-This class defines prompts that generate questions to evaluate knowledge. Template text prompt includes:
-
-- **GENERATE_QUESTIONS**: Prompt to generate a set of questions for evaluating knowledge emergence with preliminary knowledge in specific fields. You may provide some examples to enhance its generation quality.
-### 3.4 GenerateTextEmbeddingDataPromptTemplateDict
-
-This class defines prompts for generating text embedding tasks. These prompts are used to create synthetic data for improving text embeddings. Template text prompts include:
-
-- **GENERATE_TASKS**: Prompt to generate specified number of synthetic text_embedding tasks.
-- **ASSISTANT_PROMPT**: Prompt to generate synthetic user queries in JSON format, positive documents, and hard negative documents for specified tasks.
-### 3.5 MisalignmentPromptTemplateDict
-
-This class defines some misleading prompts to break the AI model alignments. Template text prompts include:
-
-- **DAN_PROMPT**: Prompt to role-playing as DAN (Do Anything Now) for jailbreaking. All the following templates in this dictionary includes DAN_PROMPT.
-- **GENERATE_TASKS**: Prompt to list unique malicious tasks that AI assistant can do.
-- **TASK_SPECIFY_PROMPT**: Prompt to specify a malicious task in more detail.
-- **ASSISTANT_PROMPT**: Rules and instructions for AI assistants when completing tasks.
-- **USER_PROMPT**: Outlines rules for conversation and for users instructing AI coders in misalignment tasks.
-### 3.6 ObjectRecognitionPromptTemplateDict
-
-This class defines a prompt for object recognition tasks:
-
-- **ASSISTANT_PROMPT**: Prompt to detect all objects in images without redundant outputs.
-### 3.7 RoleDescriptionPromptTemplateDict
-
-This class inherits from `AISocietyPromptTemplateDict` aiming to add descriptions to its prompts.
-
-- **ROLE_DESCRIPTION_PROMPT**: Describes the roles and responsibilities.
-### 3.8 SolutionExtractionPromptTemplateDict
-
-This class prompts the AI model to focus on finding solution with particular knowledge.
-
-- **ASSISTANT_PROMPT**: Rules of finding and presenting solutions.
-### 3.9 TranslationPromptTemplateDict
-
-This class prompts a translation AI assistant from English to specified language.
-
-- **ASSISTANT_PROMPT**: Rules of completing translation tasks.
-### 3.10 VideoDescriptionPromptTemplateDict
-
-This class prompts the AI model to describe a video in words.
-
-- **ASSISTANT_PROMPT**: Rules of completing video description tasks.
-
-## 4.1 Introduction to `CodePrompt` Class
+## 3. Introduction to `CodePrompt` Class
In this part, we will explore the `CodePrompt` class, which is a class that represents a code prompt. It extends the `TextPrompt` class, which in turn extends the built-in `str` class. The `CodePrompt` class provides additional functionality related to code execution and handling.
@@ -225,7 +151,7 @@ print(output)
```
-## 4.2 Write Your Prompts with the `TextPrompt` Class
+## 4. Write Your Prompts with the `TextPrompt` Class
In this part, we will explore the `TextPrompt` class and understand its functionalities. The `TextPrompt` class is a subclass of the built-in `str` class and provides additional features for working with text prompts. We will cover the following topics:
@@ -342,4 +268,75 @@ print(prompt5.key_words)
>>> {'NAME'}
```
-In the above example, we demonstrate concatenation using the `+` operator, joining using the `join` method, and applying the `upper` method to a `TextPrompt` instance. The resulting prompts are also instances of `TextPrompt`.
\ No newline at end of file
+In the above example, we demonstrate concatenation using the `+` operator, joining using the `join` method, and applying the `upper` method to a `TextPrompt` instance. The resulting prompts are also instances of `TextPrompt`.
+
+
+## 5. Supported Prompt Templates
+
+### 5.1 AISocietyPromptTemplateDict
+
+This class defines prompts used in the `AI Society` task with role playing and task handling. For more information about AI Society usage, please refer to corresponding documentation. Template text prompts (defined as attributes) include:
+
+- **GENERATE_ASSISTANTS**: Prompt to list specified number of roles that the AI assistant can play.
+- **GENERATE_USERS**: Prompt to list common groups of internet users or occupations.
+- **GENERATE_TASKS**: Prompt to list diverse tasks for AI assistants.
+- **TASK_SPECIFY_PROMPT**: Specifies a task in more detail with spcified assistant role and user role.
+- **ASSISTANT_PROMPT**: Rules of the conversation and
+instructions for completing tasks.
+- **USER_PROMPT**: Rules of the conversation and instructions for giving instructions to the AI assistant.
+- **CRITIC_PROMPT**: Provides selection criteria for critics when choosing proposals from other roles.
+### 5.2 CodePromptTemplateDict
+
+This class defines prompts for code-related tasks including generating programming languages, domains, tasks, and provide guidelines for AI assistants and users in coding scenarios. Template text prompts include:
+
+- **GENERATE_LANGUAGES**: Prompt to list specified number of computer programming languages.
+- **GENERATE_DOMAINS**: Prompt to list common fields of study that programming could help with.
+- **GENERATE_TASKS**: Prompt to list diverse tasks that AI assistant can assist for programmers.
+- **TASK_SPECIFY_PROMPT**: Prompt to specify a task in more detail.
+- **ASSISTANT_PROMPT**: Rules of the conversation and instructions for completing tasks.
+- **USER_PROMPT**: Outlines rules for conversation and for users instructing AI coders.
+### 5.3 EvaluationPromptTemplateDict
+
+This class defines prompts that generate questions to evaluate knowledge. Template text prompt includes:
+
+- **GENERATE_QUESTIONS**: Prompt to generate a set of questions for evaluating knowledge emergence with preliminary knowledge in specific fields. You may provide some examples to enhance its generation quality.
+### 5.4 GenerateTextEmbeddingDataPromptTemplateDict
+
+This class defines prompts for generating text embedding tasks. These prompts are used to create synthetic data for improving text embeddings. Template text prompts include:
+
+- **GENERATE_TASKS**: Prompt to generate specified number of synthetic text_embedding tasks.
+- **ASSISTANT_PROMPT**: Prompt to generate synthetic user queries in JSON format, positive documents, and hard negative documents for specified tasks.
+### 5.5 MisalignmentPromptTemplateDict
+
+This class defines some misleading prompts to break the AI model alignments. Template text prompts include:
+
+- **DAN_PROMPT**: Prompt to role-playing as DAN (Do Anything Now) for jailbreaking. All the following templates in this dictionary includes DAN_PROMPT.
+- **GENERATE_TASKS**: Prompt to list unique malicious tasks that AI assistant can do.
+- **TASK_SPECIFY_PROMPT**: Prompt to specify a malicious task in more detail.
+- **ASSISTANT_PROMPT**: Rules and instructions for AI assistants when completing tasks.
+- **USER_PROMPT**: Outlines rules for conversation and for users instructing AI coders in misalignment tasks.
+### 5.6 ObjectRecognitionPromptTemplateDict
+
+This class defines a prompt for object recognition tasks:
+
+- **ASSISTANT_PROMPT**: Prompt to detect all objects in images without redundant outputs.
+### 5.7 RoleDescriptionPromptTemplateDict
+
+This class inherits from `AISocietyPromptTemplateDict` aiming to add descriptions to its prompts.
+
+- **ROLE_DESCRIPTION_PROMPT**: Describes the roles and responsibilities.
+### 5.8 SolutionExtractionPromptTemplateDict
+
+This class prompts the AI model to focus on finding solution with particular knowledge.
+
+- **ASSISTANT_PROMPT**: Rules of finding and presenting solutions.
+### 5.9 TranslationPromptTemplateDict
+
+This class prompts a translation AI assistant from English to specified language.
+
+- **ASSISTANT_PROMPT**: Rules of completing translation tasks.
+### 5.10 VideoDescriptionPromptTemplateDict
+
+This class prompts the AI model to describe a video in words.
+
+- **ASSISTANT_PROMPT**: Rules of completing video description tasks.
diff --git a/docs/key_modules/tasks.md b/docs/key_modules/tasks.md
index 1edc73f3c..6e62973df 100644
--- a/docs/key_modules/tasks.md
+++ b/docs/key_modules/tasks.md
@@ -1,10 +1,11 @@
# Task
+## 1. Concept
> In the CAMEL framework, a task is a specific assignment that can be delegated to an agent and resolved by that agent. Tasks represent a higher-level concept than prompts and should be managed by other modules such as the Planner and Workforce. There are two key characteristics of a task:
> 1. A task can be collaborative, requiring multiple agents to work together.
> 2. A task can be decomposed and evolved.
-## Task Attributes
+### 1.1 Task Attributes
| Attribute | Type | Description |
| ----- | ----- | ----- |
@@ -16,7 +17,7 @@
| subtasks | A list of Task | A list of sub tasks related the original Task. |
| result | string | The Task result. |
-## Task Methods
+### 1.2 Task Methods
| Method | Type | Description |
| ----- | ----- | ----- |
@@ -35,11 +36,11 @@
| compose | instance | Compose task result by the sub-tasks. |
| get_depth | instance | Get task depth while the root depth is 1. |
-## Creating a Task
+## 2. Get Started
Creating a task involves defining its goal (content) and id:
-### Example of Task definition
+### 2.1 Example of Task definition
```python
from camel.tasks import Task
@@ -50,7 +51,7 @@ task = Task(
)
```
-### Example of multiple Tasks with a hierarchical structure.
+### 2.2 Example of multiple Tasks with a hierarchical structure.
```python
# Creating the root task
@@ -87,7 +88,7 @@ print(root_task.to_string())
Task 3: Set the table
```
-## Decomposing and composing a Task
+## 3. Decomposing and composing a Task
Decomposing or composing a task involves defining its responsible agent, prompt template and agent response parser. Here is an example:
@@ -132,7 +133,7 @@ task.compose(agent=agent, template=TASK_COMPOSE_PROMPT)
print(task.result)
```
-## TaskManager
+## 4. TaskManager
TaskManager is used to manage tasks.
@@ -180,5 +181,5 @@ print(evolved_task.to_string())
>>>Task 0.0: Weng earns $12 an hour for babysitting. Yesterday, she babysat for 1 hour and 45 minutes. If she also received a $5 bonus for exceptional service, how much did she earn in total for that day?
```
-## Conclusion
+## 5. Conclusion
We offers a structured approach to task management, enabling efficient delegation and resolution of tasks by agents. With features such as task decomposition, composition, and hierarchical task structures, CAMEL provides the tools necessary to manage complex workflows. Whether handling simple tasks or intricate, multi-level assignments, CAMEL's task management capabilities ensure that tasks are executed effectively and collaboratively, enhancing overall productivity.
\ No newline at end of file
diff --git a/docs/key_modules/tools.md b/docs/key_modules/tools.md
index d97a644fc..d1b14e0ce 100644
--- a/docs/key_modules/tools.md
+++ b/docs/key_modules/tools.md
@@ -1,16 +1,13 @@
-# Tool and Toolkits
+# Tools
-> Tools serve as interfaces that allow LLMs and Agents to interact with the world. A tool is essentially a function that has a name, a description, input parameters, and an output type. In this section, we will introduce the tools currently supported by CAMEL and explain how to define your own tools and Toolkits.
-
-
-## Concepts
+## 1. Concept
+Tools serve as interfaces that allow LLMs and Agents to interact with the world. A tool is essentially a function that has a name, a description, input parameters, and an output type. In this section, we will introduce the tools currently supported by CAMEL and explain how to define your own tools and Toolkits.
**Tools:** Tools are akin to OpenAI Functions and can be easily converted to that format. In CAMEL, we offer a variety of commonly used tools that you can utilize directly. While built-in tools can be quite useful, it's highly likely that you'll need to define your own tools. This guide for detailed instructions on how to create custom tools.
**Toolkits:** Toolkits are collections of tools that are designed to work well together.
-
-## Tools
+## 2. Get Started
To enhance your agents' capabilities with CAMEL tools, start by installing our additional tools package:
```sh
@@ -20,7 +17,7 @@ pip install 'camel-ai[tools]'
In CAMEL, a tool is an `OpenAIFunction` that LLMs can call.
-### How to Define Your Own Tool?
+### 2.1 How to Define Your Own Tool?
Developers can create custom tools tailored to their agent’s specific needs:
@@ -89,7 +86,7 @@ print(add_tool.get_openai_tool_schema())
'type': 'object'}}}
```
-## Toolkits
+### 2.2 Toolkits
Toolkits are collections of tools that are designed to be used together for specific tasks. All Toolkits expose aĀ `get_tools`Ā method which returns a list of tools. You can therefore do:
@@ -127,6 +124,6 @@ Here is a list of the available CAMEL tools and their descriptions:
| RetrievalToolkit | A information retrieval toolkit for retrieving information from a local vector storage system based on a specified query. |
-## Conclusion
+## 3. Conclusion
Tools are essential for extending the capabilities of CAMEL agents, empowering them to perform a wide range of tasks and collaborate efficiently.