pycityagent 1.0.0__tar.gz

pycityagent-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 FIBLAB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pycityagent-1.0.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.1
+Name: pycityagent
+Version: 1.0.0
+Summary: LLM-based城市模拟器agent构建库
+Author-email: Yuwei Yan <pinkgranite86@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2024 FIBLAB
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/tsinghua-fib-lab/pycityagent
+Project-URL: Repository, https://github.com/tsinghua-fib-lab/pycityagent.git
+Project-URL: Issues, https://github.com/tsinghua-fib-lab/pycityagent/issues
+Keywords: agent,city,LLM
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: dashscope>=1.14.0
+Requires-Dist: geojson>=3.1.0
+Requires-Dist: numpy>=1.26.3
+Requires-Dist: openai>=1.8.0
+Requires-Dist: Pillow>=10.2.0
+Requires-Dist: pycitysim>=1.8.0
+Requires-Dist: citystreetview>=1.1.0
+Requires-Dist: PyYAML>=6.0.1
+Requires-Dist: Requests>=2.31.0
+Requires-Dist: transitions>=0.9.0
+
+# Pycityagent
+
+# Table of Contents
+* [Introduction](#Introduction)
+	* [The Whole Framework of CityAgent](#The-Whole-Framework-of-CityAgent)
+	* [The Workflow of CityAgent](#The-Workflow-of-CityAgent)
+* [Hands On - By An Easy Demo](#Hands-On---By-An-Easy-Demo)
+
+<!-- TOC -->
+
+## Introduction
+### Framework of CityAgent
+- ![framwork](./static/framework.png)
+
+### Workflow of CityAgent
+- ![workflow](./static/workflow.png)
+
+## Hands On - By An Easy Demo
+### Apply for your App
+- You first need to register your account in the [Opencity website](https://opencity.fiblab.net/)
+- Login to the console, create your own app.
+- Get your app_id and app_secret
+    - ![app](./static/app.png)
+
+### Get your Config
+- There are three parts of a config file: **llm_request**, **citysim_request** and **apphub_request**
+```yaml
+llm_request:
+  text_request:
+    request_type: qwen
+    api_key: xxx
+    model: xxx
+  img_understand_request:
+    request_type: qwen
+    api_key: xxx
+    model: xxx
+  img_generate_request:
+    request_type: qwen
+    api_key: xxx
+    model: xxx
+
+citysim_request:
+  simulator: 
+    server: https://api-opencity-2x.fiblab.net:58081
+  map_request:
+    mongo_coll: map_beijing_extend_20240205
+    cache_dir: ./cache
+  streetview_request:
+    engine: baidumap / googlemap
+    mapAK: your baidumap AK (if baidumap)
+    proxy: your googlemap proxy (if googlemap, optional)
+
+apphub_request:
+  hub_url: https://api-opencity-2x.fiblab.net:58080
+  app_id: your APP ID
+  app_secret: your APP Secret
+  profile_image: the profile image of your agent
+```
+- Forget about **citysim_request**, let's focus on the other two.
+
+#### LLM_REQUEST
+- As you can tell, the whole CityAgent is based on the LLM, by now, there are three different parts of config items: **text_request**, **img_understand_request** and **img_generate_request**
+- By now, we support [**qwen**](https://tongyi.aliyun.com/) and [**openai**](https://openai.com/)
+    - `Notice: Our environments are basically conducted with qwen. If you prefer to use openai, then you may encounter hardships. AND fell free to issue us.`
+- Get your **api_key** and chooce your **model**s
+
+### CITYSIM_REQUEST
+- There are no need to change the 'simulator' and 'map_request' config
+- 'streetview_request': this is the config used for streetview
+  - By now, we support 'baidumap' and 'googlemap'
+  - If you use 'baidumap', then you need to apply for a mapAK
+  - If you use 'googlemap', then you can config your own proxy by 'proxy' attribute
+
+#### APPHUB_REQUEST
+- This is basically used to connect with the backend.
+- Put your **app_id** and **app_secret** here.
+
+### Installation
+- Install from **pip** easily.
+```shell
+pip install pycityagent
+```
+
+### CODE and RUN
+- Check the **example** folder and copy files from it (`Remember replace the config file`)
+- Look at the Demo:
+```python
+import yaml
+from pycityagent.simulator import Simulator
+from pycityagent.urbanllm import LLMConfig, UrbanLLM
+import asyncio
+import time
+
+async def main():
+    # load your config
+    with open('config_template.yaml', 'r') as file:
+        config = yaml.safe_load(file)
+    
+    # get the simulator object
+    smi = Simulator(config['citysim_request'])
+    
+    # get the person by person_id, return agent
+    agent = await smi.GetAgent("name_of_agent", 8)
+
+    # Help you build unique agent by scratch/profile
+    agent.Image.load_scratch('scratch_template.json')
+
+    # Load Memory and assist the agent to understand "Opencity"
+    agent.Brain.Memory.Spatial.MemoryLoad('spatial_knowledge_template.json')
+    agent.Brain.Memory.Social.MemoryLoad('social_background_template.json')
+
+    # Connect to apphub so you can interact with your agent in front end
+    agent.ConnectToHub(config['apphub_request'])
+
+    # Creat the soul (a LLM processor actually)
+    llmConfig = LLMConfig(config['llm_request'])
+    soul = UrbanLLM(llmConfig)
+
+    # Add the soul to your agent
+    agent.add_soul(soul)
+    
+    # Start and have fun with it!!!
+    while True:
+        await agent.Run()
+        time.sleep(1)
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+
+### Congratulations
+- Following this "Hands On" guide, you have easily created an agent by your hand! 
+- You can observe your AGENT in your console or in the [Opencity website](https://opencity.fiblab.net/).
+- HAVE FUN WITH IT!

pycityagent-1.0.0/README.md

@@ -0,0 +1,134 @@
+# Pycityagent
+
+# Table of Contents
+* [Introduction](#Introduction)
+	* [The Whole Framework of CityAgent](#The-Whole-Framework-of-CityAgent)
+	* [The Workflow of CityAgent](#The-Workflow-of-CityAgent)
+* [Hands On - By An Easy Demo](#Hands-On---By-An-Easy-Demo)
+
+<!-- TOC -->
+
+## Introduction
+### Framework of CityAgent
+- ![framwork](./static/framework.png)
+
+### Workflow of CityAgent
+- ![workflow](./static/workflow.png)
+
+## Hands On - By An Easy Demo
+### Apply for your App
+- You first need to register your account in the [Opencity website](https://opencity.fiblab.net/)
+- Login to the console, create your own app.
+- Get your app_id and app_secret
+    - ![app](./static/app.png)
+
+### Get your Config
+- There are three parts of a config file: **llm_request**, **citysim_request** and **apphub_request**
+```yaml
+llm_request:
+  text_request:
+    request_type: qwen
+    api_key: xxx
+    model: xxx
+  img_understand_request:
+    request_type: qwen
+    api_key: xxx
+    model: xxx
+  img_generate_request:
+    request_type: qwen
+    api_key: xxx
+    model: xxx
+
+citysim_request:
+  simulator: 
+    server: https://api-opencity-2x.fiblab.net:58081
+  map_request:
+    mongo_coll: map_beijing_extend_20240205
+    cache_dir: ./cache
+  streetview_request:
+    engine: baidumap / googlemap
+    mapAK: your baidumap AK (if baidumap)
+    proxy: your googlemap proxy (if googlemap, optional)
+
+apphub_request:
+  hub_url: https://api-opencity-2x.fiblab.net:58080
+  app_id: your APP ID
+  app_secret: your APP Secret
+  profile_image: the profile image of your agent
+```
+- Forget about **citysim_request**, let's focus on the other two.
+
+#### LLM_REQUEST
+- As you can tell, the whole CityAgent is based on the LLM, by now, there are three different parts of config items: **text_request**, **img_understand_request** and **img_generate_request**
+- By now, we support [**qwen**](https://tongyi.aliyun.com/) and [**openai**](https://openai.com/)
+    - `Notice: Our environments are basically conducted with qwen. If you prefer to use openai, then you may encounter hardships. AND fell free to issue us.`
+- Get your **api_key** and chooce your **model**s
+
+### CITYSIM_REQUEST
+- There are no need to change the 'simulator' and 'map_request' config
+- 'streetview_request': this is the config used for streetview
+  - By now, we support 'baidumap' and 'googlemap'
+  - If you use 'baidumap', then you need to apply for a mapAK
+  - If you use 'googlemap', then you can config your own proxy by 'proxy' attribute
+
+#### APPHUB_REQUEST
+- This is basically used to connect with the backend.
+- Put your **app_id** and **app_secret** here.
+
+### Installation
+- Install from **pip** easily.
+```shell
+pip install pycityagent
+```
+
+### CODE and RUN
+- Check the **example** folder and copy files from it (`Remember replace the config file`)
+- Look at the Demo:
+```python
+import yaml
+from pycityagent.simulator import Simulator
+from pycityagent.urbanllm import LLMConfig, UrbanLLM
+import asyncio
+import time
+
+async def main():
+    # load your config
+    with open('config_template.yaml', 'r') as file:
+        config = yaml.safe_load(file)
+    
+    # get the simulator object
+    smi = Simulator(config['citysim_request'])
+    
+    # get the person by person_id, return agent
+    agent = await smi.GetAgent("name_of_agent", 8)
+
+    # Help you build unique agent by scratch/profile
+    agent.Image.load_scratch('scratch_template.json')
+
+    # Load Memory and assist the agent to understand "Opencity"
+    agent.Brain.Memory.Spatial.MemoryLoad('spatial_knowledge_template.json')
+    agent.Brain.Memory.Social.MemoryLoad('social_background_template.json')
+
+    # Connect to apphub so you can interact with your agent in front end
+    agent.ConnectToHub(config['apphub_request'])
+
+    # Creat the soul (a LLM processor actually)
+    llmConfig = LLMConfig(config['llm_request'])
+    soul = UrbanLLM(llmConfig)
+
+    # Add the soul to your agent
+    agent.add_soul(soul)
+    
+    # Start and have fun with it!!!
+    while True:
+        await agent.Run()
+        time.sleep(1)
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+
+### Congratulations
+- Following this "Hands On" guide, you have easily created an agent by your hand! 
+- You can observe your AGENT in your console or in the [Opencity website](https://opencity.fiblab.net/).
+- HAVE FUN WITH IT!

pycityagent-1.0.0/pycityagent/__init__.py

@@ -0,0 +1,4 @@
+from .simulator import Simulator
+from .agent import Agent
+
+__all__ = [Simulator, Agent]

pycityagent-1.0.0/pycityagent/ac/__init__.py

@@ -0,0 +1,6 @@
+'''Action Control - 最终进行simulator以及AppHub对接'''
+
+from .ac import *
+from .action import *
+
+__all__ = [ActionController, Action]

pycityagent-1.0.0/pycityagent/ac/ac.py

@@ -0,0 +1,50 @@
+from typing import Any
+from .trip import TripAction
+from .shop import ShopAction
+from .converse import ConverseAction
+from .controled import ControledAction
+from .idle import IdleAction
+
+class ActionController:
+    """
+    Agent行为控制器: 与AppHub(simulator)对接
+    Agent Controller: Connect with AppHub and Simulator
+    Note: Actions are predefined. By now, user defined actions are not supported
+    """
+    def __init__(self, agent, config=None) -> None:
+        self._agent = agent
+        self._trip = TripAction(agent)
+        self._shop = ShopAction(agent)
+        self._converse = ConverseAction(agent)
+        self._control = ControledAction(agent)
+        self._idle = IdleAction(agent)
+        self._config = config
+
+    async def Run(self):
+        # TODO: 后期补充相关扩展接口，应该根据state-action关联模块进行（为了方便用户定义更加丰富的状态）
+        if self._agent.state == 'idle':
+            await self._idle()
+        elif self._agent.state == 'trip':
+            await self._trip()
+        elif self._agent.state == 'conve':
+            await self._converse()
+        elif self._agent.state == 'shop':
+            await self._shop()
+        elif self._agent.state == 'controled':
+            await self._control()
+
+    @property
+    def TripAction(self):
+        return self._trip
+    
+    @property
+    def ShopAction(self):
+        return self._shop
+    
+    @property
+    def ConveAction(self):
+        return self._converse
+    
+    @property
+    def ControlAction(self):
+        return self._controls

pycityagent-1.0.0/pycityagent/ac/action.py

@@ -0,0 +1,14 @@
+from abc import ABC, abstractclassmethod
+from typing import Any
+
+class Action:
+    def __init__(self, agent) -> None:
+        '''默认初始化'''
+        self._agent = agent
+
+    @abstractclassmethod
+    async def Forward(self):
+        '''接口函数'''
+
+    async def __call__(self) -> Any:
+        await self.Forward()

pycityagent-1.0.0/pycityagent/ac/controled.py

@@ -0,0 +1,13 @@
+import time
+from .action import Action
+from pycitysim.apphub import AgentMessage
+
+class ControledAction(Action):
+    '''Converse行为控制器'''
+    def __init__(self, agent) -> None:
+        super().__init__(agent)
+
+    async def Forward(self):
+        req = {'person_id': self._agent._id, 'schedules': []}
+        await self._agent._client.person_service.SetSchedule(req)
+        self._agent.Hub.Update([AgentMessage(self._agent.Hub._agent_id, int(time.time()*1000), '我已理解您的意思，正在修改我的行程', None, None)])

pycityagent-1.0.0/pycityagent/ac/converse.py

@@ -0,0 +1,31 @@
+import time
+from .action import Action
+from pycitysim.apphub import AgentMessage
+
+class ConverseAction(Action):
+    '''Converse行为控制器'''
+    def __init__(self, agent) -> None:
+        super().__init__(agent)
+
+    async def Forward(self):
+        target_agent_ids = self._agent.Brain.Memory.Working.Reason['agent_message_handle_resp'][0]
+        if len(target_agent_ids) == 0:
+            return
+        messages = self._agent.Brain.Memory.Working.Reason['agent_message_handle_resp'][1]
+        req = {'messages': []}
+        if len(target_agent_ids) != len(messages):
+            print("Warning: the number of target agent and message are not aligned, only sends matched messages")
+        rng = min(len(target_agent_ids), len(messages))
+        for i in range(rng):
+            dic = {}
+            dic['from'] = self._agent._id
+            dic['to'] = target_agent_ids[i]
+            dic['message'] = messages[i]
+            req['messages'].append(dic)
+        # * 发送至模拟器
+        await self._agent._client.social_service.Send(req=req)
+
+        # * 发送至AppHub
+        if self._agent.Hub != None and messages[0] != 'End':
+            # * 将信息中的第一条不同至pop
+            self._agent.Hub.Update(pop=messages[0])

pycityagent-1.0.0/pycityagent/ac/idle.py

@@ -0,0 +1,17 @@
+import time
+from .action import Action
+from pycitysim.apphub import AgentMessage
+
+class IdleAction(Action):
+    '''idle行为控制器'''
+    def __init__(self, agent) -> None:
+        super().__init__(agent)
+
+    async def Forward(self):
+        if len(self._agent.base['schedules']) > 0:
+            req = {'person_id': self._agent._id, 'schedules': []}
+            await self._agent._client.person_service.SetSchedule(req)
+        if self._agent.Hub != None:
+            self._agent.Hub.Update()
+
+    

pycityagent-1.0.0/pycityagent/ac/shop.py

@@ -0,0 +1,80 @@
+from .action import Action
+from pycitysim.apphub import AgentMessage
+import time
+
+def encap_msg(msg, role='user', **kwargs):
+    dialog = {'role': role, 'content': msg}
+    dialog.update(kwargs)
+    return dialog
+
+class ShopAction(Action):
+    '''Shop行为控制器'''
+    def __init__(self, agent) -> None:
+        super().__init__(agent)
+
+    async def Forward(self):
+        # * 与模拟器对接 - 暂时没有
+        # * 与AppHub对接
+        profile = self._agent.Image.get_profile()
+        self.consumption(profile)
+
+    def consumption(self, profile, mall_info):
+        dialogs = []
+        system_prompt = f'''
+                            你是一个在北京工作和生活的人。 
+                            {profile} 
+                            现在是2024年1月。
+                            你需要为下一周的基本生活购买必需品。
+                        '''
+        dialogs.append(encap_msg(system_prompt, 'system'))
+        actions_format = ['''{{'商品': 购买的商品的列表,'购买量': 每个商品的购买量，一个列表, '解释': '这种购买方式的原因'}}''']
+        actions_candidates = ['''【食品】
+                                米：10元/公斤
+                                面粉：7.5元/公斤
+                                新鲜蔬菜（如菠菜）：7元/500克
+                                水果（如苹果）：15元/公斤
+                                猪肉：30元/公斤
+                                鸡肉：20元/公斤
+                                鸡蛋：1.5元/个
+                                牛奶：10元/升''',
+                                '''【清洁用品】
+                                    洗衣液：30元/瓶
+                                    洗洁精：20元/瓶
+                                    垃圾袋：0.3元/个''',
+                                '''【个人护理用品】
+                                    牙膏：10元/支
+                                    洗发水：30元/瓶
+                                    沐浴露：35元/瓶
+                                    面巾纸：5元/包''',
+                                '''【其他】
+                                    矿泉水：1.7元/瓶
+                                    面包：8元/个
+                                    辣条：3元/包''']
+
+        user_prompt = f'''
+                        首先确定你的消费预算。以如下格式回答，不要有冗余的文本！
+                        {{'消费预算': 一个代表购买必需品需要消耗的钱的数量的数字}}
+                        '''
+        dialogs.append(encap_msg(user_prompt))
+        # * 对接一：确定消费预算
+        self._agent.Hub.Update([AgentMessage(self._agent.Hub._agent_id, int(time.time()*1000), '我正在确定消费预算......', None, None)])
+        msg = self._agent._soul.text_request(dialogs)
+        self._agent.Hub.Update([AgentMessage(self._agent.Hub._agent_id, int(time.time()*1000), f'我的消费预算是: {msg}'), None, None])
+
+        dialogs.append(encap_msg(msg, 'assistant'))
+
+        # * 对接二：购物选择
+        for cand in actions_candidates:
+            user_prompt = f'''
+                            购物中心里有
+                            {cand}
+                            你要买哪些商品，以如下格式回答，不要有冗余的文本！
+                            {actions_format[0]}
+                        '''
+            self._agent.Hub.Update([AgentMessage(self._agent.Hub._agent_id, int(time.time()*1000), f'我看到了\n {cand}', None, None)])
+            dialogs.append(encap_msg(user_prompt))
+            msg = self._agent._soul.text_request(dialogs)
+            self._agent.Hub.Update([AgentMessage(self._agent.Hub._agent_id, int(time.time()*1000), f'我的购买选择是: {msg}', None, None)])
+            dialogs.append(encap_msg(msg, 'assistant'))
+        
+        self._agent.Hub.Update([AgentMessage(self._agent.Hub._agent_id, int(time.time()*1000), '购物完成', None, None)])

pycityagent-1.0.0/pycityagent/ac/trip.py

@@ -0,0 +1,37 @@
+import time
+from .action import Action
+from pycitysim.apphub import AgentMessage
+
+class TripAction(Action):
+    '''Trip行为控制器'''
+    def __init__(self, agent) -> None:
+        super().__init__(agent)
+
+    async def Forward(self):
+        now = self._agent.Scheduler.now
+        if now.is_set:
+            '''之前已经将schedule同步至模拟器了'''
+            if self._agent.Hub != None:
+                self._agent.Hub.Update(streetview=self._agent.Brain.Sence.sence_buffer['streetview'])
+        else:
+            '''同步schedule至模拟器'''
+            self._agent.Scheduler.now.is_set = True
+            departure_time = now.time
+            mode = now.mode
+            aoi_id = now.target_id_aoi
+            poi_id = now.target_id_poi
+            end = {'aoi_position': {'aoi_id': aoi_id, 'poi_id': poi_id}}
+            activity = now.description
+            trips = [{'mode': mode, 'end': end, 'departure_time': departure_time, 'activity': activity}]
+            set_schedule = [{'trips': trips, 'loop_count': 1, 'departure_time': departure_time}]
+
+            # * 与模拟器对接
+            req = {'person_id': self._agent._id, 'schedules': set_schedule}
+            await self._agent._client.person_service.SetSchedule(req)
+
+            # * 与AppHub对接
+            if self._agent.Hub != None:
+                messages = [AgentMessage(self._agent.Hub._agent_id, int(time.time()*1000), f'已到达出发时间, {activity}', None, None)]
+                self._agent.Hub.Update(messages)
+
+