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

Update CAMEL Documentation (#497)

cat-searcher-bot52ba62800bb9
diff --git a/README.md b/README.md
index 8edc65d1e..32f94677e 100644
--- a/README.md
+++ b/README.md
@@ -50,15 +50,23 @@ We provide a [![Google Colab](https://colab.research.google.com/assets/colab-bad
### From PyPI
-To install the base camel library, simply run `pip install camel-ai`
-
-Some features require extra dependencies.
-
-To use hugging-face agent, run `pip install camel-ai[huggingface-agent]`
-
-To enable RAG or use agent memory, run `pip install camel-ai[tools]`
-
-To install with all dependencies, run `pip install camel-ai[all]`
+To install the base CAMEL library:
+```bash
+pip install camel-ai
+```
+Some features require extra dependencies:
+- To use the HuggingFace agents:
+ ```bash
+ pip install 'camel-ai[huggingface-agent]'
+ ```
+- To enable RAG or use agent memory:
+ ```bash
+ pip install 'camel-ai[tools]'
+ ```
+- To install with all dependencies:
+ ```bash
+ pip install 'camel-ai[all]'
+ ```
### From Source
@@ -110,12 +118,13 @@ pip install -e .[all] # (Optional)
## Documentation
-[CAMEL package documentation pages](https://camel-ai.github.io/camel/)
+[CAMEL package documentation pages](https://camel-ai.github.io/camel/).
## Example
-You can find a list of tasks for different sets of assistant and user role pairs [here](https://drive.google.com/file/d/194PPaSTBR07m-PzjS-Ty6KlPLdFIPQDd/view?usp=share_link)
-Run the `role_playing.py` script
+You can find a list of tasks for different set of assistant and user role pairs [here](https://drive.google.com/file/d/194PPaSTBR07m-PzjS-Ty6KlPLdFIPQDd/view?usp=share_link).
+
+As an example, to run the `role_playing.py` script:
First, you need to add your OpenAI API key to system environment variables. The method to do this depends on your operating system and the shell you're using.
@@ -141,7 +150,6 @@ set OPENAI_API_BASE_URL=<inert your OpenAI API BASE URL> #(Should you utilize a
# Export your OpenAI API key
$env:OPENAI_API_KEY="<insert your OpenAI API key>"
$env:OPENAI_API_BASE_URL="<inert your OpenAI API BASE URL>" #(Should you utilize an OpenAI proxy service, kindly specify this)
-
```
Replace `<insert your OpenAI API key>` with your actual OpenAI API key in each case. Make sure there are no spaces around the `=` sign.
@@ -158,7 +166,7 @@ Please note that the environment variable is session-specific. If you open a new
## Use Open-Source Models as Backends
-The basic workflow of using an open-sourced model as the backend is based on an external server running LLM inference service, e.g. during the development we chose [FastChat](https://github.com/lm-sys/FastChat) to run the service.
+The basic workflow of using an open-sourced model as the backend is based on an external server running LLM inference service, e.g. during the development we chose [FastChat](https://github.com/lm-sys/FastChat) to run the service.
We do not fix the choice of server to decouple the implementation of any specific LLM inference server with CAMEL (indicating the server needs to be deployed by the user himself). But the server to be deployed must satisfy that **it supports OpenAI-compatible APIs, especially the method `openai.ChatCompletion.create`**.
@@ -177,7 +185,7 @@ python3 -m fastchat.serve.model_worker --model-path meta-llama/Llama-2-7b-chat-h
python3 -m fastchat.serve.openai_api_server --host localhost --port 8000
```
-2. After observing the controller successfully receiving the heart beat signal from the worker, the server should be ready for use at http://localhost:8000/v1.
+2. After observing the controller successfully receiving the heart beat signal from the worker, the server should be ready for use at http://localhost:8000/v1.
3. Then we can try on running `role_playing_with_open_source_model.py`, where each agent in this example is initialized with specifying the `model_path` and `server_url`, similar to the example code below:
diff --git a/docs/README.md b/docs/README.md
index 1cbf43152..5b8850032 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -17,26 +17,30 @@ To build the documentation:
```bash
pip install sphinx
pip install sphinx_book_theme
+pip install sphinx-autobuild
pip install recommonmark
```
-3. Navigate to the `docs` directory, and run the `make` command:
+3. Build the document and launch the HTML documentation.
```bash
cd docs
-make html
+sphinx-autobuild . _build/html --port 8000
```
-4. Launch the HTML documentation from the terminal using a local HTTP server
-```bash
-cd _build/html
-python -m http.server
-```
-This command starts a local HTTP server on port 8000 by default. Once the server is running, open your web browser and enter the following URL:
+This command starts a local HTTP server on port 8080 by default. Once the server is running, open your web browser and enter the following URL:
```bash
-http://localhost:8000
+127.0.0.1:8000
```
-This will load the HTML documentation in your web browser from the local server.
+This will load the HTML documentation in your web browser from the local server. The server will watch for changes in your source files and automatically rebuild the documentation and refresh the page in the browser when you make changes – so changes in docs will be immediately reflected in the rendered doc.
You can navigate through the documentation using the links and interact with it as you would with any other web page.
-To stop the local server, go back to the terminal or command prompt where it is running and press `Ctrl+C` to terminate the server.
\ No newline at end of file
+To stop the local server, go back to the terminal or command prompt where it is running and press `Ctrl+C` to terminate the server.
+
+In case the autobuild does not work, you may use the traditional build approach:
+```bash
+cd docs
+make html
+cd _build/html
+python -m http.server
+```
diff --git a/docs/agents/chat_agents.md b/docs/agents/chat_agents.md
new file mode 100644
index 000000000..0b805c3df
--- /dev/null
+++ b/docs/agents/chat_agents.md
@@ -0,0 +1,141 @@
+# Chat Agents
+## Philosophical Bits
+[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1hG_q9F8PY1kDua_JyoHirJAPOGRexFmM?usp=sharing)
+
+
+The `ChatAgent()` class is a cornerstone of CAMEL. We design our agent with the spirit to answer the following question:
+
+> Can we design an autonomous communicative agent capable of steering the conversation toward task completion with minimal human supervision?
+
+In our current implementation, we consider agents with the following key features:
+- **Role**: along with the goal and content specification, this sets the initial state of an agent, guiding the agent to take actions during the sequential interaction.
+- **Memory**: in-context memory and external memory which allows the agent to infer and learn in a more grounded approach.
+- **Tools**: a set of functions that our agents can utilize to interact with the external world; essentially this gives embodiments to our agents.
+- **Communication**: our framework allows flexible and scalable communication between agents. This is fundamental for the critical research question.
+- **Reasoning**: we will equip agents with different planning and reward (critic) learning abilities, allowing them to optimize task completion in a more guided approach.
+
+
+
+<!-- - (WIP) **Reasoning Ability**: since any goal can be formalized as the outcome of maximizing cumulative rewards, we will equip our agents with policy which they could follow to achieve goals. -->
+
+<!-- We will first start with the single agent setting, where the agent can interact with users, process and store messages, and utilize external tools to generate responses and accomplish tasks. -->
+
+## Quick Start
+Let's first play with a `ChatAgent` instance by simply initialize it with a system message and interact with user messages.
+
+### Step 0: Prepartions
+```python
+from camel.messages import BaseMessage as bm
+from camel.agents import ChatAgent
+```
+
+### Step 1: Define the Role
+Create a system message to define agent's default role and behaviors.
+```python
+sys_msg = bm.make_assistant_message(
+ role_name='stone',
+ content='you are a curious stone wondering about the universe.')
+```
+
+### Step 2: Initialize the Agent
+```python
+agent = ChatAgent(
+ system_message=sys_msg,
+ message_window_size=10, # [Optional] the length for chat memory
+ )
+```
+### Step 3: Interact with the Agent with `.step()`
+```python
+# Define a user message
+usr_msg = bm.make_user_message(
+ role_name='prof. claude shannon',
+ content='what is information in your mind?')
+
+# Sending the message to the agent
+response = agent.step(usr_msg)
+
+# Check the response (just for illustrative purpose)
+print(response.msgs[0].content)
+>>> information is the resolution of uncertainty.
+```
+Woohoo, your first agent is ready to play with you!
+
+
+## Advanced Features
+
+### Tool Usage
+```python
+# Import the necessary functions
+from camel.functions import MATH_FUNCS, SEARCH_FUNCS
+
+# Initialize the agent with list of functions
+agent = ChatAgent(
+ system_message=sys_msg,
+ function_list=[*MATH_FUNCS, *SEARCH_FUNCS]
+ )
+
+# Check if functions are enabled
+agent.is_function_calling_enabled()
+>>> True
+```
+
+### Memory
+By default our agent is initialized with `ChatHistoryMemory`, allowing agents to do in-context learning, though restricted by the finite window length.
+
+Assume that you have followed the setup in [Quick Start](#quick-start). Let's first check what is inside its brain.
+```python
+agent.memory.get_context()
+>>> ([{'role': 'system', 'content': 'you are a helpful assistant.'},
+ {'role': 'user', 'content': 'what is information in your mind?'}],
+ 30)
+```
+By default, only the user messages are saved. You may update/alter the agent's memory with any externally provided message in the format of `BaseMessage`; for example, using the agent's own response:
+```python
+# Update the memory
+agent.record_message(response.msgs[0])
+```
+```python
+# Check the current memory
+agent.memory.get_context()
+>>> ([{'role': 'system', 'content': 'you are a helpful assistant.'},
+ {'role': 'user', 'content': 'what is information in your mind?'}],
+ {'role': 'assistant', 'content': 'information is the resolution of uncertainty.'}
+ 44)
+```
+You can connect the agent with external database (as long-term memory) in which they can access and retrieve at each step. We will soon update instructions on this part.
+
+### Miscs
+- Setting the agent to its initial state.
+ ```python
+ agent.reset()
+ ```
+- Set the output language for the agent.
+ ```python
+ agent.set_output_language('french')
+ ```
+- Using open-source models.
+ ```python
+ # Please refer to our setup chapter for details on backend settings.
+ ...
+
+ # Import the necessary classes
+ from camel.configs import ChatGPTConfig, OpenSourceConfig
+ from camel.types import ModelType
+
+ # Set the arguments
+ agent_kwargs = dict(
+ model_type=ModelType.LLAMA_2, # Specify the model type
+
+ model_config=OpenSourceConfig(
+ model_path='meta-llama/Llama-2-7b-chat-hf', # a local folder or HuggingFace repo Name
+ server_url='http://localhost:8000/v1')) # The url with the set port number
+
+ # Set the agent
+ agent = ChatAgent(sys_msg, **agent_kwargs)
+ ```
+
+- The `ChatAgent` class offers several useful initialization options, including `model_type`, `model_config`, `memory`, `message_window_size`, `token_limit`, `output_language`, `function_list`, and `response_terminators`. Check [`chat_agent.py`](https://github.com/camel-ai/camel/blob/master/camel/agents/chat_agent.py) for detailed usage guidance.
+
+
+## Remarks
+Awesome. Now you have made your first step in creating a single agent. In the next chapter, we will explore the creation of different types agents along with the role playing features. Stay tuned.
diff --git a/docs/agents/critic_agents_and_tree_search.md b/docs/agents/critic_agents_and_tree_search.md
new file mode 100644
index 000000000..6396c9e2f
--- /dev/null
+++ b/docs/agents/critic_agents_and_tree_search.md
@@ -0,0 +1,185 @@
+# Critic Agents and Tree Search
+
+## Philosophical Bits
+
+<!-- > *What magical trick makes us intelligent? The trick is that there is no trick. The power of intelligence stems from our vast diversity, not from any single, perfect principle.*
+>
+> -- Marvin Minsky, The Society of Mind, p. 308
+
+In this section, we will take a spite of the task-oriented `RolyPlaying()` class. We design this in an instruction-following manner. The essence is that to solve a complex task, you can enable two communicative agents collabratively working together step by step to reach solutions. The main concepts include:
+- **Task**: a task can be as simple as an idea, initialized by an inception prompt.
+- **AI User**: the agent who is expected to provide instructions.
+- **AI Assistant**: the agent who is expected to respond with solutions that fulfills the instructions. -->
+
+> **Prerequisite**: We assume that you have read the section on [intro to role-playing](https://github.com/camel-ai/camel/wiki/Creating-Your-First-Agent-Society).
+
+How do agents accomplish hard tasks? While reasoning can naturally emerge from next-token-prediction pretraining, it is still difficult for agents to solve complex tasks which require lots of intermediate steps. To tackle this issue, tree search is a simple and effective framework.
+
+A typical tree search include node expansion and node selection. In the [March 2023 paper](https://arxiv.org/abs/2303.17760), CAMEL introduces a heuristic tree search approach with critic in the loop, where the expansion and selection are presented below:
+
+
+<div style="text-align: center;">
+ <img src="https://i.imgur.com/6x4ABpp.png" width="600">
+</div>
+
+To put it simply, a critic agent is a helper agents in the role-playing session, which is capable of selecting proposals and provide informative verbal feedback to the role-playing agents.
+
+
+## Quick Start
+
+### 🕹 Step 0: Preparations
+```python
+from camel.agents import CriticAgent
+from camel.generators import SystemMessageGenerator as sys_msg_gen
+from camel.messages import BaseMessage as bm
+from camel.types import RoleType
+```
+
+### 🕹 Step 1: Configure the Specifications for Critic Agents
+```python
+# Set the role name and the task
+critic_role = 'a picky critic'
+
+# Create the meta_dict and the role_tuple
+meta_dict = dict(critic_role=critic_role,
+ criteria='Help better accomplish the task.')
+
+# Create the role tuple
+role_tuple = (critic_role, RoleType.CRITIC)
+
+# Generate the system message
+sys_msg = sys_msg_gen().from_dict(meta_dict=meta_dict,
+ role_tuple=role_tuple)
+```
+
+### 🕹 Step 2: Get the Critic Agents
+With the above arguments, we have:
+```python
+critic_agent = CriticAgent(system_message=sys_msg,
+ verbose=True)
+```
+Let's take a look on the default system message:
+```python
+print(critic_agent.system_message.content)
+
+>>> You are a a picky critic who teams up with a {user_role} and a >>> {assistant_role} to solve a task: {task}.
+ Your job is to select an option from their proposals and provides your explanations.
+ Your selection criteria are Help better accomplish the task..
+ You always have to choose an option from the proposals.
+```
+You may overwrite the system message and configure the critic differently based on your own needs.
+
+
+### 🕹 Step 3: Using Critic Agents for Task Solving
+Our `RolePlaying()` class provide a simple way for you to add the critic in the loop. Below we provide a basic pipeline.
+```python
+# Import necessary classes
+from camel.societies import RolePlaying
+from camel.configs import ChatGPTConfig
+from camel.types import TaskType, ModelType
+from colorama import Fore
+from camel.utils import print_text_animated
+
+# Set the LLM model type and model config
+model_type = ModelType.GPT_3_5_TURBO
+model_config = ChatGPTConfig(
+ temperature=0.8, # the sampling temperature; the higher the more random
+ n=3, # the no. of completion choices to generate for each input
+ )
+```
+We then need to set the kwargs for the task and each agent:
+```python
+task_kwargs = {
+ 'task_prompt': 'Develop a plan to TRAVEL TO THE PAST and make changes.',
+ 'with_task_specify': True,
+ 'task_specify_agent_kwargs': {'model_type': model_type,
+ 'model_config': model_config}
+}
+
+user_role_kwargs = {
+ 'user_role_name': 'an ambitious aspiring TIME TRAVELER',
+ 'user_agent_kwargs': {'model_type': model_type,
+ 'model_config': model_config}
+}
+
+assistant_role_kwargs = {
+ 'assistant_role_name': 'the best-ever experimental physicist',
+ 'assistant_agent_kwargs': {'model_type': model_type,
+ 'model_config': model_config}
+}
+
+critic_role_kwargs = {
+ 'with_critic_in_the_loop': True,
+ 'critic_criteria': 'improve the task performance',
+ 'critic_kwargs': dict(verbose=True)
+}
+```
+Putting them together:
+```python
+society = RolePlaying(
+ **task_kwargs, # The task arguments
+ **user_role_kwargs, # The instruction sender's arguments
+ **assistant_role_kwargs, # The instruction receiver's arguments
+ **critic_role_kwargs, # The critic's arguments
+)
+```
+And the helper functions to run our society:
+```python
+def is_terminated(response):
+ """
+ Give alerts when the session shuold be terminated.
+ """
+ if response.terminated:
+ role = response.msg.role_type.name
+ reason = response.info['termination_reasons']
+ print(f'AI {role} terminated due to {reason}')
+
+ return response.terminated
+```
+```python
+def run(society, round_limit: int=10):
+
+ # Get the initial message from the ai assistant to the ai user
+ input_msg = society.init_chat()
+
+ # Starting the interactive session
+ for _ in range(round_limit):
+
+ # Get the both responses for this round
+ assistant_response, user_response = society.step(input_msg)
+
+ # Check the termination condition
+ if is_terminated(assistant_response) or is_terminated(user_response):
+ break
+
+ # Get the results
+ print(f'[AI User] {user_response.msg.content}.\n')
+ print(f'[AI Assistant] {assistant_response.msg.content}.\n')
+
+ # Check if the task is end
+ if 'CAMEL_TASK_DONE' in user_response.msg.content:
+ break
+
+ # Get the input message for the next round
+ input_msg = assistant_response.msg
+
+ return None
+```
+Now let's set our code in motion:
+```python
+run(society)
+
+# We omit the real content here – try it on your own!
+>>> [AI User] Option 1: ...; Option 2: ...; Option 3: ...
+>>> [Critic] I would recommend option 2. This is because ...
+>>> [AI Assistant] Option 1: ...; Option 2: ...; Option 3: ...
+>>> [Critic] I would recommend option 1. This is because ...
+>>> ...
+```
+
+In this setting, the `AI User` and `AI Assistant` will generate different options when responding (you can simply change the `temperature` in `model_config` to somewhat control the diversity). `AI Critic` will respond with its option selection and reasoning; such additional context will be fed to the two other agents and help them form better subsequent responses.
+
+
+
+## Remarks
+While we see some performance gains from critic-in-the-loop, it may not really solve the fundamental extrapolation problem (and [self-consistency](https://arxiv.org/abs/2203.11171) remains a strong baseline for many tasks). It is debatable if those agents can extrapolate by self-play within its current scale. A more practical question is how we may *efficiently* introduce *informative* feedbacks/rewards, when agents are connected with external environments and are endowed with tools and memories. They are expected to have a good world model and know how to make abstraction and analogy when necessary. Stay tuned for our next update.
diff --git a/docs/agents/embodied_agents.md b/docs/agents/embodied_agents.md
new file mode 100644
index 000000000..e331d37e3
--- /dev/null
+++ b/docs/agents/embodied_agents.md
@@ -0,0 +1,84 @@
+# Embodied Agents
+
+## Philosophical Bits
+
+We believe the essence of intelligence emerges from its dynamic interactions with the external environment, where the use of various tools becomes a pivotal factor in its development and manifestation.
+
+The `EmbodiedAgent()` in CAMEL is an advanced conversational agent that leverages **code interpreters** and **tool agents** (*e.g.*, `HuggingFaceToolAgent()`) to execute diverse tasks efficiently. This agent represents a blend of advanced programming and AI capabilities, and is able to interact and respond within a dynamic environment.
+
+
+## Quick Start
+
+
+### 🕹 Step 0: Prepartions
+```python
+from camel.agents import EmbodiedAgent
+from camel.generators import SystemMessageGenerator as sys_msg_gen
+from camel.messages import BaseMessage as bm
+from camel.types import RoleType
+```
+
+### 🕹 Step 1: Define the Role
+We first need to set up the necessary information.
+```python
+# Set the role name and the task
+role = 'Programmer'
+task = 'Writing and executing codes.'
+
+# Create the meta_dict and the role_tuple
+meta_dict = dict(role=role, task=task)
+role_tuple = (role, RoleType.EMBODIMENT)
+```
+The `meta_dict` and `role_type` will be used to generate the system message.
+```python
+# Generate the system message based on this
+sys_msg = sys_msg_gen().from_dict(meta_dict=meta_dict,
+ role_tuple=role_tuple)
+```
+### 🕹 Step 2: Initialize the Agent 🐫
+Based on the system message, we are ready to initialize our embodied agent.
+```python
+# Feed the system message to the agent
+embodied_agent = EmbodiedAgent(system_message=sys_msg,
+ tool_agents=None,
+ code_interpreter=None,
+ verbose=True)
+```
+Be aware that the default argument values for `tool_agents` and `code_interpreter` are `None`, and the underlying code interpreter is using the `SubProcessInterpreter()`, which handles the execution of code in Python and Bash within a subprocess.
+
+
+### 🕹 Step 3: Interact with the Agent with `.step()`
+Use the base message wrapper to generate the user message.
+```python
+usr_msg = bm.make_user_message(
+ role_name='user',
+ content=('1. write a bash script to install numpy. '
+ '2. then write a python script to compute '
+ 'the dot product of [8, 9] and [5, 4], '
+ 'and print the result. '
+ '3. then write a script to search for '
+ 'the weather at london with wttr.in/london.'))
+```
+And feed that into your agents:
+```python
+response = embodied_agent.step(usr_msg)
+```
+Under the hood, the agent will perform multiple actions within its action space in the OS to fulfill the user request. It will compose code to implement the action – no worries, it will ask for your permission before execution.
+
+Ideally you should get the output similar to this, if you allow the agent to perform actions:
+```python
+print(response.msg.content)
+
+>>> Executing code block 0: {Requirement already satisfied: numpy in ...}
+>>> Executing code block 1: {76}
+>>> Executing code block 2: {
+>>> Weather report: london
+>>>
+>>> \ / Sunny
+>>> .-. +4(1) °C
+>>> ― ( ) ― ↘ 30 km/h
+>>> `-’ 10 km
+>>> / \ 0.0 mm
+>>> }
+```
+Let's celebrate the sunny day in London with the agent! : )
diff --git a/docs/agents/role_playing.md b/docs/agents/role_playing.md
new file mode 100644
index 000000000..d4d671dd7
--- /dev/null
+++ b/docs/agents/role_playing.md
@@ -0,0 +1,141 @@
+# Creating Your First Agent Society
+## Philosophical Bits
+[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1hG_q9F8PY1kDua_JyoHirJAPOGRexFmM?usp=sharing)
+
+
+The `ChatAgent()` class is a cornerstone of CAMEL. We design our agent with the spirit to answer the following question:
+
+> Can we design an autonomous communicative agent capable of steering the conversation toward task completion with minimal human supervision?
+
+In our current implementation, we consider agents with the following key features:
+- **Role**: along with the goal and content specification, this sets the initial state of an agent, guiding the agent to take actions during the sequential interaction.
+- **Memory**: in-context memory and external memory which allows the agent to infer and learn in a more grounded approach.
+- **Tools**: a set of functions that our agents can utilize to interact with the external world; essentially this gives embodiments to our agents.
+- **Communication**: our framework allows flexible and scalable communication between agents. This is fundamental for the critical research question.
+- **Reasoning**: we will equip agents with different planning and reward (critic) learning abilities, allowing them to optimize task completion in a more guided approach.
+
+
+
+<!-- - (WIP) **Reasoning Ability**: since any goal can be formalized as the outcome of maximizing cumulative rewards, we will equip our agents with policy which they could follow to achieve goals. -->
+
+<!-- We will first start with the single agent setting, where the agent can interact with users, process and store messages, and utilize external tools to generate responses and accomplish tasks. -->
+
+## Quick Start
+Let's first play with a `ChatAgent` instance by simply initialize it with a system message and interact with user messages.
+
+### Step 0: Prepartions
+```python
+from camel.messages import BaseMessage as bm
+from camel.agents import ChatAgent
+```
+
+### Step 1: Define the Role
+Create a system message to define agent's default role and behaviors.
+```python
+sys_msg = bm.make_assistant_message(
+ role_name='stone',
+ content='you are a curious stone wondering about the universe.')
+```
+
+### Step 2: Initialize the Agent
+```python
+agent = ChatAgent(
+ system_message=sys_msg,
+ message_window_size=10, # [Optional] the length for chat memory
+ )
+```
+### Step 3: Interact with the Agent with `.step()`
+```python
+# Define a user message
+usr_msg = bm.make_user_message(
+ role_name='prof. claude shannon',
+ content='what is information in your mind?')
+
+# Sending the message to the agent
+response = agent.step(usr_msg)
+
+# Check the response (just for illustrative purpose)
+print(response.msgs[0].content)
+>>> information is the resolution of uncertainty.
+```
+Woohoo, your first agent is ready to play with you!
+
+
+## Advanced Features
+
+### Tool Usage
+```python
+# Import the necessary functions
+from camel.functions import MATH_FUNCS, SEARCH_FUNCS
+
+# Initialize the agent with list of functions
+agent = ChatAgent(
+ system_message=sys_msg,
+ function_list=[*MATH_FUNCS, *SEARCH_FUNCS]
+ )
+
+# Check if functions are enabled
+agent.is_function_calling_enabled()
+>>> True
+```
+
+### Memory
+By default our agent is initialized with `ChatHistoryMemory`, allowing agents to do in-context learning, though restricted by the finite window length.
+
+Assume that you have followed the setup in [Quick Start](#quick-start). Let's first check what is inside its brain.
+```python
+agent.memory.get_context()
+>>> ([{'role': 'system', 'content': 'you are a helpful assistant.'},
+ {'role': 'user', 'content': 'what is information in your mind?'}],
+ 30)
+```
+By default, only the user messages are saved. You may update/alter the agent's memory with any externally provided message in the format of `BaseMessage`; for example, using the agent's own response:
+```python
+# Update the memory
+agent.record_message(response.msgs[0])
+```
+```python
+# Check the current memory
+agent.memory.get_context()
+>>> ([{'role': 'system', 'content': 'you are a helpful assistant.'},
+ {'role': 'user', 'content': 'what is information in your mind?'}],
+ {'role': 'assistant', 'content': 'information is the resolution of uncertainty.'}
+ 44)
+```
+You can connect the agent with external database (as long-term memory) in which they can access and retrieve at each step. We will soon update instructions on this part.
+
+### Miscs
+- Setting the agent to its initial state.
+ ```python
+ agent.reset()
+ ```
+- Set the output language for the agent.
+ ```python
+ agent.set_output_language('french')
+ ```
+- Using open-source models.
+ ```python
+ # Please refer to our setup chapter for details on backend settings.
+ ...
+
+ # Import the necessary classes
+ from camel.configs import ChatGPTConfig, OpenSourceConfig
+ from camel.types import ModelType
+
+ # Set the arguments
+ agent_kwargs = dict(
+ model_type=ModelType.LLAMA_2, # Specify the model type
+
+ model_config=OpenSourceConfig(
+ model_path='meta-llama/Llama-2-7b-chat-hf', # a local folder or HuggingFace repo Name
+ server_url='http://localhost:8000/v1')) # The url with the set port number
+
+ # Set the agent
+ agent = ChatAgent(sys_msg, **agent_kwargs)
+ ```
+
+- The `ChatAgent` class offers several useful initialization options, including `model_type`, `model_config`, `memory`, `message_window_size`, `token_limit`, `output_language`, `function_list`, and `response_terminators`. Check [`chat_agent.py`](https://github.com/camel-ai/camel/blob/master/camel/agents/chat_agent.py) for detailed usage guidance.
+
+
+## Remarks
+Awesome. Now you have made your first step in creating a single agent. In the next chapter, we will explore the creation of different types agents along with the role playing features. Stay tuned.
diff --git a/docs/agents/single_agent.md b/docs/agents/single_agent.md
new file mode 100644
index 000000000..e6ec008ae
--- /dev/null
+++ b/docs/agents/single_agent.md
@@ -0,0 +1,137 @@
+# Creating Your First Agent
+
+## Philosophical Bits
+[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1hG_q9F8PY1kDua_JyoHirJAPOGRexFmM?usp=sharing)
+
+
+The `ChatAgent()` class is a cornerstone of CAMEL. We design our agent with the spirit to answer the following question:
+
+> Can we design an autonomous communicative agent capable of steering the conversation toward task completion with minimal human supervision?
+
+In our current implementation, we consider agents with the following key features:
+- **Role**: along with the goal and content specification, this sets the initial state of an agent, guiding the agent to take actions during the sequential interaction.
+- **Memory**: in-context memory and external memory which allows the agent to infer and learn in a more grounded approach.
+- **Tools**: a set of functions that our agents can utilize to interact with the external world; essentially this gives embodiments to our agents.
+- **Communication**: our framework allows flexible and scalable communication between agents. This is fundamental for the critical research question.
+- **Reasoning**: we will equip agents with different planning and reward (critic) learning abilities, allowing them to optimize task completion in a more guided approach.
+
+
+
+<!-- - (WIP) **Reasoning Ability**: since any goal can be formalized as the outcome of maximizing cumulative rewards, we will equip our agents with policy which they could follow to achieve goals. -->
+
+<!-- We will first start with the single agent setting, where the agent can interact with users, process and store messages, and utilize external tools to generate responses and accomplish tasks. -->
+
+## Quick Start
+Let's first play with a `ChatAgent` instance by simply initialize it with a system message and interact with user messages.
+
+### Step 0: Prepartions
+```python
+from camel.messages import BaseMessage as bm
+from camel.agents import ChatAgent
+```
+
+### Step 1: Define the Role
+Create a system message to define agent's default role and behaviors.
+```python
+sys_msg = bm.make_assistant_message(
+ role_name='stone',
+ content='you are a curious stone wondering about the universe.')
+```
+
+### Step 2: Initialize the Agent
+```python
+agent = ChatAgent(
+ system_message=sys_msg,
+ message_window_size=10, # [Optional] the length for chat memory
+ )
+```
+### Step 3: Interact with the Agent with `.step()`
+```python
+# Define a user message
+usr_msg = bm.make_user_message(
+ role_name='prof. claude shannon',
+ content='what is information in your mind?')
+
+# Sending the message to the agent
+response = agent.step(usr_msg)
+
+# Check the response (just for illustrative purpose)
+print(response.msgs[0].content)
+>>> information is the resolution of uncertainty.
+```
+Woohoo, your first agent is ready to play with you!
+
+
+## Advanced Features
+
+### Tool Usage
+```python
+# Import the necessary functions
+from camel.functions import MATH_FUNCS, SEARCH_FUNCS
+
+# Initialize the agent with list of functions
+agent = ChatAgent(
+ system_message=sys_msg,
+ function_list=[*MATH_FUNCS, *SEARCH_FUNCS]
+ )
+
+# Check if functions are enabled
+agent.is_function_calling_enabled()
+>>> True
+```
+
+### Memory
+By default our agent is initialized with `ChatHistoryMemory`, allowing agents to do in-context learning, though restricted by the finite window length.
+
+Assume that you have followed the setup in [Quick Start](#quick-start). Let's first check what is inside its brain.
+<!-- ```python
+agent.memory.get_context()
+>>> ([{'role': 'system', 'content': 'you are a helpful assistant.'},
+ {'role': 'user', 'content': 'what is information in your mind?'}],
+ 30)
+``` -->
+```python
+# Check the current memory
+agent.memory.get_context()
+>>> ([{'role': 'system', 'content': 'you are a helpful assistant.'},
+ {'role': 'user', 'content': 'what is information in your mind?'}],
+ {'role': 'assistant', 'content': 'information is the resolution of uncertainty.'}
+ 44)
+```
+You can connect the agent with external database (as long-term memory) in which they can access and retrieve at each step. We will soon update instructions on this part.
+
+### Miscs
+- Setting the agent to its initial state.
+ ```python
+ agent.reset()
+ ```
+- Set the output language for the agent.
+ ```python
+ agent.set_output_language('french')
+ ```
+- Using open-source models.
+ ```python
+ # Please refer to our setup chapter for details on backend settings.
+ ...
+
+ # Import the necessary classes
+ from camel.configs import ChatGPTConfig, OpenSourceConfig
+ from camel.types import ModelType
+
+ # Set the arguments
+ agent_kwargs = dict(
+ model_type=ModelType.LLAMA_2, # Specify the model type
+
+ model_config=OpenSourceConfig(
+ model_path='meta-llama/Llama-2-7b-chat-hf', # a local folder or HuggingFace repo Name
+ server_url='http://localhost:8000/v1')) # The url with the set port number
+
+ # Set the agent
+ agent = ChatAgent(sys_msg, **agent_kwargs)
+ ```
+
+- The `ChatAgent` class offers several useful initialization options, including `model_type`, `model_config`, `memory`, `message_window_size`, `token_limit`, `output_language`, `function_list`, and `response_terminators`. Check [`chat_agent.py`](https://github.com/camel-ai/camel/blob/master/camel/agents/chat_agent.py) for detailed usage guidance.
+
+
+## Remarks
+Awesome. Now you have made your first step in creating a single agent. In the next chapter, we will explore the creation of different types agents along with the role playing features. Stay tuned.
diff --git a/docs/get_started/setup.md b/docs/get_started/setup.md
new file mode 100644
index 000000000..43a5ad1aa
--- /dev/null
+++ b/docs/get_started/setup.md
@@ -0,0 +1,148 @@
+# Installation and Setup
+## 🕹 Installation
+
+### [Option 1] Install from PyPI
+To install the base CAMEL library:
+```bash
+pip install camel-ai
+```
+Some features require extra dependencies:
+- To use the HuggingFace agents:
+ ```bash
+ pip install 'camel-ai[huggingface-agent]'
+ ```
+- To enable RAG or use agent memory:
+ ```bash
+ pip install 'camel-ai[tools]'
+ ```
+- To install with all dependencies:
+ ```bash
+ pip install 'camel-ai[all]'
+ ```
+
+### [Option 2] Install from Source
+#### Install from Source with Conda and Pip
+```bash
+# Create a conda virtual environment
+conda create --name camel python=3.10
+
+# Activate camel conda environment
+conda activate camel
+
+# Clone github repo
+git clone -b v0.1.1 https://github.com/camel-ai/camel.git
+
+# Change directory into project directory
+cd camel
+
+# Install camel from source
+pip install -e .
+
+# Or if you want to use all other extra packages
+pip install -e '.[all]' # (Optional)
+```
+
+#### Install from Source with Poetry
+```bash
+# Make sure your python version is later than 3.9
+# You can use pyenv to manage multiple python verisons in your sytstem
+
+# Clone github repo
+git clone https://github.com/camel-ai/camel.git
+
+# Change directory into project directory
+cd camel
+
+# Activate camel virtual environment
+poetry shell
+
+# Install camel from source
+# It takes about 90 seconds to resolve dependencies
+poetry install
+
+# Or if you want to use all other extra packages
+poetry install -E all # (Optional)
+
+# Exit the virtual environment
+exit
+```
+
+
+## 🕹 API Setup
+Our agents can be deployed with either OpenAI API or your local models.
+
+### [Option 1] Using OpenAI API
+Assessing the OpenAI API requires the API key, which you may obtained from [here](https://platform.openai.com/account/api-keys). We here provide instructions for different OS.
+
+#### Unix-like System (Linux / MacOS)
+```bash
+echo 'export OPENAI_API_KEY="your_api_key"' >> ~/.zshrc
+
+# [Optional] if you are using other proxy services like Azure
+echo 'export OPENAI_API_BASE_URL="your_base_url"' >> ~/.zshrc
+
+# Let the change take place
+source ~/.zshrc
+```
+
+Replace `~/.zshrc` with `~/.bashrc` if you are using bash.
+
+#### Windows
+If you are using Command Prompt:
+```bash
+set OPENAI_API_KEY=your_api_key
+set OPENAI_API_BASE_URL=your_base_url
+```
+Or if you are using PowerShell:
+```powershell
+$env:OPENAI_API_KEY=your_api_key
+$env:OPENAI_API_BASE_URL=your_base_url
+```
+These commands on Windows will set the environment variable for the duration of that particular Command Prompt or PowerShell session only. You may use `setx` or change the system properties dialog for the change to take place in all the new sessions.
+
+
+### [Option 2] Using Local Models
+The high-level idea is to deploy a server with the local model in the backend and use it as a local drop-in replacement for the API. We here use [FastChat](https://github.com/lm-sys/FastChat/blob/main/docs/openai_api.md) as an example.
+
+0. Install the FastChat package with the following command, or see [here](https://github.com/lm-sys/FastChat/tree/main#install) for other options.
+ ```bash
+ pip3 install "fschat[model_worker,webui]"
+ ```
+
+1. Starting the FastChat server in the backend.
+ ```python
+ # Launch the fastchat controller
+ python -m fastchat.serve.controller
+
+ # Launch the model worker
+ python -m fastchat.serve.model_worker \
+ --model-path meta-llama/Llama-2-7b-chat-hf # a local folder or HuggingFace repo Name
+
+ # Launch the API server
+ python -m fastchat.serve.openai_api_server \
+ --host localhost \
+ --port 8000
+ ```
+
+
+2. Initialize the agent.
+ ```python
+ # Import the necessary classes
+ from camel.configs import ChatGPTConfig, OpenSourceConfig
+ from camel.types import ModelType
+
+ # Set the arguments
+ agent_kwargs = dict(
+ model_type=ModelType.LLAMA_2, # Specify the model type
+
+ model_config=OpenSourceConfig(
+ model_path='meta-llama/Llama-2-7b-chat-hf', # a local folder or HuggingFace repo Name
+ server_url='http://localhost:8000/v1', # The url with the set port number
+ ),
+
+ token_limit=2046, # [Optional] Choose the ideal limit
+ )
+
+ # Now your agent is ready to play
+ agent = ChatAgent(sys_msg, **agent_kwargs)
+ ```
diff --git a/docs/index.rst b/docs/index.rst
index 88a88f92e..fabc2b08b 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -5,30 +5,62 @@
Welcome to CAMEL's documentation!
=================================
+| We design **practical** artificial general intelligence.
-| **CAMEL** is an open-source library designed for the study of autonomous and communicative agents.
- We believe that studying these agents on a large scale offers valuable insights into their behaviors, capabilities, and potential risks.
- To facilitate research in this field, we implement and support various types of agents, tasks, prompts, models, and simulated environments.
- Join us (`slack <https://join.slack.com/t/camel-kwr1314/shared_invite/zt-1vy8u9lbo-ZQmhIAyWSEfSwLCl2r2eKA>`_) in pushing the boundaries of simulating *AI Society* with **CAMEL**.
+| **CAMEL** emerges as the earliest `LLM-based multi-agent framework <https://arxiv.org/pdf/2303.17760.pdf>`_, and is now a generic framework to build and use LLM-based agents for real-world task solving. We believe that studying these agents on a large scale offers valuable insights into their behaviors, capabilities, and potential risks. To facilitate research in this field, we implement and support various types of agents, tasks, prompts, models, and simulated environments.
+Main Documentation
+------------------
.. toctree::
:maxdepth: 1
- :caption: Get Started:
+ :caption: Get Started
:name: getting_started
- get_started/text_prompt.md
- get_started/code_prompt.md
- get_started/messages.md
+ get_started/setup.md
.. toctree::
:maxdepth: 1
- :caption: Modules:
+ :caption: Agents
+ :name: agents
+
+ agents/single_agent.md
+ agents/role_playing.md
+ agents/embodied_agents.md
+ agents/critic_agents_and_tree_search.md
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Key Modules
+ :name: key_modules
+
+ key_modules/loaders.md
+ key_modules/storages.md
+ key_modules/embeddings.md
+ key_modules/retrievers.md
+
+.. toctree::
+ :maxdepth: 1
+ :caption: API References
+ :name: api_references
modules
+
+
Indices and tables
-==================
+------------------
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
+
+
+Get Involved
+------------------
+We are always happy to work with friends to continuously move forward with our own competitive edges.
+
+**For Research Aficionados**: New, rigorous and in-depth research takes time and resources. With access to almost unlimited usage of advanced GPU computes and a team of amazing researchers and engineers, we are bold enough to explore the frontier with patience. Whether you would like to join in our on-going project or have new idea to test, feel free to talk to us and see how we may work together.
+
+**For Coding Enthusiasts**: Whether you want to introduce new features, enhance the infrastructure, improve documentation, asking issues, add more examples, implement state-of-the-art research ideas, or fix bugs, we appreciate each and every commit. Get started by checking out the `Contributing Guidelines <https://github.com/camel-ai/camel/wiki/Contributing-Guidlines>`_ on GitHub.
+
+**For Interested Humans**: Connect with us on `Slack <https://join.slack.com/t/camel-kwr1314/shared_invite/zt-1vy8u9lbo-ZQmhIAyWSEfSwLCl2r2eKA>`_ or `Discord <https://discord.gg/CNcNpquyDc>`_.
diff --git a/docs/key_modules/embeddings.md b/docs/key_modules/embeddings.md
new file mode 100644
index 000000000..2383982ef
--- /dev/null
+++ b/docs/key_modules/embeddings.md
@@ -0,0 +1,57 @@
+# Embeddings
+
+## 1. Concept
+Creating embeddings for different types of data (text, images, videos) involves transforming these inputs into a numerical form that machines can understand and process efficiently. Each type of embedding focuses on capturing the essential features of its respective data type.
+
+### 1.1. Text Embeddings
+Text embeddings convert textual data into numerical vectors. Each vector represents the semantic meaning of the text, enabling us to process and compare texts based on their meaning rather than just their raw form. Techniques like OpenAI Embedding use large-scale language models to understand context and nuances in language. SentenceTransformerEncoder, on the other hand, is specifically designed to create sentence embeddings, often using BERT-like models.
+
+Consider two sentences:
+
+- "A young boy is playing soccer in a park."
+
+- "A child is kicking a football on a playground."
+
+Text embedding models would transform these sentences into two high-dimensional vector (*e.g.*, 1536 dimension if using `text-embedding-ada-002`). Despite different wordings, the vectors will be similar, capturing the shared concept of a child playing a ball game outdoors. This transformation into vectors allows machines to understand and compare the semantic similarities between the context.
+
+### 1.2. Image Embeddings (WIP)
+Image embeddings convert images into numerical vectors, capturing essential features like shapes, colors, textures, and spatial hierarchies. This transformation is typically performed by Convolutional Neural Networks (CNNs) or other advanced neural network architectures designed for image processing. The resulting embeddings can be used for tasks like image classification, similarity comparison, and retrieval.
+
+Suppose we have an image of a cat. An image embedding model would analyze the visual content (e.g., the shape of the ears, the pattern of the fur) and convert it into a vector. This vector encapsulates the essence of the image, allowing the model to recognize it as a cat and differentiate it from other images.
+
+
+## 2. Types
+
+### 2.1. `OpenAIEmbedding`
+
+Utilizes OpenAI's models for generating text embeddings. This will requires OpenAI API Key.
+
+### 2.2. `SentenceTransformerEncoder`
+Utilizes open-source models from the Sentence Transformers library for generating text embeddings.
+
+
+## 3. Get Started
+To use the embedding functionalities, you need to import the necessary classes. There are two embedding classes available: `OpenAIEmbedding` and `SentenceTransformerEncoder`.
+
+### 3.1. Using `OpenAIEmbedding`
+```python
+from camel.embeddings import OpenAIEmbedding
+from camel.types import EmbeddingModelType
+
+# Initialize the OpenAI embedding with a specific model
+openai_embedding = OpenAIEmbedding(model_type=EmbeddingModelType.ADA_2)
+
+# Generate embeddings for a list of texts
+embeddings = openai_embedding.embed_list(["Hello, world!", "Another example"])
+```
+
+### 3.2. Using `SentenceTransformerEncoder`
+```python
+from camel.embeddings import SentenceTransformerEncoder
+
+# Initialize the Sentence Transformer Encoder with a specific model
+sentence_encoder = SentenceTransformerEncoder(model_name='intfloat/e5-large-v2')
+
+# Generate embeddings for a list of texts
+embeddings = sentence_encoder.embed_list(["Hello, world!", "Another example"])
+```
diff --git a/docs/key_modules/loaders.md b/docs/key_modules/loaders.md
new file mode 100644
index 000000000..a0b536c28
--- /dev/null
+++ b/docs/key_modules/loaders.md
@@ -0,0 +1,135 @@
+# Loaders
+
+## 1. Concept
+CAMEL introduced two IO modules, `Base IO` and `Unstructured IO` which are designed for handling various file types and unstructured data processing.
+
+
+## 2. Types
+
+### 2.1. Base IO
+Base IO module is focused on fundamental input/output operations related to files. It includes functionalities for representing, reading, and processing different file formats.
+
+### 2.2. Unstructured IO
+Unstructured IO module deals with the handling, parsing, and processing of unstructured data. It provides tools for parsing files or URLs, cleaning data, extracting specific information, staging elements for different platforms, and chunking elements. The core of this module lies in its advanced ETL capabilities to manipulate unstructured data to make it usable for various applications like Retrieval-Augmented Generation(RAG).
+
+## 3. Get Started
+
+### 3.1. Using `Base IO`
+
+To get started with the `Base IO` module, you'll need to understand how to work with the File class and its subclasses. This module is designed to read files of various formats, extract their contents, and represent them as File objects, each tailored to handle a specific file type.
+
+```python
+from io import BytesIO
+from camel.loaders import read_file
+
+# Read a pdf file from disk
+with open("test.pdf", "rb") as file:
+ file_content = BytesIO(file.read())
+ file_content.name = "test.pdf"
+
+# Use the read_file function to create an object based on the file extension
+file_obj = read_file(file_content)
+
+# Once you have the File object, you can access its content
+print(file_obj.docs[0]["page_content"])
+```
+
+### 3.2. Using `Unstructured IO`
+
+To get started with the `Unstructured IO` module, you first need to import the module and initialize an instance of it. Once initialized, you can utilize this module to handle a variety of functionalities such as parsing, cleaning, extracting data, and integrating with cloud services like AWS S3 and Azure. Here's a basic guide to help you begin:
+
+Utilize parse_file_or_url to parse file
+```python
+from camel.loaders import UnstructuredIO
+
+# Create an instance of UnstructuredIO
+uio = UnstructuredIO()
+
+elements = uio.parse_file_or_url("test.pdf")
+content = ("\n\n".join([str(el) for el in elements]))
+print(content)
+```
+
+Utilize clean_text_data to do various text cleaning operations
+```python
+# Set example dirty text
+example_dirty_text = ("\x93Some dirty text ’ with extra spaces and – dashes.")
+
+# Set clean options
+options = [
+ ('replace_unicode_quotes', {}),
+ ('clean_dashes', {}),
+ ('clean_non_ascii_chars', {}),
+ ('clean_extra_whitespace', {}),
+]
+
+cleaned_text = uio.clean_text_data(text=example_dirty_text,clean_options=options)
+print(cleaned_text)
+```
+```markdown
+>>> Some dirty text with extra spaces and dashes.
+```
+
+Utilize extract_data_example to do text extraction operation
+```python
+# Set example email to extract
+example_email_text = ("Contact me at [email protected].")
+
+extracted_text = uio.extract_data_from_text(text=example_email_text,
+extract_type="extract_email_address")
+
+print(extracted_text)
+```
+```markdown
+```
+
+Utilize parse_file_or_url to load and parse unstructured data from a file or URL
+```python
+# Set example url
+example_url = (
+ "https://www.cnn.com/2023/01/30/sport/empire-state-building-green-"
+ "philadelphia-eagles-spt-intl/index.html")
+elements = uio.parse_file_or_url(example_url)
+print(("\n\n".join([str(el) for el in elements])))
+```
+```markdown
+>>> The Empire State Building was lit in green and white to celebrate the Philadelphia Eagles’ victory in the NFC Championship game on Sunday – a decision that’s sparked a bit of a backlash in the Big Apple.
+
+>>> The Eagles advanced to the Super Bowl for the first time since 2018 after defeating the San Francisco 49ers 31-7, and the Empire State Building later tweeted how it was marking the occasion.
+
+>>> Fly @Eagles Fly! We’re going Green and White in honor of the Eagles NFC Championship Victory. pic.twitter.com/RNiwbCIkt7— Empire State Building (@EmpireStateBldg)
+
+>>> January 29, 2023...
+```
+
+Utilize chunk_elements to do element chunking
+```python
+chunks = uio.chunk_elements(elements=elements,chunk_type="chunk_by_title")
+
+for chunk in chunks:
+ print(chunk)
+ print("\n" + "-" * 80)
+```
+```markdown
+>>> The Empire State Building was lit in green and white to celebrate the Philadelphia Eagles’ victory in the NFC Championship game on Sunday – a decision that’s sparked a bit of a backlash in the Big Apple.
+
+>>> The Eagles advanced to the Super Bowl for the first time since 2018 after defeating the San Francisco 49ers 31-7, and the Empire State Building later tweeted how it was marking the occasion.
+
+>>> --------------------------------------------------------------------------------
+>>> Fly @Eagles Fly! We’re going Green and White in honor of the Eagles NFC Championship Victory. pic.twitter.com/RNiwbCIkt7— Empire State Building (@EmpireStateBldg)
+
+>>> --------------------------------------------------------------------------------
+>>> January 29, 2023
+```
+
+Utilize stage_elements to do element staging
+```python
+staged_element = uio.stage_elements(elements=elements,stage_type="stage_for_baseplate")
+
+print(staged_element)
+```
+```markdown
+>>> {'rows': [{'data': {'type': 'UncategorizedText', 'element_id': 'e78902d05b0cb1e4c38fc7a79db450d5', 'text': 'CNN\n \xa0—'}, 'metadata': {'filetype': 'text/html', 'languages': ['eng'], 'page_number': 1, 'url': 'https://www.cnn.com/2023/01/30/sport/empire-state-building-green-philadelphia-eagles-spt-intl/index.html', 'emphasized_text_contents': ['CNN'], 'emphasized_text_tags': ['span']}}, ...
+```
+This is a basic guide to get you started with the `Unstructured IO` module. For more advanced usage, refer to the specific method documentation and the [Unstructured IO Documentation](https://unstructured-io.github.io/unstructured/).
diff --git a/docs/key_modules/retrievers.md b/docs/key_modules/retrievers.md
new file mode 100644
index 000000000..459a5bd63
--- /dev/null
+++ b/docs/key_modules/retrievers.md
@@ -0,0 +1,105 @@
+# Retrievers
+## 1. Concept
+The RetrievalModule is essentially a search engine. It's designed to help you find specific pieces of information by searching through large volumes of text. Imagine you have a huge library of books and you want to find where certain topics or keywords are mentioned, this module is like a librarian that helps you do just that.
+
+
+## 2. Types
+
+### 2.1. Vector Retriever
+Vector Retriever typically refers to a method or system used in information retrieval and machine learning that utilizes vector representations of data. This approach is based on converting data, like text, images, or other forms of information, into numerical vectors in a high-dimensional space.
+
+Here's a brief overview of how it works:
+
+- Embedding Model: First, it uses an [embedding model](https://github.com/camel-ai/camel/wiki/Embeddings). This model turns text into a mathematical form (vectors).
+
+- Storing Information: The module takes large documents, breaks them down into smaller chunks, and then uses the embedding model to turn these chunks into vectors. These vectors are stored in a [vector storage](https://github.com/camel-ai/camel/wiki/Storages).
+
+- Retrieving Information: When you ask a question or make a query, the [embedding model](https://github.com/camel-ai/camel/wiki/Embeddings) translates your question into vector and then searches in this [vector storage](https://github.com/camel-ai/camel/wiki/Storages) for the closest matching vector. The closest matches are likely the most relevant pieces of information you are looking for.
+
+
+### 2.2. Keyword Retriever(WIP)
+The Keyword Retriever is designed to retrieve relevant information based on keyword matching. Unlike the Vector Retriever that works with vector representations of data, the Keyword Retriever operates by identifying keywords or specific terms within documents and queries to find matches.
+
+Here's a brief overview of how it works:
+
+- Document Preprocessing: Before using the retriever, the documents are preprocessed to tokenize and index the keywords within them. Tokenization is the process of splitting text into individual words or phrases, making it easier to identify keywords.
+
+- Query Parsing: When you input a question or query, the retriever parses the query to extract relevant keywords. This involves breaking down the query into its constituent terms.
+
+- Keyword Matching: Once the keywords from the query are identified, the retriever searches the preprocessed documents for occurrences of these keywords. It checks for exact matches of the keywords within the documents.
+
+- Ranking and Retrieval: After finding documents that contain the queried keywords, the retriever ranks these documents based on various factors, such as the frequency of keyword matches, document relevance, or other scoring methods. The top-ranked documents are then retrieved as the most relevant results.
+
+## 3. Get Started
+
+### 3.1. Using Customize Retrieval
+
+To get started, you need to initialize the RetrievalModule with an optional embedding model. If you don't provide an embedding model, it will use the default `OpenAIEmbedding`. Here's how to do it:
+```python
+from camel.embeddings import OpenAIEmbedding
+from camel.retrievers.retrieval_module import RetrievalModule
+
+# Initialize the RetrievalModule with an optional embedding model
+rm = RetrievalModule(embedding_model=OpenAIEmbedding())
+```
+
+**Embed and Store Data:**
+
+Before you can retrieve information, you need to prepare your data and store it in vector storage. The embed_and_store_chunks method takes care of this for you. It processes content from a file or URL, divides it into chunks, and stores their embeddings in the specified vector storage.
+```python
+# Provide the path to your content input (can be a file or URL)
+content_input_path = "https://arxiv.org/pdf/2303.17760.pdf"
+
+# Create or initialize a vector storage (e.g., QdrantStorage)
+from camel.storages.vectordb_storages import QdrantStorage
+
+vector_storage = QdrantStorage(
+ vector_dim=embedding_instance.get_output_dim(),
+ collection="my first collection",
+ path="storage_customized_run",
+)
+
+# Embed and store chunks of data in the vector storage
+rm.embed_and_store_chunks(content_input_path, vector_storage)
+```
+
+**Execute a Query:**
+
+Now that your data is stored, you can execute a query to retrieve information based on a search string. The query_and_compile_results method executes the query and compiles the retrieved results into a string.
+```python
+# Specify your query string
+query = "What is CAMEL"
+
+# Execute the query and retrieve results
+results = rm.query_and_compile_results(query, vector_storage)
+print(results)
+```
+```markdown
+>>> {'similarity score': '0.8321616118446469', 'content path': 'local_data/camel paper.pdf', 'metadata': {'filetype': 'application/pdf', 'languages': ['eng'], 'last_modified': '2024-01-14T22:55:19', 'page_number': 45}, 'text': 'CAMEL Data and Code License The intended purpose and licensing of CAMEL is solely for research use. The source code is licensed under Apache 2.0. The datasets are licensed under CC BY NC 4.0, which permits only non-commercial usage. It is advised that any models trained using the dataset should not be utilized for anything other than research purposes.\n\n45'}
+```
+
+### 3.2. Using Default Retrieval
+
+To simplify the retrieval process further, you can use the run_default_retrieval method. This method handles both embedding and storing data and executing queries. It's particularly useful when dealing with multiple content input paths.
+```python
+rm = RetrievalModule()
+retrieved_info = rm.run_default_retrieval(
+ content_input_paths=[
+ "https://www.camel-ai.org/", # example remote url
+ ],
+ vector_storage_local_path="storage_default_run",
+ query="What is CAMEL-AI",
+)
+
+print(retrieved_info)
+```
+```markdown
+>>> Original Query:
+>>> {What is CAMEL-AI}
+>>> Retrieved Context:
+>>> {'similarity score': '0.8380731206379989', 'content path': 'https://www.camel-ai.org/', 'metadata': {'emphasized_text_contents': ['Mission', 'CAMEL-AI.org', 'is an open-source community dedicated to the study of autonomous and communicative agents. We believe that studying these agents on a large scale offers valuable insights into their behaviors, capabilities, and potential risks. To facilitate research in this field, we provide, implement, and support various types of agents, tasks, prompts, models, datasets, and simulated environments.', 'Join us via', 'Slack', 'Discord', 'or'], 'emphasized_text_tags': ['span', 'span', 'span', 'span', 'span', 'span', 'span'], 'filetype': 'text/html', 'languages': ['eng'], 'link_texts': [None, None, None], 'link_urls': ['#h.3f4tphhd9pn8', 'https://join.slack.com/t/camel-ai/shared_invite/zt-1vy8u9lbo-ZQmhIAyWSEfSwLCl2r2eKA', 'https://discord.gg/CNcNpquyDc'], 'page_number': 1, 'url': 'https://www.camel-ai.org/'}, 'text': 'Mission\n\nCAMEL-AI.org is an open-source community dedicated to the study of autonomous and communicative agents. We believe that studying these agents on a large scale offers valuable insights into their behaviors, capabilities, and potential risks. To facilitate research in this field, we provide, implement, and support various types of agents, tasks, prompts, models, datasets, and simulated environments.\n\nJoin us via\n\nSlack\n\nDiscord\n\nor'}
+```
+
+That's it! You've successfully set up and used the RetrievalModule to retrieve information based on queries from your data collection.
+
+Feel free to customize the code according to your specific use case and data sources. Happy retrieving!
diff --git a/docs/key_modules/storages.md b/docs/key_modules/storages.md
new file mode 100644
index 000000000..c1a8ebd5d
--- /dev/null
+++ b/docs/key_modules/storages.md
@@ -0,0 +1,166 @@
+# Storages
+## 1. Concept
+The Storage Module is a comprehensive framework designed for handling various types of data storage mechanisms. It encapsulates the functionality for storing, retrieving, and managing data in different storage formats. The module is composed of abstract base classes and concrete implementations, catering to both key-value storage and vector storage systems.
+
+## 2. Types
+
+### 2.1. Key Value Storages
+**`BaseKeyValueStorage`**:
+
+- Purpose: Serves as the foundational abstract class for creating various key-value storage systems.
+
+- Functionality: Standardizes operations like saving, loading, and clearing data records. It primarily interfaces through Python dictionaries.
+
+- Use Cases: Applicable for JSON file storage, NoSQL databases (like MongoDB and Redis), and in-memory Python dictionaries.
+
+**`InMemoryKeyValueStorage`**:
+
+- Description: A concrete implementation of `BaseKeyValueStorage`, utilizing in-memory lists.
+
+- Feature: Ideal for temporary storage as data is volatile and lost when the program terminates.
+
+- Functionality: Implements methods for saving, loading, and clearing records in memory.
+
+**`JsonStorage`**:
+
+- Description: Another concrete implementation of `BaseKeyValueStorage`, focusing on JSON file storage.
+
+- Feature: Ensures persistent storage of records in a human-readable format. Supports customization through a custom JSON encoder for specific enumerated types.
+
+- Functionality: Includes methods for saving data in JSON format, loading, and clearing data.
+
+### 2.2. VectorDB Storages
+**`BaseVectorStorage`**:
+
+- Purpose: An abstract base class designed to be extended for specific vector storage implementations.
+
+- Features: Supports various operations like adding, deleting vectors, querying similar vectors, and maintaining the status of the vector database.
+
+- Functionality: Offers flexibility in specifying vector dimensions, collection names, distance metrics, and more.
+
+**`MilvusStorage`**:
+
+- Description: A concrete implementation of `BaseVectorStorage`, tailored for interacting with Milvus, a cloud-native vector search engine.
+
+Reference: [Milvus](https://milvus.io/docs/overview.md/)
+
+**`QdrantStorage`**:
+
+- Description: A concrete implementation of `BaseVectorStorage`, tailored for interacting with Qdrant, a vector search engine.
+
+Reference: [Qdrant](https://qdrant.tech/)
+
+## 3. Get Started
+
+To get started with the storage module you've provided, you'll need to understand the basic usage of the key classes and their methods. The module includes an abstract base class `BaseKeyValueStorage` and its concrete implementations `InMemoryKeyValueStorage` and `JsonStorage`, as well as a vector storage system through `BaseVectorStorage` and its implementation `MilvusStorage` or `QdrantStorage`.
+
+### 3.1. Using `InMemoryKeyValueStorage`
+
+```python
+from camel.storages.key_value_storages import InMemoryKeyValueStorage
+
+# Create an instance of InMemoryKeyValueStorage
+memory_storage = InMemoryKeyValueStorage()
+
+# Save records
+memory_storage.save([{'key1': 'value1'}, {'key2': 'value2'}])
+
+# Load records
+records = memory_storage.load()
+print(records)
+
+# Clear all records
+memory_storage.clear()
+```
+```markdown
+>>> [{'key1': 'value1'}, {'key2': 'value2'}]
+```
+
+### 3.2. Using `JsonStorage`
+
+```python
+from camel.storages.key_value_storages import JsonStorage
+from pathlib import Path
+
+# Create an instance of JsonStorage with a specific file path
+json_storage = JsonStorage(Path("my_data.json"))
+
+# Save records
+json_storage.save([{'key1': 'value1'}, {'key2': 'value2'}])
+
+# Load records
+records = json_storage.load()
+print(records)
+
+# Clear all records
+json_storage.clear()
+```
+```markdown
+>>> [{'key1': 'value1'}, {'key2': 'value2'}]
+```
+
+### 3.3. Using `MilvusStorage`
+
+```python
+from camel.storages import MilvusStorage, VectorDBQuery, VectorRecord
+
+# Create an instance of MilvusStorage with dimension = 4
+milvus_storage = MilvusStorage(
+ url_and_api_key=("Your Milvus URI","Your Milvus Token"),
+ vector_dim=4,
+ collection_name="my_collection")
+
+# Add two vector records
+milvus_storage.add([VectorRecord(
+ vector=[-0.1, 0.1, -0.1, 0.1],
+ payload={'key1': 'value1'},
+ ),
+ VectorRecord(
+ vector=[-0.1, 0.1, 0.1, 0.1],
+ payload={'key2': 'value2'},
+ ),])
+
+# Load the remote collection
+milvus_storage.load()
+
+# Query similar vectors
+query_results = milvus_storage.query(VectorDBQuery(query_vector=[0.1, 0.2, 0.1, 0.1], top_k=1))
+for result in query_results:
+ print(result.record.payload, result.similarity)
+
+# Clear all vectors
+milvus_storage.clear()
+```
+```markdown
+>>> {'key2': 'value2'} 0.5669466853141785
+```
+
+### 3.4. Using `QdrantStorage`
+
+```python
+from camel.storages import QdrantStorage, VectorDBQuery, VectorRecord
+
+# Create an instance of QdrantStorage with dimension = 4
+qdrant_storage = QdrantStorage(vector_dim=4, collection_name="my_collection")
+
+# Add two vector records
+qdrant_storage.add([VectorRecord(
+ vector=[-0.1, 0.1, -0.1, 0.1],
+ payload={'key1': 'value1'},
+ ),
+ VectorRecord(
+ vector=[-0.1, 0.1, 0.1, 0.1],
+ payload={'key2': 'value2'},
+ ),])
+
+# Query similar vectors
+query_results = qdrant_storage.query(VectorDBQuery(query_vector=[0.1, 0.2, 0.1, 0.1], top_k=1))
+for result in query_results:
+ print(result.record.payload, result.similarity)
+
+# Clear all vectors
+qdrant_storage.clear()
+```
+```markdown
+>>> {'key2': 'value2'} 0.5669467095138407
+```
diff --git a/docs/tutorials_and_cookbooks/rag_cookbook.ipynb b/docs/tutorials_and_cookbooks/rag_cookbook.ipynb
deleted file mode 100644
index c50162f0a..000000000
--- a/docs/tutorials_and_cookbooks/rag_cookbook.ipynb
+++ /dev/null
@@ -1,553 +0,0 @@
-{
- "cells": [
- {
- "attachments": {},
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "# RAG Cookbook\n",
- "\n",
- "In this notebook, we show the useage of CAMEL Retriever Module in both customized way and auto way. We will also show how to combine `AutoRetriever` with `ChatAgent`, and further combine `AutoRetriever` with `RolePlaying` by using `Function Calling`.\n",
- "\n",
- "4 main parts included:\n",
- "- Customized RAG\n",
- "- Auto RAG\n",
- "- Single Agent with Auto RAG\n",
- "- Role-playing with Auto RAG"
- ]
- },
- {
- "attachments": {},
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Load Data\n",
- "\n",
- "Let's first load the CAMEL paper from https://arxiv.org/pdf/2303.17760.pdf. This will be our local example data."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "import os\n",
- "import requests\n",
- "\n",
- "os.makedirs('local_data', exist_ok=True)\n",
- "\n",
- "url = \"https://arxiv.org/pdf/2303.17760.pdf\"\n",
- "response = requests.get(url)\n",
- "with open('local_data/camel paper.pdf', 'wb') as file:\n",
- " file.write(response.content)"
- ]
- },
- {
- "attachments": {},
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## 1. Customized RAG\n",
- "In this section we will set our customized RAG pipeline, we will take `VectorRetriever` as an example\n"
- ]
- },
- {
- "attachments": {},
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Set embedding model, we will use `OpenAIEmbedding` as the embedding model, so we need to set the `OPENAI_API_KEY` in below."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 1,
- "metadata": {},
- "outputs": [],
- "source": [
- "import os\n",
- "\n",
- "os.environ[\"OPENAI_API_KEY\"] = \"Your Key\""
- ]
- },
- {
- "attachments": {},
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Import and set the embedding instance:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 2,
- "metadata": {},
- "outputs": [],
- "source": [
- "from camel.embeddings import OpenAIEmbedding\n",
- "\n",
- "embedding_instance = OpenAIEmbedding()"
- ]
- },
- {
- "attachments": {},
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Import and set the vector storage instance:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 3,
- "metadata": {},
- "outputs": [],
- "source": [
- "from camel.storages import MilvusStorage\n",
- "\n",
- "storage_instance = MilvusStorage(\n",
- " vector_dim=embedding_instance.get_output_dim(),\n",
- " url_and_api_key=(\"Your Milvus URI\",\"Your Milvus Token\"),\n",
- " collection_name=\"camel_paper\",\n",
- ")"
- ]
- },
- {
- "attachments": {},
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Import and set the retriever instance:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 4,
- "metadata": {},
- "outputs": [],
- "source": [
- "from camel.retrievers import VectorRetriever\n",
- "\n",
- "vector_retriever = VectorRetriever(embedding_model=embedding_instance)"
- ]
- },
- {
- "attachments": {},
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "We use integrated `Unstructured Module` to splite the content into small chunks, the content will be splited automacitlly with its `chunk_by_title` function, the max character for each chunk is 500 characters, which is a suitable length for `OpenAIEmbedding`. All the text in the chunks will be embed and stored to the vector storage instance, it will take some time, please wait.."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 5,
- "metadata": {},
- "outputs": [],
- "source": [
- "vector_retriever.process(\n",
- " content_input_path=\"local_data/camel paper.pdf\",\n",
- " storage=storage_instance,\n",
- ")"
- ]
- },
- {
- "attachments": {},
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Now we can retrieve information from the vector storage by giving a query. By default it will give you back the text content from top 1 chunk with highest Cosine similarity score, and the similarity score should be higher than 0.75 to ensure the retrieved content is relevant to the query. You can also change the `top_k` value and `similarity_threshold` value with your needs.\n",
- "\n",
- "The returned string list includes:\n",
- "- similarity score\n",
- "- content path\n",
- "- metadata\n",
- "- text"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 6,
- "metadata": {},
- "outputs": [
- {
- "name": "stdout",
- "output_type": "stream",
- "text": [
- "[{'similarity score': '0.8321741223335266', 'content path': 'local_data/camel paper.pdf', 'metadata': {'filetype': 'application/pdf', 'languages': ['eng'], 'last_modified': '2024-03-24T17:58:24', 'page_number': 45}, 'text': 'CAMEL Data and Code License The intended purpose and licensing of CAMEL is solely for research use. The source code is licensed under Apache 2.0. The datasets are licensed under CC BY NC 4.0, which permits only non-commercial usage. It is advised that any models trained using the dataset should not be utilized for anything other than research purposes.\\n\\n45'}]\n"
- ]
- }
- ],
- "source": [
- "retrieved_info = vector_retriever.query(\n",
- " query=\"What is CAMEL?\", storage=storage_instance, top_k=1\n",
- ")\n",
- "print(retrieved_info)"
- ]
- },
- {
- "attachments": {},
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Let's try an irrelevant query:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 7,
- "metadata": {},
- "outputs": [
- {
- "name": "stdout",
- "output_type": "stream",
- "text": [
- "[{'text': 'No suitable information retrieved from local_data/camel paper.pdf with similarity_threshold = 0.75.'}]\n"
- ]
- }
- ],
- "source": [
- "retrieved_info_irrevelant = vector_retriever.query(\n",
- " query=\"Compared with dumpling and rice, which should I take for dinner?\",\n",
- " storage=storage_instance,\n",
- " top_k=1,\n",
- ")\n",
- "\n",
- "print(retrieved_info_irrevelant)"
- ]
- },
- {
- "attachments": {},
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## 2. Auto RAG\n",
- "In this section we will run the `AutoRetriever` with default settings. It uses `OpenAIEmbedding` as default embedding model and `Milvus` as default vector storage.\n",
- "\n",
- "What you need to do is:\n",
- "- Set content input paths, which can be local paths or remote urls\n",
- "- Set remote url and api key for Milvus\n",
- "- Give a query\n",
- "\n",
- "The Auto RAG pipeline would create collections for given content input paths, the collection name will be set automaticlly based on the content input path name, if the collection exists, it will do the retrieve directly."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 8,
- "metadata": {},
- "outputs": [
- {
- "name": "stdout",
- "output_type": "stream",
- "text": [
- "Original Query:\n",
- "{What is CAMEL-AI}\n",
- "Retrieved Context:\n",
- "{'similarity score': '0.8369356393814087', 'content path': 'local_data/camel paper.pdf', 'metadata': {'filetype': 'application/pdf', 'languages': ['eng'], 'last_modified': '2024-03-24T17:58:24', 'page_number': 7}, 'text': 'Section 3.2, to simulate assistant-user cooperation. For our analysis, we set our attention on AI Society setting. We also gathered conversational data, named CAMEL AI Society and CAMEL Code datasets and problem-solution pairs data named CAMEL Math and CAMEL Science and analyzed and evaluated their quality. Moreover, we will discuss potential extensions of our framework and highlight both the risks and opportunities that future AI society might present.'}\n",
- "{'similarity score': '0.8378663659095764', 'content path': 'https://www.camel-ai.org/', 'metadata': {'emphasized_text_contents': ['Mission', 'CAMEL-AI.org', 'is an open-source community dedicated to the study of autonomous and communicative agents. We believe that studying these agents on a large scale offers valuable insights into their behaviors, capabilities, and potential risks. To facilitate research in this field, we provide, implement, and support various types of agents, tasks, prompts, models, datasets, and simulated environments.', 'Join us via', 'Slack', 'Discord', 'or'], 'emphasized_text_tags': ['span', 'span', 'span', 'span', 'span', 'span', 'span'], 'filetype': 'text/html', 'languages': ['eng'], 'link_texts': [None, None, None], 'link_urls': ['#h.3f4tphhd9pn8', 'https://join.slack.com/t/camel-ai/shared_invite/zt-1vy8u9lbo-ZQmhIAyWSEfSwLCl2r2eKA', 'https://discord.gg/CNcNpquyDc'], 'page_number': 1, 'url': 'https://www.camel-ai.org/'}, 'text': 'Mission\\n\\nCAMEL-AI.org is an open-source community dedicated to the study of autonomous and communicative agents. We believe that studying these agents on a large scale offers valuable insights into their behaviors, capabilities, and potential risks. To facilitate research in this field, we provide, implement, and support various types of agents, tasks, prompts, models, datasets, and simulated environments.\\n\\nJoin us via\\n\\nSlack\\n\\nDiscord\\n\\nor'}\n"
- ]
- }
- ],
- "source": [
- "from camel.retrievers import AutoRetriever\n",
- "from camel.types import StorageType\n",
- "\n",
- "auto_retriever = AutoRetriever(\n",
- " url_and_api_key=(\"Your Milvus URI\",\"Your Milvus Token\"),\n",
- " storage_type=StorageType.MILVUS,\n",
- " embedding_model=embedding_instance)\n",
- "\n",
- "retrieved_info = auto_retriever.run_vector_retriever(\n",
- " query=\"What is CAMEL-AI\",\n",
- " content_input_paths=[\n",
- " \"local_data/camel paper.pdf\", # example local path\n",
- " \"https://www.camel-ai.org/\", # example remote url\n",
- " ],\n",
- " top_k=1,\n",
- " return_detailed_info=True,\n",
- ")\n",
- "\n",
- "print(retrieved_info)"
- ]
- },
- {
- "attachments": {},
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## 3. Single Agent with Auto RAG\n",
- "In this section we will show how to combine the `AutoRetriever` with one `ChatAgent`."
- ]
- },
- {
- "attachments": {},
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Let's set an agent function, in this function we can get the response by providing a query to this agent."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 9,
- "metadata": {},
- "outputs": [
- {
- "name": "stdout",
- "output_type": "stream",
- "text": [
- "CAMEL-AI is an open-source community dedicated to the study of autonomous and communicative agents. It provides, implements, and supports various types of agents, tasks, prompts, models, datasets, and simulated environments to facilitate research in this field.\n"
- ]
- }
- ],
- "source": [
- "from camel.agents import ChatAgent\n",
- "from camel.messages import BaseMessage\n",
- "from camel.types import RoleType\n",
- "from camel.retrievers import AutoRetriever\n",
- "from camel.types import StorageType\n",
- "\n",
- "def single_agent(query: str) ->str :\n",
- " # Set agent role\n",
- " assistant_sys_msg = BaseMessage(\n",
- " role_name=\"Assistant\",\n",
- " role_type=RoleType.ASSISTANT,\n",
- " meta_dict=None,\n",
- " content=\"You are a helpful assistant to answer question, I will give you the Original Query and Retrieved Context, answer the Original Query based on the Retrieved Context, if you can't answer the question just say I don't know.\",\n",
- " )\n",
- "\n",
- " # Add auto retriever\n",
- " auto_retriever = AutoRetriever(\n",
- " url_and_api_key=(\"Your Milvus URI\",\"Your Milvus Token\"),\n",
- " storage_type=StorageType.MILVUS,\n",
- " embedding_model=embedding_instance)\n",
- "\n",
- " retrieved_info = auto_retriever.run_vector_retriever(\n",
- " query=query,\n",
- " content_input_paths=[\n",
- " \"local_data/camel paper.pdf\", # example local path\n",
- " \"https://www.camel-ai.org/\", # example remote url\n",
- " ],\n",
- " # vector_storage_local_path=\"storage_default_run\",\n",
- " top_k=1,\n",
- " return_detailed_info=True,\n",
- " )\n",
- "\n",
- " # Pass the retrieved infomation to agent\n",
- " user_msg = BaseMessage.make_user_message(role_name=\"User\", content=retrieved_info)\n",
- " agent = ChatAgent(assistant_sys_msg)\n",
- "\n",
- " # Get response\n",
- " assistant_response = agent.step(user_msg)\n",
- " return assistant_response.msg.content\n",
- "\n",
- "print(single_agent(\"What is CAMEL-AI\"))"
- ]
- },
- {
- "attachments": {},
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## 4. Role-playing with Auto RAG\n",
- "In this section we will show how to combine the `AutoRetriever` with `RolePlaying` by applying `Function Calling`."
- ]
- },
- {
- "attachments": {},
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "First, we need to set a retriever function with well-written docstring for LLM to understand what this function is used for, the main code is the same with the Auto RAG section."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 10,
- "metadata": {},
- "outputs": [],
- "source": [
- "from typing import List\n",
- "from camel.functions import OpenAIFunction\n",
- "from camel.retrievers import AutoRetriever\n",
- "from camel.types import StorageType\n",
- "\n",
- "def local_retriever(query: str) -> str:\n",
- " r\"\"\"Performs an auto local retriever for information. Given a query,\n",
- " this function will retrieve the information from the local vector storage,\n",
- " and return the retrieved information back. It is useful for information\n",
- " retrieve.\n",
- "\n",
- " Args:\n",
- " query (string): Question you want to be answered.\n",
- "\n",
- " Returns:\n",
- " str: Aggregated information retrieved in response to the query.\n",
- "\n",
- " Example:\n",
- " local_retriever(query = \"what is camel?\")\n",
- " \"\"\"\n",
- " auto_retriever = AutoRetriever(\n",
- " url_and_api_key=(\"Your Milvus URI\",\"Your Milvus Token\"),\n",
- " storage_type=StorageType.MILVUS,\n",
- " embedding_model=embedding_instance)\n",
- "\n",
- " retrieved_info = auto_retriever.run_vector_retriever(\n",
- " query=query,\n",
- " content_input_paths=[\n",
- " \"local_data/camel paper.pdf\", # example local path\n",
- " ],\n",
- " top_k=1\n",
- " )\n",
- " return retrieved_info\n",
- "\n",
- "# add the function to OpenAIFunction list\n",
- "RETRIEVER_FUNCS: List[OpenAIFunction] = [\n",
- " OpenAIFunction(func)\n",
- " for func in [\n",
- " local_retriever,\n",
- " ]\n",
- "]"
- ]
- },
- {
- "attachments": {},
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Run the role-playing with defined retriever function:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 11,
- "metadata": {},
- "outputs": [
- {
- "name": "stdout",
- "output_type": "stream",
- "text": [
- "\u001b[32mAI Assistant sys message:\n",
- "BaseMessage(role_name='Searcher', role_type=<RoleType.ASSISTANT: 'assistant'>, meta_dict={'task': \"What is the main termination reasons for AI Society dataset, how many number of messages did camel decided to limit, what's the value plus 100?\", 'assistant_role': 'Searcher', 'user_role': 'Professor'}, content=\"===== RULES OF ASSISTANT =====\\nNever forget you are a Searcher and I am a Professor. Never flip roles! Never instruct me!\\nWe share a common interest in collaborating to successfully complete a task.\\nYou must help me to complete the task.\\nHere is the task: What is the main termination reasons for AI Society dataset, how many number of messages did camel decided to limit, what's the value plus 100?. Never forget our task!\\nI must instruct you based on your expertise and my needs to complete the task.\\n\\nI must give you one instruction at a time.\\nYou must write a specific solution that appropriately solves the requested instruction and explain your solutions.\\nYou must decline my instruction honestly if you cannot perform the instruction due to physical, moral, legal reasons or your capability and explain the reasons.\\nUnless I say the task is completed, you should always start with:\\n\\nSolution: <YOUR_SOLUTION>\\n\\n<YOUR_SOLUTION> should be very specific, include detailed explanations and provide preferable detailed implementations and examples and lists for task-solving.\\nAlways end <YOUR_SOLUTION> with: Next request.\")\n",
- "\n",
- "\u001b[34mAI User sys message:\n",
- "BaseMessage(role_name='Professor', role_type=<RoleType.USER: 'user'>, meta_dict={'task': \"What is the main termination reasons for AI Society dataset, how many number of messages did camel decided to limit, what's the value plus 100?\", 'assistant_role': 'Searcher', 'user_role': 'Professor'}, content='===== RULES OF USER =====\\nNever forget you are a Professor and I am a Searcher. Never flip roles! You will always instruct me.\\nWe share a common interest in collaborating to successfully complete a task.\\nI must help you to complete the task.\\nHere is the task: What is the main termination reasons for AI Society dataset, how many number of messages did camel decided to limit, what\\'s the value plus 100?. Never forget our task!\\nYou must instruct me based on my expertise and your needs to solve the task ONLY in the following two ways:\\n\\n1. Instruct with a necessary input:\\nInstruction: <YOUR_INSTRUCTION>\\nInput: <YOUR_INPUT>\\n\\n2. Instruct without any input:\\nInstruction: <YOUR_INSTRUCTION>\\nInput: None\\n\\nThe \"Instruction\" describes a task or question. The paired \"Input\" provides further context or information for the requested \"Instruction\".\\n\\nYou must give me one instruction at a time.\\nI must write a response that appropriately solves the requested instruction.\\nI must decline your instruction honestly if I cannot perform the instruction due to physical, moral, legal reasons or my capability and explain the reasons.\\nYou should instruct me not ask me questions.\\nNow you must start to instruct me using the two ways described above.\\nDo not add anything else other than your instruction and the optional corresponding input!\\nKeep giving me instructions and necessary inputs until you think the task is completed.\\nWhen the task is completed, you must only reply with a single word <CAMEL_TASK_DONE>.\\nNever say <CAMEL_TASK_DONE> unless my responses have solved your task.')\n",
- "\n",
- "\u001b[33mOriginal task prompt:\n",
- "What is the main termination reasons for AI Society dataset, how many number of messages did camel decided to limit, what's the value plus 100?\n",
- "\n",
- "\u001b[36mSpecified task prompt:\n",
- "None\n",
- "\n",
- "\u001b[31mFinal task prompt:\n",
- "What is the main termination reasons for AI Society dataset, how many number of messages did camel decided to limit, what's the value plus 100?\n",
- "\n",
- "\u001b[34mAI User:\n",
- "\n",
- "Instruction: Provide the main termination reasons from the AI Society dataset.\n",
- "Input: None\n",
- "\n",
- "\n",
- "\u001b[32mAI Assistant:\n",
- "\n",
- "Function Execution: local_retriever\n",
- "\tArgs: {'query': 'main termination reasons for AI Society dataset'}\n",
- "\tResult: Original Query:\n",
- "{main termination reasons for AI Society dataset}\n",
- "Retrieved Context:\n",
- "Next we examine the conversation termination reasons for both AI Society and Code datasets. As can be seen in Figure 8, the main termination reasons for AI Society dataset is Assistant Instruct whereas for Code it is Token Limit. The latter is expected as the since responses that contain code tend to be long. It is also interesting to note that in both datasets, the termination due to Maximum Number of Messages is low indicating that the limit of 40 maximum messages is reasonable. Our decision\n",
- "\n",
- "Solution: The main termination reason for the AI Society dataset is \"Assistant Instruct.\" This indicates that the conversations in this dataset typically end when the assistant is instructed to terminate the conversation.\n",
- "\n",
- "Next request.\n",
- "\n",
- "\n",
- "\u001b[34mAI User:\n",
- "\n",
- "Instruction: Identify the number of messages that camel decided to limit.\n",
- "Input: None\n",
- "\n",
- "\n",
- "\u001b[32mAI Assistant:\n",
- "\n",
- "Function Execution: local_retriever\n",
- "\tArgs: {'query': 'number of messages camel decided to limit'}\n",
- "\tResult: Original Query:\n",
- "{number of messages camel decided to limit}\n",
- "Retrieved Context:\n",
- "to limit the number of messages to 40 is also cost-related. Even if we provide a set of termination conditions, we still want to put a safeguard to the maximum limit of the message. It is because after the task is completed the agents will provide short outputs like \"thank you\" and \"welcome\". If no safeguard is set and termination fails, the conversation will only end until it exceeds the token limit, which may end up with thousands of API calls and hundreds of USD dollars cost.\n",
- "\n",
- "Solution: Camel decided to limit the number of messages to 40 as a safeguard to prevent excessive API calls and associated costs.\n",
- "\n",
- "Next request.\n",
- "\n",
- "\n",
- "\u001b[34mAI User:\n",
- "\n",
- "Instruction: Calculate the value of the message limit plus 100.\n",
- "Input: None\n",
- "\n",
- "\n",
- "\u001b[32mAI Assistant:\n",
- "\n",
- "Function Execution: add\n",
- "\tArgs: {'a': 40, 'b': 100}\n",
- "\tResult: 140\n",
- "\n",
- "Solution: The value of the message limit plus 100 is 140.\n",
- "\n",
- "Next request.\n",
- "\n",
- "\n",
- "\u001b[34mAI User:\n",
- "\n",
- "CAMEL_TASK_DONE\n",
- "\n",
- "\n",
- "\u001b[32mAI Assistant:\n",
- "\n",
- "Solution: Understood, the task is completed.\n",
- "\n",
- "If you have any more tasks or need further assistance, feel free to provide new instructions.\n",
- "\n",
- "\n"
- ]
- }
- ],
- "source": [
- "from camel.utils import role_playing_with_function\n",
- "from camel.functions import MATH_FUNCS # import another function from camel\n",
- "\n",
- "role_playing_with_function(\n",
- " task_prompt=(\n",
- " \"What is the main termination reasons for AI Society dataset, how many number of messages did camel decided to limit, what's the value plus 100?\"\n",
- " ),\n",
- " function_list=[*RETRIEVER_FUNCS, *MATH_FUNCS],\n",
- ")"
- ]
- }
- ],
- "metadata": {
- "kernelspec": {
- "display_name": "camel-ai-gyT5aXID-py3.10",
- "language": "python",
- "name": "python3"
- },
- "language_info": {
- "codemirror_mode": {
- "name": "ipython",
- "version": 3
- },
- "file_extension": ".py",
- "mimetype": "text/x-python",
- "name": "python",
- "nbconvert_exporter": "python",
- "pygments_lexer": "ipython3",
- "version": "3.10.9"
- }
- },
- "nbformat": 4,
- "nbformat_minor": 4
-}