modelscope · DavdGao · Jan 22, 2024 · Jan 22, 2024 · Jan 22, 2024 · Jan 22, 2024
diff --git a/README.md b/README.md
@@ -8,10 +8,11 @@ AgentScope is an innovative multi-agent platform designed to empower developers
 
 - **Actor-Based Distribution**: Enabling developers to build distributed multi-agent applications in a centralized programming manner for streamlined development.
 
+Welcome to join our community on
 
-Welcome to join our community on [Discord](https://discord.gg/Fwg5hZ2S) or DingDing group (please scan the following QR code) for discussion.
-
-<img width="100" height="100" src="https://img.alicdn.com/imgextra/i2/O1CN01tuJ5971OmAqNg9cOw_!!6000000001747-0-tps-444-460.jpg" alt="AgentScope-logo">
+| [Discord](https://discord.gg/eYMpfnkG8h) | DingTalk | WeChat |
+|---------|----------|--------|
+| <img src="https://gw.alicdn.com/imgextra/i1/O1CN01hhD1mu1Dd3BWVUvxN_!!6000000000238-2-tps-400-400.png" width="100" height="100"> | <img src="https://img.alicdn.com/imgextra/i2/O1CN01tuJ5971OmAqNg9cOw_!!6000000001747-0-tps-444-460.jpg" width="100" height="100"> | <img src="https://img.alicdn.com/imgextra/i3/O1CN01UyfWfx1CYBM3WqlBy_!!6000000000092-2-tps-400-400.png" width="100" height="100"> |
 
 Table of Contents
 =================
@@ -59,6 +60,7 @@ pip install -e .
 ```
 
 - Building a distributed multi-agent application relies on [gRPC](https://github.com/grpc/grpc) libraries, and you can install the required dependencies as follows.
+
 ```bash
 # On windows
 pip install -e .[distribute]
@@ -87,12 +89,13 @@ Taking a multi-agent application with user and assistant agent as an example, yo
 #### Step 1: Prepare Model Configs
 
 AgentScope supports the following model API services:
-  - OpenAI Python APIs, including
-    - OpenAI Chat, DALL-E and Embedding API
-    - OpenAI-Compatible platforms, e.g. [FastChat](https://github.com/lm-sys/FastChat) and [vllm](https://github.com/vllm-project/vllm)
-  - Post request APIs, including
-    - [HuggingFace](https://huggingface.co/docs/api-inference/index) and [ModelScope](https://www.modelscope.cn/docs/%E9%AD%94%E6%90%ADv1.5%E7%89%88%E6%9C%AC%20Release%20Note%20(20230428)) inference APIs
-    - Customized model APIs
+
+- OpenAI Python APIs, including
+  - OpenAI Chat, DALL-E and Embedding API
+  - OpenAI-Compatible platforms, e.g. [FastChat](https://github.com/lm-sys/FastChat) and [vllm](https://github.com/vllm-project/vllm)
+- Post request APIs, including
+  - [HuggingFace](https://huggingface.co/docs/api-inference/index) and [ModelScope](https://www.modelscope.cn/docs/%E9%AD%94%E6%90%ADv1.5%E7%89%88%E6%9C%AC%20Release%20Note%20(20230428)) inference APIs
+  - Customized model APIs
 
 |                      | Type Argument      | Support APIs                                                  |
 |----------------------|--------------------|---------------------------------------------------------------|
@@ -101,10 +104,10 @@ AgentScope supports the following model API services:
 | OpenAI Embedding API | `openai_embedding` | OpenAI embedding API                                          |
 | Post API             | `post_api`         | Huggingface/ModelScope inference API, and customized post API |
 
-
 ##### OpenAI API Config
 
 For OpenAI APIs, you need to prepare a dict of model config with the following fields:
+
 ```
 {
     "type": "openai" | "openai_dall_e" | "openai_embedding",
@@ -135,8 +138,7 @@ For post requests APIs, the config contains the following fields.
 ```
 
 AgentScope provides fruitful scripts to fast deploy model services in [Scripts](./scripts/README.md).
-For more details of model services, refer to our Tutorial and API Document.
-
+For more details of model services, refer to our [Tutorial](https://alibaba.github.io/AgentScope/index.html) and [API Document](https://alibaba.github.io/AgentScope/index.html).
 
 #### Step 2: Create Agents
 
@@ -168,6 +170,7 @@ x = Msg("Bob", "What about this picture I took?", url="/path/to/picture.jpg")
 
 Start a conversation between two agents (e.g. dialog_agent and user_agent)
 with the following code:
+
 ```python
 x = None
 while True:
@@ -180,25 +183,30 @@ while True:
 ### Advanced Usage
 
 #### **Pipeline** and **MsgHub**
+
 To simplify the construction of agents communication, AgentScope provides two helpful tools: **Pipeline** and **MsgHub**.
 
 - **Pipeline**: It allows users to program a communication among agents easily. Taking a sequential pipeline as an example, the following two codes are equivalent, but pipeline is more convenient and elegant.
 
   - Passing message throught agent1, agent2 and agent3 **WITHOUT** pipeline:
+
     ```python
     x1 = agent1(input_msg)
     x2 = agent2(x1)
     x3 = agent3(x2)
     ```
 
   - **WITH** object-level pipeline:
+
     ```python
     from agentscope.pipelines import SequentialPipeline
 
     pipe = SequentialPipeline([agent1, agent2, agent3])
     x3 = pipe(input_msg)
     ```
+
   - **WITH** functional-level pipeline:
+
     ```python
     from agentscope.pipelines.functional import sequentialpipeline
 
@@ -208,6 +216,7 @@ To simplify the construction of agents communication, AgentScope provides two he
 - **MsgHub**: To achieve a group conversation, AgentScope provides message hub.
 
   - Achieving group conversation **WITHOUT** `msghub`:
+
     ```python
     x1 = agent1(x)
     agent2.observe(x1)  # The message x1 should be broadcast to other agents
@@ -219,6 +228,7 @@ To simplify the construction of agents communication, AgentScope provides two he
     ```
 
   - **With** `msghub`: In a message hub, the messages from participants will be broadcast to all other participants automatically. In such case, participated agents even don't need input and output messages explicitly. All we need to do is to decide the order of speaking. Besides, `msghub` also supports dynamic control of participants as follows.
+
     ```python
     from agentscope import msghub
 
@@ -235,7 +245,9 @@ To simplify the construction of agents communication, AgentScope provides two he
     ```
 
 #### Customize Your Own Agent
+
 To implement your own agent, you need to inherit the `AgentBase` class and implement the `reply` function.
+
 ```python
 from agentscope.agents import AgentBase
 
@@ -247,16 +259,19 @@ class MyAgent(AgentBase):
 ```
 
 #### Built-in Resources
+
 AgentScope provides built-in resources for developers to build their own applications easily. More built-in agents, services and examples are coming soon!
 
 ##### Agent Pool
+
 - UserAgent
 - DialogAgent
 - DictDialogAgent
 - RpcDialogAgent
 - ...
 
 ##### Services
+
 - Web Search Service
 - Code Execution Service
 - Retrieval Service
@@ -265,6 +280,7 @@ AgentScope provides built-in resources for developers to build their own applica
 - ...
 
 ##### Example Applications
+
 - Example of Conversation: [examples/Conversation](examples/conversation/README.md)
 - Example of Werewolf: [examples/Werewolf](examples/werewolf/README.md)
 - Example of Distributed Agents: [examples/Distributed Agents](examples/distributed/README.md)
@@ -292,7 +308,8 @@ pip install -e .\[dev\]
 pre-commit install
 ```
 
-Please refer to our Tutorial for more details.
+Please refer to our [Tutorial](https://alibaba.github.io/AgentScope/) for more details.
 
 ## References
+
 Our paper is coming soon!
diff --git a/docs/sphinx_doc/source/tutorial/207-monitor.md b/docs/sphinx_doc/source/tutorial/207-monitor.md
@@ -2,9 +2,9 @@
 
 # Monitor
 
-In multi-agent applications, particularly those that rely on external model APIs, it's crucial to monitor the usage and cost to prevent overutilization and ensure compliance with rate limits. The `MonitorBase` class and its implementation, `DictMonitor`, provide a way to track and regulate the usage of such APIs in your applications. In this tutorial, you'll learn how to use them to monitor API calls.
+In multi-agent applications, particularly those that rely on external model APIs, it's crucial to monitor the usage and cost to prevent overutilization and ensure compliance with rate limits. The `MonitorBase` class and its implementation, `SqliteMonitor`, provide a way to track and regulate the usage of such APIs in your applications. In this tutorial, you'll learn how to use them to monitor API calls.
 
-## Understanding the `MonitorBase` Class
+## Understanding the Monitor in AgentScope
 
 The `MonitorBase` class serves as an interface for setting up a monitoring system that tracks various metrics, especially focusing on API usage. It defines methods that enable registration, checking, updating, and management of metrics related to API calls.
 
@@ -22,36 +22,41 @@ Here are the key methods of `MonitorBase`:
 - **`set_quota`**: Adjusts the quota for a metric, if the terms of API usage change.
 - **`get_metric`**: Returns detailed information about a specific metric.
 - **`get_metrics`**: Retrieves information about all tracked metrics, with optional filtering based on metric names.
+- **`register_budget`**: Sets a budget for a certain API call, which will initialize a series of metrics used to calculate the cost.
 
-## Using the `DictMonitor` Class
+## Using the Monitor
 
-The `DictMonitor` class is a subclass of the `MonitorBase` class, which is implemented in an in-memory dictionary.
+### Get a Monitor Instance
 
-### Initializing DictMonitor
-
-Create an instance of `DictMonitor` to begin monitoring:
+Get a monitor instance from `MonitorFactory` to begin monitoring, and note that multiple calls to the `get_monitor` method return the same monitor instance.
 
 ```python
-monitor = DictMonitor()
+# make sure you have called agentscope.init(...) before
+monitor = MonitorFactory.get_monitor()
 ```
 
-### Registering API Usage Metrics
+> Currently the above code returns a `SqliteMonitor` instance, which is initialized in `agentscope.init`.
+> The `SqliteMonitor` class is the default implementation of `MonitorBase` class, which is based on Sqlite3.
+
+### Basic Usage
+
+#### Registering API Usage Metrics
 
 Register a new metric to start monitoring the number of tokens:
 
 ```python
 monitor.register("token_num", metric_unit="token", quota=1000)
 ```
 
-### Updating Metrics
+#### Updating Metrics
 
 Increment the `token_num` metric:
 
 ```python
 monitor.add("token_num", 20)
 ```
 
-### Handling Quotas
+#### Handling Quotas
 
 If the number of API calls exceeds the quota, a `QuotaExceededError` will be thrown:
 
@@ -63,15 +68,15 @@ except QuotaExceededError as e:
     print(e.message)
 ```
 
-### Retrieving Metrics
+#### Retrieving Metrics
 
 Get the current number of tokens used:
 
 ```python
 token_num_used = monitor.get_value("token_num")
 ```
 
-### Resetting and Removing Metrics
+#### Resetting and Removing Metrics
 
 Reset the number of token count at the start of a new period:
 
@@ -85,16 +90,83 @@ Remove the metric if it's no longer needed:
 monitor.remove("token_num")
 ```
 
-## Using Singleton Access
+### Advanced Usage
+
+> Features here are under development, the interface may continue to change.
 
-`MonitorFactory` provides a singleton instance of a `MonitorBase` to ensure consistent access throughout your application.
+#### Using `prefix` to Distinguish Metrics
 
-### Acquiring the Singleton Monitor Instance
+Assume you have multiple agents/models that use the same API call, but you want to calculate their token usage separately, you can add a unique `prefix` before the original metric name, and `get_full_name` provides such functionality.
 
-Get the singleton instance of the monitor:
+For example, if model_A and model_B both use the OpenAI API, you can register these metrics by the following code.
 
 ```python
-monitor = MonitorFactory.get_monitor()
+from agentscope.utils.monitor import get_full_name
+
+...
+
+# in model_A
+monitor.register(get_full_name('prompt_tokens', 'model_A'))
+monitor.register(get_full_name('completion_tokens', 'model_A'))
+
+# in model_B
+monitor.register(get_full_name('prompt_tokens', 'model_B'))
+monitor.register(get_full_name('completion_tokens', 'model_B'))
+```
+
+To update those metrics, just use the `update` method.
+
+```python
+# in model_A
+monitor.update(openai_response.usage.model_dump(), prefix='model_A')
+
+# in model_B
+monitor.update(openai_response.usage.model_dump(), prefix='model_B')
+```
+
+To get metrics of a specific model, please use the `get_metrics` method.
+
+```python
+# get metrics of model_A
+model_A_metrics = monitor.get_metrics('model_A')
+
+# get metrics of model_B
+model_B_metrics = monitor.get_metrics('model_B')
 ```
 
+#### Register a budget for an API
+
+Currently, the Monitor already supports automatically calculating the cost of API calls based on various metrics, and you can directly set a budget of a model to avoid exceeding the quota.
+
+Suppose you are using `gpt-4-turbo` and your budget is $10, you can use the following code.
+
+```python
+model_name = 'gpt-4-turbo'
+monitor.register_budget(model_name=model_name, value=10, prefix=model_name)
+```
+
+Use `prefix` to set budgets for different models that use the same API.
+
+```python
+model_name = 'gpt-4-turbo'
+# in model_A
+monitor.register_budget(model_name=model_name, value=10, prefix=f'model_A.{model_name}')
+
+# in model_B
+monitor.register_budget(model_name=model_name, value=10, prefix=f'model_B.{model_name}')
+```
+
+`register_budget` will automatically register metrics that are required to calculate the total cost, calculate the total cost when these metrics are updated, and throw a `QuotaExceededError` when the budget is exceeded.
+
+```python
+model_name = 'gpt-4-turbo'
+try:
+    monitor.update(openai_response.usage.model_dump(), prefix=model_name)
+except QuotaExceededError as e:
+    # Handle the exceeded quota
+    print(e.message)
+```
+
+> **Note:** This feature is still in the experimental stage and only supports some specified APIs, which are listed in `agentscope.utils.monitor._get_pricing`.
+
 [[Return to the top]](#monitoring-and-logging)
diff --git a/docs/sphinx_doc/source/tutorial/301-community.md b/docs/sphinx_doc/source/tutorial/301-community.md
@@ -11,15 +11,15 @@ Becoming a part of the AgentScope community allows you to connect with other use
 
 ## Discord
 
-- **Join our Discord:** Collaborate with the AgentScope community in real-time. Engage in discussions, seek assistance, and share your experiences and insights on [Discord](https://discord.gg/Fwg5hZ2S).
+- **Join our Discord:** Collaborate with the AgentScope community in real-time. Engage in discussions, seek assistance, and share your experiences and insights on [Discord](https://discord.gg/eYMpfnkG8h).
 
 ## DingTalk (钉钉)
 
 - **Connect on DingTalk:** We are also available on DingTalk. Join our group to chat, and stay informed about AgentScope-related news and updates.
 
   Scan the QR code below on DingTalk to join:
 
-  <img width="150" src="https://img.alicdn.com/imgextra/i2/O1CN01tuJ5971OmAqNg9cOw_!!6000000001747-0-tps-444-460.jpg" alt="AgentScope-logo">
+  <img width="150" src="https://img.alicdn.com/imgextra/i2/O1CN01tuJ5971OmAqNg9cOw_!!6000000001747-0-tps-444-460.jpg" alt="AgentScope-dingtalk">
 
   Our DingTalk group invitation: [AgentScope DingTalk Group](https://qr.dingtalk.com/action/joingroup?code=v1,k1,20IUyRX5XZQ2vWjKDsjvI9dhcXjGZi3bq1pFfDZINCM=&_dt_no_comment=1&origin=11)