init

.github/workflows/python-publish.yml

@@ -0,0 +1,39 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v3
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+    - name: Build package
+      run: python -m build
+    - name: Publish package
+      uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_API_TOKEN }}

.gitignore

@@ -0,0 +1,9 @@
+test*
+cache/
+*.ipynb*
+*.ipynb*/
+*pycache*
+*pycache*/
+dist/
+*egg-info/
+__*

Dockerfile

@@ -0,0 +1,24 @@
+FROM registry.fiblab.net/general/dev:latest as builder
+
+WORKDIR /build
+COPY . /build
+ENV PIP_NO_CACHE_DIR=1
+RUN pip3 install --upgrade pip \ 
+    && pip3 install pdoc \
+    && ./scripts/init.sh \
+    && ./scripts/install-local.sh \
+    && ./scripts/gen_docs.sh
+
+FROM node:18-alpine
+ENV NODE_ENV=production
+WORKDIR /home/node/app
+
+# Install serve
+RUN yarn global add serve
+
+# Copy build files
+COPY --from=builder /build/docs ./build
+
+EXPOSE 80
+
+CMD serve build -p 80

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.

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!

example/config_template.yaml

@@ -0,0 +1,30 @@
+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

example/demo.py

@@ -0,0 +1,41 @@
+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())

example/social_background_template.json

@@ -0,0 +1,3 @@
+[
+    {"id": 3400, "name": "李四", "relation": "亲密朋友", "learned": "他最近在进行社会科学相关的研究"}
+]

example/spatial_knowledge_template.json

@@ -0,0 +1,4 @@
+[
+    {"id": 700809796, "name": "三里屯太古里-北区", "category": "购物", "aoi_id": 500004957, "relation": "你常常在这里购买生活用品"},
+    {"id": 700426179, "name": "清华大学", "category": "教育学校", "aoi_id": 500000011, "relation": "你在这里学习和工作"}
+]

example/sratch_template.json

@@ -0,0 +1,11 @@
+{
+    "name": "张三", 
+    "age": 24, 
+    "education": "高等教育水平",
+    "gender": "男",
+    "consumption": "低等消费水平",
+    "innate": "热情开朗", 
+    "learned": "张三是一名硕士生，通常在清华大学园区工作，他非常喜爱AI方面的内容", 
+    "currently": "我想努力进行AI生成领域的研究工作，争取发表高水平论文", 
+    "lifestyle": "张三通常在晚上11点睡觉，早晨7点起床"
+  }