doc: pdate readme.md with features and some main feature code sinppets (#1154)

Co-authored-by: Wendong <[email protected]>
Co-authored-by: Wendong-Fan <[email protected]>
Co-authored-by: Zecheng Zhang <[email protected]>

Author: 3 people

README.md

@@ -36,7 +36,37 @@ ______________________________________________________________________
 
 Join us ([*Discord*](https://discord.camel-ai.org/), [*WeChat*](https://ghli.org/camel/wechat.png) or [*Slack*](https://join.slack.com/t/camel-ai/shared_invite/zt-2g7xc41gy-_7rcrNNAArIP6sLQqldkqQ)) in pushing the boundaries of finding the scaling laws of agents.
 
-## Try it yourself
+## What Can You Build With CAMEL?
+
+### 🤖 Customize Agents
+- Customizable agents are the fundamental entities of the CAMEL architecture. CAMEL empowers you to customize agents using our modular components for specific tasks.
+
+### ⚙️ Build Multi-Agent Systems
+- We propose a multi-agent framework to address agents' autonomous cooperation challenges, guiding agents toward task completion while maintaining human intentions.
+
+### 💻 Practical Applications
+- The CAMEL framework serves as a generic infrastructure for a wide range of multi-agent applications, including task automation, data generation, and world simulations.
+
+
+## Why Should You Use CAMEL?
+
+1. Comprehensive Customization and Collaboration:
+
+    - Integrates over 20 advanced model platforms (e.g., commercial models like OpenAI, open-source models such as Llama3, and self-deployment frameworks like Ollama.).
+
+    - Supports extensive external tools (e.g., Search, Twitter, Github, Google Maps, Reddit, Slack utilities).
+    - Includes memory and prompt components for deep customization.
+    - Facilitates complex multi-agent systems with advanced collaboration features.
+
+
+2. User-Friendly with Transparent Internal Structure:
+    - Designed for transparency and consistency in internal structure.
+
+    - Offers comprehensive [tutorials and detailed docstrings](https://docs.camel-ai.org/) for all functions.
+    - Ensures an approachable learning curve for newcomers.
+
+
+## Try It Yourself
 We provide a [![Google Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1AzP33O8rnMW__7ocWJhVBXjKziJXPtim?usp=sharing) demo showcasing a conversation between two ChatGPT agents playing roles as a python programmer and a stock trader collaborating on developing a trading bot for stock market.
 
 <p align="center">
@@ -105,8 +135,6 @@ exit
 > ```
 
 
-
-
 Install `CAMEL` from source with conda and pip:
 ```sh
 # Create a conda virtual environment
@@ -134,13 +162,58 @@ Detailed guidance can be find [here](https://github.com/camel-ai/camel/blob/mast
 
 ## Documentation
 
-[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).
-
-As an example, to run the `role_playing.py` script:
+The [complete documentation](https://camel-ai.github.io/camel/) pages for the CAMEL package. Also, detailed tutorials for each part are provided below:
+
+### Agents
+Explore different types of agents, their roles, and their applications.
+
+- **[Creating Your First Agent](https://docs.camel-ai.org/cookbooks/create_your_first_agent.html)**
+- **[Creating Your First Agent Society](https://docs.camel-ai.org/cookbooks/create_your_first_agents_society.html)**
+- **[Embodied Agents](https://docs.camel-ai.org/cookbooks/embodied_agents.html)**
+- **[Critic Agents](https://docs.camel-ai.org/cookbooks/critic_agents_and_tree_search.html)**
+
+---
+
+### Key Modules
+Core components and utilities to build, operate, and enhance CAMEL-AI agents and societies.
+
+| Module | Description |
+|:---|:---|
+| **[Models](https://docs.camel-ai.org/key_modules/models.html)** | Model architectures and customization options for agent intelligence. |
+| **[Messages](https://docs.camel-ai.org/key_modules/messages.html)** | Messaging protocols for agent communication. |
+| **[Memory](https://docs.camel-ai.org/key_modules/memory.html)** | Memory storage and retrieval mechanisms. |
+| **[Tools](https://docs.camel-ai.org/key_modules/tools.html)** | Tools integration for specialized agent tasks. |
+| **[Prompts](https://docs.camel-ai.org/key_modules/prompts.html)** | Prompt engineering and customization. |
+| **[Tasks](https://docs.camel-ai.org/key_modules/tasks.html)** | Task creation and management for agent workflows. |
+| **[Loaders](https://docs.camel-ai.org/key_modules/loaders.html)** | Data loading tools for agent operation. |
+| **[Storages](https://docs.camel-ai.org/key_modules/storages.html)** | Storage solutions for agent. |
+| **[Society](https://docs.camel-ai.org/key_modules/society.html)** | Components for building agent societies and inter-agent collaboration. |
+| **[Embeddings](https://docs.camel-ai.org/key_modules/embeddings.html)** | Embedding models for RAG. |
+| **[Retrievers](https://docs.camel-ai.org/key_modules/retrievers.html)** | Retrieval methods for knowledge access. |
+---
+
+### Cookbooks
+Practical guides and tutorials for implementing specific functionalities in CAMEL-AI agents and societies.
+
+| Cookbook | Description |
+|:---|:---|
+| **[Creating Your First Agent](https://docs.camel-ai.org/cookbooks/create_your_first_agent.html)** | A step-by-step guide to building your first agent. |
+| **[Creating Your First Agent Society](https://docs.camel-ai.org/cookbooks/create_your_first_agents_society.html)** | Learn to build a collaborative society of agents. |
+| **[Society Cookbook](https://docs.camel-ai.org/cookbooks/agents_society.html)** | Advanced configurations for agent societies. |
+| **[Model Speed Comparison Cookbook](https://docs.camel-ai.org/cookbooks/model_speed_comparison.html)** | Benchmarking models for performance. |
+| **[Message Cookbook](https://docs.camel-ai.org/cookbooks/agents_message.html)** | Best practices for message handling in agents. |
+| **[Tools Cookbook](https://docs.camel-ai.org/cookbooks/agents_with_tools.html)** | Integrating tools for enhanced functionality. |
+| **[Memory Cookbook](https://docs.camel-ai.org/cookbooks/agents_with_memory.html)** | Implementing memory systems in agents. |
+| **[RAG Cookbook](https://docs.camel-ai.org/cookbooks/agents_with_rag.html)** | Recipes for Retrieval-Augmented Generation. |
+| **[Prompting Cookbook](https://docs.camel-ai.org/cookbooks/agents_prompting.html)** | Techniques for effective prompt creation. |
+| **[Task Generation Cookbook](https://docs.camel-ai.org/cookbooks/task_generation.html)** | Automating task generation for agents. |
+| **[Graph RAG Cookbook](https://docs.camel-ai.org/cookbooks/knowledge_graph.html)** | Leveraging knowledge graphs with RAG. |
+| **[Role-Playing Scraper for Report & Knowledge Graph Generation](https://docs.camel-ai.org/cookbooks/roleplaying_scraper.html)** | Create role-playing agents for data scraping and reporting. |
+| **[Video Analysis](https://docs.camel-ai.org/cookbooks/video_analysis.html)** | Techniques for agents in video data analysis. |
+| **[Track CAMEL Agents with AgentOps](https://docs.camel-ai.org/cookbooks/agents_tracking.html)** | Tools for tracking and managing agents in operations. |
+| **[Create A Hackathon Judge Committee with Workforce](https://docs.camel-ai.org/cookbooks/workforce_judge_committee.html)** | Building a team of agents for collaborative judging. |
+
+## Examples
 
 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.
 
@@ -170,83 +243,41 @@ $env:OPENAI_API_BASE_URL="<inert your OpenAI API BASE URL>"  #(Should you utiliz
 
 Replace `<insert your OpenAI API key>` with your actual OpenAI API key in each case. Make sure there are no spaces around the `=` sign.
 
-After setting the OpenAI API key, you can run the script:
+
+Please note that the environment variable is session-specific. If you open a new terminal window or tab, you will need to set the API key again in that new session.
+
+After setting the OpenAI API key, you can run the `role_playing.py` script. Find tasks for various assistant-user roles [here](https://drive.google.com/file/d/194PPaSTBR07m-PzjS-Ty6KlPLdFIPQDd/view?usp=share_link).
 
 ```bash
 # You can change the role pair and initial prompt in role_playing.py
 python examples/ai_society/role_playing.py
 ```
 
-Please note that the environment variable is session-specific. If you open a new terminal window or tab, you will need to set the API key again in that new session.
+Also feel free to run any scripts below that interest you:
 
+```bash
+# You can change the role pair and initial prompt in these python files
 
-## Use Open-Source Models as Backends (ex. using Ollama to set Llama 3 locally)
+# Examples of two agents role-playing
+python examples/ai_society/role_playing.py
 
-- Download [Ollama](https://ollama.com/download).
-- After setting up Ollama, pull the Llama3 model by typing the following command into the terminal:
-    ```bash
-    ollama pull llama3
-    ```
-- Run the script. Enjoy your Llama3 model, enhanced by CAMEL's excellent agents.
-    ```python
-    from camel.agents import ChatAgent
-    from camel.messages import BaseMessage
-    from camel.models import ModelFactory
-    from camel.types import ModelPlatformType
-
-    ollama_model = ModelFactory.create(
-        model_platform=ModelPlatformType.OLLAMA,
-        model_type="llama3",
-        model_config_dict={"temperature": 0.4},
-    )
-
-    assistant_sys_msg = BaseMessage.make_assistant_message(
-        role_name="Assistant",
-        content="You are a helpful assistant.",
-    )
-    agent = ChatAgent(assistant_sys_msg, model=ollama_model, token_limit=4096)
-
-    user_msg = BaseMessage.make_user_message(
-        role_name="User", content="Say hi to CAMEL"
-    )
-    assistant_response = agent.step(user_msg)
-    print(assistant_response.msg.content)
-    ```
+# The agent answers questions by utilizing code execution tools.
+python examples/toolkits/code_execution_toolkit.py
 
-## Use Open-Source Models as Backends (ex. using vLLM to set Phi-3 locally)
-- [Install vLLM](https://docs.vllm.ai/en/latest/getting_started/installation.html)
-- After setting up vLLM, start an OpenAI compatible server for example by
-    ```bash
-    python -m vllm.entrypoints.openai.api_server --model microsoft/Phi-3-mini-4k-instruct --api-key vllm --dtype bfloat16
-    ```
-- Create and run following script (more details please refer to this [example](https://github.com/camel-ai/camel/blob/master/examples/models/vllm_model_example.py))
-    ```python
-    from camel.agents import ChatAgent
-    from camel.messages import BaseMessage
-    from camel.models import ModelFactory
-    from camel.types import ModelPlatformType
-
-    vllm_model = ModelFactory.create(
-        model_platform=ModelPlatformType.VLLM,
-        model_type="microsoft/Phi-3-mini-4k-instruct",
-        url="http://localhost:8000/v1",
-        model_config_dict={"temperature": 0.0},
-        api_key="vllm",
-    )
-
-    assistant_sys_msg = BaseMessage.make_assistant_message(
-        role_name="Assistant",
-        content="You are a helpful assistant.",
-    )
-    agent = ChatAgent(assistant_sys_msg, model=vllm_model, token_limit=4096)
-
-    user_msg = BaseMessage.make_user_message(
-        role_name="User",
-        content="Say hi to CAMEL AI",
-    )
-    assistant_response = agent.step(user_msg)
-    print(assistant_response.msg.content)
-    ```
+# Generating a knowledge graph with an agent
+python examples/knowledge_graph/knowledge_graph_agent_example.py  
+
+# Multiple agents collaborating to decompose and solve tasks
+python examples/workforce/multiple_single_agents.py 
+
+# Use agent to generate creative image
+python examples/vision/image_crafting.py
+```
+For additional feature examples, see the [`examples`](https://github.com/camel-ai/camel/tree/master/examples) directory.
+
+## Utilize Various LLMs as Backends
+
+For more details, please see our [`Models Documentation`](https://docs.camel-ai.org/key_modules/models.html#).
 
 ## Data (Hosted on Hugging Face)
 | Dataset        | Chat format                                                                                         | Instruction format                                                                                               | Chat format (translated)                                                                   |
@@ -270,7 +301,21 @@ Please note that the environment variable is session-specific. If you open a new
 We implemented amazing research ideas from other works for you to build, compare and customize your agents. If you use any of these modules, please kindly cite the original works:
 - `TaskCreationAgent`, `TaskPrioritizationAgent` and `BabyAGI` from *Nakajima et al.*: [Task-Driven Autonomous Agent](https://yoheinakajima.com/task-driven-autonomous-agent-utilizing-gpt-4-pinecone-and-langchain-for-diverse-applications/). [[Example](https://github.com/camel-ai/camel/blob/master/examples/ai_society/babyagi_playing.py)]
 
+## Other Research Works Based on Camel
+- [Agent Trust](http://agent-trust.camel-ai.org/): Can Large Language Model Agents Simulate Human Trust Behavior?
+
+- [CRAB](https://crab.camel-ai.org/): Cross-environment Agent Benchmark for Multimodal Language Model Agents.
+
+- OASIS: Open Agents Social Interaction Simulations on a Large Scale.
+
+We warmly invite you to use CAMEL for your impactful research.
+
 ## News
+📢 Added the Workforce module to the 🐫 CAMEL framework! For more details, see the [post](https://x.com/CamelAIOrg/status/1851682063830720912). (Oct 31, 2024)
+- Added subprocess support for Ollama and vLLM models. (Oct, 29, 2024)
+- Integrated Firecrawl's Map into the 🐫 CAMEL framework. (Oct, 22, 2024)
+- Integrated Nvidia's Llama-3.1-Nemotron-70b-Instruct! (Oct, 17, 2024)
+- ...
 - Released AI Society and Code dataset (April 2, 2023)
 - Initial release of `CAMEL` python library (March 21, 2023)